API Documentation

OpenAPI Specification

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

Authentication

Signing in returns a JWT. Send it as a bearer token on every request. Password sign-in is off by default (servers are passkey-first); an administrator can enable it with PASSWORD_LOGIN_ENABLED=true.

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

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

Response:
{
  "user": { "id": "uuid", "username": "your-username", ... },
  "token": "eyJ..."
}

Then: Authorization: Bearer eyJ...

Common Endpoints

Projects

• GET /api/v1/projects - List your projects
• POST /api/v1/projects - Create a project from a title and slug
• GET /api/v1/projects/:username/:slug - Get project details
• PUT /api/v1/projects/:username/:slug - Update project
• DELETE /api/v1/projects/:username/:slug - Delete project

Elements and documents

• GET /api/v1/projects/:username/:slug/elements - The project tree (folders, documents, worldbuilding elements)
• GET /api/v1/projects/:username/:slug/docs - List documents
• GET /api/v1/projects/:username/:slug/docs/:docId - Get a document

Documents and worldbuilding content are edited through the real-time connection below or the MCP server, not through REST writes.

WebSocket Connection

Real-time collaboration uses WebSocket connections:

wss://your-server/api/v1/ws/yjs?documentId=<username>:<slug>:<elementId>

The client authenticates with its token after connecting.
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