Calling the API

The token door

Programs call https://api.clusterstuck.sh/v1/... with Authorization: Bearer cs_pat_... and nothing else; cookies are ignored there. Every path is versioned: /v1/me, /v1/settings, /v1/p/<project>/..., /v1/llm/.... An unversioned path answers 404, naming the /v1 one.

The app's, the docs' and the sign-in pages call the same API at their own /api/..., with their session cookie and a CSRF token. Those are theirs, not an interface: programs do not use them.

Errors answer { "error": "...", "code"?: "..." } with their status. A 400 names what was wrong with the request, in the schema's words.

The API's own description

https://api.clusterstuck.sh/v1/openapi.json is the API's OpenAPI document, built from its routes; ?format=md gives the same as Markdown. The reference is rendered from it.

Models

llm is OpenAI-compatible: any OpenAI client works with the base URL https://api.clusterstuck.sh/v1/llm and your token as the key. jev, the decision model, answers questions about a JSON state. The models your account may call are modelApi in /v1/me; each operation is in the reference, and /v1/usage shows what your calls cost.

curl https://api.clusterstuck.sh/v1/llm/chat/completions \
  -H "Authorization: Bearer cs_pat_..." -H "content-type: application/json" \
  -d '{"messages":[{"role":"user","content":"hello"}],"stream":true}'

From your project's own backend, use @cs/models instead: see Writing a project.

Your projects' APIs

Everything under /v1/p/<project>/ is that project's own backend. Each project describes its routes: /v1/p/<project>/openapi.json (or ?format=md), built with the project's release, readable by its owner -- and, signed in, rendered at your projects. A project's live status is a WebSocket on the same paths.