API Documentation

OpenAPI Specification

The Inkweld API follows OpenAPI 3.0 specifications. You can access the complete API specification and try endpoints interactively.

Authentication

The Inkweld API uses session-based authentication with httpOnly cookies.

POST /api/auth/login
Content-Type: application/json

{
  "username": "your-username",
  "password": "your-password"
}

Response:
{
  "user": {
    "id": "uuid",
    "username": "your-username",
    "email": "you@example.com"
  }
}

Common Endpoints

Projects

• GET /api/projects - List your projects
• POST /api/projects - Create a new project
• GET /api/projects/:id - Get project details
• PUT /api/projects/:id - Update project
• DELETE /api/projects/:id - Delete project

Documents

• GET /api/projects/:projectId/elements - List project files and folders
• POST /api/projects/:projectId/elements - Create file or folder
• GET /api/documents/:id - Get document content
• PUT /api/documents/:id - Update document

Worldbuilding

• GET /api/projects/:projectId/worldbuilding - List worldbuilding entries
• POST /api/projects/:projectId/worldbuilding - Create entry
• GET /api/worldbuilding/:id - Get entry details

WebSocket Connection

Real-time collaboration uses WebSocket connections:

wss://your-server/ws/:projectId

Connection authenticated via session cookie.
Yjs CRDT updates exchanged in binary format.

Rate Limiting

The API implements rate limiting to prevent abuse. Default limits:

• 100 requests per minute per IP address
• 1000 requests per hour per authenticated user

Rate limit configuration can be adjusted via environment variables.

Error Responses

The API returns standard HTTP status codes:

• 200 - Success
• 201 - Resource created
• 400 - Bad request (validation error)
• 401 - Unauthorized (not logged in)
• 403 - Forbidden (insufficient permissions)
• 404 - Resource not found
• 429 - Too many requests (rate limited)
• 500 - Internal server error

Client Generation

Generate type-safe API clients from the OpenAPI specification:

# TypeScript/Angular client (included in repo)
cd backend
bun run generate:angular-client

# Other languages via openapi-generator
npx @openapitools/openapi-generator-cli generate \
  -i backend/openapi.json \
  -g python \
  -o ./python-client