API conventions

Authentication, pagination, errors, and idempotency.

The Core API is at https://api.us.cloud.subako.ai, every route under /v1. The API reference lists every endpoint, with a playground that calls the live server.

Authentication

Every call sends Authorization: Bearer <token>. The token’s prefix says what it is:

Prefix		Lives
`sbk_ak_`	An API key: one workspace, its permissions	Until revoked, or its expiry
`sbk_st_`	A session token: one session	One hour
`sbk_at_`	A person’s access token, as the CLI holds after `subako login`	Minutes; `subako token` prints a fresh one

The workspace header

A person belongs to many workspaces, so a call made with a person’s token names the one it acts in, by ID, in Kikuvi-Workspace:

curl https://api.us.cloud.subako.ai/v1/agents \
  -H "Authorization: Bearer $(subako token | jq -r .access_token)" \
  -H "Kikuvi-Workspace: $WORKSPACE_ID"

It is required on a workspace’s collections — /v1/agents, /v1/sessions, /v1/skills, /v1/functions, /v1/vaults, /v1/model-providers, /v1/api-keys. A route that names a resource by ID finds the workspace from it. An API key already belongs to one workspace, so its calls need no header; one that names another workspace is refused.

The workspace’s ID is on its Overview page in the console.

Pagination

Lists answer { "items": [...], "next_cursor": ..., "prev_cursor": ... }, newest first:

Parameter
`limit`	1 to 200, 50 by default. Outside that range is an error, not clamped.
`after`	`next_cursor` from the previous page, for the next one
`before`	`prev_cursor`, for the one before
`order`	`desc` (the default) or `asc`

A session’s events page by sequence number instead — see Streaming events.

Errors

Every failure answers the same envelope:

{ "error": { "code": "not_found", "message": "session not found" } }

`code`	Status
`invalid_request`	400
`unauthorized`	401
`forbidden`	403 — also when the plan’s cap, or the organization’s credit, refuses it
`not_found`	404
`conflict`	409
`precondition_failed`	412
`too_many_requests`	429
`internal`	500

Branch on code; the message is for people and may change.

Idempotency

Calls that create something take an Idempotency-Key header, 1 to 255 characters. The same key again answers what the first call did, with Idempotency-Replayed: true, instead of doing it twice — so a retry after a timeout is safe. The same key with a different body is a conflict. A secret shown once, such as a new session’s token or a new API key, is not replayed. Keys are remembered for at least seven days.