DevHub API 数据结构
DevHub API 参考。路径相对于 DevHub 基础地址,在 DevHub Console 中 Agent 的 API 页可以看到;每个接口都需要 DevHub Key。规范中的描述保留原文。
parameters/SessionId
Section titled “parameters/SessionId”{ "name": "sessionId", "in": "path", "required": true, "description": "A Session id from this API. Any id that is not one of the calling Developer's Sessions answers 404 `not_found`.", "schema": { "type": "string" }}parameters/TurnId
Section titled “parameters/TurnId”{ "name": "turnId", "in": "path", "required": true, "description": "A Turn id from `POST /api/v1/sessions/{sessionId}/turns` for this Session; submitting a Client Tool result also accepts the Turn of a call DevHub lists for the Session. Any other id answers 404 `not_found`.", "schema": { "type": "string" }}parameters/Limit
Section titled “parameters/Limit”{ "name": "limit", "in": "query", "required": false, "description": "The most items to return.", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }}parameters/Cursor
Section titled “parameters/Cursor”{ "name": "cursor", "in": "query", "required": false, "description": "A cursor this operation returned to you for the same Session; any other value answers 400 `invalid_request`.", "schema": { "type": "string" }}parameters/IdempotencyKey
Section titled “parameters/IdempotencyKey”{ "name": "Idempotency-Key", "in": "header", "required": true, "description": "Identifies one creation or input, so a repeated request cannot create a second Agent, Session or Turn input.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:-]{0,127}$" }}parameters/AgentId
Section titled “parameters/AgentId”{ "name": "agentId", "in": "path", "required": true, "description": "An Agent id from this API. Any id that is not one of the calling Developer's Agents answers 404 `not_found`.", "schema": { "type": "string" }}headers/ClientToolsETag
Section titled “headers/ClientToolsETag”{ "description": "Identifies the Client Tool set's revision; send it in `If-Match` to replace only that revision.", "schema": { "type": "string" }}securitySchemes/DevhubKey
Section titled “securitySchemes/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."}responses/AuthenticationRequired
Section titled “responses/AuthenticationRequired”{ "description": "The request carries no usable DevHub Key.", "headers": { "WWW-Authenticate": { "description": "Always `Bearer`.", "schema": { "type": "string", "const": "Bearer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "authentication_required", "message": "A valid DevHub Key is required." } } } }}responses/ServiceUnavailable
Section titled “responses/ServiceUnavailable”{ "description": "DevHub or the service behind it is temporarily unavailable; retry later. The DevHub Key was not refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }}responses/InvalidRequest
Section titled “responses/InvalidRequest”{ "description": "The request is malformed; `invalid_request`. Nothing was changed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }}responses/AgentNotFound
Section titled “responses/AgentNotFound”{ "description": "The id is not one of the calling Developer's Agents; `not_found`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }}responses/SessionNotFound
Section titled “responses/SessionNotFound”{ "description": "The id is not one of the calling Developer's Sessions; `not_found`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }}responses/TurnNotFound
Section titled “responses/TurnNotFound”{ "description": "The Session is not one of the calling Developer's, or the Turn is not one of its Turns; `not_found`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }}responses/AgentConflict
Section titled “responses/AgentConflict”{ "description": "`conflict`: another request is changing this Agent; retry when it has finished. `configuration_unavailable` (update only): the Agent's configuration references something no longer available, such as a Skill version, so the core refuses to save it until that is changed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }}schemas/Session
Section titled “schemas/Session”{ "type": "object", "additionalProperties": false, "required": [ "id", "agentId", "name", "autoTitle", "model", "realtimeModel", "activeTurnId", "readOnly", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string", "pattern": "^ses_[0-9a-f]{32}$" }, "agentId": { "type": "string", "pattern": "^agt_[0-9a-f]{32}$", "description": "The Agent the Session belongs to; it stays set after that Agent is deleted." }, "name": { "type": [ "string", "null" ], "description": "The name you gave the Session, if any." }, "autoTitle": { "type": [ "string", "null" ], "description": "A title the platform generated from the conversation, if any." }, "model": { "type": "string", "description": "The text model the Session's next Turn uses." }, "realtimeModel": { "type": [ "string", "null" ], "description": "The Realtime model of the Session's voice conversations; null without voice." }, "activeTurnId": { "type": [ "string", "null" ], "description": "The running Turn, if any." }, "readOnly": { "type": "boolean", "description": "The Session can be read but no longer changed or continued." }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }}schemas/SessionList
Section titled “schemas/SessionList”{ "type": "object", "additionalProperties": false, "required": [ "sessions", "nextCursor" ], "properties": { "sessions": { "type": "array", "items": { "$ref": "#/components/schemas/Session" } }, "nextCursor": { "type": [ "string", "null" ] } }}schemas/CreateSessionRequest
Section titled “schemas/CreateSessionRequest”{ "type": "object", "additionalProperties": false, "required": [ "agentId" ], "properties": { "agentId": { "type": "string", "pattern": "^agt_[0-9a-f]{32}$", "description": "One of your Agents." } }}schemas/RenameSessionRequest
Section titled “schemas/RenameSessionRequest”{ "type": "object", "additionalProperties": false, "required": [ "name" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 80, "description": "Surrounding whitespace is trimmed; control characters are refused." } }}schemas/Message
Section titled “schemas/Message”{ "type": "object", "additionalProperties": false, "required": [ "id", "role", "content", "createdAt" ], "properties": { "id": { "type": "string" }, "role": { "type": "string", "enum": [ "user", "assistant" ] }, "content": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" } }}schemas/Operation
Section titled “schemas/Operation”{ "description": "Work the Agent did during a Turn, such as a tool call.", "type": "object", "additionalProperties": false, "required": [ "id", "kind", "status", "category", "label", "createdAt", "completedAt" ], "properties": { "id": { "type": "string" }, "kind": { "type": "string" }, "status": { "type": "string", "description": "running, succeeded, failed, interrupted or unknown_result; more may be added." }, "category": { "type": [ "string", "null" ], "description": "`tool_call` or `skill_read` for a tool call; null for other work such as model calls." }, "label": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time" }, "completedAt": { "type": [ "string", "null" ], "format": "date-time" } }}schemas/Turn
Section titled “schemas/Turn”{ "type": "object", "additionalProperties": false, "if": { "required": [ "kind" ] }, "then": { "properties": { "userMessages": { "maxItems": 0 } } }, "required": [ "id", "sessionId", "status", "userMessages", "assistantMessage", "operations", "failure", "createdAt", "completedAt" ], "properties": { "id": { "type": "string" }, "sessionId": { "type": "string", "pattern": "^ses_[0-9a-f]{32}$" }, "status": { "type": "string", "enum": [ "running", "succeeded", "failed", "interrupted" ] }, "kind": { "type": "string", "enum": [ "template_handoff" ], "description": "The visible summary created while switching the Session to another AgentTemplate." }, "userMessages": { "type": "array", "description": "The input the Turn received, in order. Empty for a Template Handoff.", "items": { "$ref": "#/components/schemas/Message" } }, "assistantMessage": { "oneOf": [ { "$ref": "#/components/schemas/Message" }, { "type": "null" } ] }, "operations": { "type": "array", "items": { "$ref": "#/components/schemas/Operation" } }, "failure": { "description": "Why a failed Turn failed, when known.", "oneOf": [ { "$ref": "#/components/schemas/TurnFailure" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "completedAt": { "type": [ "string", "null" ], "format": "date-time" } }}schemas/TurnFailure
Section titled “schemas/TurnFailure”{ "type": "object", "additionalProperties": false, "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "A stable code, such as `model_provider_failed`." }, "message": { "type": "string" } }}schemas/RealtimeFact
Section titled “schemas/RealtimeFact”{ "description": "A final transcript of a voice conversation in the Session: what the user said (`input_transcript`) or what the voice model answered (`response`). `turnId` names the Turn it started or speaks about, if any.", "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "id", "type", "text", "turnId", "createdAt" ], "properties": { "id": { "type": "string" }, "type": { "type": "string", "const": "input_transcript" }, "text": { "type": "string" }, "turnId": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time" } } }, { "type": "object", "additionalProperties": false, "required": [ "id", "type", "kind", "text", "turnId", "interrupted", "createdAt" ], "properties": { "id": { "type": "string" }, "type": { "type": "string", "const": "response" }, "kind": { "type": "string", "description": "chat, task_ack, task_progress, task_result or clarify; more may be added." }, "text": { "type": "string" }, "turnId": { "type": [ "string", "null" ] }, "interrupted": { "type": "boolean", "description": "The answer was cut off; its text may include speech the user did not hear." }, "createdAt": { "type": "string", "format": "date-time" } } } ]}schemas/TimelineEntry
Section titled “schemas/TimelineEntry”{ "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "type", "turn" ], "properties": { "type": { "type": "string", "const": "turn" }, "turn": { "$ref": "#/components/schemas/Turn" } } }, { "type": "object", "additionalProperties": false, "required": [ "type", "realtime" ], "properties": { "type": { "type": "string", "const": "realtime" }, "realtime": { "$ref": "#/components/schemas/RealtimeFact" } } } ]}schemas/Timeline
Section titled “schemas/Timeline”{ "type": "object", "additionalProperties": false, "required": [ "entries", "nextCursor" ], "properties": { "entries": { "type": "array", "items": { "$ref": "#/components/schemas/TimelineEntry" } }, "nextCursor": { "type": [ "string", "null" ] } }}schemas/CreateTurnRequest
Section titled “schemas/CreateTurnRequest”{ "type": "object", "additionalProperties": false, "required": [ "input" ], "properties": { "input": { "type": "string", "minLength": 1, "description": "Text that is not only whitespace, at most 32 KiB in UTF-8." }, "fileIds": { "type": "array", "minItems": 1, "maxItems": 20, "uniqueItems": true, "description": "Files uploaded to this Session for the Agent to use in the Turn. A file uploaded with an `image/` content type is also shown to the model as an image, so the Session's model must accept images and the platform's image limits apply (at most 4 JPEG, PNG or static WebP images of up to 8 MiB each); otherwise the Turn fails with a `turn_error` that says why.", "items": { "type": "string", "pattern": "^file_[0-9a-f]{32}$" } } }}schemas/TurnSubmission
Section titled “schemas/TurnSubmission”{ "type": "object", "additionalProperties": false, "required": [ "turnId", "sessionId", "mode" ], "properties": { "turnId": { "type": "string", "description": "The Turn the input started or joined." }, "sessionId": { "type": "string", "pattern": "^ses_[0-9a-f]{32}$" }, "mode": { "type": "string", "enum": [ "started", "steered" ] } }}schemas/TurnCancellation
Section titled “schemas/TurnCancellation”{ "type": "object", "additionalProperties": false, "required": [ "turnId", "accepted" ], "properties": { "turnId": { "type": "string" }, "accepted": { "type": "boolean", "description": "True when the running Turn was asked to stop; false when it was not running." } }}schemas/SessionEvent
Section titled “schemas/SessionEvent”{ "description": "One Server-Sent Events `data` frame. Turn events carry the Turn's `event`, its per-Turn `seq` and a `payload`: `turn_started` {model} (type `agent.session.turn.started`); `progress` {text} (`agent.session.turn.progress`, a progress note, not answer text); `assistant_draft` {text} (`agent.session.turn.output_text.snapshot`, the complete draft so far: replace, do not append); `operation_step` {operationId, status, label, category} and `assistant_message` {messageId, text} (`agent.session.turn.item.added`; the latter is the saved answer); `turn_error` {code, message} (`agent.session.turn.failed`); `turn_finished` {status} (`agent.session.turn.completed`, `.failed` or `.cancelled`), the Turn's last event. Client Tool calls carry a `ClientToolCallsEvent` (`agent.session.turn.requires_action`). Voice transcripts carry a `RealtimeFact`. Ignore types you do not know.", "type": "object", "additionalProperties": false, "required": [ "type", "sessionId", "turnId", "createdAt", "data" ], "properties": { "type": { "type": "string", "enum": [ "agent.session.turn.started", "agent.session.turn.progress", "agent.session.turn.requires_action", "agent.session.turn.output_text.snapshot", "agent.session.turn.item.added", "agent.session.turn.failed", "agent.session.turn.completed", "agent.session.turn.cancelled", "agent.session.realtime.input_transcript.completed", "agent.session.realtime.response.completed" ] }, "sessionId": { "type": "string", "pattern": "^ses_[0-9a-f]{32}$" }, "turnId": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time" }, "data": { "oneOf": [ { "$ref": "#/components/schemas/TurnEvent" }, { "$ref": "#/components/schemas/ClientToolCallsEvent" }, { "$ref": "#/components/schemas/RealtimeFact" } ] } }}schemas/ClientToolCallsEvent
Section titled “schemas/ClientToolCallsEvent”{ "description": "The Client Tool calls the Agent made in one step of the Turn that DevHub took for your application. Answer each with `POST /api/v1/sessions/{sessionId}/turns/{turnId}/client-tool-results` before its `deadlineAt`. A call made while DevHub was not executing the Session, such as during a DevHub restart, is not shown, and the Agent is told that it was not performed.", "type": "object", "additionalProperties": false, "required": [ "event", "seq", "payload" ], "properties": { "event": { "type": "string", "const": "client_tool_calls" }, "seq": { "type": "integer", "minimum": 0 }, "payload": { "type": "object", "additionalProperties": false, "required": [ "calls" ], "properties": { "calls": { "type": "array", "items": { "$ref": "#/components/schemas/ClientToolCall" } } } } }}schemas/ClientToolCall
Section titled “schemas/ClientToolCall”{ "type": "object", "additionalProperties": false, "required": [ "callId", "name", "arguments", "deadlineAt" ], "properties": { "callId": { "type": "string", "description": "Identifies the call within its Turn; send it back with the result." }, "name": { "type": "string", "description": "The Client Tool the Agent called." }, "arguments": { "type": "object", "description": "Arguments for the tool's declared parameters." }, "deadlineAt": { "type": "string", "format": "date-time", "description": "The result must arrive before this time." } }}schemas/TurnEvent
Section titled “schemas/TurnEvent”{ "type": "object", "additionalProperties": false, "required": [ "event", "seq", "payload" ], "properties": { "event": { "type": "string", "enum": [ "turn_started", "progress", "assistant_draft", "operation_step", "assistant_message", "turn_error", "turn_finished" ] }, "seq": { "type": "integer", "minimum": 0 }, "payload": { "type": "object", "additionalProperties": false, "properties": { "model": { "type": [ "string", "null" ] }, "text": { "type": "string" }, "operationId": { "type": "string" }, "status": { "type": [ "string", "null" ] }, "label": { "type": [ "string", "null" ] }, "category": { "type": [ "string", "null" ] }, "messageId": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } }}schemas/File
Section titled “schemas/File”{ "description": "A file uploaded to a Session for its Turns.", "type": "object", "additionalProperties": false, "required": [ "id", "sessionId", "name", "contentType", "size", "sha256", "createdAt" ], "properties": { "id": { "type": "string", "pattern": "^file_[0-9a-f]{32}$" }, "sessionId": { "type": "string", "pattern": "^ses_[0-9a-f]{32}$", "description": "The only Session whose Turns can use the file." }, "name": { "type": "string" }, "contentType": { "type": [ "string", "null" ] }, "size": { "type": "integer", "minimum": 1, "description": "Bytes." }, "sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "Lowercase hexadecimal SHA-256 of the content." }, "createdAt": { "type": "string", "format": "date-time" } }}schemas/ClientTool
Section titled “schemas/ClientTool”{ "description": "A function your application executes for the Agent. The Agent sees the name, description and parameters as written.", "type": "object", "additionalProperties": false, "required": [ "type", "name", "description", "parameters" ], "properties": { "type": { "type": "string", "const": "function" }, "name": { "type": "string", "pattern": "^[a-zA-Z0-9_-]{1,64}$", "description": "Unique in the set and without `__`. Names of the platform's own tools and the `mcp_` and `device_` prefixes are reserved." }, "description": { "type": "string", "minLength": 1, "maxLength": 4096 }, "parameters": { "type": "object", "description": "A JSON Schema with `type: object`, at most 16 KiB and 16 levels deep. It may not define an `async` property: the platform adds that argument for the Agent to choose not to wait for the result, and never sends it to you." } }}schemas/ClientToolSet
Section titled “schemas/ClientToolSet”{ "type": "object", "additionalProperties": false, "required": [ "revision", "tools" ], "properties": { "revision": { "type": "integer", "minimum": 0, "description": "Increases with each replacement that changes the set; 0 before any." }, "tools": { "type": "array", "items": { "$ref": "#/components/schemas/ClientTool" } } }}schemas/ReplaceClientToolsRequest
Section titled “schemas/ReplaceClientToolsRequest”{ "type": "object", "additionalProperties": false, "required": [ "tools" ], "properties": { "tools": { "type": "array", "maxItems": 64, "description": "The whole new set, at most 64 KiB of JSON.", "items": { "$ref": "#/components/schemas/ClientTool" } } }}schemas/PendingClientToolCall
Section titled “schemas/PendingClientToolCall”{ "type": "object", "additionalProperties": false, "required": [ "turnId", "callId", "name", "arguments", "publishedAt", "deadlineAt" ], "properties": { "turnId": { "type": "string" }, "callId": { "type": "string" }, "name": { "type": "string" }, "arguments": { "type": "object" }, "publishedAt": { "type": "string", "format": "date-time" }, "deadlineAt": { "type": "string", "format": "date-time" } }}schemas/PendingClientToolCallList
Section titled “schemas/PendingClientToolCallList”{ "type": "object", "additionalProperties": false, "required": [ "calls" ], "properties": { "calls": { "type": "array", "items": { "$ref": "#/components/schemas/PendingClientToolCall" } } }}schemas/ClientToolResultRequest
Section titled “schemas/ClientToolResultRequest”{ "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "callId", "output" ], "properties": { "callId": { "type": "string", "minLength": 1, "maxLength": 64 }, "output": { "type": "string", "maxLength": 65536, "description": "What the tool returned, as text the Agent reads." } } }, { "type": "object", "additionalProperties": false, "required": [ "callId", "error" ], "properties": { "callId": { "type": "string", "minLength": 1, "maxLength": 64 }, "error": { "type": "object", "additionalProperties": false, "required": [ "message" ], "properties": { "message": { "type": "string", "minLength": 1, "maxLength": 4096, "description": "Why the tool failed, for the Agent." } } } } } ]}schemas/ClientToolResultReceipt
Section titled “schemas/ClientToolResultReceipt”{ "type": "object", "additionalProperties": false, "required": [ "turnId", "callId" ], "properties": { "turnId": { "type": "string" }, "callId": { "type": "string" } }}schemas/OfficialExample
Section titled “schemas/OfficialExample”{ "type": "object", "additionalProperties": false, "required": [ "id", "name", "description" ], "properties": { "id": { "type": "string", "description": "Pass as `exampleId` to create an Agent from this example." }, "name": { "type": "string" }, "description": { "type": "string" } }}schemas/OfficialExampleList
Section titled “schemas/OfficialExampleList”{ "type": "object", "additionalProperties": false, "required": [ "examples" ], "properties": { "examples": { "type": "array", "items": { "$ref": "#/components/schemas/OfficialExample" } } }}schemas/AgentSummary
Section titled “schemas/AgentSummary”{ "description": "An Agent as lists show it; read the Agent for its instructions.", "type": "object", "additionalProperties": false, "required": [ "id", "name", "description", "defaultModel", "defaultRealtimeModel", "exampleId", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string", "pattern": "^agt_[0-9a-f]{32}$" }, "name": { "type": "string" }, "description": { "type": "string" }, "defaultModel": { "type": [ "string", "null" ], "description": "The text model new Sessions of this Agent use; null uses the platform default." }, "defaultRealtimeModel": { "type": [ "string", "null" ], "description": "The Realtime model new Sessions use when the Agent has voice enabled; null uses the platform default. It has no effect while voice is off." }, "exampleId": { "type": [ "string", "null" ], "description": "The Official Example this Agent was copied from, if any." }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }}schemas/Agent
Section titled “schemas/Agent”{ "type": "object", "additionalProperties": false, "required": [ "id", "name", "description", "defaultModel", "defaultRealtimeModel", "exampleId", "instructions", "voice", "sessionRecall", "skills", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string", "pattern": "^agt_[0-9a-f]{32}$" }, "name": { "type": "string" }, "description": { "type": "string" }, "defaultModel": { "type": [ "string", "null" ], "description": "The text model new Sessions of this Agent use; null uses the platform default." }, "defaultRealtimeModel": { "type": [ "string", "null" ], "description": "The Realtime model new Sessions use when the Agent has voice enabled; null uses the platform default. It has no effect while voice is off." }, "exampleId": { "type": [ "string", "null" ], "description": "The Official Example this Agent was copied from, if any." }, "instructions": { "type": "string" }, "voice": { "$ref": "#/components/schemas/Voice" }, "sessionRecall": { "type": "boolean", "description": "Whether new Sessions can recall the Developer's earlier Sessions with this Agent." }, "skills": { "type": "array", "description": "The Official Skills this Agent uses, each at the version it selected.", "items": { "$ref": "#/components/schemas/SelectedSkill" } }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }}schemas/Voice
Section titled “schemas/Voice”{ "description": "Voice (Realtime) for new Sessions; null is voice off. Sessions with voice use the Agent's `defaultRealtimeModel`.", "type": [ "object", "null" ], "additionalProperties": false, "required": [ "language", "standingTask" ], "properties": { "language": { "type": "string", "enum": [ "zh-CN", "en-US" ] }, "standingTask": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 4000, "description": "A goal the Agent keeps working on while a voice client is connected and the conversation gives it nothing else to do; null for none. Line endings become LF and surrounding whitespace is trimmed." } }}schemas/SelectedSkill
Section titled “schemas/SelectedSkill”{ "type": "object", "additionalProperties": false, "required": [ "id", "version", "name" ], "properties": { "id": { "type": "string", "pattern": "^osk_[0-9a-f]{32}$" }, "version": { "type": "integer", "minimum": 1 }, "name": { "type": "string" } }}schemas/SkillSelection
Section titled “schemas/SkillSelection”{ "type": "object", "additionalProperties": false, "required": [ "id", "version" ], "properties": { "id": { "type": "string", "pattern": "^osk_[0-9a-f]{32}$" }, "version": { "type": "integer", "minimum": 1 } }}schemas/OfficialSkill
Section titled “schemas/OfficialSkill”{ "type": "object", "additionalProperties": false, "required": [ "id", "name", "description", "version" ], "properties": { "id": { "type": "string", "pattern": "^osk_[0-9a-f]{32}$" }, "name": { "type": "string" }, "description": { "type": "string" }, "version": { "type": "integer", "minimum": 1, "description": "The version an Agent can select." } }}schemas/OfficialSkillList
Section titled “schemas/OfficialSkillList”{ "type": "object", "additionalProperties": false, "required": [ "skills" ], "properties": { "skills": { "type": "array", "items": { "$ref": "#/components/schemas/OfficialSkill" } } }}schemas/AgentList
Section titled “schemas/AgentList”{ "type": "object", "additionalProperties": false, "required": [ "agents" ], "properties": { "agents": { "type": "array", "items": { "$ref": "#/components/schemas/AgentSummary" } } }}schemas/CreateAgentRequest
Section titled “schemas/CreateAgentRequest”{ "type": "object", "additionalProperties": false, "description": "`name` is required for a blank Agent. For a copy, absent `name` and `description` take the Official Example's, as `GET /api/v1/examples` lists them.", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Surrounding whitespace is trimmed; control characters are refused." }, "description": { "type": "string", "maxLength": 2000 }, "exampleId": { "type": [ "string", "null" ], "description": "An Official Example id to copy; absent or null creates a blank Agent." } }}schemas/UpdateAgentRequest
Section titled “schemas/UpdateAgentRequest”{ "type": "object", "additionalProperties": false, "minProperties": 1, "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Surrounding whitespace is trimmed; control characters are refused." }, "description": { "type": "string", "maxLength": 2000 }, "instructions": { "type": "string", "description": "Line endings become LF and surrounding whitespace is trimmed; at most 16 KiB in UTF-8." }, "defaultModel": { "type": [ "string", "null" ], "pattern": "^[!-~]{1,128}$", "description": "A model id for new Sessions; null returns to the platform default. Availability is checked when a Session is created." }, "defaultRealtimeModel": { "type": [ "string", "null" ], "pattern": "^[!-~]{1,128}$", "description": "A Realtime model id for new voice Sessions; null returns to the platform default. Availability is checked when a Session is created." }, "voice": { "$ref": "#/components/schemas/Voice" }, "sessionRecall": { "type": "boolean" }, "skills": { "type": "array", "maxItems": 100, "description": "The complete selection, each Official Skill at most once. Together with any Skills a copied Official Example brought that are not Official Skills, which the Agent keeps, an Agent has at most 100 Skills.", "items": { "$ref": "#/components/schemas/SkillSelection" } } }}schemas/Model
Section titled “schemas/Model”{ "type": "object", "additionalProperties": false, "required": [ "id", "label", "available" ], "properties": { "id": { "type": "string", "description": "The id to set as an Agent's default model." }, "label": { "type": "string", "description": "A display name." }, "available": { "type": "boolean", "description": "Whether the platform can serve it now." } }}schemas/RealtimeModel
Section titled “schemas/RealtimeModel”{ "type": "object", "additionalProperties": false, "required": [ "id", "label", "available", "languages" ], "properties": { "id": { "type": "string", "description": "The id to set as an Agent's default Realtime model." }, "label": { "type": "string", "description": "A display name." }, "available": { "type": "boolean", "description": "Whether the platform can serve it now." }, "languages": { "type": "array", "description": "The voice languages it serves.", "items": { "type": "string", "enum": [ "zh-CN", "en-US" ] } } }}schemas/ModelCatalog
Section titled “schemas/ModelCatalog”{ "type": "object", "additionalProperties": false, "required": [ "defaultModel", "models", "defaultRealtimeModel", "realtimeModels" ], "properties": { "defaultModel": { "type": "string", "description": "The platform's suggested text model, which new Sessions normally use when the Agent's `defaultModel` is null." }, "models": { "type": "array", "description": "Text models.", "items": { "$ref": "#/components/schemas/Model" } }, "defaultRealtimeModel": { "type": [ "string", "null" ], "description": "The Realtime model voice Sessions use when the Agent's `defaultRealtimeModel` is null; null when the platform has none." }, "realtimeModels": { "type": "array", "description": "Realtime models.", "items": { "$ref": "#/components/schemas/RealtimeModel" } } }}schemas/Me
Section titled “schemas/Me”{ "type": "object", "additionalProperties": false, "required": [ "developerId" ], "properties": { "developerId": { "type": "string", "pattern": "^dev_[0-9a-f]{32}$", "description": "The Developer's DevHub id." } }}schemas/ErrorEnvelope
Section titled “schemas/ErrorEnvelope”{ "type": "object", "additionalProperties": false, "required": [ "error" ], "properties": { "error": { "type": "object", "additionalProperties": false, "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Stable machine-readable code; clients branch on this, not on the message.", "enum": [ "authentication_required", "not_found", "invalid_request", "idempotency_key_reused", "conflict", "session_has_active_turn", "session_read_only", "configuration_unavailable", "client_tool_call_settled", "precondition_failed", "file_too_large", "credits_exhausted", "credits_unavailable", "service_unavailable", "internal_error" ] }, "message": { "type": "string", "description": "Human-readable explanation; may change." }, "resetsAt": { "type": "string", "format": "date-time", "description": "Only with `credits_exhausted`; when your Credits reset." } } } }}