API Reference

This page summarizes how to call Kilavuz’s public API and which callers can reach which endpoints. The API base is served at https://api.kilavuz.app.

General contract

Content type: JSON (request and response bodies). The Markdown download endpoint returns text/markdown.
Authentication: session cookie or Authorization: Bearer <token> header. Both methods resolve to the same user context.
Error codes: The API uses standard HTTP status codes.
- 400 — the request body failed validation.
- 401 — no session, or the session has expired.
- 403 — the user is not authorized (for example, an ordinary user hitting an admin endpoint).
- 404 — the resource was not found.
- 500 — server error; the error body remains in English.

Endpoints

Export to Markdown

POST /api/question-review/export-markdown

Returns every active (non-deleted) question for a given project as Markdown with hierarchical numbering.

Request body

{
  "projectId": "ckxxxxxxxxxxxxxxxx",
  "include": ["questions"]
}

include is optional; when omitted, only questions are fetched.

Response headers

Content-Type: text/markdown; charset=utf-8
Content-Disposition: attachment; filename="<project-slug>.md"

Response body

Example:

# Project name

1. First root question
  1.1. First child
  1.2. Second child
    1.2.1. Deeper child
2. Second root question

Numbering starts at the root; each level is indented by two spaces. The output is produced by the pure renderQuestionsAsMarkdown function in app/src/question-review/export.ts.

Health check

GET /healthz

The API container listens on port 3001; /healthz returns HTTP 200 with the body {"status":"ok"}. Details are documented in docs/deploy/kilavuz-readiness.md.

Versioning and compatibility

The API does not follow semantic versioning; endpoints are added with backwards compatibility preserved. Removal or behavior change for any endpoint is announced on this blog at least one release ahead of time.

Authorization matrix

Endpoint	Owner	Admin
`POST /api/question-review/export-markdown`	Yes	Yes
`GET /api/admin/users`	No	Yes
`GET /api/admin/billing/subscriptions`	No	Yes

An ordinary user’s request to an admin endpoint returns 403, independent of the chosen language.