Skip to content
Subako Docs
Esc
↑↓navigate↵open⌘Jpreview

POST /v1/sessions

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
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
session_token_expires_atstring<date-time>required
session_token_idstring<uuid>required
statusSessionStatusBodyrequired
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
session_tokenstringrequired
Shown once. Store it now; it cannot be retrieved again.
session_token_expires_atstring<date-time>required
statusSessionStatusBodyrequired
Allowed:idleactive
workspace_idstring<uuid>required
400Malformed body, a display_name over 200 characters, more than 10 vault_ids, an agent with no live version, a vault outside the workspace, a malformed workspace header, or a user caller with no workspace header.
errorErrorDetailrequired
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
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
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
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
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",
  "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",
  "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"
}