Skip to content
Subako Docs
English
English日本語Not translated
Esc
↑↓navigate↵open⌘Jpreview

Create a session

A session runs one agent version and keeps the event log every other session route reads. The response carries the session’s first token, which is shown once.

POST/v1/sessions
Authorization
AuthorizationBearer token · headerrequired
Header parameters
Idempotency-Keystring
Retry the same operation with this key to return its saved receipt. Scoped by the operation's authenticated caller or resource. A different input under the same key returns 409. Receipts are retained for at least 7 days after completion, then removed by an hourly sweep. After removal the key can execute again. Fresh-only secrets are never included in a replay.
min length 1 · max length 255
Kikuvi-Workspacestring<uuid>
Workspace to create in. Required for a user caller; implied by the key for an API key caller.
Request body
requiredapplication/json
agent_idstring<uuid>required
display_namestring
Human label for the session. Omitted reads as empty.
max length 200
metadataobject
Labels for the session, fixed at creation and inherited by every session it spawns. Each usage row the session produces carries a copy, so usage can be filtered and grouped by them. At most 50 keys, each 1 to 64 lowercase letters, digits, or underscores and not starting with `subako_`; each value a string of at most 500 characters. Usage keeps them after the session is deleted, so put opaque identifiers here, never personal or secret information.
vault_idsstring<uuid>[]
Vaults this session may draw tool-source credentials from; each must be a live vault in the session's workspace.
max items 10
Responses
200Replayed receipt. The token secret is never replayed. If the first response was lost, mint a replacement with a new key. The original token remains valid until expiry.
agent_idstring<uuid>required
agent_version_idstring<uuid>required
created_atstring<date-time>required
display_namestringrequired
idstring<uuid>required
metadataobjectrequired
session_token_expires_atstring<date-time>required
session_token_idstring<uuid>required
statusSessionStatusBodyrequired
Whether a run is under way. Input is accepted either way: it starts a run when the session is `idle` and steers the live one when it is `active`.
Allowed:idleactive
workspace_idstring<uuid>required
201Created. The session token is shown once.
agent_idstring<uuid>required
agent_version_idstring<uuid>required
created_atstring<date-time>required
display_namestringrequired
idstring<uuid>required
metadataobjectrequired
session_tokenstringrequired
Shown once. Store it now; it cannot be retrieved again.
session_token_expires_atstring<date-time>required
statusSessionStatusBodyrequired
Whether a run is under way. Input is accepted either way: it starts a run when the session is `idle` and steers the live one when it is `active`.
Allowed:idleactive
workspace_idstring<uuid>required
400Malformed body, a display_name over 200 characters, more than 10 vault_ids, metadata outside its bounds or under a reserved key, an agent with no live version, a vault outside the workspace, a malformed workspace header, or a user caller with no workspace header.
errorErrorDetailrequired
What went wrong: a `code` to branch on and a `message` to show. The message is written for a person and may change; the code will not.
Show properties
codeErrorCoderequired
The machine-readable half of an error response, and the field a client branches on. Closed: every error carries exactly one of these.
Allowed:unauthorizedforbiddennot_foundinvalid_requestconflictclient_outdatedprecondition_failedtoo_many_requestsinternal
messagestringrequired
401Missing, malformed, or invalid bearer token.
errorErrorDetailrequired
What went wrong: a `code` to branch on and a `message` to show. The message is written for a person and may change; the code will not.
Show properties
codeErrorCoderequired
The machine-readable half of an error response, and the field a client branches on. Closed: every error carries exactly one of these.
Allowed:unauthorizedforbiddennot_foundinvalid_requestconflictclient_outdatedprecondition_failedtoo_many_requestsinternal
messagestringrequired
403Caller lacks session.create, or an API key's Kikuvi-Workspace header names another workspace.
errorErrorDetailrequired
What went wrong: a `code` to branch on and a `message` to show. The message is written for a person and may change; the code will not.
Show properties
codeErrorCoderequired
The machine-readable half of an error response, and the field a client branches on. Closed: every error carries exactly one of these.
Allowed:unauthorizedforbiddennot_foundinvalid_requestconflictclient_outdatedprecondition_failedtoo_many_requestsinternal
messagestringrequired
404No such workspace, agent, or vault -- or the caller cannot see it.
errorErrorDetailrequired
What went wrong: a `code` to branch on and a `message` to show. The message is written for a person and may change; the code will not.
Show properties
codeErrorCoderequired
The machine-readable half of an error response, and the field a client branches on. Closed: every error carries exactly one of these.
Allowed:unauthorizedforbiddennot_foundinvalid_requestconflictclient_outdatedprecondition_failedtoo_many_requestsinternal
messagestringrequired
409Idempotency-Key was already used for a different request. The same vault named twice.
errorErrorDetailrequired
What went wrong: a `code` to branch on and a `message` to show. The message is written for a person and may change; the code will not.
Show properties
codeErrorCoderequired
The machine-readable half of an error response, and the field a client branches on. Closed: every error carries exactly one of these.
Allowed:unauthorizedforbiddennot_foundinvalid_requestconflictclient_outdatedprecondition_failedtoo_many_requestsinternal
messagestringrequired
Try it
Server
Authorization
Parameters
Bodyapplication/json
Request
curl -X POST "https://api.us.cloud.subako.ai/v1/sessions" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "agent_id": "2b1e3b65-2c04-4fa2-a2d7-467901e98978",
  "display_name": "string",
  "metadata": {
    "property1": "string",
    "property2": "string"
  },
  "vault_ids": [
    "497f6eca-6276-4993-bfeb-53cbbbba6f08"
  ]
}'
Response
{
  "agent_id": "2b1e3b65-2c04-4fa2-a2d7-467901e98978",
  "agent_version_id": "1c2a713c-7248-4a56-a9eb-0bdcb3a41741",
  "created_at": "2019-08-24T14:15:22Z",
  "display_name": "string",
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "metadata": {
    "property1": "string",
    "property2": "string"
  },
  "session_token_expires_at": "2019-08-24T14:15:22Z",
  "session_token_id": "54d12a8d-1158-4753-88fe-9c724fd86e9d",
  "status": "idle",
  "workspace_id": "0967198e-ec7b-4c6b-b4d3-f71244cadbe9"
}