API reference

Every public HTTP endpoint, with request and response shapes.

API reference

Promptsheon exposes a JSON-over-HTTP API on the same port as the UI (8080). The frontend’s Next.js config rewrites every /api/* request from localhost:3000 to localhost:8080, so browser code can use relative paths.

The full OpenAPI 3.1 spec is auto-emitted at GET /api/openapi.json once the server boots. This page is the human-readable summary.

Conventions

• Content type. All requests and responses use application/json.
• Error shape. Every error returns {"error": {"code": "<MACHINE_CODE>", "message": "<human-readable>"}}. See Error codes.
• Authentication. When PROMPTSHEON_AUTH=true, every non-public request needs an Authorization: Bearer <token> header. The token is sha256-hashed and looked up in the api_keys table. See Authentication.
• Request id. Every response carries an X-Request-Id header. The header value is echoed if the request supplied one.
• Pagination. List endpoints accept ?page=N&pageSize=M. The default page size is 25. The response is always {items: [...], total: N}.

Authentication

POST /api/executions HTTP/1.1
Host: localhost:8080
Authorization: Bearer <token>
Content-Type: application/json

When PROMPTSHEON_AUTH=false (the development default), the request can include X-User-Id and X-Org-Id headers instead. In production, set PROMPTSHEON_AUTH=true and supply a Bearer token.

The server also accepts Authorization: SVID <token> for agent identities. See Security.

Health

GET /api/health

Returns the server’s liveness state. Always 200 OK.

{
  "status": "ok",
  "service": "promptsheon-server",
  "version": "0.4.2",
  "uptimeSec": 1234
}

GET /api/audit/state and GET /api/audit/verify

Both endpoints are publicly callable (no auth required) so the documentation links work in a fresh browser. /api/audit/verify returns:

{
  "valid": true,
  "frameCount": 1024,
  "lastHash": "abc123…"
}

If any frame is tampered with, valid becomes false and brokenAt reports the index of the first bad frame.

Onboarding

POST /api/bootstrap/admin

Creates the first admin user and organisation. Called once during onboarding.

POST /api/bootstrap/admin
Content-Type: application/json

{
  "userName": "Alice",
  "userEmail": "alice@example.com",
  "orgName": "Acme"
}

The response carries the session cookie that the rest of the API expects.

Workspaces

POST /api/workspaces
Content-Type: application/json

{
  "name": "Refund triage",
  "description": "Customer-facing refund flows"
}

Projects, capabilities, versions, releases

The same CRUD shape applies. The full list lives in packages/server/API.md.

Executions

POST /api/executions

Execute a capability release. Without an Accept header, returns buffered JSON. With Accept: text/event-stream, streams per-node events:

event: execution_start
data: {"executionId":"e_123","manifestHash":"…"}

event: node_start
data: {"executionId":"e_123","nodeId":"plan"}

event: node_complete
data: {"executionId":"e_123","nodeId":"plan","output":"…"}

event: execution_complete
data: {"executionId":"e_123","output":"…","tokens":1234}

event: done
data: [DONE]

GET /api/executions/:id

Fetch an execution by id. Returns the manifest, the inputs, the per-node outputs, and the trace.

POST /api/executions/:id/replay

Re-run an execution with the same manifest, model, environment, and inputs. The new execution is linked to the original via replay_of; the original’s replay_count is incremented.

GET /api/executions/:id/replays

List every replay attempt with outcome and diff.

Eval

Repositories, commits, merge requests

The full repo surface (/api/repos, /api/repos/:id/branches, /api/repos/:id/commits, /api/merge-requests, …) is documented in packages/server/API.md. Repos are content-addressed and signed.

Cost and budgets

Firewall sidecar

If you mount the firewall sidecar (pnpm --filter @promptsheon/server firewall), it exposes POST /v1/chat/completions on a separate port. It forwards to the upstream URL after running the scanner. Decisions are written to the audit chain so /api/audit/verify covers sidecar traffic.

Error codes

Where to go next