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

POST /v1/sessions/{session_id}/clients

POST/v1/sessions/{session_id}/clients
Authorization
AuthorizationBearer token · headerrequired
Path parameters
session_idstring<uuid>required
Session id
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
Request body
requiredapplication/json
lifetimeClientLifetimeFormrequired
How long the registration outlives its last ping.
Show properties
One of:
object
typestringrequired
Allowed:never
object
dataobjectrequired
Ends this many seconds after the last ping. For a client that can vanish without saying so, such as a browser tab.
Show properties
secondsinteger<int32>required
min 5 · max 3600
typestringrequired
Allowed:ttl
namestringrequired
What to call this client. Chosen by whoever writes it, because the model reads it: every tool reaches the model as `client__{name}__{tool}`. A name this session has already handed out gets a counter -- spent for the session, whether or not that client is still here -- so the assigned name in the response is the one that counts. Registering again therefore takes a fresh name: a client that wants to keep its own pings instead.
min length 1 · max length 32 · matches ^[a-z0-9-]+$
toolsClientToolBody[]
What this client can do right now. Replace it with the tools endpoint whenever that changes.
max items 64
Show properties
Array of ClientToolBody
descriptionstringrequired
What the tool does, as the model reads it.
max length 4096
namestringrequired
min length 1 · max length 64 · matches ^[A-Za-z0-9_-]+$
parametersobjectrequired
JSON Schema object describing the tool's arguments.
Responses
201Registered. `name` is the assigned name, which may carry a counter; the tools reach the model as `client__{name}__{tool}` from its next model call, whether a run is already live on the session or starts later.
expires_atstring<date-time> | nullrequired
When the registration lapses without a ping; null when it never does.
idstring<uuid>required
namestringrequired
The name assigned: the one asked for, or that one plus a counter when this session had already spent it. This is what the model sees the tools under.
400Malformed body or path parameter, a name outside its charset or length, a tool outside its own, or a ttl outside 5..3600 seconds.
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 credential.
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
403A workspace credential lacking session.manage.
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
404The session token authenticates for another session, or a workspace credential cannot see this one.
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 session already holds the most live clients it may.
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/497f6eca-6276-4993-bfeb-53cbbbba6f08/clients" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "lifetime": {
    "type": "never"
  },
  "name": "string",
  "tools": [
    {
      "description": "string",
      "name": "string",
      "parameters": {}
    }
  ]
}'
Response
{
  "expires_at": "2019-08-24T14:15:22Z",
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "name": "string"
}