HTTP API and WebSocket Reference

Note: Examples use http://localhost:800. See Set Up the CLI for CLI profile setup, Generate Documentation for guided runs, and Track Generation Progress for human-facing monitoring.

Authentication and Conventions

Authentication surfaces

Use a Bearer token for automation, or log in once to receive a docsfy_session cookie for browser and same-origin WebSocket access.

curl -H "Authorization: Bearer <USER_API_KEY>" \
  http://localhost:800/api/projects

const ws = new WebSocket("ws://localhost:800/api/ws?token=<USER_API_KEY>");

Authenticates protected HTTP requests and the WebSocket handshake.

Warning: Hidden resources return 404 instead of 403. A missing project and an inaccessible project are intentionally indistinguishable to non-admin callers.

Warning: Unauthenticated /docs/* requests with Accept: text/html receive 302 /login. Other unauthenticated /docs/* requests receive 401 {"detail":"Unauthorized"}.

Variant path encoding

Variant-scoped routes put the branch in a single URL path segment. Encode / as ~2F and ~ as ~7E.

curl -H "Authorization: Bearer <ADMIN_KEY>" \
  "http://localhost:800/api/projects/my-repo/release~2Fv2.0/claude/opus?owner=alice"

Use the encoded segment anywhere the route path contains {branch}.

Error response body

Most non-2xx HTTP responses use a detail field. Validation failures use FastAPI's 422 format, where detail is an array.

{"detail":"Unauthorized"}

{
  "detail": [
    {
      "type": "value_error",
      "loc": ["body", "repo_url"],
      "msg": "Value error, Invalid git repository URL: 'not-a-url'",
      "input": "not-a-url"
    }
  ]
}

Returns machine-readable error data for automated clients.

Health and Model Discovery

GET /health

Public health check.

Auth: Public

No parameters.

curl http://localhost:800/health

{"status":"ok"}

Returns 200 OK when the service is reachable.

GET /api/models

List supported providers, current server defaults, discovered model catalogs, and Cursor availability status.

Auth: Public

No parameters.

Response body:

Model entry fields:

provider_status.cursor fields:

curl http://localhost:800/api/models

{
  "providers": ["claude", "gemini", "cursor"],
  "default_provider": "cursor",
  "default_model": "gpt-5.4-xhigh-fast",
  "default_vision_provider": "",
  "default_vision_model": "",
  "available_models": {
    "cursor": [
      {
        "id": "gpt-5.4-xhigh-fast",
        "name": "GPT-5.4 XHigh Fast",
        "source": "acpx"
      }
    ],
    "claude": [],
    "gemini": []
  },
  "provider_status": {
    "cursor": {
      "ok": true,
      "reason": null,
      "hint": null,
      "model_count": 1
    }
  }

Returns the current model catalog and configured defaults. Public and non-admin callers receive coarse Cursor status; authenticated admins receive additional Cursor auth details such as has_api_key.

POST /api/models/refresh

Refresh the sidecar model catalog and return a fresh GET /api/models response body.

Auth: admin

No parameters.

curl -X POST \
  -H "Authorization: Bearer <ADMIN_KEY>" \
  http://localhost:800/api/models/refresh

{
  "providers": ["claude", "gemini", "cursor"],
  "default_provider": "cursor",
  "default_model": "gpt-5.4-xhigh-fast",
  "default_vision_provider": "",
  "default_vision_model": "",
  "available_models": {
    "cursor": []
  },
  "provider_status": {
    "cursor": {
      "ok": false,
      "reason": "unavailable",
      "hint": "Cursor is unavailable. Contact an administrator.",
      "has_api_key": false,
      "model_count": 0
    }
  }

Returns a refreshed model catalog. Unauthenticated callers receive 401, authenticated non-admin callers receive 403, and refresh failures return 502. See Configure AI Providers and Models for details.

GET /api/cost

Return the accumulated generation cost total visible to the caller.

Auth: Bearer token or session cookie

No parameters.

Response body:

curl -H "Authorization: Bearer <USER_API_KEY>" \
  http://localhost:800/api/cost

{"total_cost_usd":4.56}

Returns 200 OK with the scoped cost total.

Authentication Endpoints

POST /api/auth/login

Authenticate a user, create a session cookie, and return the authenticated identity.

Auth: Public

Body parameters:

Response body:

Response headers:

curl -i -X POST http://localhost:800/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","api_key":"<ADMIN_KEY>"}'

{
  "username": "admin",
  "role": "admin",
  "is_admin": true
}

Returns 200 OK and sets docsfy_session. Returns 400 for malformed or non-object JSON and 401 for invalid credentials.

POST /api/auth/logout

Delete the current session cookie and remove the current server-side session row if one exists.

Auth: Public

No parameters.

curl -X POST \
  -b "docsfy_session=<SESSION_TOKEN>" \
  http://localhost:800/api/auth/logout

{"ok":true}

Returns 200 OK. The response always clears docsfy_session, even when no valid session existed.

GET /api/auth/me

Return the current authenticated identity.

Auth: Bearer token or session cookie

No parameters.

Response body:

curl -H "Authorization: Bearer <USER_API_KEY>" \
  http://localhost:800/api/auth/me

{
  "username": "alice",
  "role": "viewer",
  "is_admin": false
}

Returns 200 OK with the active identity, or 401 when unauthenticated.

POST /api/auth/rotate-key

Rotate the current DB-backed user's API key.

Auth: Bearer token or session cookie

Body parameters:

Response body:

Response headers:

curl -X POST http://localhost:800/api/auth/rotate-key \
  -b "docsfy_session=<SESSION_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"new_key":"my-very-secure-custom-password-123"}'

{
  "username": "alice",
  "new_api_key": "my-very-secure-custom-password-123"
}

Returns 200 OK, invalidates all sessions for that user, and clears the caller's docsfy_session. Returns 400 for malformed JSON, non-object JSON, short custom keys, or when the caller is the bootstrap ADMIN_KEY identity.

Project Records and Snapshots

ProjectVariant object

Stored record for one generated variant.

Status values:

current_stage values:

{
  "name": "for-testing-only",
  "branch": "main",
  "ai_provider": "claude",
  "ai_model": "opus",
  "owner": "alice",
  "repo_url": "https://github.com/myk-org/for-testing-only.git",
  "status": "ready",
  "current_stage": null,
  "last_commit_sha": "abc123def456",
  "last_generated": "2026-07-31 11:30:00",
  "page_count": 12,
  "error_message": null,
  "plan_json": "{\"project_name\":\"for-testing-only\",\"tagline\":\"Test repo\",\"navigation\":[]}",
  "repo_type": "app",
  "total_cost_usd": 1.4628,
  "vision_provider": "",
  "vision_model": "",
  "generation_id": "5bf1495b-b6fa-4318-841c-dced628a2c5b",
  "generation_duration": 214,
  "generation_started_at": null,
  "created_at": "2026-07-31 11:25:00",
  "updated_at": "2026-07-31 11:30:00"
}

Returned by variant lookup routes and included in project snapshots.

ProjectSnapshot object

Snapshot used by GET /api/status, GET /api/projects, and WebSocket sync.

{
  "projects": [
    {
      "name": "for-testing-only",
      "branch": "main",
      "ai_provider": "claude",
      "ai_model": "opus",
      "owner": "alice",
      "status": "ready",
      "page_count": 12,
      "generation_id": "5bf1495b-b6fa-4318-841c-dced628a2c5b"
    }
  ],
  "known_branches": {
    "for-testing-only": ["main", "release/v2.0"]
  },
  "total_cost_usd": 4.56
}

Returned by listing routes and WebSocket sync. It does not include model catalogs; fetch /api/models separately for provider and model discovery.

GET /api/status and GET /api/projects

Return the current ProjectSnapshot.

Auth: Bearer token or session cookie

No parameters.

curl -H "Authorization: Bearer <USER_API_KEY>" \
  http://localhost:800/api/projects

{
  "projects": [],
  "known_branches": {},
  "total_cost_usd": 0
}

Returns 200 OK. GET /api/status is a direct alias of GET /api/projects.

GET /api/projects/by-id/{generation_id}

Look up one variant by generation UUID.

Auth: Bearer token or session cookie

Path parameters:

curl -H "Authorization: Bearer <USER_API_KEY>" \
  http://localhost:800/api/projects/by-id/5bf1495b-b6fa-4318-841c-dced628a2c5b

{
  "name": "for-testing-only",
  "branch": "main",
  "ai_provider": "claude",
  "ai_model": "opus",
  "owner": "alice",
  "status": "ready",
  "generation_id": "5bf1495b-b6fa-4318-841c-dced628a2c5b"
}

Returns a ProjectVariant. Returns 400 for invalid UUID format and 404 when the ID does not exist or is not visible to the caller.

GET /api/projects/{name}

List all visible variants for one project name.

Auth: Bearer token or session cookie

Path parameters:

Response body:

curl -H "Authorization: Bearer <ADMIN_KEY>" \
  http://localhost:800/api/projects/for-testing-only

{
  "name": "for-testing-only",
  "variants": [
    {
      "name": "for-testing-only",
      "branch": "main",
      "ai_provider": "claude",
      "ai_model": "opus",
      "owner": "alice",
      "status": "ready"
    }
  ]
}

Returns 200 OK with project-scoped variants, or 404 when no visible variants exist.

GET /api/projects/{name}/{branch}/{provider}/{model}

Look up one variant by project name, branch, provider, and model.

Auth: Bearer token or session cookie

Path parameters:

Query parameters:

curl -H "Authorization: Bearer <ADMIN_KEY>" \
  "http://localhost:800/api/projects/for-testing-only/release~2Fv2.0/claude/opus?owner=alice"

{
  "name": "for-testing-only",
  "branch": "release/v2.0",
  "ai_provider": "claude",
  "ai_model": "opus",
  "owner": "alice",
  "status": "ready"
}

Returns a ProjectVariant. Returns 404 when the variant does not exist or is not visible, and 409 when an admin lookup is ambiguous across multiple owners.

Generation and Lifecycle Control

POST /api/generate

Start documentation generation for a remote Git repository or an admin-supplied local Git path.

Auth: admin or user

Body parameters:

Response body:

curl -X POST http://localhost:800/api/generate \
  -H "Authorization: Bearer <USER_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "repo_url": "https://github.com/myk-org/for-testing-only.git",
    "ai_provider": "claude",
    "ai_model": "opus",
    "branch": "release/v2.0",
    "repo_type": "app",
    "force": false
  }'

{
  "project": "for-testing-only",
  "status": "generating",
  "branch": "release/v2.0",
  "generation_id": "5bf1495b-b6fa-4318-841c-dced628a2c5b",
  "repo_type": "app"
}

Returns 202 Accepted, creates or updates the variant row immediately, and starts background generation. Returns 403 for viewer access or non-admin repo_path usage, 400 for invalid local path or missing defaults, 422 for request validation failures, and 409 when the same owner/name/branch/provider/model is already generating. See Generate Documentation for guided workflows.

Warning: repo_url values that point to localhost, private network addresses, or unsupported URL schemes are rejected.

Warning: repo_path must exist, be absolute, and contain a .git directory.

POST /api/projects/{name}/abort

Abort the only active generation that matches a project name.

Auth: admin or user

Path parameters:

No query or body parameters.

curl -X POST \
  -H "Authorization: Bearer <USER_API_KEY>" \
  http://localhost:800/api/projects/for-testing-only/abort

{"aborted":"for-testing-only"}

Returns 200 OK when exactly one matching active generation is cancelled. Non-admin callers can abort only their own runs. Returns 404 when no active generation exists and 409 when more than one active variant matches or cancellation is still in progress.

Warning: This route is not deterministic when more than one active variant exists for the same project name. Use the variant-scoped abort route for automation.

POST /api/projects/{name}/{branch}/{provider}/{model}/abort

Abort one active variant.

Auth: admin or user

Path parameters:

Query parameters:

curl -X POST \
  -H "Authorization: Bearer <ADMIN_KEY>" \
  "http://localhost:800/api/projects/for-testing-only/release~2Fv2.0/claude/opus/abort?owner=alice"

{"aborted":"for-testing-only/release/v2.0/claude/opus"}

Returns 200 OK when the matching task is cancelled. Returns 404 when no active generation matches, and 409 when the lookup is ambiguous or cancellation is still in progress.

DELETE /api/projects/{name}

Delete all variants for one project name.

Auth: admin or user

Path parameters:

Query parameters:

curl -X DELETE \
  -H "Authorization: Bearer <ADMIN_KEY>" \
  "http://localhost:800/api/projects/for-testing-only?owner=alice"

{"deleted":"for-testing-only"}

Returns 200 OK after deleting the matching owner-scoped project variants. Returns 404 when nothing matches and 409 when any matching variant is still generating. A successful delete sends a WebSocket sync.

DELETE /api/projects/{name}/{branch}/{provider}/{model}

Delete one variant.

Auth: admin or user

Path parameters:

Query parameters:

curl -X DELETE \
  -H "Authorization: Bearer <ADMIN_KEY>" \
  "http://localhost:800/api/projects/for-testing-only/release~2Fv2.0/claude/opus?owner=alice"

{"deleted":"for-testing-only/release/v2.0/claude/opus"}

Returns 200 OK after deleting the matching variant. Returns 404 when the variant does not exist and 409 when the variant is still generating.

Downloads and Document-Serving URLs

Generated site files

Generated sites expose both browser-facing HTML and machine-readable artifacts under /docs/*.

curl -H "Authorization: Bearer <USER_API_KEY>" \
  http://localhost:800/docs/for-testing-only/llms.txt

Returns raw file bytes from the generated site. See Browse and Download Docs for browser and CLI workflows.

GET /api/projects/{name}/download

Download a tarball for the newest accessible ready variant of a project.

Auth: Bearer token or session cookie

Path parameters:

Response headers:

curl -OJ \
  -H "Authorization: Bearer <USER_API_KEY>" \
  http://localhost:800/api/projects/for-testing-only/download

Returns the newest accessible ready variant as a tarball. Returns 404 when no accessible ready variant exists or the site directory is missing, and 409 when multiple owners have equally newest ready variants with the same timestamp.

Warning: This route resolves the newest accessible ready variant. Use the variant-scoped download route for deterministic automation.

GET /api/projects/{name}/{branch}/{provider}/{model}/download

Download a tarball for one variant.

Auth: Bearer token or session cookie

Path parameters:

Query parameters:

Response headers:

curl -OJ \
  -H "Authorization: Bearer <ADMIN_KEY>" \
  "http://localhost:800/api/projects/for-testing-only/release~2Fv2.0/claude/opus/download?owner=alice"

Returns the generated site for that variant. Returns 400 when the variant exists but is not ready, 404 when the variant or site is missing, and 409 when an admin lookup is ambiguous across owners.

GET /docs/{project}/{path:path}

Serve one file from the newest accessible ready variant.

Auth: Bearer token or session cookie

Path parameters:

curl -H "Authorization: Bearer <USER_API_KEY>" \
  http://localhost:800/docs/for-testing-only/search-index.json

Returns raw file bytes from the newest accessible ready variant. Returns 404 when no accessible docs are available or the file does not exist, 403 when the resolved path escapes the site directory, and 409 when the newest accessible variant is ambiguous across owners.

GET /docs/{project}/{branch}/{provider}/{model}/{path:path}

Serve one file from a specific variant.

Auth: Bearer token or session cookie

Path parameters:

Query parameters:

curl -H "Authorization: Bearer <ADMIN_KEY>" \
  "http://localhost:800/docs/for-testing-only/release~2Fv2.0/claude/opus/llms-full.txt?owner=alice"

Returns raw file bytes from the requested variant. Returns 404 when the variant or file does not exist, 403 when the resolved file path escapes the site directory, and 409 when an admin lookup is ambiguous across owners.

Admin API

GET /api/admin/users

List all users.

Auth: admin

No parameters.

Response body:

curl -H "Authorization: Bearer <ADMIN_KEY>" \
  http://localhost:800/api/admin/users

{
  "users": [
    {
      "id": 1,
      "username": "alice",
      "role": "user",
      "created_at": "2026-07-31 11:00:00"
    }
  ]
}

Returns 200 OK. Non-admin callers receive 403.

POST /api/admin/users

Create a user and return its raw API key.

Auth: admin

Body parameters:

Response body:

Response headers:

curl -X POST http://localhost:800/api/admin/users \
  -H "Authorization: Bearer <ADMIN_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"username":"alice","role":"viewer"}'

{
  "username": "alice",
  "api_key": "docsfy_xxxxxxxxx",
  "role": "viewer"
}

Returns 200 OK. Returns 400 for invalid usernames, reserved admin, duplicate users, invalid roles, malformed JSON, or a non-object request body.

DELETE /api/admin/users/{username}

Delete a user.

Auth: admin

Path parameters:

curl -X DELETE \
  -H "Authorization: Bearer <ADMIN_KEY>" \
  http://localhost:800/api/admin/users/alice

{"deleted":"alice"}

Returns 200 OK after deleting the user, all of their sessions, their owned projects, grants they received, grants to their projects, and their project directory. Returns 400 when an admin tries to delete their own account, 404 when the user does not exist, and 409 when that user has an active generation.

POST /api/admin/users/{username}/rotate-key

Rotate another user's API key.

Auth: admin

Path parameters:

Body parameters:

Response body:

Response headers:

curl -X POST http://localhost:800/api/admin/users/alice/rotate-key \
  -H "Authorization: Bearer <ADMIN_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"new_key":"admin-chosen-password-long"}'

{
  "username": "alice",
  "new_api_key": "admin-chosen-password-long"
}

Returns 200 OK and invalidates all sessions for the target user. Returns 400 for invalid custom keys, malformed JSON, or a non-object body, and 404 when the user does not exist.

GET /api/admin/projects/{name}/access

List users who have access to a project-owner pair.

Auth: admin

Path parameters:

Query parameters:

Response body:

curl -H "Authorization: Bearer <ADMIN_KEY>" \
  "http://localhost:800/api/admin/projects/for-testing-only/access?owner=alice"

{
  "project": "for-testing-only",
  "owner": "alice",
  "users": ["bob", "carol"]
}

Returns 200 OK. Returns 400 when owner is missing and 403 for non-admin callers.

POST /api/admin/projects/{name}/access

Grant a user read access to all variants of a project owned by one owner.

Auth: admin

Path parameters:

Body parameters:

curl -X POST http://localhost:800/api/admin/projects/for-testing-only/access \
  -H "Authorization: Bearer <ADMIN_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"username":"bob","owner":"alice"}'

{
  "granted": "for-testing-only",
  "username": "bob",
  "owner": "alice"
}

Returns 200 OK. Duplicate grants are ignored without error. Returns 400 for malformed JSON, a non-object body, or missing fields, and 404 when the target user or the project-owner pair does not exist. A successful grant sends a WebSocket sync to the target user's active connections. See Manage Users and Access for details.

DELETE /api/admin/projects/{name}/access/{username}

Revoke a user's access grant for one project-owner pair.

Auth: admin

Path parameters:

Query parameters:

curl -X DELETE \
  -H "Authorization: Bearer <ADMIN_KEY>" \
  "http://localhost:800/api/admin/projects/for-testing-only/access/bob?owner=alice"

{
  "revoked": "for-testing-only",
  "username": "bob",
  "owner": "alice"
}

Returns 200 OK and sends a WebSocket sync to the target user's active connections. Returns 400 when owner is missing and 403 for non-admin callers. This route is idempotent.

GET /api/admin/settings

Return the current persisted admin settings and any active environment overrides.

Auth: admin

No parameters.

Response body:

settings fields:

curl -H "Authorization: Bearer <ADMIN_KEY>" \
  http://localhost:800/api/admin/settings

{
  "settings": {
    "default_ai_provider": "cursor",
    "default_ai_model": "gpt-5.4-xhigh-fast",
    "ai_cli_timeout": 60,
    "max_concurrent_pages": 10,
    "vision_provider": "",
    "vision_model": ""
  },
  "env_overrides": {
    "default_ai_provider": "AI_PROVIDER"
  }

Returns 200 OK. Numeric settings are returned as integers.

PUT /api/admin/settings

Update one or more admin settings.

Auth: admin

Body parameters:

Allowed settings keys:

curl -X PUT http://localhost:800/api/admin/settings \
  -H "Authorization: Bearer <ADMIN_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "settings": {
      "default_ai_provider": "cursor",
      "default_ai_model": "gpt-5.4-xhigh-fast",
      "max_concurrent_pages": 12
    }
  }'

{"status":"ok"}

Returns 200 OK after persisting the submitted keys. Returns 400 for malformed JSON, a non-object body, an unknown setting key, invalid provider values, non-positive integers, or provider fields without the required matching model. See Configure AI Providers and Models and Configuration Reference for details.

WebSocket

WebSocket /api/ws

Open a real-time stream of project snapshots and generation updates.

Auth: docsfy_session cookie or ?token=<api_key>

Query parameters:

Connection behavior:

const ws = new WebSocket("ws://localhost:800/api/ws?token=<USER_API_KEY>");

ws.onmessage = (event) => {
  const message = JSON.parse(event.data);

  if (message.type === "ping") {
    ws.send(JSON.stringify({ type: "pong" }));
    return;
  }

  console.log(message);
};

Opens a live subscription. The server sends sync, progress, status_change, and ping messages. Client messages other than {"type":"pong"} are ignored.

sync message

Full project snapshot message.

Fields:

{
  "type": "sync",
  "projects": [
    {
      "name": "for-testing-only",
      "branch": "main",
      "ai_provider": "claude",
      "ai_model": "opus",
      "owner": "alice",
      "status": "ready",
      "page_count": 12,
      "generation_id": "5bf1495b-b6fa-4318-841c-dced628a2c5b"
    }
  ],
  "known_branches": {
    "for-testing-only": ["main", "release/v2.0"]
  },
  "total_cost_usd": 4.56
}

Sent immediately after connect and again after access changes, deletions, and terminal generation refreshes. Model catalogs are not included; call GET /api/models separately when needed.

progress message

Incremental update for an in-progress generation.

Fields:

{
  "type": "progress",
  "name": "for-testing-only",
  "branch": "release/v2.0",
  "provider": "claude",
  "model": "opus",
  "owner": "alice",
  "status": "generating",
  "current_stage": "generating_pages",
  "page_count": 4,
  "plan_json": "{\"project_name\":\"for-testing-only\",\"tagline\":\"Test repo\",\"navigation\":[]}",
  "generation_id": "5bf1495b-b6fa-4318-841c-dced628a2c5b",
  "generation_started_at": "2026-07-31T11:26:12.345678+00:00"
}

Sent during non-terminal stages. Merge these updates by the tuple (name, branch, provider, model, owner).

status_change message

Terminal update for a variant.

Fields:

{
  "type": "status_change",
  "name": "for-testing-only",
  "branch": "release/v2.0",
  "provider": "claude",
  "model": "opus",
  "owner": "alice",
  "status": "ready",
  "page_count": 12,
  "last_generated": "2026-07-31 11:30:00",
  "last_commit_sha": "abc123def456",
  "generation_id": "5bf1495b-b6fa-4318-841c-dced628a2c5b",
  "generation_duration": 214
}

Sent when a variant reaches a terminal state. A follow-up sync may arrive immediately afterward.

ping message

Server heartbeat message.

Fields:

{"type":"ping"}

Sent every 30 seconds per open connection.

pong message

Client heartbeat response.

Fields:

{"type":"pong"}

Acknowledge the most recent server ping. If the server misses two consecutive pongs, it closes the connection with code 1001.

Related Pages

• See Set Up the CLI for CLI profile setup.
• See Generate Documentation for guided generation flows.
• See Configure AI Providers and Models for provider setup and troubleshooting.
• See Track Generation Progress for live monitoring patterns.
• See Browse and Download Docs for browser and CLI download workflows.
• See Manage Projects and Variants for day-to-day project operations.
• See Manage Users and Access for task-oriented admin procedures.
• See Configuration Reference for environment variables and deployment settings.# HTTP API and WebSocket Reference

Note: Examples use http://localhost:8000. See Set Up the CLI for CLI profile setup, Generate Documentation for guided runs, and Track Generation Progress for human-facing monitoring.

Authentication and Conventions

Authentication surfaces

Use a Bearer token for automation, or log in once to receive a docsfy_session cookie for browser and same-origin WebSocket access.

curl -H "Authorization: Bearer <USER_API_KEY>" \
  http://localhost:8000/api/projects

const ws = new WebSocket("ws://localhost:8000/api/ws?token=<USER_API_KEY>");

Authenticates protected HTTP requests and the WebSocket handshake.

Warning: Hidden resources return 404 instead of 403. A missing project and an inaccessible project are intentionally indistinguishable to non-admin callers.

Warning: Unauthenticated /docs/* requests with Accept: text/html receive 302 /login. Other unauthenticated /docs/* requests receive 401 {"detail":"Unauthorized"}.

Variant path encoding

Variant-scoped routes put the branch in a single URL path segment. Encode / as ~2F and ~ as ~7E.

curl -H "Authorization: Bearer <ADMIN_KEY>" \
  "http://localhost:8000/api/projects/my-repo/release~2Fv2.0/claude/opus?owner=alice"

Use the encoded segment anywhere the route path contains {branch}.

Error response body

Most non-2xx HTTP responses use a detail field. Validation failures use FastAPI's 422 format, where detail is an array.

{"detail":"Unauthorized"}

{
  "detail": [
    {
      "type": "value_error",
      "loc": ["body", "repo_url"],
      "msg": "Value error, Invalid git repository URL: 'not-a-url'",
      "input": "not-a-url"
    }
  ]
}

Returns machine-readable error data for automated clients.

Health and Model Discovery

GET /health

Public health check.

Auth: Public

No parameters.

curl http://localhost:8000/health

{"status":"ok"}

Returns 200 OK when the service is reachable.

GET /api/models

List supported providers, current server defaults, discovered model catalogs, and Cursor availability status.

Auth: Public

No parameters.

Response body:

Model entry fields:

provider_status.cursor fields:

curl http://localhost:8000/api/models

{
  "providers": ["claude", "gemini", "cursor"],
  "default_provider": "cursor",
  "default_model": "gpt-5.4-xhigh-fast",
  "default_vision_provider": "",
  "default_vision_model": "",
  "available_models": {
    "cursor": [
      {
        "id": "gpt-5.4-xhigh-fast",
        "name": "GPT-5.4 XHigh Fast",
        "source": "acpx"
      }
    ],
    "claude": [],
    "gemini": []
  },
  "provider_status": {
    "cursor": {
      "ok": true,
      "reason": null,
      "hint": null,
      "model_count": 1
    }
  }
}

Returns the current model catalog and configured defaults. Public and non-admin callers receive coarse Cursor status; authenticated admins receive additional Cursor auth details such as has_api_key.

POST /api/models/refresh

Refresh the sidecar model catalog and return a fresh GET /api/models response body.

Auth: admin

No parameters.

curl -X POST \
  -H "Authorization: Bearer <ADMIN_KEY>" \
  http://localhost:8000/api/models/refresh

{
  "providers": ["claude", "gemini", "cursor"],
  "default_provider": "cursor",
  "default_model": "gpt-5.4-xhigh-fast",
  "default_vision_provider": "",
  "default_vision_model": "",
  "available_models": {
    "cursor": []
  },
  "provider_status": {
    "cursor": {
      "ok": false,
      "reason": "unavailable",
      "hint": "Cursor is unavailable. Contact an administrator.",
      "has_api_key": false,
      "model_count": 0
    }
  }
}

Returns a refreshed model catalog. Unauthenticated callers receive 401, authenticated non-admin callers receive 403, and refresh failures return 502. See Configure AI Providers and Models for details.

GET /api/cost

Return the accumulated generation cost total visible to the caller.

Auth: Bearer token or session cookie

No parameters.

Response body:

curl -H "Authorization: Bearer <USER_API_KEY>" \
  http://localhost:8000/api/cost

{"total_cost_usd":4.56}

Returns 200 OK with the scoped cost total.

Authentication Endpoints

POST /api/auth/login

Authenticate a user, create a session cookie, and return the authenticated identity.

Auth: Public

Body parameters:

Response body:

Response headers:

curl -i -X POST http://localhost:8000/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","api_key":"<ADMIN_KEY>"}'

{
  "username": "admin",
  "role": "admin",
  "is_admin": true
}

Returns 200 OK and sets docsfy_session. Returns 400 for malformed or non-object JSON and 401 for invalid credentials.

POST /api/auth/logout

Delete the current session cookie and remove the current server-side session row if one exists.

Auth: Public

No parameters.

curl -X POST \
  -b "docsfy_session=<SESSION_TOKEN>" \
  http://localhost:8000/api/auth/logout

{"ok":true}

Returns 200 OK. The response always clears docsfy_session, even when no valid session existed.

GET /api/auth/me

Return the current authenticated identity.

Auth: Bearer token or session cookie

No parameters.

Response body:

curl -H "Authorization: Bearer <USER_API_KEY>" \
  http://localhost:8000/api/auth/me

{
  "username": "alice",
  "role": "viewer",
  "is_admin": false
}

Returns 200 OK with the active identity, or 401 when unauthenticated.

POST /api/auth/rotate-key

Rotate the current DB-backed user's API key.

Auth: Bearer token or session cookie

Body parameters:

Response body:

Response headers:

curl -X POST http://localhost:8000/api/auth/rotate-key \
  -b "docsfy_session=<SESSION_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"new_key":"my-very-secure-custom-password-123"}'

{
  "username": "alice",
  "new_api_key": "my-very-secure-custom-password-123"
}

Returns 200 OK, invalidates all sessions for that user, and clears the caller's docsfy_session. Returns 400 for malformed JSON, non-object JSON, short custom keys, or when the caller is the bootstrap ADMIN_KEY identity.

Project Records and Snapshots

ProjectVariant object

Stored record for one generated variant.

Status values:

current_stage values:

{
  "name": "for-testing-only",
  "branch": "main",
  "ai_provider": "claude",
  "ai_model": "opus",
  "owner": "alice",
  "repo_url": "https://github.com/myk-org/for-testing-only.git",
  "status": "ready",
  "current_stage": null,
  "last_commit_sha": "abc123def456",
  "last_generated": "2026-07-31 11:30:00",
  "page_count": 12,
  "error_message": null,
  "plan_json": "{\"project_name\":\"for-testing-only\",\"tagline\":\"Test repo\",\"navigation\":[]}",
  "repo_type": "app",
  "total_cost_usd": 1.4628,
  "vision_provider": "",
  "vision_model": "",
  "generation_id": "5bf1495b-b6fa-4318-841c-dced628a2c5b",
  "generation_duration": 214,
  "generation_started_at": null,
  "created_at": "2026-07-31 11:25:00",
  "updated_at": "2026-07-31 11:30:00"
}

Returned by variant lookup routes and included in project snapshots.

ProjectSnapshot object

Snapshot used by GET /api/status, GET /api/projects, and WebSocket sync.

{
  "projects": [
    {
      "name": "for-testing-only",
      "branch": "main",
      "ai_provider": "claude",
      "ai_model": "opus",
      "owner": "alice",
      "status": "ready",
      "page_count": 12,
      "generation_id": "5bf1495b-b6fa-4318-841c-dced628a2c5b"
    }
  ],
  "known_branches": {
    "for-testing-only": ["main", "release/v2.0"]
  },
  "total_cost_usd": 4.56
}

Returned by listing routes and WebSocket sync. It does not include model catalogs; fetch /api/models separately for provider and model discovery.

GET /api/status and GET /api/projects

Return the current ProjectSnapshot.

Auth: Bearer token or session cookie

No parameters.

curl -H "Authorization: Bearer <USER_API_KEY>" \
  http://localhost:8000/api/projects

{
  "projects": [],
  "known_branches": {},
  "total_cost_usd": 0
}

Returns 200 OK. GET /api/status is a direct alias of GET /api/projects.

GET /api/projects/by-id/{generation_id}

Look up one variant by generation UUID.

Auth: Bearer token or session cookie

Path parameters:

curl -H "Authorization: Bearer <USER_API_KEY>" \
  http://localhost:8000/api/projects/by-id/5bf1495b-b6fa-4318-841c-dced628a2c5b

{
  "name": "for-testing-only",
  "branch": "main",
  "ai_provider": "claude",
  "ai_model": "opus",
  "owner": "alice",
  "status": "ready",
  "generation_id": "5bf1495b-b6fa-4318-841c-dced628a2c5b"
}

Returns a ProjectVariant. Returns 400 for invalid UUID format and 404 when the ID does not exist or is not visible to the caller.

GET /api/projects/{name}

List all visible variants for one project name.

Auth: Bearer token or session cookie

Path parameters:

Response body:

curl -H "Authorization: Bearer <ADMIN_KEY>" \
  http://localhost:8000/api/projects/for-testing-only

{
  "name": "for-testing-only",
  "variants": [
    {
      "name": "for-testing-only",
      "branch": "main",
      "ai_provider": "claude",
      "ai_model": "opus",
      "owner": "alice",
      "status": "ready"
    }
  ]
}

Returns 200 OK with project-scoped variants, or 404 when no visible variants exist.

GET /api/projects/{name}/{branch}/{provider}/{model}

Look up one variant by project name, branch, provider, and model.

Auth: Bearer token or session cookie

Path parameters:

Query parameters:

curl -H "Authorization: Bearer <ADMIN_KEY>" \
  "http://localhost:8000/api/projects/for-testing-only/release~2Fv2.0/claude/opus?owner=alice"

{
  "name": "for-testing-only",
  "branch": "release/v2.0",
  "ai_provider": "claude",
  "ai_model": "opus",
  "owner": "alice",
  "status": "ready"
}

Returns a ProjectVariant. Returns 404 when the variant does not exist or is not visible, and 409 when an admin lookup is ambiguous across multiple owners.

Generation and Lifecycle Control

POST /api/generate

Start documentation generation for a remote Git repository or an admin-supplied local Git path.

Auth: admin or user

Body parameters:

Response body:

curl -X POST http://localhost:8000/api/generate \
  -H "Authorization: Bearer <USER_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "repo_url": "https://github.com/myk-org/for-testing-only.git",
    "ai_provider": "claude",
    "ai_model": "opus",
    "branch": "release/v2.0",
    "repo_type": "app",
    "force": false
  }'

{
  "project": "for-testing-only",
  "status": "generating",
  "branch": "release/v2.0",
  "generation_id": "5bf1495b-b6fa-4318-841c-dced628a2c5b",
  "repo_type": "app"
}

Returns 202 Accepted, creates or updates the variant row immediately, and starts background generation. Returns 403 for viewer access or non-admin repo_path usage, 400 for invalid local path or missing defaults, 422 for request validation failures, and 409 when the same owner/name/branch/provider/model is already generating. See Generate Documentation for guided workflows.

Warning: repo_url values that point to localhost, private network addresses, or unsupported URL schemes are rejected.

Warning: repo_path must exist, be absolute, and contain a .git directory.

POST /api/projects/{name}/abort

Abort the only active generation that matches a project name.

Auth: admin or user

Path parameters:

No query or body parameters.

curl -X POST \
  -H "Authorization: Bearer <USER_API_KEY>" \
  http://localhost:8000/api/projects/for-testing-only/abort

{"aborted":"for-testing-only"}

Returns 200 OK when exactly one matching active generation is cancelled. Non-admin callers can abort only their own runs. Returns 404 when no active generation exists and 409 when more than one active variant matches or cancellation is still in progress.

Warning: This route is not deterministic when more than one active variant exists for the same project name. Use the variant-scoped abort route for automation.

POST /api/projects/{name}/{branch}/{provider}/{model}/abort

Abort one active variant.

Auth: admin or user

Path parameters:

Query parameters:

curl -X POST \
  -H "Authorization: Bearer <ADMIN_KEY>" \
  "http://localhost:8000/api/projects/for-testing-only/release~2Fv2.0/claude/opus/abort?owner=alice"

{"aborted":"for-testing-only/release/v2.0/claude/opus"}

Returns 200 OK when the matching task is cancelled. Returns 404 when no active generation matches, and 409 when the lookup is ambiguous or cancellation is still in progress.

DELETE /api/projects/{name}

Delete all variants for one project name.

Auth: admin or user

Path parameters:

Query parameters:

curl -X DELETE \
  -H "Authorization: Bearer <ADMIN_KEY>" \
  "http://localhost:8000/api/projects/for-testing-only?owner=alice"

{"deleted":"for-testing-only"}

Returns 200 OK after deleting the matching owner-scoped project variants. Returns 404 when nothing matches and 409 when any matching variant is still generating. A successful delete sends a WebSocket sync.

DELETE /api/projects/{name}/{branch}/{provider}/{model}

Delete one variant.

Auth: admin or user

Path parameters:

Query parameters:

curl -X DELETE \
  -H "Authorization: Bearer <ADMIN_KEY>" \
  "http://localhost:8000/api/projects/for-testing-only/release~2Fv2.0/claude/opus?owner=alice"

{"deleted":"for-testing-only/release/v2.0/claude/opus"}

Returns 200 OK after deleting the matching variant. Returns 404 when the variant does not exist and 409 when the variant is still generating.

Downloads and Document-Serving URLs

Generated site files

Generated sites expose both browser-facing HTML and machine-readable artifacts under /docs/*.

curl -H "Authorization: Bearer <USER_API_KEY>" \
  http://localhost:8000/docs/for-testing-only/llms.txt

Returns raw file bytes from the generated site. See Browse and Download Docs for browser and CLI workflows.

GET /api/projects/{name}/download

Download a tarball for the newest accessible ready variant of a project.

Auth: Bearer token or session cookie

Path parameters:

Response headers:

curl -OJ \
  -H "Authorization: Bearer <USER_API_KEY>" \
  http://localhost:8000/api/projects/for-testing-only/download

Returns the newest accessible ready variant as a tarball. Returns 404 when no accessible ready variant exists or the site directory is missing, and 409 when multiple owners have equally newest ready variants with the same timestamp.

Warning: This route resolves the newest accessible ready variant. Use the variant-scoped download route for deterministic automation.

GET /api/projects/{name}/{branch}/{provider}/{model}/download

Download a tarball for one variant.

Auth: Bearer token or session cookie

Path parameters:

Query parameters:

Response headers:

curl -OJ \
  -H "Authorization: Bearer <ADMIN_KEY>" \
  "http://localhost:8000/api/projects/for-testing-only/release~2Fv2.0/claude/opus/download?owner=alice"

Returns the generated site for that variant. Returns 400 when the variant exists but is not ready, 404 when the variant or site is missing, and 409 when an admin lookup is ambiguous across owners.

GET /docs/{project}/{path:path}

Serve one file from the newest accessible ready variant.

Auth: Bearer token or session cookie

Path parameters:

curl -H "Authorization: Bearer <USER_API_KEY>" \
  http://localhost:8000/docs/for-testing-only/search-index.json

Returns raw file bytes from the newest accessible ready variant. Returns 404 when no accessible docs are available or the file does not exist, 403 when the resolved path escapes the site directory, and 409 when the newest accessible variant is ambiguous across owners.

GET /docs/{project}/{branch}/{provider}/{model}/{path:path}

Serve one file from a specific variant.

Auth: Bearer token or session cookie

Path parameters:

Query parameters:

curl -H "Authorization: Bearer <ADMIN_KEY>" \
  "http://localhost:8000/docs/for-testing-only/release~2Fv2.0/claude/opus/llms-full.txt?owner=alice"

Returns raw file bytes from the requested variant. Returns 404 when the variant or file does not exist, 403 when the resolved file path escapes the site directory, and 409 when an admin lookup is ambiguous across owners.

Admin API

GET /api/admin/users

List all users.

Auth: admin

No parameters.

Response body:

curl -H "Authorization: Bearer <ADMIN_KEY>" \
  http://localhost:8000/api/admin/users

{
  "users": [
    {
      "id": 1,
      "username": "alice",
      "role": "user",
      "created_at": "2026-07-31 11:00:00"
    }
  ]
}

Returns 200 OK. Non-admin callers receive 403.

POST /api/admin/users

Create a user and return its raw API key.

Auth: admin

Body parameters:

Response body:

Response headers:

curl -X POST http://localhost:8000/api/admin/users \
  -H "Authorization: Bearer <ADMIN_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"username":"alice","role":"viewer"}'

{
  "username": "alice",
  "api_key": "docsfy_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "role": "viewer"
}

Returns 200 OK. Returns 400 for invalid usernames, reserved admin, duplicate users, invalid roles, malformed JSON, or a non-object request body.

DELETE /api/admin/users/{username}

Delete a user.

Auth: admin

Path parameters:

curl -X DELETE \
  -H "Authorization: Bearer <ADMIN_KEY>" \
  http://localhost:8000/api/admin/users/alice

{"deleted":"alice"}

Returns 200 OK after deleting the user, all of their sessions, their owned projects, grants they received, grants to their projects, and their project directory. Returns 400 when an admin tries to delete their own account, 404 when the user does not exist, and 409 when that user has an active generation.

POST /api/admin/users/{username}/rotate-key

Rotate another user's API key.

Auth: admin

Path parameters:

Body parameters:

Response body:

Response headers:

curl -X POST http://localhost:8000/api/admin/users/alice/rotate-key \
  -H "Authorization: Bearer <ADMIN_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"new_key":"admin-chosen-password-long"}'

{
  "username": "alice",
  "new_api_key": "admin-chosen-password-long"
}

Returns 200 OK and invalidates all sessions for the target user. Returns 400 for invalid custom keys, malformed JSON, or a non-object body, and 404 when the user does not exist.

GET /api/admin/projects/{name}/access

List users who have access to a project-owner pair.

Auth: admin

Path parameters:

Query parameters:

Response body:

curl -H "Authorization: Bearer <ADMIN_KEY>" \
  "http://localhost:8000/api/admin/projects/for-testing-only/access?owner=alice"

{
  "project": "for-testing-only",
  "owner": "alice",
  "users": ["bob", "carol"]
}

Returns 200 OK. Returns 400 when owner is missing and 403 for non-admin callers.

POST /api/admin/projects/{name}/access

Grant a user read access to all variants of a project owned by one owner.

Auth: admin

Path parameters:

Body parameters:

curl -X POST http://localhost:8000/api/admin/projects/for-testing-only/access \
  -H "Authorization: Bearer <ADMIN_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"username":"bob","owner":"alice"}'

{
  "granted": "for-testing-only",
  "username": "bob",
  "owner": "alice"
}

Returns 200 OK. Duplicate grants are ignored without error. Returns 400 for malformed JSON, a non-object body, or missing fields, and 404 when the target user or the project-owner pair does not exist. A successful grant sends a WebSocket sync to the target user's active connections. See Manage Users and Access for details.

DELETE /api/admin/projects/{name}/access/{username}

Revoke a user's access grant for one project-owner pair.

Auth: admin

Path parameters:

Query parameters:

curl -X DELETE \
  -H "Authorization: Bearer <ADMIN_KEY>" \
  "http://localhost:8000/api/admin/projects/for-testing-only/access/bob?owner=alice"

{
  "revoked": "for-testing-only",
  "username": "bob",
  "owner": "alice"
}

Returns 200 OK and sends a WebSocket sync to the target user's active connections. Returns 400 when owner is missing and 403 for non-admin callers. This route is idempotent.

GET /api/admin/settings

Return the current persisted admin settings and any active environment overrides.

Auth: admin

No parameters.

Response body:

settings fields:

curl -H "Authorization: Bearer <ADMIN_KEY>" \
  http://localhost:8000/api/admin/settings

{
  "settings": {
    "default_ai_provider": "cursor",
    "default_ai_model": "gpt-5.4-xhigh-fast",
    "ai_cli_timeout": 60,
    "max_concurrent_pages": 10,
    "vision_provider": "",
    "vision_model": ""
  },
  "env_overrides": {
    "default_ai_provider": "AI_PROVIDER"
  }
}