~/sursakit

// docs

API reference

Sursakit exposes a REST API at /api/v1. Anything you can do in the UI you can script against the API. OpenAPI definitions live with the backend; this page is the human-readable index.

Authentication

Two ways to authenticate:

  • Session cookie — issued by the auth flow when a user signs in.
  • Per-organization API key — created in organization settings, sent as a bearer token. Use these for scripts and CI.

Resource map

Workspaces

  • POST /workspace — create.
  • POST /workspace/auto-create — create from a template.
  • GET /workspace — list.
  • GET /workspace/{id} — read.
  • PUT /workspace/{id} — update.
  • DELETE /workspace/{id} — delete.
  • GET /workspace/{id}/default-session — fetch default session id.

Sessions

  • POST /sessions, GET /sessions, GET /sessions/{id}, DELETE /sessions/{id}.
  • GET /sessions/{workspace_id}/sessions — list within a workspace.

Services & runtimes

Under /workspace/{session_id}:

  • POST /services, GET /services, PUT /services/{id}, DELETE /services/{id}.
  • POST /services/import-github | import-gitlab | import-bitbucket | import-dockerhub — typed import flows.
  • PUT /services/reorder.
  • POST /runtimes/{service_id}/restart | stop.
  • POST /runtimes/run-all | stop-all.
  • Database services expose config, schema, table data, and SQL query endpoints under /services/{service_id}/database.

Version control

Under /workspace/{session_id}/version-controls:

  • POST /log, GET /log/{commit_id}.
  • POST /diff, GET /diff/working-copy.
  • POST /commit, POST /commit/generate-message.
  • POST /discard, POST /rollback.

Pull requests

Under /workspace/{workspace_id}/pull-requests:

  • POST, GET, PUT.
  • POST /{id}/merge, POST /{id}/refresh.
  • GET /counts, POST /{id}/conflict-content.
  • Session-specific diff and review endpoints live under /workspace/{workspace_id}/sessions/{session_id}/pull-requests/{id}.

Filesystem

  • POST /workspace/{session_id}/filesystem — read / write / delete.
  • POST /workspace/{session_id}/file-tree.
  • POST /filestorage — uploads (resumable streams).

Editor / LSP

  • GET /ws/lsp — upgrade to WebSocket for LSP.
  • GET /lsp-fs, GET /ws/lsp-fs-watch.

Terminal

  • GET /ws/terminal — upgrade to WebSocket for a PTY.

Chat & AI

  • POST /chat — chat completion (Vercel AI SDK Agent API).
  • GET / POST /chats/history.
  • POST /workflow-chat, POST /chat/attachments.
  • POST /workspace/ai/auto-complete, POST /workspace/suggestions.

Skills, automations, tasks

  • GET / POST /workspace/{workspace_id}/skills.
  • GET / POST /workspace/{workspace_id}/automations.
  • POST / GET /workspace/{session_id}/tasks, POST /task-management.

Webhooks & integrations

  • POST /webhooks/incoming — incoming webhook receiver.
  • POST /webhook-integrations.
  • GET / POST /github | /gitlab | /bitbucket.

Organization

  • /organizations/{organizationId}/billing, /organizations/{organizationId}/api-keys, /organizations/{organizationId}/models.
  • /account, /admin.

Models & usage

  • GET /models — list available AI models.
  • GET /llm-usage — usage tracking.

Notes

  • Runtime, service, filesystem, task, and version-control endpoints are session-scoped. Workspace settings, skills, automations, members, and pull requests are workspace-scoped.
  • OpenAPI definitions are generated from the route schemas; ask us if you want a copy of the current spec.