DevHub API reference
DevHub API reference. Paths are relative to the DevHub base URL, shown on an Agent’s API tab in DevHub Console, and every operation requires a DevHub Key.
Security schemes
Section titled “Security schemes”{ "DevhubKey": { "type": "http", "scheme": "bearer", "bearerFormat": "DevHub Key", "description": "A DevHub Key, `ti_dev_` followed by 43 base64url characters, sent as `Authorization: Bearer <key>`. It authenticates exactly one provisioned Developer and grants nothing in the core. A missing, malformed, unknown or revoked key, or a key whose Developer is not yet provisioned, is refused with 401 `authentication_required`. A revocation applies to the next request and ends the event streams the key opened within a few seconds." }}GET /api/v1/me
Section titled “GET /api/v1/me”Identify the calling Developer
Returns the id of the Developer that owns the presented DevHub Key.
getMe
Authentication
Section titled “Authentication”[ { "DevhubKey": [] }]Responses
Section titled “Responses”{ "200": { "description": "The calling Developer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Me" } } } }, "401": { "$ref": "#/components/responses/AuthenticationRequired" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" }}GET /api/v1/examples
Section titled “GET /api/v1/examples”List Official Examples
Returns the Official Examples DevHub currently publishes, newest publication first. Copy one into a new Agent with POST /api/v1/agents and its exampleId.
listOfficialExamples
Authentication
Section titled “Authentication”[ { "DevhubKey": [] }]Responses
Section titled “Responses”{ "200": { "description": "The published Official Examples.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OfficialExampleList" } } } }, "401": { "$ref": "#/components/responses/AuthenticationRequired" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" }}GET /api/v1/skills
Section titled “GET /api/v1/skills”List Official Skills
Returns the Official Skills DevHub currently publishes, newest publication first, each at the version an Agent can select. Select them with the skills field of PATCH /api/v1/agents/{agentId}.
listOfficialSkills
Authentication
Section titled “Authentication”[ { "DevhubKey": [] }]Responses
Section titled “Responses”{ "200": { "description": "The published Official Skills.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OfficialSkillList" } } } }, "401": { "$ref": "#/components/responses/AuthenticationRequired" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" }}GET /api/v1/models
Section titled “GET /api/v1/models”List the models your Agents can use
Returns the text models an Agent’s defaultModel can name and the Realtime models its defaultRealtimeModel can name, as the platform serves them now. A model with available: false is known but cannot serve right now; a Session created with it is refused with 409 configuration_unavailable.
listModels
Authentication
Section titled “Authentication”[ { "DevhubKey": [] }]Responses
Section titled “Responses”{ "200": { "description": "The selectable models.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModelCatalog" } } } }, "401": { "$ref": "#/components/responses/AuthenticationRequired" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" }}GET /api/v1/agents
Section titled “GET /api/v1/agents”List your Agents
Returns every Agent of the calling Developer, newest first.
listAgents
Authentication
Section titled “Authentication”[ { "DevhubKey": [] }]Responses
Section titled “Responses”{ "200": { "description": "The calling Developer's Agents.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentList" } } } }, "401": { "$ref": "#/components/responses/AuthenticationRequired" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" }}POST /api/v1/agents
Section titled “POST /api/v1/agents”Create an Agent
Creates a blank Agent, or one that copies an Official Example’s current configuration (instructions, default models, Skills, voice and Session Recall settings). A copy never follows later changes to the example. A blank Agent starts with empty instructions, no Skills, voice off and Session Recall off.
Send a new Idempotency-Key for each Agent. If a response is lost, repeat the request with the same key and body: it completes or returns the same Agent and never creates a second one. The same key with a different body is refused with 409 idempotency_key_reused.
createAgent
Authentication
Section titled “Authentication”[ { "DevhubKey": [] }]Parameters
Section titled “Parameters”[ { "$ref": "#/components/parameters/IdempotencyKey" }]Request body
Section titled “Request body”{ "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAgentRequest" } } }}Responses
Section titled “Responses”{ "201": { "description": "The created Agent, or the Agent an earlier request with this key created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Agent" } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/AuthenticationRequired" }, "404": { "description": "The Official Example is not published, or the Agent created with this key has since been deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "`idempotency_key_reused`: the key was used with a different body. `configuration_unavailable`: the configuration references something no longer available, such as a Skill version of the example; nothing was created and the key may be reused. `conflict`: another request with this key is in progress, or the Agent cannot be created right now; retry with the same key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "$ref": "#/components/responses/ServiceUnavailable" }}GET /api/v1/agents/{agentId}
Section titled “GET /api/v1/agents/{agentId}”Read one of your Agents
getAgent
Authentication
Section titled “Authentication”[ { "DevhubKey": [] }]Parameters
Section titled “Parameters”[ { "$ref": "#/components/parameters/AgentId" }]Responses
Section titled “Responses”{ "200": { "description": "The Agent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Agent" } } } }, "401": { "$ref": "#/components/responses/AuthenticationRequired" }, "404": { "$ref": "#/components/responses/AgentNotFound" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" }}DELETE /api/v1/agents/{agentId}
Section titled “DELETE /api/v1/agents/{agentId}”Delete one of your Agents
Deletes the Agent permanently and keeps its Session history. As soon as deletion starts, the Agent disappears from list and read, and DevHub refuses new input or Realtime connections for its Sessions. If the request fails, repeat it until it answers 204 or 404. DevHub also finishes a deletion that is not repeated.
deleteAgent
Authentication
Section titled “Authentication”[ { "DevhubKey": [] }]Parameters
Section titled “Parameters”[ { "$ref": "#/components/parameters/AgentId" }]Responses
Section titled “Responses”{ "204": { "description": "The Agent is deleted." }, "401": { "$ref": "#/components/responses/AuthenticationRequired" }, "404": { "$ref": "#/components/responses/AgentNotFound" }, "409": { "$ref": "#/components/responses/AgentConflict" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" }}PATCH /api/v1/agents/{agentId}
Section titled “PATCH /api/v1/agents/{agentId}”Update one of your Agents
Changes the fields present in the body; absent fields stay unchanged and at least one is required. Every change applies to Sessions created afterwards; existing Sessions keep the configuration they started with. Repeating an update is safe. skills replaces the selected Official Skills: each must be listed by GET /api/v1/skills at that version, or already be selected on this Agent at that version, which keeps a Skill DevHub has since withdrawn.
updateAgent
Authentication
Section titled “Authentication”[ { "DevhubKey": [] }]Parameters
Section titled “Parameters”[ { "$ref": "#/components/parameters/AgentId" }]Request body
Section titled “Request body”{ "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateAgentRequest" } } }}Responses
Section titled “Responses”{ "200": { "description": "The updated Agent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Agent" } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/AuthenticationRequired" }, "404": { "$ref": "#/components/responses/AgentNotFound" }, "409": { "$ref": "#/components/responses/AgentConflict" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" }}GET /api/v1/sessions
Section titled “GET /api/v1/sessions”List your Sessions
Returns one page of the calling Developer’s Sessions, newest first. A page can hold fewer than limit Sessions, even none; continue with nextCursor until it is null. Deleted Sessions are not listed.
listSessions
Authentication
Section titled “Authentication”[ { "DevhubKey": [] }]Parameters
Section titled “Parameters”[ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }]Responses
Section titled “Responses”{ "200": { "description": "One page of Sessions.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionList" } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/AuthenticationRequired" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" }}POST /api/v1/sessions
Section titled “POST /api/v1/sessions”Create a Session
Creates a Session of one of your Agents. The Session starts with the Agent’s current configuration and default models: defaultModel, or the platform default when it is null, and defaultRealtimeModel when the Agent has voice enabled. Later Agent changes do not reach existing Sessions.
Send a new Idempotency-Key for each Session. If a response is lost, repeat the request with the same key and body: it completes or returns the same Session and never creates a second one, even if the Agent’s default models changed meanwhile. The same key with a different agentId is refused with 409 idempotency_key_reused. A creation refused with 409 configuration_unavailable keeps its key; after changing the Agent, create the Session with a new key.
createSession
Authentication
Section titled “Authentication”[ { "DevhubKey": [] }]Parameters
Section titled “Parameters”[ { "$ref": "#/components/parameters/IdempotencyKey" }]Request body
Section titled “Request body”{ "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSessionRequest" } } }}Responses
Section titled “Responses”{ "201": { "description": "The created Session, or the Session an earlier request with this key created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Session" } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/AuthenticationRequired" }, "404": { "description": "The Agent is not one of your Agents, or the Session created with this key has since been deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "`idempotency_key_reused`: the key was used with a different body. `configuration_unavailable`: the Agent's configuration, such as its default model, is not available. `conflict`: another request with this key is in progress; retry with the same key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "$ref": "#/components/responses/ServiceUnavailable" }}GET /api/v1/sessions/{sessionId}
Section titled “GET /api/v1/sessions/{sessionId}”Read one of your Sessions
getSession
Authentication
Section titled “Authentication”[ { "DevhubKey": [] }]Parameters
Section titled “Parameters”[ { "$ref": "#/components/parameters/SessionId" }]Responses
Section titled “Responses”{ "200": { "description": "The Session.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Session" } } } }, "401": { "$ref": "#/components/responses/AuthenticationRequired" }, "404": { "$ref": "#/components/responses/SessionNotFound" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" }}DELETE /api/v1/sessions/{sessionId}
Section titled “DELETE /api/v1/sessions/{sessionId}”Delete one of your Sessions
Deletes the Session through the platform’s public Session deletion: it disappears from list and read, and its Turns can no longer be read. If the request fails, repeat it until it answers 204 or 404; either means the Session is deleted.
deleteSession
Authentication
Section titled “Authentication”[ { "DevhubKey": [] }]Parameters
Section titled “Parameters”[ { "$ref": "#/components/parameters/SessionId" }]Responses
Section titled “Responses”{ "204": { "description": "The Session is deleted." }, "401": { "$ref": "#/components/responses/AuthenticationRequired" }, "404": { "$ref": "#/components/responses/SessionNotFound" }, "409": { "description": "`session_has_active_turn`: a Turn is running; cancel it or wait until it finishes, then retry. `session_read_only`: the Session can no longer be changed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "$ref": "#/components/responses/ServiceUnavailable" }}PATCH /api/v1/sessions/{sessionId}
Section titled “PATCH /api/v1/sessions/{sessionId}”Rename one of your Sessions
renameSession
Authentication
Section titled “Authentication”[ { "DevhubKey": [] }]Parameters
Section titled “Parameters”[ { "$ref": "#/components/parameters/SessionId" }]Request body
Section titled “Request body”{ "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RenameSessionRequest" } } }}Responses
Section titled “Responses”{ "200": { "description": "The renamed Session.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Session" } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/AuthenticationRequired" }, "404": { "$ref": "#/components/responses/SessionNotFound" }, "409": { "description": "`session_read_only`: the Session can no longer be changed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "$ref": "#/components/responses/ServiceUnavailable" }}GET /api/v1/sessions/{sessionId}/timeline
Section titled “GET /api/v1/sessions/{sessionId}/timeline”Read a Session’s timeline
Returns one page of the Session’s history, oldest first: each entry is a Turn or a voice transcript. A Turn that is still running is a snapshot; read it again or follow the event stream. An entry can appear again on a later page; key entries by id and keep the latest. Continue with nextCursor until it is null. A platform Handoff appears as a template_handoff Turn with no user Messages. Its saved assistant Message summarizes the Session for the new configuration. Follow it through the Session stream.
getSessionTimeline
Authentication
Section titled “Authentication”[ { "DevhubKey": [] }]Parameters
Section titled “Parameters”[ { "$ref": "#/components/parameters/SessionId" }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }]Responses
Section titled “Responses”{ "200": { "description": "One page of the timeline.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Timeline" } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/AuthenticationRequired" }, "404": { "$ref": "#/components/responses/SessionNotFound" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" }}POST /api/v1/sessions/{sessionId}/turns
Section titled “POST /api/v1/sessions/{sessionId}/turns”Send input to a Session
Sends text input to the Session. When no Turn is running it starts a Turn (mode: started); while a Turn is running, the input joins that Turn instead (mode: steered). Follow the Turn with GET .../turns/{turnId}/events and read it afterwards with GET .../turns/{turnId}.
fileIds selects files uploaded to this Session with POST .../files for the Agent to use. Input with files can only start a Turn: while a Turn is running it is refused with 409 session_has_active_turn, and that refusal stays with its Idempotency-Key, so send it again with a new key once the Turn has finished. A Turn started with input uses the Session’s Client Tools as they are at that moment.
Send a new Idempotency-Key for each input. Repeating a request with the same key and input returns the same answer without sending the input again; the same key with different input is refused with 409 idempotency_key_reused.
Input that starts or steers a Turn uses your monthly Credits. Once they are used up, input is refused with 429 credits_exhausted until they reset at the start of the next UTC month. Client Tool results are still accepted, so a running Turn can finish.
createTurn
Authentication
Section titled “Authentication”[ { "DevhubKey": [] }]Parameters
Section titled “Parameters”[ { "$ref": "#/components/parameters/SessionId" }, { "$ref": "#/components/parameters/IdempotencyKey" }]Request body
Section titled “Request body”{ "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTurnRequest" } } }}Responses
Section titled “Responses”{ "202": { "description": "The input was accepted; the Turn runs in the background.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TurnSubmission" } } } }, "400": { "description": "`invalid_request`: the request is malformed, or the platform refused valid input because the Session's Client Tools exceed its limit of 64 tools or 64 KiB once it adds its own arguments, or refused the Session's Client Tools themselves. Nothing was sent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/AuthenticationRequired" }, "404": { "description": "`not_found`: the Session is not one of your Sessions, or a file in `fileIds` was not uploaded to this Session.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "`idempotency_key_reused`: the key was used with different input. `conflict`: the running Turn is finishing and no longer accepts input, or a Handoff is changing the Session configuration. Use a new key after a Turn refused input while finishing. `session_has_active_turn`: input with files arrived while a Turn was running; send it again with a new key once the Turn has finished. `session_read_only`: the Session can no longer be continued. `configuration_unavailable`: the Session's configuration, such as its model, is not available.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "`credits_exhausted`: this month's Credits are used up. This request sent nothing; a retry of input accepted earlier is refused the same way. `resetsAt` says when they reset: the start of the next UTC month.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "credits_exhausted", "message": "You have used this month's Credits; they reset at the start of next month (UTC).", "resetsAt": "2026-12-01T00:00:00.000Z" } } } } }, "503": { "description": "`service_unavailable`: DevHub or the service behind it is temporarily unavailable; the input may have been accepted, so retry with the same `Idempotency-Key`. `credits_unavailable`: DevHub cannot check your Credits right now. Nothing was sent; retry later with the same `Idempotency-Key`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }}GET /api/v1/sessions/{sessionId}/turns/{turnId}
Section titled “GET /api/v1/sessions/{sessionId}/turns/{turnId}”Read a Turn
getTurn
Authentication
Section titled “Authentication”[ { "DevhubKey": [] }]Parameters
Section titled “Parameters”[ { "$ref": "#/components/parameters/SessionId" }, { "$ref": "#/components/parameters/TurnId" }]Responses
Section titled “Responses”{ "200": { "description": "The Turn as it is now.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Turn" } } } }, "401": { "$ref": "#/components/responses/AuthenticationRequired" }, "404": { "$ref": "#/components/responses/TurnNotFound" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" }}POST /api/v1/sessions/{sessionId}/turns/{turnId}/cancel
Section titled “POST /api/v1/sessions/{sessionId}/turns/{turnId}/cancel”Cancel a Turn
Asks the running Turn to stop. It ends as interrupted shortly afterwards; work it already completed is kept. Cancelling a Turn that is no longer running changes nothing and answers accepted: false. Repeating a cancellation is safe and answers as the first one did.
cancelTurn
Authentication
Section titled “Authentication”[ { "DevhubKey": [] }]Parameters
Section titled “Parameters”[ { "$ref": "#/components/parameters/SessionId" }, { "$ref": "#/components/parameters/TurnId" }]Responses
Section titled “Responses”{ "202": { "description": "Whether the Turn was asked to stop.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TurnCancellation" } } } }, "401": { "$ref": "#/components/responses/AuthenticationRequired" }, "404": { "$ref": "#/components/responses/TurnNotFound" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" }}GET /api/v1/sessions/{sessionId}/events
Section titled “GET /api/v1/sessions/{sessionId}/events”Stream a Session’s events
A Server-Sent Events stream of the Session’s Turn events and voice transcripts in the order they were saved. Without cursor it starts at the Session’s first event; each frame’s id is a cursor that continues after that frame. Each data field is one SessionEvent; comment lines are keep-alives. Closing the stream does not cancel a running Turn.
The stream ends when the Session is deleted, when the platform ends it, or when the DevHub Key that opened it is revoked, within a few seconds on every DevHub server. Reconnect with the last cursor, as cursor or in the Last-Event-ID header, to continue; a revoked key is then refused with 401. A stream reads only as fast as the client does, and ends when the client accepts nothing for 30 seconds. Cursors issued before DevHub moved its streams to the platform’s Backend Connections no longer continue and answer 400 invalid_request; start again without one.
streamSessionEvents
Authentication
Section titled “Authentication”[ { "DevhubKey": [] }]Parameters
Section titled “Parameters”[ { "$ref": "#/components/parameters/SessionId" }, { "$ref": "#/components/parameters/Cursor" }, { "name": "Last-Event-ID", "in": "header", "required": false, "description": "The `id` of the last frame received; ignored when `cursor` is given.", "schema": { "type": "string" } }]Responses
Section titled “Responses”{ "200": { "description": "The event stream.", "content": { "text/event-stream": { "schema": { "type": "string" }, "x-devhub-event": { "$ref": "#/components/schemas/SessionEvent" } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/AuthenticationRequired" }, "404": { "$ref": "#/components/responses/SessionNotFound" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" }}GET /api/v1/sessions/{sessionId}/turns/{turnId}/events
Section titled “GET /api/v1/sessions/{sessionId}/turns/{turnId}/events”Stream a Turn’s events
A Server-Sent Events stream of one Turn’s events from its start, including those already saved, ending after the Turn’s turn_finished event. Frames carry no id. It also ends when the Session is deleted, when the platform ends it, when the DevHub Key that opened it is revoked, or when the client accepts nothing for 30 seconds; read the Turn to learn its outcome.
streamTurnEvents
Authentication
Section titled “Authentication”[ { "DevhubKey": [] }]Parameters
Section titled “Parameters”[ { "$ref": "#/components/parameters/SessionId" }, { "$ref": "#/components/parameters/TurnId" }]Responses
Section titled “Responses”{ "200": { "description": "The event stream.", "content": { "text/event-stream": { "schema": { "type": "string" }, "x-devhub-event": { "$ref": "#/components/schemas/SessionEvent" } } } }, "401": { "$ref": "#/components/responses/AuthenticationRequired" }, "404": { "$ref": "#/components/responses/TurnNotFound" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" }}POST /api/v1/sessions/{sessionId}/files
Section titled “POST /api/v1/sessions/{sessionId}/files”Upload a file for the Session’s Turns
Uploads one file, 1 byte to 20 MiB, for Turns of this Session. Send the file’s bytes as the request body with Content-Type: application/octet-stream, its name in name and, optionally, its media type in contentType. The whole body must arrive within 120 seconds, otherwise the upload is refused with 400. DevHub takes a limited number of uploads at once, overall and per Developer; beyond that it answers 503, and the upload can be retried. The answer arrives once the file is stored; pass its id in fileIds when sending input. Only Turns of this Session can use the file. Files are kept after the Session is deleted, but can no longer be used.
Send a new Idempotency-Key for each file. If a response is lost, repeat the request with the same key, query and body: it completes or returns the same file and never stores a second one. The same key with a different file, name, media type or Session is refused with 409 idempotency_key_reused.
uploadFile
Authentication
Section titled “Authentication”[ { "DevhubKey": [] }]Parameters
Section titled “Parameters”[ { "$ref": "#/components/parameters/SessionId" }, { "$ref": "#/components/parameters/IdempotencyKey" }, { "name": "name", "in": "query", "required": true, "description": "The file's name, 1 to 255 characters on one line, without control or bidirectional formatting characters. Surrounding whitespace is trimmed.", "schema": { "type": "string" } }, { "name": "contentType", "in": "query", "required": false, "description": "The file's media type without parameters, such as `image/png` or `application/pdf`.", "schema": { "type": "string" } }]Request body
Section titled “Request body”{ "required": true, "content": { "application/octet-stream": { "schema": { "type": "string", "contentMediaType": "application/octet-stream" } } }}Responses
Section titled “Responses”{ "201": { "description": "The stored file, or the file an earlier request with this key stored.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/File" } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/AuthenticationRequired" }, "404": { "$ref": "#/components/responses/SessionNotFound" }, "409": { "description": "`idempotency_key_reused`: the key was used with a different request. `conflict`: another request with this key is uploading the file, so retry with the same key; or the upload can no longer complete, so upload the file again with a new key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "`file_too_large`: the file is larger than 20 MiB, or than the platform accepts.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "$ref": "#/components/responses/ServiceUnavailable" }}GET /api/v1/sessions/{sessionId}/client-tools
Section titled “GET /api/v1/sessions/{sessionId}/client-tools”Read the Session’s Client Tools
The Client Tools your application declared for this Session, as DevHub stores them. The ETag header identifies this revision for a conditional replacement.
getClientTools
Authentication
Section titled “Authentication”[ { "DevhubKey": [] }]Parameters
Section titled “Parameters”[ { "$ref": "#/components/parameters/SessionId" }]Responses
Section titled “Responses”{ "200": { "description": "The Session's Client Tools.", "headers": { "ETag": { "$ref": "#/components/headers/ClientToolsETag" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientToolSet" } } } }, "401": { "$ref": "#/components/responses/AuthenticationRequired" }, "404": { "$ref": "#/components/responses/SessionNotFound" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" }}PUT /api/v1/sessions/{sessionId}/client-tools
Section titled “PUT /api/v1/sessions/{sessionId}/client-tools”Declare the Session’s Client Tools
Replaces the Session’s whole Client Tool set; an empty list removes every Client Tool. DevHub stores the set and checks it here, and the platform receives it with the next input you send to the Session: a Turn uses the set stored when its input was accepted, so a replacement reaches the next Turn, not a Turn already running. Your application executes these tools: when the Agent calls one, the event stream carries an agent.session.turn.requires_action frame, and you answer each call with POST .../turns/{turnId}/client-tool-results before its deadlineAt. Replacing with an identical set keeps its revision.
The platform also receives the device tools of the Session’s Agent, named device_<device>_<tool>. They are not part of this set and DevHub executes them; with yours they count toward the platform’s limit of 64 tools and 64 KiB, and device tools beyond it are left out.
Without If-Match the last replacement wins. With If-Match set to an ETag from this resource, the set is replaced only if it has not changed since; otherwise the answer is 412 precondition_failed.
replaceClientTools
Authentication
Section titled “Authentication”[ { "DevhubKey": [] }]Parameters
Section titled “Parameters”[ { "$ref": "#/components/parameters/SessionId" }, { "name": "If-Match", "in": "header", "required": false, "description": "One or more `ETag`s this resource returned, separated by commas, or `*` for any revision. The replacement happens only if the set is at one of them.", "schema": { "type": "string" } }]Request body
Section titled “Request body”{ "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReplaceClientToolsRequest" } } }}Responses
Section titled “Responses”{ "200": { "description": "The Session's Client Tools after the replacement.", "headers": { "ETag": { "$ref": "#/components/headers/ClientToolsETag" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientToolSet" } } } }, "400": { "description": "`invalid_request`: the declarations are malformed or break the platform's rules, for example with a name it reserves for its own tools (including the `mcp_` prefix), a name with the `device_` prefix, which DevHub reserves for the Agent's device tools, or parameters that are not a valid JSON Schema.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/AuthenticationRequired" }, "404": { "$ref": "#/components/responses/SessionNotFound" }, "409": { "description": "`conflict`: other requests kept replacing the set meanwhile; retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "`precondition_failed`: the set changed since the `ETag` in `If-Match`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "$ref": "#/components/responses/ServiceUnavailable" }}GET /api/v1/sessions/{sessionId}/client-tool-calls
Section titled “GET /api/v1/sessions/{sessionId}/client-tool-calls”List Client Tool calls waiting for a result
The Session’s Client Tool calls that still wait for a result before their deadline, oldest first, including calls of Turns the Agent started itself, such as voice-delegated ones. Use it to recover calls after a disconnect. DevHub takes every call for your application as soon as the Agent makes it, so a call is listed here whether or not you received its event, and reading the list changes nothing: any call that gets no result before its deadline ends with an unknown effect for the Agent.
listPendingClientToolCalls
Authentication
Section titled “Authentication”[ { "DevhubKey": [] }]Parameters
Section titled “Parameters”[ { "$ref": "#/components/parameters/SessionId" }]Responses
Section titled “Responses”{ "200": { "description": "The pending calls.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PendingClientToolCallList" } } } }, "401": { "$ref": "#/components/responses/AuthenticationRequired" }, "404": { "$ref": "#/components/responses/SessionNotFound" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" }}POST /api/v1/sessions/{sessionId}/turns/{turnId}/client-tool-results
Section titled “POST /api/v1/sessions/{sessionId}/turns/{turnId}/client-tool-results”Submit a Client Tool result
Answers one Client Tool call of the Turn with its output, or with an error the Agent sees instead. Answer every call before its deadlineAt, whether or not the Agent waits for it; a call without a result by then ends with an unknown effect, and the Agent decides how to continue. The first result DevHub accepts is the call’s result, and DevHub passes it to the Agent; repeating the same result is safe and answers as the first one did. A result less than two seconds before the deadline is refused. The Turn may also be one the Agent started itself, such as a voice-delegated Turn, when DevHub lists its call.
submitClientToolResult
Authentication
Section titled “Authentication”[ { "DevhubKey": [] }]Parameters
Section titled “Parameters”[ { "$ref": "#/components/parameters/SessionId" }, { "$ref": "#/components/parameters/TurnId" }]Request body
Section titled “Request body”{ "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientToolResultRequest" } } }}Responses
Section titled “Responses”{ "202": { "description": "DevHub accepted the result as the call's result and passes it on to the Agent. A Turn that ended meanwhile no longer reads it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientToolResultReceipt" } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/AuthenticationRequired" }, "404": { "description": "`not_found`: the Session or Turn is not one of yours, or the Turn has no Client Tool call with this `callId`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "`client_tool_call_settled`: the call already has an outcome. A different result was accepted or its deadline passed; a call can also be settled because its Turn ended.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "$ref": "#/components/responses/ServiceUnavailable" }}