🌐

14-API-Endpoints

🌐

The canonical REST + SSE surface that drives the iPhone client and any future web console. All routes are prefixed with /api/ and authenticated with Sanctum tokens unless noted.

Conventions

  • JSON, camelCase keys.
  • Errors: RFC 7807 application/problem+json.
  • Pagination: cursor-based (?cursor=…&limit=50) where applicable. Returns { data, meta: { nextCursor } }.
  • Streaming: SSE.
  • Timestamps: ISO-8601 UTC.
  • Rate limit: 60 req/min default; 6 req/min for run-start endpoints.

Auth

MethodPathBodyReturns
POST/api/auth/token (public){ email, password }{ token, abilities[] }
POST/api/auth/logout—204
GET/api/auth/me—User

Projects

MethodPathNotes
GET/api/projectsList user-accessible projects.
POST/api/projects{ name, repositoryUrl, defaultBranch? }. Creates project + queues clone + initial RAG index.
GET/api/projects/{project}Project detail.
PUT/api/projects/{project}Update name/description/defaults.
DELETE/api/projects/{project}Soft-delete project (archive workspace).
POST/api/projects/{project}/cloneRe-clone (must be in error or archived).
POST/api/projects/{project}/pullPull default branch.
POST/api/projects/{project}/index-ragForce re-index.
GET/api/projects/{project}/mapReturns generated PROJECT_MAP as JSON (rows).
GET/api/projects/{project}/schemaReturns DATABASE_SCHEMA as JSON.
GET/api/projects/{project}/diagramsReturns ARCHITECTURE_DIAGRAMS markdown.

Runs

MethodPathNotes
POST/api/runs{ projectId, title, prompt, selectedAgent, selectedModel, ragEnabled?, safeMode? }. Creates draft.
GET/api/runs/{run}Run detail (includes timeline summary).
POST/api/runs/{run}/startTransitions `draft
POST/api/runs/{run}/pauserunning → paused.
POST/api/runs/{run}/resume`paused
POST/api/runs/{run}/cancelAny non-terminal → cancelled.
POST/api/runs/{run}/retryfailed → queued. Reuses prompt; new branch.

Run telemetry

MethodPathNotes
GET/api/runs/{run}/events?since=&eventTypes=&severity=&path=&limit= paged backfill.
GET/api/runs/{run}/events/streamSSE; supports Last-Event-ID.
GET/api/runs/{run}/filesList of workspace_files for the run.
GET/api/runs/{run}/files/{file}Detail + full diff.
GET/api/runs/{run}/diffAggregate unified diff for the run.
GET/api/runs/{run}/snapshotsSnapshots created by this run.
GET/api/runs/{run}/commandscommand_executions rows.
GET/api/runs/{run}/commands/{command}Detail + signed URLs to stdout/stderr blobs.
GET/api/runs/{run}/summaryStructured final summary (changed files, risks, tests, docs).

Run approval & Git actions

MethodPathNotes
POST/api/runs/{run}/approve{ notes?, commit?: boolean }. Writes run_reviews row.
POST/api/runs/{run}/reject{ notes? }. Writes run_reviews row.
POST/api/runs/{run}/commitCommits outstanding changes on the run branch. Requires approval.
POST/api/runs/{run}/pushGated by safety.auto_git_push • ability git:push • approved review.

Snapshots

MethodPathNotes
GET/api/projects/{project}/snapshotsList all snapshots for a project.
GET/api/snapshots/{snapshot}Snapshot detail.
POST/api/snapshots/{snapshot}/restoreRestores. Emits snapshot_created (description: "restore checkpoint").
POST/api/snapshots/{snapshot}/compare`{ against: "current"
POST/api/projects/{project}/snapshotsCreate a manual snapshot ({ description }).

Documentation

MethodPathNotes
GET/api/projects/{project}/docsList managed docs and last update timestamps.
GET/api/projects/{project}/docs/{slug}Returns the markdown body + metadata.
GET/api/projects/{project}/changelogReturns parsed CHANGELOG_AI.md entries.
POST/api/projects/{project}/docs/regenerateForce regenerate all auto-blocks.

Settings (server params)

MethodPathNotes
GET/api/settings/server-paramsMerged settings; secrets masked.
PUT/api/settings/server-paramsPartial update; type-checked; never echoes secret values.
GET/api/settings/providersLists agent_providers rows + enabled state.
PUT/api/settings/providers/{key}Enable/disable a provider.

Devices (notifications, v1.1)

MethodPathNotes
POST/api/devicesRegister APNs token.
DELETE/api/devices/{device}Unregister.

Error model (RFC 7807)

{
	"type": "https://docs.example.com/errors/run-not-startable",
	"title": "Run is not in a startable state",
	"detail": "Run #148 is already running.",
	"status": 409,
	"instance": "/api/runs/148/start",
	"runId": 148,
	"currentStatus": "running"
}

SSE event format

Each event:

id: 91823
event: agent_event
data: { "id": 91823, "runId": 148, "eventType": "file_updated", … }

:ping

The id field is the agent_events.id. Clients send Last-Event-ID on reconnect.

Sanctum abilities

  • projects:read
  • projects:write
  • runs:start
  • runs:control (pause/resume/cancel/retry)
  • git:commit
  • git:push
  • settings:read
  • settings:write

Mobile app's default token requests projects:*, runs:start, runs:control, git:commit, settings:read. git:push and settings:write require an explicit elevation flow.

Rate limits

GroupLimit
Default60 req/min/user
runs:start6 req/min/user
SSE streamsMax 4 concurrent per user
Settings writes20 req/min/user