跳转到内容

API 参考

Organization 与 End User API 参考。接口字段来自客户规范,规范中的描述保留原文。

下载 OpenAPI · 数据结构

{
"OrganizationApiKey": {
"scheme": "bearer",
"bearerFormat": "opaque",
"type": "http",
"description": "Opaque ti_org_<id>_<secret> credential: ASCII alphanumeric id body (1–64), unpadded base64url secret (43 characters from 32 random bytes). Authenticates an Organization machine principal with no acting User. Each handler explicitly chooses whether to admit this principal kind."
},
"UserApiKey": {
"scheme": "bearer",
"bearerFormat": "opaque",
"type": "http",
"description": "Opaque ti_user_<id>_<secret> credential: ASCII alphanumeric id body (1–64), unpadded base64url secret (43 characters from 32 random bytes). Authenticates the bound User and Organization. The persisted key owner determines scope."
}
}

GET /api/v1/org/users/{userId}/realtime-models

Section titled “GET /api/v1/org/users/{userId}/realtime-models”

Authorization: OrganizationApiKey; persisted credentials determine Organization and End User scope.

OrganizationRealtimeModelsController_list

[
{
"OrganizationApiKey": []
}
]
[
{
"name": "userId",
"required": true,
"in": "path",
"schema": {
"type": "string"
}
}
]
{
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RealtimeModelsResponseOpenApiDto"
}
}
}
},
"401": {
"description": "authentication_required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "auth_kind_forbidden: an Organization API Key is required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"404": {
"description": "The ordinary target End User is unavailable.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"503": {
"description": "Realtime model configuration is unavailable.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}

Authorization: UserApiKey; persisted credentials determine Organization and End User scope.

PublishedTemplateSummariesController_list

[
{
"UserApiKey": []
}
]
[
{
"name": "cursor",
"required": false,
"in": "query",
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 4096
}
},
{
"name": "limit",
"required": false,
"in": "query",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 200,
"default": 100
}
}
]
{
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublishedTemplateSummariesDto"
}
}
},
"headers": {
"Cache-Control": {
"schema": {
"type": "string",
"example": "no-store"
}
}
}
},
"400": {
"description": "The request is invalid.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"401": {
"description": "User Key authentication is required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "A current End User Key is required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"404": {
"description": "The selected End User or Template was not found.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}

GET /api/v1/org/users/{userId}/agent-templates

Section titled “GET /api/v1/org/users/{userId}/agent-templates”

Authorization: OrganizationApiKey; persisted credentials determine Organization and End User scope.

OrganizationPublishedTemplateSummariesController_list

[
{
"OrganizationApiKey": []
}
]
[
{
"name": "userId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "cursor",
"required": false,
"in": "query",
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 4096
}
},
{
"name": "limit",
"required": false,
"in": "query",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 200,
"default": 100
}
}
]
{
"200": {
"headers": {
"Cache-Control": {
"schema": {
"type": "string",
"example": "no-store"
}
}
},
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublishedTemplateSummariesDto"
}
}
}
},
"400": {
"description": "The request is invalid.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"401": {
"description": "User Key authentication is required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "A current End User Key is required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"404": {
"description": "The selected End User or Template was not found.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}

GET /api/v1/org/users/{userId}/agent-models

Section titled “GET /api/v1/org/users/{userId}/agent-models”

List selectable Agent Models.

Authorization: OrganizationApiKey; persisted credentials determine Organization and End User scope.

OrganizationAgentModelsController_list

[
{
"OrganizationApiKey": []
}
]
[
{
"name": "userId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
]
{
"200": {
"description": "Canonical ordered Agent Model catalog and create-time default.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AgentModelsResponseOpenApiDto"
}
}
}
},
"401": {
"description": "User Key authentication is required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "A User Key principal is required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"404": {
"description": "The selected End User was not found.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"503": {
"description": "The Organization model policy or active End User is unavailable.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}

Authorization: UserApiKey; persisted credentials determine Organization and End User scope.

SessionsController_getTools

[
{
"UserApiKey": []
}
]
[
{
"name": "id",
"required": true,
"in": "path",
"schema": {
"type": "string"
}
}
]
{
"200": {
"description": "The Session client-declared Client Tool set and its revision.",
"headers": {
"ETag": {
"description": "Strong ETag of the Session Client Tool set revision.",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SessionClientToolsResponseOpenApiDto"
}
}
}
},
"401": {
"description": "Authentication is required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "An active End User principal is required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"404": {
"description": "The Session is unavailable or authorization-hidden.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}

Authorization: UserApiKey; persisted credentials determine Organization and End User scope.

SessionsController_replaceTools

[
{
"UserApiKey": []
}
]
[
{
"name": "id",
"required": true,
"in": "path",
"schema": {
"type": "string"
}
},
{
"name": "If-Match",
"in": "header",
"description": "Exact Client Tool set ETag from the latest tools response.",
"required": true,
"schema": {
"type": "string"
}
}
]
{
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ReplaceSessionToolsOpenApiDto"
}
}
}
}
{
"200": {
"description": "The replaced Client Tool set. An identical set keeps its revision.",
"headers": {
"ETag": {
"description": "Strong ETag of the Session Client Tool set revision.",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SessionClientToolsResponseOpenApiDto"
}
}
}
},
"400": {
"description": "The Client Tool declarations are invalid.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"401": {
"description": "Authentication is required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "An active End User principal is required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"404": {
"description": "The Session is unavailable or authorization-hidden.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"409": {
"description": "The Session is read-only (session_read_only).",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"412": {
"description": "The supplied Client Tool set ETag is stale.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"428": {
"description": "If-Match is required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}

Authorization: UserApiKey; persisted credentials determine Organization and End User scope.

SessionsController_list

[
{
"UserApiKey": []
}
]
[
{
"name": "agentTemplateId",
"required": false,
"in": "query",
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 64
},
"description": "Select Sessions whose current Configuration Epoch uses this AgentTemplate."
},
{
"name": "cursor",
"required": false,
"in": "query",
"description": "Opaque continuation cursor bound to the owner and Template filter.",
"schema": {
"type": "string"
}
},
{
"name": "limit",
"required": false,
"in": "query",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 200,
"default": 50
}
}
]
{
"200": {
"description": "The authenticated End User’s Sessions in descending creation-time and Session-ID order. Display and activity changes do not move the continuation position.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SessionsResponseOpenApiDto"
}
}
}
},
"400": {
"description": "Invalid query or cursor, including another owner or list kind.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"401": {
"description": "Authentication is required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "An active End User principal is required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}

Authorization: UserApiKey; persisted credentials determine Organization and End User scope.

SessionsController_create

[
{
"UserApiKey": []
}
]
[
{
"name": "Idempotency-Key",
"in": "header",
"required": true,
"schema": {
"type": "string",
"pattern": "^[A-Za-z0-9][A-Za-z0-9_.:-]{0,127}$",
"maxLength": 128
}
}
]
{
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateTemplateSessionOpenApiDto"
}
}
}
}
{
"201": {
"description": "Created Session.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SessionResponseOpenApiDto"
}
}
},
"headers": {
"ETag": {
"description": "Opaque Session model revision token. Model changes apply to the next Turn. It does not version live `realtime` presence.",
"required": true,
"schema": {
"type": "string"
}
}
}
},
"400": {
"description": "The Session input or required Idempotency-Key is invalid.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"401": {
"description": "Authentication is required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "An active End User principal is required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"404": {
"description": "The selected active Template or its dependencies are unavailable or authorization-hidden.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"409": {
"description": "The Idempotency-Key conflicts, cross-Session Recall requires acknowledgment (agent_template_recall_acknowledgment_required), the model provider is unconfigured, the Realtime Model is unavailable (realtime_model_unavailable), Realtime is disabled (realtime_not_enabled), or combined instructions exceed 16 KiB (agent_instructions_too_large).",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"503": {
"description": "skill_package_store_unavailable: required Skill package storage is temporarily unavailable.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"default": {
"$ref": "#/components/responses/Error"
}
}

Authorization: UserApiKey; persisted credentials determine Organization and End User scope.

SessionsController_get

[
{
"UserApiKey": []
}
]
[
{
"name": "id",
"required": true,
"in": "path",
"schema": {
"type": "string"
}
}
]
{
"200": {
"description": "Session.",
"headers": {
"ETag": {
"description": "Opaque Session model revision token. Model changes apply to the next Turn. It does not version live `realtime` presence.",
"required": true,
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SessionResponseOpenApiDto"
}
}
}
},
"401": {
"description": "Authentication is required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "An active End User principal is required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"404": {
"description": "The Session is unavailable or authorization-hidden.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}

Authorization: UserApiKey; persisted credentials determine Organization and End User scope.

SessionsController_delete

[
{
"UserApiKey": []
}
]
[
{
"$ref": "#/components/parameters/IdPath"
}
]
{
"200": {
"description": "Deleted Session tombstone.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SessionResponseOpenApiDto"
}
}
}
},
"401": {
"description": "Authentication is required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "An active End User principal is required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"404": {
"description": "The Session is unavailable or authorization-hidden.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"409": {
"description": "The Session is read-only or still has an active Turn.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"default": {
"$ref": "#/components/responses/Error"
}
}

Authorization: UserApiKey; persisted credentials determine Organization and End User scope.

SessionsController_updateModel

[
{
"UserApiKey": []
}
]
[
{
"$ref": "#/components/parameters/IdPath"
},
{
"name": "If-Match",
"in": "header",
"description": "Exact Session model ETag from the latest Session response.",
"required": true,
"schema": {
"type": "string"
}
}
]
{
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UpdateSessionModelOpenApiDto"
}
}
}
}
{
"200": {
"description": "Updated Session model. An active Turn retains its admitted model; the next Turn uses this selection.",
"headers": {
"ETag": {
"description": "Opaque Session model revision token. Model changes apply to the next Turn. It does not version live `realtime` presence.",
"required": true,
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SessionResponseOpenApiDto"
}
}
}
},
"400": {
"description": "validation_error or session_model_not_allowed.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"401": {
"description": "Missing or invalid User API Key.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "The principal or Organization is not authorized.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"404": {
"description": "session_not_found.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"409": {
"description": "model_provider_unconfigured or session_read_only.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"412": {
"description": "The supplied Session model ETag is stale.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"428": {
"description": "If-Match is required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}

PATCH /api/v1/user/sessions/{id}/realtime-model

Section titled “PATCH /api/v1/user/sessions/{id}/realtime-model”

Authorization: UserApiKey; persisted credentials determine Organization and End User scope.

SessionsController_updateRealtimeModel

[
{
"UserApiKey": []
}
]
[
{
"name": "id",
"required": true,
"in": "path",
"schema": {
"type": "string"
}
},
{
"name": "If-Match",
"in": "header",
"description": "The realtimeModelEtag from the latest Session response.",
"required": true,
"schema": {
"type": "string"
}
}
]
{
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UpdateSessionRealtimeModelOpenApiDto"
}
}
}
}
{
"200": {
"description": "Updated selection for the next Realtime Connection. A live connection retains its admitted model.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SessionResponseOpenApiDto"
}
}
}
},
"400": {
"description": "validation_error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"401": {
"description": "Missing or invalid User API Key.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "A User API Key is required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"404": {
"description": "session_not_found.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"409": {
"description": "realtime_model_unavailable, realtime_not_enabled or session_read_only.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"412": {
"description": "realtime_model_conflict: the supplied selection revision is stale.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"428": {
"description": "precondition_required: If-Match is required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}

PATCH /api/v1/user/sessions/{id}/billing-tag

Section titled “PATCH /api/v1/user/sessions/{id}/billing-tag”

Authorization: UserApiKey; persisted credentials determine Organization and End User scope.

SessionsController_updateBillingTag

[
{
"UserApiKey": []
}
]
[
{
"$ref": "#/components/parameters/IdPath"
}
]
{
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UpdateSessionBillingTagOpenApiDto"
}
}
}
}
{
"200": {
"description": "Updated Session billing tag.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SessionResponseOpenApiDto"
}
}
}
},
"400": {
"description": "The Billing Tag is malformed or incomplete.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"401": {
"description": "Authentication is required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "An active End User principal is required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"404": {
"description": "The Session is unavailable or authorization-hidden.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"409": {
"description": "The Session is read-only.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}

Authorization: UserApiKey; persisted credentials determine Organization and End User scope.

SessionsController_rename

[
{
"UserApiKey": []
}
]
[
{
"name": "id",
"required": true,
"in": "path",
"schema": {
"type": "string"
}
}
]
{
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RenameSessionOpenApiDto"
}
}
}
}
{
"201": {
"description": "Session.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SessionResponseOpenApiDto"
}
}
}
},
"400": {
"description": "The Session name is empty, too long, or otherwise invalid.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"401": {
"description": "Authentication is required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "An active End User principal is required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"404": {
"description": "The Session is unavailable or authorization-hidden.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"409": {
"description": "The Session is read-only.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"default": {
"$ref": "#/components/responses/Error"
}
}

POST /api/v1/user/sessions/{id}/name/suggest

Section titled “POST /api/v1/user/sessions/{id}/name/suggest”

Authorization: UserApiKey; persisted credentials determine Organization and End User scope.

SessionsController_suggestName

[
{
"UserApiKey": []
}
]
[
{
"$ref": "#/components/parameters/IdPath"
}
]
{
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SuggestSessionNameOpenApiDto"
}
}
}
}
{
"201": {
"description": "Suggested name and updated Session.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SuggestSessionNameResponseOpenApiDto"
}
}
}
},
"400": {
"description": "The source exchange used for naming is invalid.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"401": {
"description": "Authentication is required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "An active End User principal is required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"404": {
"description": "The Session is unavailable or authorization-hidden.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"409": {
"description": "The selected model configuration or command authority is unavailable, or the Session is read-only (session_read_only).",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"default": {
"$ref": "#/components/responses/Error"
}
}

Authorization: UserApiKey; persisted credentials determine Organization and End User scope.

SessionsController_uploadFile

[
{
"UserApiKey": []
}
]
[
{
"$ref": "#/components/parameters/IdPath"
}
]
{
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UploadSessionFileOpenApiDto"
}
}
}
}
{
"201": {
"description": "Created Session Drive file.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UploadSessionFileResponseOpenApiDto"
}
}
}
},
"409": {
"description": "The Session is read-only (session_read_only).",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"default": {
"$ref": "#/components/responses/Error"
}
}

POST /api/v1/user/sessions/{id}/files/batch

Section titled “POST /api/v1/user/sessions/{id}/files/batch”

Authorization: UserApiKey; persisted credentials determine Organization and End User scope.

SessionsController_uploadFiles

[
{
"UserApiKey": []
}
]
[
{
"$ref": "#/components/parameters/IdPath"
}
]
{
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UploadSessionFilesOpenApiDto"
}
}
}
}
{
"201": {
"description": "Created Session Drive files.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UploadSessionFilesResponseOpenApiDto"
}
}
}
},
"409": {
"description": "A target path already contains different content.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"default": {
"$ref": "#/components/responses/Error"
}
}

Authorization: UserApiKey; persisted credentials determine Organization and End User scope.

SessionsController_submitEvent

[
{
"UserApiKey": []
}
]
[
{
"name": "id",
"required": true,
"in": "path",
"schema": {
"type": "string"
}
}
]
{
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SessionEventOpenApiDto"
}
}
}
}
{
"200": {
"description": "An idempotent replay of an already accepted command.",
"content": {
"application/json": {
"schema": {
"oneOf": [
{
"$ref": "#/components/schemas/SessionInteractionResponseOpenApiDto"
},
{
"$ref": "#/components/schemas/SessionEventRetryResponseOpenApiDto"
}
]
}
}
}
},
"202": {
"description": "The command was accepted. Message and cancellation commands return durable interaction receipts; retry commands return a retrying event receipt. Read execution progress and results through Turn reads, or follow the Session over a Backend Connection.",
"content": {
"application/json": {
"schema": {
"oneOf": [
{
"$ref": "#/components/schemas/SessionInteractionResponseOpenApiDto"
},
{
"$ref": "#/components/schemas/SessionEventRetryResponseOpenApiDto"
}
]
}
}
}
},
"400": {
"description": "The command envelope or command data is invalid, or an idle text Turn admission exceeds the Client Tool limit after model projection (64 tools or 64 KiB; validation_failed). Admission saves no input or Turn on this overflow. New checkpoint retries are disabled by default and return checkpoint_runtime_unavailable when disabled or unavailable; previously accepted retry commands still recover their receipts.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"401": {
"description": "Authentication is required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "An active End User principal is required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"404": {
"description": "The Session is unavailable or authorization-hidden.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"409": {
"description": "The command identity was already used with a different body or target state, a new message or retry targets a read-only Session (session_read_only), a checkpoint retry targets an earlier Session Configuration Epoch (session_configuration_epoch_changed), or a Session Template switch is in progress (session_switch_in_progress). A Turn start is refused when an MCP Server Registration the Session references is disabled or deleted (session_execution_dependency_unavailable), or when an MCP Authorization it needs is not usable (mcp_authorization_required): details.registrations lists each such registration with its serverId, owner (organization or end_user) and reason (missing, invalid, revoked or insufficient_scope). Only a message that would start a new Turn is checked, never one steered into a running Turn. Nothing is saved, so the same clientEventId can be sent again once the authorization is usable.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"503": {
"description": "New Turn admission is temporarily closed for deployment maintenance or recovery (turn_admission_closed), or the deployment lacks the Sandbox or Drive9 service a new Turn needs (service_configuration_unavailable; details.reason names it). This refusal happens before the command is saved, so the same clientEventId can be sent again once the service is set up. If the configuration changes after that check, the command is accepted instead and its Turn fails with the same code and reason in turn_error. A model the deployment does not configure keeps its 409 model_provider_unconfigured refusal.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
},
"example": {
"error": {
"code": "turn_admission_closed",
"message": "New Turns are temporarily unavailable"
}
}
}
}
}
}

GET /api/v1/user/sessions/{id}/interactions

Section titled “GET /api/v1/user/sessions/{id}/interactions”

Authorization: UserApiKey; persisted credentials determine Organization and End User scope.

SessionsController_listInteractions

[
{
"UserApiKey": []
}
]
[
{
"name": "id",
"required": true,
"in": "path",
"schema": {
"type": "string"
}
},
{
"name": "cursor",
"required": false,
"in": "query",
"description": "Opaque Session-bound continuation cursor.",
"schema": {
"type": "string"
}
},
{
"name": "limit",
"required": false,
"in": "query",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 200,
"default": 50
}
},
{
"name": "clientEventId",
"required": false,
"in": "query",
"description": "Read only the original command receipt, including checkpoint retry. Cannot be combined with limit or cursor; a missing key returns an empty page. No execution is started.",
"schema": {
"type": "string"
}
}
]
{
"200": {
"description": "Saved commands in ascending Session-local sequence, or the exact original command-key receipt without executing again.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SessionInteractionsResponseOpenApiDto"
}
}
}
},
"400": {
"description": "Invalid limit or malformed, negative or different-Session continuation cursor.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"default": {
"description": "Unavailable owning Session or unsupported, invalid or unavailable credentials.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}

GET /api/v1/user/sessions/{id}/interactions/{receiptId}

Section titled “GET /api/v1/user/sessions/{id}/interactions/{receiptId}”

Authorization: UserApiKey; persisted credentials determine Organization and End User scope.

SessionsController_getInteraction

[
{
"UserApiKey": []
}
]
[
{
"name": "id",
"required": true,
"in": "path",
"schema": {
"type": "string"
}
},
{
"name": "receiptId",
"required": true,
"in": "path",
"schema": {
"type": "string"
}
}
]
{
"200": {
"description": "Original input receipt and original-generation outcome, including saved refusals.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SessionInteractionResponseOpenApiDto"
}
}
}
},
"404": {
"description": "Unrecorded input or unavailable owning Session.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"default": {
"description": "Unsupported, invalid or unavailable caller credentials.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}

POST /api/v1/user/sessions/{id}/turns/audio

Section titled “POST /api/v1/user/sessions/{id}/turns/audio”

Authorization: UserApiKey; persisted credentials determine Organization and End User scope.

SessionsController_createAudioTurn

[
{
"UserApiKey": []
}
]
[
{
"name": "id",
"required": true,
"in": "path",
"schema": {
"type": "string"
}
}
]
{
"required": true,
"content": {
"multipart/form-data": {
"schema": {
"type": "object",
"required": [
"file"
],
"properties": {
"file": {
"type": "string",
"format": "binary",
"description": "Audio file to transcribe. Supported formats: mp3, mp4, mpeg, mpga, m4a, wav, webm."
},
"billingTag": {
"nullable": true,
"description": "Omit to inherit the Session default, send one JSON Billing Tag object to override it, or send the JSON literal null to clear it for this Turn.",
"allOf": [
{
"$ref": "#/components/schemas/BillingTag"
}
]
}
}
},
"encoding": {
"billingTag": {
"contentType": "application/json"
}
}
}
}
}
{
"201": {
"description": "Audio Turn outside ordinary JSON text input identity/recovery guarantees. The owning response uses SSE frames whose event name and JSON data identify the TurnStreamEvent, with comment keepalives; turn_started may omit inputId. Closing its active upstream requests interruption. Cancel an owned live Turn through POST events with a stable clientEventId and its exact turnId. The transcript is the Turn input, so the Turn freezes the Session Client Tool set as a text Turn does. Its client_tool_calls frames carry claimBy: only the Session’s executing Backend Connection attachment executes and answers them; a call published while the Session has none is not performed and gets no frame.",
"content": {
"text/event-stream": {
"schema": {
"type": "string",
"description": "Each SSE frame contains event: <TurnStreamEvent.event> and data: <TurnStreamEvent JSON>, terminated by a blank line. Comment frames are keepalive heartbeats.",
"x-sse-event-schema": {
"$ref": "#/components/schemas/TurnStreamEvent"
}
}
}
},
"headers": {
"Cache-Control": {
"required": true,
"schema": {
"type": "string",
"enum": [
"no-cache, no-transform"
]
}
},
"X-Accel-Buffering": {
"required": true,
"schema": {
"type": "string",
"enum": [
"no"
]
}
}
}
},
"400": {
"description": "validation_error: the upload is invalid, the transcript is empty, or the Session Client Tool set exceeds 64 tools or 64 KiB after model projection. The tool-set check runs at Turn admission, after transcription; transcription usage remains billed and no Turn is saved.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"409": {
"description": "The Session is read-only (session_read_only), a Template switch is in progress (session_switch_in_progress), or it already has an active Turn (session_has_active_turn), either before transcription or reservation, or because another Turn starts during transcription. A switch that changes the Configuration Epoch during transcription returns session_configuration_epoch_changed. Conflicts after accepted transcription retain ASR usage under the original Template. A Turn start is refused when an MCP Server Registration the Session references is disabled or deleted (session_execution_dependency_unavailable), or when an MCP Authorization it needs is not usable (mcp_authorization_required): details.registrations lists each such registration with its serverId, owner (organization or end_user) and reason (missing, invalid, revoked or insufficient_scope). The check runs before the upload is read, transcribed or billed. A registration or authorization that becomes unusable during transcription is refused the same way after it: ASR usage stays billed, and the Turn the transcript began reads as failed with the same failure.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"501": {
"description": "Audio transcription is disabled because ASR_OPENAI_API_KEY is not configured.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"503": {
"description": "New Turn admission is temporarily closed for deployment maintenance or recovery (turn_admission_closed), or the deployment lacks the Sandbox or Drive9 service a new Turn needs (service_configuration_unavailable; details.reason names it). Normally this refusal happens before the audio is read, transcribed or billed and before anything is saved. If the configuration changes concurrently, the same 503 can follow transcription; that transcription remains billed and no Turn is saved.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
},
"example": {
"error": {
"code": "turn_admission_closed",
"message": "New Turns are temporarily unavailable"
}
}
}
}
},
"default": {
"$ref": "#/components/responses/Error"
}
}

Authorization: UserApiKey; persisted credentials determine Organization and End User scope.

SessionsController_timeline

[
{
"UserApiKey": []
}
]
[
{
"name": "id",
"required": true,
"in": "path",
"schema": {
"type": "string"
}
},
{
"name": "cursor",
"required": false,
"in": "query",
"description": "Opaque owning User and Session continuation cursor from nextCursor.",
"schema": {
"type": "string"
}
},
{
"name": "limit",
"required": false,
"in": "query",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 200,
"default": 50
}
}
]
{
"200": {
"description": "A bounded page of the Session timeline. Each entry is a complete Turn, one Realtime fact, or one successful Template-switch fact with epoch and Template provenance. Failed switches remain stream-only. Facts follow durable write order. A Turn started by a Realtime utterance is placed directly after that utterance; every other Turn sits where its first event was saved. Key entries by their stable id and replace an entry that arrives again. A running Turn is a snapshot of its progress so far; read it again for later changes.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SessionTimelineResponseOpenApiDto"
}
}
}
},
"400": {
"description": "Invalid limit, or a malformed, foreign or unknown continuation cursor.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"default": {
"$ref": "#/components/responses/Error",
"description": "Unavailable owning Session or unsupported, invalid or unavailable credentials.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}

Authorization: UserApiKey; persisted credentials determine Organization and End User scope.

SessionsController_listTurns

[
{
"UserApiKey": []
}
]
[
{
"$ref": "#/components/parameters/IdPath"
},
{
"name": "cursor",
"required": false,
"in": "query",
"description": "Opaque owning User and Session continuation cursor; chronological creation order with Turn ID as tie breaker.",
"schema": {
"type": "string"
}
},
{
"name": "limit",
"required": false,
"in": "query",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 200,
"default": 50
}
}
]
{
"200": {
"description": "Full Agent and Realtime Turns in creation-time order. Late Realtime writes before an already consumed cursor require a full refresh; use /timeline for durable event-sequence replay.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TurnsResponseOpenApiDto"
}
}
}
},
"400": {
"description": "Invalid query or cursor, including another owner, Session or list kind.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"default": {
"$ref": "#/components/responses/Error",
"description": "Unavailable owning Session or unsupported, invalid or unavailable credentials.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}

GET /api/v1/user/sessions/{id}/turns/{turnId}

Section titled “GET /api/v1/user/sessions/{id}/turns/{turnId}”

Authorization: UserApiKey; persisted credentials determine Organization and End User scope.

SessionsController_getTurn

[
{
"UserApiKey": []
}
]
[
{
"$ref": "#/components/parameters/IdPath"
},
{
"$ref": "#/components/parameters/TurnIdPath"
}
]
{
"200": {
"description": "One Full Agent or user-input Realtime Turn.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TurnResponse"
}
}
}
},
"404": {
"description": "Unavailable Session, unknown Turn or narration-only Realtime Turn.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"default": {
"$ref": "#/components/responses/Error"
}
}

POST /api/v1/org/users/{userId}/sessions/{id}/turns/audio

Section titled “POST /api/v1/org/users/{userId}/sessions/{id}/turns/audio”

Authorization: OrganizationApiKey; persisted credentials determine Organization and End User scope.

SessionsController_organizationCreateAudioTurn

[
{
"OrganizationApiKey": []
}
]
[
{
"name": "userId",
"required": true,
"in": "path",
"schema": {
"type": "string"
}
},
{
"name": "id",
"required": true,
"in": "path",
"schema": {
"type": "string"
}
}
]
{
"required": true,
"content": {
"multipart/form-data": {
"schema": {
"type": "object",
"required": [
"file"
],
"properties": {
"file": {
"type": "string",
"format": "binary",
"description": "Audio file to transcribe. Supported formats: mp3, mp4, mpeg, mpga, m4a, wav, webm."
},
"billingTag": {
"nullable": true,
"description": "Omit to inherit the Session default, send one JSON Billing Tag object to override it, or send the JSON literal null to clear it for this Turn.",
"allOf": [
{
"$ref": "#/components/schemas/BillingTag"
}
]
}
}
},
"encoding": {
"billingTag": {
"contentType": "application/json"
}
}
}
}
}
{
"201": {
"description": "Audio Turn outside ordinary JSON text input identity/recovery guarantees. The owning response uses SSE frames whose event name and JSON data identify the TurnStreamEvent, with comment keepalives; turn_started may omit inputId. An ordinary upstream disconnect requests interruption. Rotation or revocation closes this response without canceling an accepted Turn; recover its result using fresh authority. Cancel an owned live Turn through POST events with a stable clientEventId and its exact turnId. The transcript is the Turn input, so the Turn freezes the Session Client Tool set as a text Turn does. Its client_tool_calls frames carry claimBy: only the Session’s executing Backend Connection attachment executes and answers them; a call published while the Session has none is not performed and gets no frame.",
"headers": {
"Cache-Control": {
"required": true,
"schema": {
"type": "string",
"enum": [
"no-cache, no-transform"
]
}
},
"X-Accel-Buffering": {
"required": true,
"schema": {
"type": "string",
"enum": [
"no"
]
}
}
},
"content": {
"text/event-stream": {
"schema": {
"type": "string",
"description": "Each SSE frame contains event: <TurnStreamEvent.event> and data: <TurnStreamEvent JSON>, terminated by a blank line. Comment frames are keepalive heartbeats.",
"x-sse-event-schema": {
"$ref": "#/components/schemas/TurnStreamEvent"
}
}
}
}
},
"400": {
"description": "validation_error: the upload is invalid, the transcript is empty, or the Session Client Tool set exceeds 64 tools or 64 KiB after model projection. The tool-set check runs at Turn admission, after transcription; transcription usage remains billed and no Turn is saved.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"409": {
"description": "The Session is read-only (session_read_only), a Template switch is in progress (session_switch_in_progress), or it already has an active Turn (session_has_active_turn), either before transcription or reservation, or because another Turn starts during transcription. A switch that changes the Configuration Epoch during transcription returns session_configuration_epoch_changed. Conflicts after accepted transcription retain ASR usage under the original Template. A Turn start is refused when an MCP Server Registration the Session references is disabled or deleted (session_execution_dependency_unavailable), or when an MCP Authorization it needs is not usable (mcp_authorization_required): details.registrations lists each such registration with its serverId, owner (organization or end_user) and reason (missing, invalid, revoked or insufficient_scope). The check runs before the upload is read, transcribed or billed. A registration or authorization that becomes unusable during transcription is refused the same way after it: ASR usage stays billed, and the Turn the transcript began reads as failed with the same failure.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"501": {
"description": "Audio transcription is disabled because ASR_OPENAI_API_KEY is not configured."
},
"503": {
"description": "New Turn admission is temporarily closed for deployment maintenance or recovery (turn_admission_closed), or the deployment lacks the Sandbox or Drive9 service a new Turn needs (service_configuration_unavailable; details.reason names it). Normally this refusal happens before the audio is read, transcribed or billed and before anything is saved. If the configuration changes concurrently, the same 503 can follow transcription; that transcription remains billed and no Turn is saved.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
},
"example": {
"error": {
"code": "turn_admission_closed",
"message": "New Turns are temporarily unavailable"
}
}
}
}
}
}

GET /api/v1/org/users/{userId}/sessions/{id}/tools

Section titled “GET /api/v1/org/users/{userId}/sessions/{id}/tools”

Authorization: OrganizationApiKey; persisted credentials determine Organization and End User scope.

SessionsController_organizationGetTools

[
{
"OrganizationApiKey": []
}
]
[
{
"name": "userId",
"required": true,
"in": "path",
"schema": {
"type": "string"
}
},
{
"name": "id",
"required": true,
"in": "path",
"schema": {
"type": "string"
}
}
]
{
"200": {
"description": "The Session client-declared Client Tool set and its revision.",
"headers": {
"ETag": {
"description": "Strong ETag of the Session Client Tool set revision.",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SessionClientToolsResponseOpenApiDto"
}
}
}
},
"401": {
"description": "Authentication is required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "An Organization API Key and an explicitly selected ordinary End User are required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"404": {
"description": "The Session is unavailable or authorization-hidden.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}

PUT /api/v1/org/users/{userId}/sessions/{id}/tools

Section titled “PUT /api/v1/org/users/{userId}/sessions/{id}/tools”

Authorization: OrganizationApiKey; persisted credentials determine Organization and End User scope.

SessionsController_organizationReplaceTools

[
{
"OrganizationApiKey": []
}
]
[
{
"name": "userId",
"required": true,
"in": "path",
"schema": {
"type": "string"
}
},
{
"name": "id",
"required": true,
"in": "path",
"schema": {
"type": "string"
}
},
{
"name": "If-Match",
"in": "header",
"description": "Exact Client Tool set ETag from the latest tools response.",
"required": true,
"schema": {
"type": "string"
}
}
]
{
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ReplaceSessionToolsOpenApiDto"
}
}
}
}
{
"200": {
"description": "The replaced Client Tool set. An identical set keeps its revision.",
"headers": {
"ETag": {
"description": "Strong ETag of the Session Client Tool set revision.",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SessionClientToolsResponseOpenApiDto"
}
}
}
},
"400": {
"description": "The Client Tool declarations are invalid.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"401": {
"description": "Authentication is required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "An Organization API Key and an explicitly selected ordinary End User are required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"404": {
"description": "The Session is unavailable or authorization-hidden.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"409": {
"description": "The Session is read-only (session_read_only).",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"412": {
"description": "The supplied Client Tool set ETag is stale.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"428": {
"description": "If-Match is required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}

POST /api/v1/org/users/{userId}/sessions/{id}/events

Section titled “POST /api/v1/org/users/{userId}/sessions/{id}/events”

Authorization: OrganizationApiKey; persisted credentials determine Organization and End User scope.

SessionsController_organizationSubmitEvent

[
{
"OrganizationApiKey": []
}
]
[
{
"name": "userId",
"required": true,
"in": "path",
"schema": {
"type": "string"
}
},
{
"name": "id",
"required": true,
"in": "path",
"schema": {
"type": "string"
}
}
]
{
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SessionEventOpenApiDto"
}
}
}
}
{
"200": {
"description": "An idempotent replay of an already accepted command.",
"content": {
"application/json": {
"schema": {
"oneOf": [
{
"$ref": "#/components/schemas/SessionInteractionResponseOpenApiDto"
},
{
"$ref": "#/components/schemas/SessionEventRetryResponseOpenApiDto"
}
]
}
}
}
},
"202": {
"description": "The command was accepted. Message and cancellation commands return durable interaction receipts; retry commands return a retrying event receipt. Read execution progress and results through Turn reads, or follow the Session over a Backend Connection.",
"content": {
"application/json": {
"schema": {
"oneOf": [
{
"$ref": "#/components/schemas/SessionInteractionResponseOpenApiDto"
},
{
"$ref": "#/components/schemas/SessionEventRetryResponseOpenApiDto"
}
]
}
}
}
},
"400": {
"description": "The command envelope or command data is invalid, or an idle text Turn admission exceeds the Client Tool limit after model projection (64 tools or 64 KiB; validation_failed). Admission saves no input or Turn on this overflow. New checkpoint retries are disabled by default and return checkpoint_runtime_unavailable when disabled or unavailable; previously accepted retry commands still recover their receipts.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"401": {
"description": "Authentication is required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "An Organization API Key and an explicitly selected ordinary End User are required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"404": {
"description": "The Session is unavailable or authorization-hidden.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"409": {
"description": "The command identity was already used with a different body or target state, a new message or retry targets a read-only Session (session_read_only), a checkpoint retry targets an earlier Session Configuration Epoch (session_configuration_epoch_changed), or a Session Template switch is in progress (session_switch_in_progress). A Turn start is refused when an MCP Server Registration the Session references is disabled or deleted (session_execution_dependency_unavailable), or when an MCP Authorization it needs is not usable (mcp_authorization_required): details.registrations lists each such registration with its serverId, owner (organization or end_user) and reason (missing, invalid, revoked or insufficient_scope). Only a message that would start a new Turn is checked, never one steered into a running Turn. Nothing is saved, so the same clientEventId can be sent again once the authorization is usable.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"503": {
"description": "New Turn admission is temporarily closed for deployment maintenance or recovery (turn_admission_closed), or the deployment lacks the Sandbox or Drive9 service a new Turn needs (service_configuration_unavailable; details.reason names it). This refusal happens before the command is saved, so the same clientEventId can be sent again once the service is set up. If the configuration changes after that check, the command is accepted instead and its Turn fails with the same code and reason in turn_error. A model the deployment does not configure keeps its 409 model_provider_unconfigured refusal.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
},
"example": {
"error": {
"code": "turn_admission_closed",
"message": "New Turns are temporarily unavailable"
}
}
}
}
}
}

GET /api/v1/org/users/{userId}/sessions/{id}/interactions

Section titled “GET /api/v1/org/users/{userId}/sessions/{id}/interactions”

Authorization: OrganizationApiKey; persisted credentials determine Organization and End User scope.

SessionsController_organizationListInteractions

[
{
"OrganizationApiKey": []
}
]
[
{
"name": "userId",
"required": true,
"in": "path",
"schema": {
"type": "string"
}
},
{
"name": "id",
"required": true,
"in": "path",
"schema": {
"type": "string"
}
},
{
"name": "cursor",
"required": false,
"in": "query",
"description": "Opaque Session-bound continuation cursor.",
"schema": {
"type": "string"
}
},
{
"name": "limit",
"required": false,
"in": "query",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 200,
"default": 50
}
},
{
"name": "clientEventId",
"required": false,
"in": "query",
"description": "Read only the original command receipt, including checkpoint retry. Cannot be combined with limit or cursor; a missing key returns an empty page. No execution is started.",
"schema": {
"type": "string"
}
}
]
{
"200": {
"description": "Saved commands in ascending Session-local sequence, or the exact original command-key receipt without executing again.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SessionInteractionsResponseOpenApiDto"
}
}
}
},
"400": {
"description": "Invalid limit or malformed, negative or different-Session continuation cursor.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"default": {
"description": "Unavailable owning Session or unsupported, invalid or unavailable credentials.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}

GET /api/v1/org/users/{userId}/sessions/{id}/interactions/{receiptId}

Section titled “GET /api/v1/org/users/{userId}/sessions/{id}/interactions/{receiptId}”

Authorization: OrganizationApiKey; persisted credentials determine Organization and End User scope.

SessionsController_organizationGetInteraction

[
{
"OrganizationApiKey": []
}
]
[
{
"name": "userId",
"required": true,
"in": "path",
"schema": {
"type": "string"
}
},
{
"name": "id",
"required": true,
"in": "path",
"schema": {
"type": "string"
}
},
{
"name": "receiptId",
"required": true,
"in": "path",
"schema": {
"type": "string"
}
}
]
{
"200": {
"description": "Original input receipt and original-generation outcome, including saved refusals.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SessionInteractionResponseOpenApiDto"
}
}
}
},
"404": {
"description": "Unrecorded input or unavailable owning Session.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"default": {
"description": "Unsupported, invalid or unavailable caller credentials.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}

GET /api/v1/org/users/{userId}/sessions/{id}/timeline

Section titled “GET /api/v1/org/users/{userId}/sessions/{id}/timeline”

Authorization: OrganizationApiKey; persisted credentials determine Organization and End User scope.

SessionsController_organizationTimeline

[
{
"OrganizationApiKey": []
}
]
[
{
"name": "userId",
"required": true,
"in": "path",
"schema": {
"type": "string"
}
},
{
"name": "id",
"required": true,
"in": "path",
"schema": {
"type": "string"
}
},
{
"name": "cursor",
"required": false,
"in": "query",
"description": "Opaque owning User and Session continuation cursor from nextCursor.",
"schema": {
"type": "string"
}
},
{
"name": "limit",
"required": false,
"in": "query",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 200,
"default": 50
}
}
]
{
"200": {
"description": "A bounded page of the Session timeline. Each entry is a complete Turn, one Realtime fact, or one successful Template-switch fact with epoch and Template provenance. Failed switches remain stream-only. Facts follow durable write order. A Turn started by a Realtime utterance is placed directly after that utterance; every other Turn sits where its first event was saved. Key entries by their stable id and replace an entry that arrives again. A running Turn is a snapshot of its progress so far; read it again for later changes.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SessionTimelineResponseOpenApiDto"
}
}
}
},
"400": {
"description": "Invalid limit, or a malformed, foreign or unknown continuation cursor.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"default": {
"description": "Unavailable owning Session or unsupported, invalid or unavailable credentials.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}

GET /api/v1/org/users/{userId}/sessions/{id}/turns

Section titled “GET /api/v1/org/users/{userId}/sessions/{id}/turns”

Authorization: OrganizationApiKey; persisted credentials determine Organization and End User scope.

SessionsController_organizationListTurns

[
{
"OrganizationApiKey": []
}
]
[
{
"name": "userId",
"required": true,
"in": "path",
"schema": {
"type": "string"
}
},
{
"name": "id",
"required": true,
"in": "path",
"schema": {
"type": "string"
}
},
{
"name": "cursor",
"required": false,
"in": "query",
"description": "Opaque owning User and Session continuation cursor; chronological creation order with Turn ID as tie breaker.",
"schema": {
"type": "string"
}
},
{
"name": "limit",
"required": false,
"in": "query",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 200,
"default": 50
}
}
]
{
"200": {
"description": "Full Agent and Realtime Turns in creation-time order. Late Realtime writes before an already consumed cursor require a full refresh; use /timeline for durable event-sequence replay.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TurnsResponseOpenApiDto"
}
}
}
},
"400": {
"description": "Invalid query or cursor, including another owner, Session or list kind.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"default": {
"description": "Unavailable owning Session or unsupported, invalid or unavailable credentials.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}

GET /api/v1/org/users/{userId}/sessions/{id}/turns/{turnId}

Section titled “GET /api/v1/org/users/{userId}/sessions/{id}/turns/{turnId}”

Authorization: OrganizationApiKey; persisted credentials determine Organization and End User scope.

SessionsController_organizationGetTurn

[
{
"OrganizationApiKey": []
}
]
[
{
"name": "userId",
"required": true,
"in": "path",
"schema": {
"type": "string"
}
},
{
"name": "id",
"required": true,
"in": "path",
"schema": {
"type": "string"
}
},
{
"name": "turnId",
"required": true,
"in": "path",
"schema": {
"type": "string"
}
}
]
{
"200": {
"description": "One Full Agent or user-input Realtime Turn.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TurnResponse"
}
}
}
},
"404": {
"description": "Unavailable Session, unknown Turn or narration-only Realtime Turn.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}

POST /api/v1/org/users/{userId}/sessions/{id}/files

Section titled “POST /api/v1/org/users/{userId}/sessions/{id}/files”

Authorization: OrganizationApiKey; persisted credentials determine Organization and End User scope.

OrganizationSessionsController_uploadFile

[
{
"OrganizationApiKey": []
}
]
[
{
"name": "userId",
"required": true,
"in": "path",
"schema": {
"type": "string"
}
},
{
"name": "id",
"required": true,
"in": "path",
"schema": {
"type": "string"
}
}
]
{
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UploadSessionFileOpenApiDto"
}
}
}
}
{
"201": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UploadSessionFileResponseOpenApiDto"
}
}
}
},
"401": {
"description": "A current Organization API Key is required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "An Organization API Key is required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"404": {
"description": "session_not_found: the ordinary target User or owned Session is unavailable.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"409": {
"description": "The Session is read-only.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"503": {
"description": "Storage or required durable audit is unavailable.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}

POST /api/v1/org/users/{userId}/sessions/{id}/files/batch

Section titled “POST /api/v1/org/users/{userId}/sessions/{id}/files/batch”

Authorization: OrganizationApiKey; persisted credentials determine Organization and End User scope.

OrganizationSessionsController_uploadFiles

[
{
"OrganizationApiKey": []
}
]
[
{
"name": "userId",
"required": true,
"in": "path",
"schema": {
"type": "string"
}
},
{
"name": "id",
"required": true,
"in": "path",
"schema": {
"type": "string"
}
}
]
{
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UploadSessionFilesOpenApiDto"
}
}
}
}
{
"201": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UploadSessionFilesResponseOpenApiDto"
}
}
}
},
"401": {
"description": "A current Organization API Key is required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "An Organization API Key is required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"404": {
"description": "session_not_found: the ordinary target User or owned Session is unavailable.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"409": {
"description": "A target path contains different content.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"503": {
"description": "Storage or required durable audit is unavailable.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}

Authorization: OrganizationApiKey; persisted credentials determine Organization and End User scope.

OrganizationSessionsController_list

[
{
"OrganizationApiKey": []
}
]
[
{
"name": "userId",
"required": true,
"in": "path",
"schema": {
"type": "string"
}
},
{
"name": "agentTemplateId",
"required": false,
"in": "query",
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 64
},
"description": "Select Sessions whose current Configuration Epoch uses this AgentTemplate."
},
{
"name": "cursor",
"required": false,
"in": "query",
"description": "Opaque continuation cursor bound to the owner and Template filter.",
"schema": {
"type": "string"
}
},
{
"name": "limit",
"required": false,
"in": "query",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 200,
"default": 50
}
}
]
{
"200": {
"description": "The explicitly selected ordinary End User’s Sessions in descending creation-time and Session-ID order. Display and activity changes do not move the continuation position.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SessionsResponseOpenApiDto"
}
}
}
},
"400": {
"description": "Invalid query or cursor, including another owner or list kind.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"401": {
"description": "Authentication is required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "auth_kind_forbidden: an Organization API Key is required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"404": {
"description": "session_not_found: the ordinary target User or owned Session is unavailable.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}

Authorization: OrganizationApiKey; persisted credentials determine Organization and End User scope.

OrganizationSessionsController_create

[
{
"OrganizationApiKey": []
}
]
[
{
"name": "userId",
"required": true,
"in": "path",
"schema": {
"type": "string"
}
},
{
"name": "Idempotency-Key",
"in": "header",
"required": true,
"schema": {
"type": "string",
"pattern": "^[A-Za-z0-9][A-Za-z0-9_.:-]{0,127}$",
"maxLength": 128
}
}
]
{
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateTemplateSessionOpenApiDto"
}
}
}
}
{
"201": {
"description": "Created Session.",
"headers": {
"ETag": {
"description": "Opaque Session model revision token. Model changes apply to the next Turn. It does not version live `realtime` presence.",
"required": true,
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SessionResponseOpenApiDto"
}
}
}
},
"400": {
"description": "The Session input or required Idempotency-Key is invalid.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"401": {
"description": "Authentication is required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "auth_kind_forbidden: an Organization API Key is required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"404": {
"description": "The selected active Template or its dependencies are unavailable or authorization-hidden.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"409": {
"description": "The Idempotency-Key conflicts, cross-Session Recall requires acknowledgment (agent_template_recall_acknowledgment_required), the model provider is unconfigured, the Realtime Model is unavailable (realtime_model_unavailable), Realtime is disabled (realtime_not_enabled), or combined instructions exceed 16 KiB (agent_instructions_too_large).",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"503": {
"description": "skill_package_store_unavailable: required Skill package storage is temporarily unavailable.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}

POST /api/v1/org/users/{userId}/sessions/{id}/template-switches

Section titled “POST /api/v1/org/users/{userId}/sessions/{id}/template-switches”

Authorization: OrganizationApiKey; persisted credentials determine Organization and End User scope.

OrganizationSessionsController_switchTemplate

[
{
"OrganizationApiKey": []
}
]
[
{
"name": "userId",
"required": true,
"in": "path",
"schema": {
"type": "string"
}
},
{
"name": "id",
"required": true,
"in": "path",
"schema": {
"type": "string"
}
},
{
"name": "Idempotency-Key",
"in": "header",
"required": true,
"schema": {
"type": "string",
"pattern": "^[A-Za-z0-9][A-Za-z0-9_.:-]{0,127}$",
"maxLength": 128
}
}
]
{
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SwitchSessionTemplateOpenApiDto"
}
}
}
}
{
"202": {
"description": "Durable pending Handoff receipt for a changed target with history, or a terminal succeeded or unchanged receipt.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SessionTemplateSwitchResponseOpenApiDto"
}
}
}
},
"400": {
"description": "The body or required Idempotency-Key is invalid.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"401": {
"description": "A current exact Organization API Key is required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "auth_kind_forbidden: an Organization API Key is required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"404": {
"description": "session_not_found or agent_template_unavailable: the explicit ordinary owner, active Session or target Template is unavailable or authorization-hidden.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"409": {
"description": "agent_instructions_too_large, idempotency_key_reused, session_read_only, agent_template_recall_acknowledgment_required, session_switch_in_progress, session_switch_busy, session_switch_unsupported, or resource_conflict when the target Realtime language is no longer offered.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"503": {
"description": "turn_admission_closed when deployment maintenance or recovery pauses new Handoff Turns, or skill_package_store_unavailable when required Skill package storage is temporarily unavailable.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}

GET /api/v1/org/users/{userId}/sessions/{id}

Section titled “GET /api/v1/org/users/{userId}/sessions/{id}”

Authorization: OrganizationApiKey; persisted credentials determine Organization and End User scope.

OrganizationSessionsController_get

[
{
"OrganizationApiKey": []
}
]
[
{
"name": "userId",
"required": true,
"in": "path",
"schema": {
"type": "string"
}
},
{
"name": "id",
"required": true,
"in": "path",
"schema": {
"type": "string"
}
}
]
{
"200": {
"description": "Session.",
"headers": {
"ETag": {
"description": "Opaque Session model revision token. Model changes apply to the next Turn. It does not version live `realtime` presence.",
"required": true,
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SessionResponseOpenApiDto"
}
}
}
},
"401": {
"description": "Authentication is required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "auth_kind_forbidden: an Organization API Key is required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"404": {
"description": "The Session is unavailable or authorization-hidden.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}

DELETE /api/v1/org/users/{userId}/sessions/{id}

Section titled “DELETE /api/v1/org/users/{userId}/sessions/{id}”

Authorization: OrganizationApiKey; persisted credentials determine Organization and End User scope.

OrganizationSessionsController_delete

[
{
"OrganizationApiKey": []
}
]
[
{
"name": "userId",
"required": true,
"in": "path",
"schema": {
"type": "string"
}
},
{
"name": "id",
"required": true,
"in": "path",
"schema": {
"type": "string"
}
}
]
{
"200": {
"description": "Deleted Session tombstone.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SessionResponseOpenApiDto"
}
}
}
},
"401": {
"description": "Authentication is required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "auth_kind_forbidden: an Organization API Key is required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"404": {
"description": "The Session is unavailable or authorization-hidden.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"409": {
"description": "The Session is read-only or still has an active Turn.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}

PATCH /api/v1/org/users/{userId}/sessions/{id}/model

Section titled “PATCH /api/v1/org/users/{userId}/sessions/{id}/model”

Authorization: OrganizationApiKey; persisted credentials determine Organization and End User scope.

OrganizationSessionsController_updateModel

[
{
"OrganizationApiKey": []
}
]
[
{
"name": "userId",
"required": true,
"in": "path",
"schema": {
"type": "string"
}
},
{
"name": "id",
"required": true,
"in": "path",
"schema": {
"type": "string"
}
},
{
"name": "If-Match",
"in": "header",
"description": "Exact Session model ETag from the latest Session response.",
"required": true,
"schema": {
"type": "string"
}
}
]
{
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UpdateSessionModelOpenApiDto"
}
}
}
}
{
"200": {
"description": "Updated Session model. An active Turn retains its admitted model; the next Turn uses this selection.",
"headers": {
"ETag": {
"description": "Opaque Session model revision token. Model changes apply to the next Turn. It does not version live `realtime` presence.",
"required": true,
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SessionResponseOpenApiDto"
}
}
}
},
"400": {
"description": "validation_error or session_model_not_allowed.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"401": {
"description": "Missing or invalid Organization API Key.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "auth_kind_forbidden: an Organization API Key is required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"404": {
"description": "session_not_found.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"409": {
"description": "model_provider_unconfigured or session_read_only.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"412": {
"description": "The supplied Session model ETag is stale.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"428": {
"description": "If-Match is required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}

PATCH /api/v1/org/users/{userId}/sessions/{id}/realtime-model

Section titled “PATCH /api/v1/org/users/{userId}/sessions/{id}/realtime-model”

Authorization: OrganizationApiKey; persisted credentials determine Organization and End User scope.

OrganizationSessionsController_updateRealtimeModel

[
{
"OrganizationApiKey": []
}
]
[
{
"name": "userId",
"required": true,
"in": "path",
"schema": {
"type": "string"
}
},
{
"name": "id",
"required": true,
"in": "path",
"schema": {
"type": "string"
}
},
{
"name": "If-Match",
"in": "header",
"description": "The realtimeModelEtag from the latest Session response.",
"required": true,
"schema": {
"type": "string"
}
}
]
{
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UpdateSessionRealtimeModelOpenApiDto"
}
}
}
}
{
"200": {
"description": "Updated selection for the next Realtime Connection. A live connection retains its admitted model.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SessionResponseOpenApiDto"
}
}
}
},
"400": {
"description": "validation_error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"401": {
"description": "Missing or invalid Organization API Key.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "A Organization API Key is required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"404": {
"description": "session_not_found.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"409": {
"description": "realtime_model_unavailable, realtime_not_enabled or session_read_only.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"412": {
"description": "realtime_model_conflict: the supplied selection revision is stale.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"428": {
"description": "precondition_required: If-Match is required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}

PATCH /api/v1/org/users/{userId}/sessions/{id}/billing-tag

Section titled “PATCH /api/v1/org/users/{userId}/sessions/{id}/billing-tag”

Authorization: OrganizationApiKey; persisted credentials determine Organization and End User scope.

OrganizationSessionsController_updateBillingTag

[
{
"OrganizationApiKey": []
}
]
[
{
"name": "userId",
"required": true,
"in": "path",
"schema": {
"type": "string"
}
},
{
"name": "id",
"required": true,
"in": "path",
"schema": {
"type": "string"
}
}
]
{
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UpdateSessionBillingTagOpenApiDto"
}
}
}
}
{
"200": {
"description": "Updated Session billing tag.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SessionResponseOpenApiDto"
}
}
}
},
"400": {
"description": "The Billing Tag is malformed or incomplete.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"401": {
"description": "Authentication is required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "auth_kind_forbidden: an Organization API Key is required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"404": {
"description": "The Session is unavailable or authorization-hidden.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"409": {
"description": "The Session is read-only.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}

POST /api/v1/org/users/{userId}/sessions/{id}/name

Section titled “POST /api/v1/org/users/{userId}/sessions/{id}/name”

Authorization: OrganizationApiKey; persisted credentials determine Organization and End User scope.

OrganizationSessionsController_rename

[
{
"OrganizationApiKey": []
}
]
[
{
"name": "userId",
"required": true,
"in": "path",
"schema": {
"type": "string"
}
},
{
"name": "id",
"required": true,
"in": "path",
"schema": {
"type": "string"
}
}
]
{
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RenameSessionOpenApiDto"
}
}
}
}
{
"201": {
"description": "Session.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SessionResponseOpenApiDto"
}
}
}
},
"400": {
"description": "The Session name is empty, too long, or otherwise invalid.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"401": {
"description": "Authentication is required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "auth_kind_forbidden: an Organization API Key is required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"404": {
"description": "The Session is unavailable or authorization-hidden.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"409": {
"description": "The Session is read-only.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}

POST /api/v1/org/users/{userId}/sessions/{id}/name/suggest

Section titled “POST /api/v1/org/users/{userId}/sessions/{id}/name/suggest”

Authorization: OrganizationApiKey; persisted credentials determine Organization and End User scope.

OrganizationSessionsController_suggestName

[
{
"OrganizationApiKey": []
}
]
[
{
"name": "userId",
"required": true,
"in": "path",
"schema": {
"type": "string"
}
},
{
"name": "id",
"required": true,
"in": "path",
"schema": {
"type": "string"
}
}
]
{
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SuggestSessionNameOpenApiDto"
}
}
}
}
{
"201": {
"description": "Suggested name and updated Session.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SuggestSessionNameResponseOpenApiDto"
}
}
}
},
"400": {
"description": "The source exchange used for naming is invalid.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"401": {
"description": "Authentication is required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "auth_kind_forbidden: an Organization API Key is required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"404": {
"description": "The Session is unavailable or authorization-hidden.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"409": {
"description": "The selected model configuration or command authority is unavailable, or the Session is read-only (session_read_only).",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}

Create a directory in the authenticated user’s general Drive

Creates one non-system directory in the caller-owned general Drive. The path is relative to that Drive root.

Authorization: UserApiKey; persisted credentials determine Organization and End User scope.

UserDriveUploadsController_createDirectory

[
{
"UserApiKey": []
}
]
[
{
"name": "Idempotency-Key",
"in": "header",
"required": true,
"schema": {
"type": "string"
}
}
]
{
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateUserDriveDirectoryBodyDto"
}
}
}
}
{
"201": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UserDriveEntryResponseDto"
}
}
}
},
"400": {
"description": "Invalid path, cursor, body, or request headers.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"401": {
"description": "A User API Key is required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "A User API Key for an ordinary End User is required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"404": {
"description": "The entry is not owned by the current Organization and End User.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"409": {
"description": "ErrorEnvelope code: resource_conflict.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"503": {
"description": "The owned Drive provider or durable entry state is temporarily unavailable.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}

Issue a short-lived ticket for an owned general Drive file

The ticket is bound to the current User Key scope and the complete file identity.

Authorization: UserApiKey; persisted credentials determine Organization and End User scope.

UserDriveUploadsController_downloadTicket

[
{
"UserApiKey": []
}
]
{
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UserDriveDownloadTicketBodyDto"
}
}
}
}
{
"201": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"url",
"expiresAt",
"byteSize"
],
"properties": {
"url": {
"type": "string"
},
"expiresAt": {
"type": "string",
"format": "date-time"
},
"byteSize": {
"type": "integer"
},
"sha256": {
"type": "string"
}
}
}
}
}
},
"400": {
"description": "Invalid path, cursor, body, or request headers.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"401": {
"description": "A User API Key is required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "A User API Key for an ordinary End User is required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"404": {
"description": "The entry is not owned by the current Organization and End User.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"503": {
"description": "The owned Drive provider or durable entry state is temporarily unavailable.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}

List an owned general Drive directory or read an entry’s metadata

Directory listings are immediate children only and return opaque file IDs. Cursors are bound to the current user and path.

Authorization: UserApiKey; persisted credentials determine Organization and End User scope.

UserDriveUploadsController_listEntries

[
{
"UserApiKey": []
}
]
[
{
"name": "path",
"required": false,
"in": "query",
"schema": {
"maxLength": 1024,
"type": "string"
}
},
{
"name": "fileId",
"required": false,
"in": "query",
"schema": {
"maxLength": 128,
"type": "string"
}
},
{
"name": "limit",
"required": false,
"in": "query",
"schema": {
"minimum": 1,
"maximum": 1000,
"exclusiveMaximum": false,
"exclusiveMinimum": false,
"default": 100,
"type": "integer"
}
},
{
"name": "cursor",
"required": false,
"in": "query",
"schema": {
"maxLength": 2048,
"type": "string"
}
}
]
{
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UserDriveEntriesResponseDto"
}
}
}
},
"400": {
"description": "Invalid path, cursor, body, or request headers.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"401": {
"description": "A User API Key is required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "A User API Key for an ordinary End User is required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"404": {
"description": "The entry is not owned by the current Organization and End User.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"503": {
"description": "The owned Drive provider or durable entry state is temporarily unavailable.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}

Delete an owned general Drive file or empty directory

Deletion is non-recursive. Unknown provider write outcomes are surfaced without an automatic retry.

Authorization: UserApiKey; persisted credentials determine Organization and End User scope.

UserDriveUploadsController_deleteEntry

[
{
"UserApiKey": []
}
]
{
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UserDriveEntryMutationBodyDto"
}
}
}
}
{
"204": {
"description": "The owned file or empty directory was deleted."
},
"400": {
"description": "Invalid path, cursor, body, or request headers.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"401": {
"description": "A User API Key is required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "A User API Key for an ordinary End User is required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"404": {
"description": "The entry is not owned by the current Organization and End User.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"409": {
"description": "The path is occupied or a directory is not empty.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"503": {
"description": "The owned Drive provider or durable entry state is temporarily unavailable.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}

Read complete content from an owned general Drive file

Authorization: UserApiKey; persisted credentials determine Organization and End User scope.

UserDriveUploadsController_readContent

[
{
"UserApiKey": []
}
]
[
{
"name": "fileId",
"required": false,
"in": "query",
"schema": {
"maxLength": 128,
"type": "string"
}
},
{
"name": "path",
"required": false,
"in": "query",
"schema": {
"maxLength": 1024,
"type": "string"
}
}
]
{
"200": {
"content": {
"*/*": {
"schema": {
"type": "string",
"format": "binary"
}
}
},
"headers": {
"Cache-Control": {
"schema": {
"type": "string",
"example": "private, no-store"
}
},
"Content-Disposition": {
"schema": {
"type": "string"
}
},
"Content-Length": {
"schema": {
"type": "string"
}
},
"Content-Type": {
"schema": {
"type": "string"
}
},
"ETag": {
"schema": {
"type": "string"
}
},
"X-Content-Type-Options": {
"schema": {
"type": "string",
"example": "nosniff"
}
}
},
"description": ""
},
"400": {
"description": "Invalid path, cursor, body, or request headers.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"401": {
"description": "A User API Key is required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "A User API Key for an ordinary End User is required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"404": {
"description": "The entry is not owned by the current Organization and End User.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"503": {
"description": "The owned Drive provider or durable entry state is temporarily unavailable.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}

Create or replace an owned general Drive file

The complete byte body is verified before the new metadata and ETag are returned. Existing files require their current If-Match value.

Authorization: UserApiKey; persisted credentials determine Organization and End User scope.

UserDriveUploadsController_writeContent

[
{
"UserApiKey": []
}
]
[
{
"name": "fileId",
"required": false,
"in": "query",
"schema": {
"maxLength": 128,
"type": "string"
}
},
{
"name": "path",
"required": false,
"in": "query",
"schema": {
"maxLength": 1024,
"type": "string"
}
},
{
"name": "Content-Length",
"in": "header",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "If-Match",
"in": "header",
"required": false,
"schema": {
"type": "string"
}
},
{
"name": "Idempotency-Key",
"in": "header",
"required": true,
"schema": {
"type": "string"
}
}
]
{
"required": true,
"content": {
"application/octet-stream": {
"schema": {
"type": "string",
"format": "binary"
}
}
}
}
{
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UserDriveEntryResponseDto"
}
}
},
"headers": {
"ETag": {
"schema": {
"type": "string"
}
}
}
},
"400": {
"description": "Invalid path, cursor, body, or request headers.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"401": {
"description": "A User API Key is required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "A User API Key for an ordinary End User is required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"404": {
"description": "The entry is not owned by the current Organization and End User.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"409": {
"description": "The path is occupied by a directory or the idempotency key was reused.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"412": {
"description": "The supplied If-Match value is stale.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"413": {
"description": "The complete body exceeds the Drive file limit.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"428": {
"description": "If-Match is required when replacing an existing file.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"503": {
"description": "The owned Drive provider or durable entry state is temporarily unavailable.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}

GET /api/v1/user/drive/upload-capabilities

Section titled “GET /api/v1/user/drive/upload-capabilities”

Get the effective user-file upload limits

Returns the current inline threshold and effective maximum. Re-read after a typed 413 before replanning.

Authorization: UserApiKey; persisted credentials determine Organization and End User scope.

UserDriveUploadsController_uploadCapabilities

[
{
"UserApiKey": []
}
]
{
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicUserFileUploadCapabilitiesOpenApiDto"
}
}
}
},
"400": {
"description": "Invalid request input, upload state, or upload metadata.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"401": {
"description": "A User API Key is required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "A User API Key for an ordinary End User is required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"404": {
"description": "File not found for the current Organization and End User.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"503": {
"description": "Drive9 or durable upload state is temporarily unavailable; retry as directed by the error details.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}

Create or replay an owned Drive upload intent

The Idempotency-Key binds the exact request. Same-key retries recover the original File and fixed expiry. Expired or failed uploads require a new key and File. The response identifies inline versus multipart transport and the verification expected after settlement. Browsers on any origin may call every upload route with the User API Key in Authorization; responses never admit credentials.

Authorization: UserApiKey; persisted credentials determine Organization and End User scope.

UserDriveUploadsController_createUpload

[
{
"UserApiKey": []
}
]
[
{
"name": "Idempotency-Key",
"in": "header",
"required": true,
"schema": {
"type": "string"
}
}
]
{
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreatePublicUserFileUploadBodyOpenApiDto"
}
}
}
}
{
"201": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FileUploadResponseDto"
}
}
}
},
"400": {
"description": "Invalid request input, upload state, or upload metadata.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"401": {
"description": "A User API Key is required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "A User API Key for an ordinary End User is required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"404": {
"description": "File not found for the current Organization and End User.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"409": {
"description": "The Idempotency-Key has different input, the attempt is in progress, or the original upload is expired or failed.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"413": {
"description": "upload_too_large: the declared byteSize exceeds the current product or Drive9 maximum.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"503": {
"description": "Drive9 or durable upload state is temporarily unavailable; retry as directed by the error details.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}

Read the current owned Drive upload state

The opaque uploadId addresses the persisted upload intent, including initialization, cancellation and completion. Expiry stays fixed across recovery; a status read never recreates an upload.

Authorization: UserApiKey; persisted credentials determine Organization and End User scope.

UserDriveUploadsController_uploadStatus

[
{
"UserApiKey": []
}
]
[
{
"name": "uploadId",
"required": true,
"in": "path",
"schema": {
"type": "string"
}
}
]
{
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UploadStatusResponseDto"
}
}
}
},
"400": {
"description": "Invalid request input, upload state, or upload metadata.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"401": {
"description": "A User API Key is required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "A User API Key for an ordinary End User is required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"404": {
"description": "File not found for the current Organization and End User.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"503": {
"description": "Drive9 or durable upload state is temporarily unavailable; retry as directed by the error details.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}

DELETE /api/v1/user/drive/uploads/{uploadId}

Section titled “DELETE /api/v1/user/drive/uploads/{uploadId}”

Abort an upload intent

Aborts remote multipart state when present. A same-key create retry cannot revive an aborted upload.

Authorization: UserApiKey; persisted credentials determine Organization and End User scope.

UserDriveUploadsController_abortUpload

[
{
"UserApiKey": []
}
]
[
{
"name": "uploadId",
"required": true,
"in": "path",
"schema": {
"type": "string"
}
}
]
{
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FileResponseDto"
}
}
}
},
"400": {
"description": "Invalid request input, upload state, or upload metadata.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"401": {
"description": "A User API Key is required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "A User API Key for an ordinary End User is required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"404": {
"description": "File not found for the current Organization and End User.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"503": {
"description": "Drive9 or durable upload state is temporarily unavailable; retry as directed by the error details.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}

PUT /api/v1/user/drive/uploads/{uploadId}/content

Section titled “PUT /api/v1/user/drive/uploads/{uploadId}/content”

Upload and whole-file verify inline content

Send exactly Content-Length bytes with an RFC 9530 SHA-256 Content-Digest. A multipart-required 413 requires a new File and Idempotency-Key.

Authorization: UserApiKey; persisted credentials determine Organization and End User scope.

UserDriveUploadsController_uploadContent

[
{
"UserApiKey": []
}
]
[
{
"name": "uploadId",
"required": true,
"in": "path",
"schema": {
"type": "string"
}
},
{
"name": "Content-Digest",
"in": "header",
"description": "RFC 9530 SHA-256 digest, for example sha-256=:base64-value=:",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "Content-Length",
"in": "header",
"required": true,
"schema": {
"type": "string"
}
}
]
{
"required": true,
"content": {
"application/octet-stream": {
"schema": {
"type": "string",
"format": "binary"
}
}
}
}
{
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FileResponseDto"
}
}
}
},
"400": {
"description": "Invalid request input, upload state, or upload metadata.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"401": {
"description": "A User API Key is required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "A User API Key for an ordinary End User is required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"404": {
"description": "File not found for the current Organization and End User.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"413": {
"description": "upload_requires_multipart means create a new File with a new Idempotency-Key for an S3 plan; upload_too_large means re-read capabilities and reduce the file size.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"422": {
"description": "upload_integrity_failed: persisted bytes do not match the whole-file size or SHA-256.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"503": {
"description": "Drive9 or durable upload state is temporarily unavailable; retry as directed by the error details.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}

POST /api/v1/user/drive/uploads/{uploadId}/parts/{partNumber}/presign

Section titled “POST /api/v1/user/drive/uploads/{uploadId}/parts/{partNumber}/presign”

Bind a multipart part digest and get its upload URL

The declared SHA-256 is durably bound to this exact part. PUT exactly the returned size to the returned URL with every returned header, then retain the S3 ETag for completion.

Authorization: UserApiKey; persisted credentials determine Organization and End User scope.

UserDriveUploadsController_presignPart

[
{
"UserApiKey": []
}
]
[
{
"name": "uploadId",
"required": true,
"in": "path",
"schema": {
"type": "string"
}
},
{
"name": "partNumber",
"required": true,
"in": "path",
"schema": {
"type": "string"
}
}
]
{
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PresignPublicUserFileUploadPartBodyOpenApiDto"
}
}
}
}
{
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicUserFileUploadPartResponseOpenApiDto"
}
}
}
},
"400": {
"description": "Invalid request input, upload state, or upload metadata.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"401": {
"description": "A User API Key is required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "A User API Key for an ordinary End User is required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"404": {
"description": "File not found for the current Organization and End User.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"503": {
"description": "Drive9 or durable upload state is temporarily unavailable; retry as directed by the error details.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}

POST /api/v1/user/drive/uploads/{uploadId}/complete

Section titled “POST /api/v1/user/drive/uploads/{uploadId}/complete”

Confirm a whole-file verified upload

Inline uploads accept an empty object. Multipart uploads submit every part in ascending number order with the exact SHA-256 bound at presign time and the S3 ETag. Success requires complete size and SHA-256 verification; repeated confirmation returns the same ready File.

Authorization: UserApiKey; persisted credentials determine Organization and End User scope.

UserDriveUploadsController_completeUpload

[
{
"UserApiKey": []
}
]
[
{
"name": "uploadId",
"required": true,
"in": "path",
"schema": {
"type": "string"
}
}
]
{
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FileConfirmationDto"
}
}
}
}
{
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FileResponseDto"
}
}
}
},
"400": {
"description": "Invalid request input, upload state, or upload metadata.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"401": {
"description": "A User API Key is required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "A User API Key for an ordinary End User is required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"404": {
"description": "File not found for the current Organization and End User.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"409": {
"description": "upload_incomplete is retryable; upload_expired or upload_failed requires a new File and Idempotency-Key.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"422": {
"description": "upload_integrity_failed: completed bytes differ from the declared whole-file size or SHA-256.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"503": {
"description": "Drive9 or durable upload state is temporarily unavailable; retry as directed by the error details.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}

POST /api/v1/org/users/{userId}/drive/directories

Section titled “POST /api/v1/org/users/{userId}/drive/directories”

Create a directory in an Organization User’s general Drive

Creates one non-system directory in the target ordinary End User Drive. The path is relative to that Drive root.

Authorization: OrganizationApiKey; persisted credentials determine Organization scope. The path userId selects an ordinary target User that must belong to that Organization.

OrganizationUserDriveController_createDirectory

[
{
"OrganizationApiKey": []
}
]
[
{
"name": "userId",
"required": true,
"in": "path",
"description": "Target ordinary End User identifier.",
"schema": {
"type": "string"
}
},
{
"name": "Idempotency-Key",
"in": "header",
"required": true,
"schema": {
"type": "string"
}
}
]
{
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateUserDriveDirectoryBodyDto"
}
}
}
}
{
"201": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UserDriveEntryResponseDto"
}
}
}
},
"400": {
"description": "Invalid path, cursor, body, or request headers.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"401": {
"description": "An authenticated Organization API Key is required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "An Organization API Key is required for this target User operation.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"404": {
"description": "The ordinary target User or Drive entry is unavailable in the current Organization. Disabled ordinary owners remain manageable.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"409": {
"description": "ErrorEnvelope code: resource_conflict.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"503": {
"description": "The target User Drive provider or durable entry state is unavailable.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}

POST /api/v1/org/users/{userId}/drive/download-tickets

Section titled “POST /api/v1/org/users/{userId}/drive/download-tickets”

Issue a download ticket for an Organization User’s Drive file

The ticket binds the exact issuing Organization credential, target ordinary End User, and complete file identity. A disabled ordinary owner remains eligible. Rotation or revocation prevents new redemption; already admitted transfers retain their existing limits.

Authorization: OrganizationApiKey; persisted credentials determine Organization scope. The path userId selects an ordinary target User that must belong to that Organization.

OrganizationUserDriveController_downloadTicket

[
{
"OrganizationApiKey": []
}
]
[
{
"name": "userId",
"required": true,
"in": "path",
"description": "Target ordinary End User identifier.",
"schema": {
"type": "string"
}
}
]
{
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UserDriveDownloadTicketBodyDto"
}
}
}
}
{
"201": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"url",
"expiresAt",
"byteSize"
],
"properties": {
"url": {
"type": "string"
},
"expiresAt": {
"type": "string",
"format": "date-time"
},
"byteSize": {
"type": "integer"
},
"sha256": {
"type": "string"
}
}
}
}
}
},
"400": {
"description": "Invalid path, cursor, body, or request headers.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"401": {
"description": "An authenticated Organization API Key is required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "An Organization API Key is required for this target User operation.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"404": {
"description": "The ordinary target User or Drive entry is unavailable in the current Organization. Disabled ordinary owners remain manageable.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"503": {
"description": "The target User Drive provider or durable entry state is unavailable.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}

GET /api/v1/org/users/{userId}/drive/entries

Section titled “GET /api/v1/org/users/{userId}/drive/entries”

List an Organization User’s Drive directory or read entry metadata

Directory listings are immediate children only and return opaque file IDs. Cursors are bound to the target User and path.

Authorization: OrganizationApiKey; persisted credentials determine Organization scope. The path userId selects an ordinary target User that must belong to that Organization.

OrganizationUserDriveController_listEntries

[
{
"OrganizationApiKey": []
}
]
[
{
"name": "userId",
"required": true,
"in": "path",
"description": "Target ordinary End User identifier.",
"schema": {
"type": "string"
}
},
{
"name": "path",
"required": false,
"in": "query",
"schema": {
"maxLength": 1024,
"type": "string"
}
},
{
"name": "fileId",
"required": false,
"in": "query",
"schema": {
"maxLength": 128,
"type": "string"
}
},
{
"name": "limit",
"required": false,
"in": "query",
"schema": {
"minimum": 1,
"maximum": 1000,
"exclusiveMaximum": false,
"exclusiveMinimum": false,
"default": 100,
"type": "integer"
}
},
{
"name": "cursor",
"required": false,
"in": "query",
"schema": {
"maxLength": 2048,
"type": "string"
}
}
]
{
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UserDriveEntriesResponseDto"
}
}
}
},
"400": {
"description": "Invalid path, cursor, body, or request headers.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"401": {
"description": "An authenticated Organization API Key is required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "An Organization API Key is required for this target User operation.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"404": {
"description": "The ordinary target User or Drive entry is unavailable in the current Organization. Disabled ordinary owners remain manageable.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"503": {
"description": "The target User Drive provider or durable entry state is unavailable.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}

DELETE /api/v1/org/users/{userId}/drive/entries

Section titled “DELETE /api/v1/org/users/{userId}/drive/entries”

Delete an Organization User’s Drive file or empty directory

Deletion is non-recursive. Unknown provider write outcomes are surfaced without an automatic retry.

Authorization: OrganizationApiKey; persisted credentials determine Organization scope. The path userId selects an ordinary target User that must belong to that Organization.

OrganizationUserDriveController_deleteEntry

[
{
"OrganizationApiKey": []
}
]
[
{
"name": "userId",
"required": true,
"in": "path",
"description": "Target ordinary End User identifier.",
"schema": {
"type": "string"
}
}
]
{
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UserDriveEntryMutationBodyDto"
}
}
}
}
{
"204": {
"description": "The target User file or empty directory was deleted."
},
"400": {
"description": "Invalid path, cursor, body, or request headers.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"401": {
"description": "An authenticated Organization API Key is required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "An Organization API Key is required for this target User operation.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"404": {
"description": "The ordinary target User or Drive entry is unavailable in the current Organization. Disabled ordinary owners remain manageable.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"409": {
"description": "The path is occupied or a directory is not empty.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"503": {
"description": "The target User Drive provider or durable entry state is unavailable.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}

GET /api/v1/org/users/{userId}/drive/files/content

Section titled “GET /api/v1/org/users/{userId}/drive/files/content”

Read complete content from an Organization User’s Drive file

Authorization: OrganizationApiKey; persisted credentials determine Organization scope. The path userId selects an ordinary target User that must belong to that Organization.

OrganizationUserDriveController_readContent

[
{
"OrganizationApiKey": []
}
]
[
{
"name": "userId",
"required": true,
"in": "path",
"description": "Target ordinary End User identifier.",
"schema": {
"type": "string"
}
},
{
"name": "fileId",
"required": false,
"in": "query",
"schema": {
"maxLength": 128,
"type": "string"
}
},
{
"name": "path",
"required": false,
"in": "query",
"schema": {
"maxLength": 1024,
"type": "string"
}
}
]
{
"200": {
"content": {
"*/*": {
"schema": {
"type": "string",
"format": "binary"
}
}
},
"headers": {
"Cache-Control": {
"schema": {
"type": "string",
"example": "private, no-store"
}
},
"Content-Disposition": {
"schema": {
"type": "string"
}
},
"Content-Length": {
"schema": {
"type": "string"
}
},
"Content-Type": {
"schema": {
"type": "string"
}
},
"ETag": {
"schema": {
"type": "string"
}
},
"X-Content-Type-Options": {
"schema": {
"type": "string",
"example": "nosniff"
}
}
},
"description": ""
},
"400": {
"description": "Invalid path, cursor, body, or request headers.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"401": {
"description": "An authenticated Organization API Key is required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "An Organization API Key is required for this target User operation.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"404": {
"description": "The ordinary target User or Drive entry is unavailable in the current Organization. Disabled ordinary owners remain manageable.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"503": {
"description": "The target User Drive provider or durable entry state is unavailable.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}

PUT /api/v1/org/users/{userId}/drive/files/content

Section titled “PUT /api/v1/org/users/{userId}/drive/files/content”

Create or replace an Organization User’s Drive file

The complete byte body is verified before the new metadata and ETag are returned. Existing files require their current If-Match value.

Authorization: OrganizationApiKey; persisted credentials determine Organization scope. The path userId selects an ordinary target User that must belong to that Organization.

OrganizationUserDriveController_writeContent

[
{
"OrganizationApiKey": []
}
]
[
{
"name": "userId",
"required": true,
"in": "path",
"description": "Target ordinary End User identifier.",
"schema": {
"type": "string"
}
},
{
"name": "fileId",
"required": false,
"in": "query",
"schema": {
"maxLength": 128,
"type": "string"
}
},
{
"name": "path",
"required": false,
"in": "query",
"schema": {
"maxLength": 1024,
"type": "string"
}
},
{
"name": "Content-Length",
"in": "header",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "If-Match",
"in": "header",
"required": false,
"schema": {
"type": "string"
}
},
{
"name": "Idempotency-Key",
"in": "header",
"required": true,
"schema": {
"type": "string"
}
}
]
{
"required": true,
"content": {
"application/octet-stream": {
"schema": {
"type": "string",
"format": "binary"
}
}
}
}
{
"200": {
"headers": {
"ETag": {
"schema": {
"type": "string"
}
}
},
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UserDriveEntryResponseDto"
}
}
}
},
"400": {
"description": "Invalid path, cursor, body, or request headers.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"401": {
"description": "An authenticated Organization API Key is required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "An Organization API Key is required for this target User operation.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"404": {
"description": "The ordinary target User or Drive entry is unavailable in the current Organization. Disabled ordinary owners remain manageable.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"409": {
"description": "The path is occupied by a directory or the idempotency key was reused.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"412": {
"description": "The supplied If-Match value is stale.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"413": {
"description": "The complete body exceeds the Drive file limit.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"428": {
"description": "If-Match is required when replacing an existing file.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"503": {
"description": "The target User Drive provider or durable entry state is unavailable.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}

Authorization: OrganizationApiKey; persisted credentials determine Organization and End User scope.

OrganizationUserFilesController_list

[
{
"OrganizationApiKey": []
}
]
[
{
"name": "userId",
"required": true,
"in": "path",
"schema": {
"type": "string"
}
},
{
"name": "history",
"required": false,
"in": "query",
"schema": {
"default": "false",
"type": "string",
"enum": [
"true",
"false"
]
}
},
{
"name": "limit",
"required": false,
"in": "query",
"schema": {
"minimum": 1,
"maximum": 100,
"exclusiveMaximum": false,
"exclusiveMinimum": false,
"default": 50,
"type": "integer"
}
},
{
"name": "cursor",
"required": false,
"in": "query",
"schema": {
"minLength": 1,
"maxLength": 2048,
"type": "string"
}
}
]
{
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FilesPageDto"
}
}
}
},
"400": {
"description": "Invalid input or content digest.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"401": {
"description": "A current Organization API Key is required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "An Organization API Key is required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"404": {
"description": "The ordinary User or owned File is unavailable.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"409": {
"description": "Upload state or idempotency conflict.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"413": {
"description": "upload_requires_multipart or upload_too_large; read the current upload limits.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"422": {
"description": "upload_integrity_failed: content does not match the declared identity.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"503": {
"description": "Storage or required durable audit is unavailable.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}

GET /api/v1/org/users/{userId}/files/{fileId}

Section titled “GET /api/v1/org/users/{userId}/files/{fileId}”

Authorization: OrganizationApiKey; persisted credentials determine Organization and End User scope.

OrganizationUserFilesController_get

[
{
"OrganizationApiKey": []
}
]
[
{
"name": "userId",
"required": true,
"in": "path",
"schema": {
"type": "string"
}
},
{
"name": "fileId",
"required": true,
"in": "path",
"schema": {
"type": "string"
}
}
]
{
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FileResponseDto"
}
}
}
},
"400": {
"description": "Invalid input or content digest.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"401": {
"description": "A current Organization API Key is required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "An Organization API Key is required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"404": {
"description": "The ordinary User or owned File is unavailable.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"409": {
"description": "Upload state or idempotency conflict.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"413": {
"description": "upload_requires_multipart or upload_too_large; read the current upload limits.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"422": {
"description": "upload_integrity_failed: content does not match the declared identity.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"503": {
"description": "Storage or required durable audit is unavailable.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}

GET /api/v1/org/users/{userId}/files/{fileId}/content

Section titled “GET /api/v1/org/users/{userId}/files/{fileId}/content”

Read an ordinary User File, including disabled owners

Bounded content is verified before delivery. Files above 50 MiB return a short-lived download ticket bound to the exact issuing Organization credential. Revocation and same-ID rotation deny new redemption; admitted transfers may finish.

Authorization: OrganizationApiKey; persisted credentials determine Organization and End User scope.

OrganizationUserFilesController_content

[
{
"OrganizationApiKey": []
}
]
[
{
"name": "userId",
"required": true,
"in": "path",
"schema": {
"type": "string"
}
},
{
"name": "fileId",
"required": true,
"in": "path",
"schema": {
"type": "string"
}
}
]
{
"200": {
"content": {
"*/*": {
"schema": {
"type": "string",
"format": "binary"
}
},
"application/vnd.tidb-link.file-download+json": {
"schema": {
"type": "object",
"properties": {
"url": {
"type": "string"
},
"expiresAt": {
"type": "string",
"format": "date-time"
},
"byteSize": {
"type": "integer"
},
"sha256": {
"type": "string"
}
},
"required": [
"url",
"expiresAt",
"byteSize",
"sha256"
]
}
}
},
"description": ""
},
"400": {
"description": "Invalid input or content digest.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"401": {
"description": "A current Organization API Key is required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "An Organization API Key is required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"404": {
"description": "The ordinary User or owned File is unavailable.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"409": {
"description": "Upload state or idempotency conflict.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"413": {
"description": "upload_requires_multipart or upload_too_large; read the current upload limits.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"422": {
"description": "upload_integrity_failed: content does not match the declared identity.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"503": {
"description": "Storage or required durable audit is unavailable.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}

GET /api/v1/org/users/{userId}/drive/upload-capabilities

Section titled “GET /api/v1/org/users/{userId}/drive/upload-capabilities”

Discover the effective inline and multipart upload limits

Authorization: OrganizationApiKey; persisted credentials determine Organization scope. The path userId selects an ordinary target User that must belong to that Organization.

OrganizationUserFilesController_capabilities

[
{
"OrganizationApiKey": []
}
]
[
{
"name": "userId",
"required": true,
"in": "path",
"schema": {
"type": "string"
}
}
]
{
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicUserFileUploadCapabilitiesOpenApiDto"
}
}
}
},
"400": {
"description": "Invalid input or content digest.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"401": {
"description": "A current Organization API Key is required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "An Organization API Key is required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"404": {
"description": "The ordinary User or owned File is unavailable.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"409": {
"description": "Upload state or idempotency conflict.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"413": {
"description": "upload_requires_multipart or upload_too_large; read the current upload limits.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"422": {
"description": "upload_integrity_failed: content does not match the declared identity.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"503": {
"description": "Storage or required durable audit is unavailable.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}

POST /api/v1/org/users/{userId}/drive/uploads

Section titled “POST /api/v1/org/users/{userId}/drive/uploads”

Create or replay an ordinary User upload with current Organization authority

The Idempotency-Key binds the exact input, File and fixed expiry. Fresh valid Organization authority can recover the same owned upload after rotation or revocation. Inline responses include contentUrl and an optional core upload ticket; multipart responses include partSize and totalParts.

Authorization: OrganizationApiKey; persisted credentials determine Organization scope. The path userId selects an ordinary target User that must belong to that Organization.

OrganizationUserFilesController_create

[
{
"OrganizationApiKey": []
}
]
[
{
"name": "userId",
"required": true,
"in": "path",
"schema": {
"type": "string"
}
},
{
"name": "Idempotency-Key",
"in": "header",
"required": true,
"schema": {
"type": "string"
}
}
]
{
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreatePublicUserFileUploadBodyOpenApiDto"
}
}
}
}
{
"201": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FileUploadResponseDto"
}
}
}
},
"400": {
"description": "Invalid input or content digest.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"401": {
"description": "A current Organization API Key is required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "An Organization API Key is required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"404": {
"description": "The ordinary User or owned File is unavailable.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"409": {
"description": "Upload state or idempotency conflict.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"413": {
"description": "upload_requires_multipart or upload_too_large; read the current upload limits.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"422": {
"description": "upload_integrity_failed: content does not match the declared identity.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"503": {
"description": "Storage or required durable audit is unavailable.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}

GET /api/v1/org/users/{userId}/drive/uploads/{uploadId}

Section titled “GET /api/v1/org/users/{userId}/drive/uploads/{uploadId}”

Authorization: OrganizationApiKey; persisted credentials determine Organization scope. The path userId selects an ordinary target User that must belong to that Organization.

OrganizationUserFilesController_status

[
{
"OrganizationApiKey": []
}
]
[
{
"name": "userId",
"required": true,
"in": "path",
"schema": {
"type": "string"
}
},
{
"name": "uploadId",
"required": true,
"in": "path",
"schema": {
"type": "string"
}
}
]
{
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UploadStatusResponseDto"
}
}
}
},
"400": {
"description": "Invalid input or content digest.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"401": {
"description": "A current Organization API Key is required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "An Organization API Key is required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"404": {
"description": "The ordinary User or owned File is unavailable.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"409": {
"description": "Upload state or idempotency conflict.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"413": {
"description": "upload_requires_multipart or upload_too_large; read the current upload limits.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"422": {
"description": "upload_integrity_failed: content does not match the declared identity.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"503": {
"description": "Storage or required durable audit is unavailable.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}

DELETE /api/v1/org/users/{userId}/drive/uploads/{uploadId}

Section titled “DELETE /api/v1/org/users/{userId}/drive/uploads/{uploadId}”

Authorization: OrganizationApiKey; persisted credentials determine Organization scope. The path userId selects an ordinary target User that must belong to that Organization.

OrganizationUserFilesController_abort

[
{
"OrganizationApiKey": []
}
]
[
{
"name": "userId",
"required": true,
"in": "path",
"schema": {
"type": "string"
}
},
{
"name": "uploadId",
"required": true,
"in": "path",
"schema": {
"type": "string"
}
}
]
{
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FileResponseDto"
}
}
}
},
"400": {
"description": "Invalid input or content digest.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"401": {
"description": "A current Organization API Key is required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "An Organization API Key is required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"404": {
"description": "The ordinary User or owned File is unavailable.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"409": {
"description": "Upload state or idempotency conflict.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"413": {
"description": "upload_requires_multipart or upload_too_large; read the current upload limits.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"422": {
"description": "upload_integrity_failed: content does not match the declared identity.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"503": {
"description": "Storage or required durable audit is unavailable.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}

PUT /api/v1/org/users/{userId}/drive/uploads/{uploadId}/content

Section titled “PUT /api/v1/org/users/{userId}/drive/uploads/{uploadId}/content”

Authorization: OrganizationApiKey; persisted credentials determine Organization scope. The path userId selects an ordinary target User that must belong to that Organization.

OrganizationUserFilesController_upload

[
{
"OrganizationApiKey": []
}
]
[
{
"name": "userId",
"required": true,
"in": "path",
"schema": {
"type": "string"
}
},
{
"name": "uploadId",
"required": true,
"in": "path",
"schema": {
"type": "string"
}
},
{
"name": "Content-Digest",
"in": "header",
"description": "RFC 9530 SHA-256 digest.",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "Content-Length",
"in": "header",
"required": true,
"schema": {
"type": "string"
}
}
]
{
"required": true,
"content": {
"application/octet-stream": {
"schema": {
"type": "string",
"format": "binary"
}
}
}
}
{
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FileResponseDto"
}
}
}
},
"400": {
"description": "Invalid input or content digest.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"401": {
"description": "A current Organization API Key is required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "An Organization API Key is required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"404": {
"description": "The ordinary User or owned File is unavailable.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"409": {
"description": "Upload state or idempotency conflict.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"413": {
"description": "upload_requires_multipart or upload_too_large; read the current upload limits.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"422": {
"description": "upload_integrity_failed: content does not match the declared identity.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"503": {
"description": "Storage or required durable audit is unavailable.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}

POST /api/v1/org/users/{userId}/drive/uploads/{uploadId}/parts/{partNumber}/presign

Section titled “POST /api/v1/org/users/{userId}/drive/uploads/{uploadId}/parts/{partNumber}/presign”

Bind a multipart part digest and obtain its provider upload grant

Each request checks the exact current Organization Key and active ordinary owner before durable audit and provider access. PUT exactly the returned size and every returned header to the provider URL, then retain its ETag. This URL is a separate provider grant: Organization Key rotation or revocation does not revoke it. New core presign and completion requests still require current authority.

Authorization: OrganizationApiKey; persisted credentials determine Organization scope. The path userId selects an ordinary target User that must belong to that Organization.

OrganizationUserFilesController_presignPart

[
{
"OrganizationApiKey": []
}
]
[
{
"name": "userId",
"required": true,
"in": "path",
"schema": {
"type": "string"
}
},
{
"name": "uploadId",
"required": true,
"in": "path",
"schema": {
"type": "string"
}
},
{
"name": "partNumber",
"required": true,
"in": "path",
"schema": {
"type": "string"
}
}
]
{
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PresignPublicUserFileUploadPartBodyOpenApiDto"
}
}
}
}
{
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicUserFileUploadPartResponseOpenApiDto"
}
}
}
},
"400": {
"description": "Invalid input or content digest.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"401": {
"description": "A current Organization API Key is required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "An Organization API Key is required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"404": {
"description": "The ordinary User or owned File is unavailable.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"409": {
"description": "Upload state or idempotency conflict.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"413": {
"description": "upload_requires_multipart or upload_too_large; read the current upload limits.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"422": {
"description": "upload_integrity_failed: content does not match the declared identity.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"503": {
"description": "Storage or required durable audit is unavailable.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}

POST /api/v1/org/users/{userId}/drive/uploads/{uploadId}/complete

Section titled “POST /api/v1/org/users/{userId}/drive/uploads/{uploadId}/complete”

Confirm a whole-file verified upload with current Organization authority

Inline uploads accept an empty object. Multipart uploads submit every part in ascending order with its bound SHA-256 and provider ETag. Success requires exact whole-file size and digest verification; retries return the same ready File. An admitted completion may finish after Key invalidation, while new requests require current authority.

Authorization: OrganizationApiKey; persisted credentials determine Organization scope. The path userId selects an ordinary target User that must belong to that Organization.

OrganizationUserFilesController_complete

[
{
"OrganizationApiKey": []
}
]
[
{
"name": "userId",
"required": true,
"in": "path",
"schema": {
"type": "string"
}
},
{
"name": "uploadId",
"required": true,
"in": "path",
"schema": {
"type": "string"
}
}
]
{
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FileConfirmationDto"
}
}
}
}
{
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FileResponseDto"
}
}
}
},
"400": {
"description": "Invalid input or content digest.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"401": {
"description": "A current Organization API Key is required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "An Organization API Key is required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"404": {
"description": "The ordinary User or owned File is unavailable.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"409": {
"description": "Upload state or idempotency conflict.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"413": {
"description": "upload_requires_multipart or upload_too_large; read the current upload limits.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"422": {
"description": "upload_integrity_failed: content does not match the declared identity.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"503": {
"description": "Storage or required durable audit is unavailable.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}

List the Organization’s MCP server registrations.

Authorization: OrganizationApiKey; persisted credentials determine Organization scope; no End User scope. Changes are attributed to the authentic Organization API Key in management audit; a Key revoked or rotated before the change commits is refused. User API Keys have no MCP routes. MCP Server Registrations belong to the Organization.

OrganizationMcpServersController_list

[
{
"OrganizationApiKey": []
}
]
{
"200": {
"description": "The Organization's MCP registrations.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"servers"
],
"additionalProperties": false,
"properties": {
"servers": {
"type": "array",
"items": {
"type": "object",
"required": [
"serverId",
"organizationId",
"displayName",
"endpointUrl",
"endpointVersion",
"transport",
"authorizationMode",
"status",
"serverVersion",
"createdByUserId",
"createdByPlatformAccountId",
"createdByOrganizationMemberId",
"createdAt",
"updatedAt",
"observation",
"oauthClient",
"authorization"
],
"additionalProperties": false,
"properties": {
"serverId": {
"type": "string",
"pattern": "^mcp_[a-f0-9-]{36}$"
},
"organizationId": {
"type": "string"
},
"displayName": {
"type": "string"
},
"endpointUrl": {
"type": "string",
"format": "uri",
"pattern": "^https:\\/\\/(?![^/?#]*@)[^#]+$"
},
"endpointVersion": {
"type": "integer",
"minimum": 1
},
"transport": {
"type": "string",
"enum": [
"streamable_http"
]
},
"authorizationMode": {
"type": "string",
"enum": [
"none",
"organization_static_token",
"end_user_static_token",
"organization_client_credentials",
"organization_oauth",
"end_user_oauth"
]
},
"status": {
"type": "string",
"enum": [
"enabled",
"disabled"
]
},
"serverVersion": {
"type": "integer",
"minimum": 1
},
"createdByUserId": {
"type": "string",
"nullable": true
},
"createdByPlatformAccountId": {
"type": "string",
"nullable": true
},
"createdByOrganizationMemberId": {
"type": "string",
"nullable": true
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"updatedAt": {
"type": "string",
"format": "date-time"
},
"observation": {
"type": "object",
"nullable": true,
"description": "The protocol era last detected at the current endpoint; diagnostic, never permission.",
"required": [
"era",
"protocolVersion"
],
"additionalProperties": false,
"properties": {
"era": {
"type": "string",
"enum": [
"modern",
"legacy"
]
},
"protocolVersion": {
"type": "string"
}
}
},
"oauthClient": {
"type": "object",
"nullable": true,
"description": "The registration's pre-registered OAuth client, by its client ID; null when none is set. Its secret is write-only.",
"required": [
"clientId"
],
"additionalProperties": false,
"properties": {
"clientId": {
"type": "string"
}
}
},
"authorization": {
"type": "object",
"description": "The Organization's MCP Authorization of this registration. Its credential is write-only. Null while it has none, and always for modes `end_user_static_token` and `end_user_oauth`, whose authorizations belong to each End User.",
"required": [
"owner",
"state",
"invalidReason",
"requiredScope",
"hasCredential",
"catalog",
"updatedAt"
],
"additionalProperties": false,
"properties": {
"owner": {
"type": "object",
"required": [
"kind"
],
"additionalProperties": false,
"properties": {
"kind": {
"type": "string",
"enum": [
"organization"
]
}
}
},
"state": {
"type": "string",
"enum": [
"usable",
"invalid",
"revoked"
]
},
"invalidReason": {
"type": "string",
"nullable": true,
"enum": [
"endpoint_changed",
"mode_changed",
"unauthorized",
"forbidden",
"insufficient_scope",
"token_rejected",
"client_changed"
],
"description": "Why an invalid authorization stopped being usable; null otherwise. endpoint_changed, mode_changed and client_changed (another OAuth client ID) follow a registration change. During a Turn the server refused the credential: unauthorized (HTTP 401), forbidden (403) or insufficient_scope (403 with that challenge). token_rejected: the authorization server rejected the request for an access token, with the client credentials or the refresh token, or an expired OAuth token has no refresh token. Setting the credential again, or authorizing again with OAuth, makes the authorization usable again."
},
"requiredScope": {
"type": "string",
"nullable": true,
"maxLength": 512,
"description": "The scope the server said it requires when it refused the credential with insufficient_scope, when it named a valid one; null otherwise. Authorizing again with OAuth requests it together with the scope the authorization was granted."
},
"hasCredential": {
"type": "boolean"
},
"catalog": {
"type": "object",
"nullable": true,
"description": "The catalog new AgentRuns freeze; null until discovery succeeds under this authorization.",
"required": [
"discoveredAt",
"toolNames"
],
"additionalProperties": false,
"properties": {
"discoveredAt": {
"type": "string",
"format": "date-time",
"description": "When the server's tools were last listed, by discovery or before a call."
},
"toolNames": {
"type": "array",
"items": {
"type": "string"
}
}
}
},
"updatedAt": {
"type": "string",
"format": "date-time"
}
},
"nullable": true
}
}
}
}
}
}
}
}
},
"400": {
"description": "Invalid MCP request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"401": {
"description": "authentication_required: missing credentials, or the acting credential was revoked or rotated before the change committed.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "The credential cannot manage this Organization's MCP registrations; auth_kind_forbidden for an API Key that is not an Organization API Key.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}

Create an enabled MCP server registration.

A registration in mode none is usable at once and its catalog is discovered now. A registration in mode organization_static_token becomes usable when its token is set, and one in mode organization_client_credentials when its OAuth client credentials are set and obtain an access token. A registration in mode organization_oauth takes an optional oauthClient and becomes usable when a Console owner authorizes it with OAuth, or an Application Server confirms the OAuth authorization it started with its Organization API Key. In modes end_user_static_token and end_user_oauth each End User has their own MCP Authorization, which becomes usable when an Application Server sets that End User’s token, or confirms the OAuth authorization it started for that End User; end_user_oauth takes an optional oauthClient too. A Session uses its owner’s.

Authorization: OrganizationApiKey; persisted credentials determine Organization scope; no End User scope. Changes are attributed to the authentic Organization API Key in management audit; a Key revoked or rotated before the change commits is refused. User API Keys have no MCP routes. MCP Server Registrations belong to the Organization.

OrganizationMcpServersController_create

[
{
"OrganizationApiKey": []
}
]
{
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"displayName",
"endpointUrl",
"authorizationMode"
],
"additionalProperties": false,
"properties": {
"displayName": {
"type": "string",
"minLength": 1,
"maxLength": 255
},
"endpointUrl": {
"type": "string",
"format": "uri",
"maxLength": 2048,
"pattern": "^https:\\/\\/(?![^/?#]*@)[^#]+$"
},
"authorizationMode": {
"type": "string",
"enum": [
"none",
"organization_static_token",
"end_user_static_token",
"organization_client_credentials",
"organization_oauth",
"end_user_oauth"
]
},
"oauthClient": {
"type": "object",
"description": "The registration's pre-registered OAuth client, for modes `organization_oauth` and `end_user_oauth`: Agent Service presents it to the authorization server, whose consent page then shows the client's own name. Register Agent Service's OAuth callback, `https://<PUBLIC_API_URL host>/api/v1/mcp/oauth/callback`, as one of its redirect URIs. The secret is write-only. Without one, Agent Service presents the deployment's Client ID Metadata Document, or registers a client of its own with Dynamic Client Registration, and consent pages show the platform name. A pre-registered client always takes precedence. Setting a client with another `clientId` invalidates the registration's MCP Authorizations; a new secret for the same `clientId` does not.",
"required": [
"clientId",
"clientSecret"
],
"additionalProperties": false,
"properties": {
"clientId": {
"type": "string",
"minLength": 1,
"maxLength": 1024
},
"clientSecret": {
"type": "string",
"minLength": 1,
"maxLength": 4096,
"writeOnly": true
}
}
}
}
}
}
}
}
{
"201": {
"description": "Enabled MCP registration.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"serverId",
"organizationId",
"displayName",
"endpointUrl",
"endpointVersion",
"transport",
"authorizationMode",
"status",
"serverVersion",
"createdByUserId",
"createdByPlatformAccountId",
"createdByOrganizationMemberId",
"createdAt",
"updatedAt",
"observation",
"oauthClient",
"authorization"
],
"additionalProperties": false,
"properties": {
"serverId": {
"type": "string",
"pattern": "^mcp_[a-f0-9-]{36}$"
},
"organizationId": {
"type": "string"
},
"displayName": {
"type": "string"
},
"endpointUrl": {
"type": "string",
"format": "uri",
"pattern": "^https:\\/\\/(?![^/?#]*@)[^#]+$"
},
"endpointVersion": {
"type": "integer",
"minimum": 1
},
"transport": {
"type": "string",
"enum": [
"streamable_http"
]
},
"authorizationMode": {
"type": "string",
"enum": [
"none",
"organization_static_token",
"end_user_static_token",
"organization_client_credentials",
"organization_oauth",
"end_user_oauth"
]
},
"status": {
"type": "string",
"enum": [
"enabled",
"disabled"
]
},
"serverVersion": {
"type": "integer",
"minimum": 1
},
"createdByUserId": {
"type": "string",
"nullable": true
},
"createdByPlatformAccountId": {
"type": "string",
"nullable": true
},
"createdByOrganizationMemberId": {
"type": "string",
"nullable": true
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"updatedAt": {
"type": "string",
"format": "date-time"
},
"observation": {
"type": "object",
"nullable": true,
"description": "The protocol era last detected at the current endpoint; diagnostic, never permission.",
"required": [
"era",
"protocolVersion"
],
"additionalProperties": false,
"properties": {
"era": {
"type": "string",
"enum": [
"modern",
"legacy"
]
},
"protocolVersion": {
"type": "string"
}
}
},
"oauthClient": {
"type": "object",
"nullable": true,
"description": "The registration's pre-registered OAuth client, by its client ID; null when none is set. Its secret is write-only.",
"required": [
"clientId"
],
"additionalProperties": false,
"properties": {
"clientId": {
"type": "string"
}
}
},
"authorization": {
"type": "object",
"description": "The Organization's MCP Authorization of this registration. Its credential is write-only. Null while it has none, and always for modes `end_user_static_token` and `end_user_oauth`, whose authorizations belong to each End User.",
"required": [
"owner",
"state",
"invalidReason",
"requiredScope",
"hasCredential",
"catalog",
"updatedAt"
],
"additionalProperties": false,
"properties": {
"owner": {
"type": "object",
"required": [
"kind"
],
"additionalProperties": false,
"properties": {
"kind": {
"type": "string",
"enum": [
"organization"
]
}
}
},
"state": {
"type": "string",
"enum": [
"usable",
"invalid",
"revoked"
]
},
"invalidReason": {
"type": "string",
"nullable": true,
"enum": [
"endpoint_changed",
"mode_changed",
"unauthorized",
"forbidden",
"insufficient_scope",
"token_rejected",
"client_changed"
],
"description": "Why an invalid authorization stopped being usable; null otherwise. endpoint_changed, mode_changed and client_changed (another OAuth client ID) follow a registration change. During a Turn the server refused the credential: unauthorized (HTTP 401), forbidden (403) or insufficient_scope (403 with that challenge). token_rejected: the authorization server rejected the request for an access token, with the client credentials or the refresh token, or an expired OAuth token has no refresh token. Setting the credential again, or authorizing again with OAuth, makes the authorization usable again."
},
"requiredScope": {
"type": "string",
"nullable": true,
"maxLength": 512,
"description": "The scope the server said it requires when it refused the credential with insufficient_scope, when it named a valid one; null otherwise. Authorizing again with OAuth requests it together with the scope the authorization was granted."
},
"hasCredential": {
"type": "boolean"
},
"catalog": {
"type": "object",
"nullable": true,
"description": "The catalog new AgentRuns freeze; null until discovery succeeds under this authorization.",
"required": [
"discoveredAt",
"toolNames"
],
"additionalProperties": false,
"properties": {
"discoveredAt": {
"type": "string",
"format": "date-time",
"description": "When the server's tools were last listed, by discovery or before a call."
},
"toolNames": {
"type": "array",
"items": {
"type": "string"
}
}
}
},
"updatedAt": {
"type": "string",
"format": "date-time"
}
},
"nullable": true
}
}
}
}
}
},
"400": {
"description": "Invalid MCP request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"401": {
"description": "authentication_required: missing credentials, or the acting credential was revoked or rotated before the change committed.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "The credential cannot manage this Organization's MCP registrations; auth_kind_forbidden for an API Key that is not an Organization API Key.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"409": {
"description": "Registration name already exists in this Organization.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}

Get one MCP server registration.

Authorization: OrganizationApiKey; persisted credentials determine Organization scope; no End User scope. Changes are attributed to the authentic Organization API Key in management audit; a Key revoked or rotated before the change commits is refused. User API Keys have no MCP routes. MCP Server Registrations belong to the Organization.

OrganizationMcpServersController_get

[
{
"OrganizationApiKey": []
}
]
[
{
"name": "serverId",
"required": true,
"in": "path",
"schema": {
"type": "string",
"pattern": "^mcp_[a-f0-9-]{36}$"
}
}
]
{
"200": {
"description": "MCP registration.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"serverId",
"organizationId",
"displayName",
"endpointUrl",
"endpointVersion",
"transport",
"authorizationMode",
"status",
"serverVersion",
"createdByUserId",
"createdByPlatformAccountId",
"createdByOrganizationMemberId",
"createdAt",
"updatedAt",
"observation",
"oauthClient",
"authorization"
],
"additionalProperties": false,
"properties": {
"serverId": {
"type": "string",
"pattern": "^mcp_[a-f0-9-]{36}$"
},
"organizationId": {
"type": "string"
},
"displayName": {
"type": "string"
},
"endpointUrl": {
"type": "string",
"format": "uri",
"pattern": "^https:\\/\\/(?![^/?#]*@)[^#]+$"
},
"endpointVersion": {
"type": "integer",
"minimum": 1
},
"transport": {
"type": "string",
"enum": [
"streamable_http"
]
},
"authorizationMode": {
"type": "string",
"enum": [
"none",
"organization_static_token",
"end_user_static_token",
"organization_client_credentials",
"organization_oauth",
"end_user_oauth"
]
},
"status": {
"type": "string",
"enum": [
"enabled",
"disabled"
]
},
"serverVersion": {
"type": "integer",
"minimum": 1
},
"createdByUserId": {
"type": "string",
"nullable": true
},
"createdByPlatformAccountId": {
"type": "string",
"nullable": true
},
"createdByOrganizationMemberId": {
"type": "string",
"nullable": true
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"updatedAt": {
"type": "string",
"format": "date-time"
},
"observation": {
"type": "object",
"nullable": true,
"description": "The protocol era last detected at the current endpoint; diagnostic, never permission.",
"required": [
"era",
"protocolVersion"
],
"additionalProperties": false,
"properties": {
"era": {
"type": "string",
"enum": [
"modern",
"legacy"
]
},
"protocolVersion": {
"type": "string"
}
}
},
"oauthClient": {
"type": "object",
"nullable": true,
"description": "The registration's pre-registered OAuth client, by its client ID; null when none is set. Its secret is write-only.",
"required": [
"clientId"
],
"additionalProperties": false,
"properties": {
"clientId": {
"type": "string"
}
}
},
"authorization": {
"type": "object",
"description": "The Organization's MCP Authorization of this registration. Its credential is write-only. Null while it has none, and always for modes `end_user_static_token` and `end_user_oauth`, whose authorizations belong to each End User.",
"required": [
"owner",
"state",
"invalidReason",
"requiredScope",
"hasCredential",
"catalog",
"updatedAt"
],
"additionalProperties": false,
"properties": {
"owner": {
"type": "object",
"required": [
"kind"
],
"additionalProperties": false,
"properties": {
"kind": {
"type": "string",
"enum": [
"organization"
]
}
}
},
"state": {
"type": "string",
"enum": [
"usable",
"invalid",
"revoked"
]
},
"invalidReason": {
"type": "string",
"nullable": true,
"enum": [
"endpoint_changed",
"mode_changed",
"unauthorized",
"forbidden",
"insufficient_scope",
"token_rejected",
"client_changed"
],
"description": "Why an invalid authorization stopped being usable; null otherwise. endpoint_changed, mode_changed and client_changed (another OAuth client ID) follow a registration change. During a Turn the server refused the credential: unauthorized (HTTP 401), forbidden (403) or insufficient_scope (403 with that challenge). token_rejected: the authorization server rejected the request for an access token, with the client credentials or the refresh token, or an expired OAuth token has no refresh token. Setting the credential again, or authorizing again with OAuth, makes the authorization usable again."
},
"requiredScope": {
"type": "string",
"nullable": true,
"maxLength": 512,
"description": "The scope the server said it requires when it refused the credential with insufficient_scope, when it named a valid one; null otherwise. Authorizing again with OAuth requests it together with the scope the authorization was granted."
},
"hasCredential": {
"type": "boolean"
},
"catalog": {
"type": "object",
"nullable": true,
"description": "The catalog new AgentRuns freeze; null until discovery succeeds under this authorization.",
"required": [
"discoveredAt",
"toolNames"
],
"additionalProperties": false,
"properties": {
"discoveredAt": {
"type": "string",
"format": "date-time",
"description": "When the server's tools were last listed, by discovery or before a call."
},
"toolNames": {
"type": "array",
"items": {
"type": "string"
}
}
}
},
"updatedAt": {
"type": "string",
"format": "date-time"
}
},
"nullable": true
}
}
}
}
}
},
"400": {
"description": "Invalid MCP request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"401": {
"description": "authentication_required: missing credentials, or the acting credential was revoked or rotated before the change committed.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "The credential cannot manage this Organization's MCP registrations; auth_kind_forbidden for an API Key that is not an Organization API Key.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"404": {
"description": "MCP registration not found.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}

Delete an MCP server registration.

Allowed only when no non-archived AgentTemplate references the registration. Deletion removes its MCP Authorizations and destroys their stored tokens. A Session whose configuration still references the registration can no longer start a Turn (session_execution_dependency_unavailable), and bound AgentRuns dispatch no further call.

Authorization: OrganizationApiKey; persisted credentials determine Organization scope; no End User scope. Changes are attributed to the authentic Organization API Key in management audit; a Key revoked or rotated before the change commits is refused. User API Keys have no MCP routes. MCP Server Registrations belong to the Organization.

OrganizationMcpServersController_delete

[
{
"OrganizationApiKey": []
}
]
[
{
"name": "serverId",
"required": true,
"in": "path",
"schema": {
"type": "string",
"pattern": "^mcp_[a-f0-9-]{36}$"
}
}
]
{
"204": {
"description": "Registration deleted."
},
"400": {
"description": "Invalid MCP request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"401": {
"description": "authentication_required: missing credentials, or the acting credential was revoked or rotated before the change committed.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "The credential cannot manage this Organization's MCP registrations; auth_kind_forbidden for an API Key that is not an Organization API Key.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"404": {
"description": "MCP registration not found.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"409": {
"description": "`mcp_server_delete_blocked`: non-archived AgentTemplates still reference the registration; `details.templates` lists them as `{templateId, templateName}`.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}

Edit an MCP server registration.

Changing the endpoint, the MCP Authorization Mode or the OAuth client’s clientId invalidates the registration’s MCP Authorizations together with their catalogs and revokes their credentials; changing the display name or the OAuth client secret does not. oauthClient: null removes the pre-registered OAuth client, and a mode that takes none removes any OAuth client. A client Agent Service registered with Dynamic Client Registration is discarded with the endpoint, and replaced by a pre-registered client. In mode none the catalog is then discovered again.

Authorization: OrganizationApiKey; persisted credentials determine Organization scope; no End User scope. Changes are attributed to the authentic Organization API Key in management audit; a Key revoked or rotated before the change commits is refused. User API Keys have no MCP routes. MCP Server Registrations belong to the Organization.

OrganizationMcpServersController_update

[
{
"OrganizationApiKey": []
}
]
[
{
"name": "serverId",
"required": true,
"in": "path",
"schema": {
"type": "string",
"pattern": "^mcp_[a-f0-9-]{36}$"
}
}
]
{
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"expectedServerVersion"
],
"minProperties": 2,
"additionalProperties": false,
"properties": {
"expectedServerVersion": {
"type": "integer",
"minimum": 1
},
"displayName": {
"type": "string",
"minLength": 1,
"maxLength": 255
},
"endpointUrl": {
"type": "string",
"format": "uri",
"maxLength": 2048,
"pattern": "^https:\\/\\/(?![^/?#]*@)[^#]+$"
},
"authorizationMode": {
"type": "string",
"enum": [
"none",
"organization_static_token",
"end_user_static_token",
"organization_client_credentials",
"organization_oauth",
"end_user_oauth"
]
},
"oauthClient": {
"type": "object",
"description": "The registration's pre-registered OAuth client, for modes `organization_oauth` and `end_user_oauth`: Agent Service presents it to the authorization server, whose consent page then shows the client's own name. Register Agent Service's OAuth callback, `https://<PUBLIC_API_URL host>/api/v1/mcp/oauth/callback`, as one of its redirect URIs. The secret is write-only. Without one, Agent Service presents the deployment's Client ID Metadata Document, or registers a client of its own with Dynamic Client Registration, and consent pages show the platform name. A pre-registered client always takes precedence. Setting a client with another `clientId` invalidates the registration's MCP Authorizations; a new secret for the same `clientId` does not.",
"required": [
"clientId",
"clientSecret"
],
"additionalProperties": false,
"properties": {
"clientId": {
"type": "string",
"minLength": 1,
"maxLength": 1024
},
"clientSecret": {
"type": "string",
"minLength": 1,
"maxLength": 4096,
"writeOnly": true
}
},
"nullable": true
}
}
}
}
}
}
{
"200": {
"description": "Updated MCP registration.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"serverId",
"organizationId",
"displayName",
"endpointUrl",
"endpointVersion",
"transport",
"authorizationMode",
"status",
"serverVersion",
"createdByUserId",
"createdByPlatformAccountId",
"createdByOrganizationMemberId",
"createdAt",
"updatedAt",
"observation",
"oauthClient",
"authorization"
],
"additionalProperties": false,
"properties": {
"serverId": {
"type": "string",
"pattern": "^mcp_[a-f0-9-]{36}$"
},
"organizationId": {
"type": "string"
},
"displayName": {
"type": "string"
},
"endpointUrl": {
"type": "string",
"format": "uri",
"pattern": "^https:\\/\\/(?![^/?#]*@)[^#]+$"
},
"endpointVersion": {
"type": "integer",
"minimum": 1
},
"transport": {
"type": "string",
"enum": [
"streamable_http"
]
},
"authorizationMode": {
"type": "string",
"enum": [
"none",
"organization_static_token",
"end_user_static_token",
"organization_client_credentials",
"organization_oauth",
"end_user_oauth"
]
},
"status": {
"type": "string",
"enum": [
"enabled",
"disabled"
]
},
"serverVersion": {
"type": "integer",
"minimum": 1
},
"createdByUserId": {
"type": "string",
"nullable": true
},
"createdByPlatformAccountId": {
"type": "string",
"nullable": true
},
"createdByOrganizationMemberId": {
"type": "string",
"nullable": true
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"updatedAt": {
"type": "string",
"format": "date-time"
},
"observation": {
"type": "object",
"nullable": true,
"description": "The protocol era last detected at the current endpoint; diagnostic, never permission.",
"required": [
"era",
"protocolVersion"
],
"additionalProperties": false,
"properties": {
"era": {
"type": "string",
"enum": [
"modern",
"legacy"
]
},
"protocolVersion": {
"type": "string"
}
}
},
"oauthClient": {
"type": "object",
"nullable": true,
"description": "The registration's pre-registered OAuth client, by its client ID; null when none is set. Its secret is write-only.",
"required": [
"clientId"
],
"additionalProperties": false,
"properties": {
"clientId": {
"type": "string"
}
}
},
"authorization": {
"type": "object",
"description": "The Organization's MCP Authorization of this registration. Its credential is write-only. Null while it has none, and always for modes `end_user_static_token` and `end_user_oauth`, whose authorizations belong to each End User.",
"required": [
"owner",
"state",
"invalidReason",
"requiredScope",
"hasCredential",
"catalog",
"updatedAt"
],
"additionalProperties": false,
"properties": {
"owner": {
"type": "object",
"required": [
"kind"
],
"additionalProperties": false,
"properties": {
"kind": {
"type": "string",
"enum": [
"organization"
]
}
}
},
"state": {
"type": "string",
"enum": [
"usable",
"invalid",
"revoked"
]
},
"invalidReason": {
"type": "string",
"nullable": true,
"enum": [
"endpoint_changed",
"mode_changed",
"unauthorized",
"forbidden",
"insufficient_scope",
"token_rejected",
"client_changed"
],
"description": "Why an invalid authorization stopped being usable; null otherwise. endpoint_changed, mode_changed and client_changed (another OAuth client ID) follow a registration change. During a Turn the server refused the credential: unauthorized (HTTP 401), forbidden (403) or insufficient_scope (403 with that challenge). token_rejected: the authorization server rejected the request for an access token, with the client credentials or the refresh token, or an expired OAuth token has no refresh token. Setting the credential again, or authorizing again with OAuth, makes the authorization usable again."
},
"requiredScope": {
"type": "string",
"nullable": true,
"maxLength": 512,
"description": "The scope the server said it requires when it refused the credential with insufficient_scope, when it named a valid one; null otherwise. Authorizing again with OAuth requests it together with the scope the authorization was granted."
},
"hasCredential": {
"type": "boolean"
},
"catalog": {
"type": "object",
"nullable": true,
"description": "The catalog new AgentRuns freeze; null until discovery succeeds under this authorization.",
"required": [
"discoveredAt",
"toolNames"
],
"additionalProperties": false,
"properties": {
"discoveredAt": {
"type": "string",
"format": "date-time",
"description": "When the server's tools were last listed, by discovery or before a call."
},
"toolNames": {
"type": "array",
"items": {
"type": "string"
}
}
}
},
"updatedAt": {
"type": "string",
"format": "date-time"
}
},
"nullable": true
}
}
}
}
}
},
"400": {
"description": "Invalid MCP request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"401": {
"description": "authentication_required: missing credentials, or the acting credential was revoked or rotated before the change committed.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "The credential cannot manage this Organization's MCP registrations; auth_kind_forbidden for an API Key that is not an Organization API Key.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"404": {
"description": "MCP registration not found.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"409": {
"description": "Registration name or version conflicts.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}

POST /api/v1/org/mcp/servers/{serverId}/enable

Section titled “POST /api/v1/org/mcp/servers/{serverId}/enable”

Enable an MCP server registration.

New AgentTemplate saves, Sessions and Turns may reference it again, and bound AgentRuns dispatch again. In mode none the catalog is discovered again.

Authorization: OrganizationApiKey; persisted credentials determine Organization scope; no End User scope. Changes are attributed to the authentic Organization API Key in management audit; a Key revoked or rotated before the change commits is refused. User API Keys have no MCP routes. MCP Server Registrations belong to the Organization.

OrganizationMcpServersController_enable

[
{
"OrganizationApiKey": []
}
]
[
{
"name": "serverId",
"required": true,
"in": "path",
"schema": {
"type": "string",
"pattern": "^mcp_[a-f0-9-]{36}$"
}
}
]
{
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"properties": {
"expectedServerVersion": {
"type": "integer",
"minimum": 1,
"description": "When present, the change applies only to this registration version."
}
}
}
}
}
}
{
"200": {
"description": "Enabled MCP registration.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"serverId",
"organizationId",
"displayName",
"endpointUrl",
"endpointVersion",
"transport",
"authorizationMode",
"status",
"serverVersion",
"createdByUserId",
"createdByPlatformAccountId",
"createdByOrganizationMemberId",
"createdAt",
"updatedAt",
"observation",
"oauthClient",
"authorization"
],
"additionalProperties": false,
"properties": {
"serverId": {
"type": "string",
"pattern": "^mcp_[a-f0-9-]{36}$"
},
"organizationId": {
"type": "string"
},
"displayName": {
"type": "string"
},
"endpointUrl": {
"type": "string",
"format": "uri",
"pattern": "^https:\\/\\/(?![^/?#]*@)[^#]+$"
},
"endpointVersion": {
"type": "integer",
"minimum": 1
},
"transport": {
"type": "string",
"enum": [
"streamable_http"
]
},
"authorizationMode": {
"type": "string",
"enum": [
"none",
"organization_static_token",
"end_user_static_token",
"organization_client_credentials",
"organization_oauth",
"end_user_oauth"
]
},
"status": {
"type": "string",
"enum": [
"enabled",
"disabled"
]
},
"serverVersion": {
"type": "integer",
"minimum": 1
},
"createdByUserId": {
"type": "string",
"nullable": true
},
"createdByPlatformAccountId": {
"type": "string",
"nullable": true
},
"createdByOrganizationMemberId": {
"type": "string",
"nullable": true
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"updatedAt": {
"type": "string",
"format": "date-time"
},
"observation": {
"type": "object",
"nullable": true,
"description": "The protocol era last detected at the current endpoint; diagnostic, never permission.",
"required": [
"era",
"protocolVersion"
],
"additionalProperties": false,
"properties": {
"era": {
"type": "string",
"enum": [
"modern",
"legacy"
]
},
"protocolVersion": {
"type": "string"
}
}
},
"oauthClient": {
"type": "object",
"nullable": true,
"description": "The registration's pre-registered OAuth client, by its client ID; null when none is set. Its secret is write-only.",
"required": [
"clientId"
],
"additionalProperties": false,
"properties": {
"clientId": {
"type": "string"
}
}
},
"authorization": {
"type": "object",
"description": "The Organization's MCP Authorization of this registration. Its credential is write-only. Null while it has none, and always for modes `end_user_static_token` and `end_user_oauth`, whose authorizations belong to each End User.",
"required": [
"owner",
"state",
"invalidReason",
"requiredScope",
"hasCredential",
"catalog",
"updatedAt"
],
"additionalProperties": false,
"properties": {
"owner": {
"type": "object",
"required": [
"kind"
],
"additionalProperties": false,
"properties": {
"kind": {
"type": "string",
"enum": [
"organization"
]
}
}
},
"state": {
"type": "string",
"enum": [
"usable",
"invalid",
"revoked"
]
},
"invalidReason": {
"type": "string",
"nullable": true,
"enum": [
"endpoint_changed",
"mode_changed",
"unauthorized",
"forbidden",
"insufficient_scope",
"token_rejected",
"client_changed"
],
"description": "Why an invalid authorization stopped being usable; null otherwise. endpoint_changed, mode_changed and client_changed (another OAuth client ID) follow a registration change. During a Turn the server refused the credential: unauthorized (HTTP 401), forbidden (403) or insufficient_scope (403 with that challenge). token_rejected: the authorization server rejected the request for an access token, with the client credentials or the refresh token, or an expired OAuth token has no refresh token. Setting the credential again, or authorizing again with OAuth, makes the authorization usable again."
},
"requiredScope": {
"type": "string",
"nullable": true,
"maxLength": 512,
"description": "The scope the server said it requires when it refused the credential with insufficient_scope, when it named a valid one; null otherwise. Authorizing again with OAuth requests it together with the scope the authorization was granted."
},
"hasCredential": {
"type": "boolean"
},
"catalog": {
"type": "object",
"nullable": true,
"description": "The catalog new AgentRuns freeze; null until discovery succeeds under this authorization.",
"required": [
"discoveredAt",
"toolNames"
],
"additionalProperties": false,
"properties": {
"discoveredAt": {
"type": "string",
"format": "date-time",
"description": "When the server's tools were last listed, by discovery or before a call."
},
"toolNames": {
"type": "array",
"items": {
"type": "string"
}
}
}
},
"updatedAt": {
"type": "string",
"format": "date-time"
}
},
"nullable": true
}
}
}
}
}
},
"400": {
"description": "Invalid MCP request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"401": {
"description": "authentication_required: missing credentials, or the acting credential was revoked or rotated before the change committed.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "The credential cannot manage this Organization's MCP registrations; auth_kind_forbidden for an API Key that is not an Organization API Key.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"404": {
"description": "MCP registration not found.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"409": {
"description": "Registration version changed.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}

POST /api/v1/org/mcp/servers/{serverId}/disable

Section titled “POST /api/v1/org/mcp/servers/{serverId}/disable”

Disable an MCP server registration.

An emergency stop: AgentTemplate saves, Session creation and Turns that reference the registration are refused, and bound AgentRuns dispatch no further call until it is enabled.

Authorization: OrganizationApiKey; persisted credentials determine Organization scope; no End User scope. Changes are attributed to the authentic Organization API Key in management audit; a Key revoked or rotated before the change commits is refused. User API Keys have no MCP routes. MCP Server Registrations belong to the Organization.

OrganizationMcpServersController_disable

[
{
"OrganizationApiKey": []
}
]
[
{
"name": "serverId",
"required": true,
"in": "path",
"schema": {
"type": "string",
"pattern": "^mcp_[a-f0-9-]{36}$"
}
}
]
{
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"properties": {
"expectedServerVersion": {
"type": "integer",
"minimum": 1,
"description": "When present, the change applies only to this registration version."
}
}
}
}
}
}
{
"200": {
"description": "Disabled MCP registration.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"serverId",
"organizationId",
"displayName",
"endpointUrl",
"endpointVersion",
"transport",
"authorizationMode",
"status",
"serverVersion",
"createdByUserId",
"createdByPlatformAccountId",
"createdByOrganizationMemberId",
"createdAt",
"updatedAt",
"observation",
"oauthClient",
"authorization"
],
"additionalProperties": false,
"properties": {
"serverId": {
"type": "string",
"pattern": "^mcp_[a-f0-9-]{36}$"
},
"organizationId": {
"type": "string"
},
"displayName": {
"type": "string"
},
"endpointUrl": {
"type": "string",
"format": "uri",
"pattern": "^https:\\/\\/(?![^/?#]*@)[^#]+$"
},
"endpointVersion": {
"type": "integer",
"minimum": 1
},
"transport": {
"type": "string",
"enum": [
"streamable_http"
]
},
"authorizationMode": {
"type": "string",
"enum": [
"none",
"organization_static_token",
"end_user_static_token",
"organization_client_credentials",
"organization_oauth",
"end_user_oauth"
]
},
"status": {
"type": "string",
"enum": [
"enabled",
"disabled"
]
},
"serverVersion": {
"type": "integer",
"minimum": 1
},
"createdByUserId": {
"type": "string",
"nullable": true
},
"createdByPlatformAccountId": {
"type": "string",
"nullable": true
},
"createdByOrganizationMemberId": {
"type": "string",
"nullable": true
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"updatedAt": {
"type": "string",
"format": "date-time"
},
"observation": {
"type": "object",
"nullable": true,
"description": "The protocol era last detected at the current endpoint; diagnostic, never permission.",
"required": [
"era",
"protocolVersion"
],
"additionalProperties": false,
"properties": {
"era": {
"type": "string",
"enum": [
"modern",
"legacy"
]
},
"protocolVersion": {
"type": "string"
}
}
},
"oauthClient": {
"type": "object",
"nullable": true,
"description": "The registration's pre-registered OAuth client, by its client ID; null when none is set. Its secret is write-only.",
"required": [
"clientId"
],
"additionalProperties": false,
"properties": {
"clientId": {
"type": "string"
}
}
},
"authorization": {
"type": "object",
"description": "The Organization's MCP Authorization of this registration. Its credential is write-only. Null while it has none, and always for modes `end_user_static_token` and `end_user_oauth`, whose authorizations belong to each End User.",
"required": [
"owner",
"state",
"invalidReason",
"requiredScope",
"hasCredential",
"catalog",
"updatedAt"
],
"additionalProperties": false,
"properties": {
"owner": {
"type": "object",
"required": [
"kind"
],
"additionalProperties": false,
"properties": {
"kind": {
"type": "string",
"enum": [
"organization"
]
}
}
},
"state": {
"type": "string",
"enum": [
"usable",
"invalid",
"revoked"
]
},
"invalidReason": {
"type": "string",
"nullable": true,
"enum": [
"endpoint_changed",
"mode_changed",
"unauthorized",
"forbidden",
"insufficient_scope",
"token_rejected",
"client_changed"
],
"description": "Why an invalid authorization stopped being usable; null otherwise. endpoint_changed, mode_changed and client_changed (another OAuth client ID) follow a registration change. During a Turn the server refused the credential: unauthorized (HTTP 401), forbidden (403) or insufficient_scope (403 with that challenge). token_rejected: the authorization server rejected the request for an access token, with the client credentials or the refresh token, or an expired OAuth token has no refresh token. Setting the credential again, or authorizing again with OAuth, makes the authorization usable again."
},
"requiredScope": {
"type": "string",
"nullable": true,
"maxLength": 512,
"description": "The scope the server said it requires when it refused the credential with insufficient_scope, when it named a valid one; null otherwise. Authorizing again with OAuth requests it together with the scope the authorization was granted."
},
"hasCredential": {
"type": "boolean"
},
"catalog": {
"type": "object",
"nullable": true,
"description": "The catalog new AgentRuns freeze; null until discovery succeeds under this authorization.",
"required": [
"discoveredAt",
"toolNames"
],
"additionalProperties": false,
"properties": {
"discoveredAt": {
"type": "string",
"format": "date-time",
"description": "When the server's tools were last listed, by discovery or before a call."
},
"toolNames": {
"type": "array",
"items": {
"type": "string"
}
}
}
},
"updatedAt": {
"type": "string",
"format": "date-time"
}
},
"nullable": true
}
}
}
}
}
},
"400": {
"description": "Invalid MCP request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"401": {
"description": "authentication_required: missing credentials, or the acting credential was revoked or rotated before the change committed.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "The credential cannot manage this Organization's MCP registrations; auth_kind_forbidden for an API Key that is not an Organization API Key.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"404": {
"description": "MCP registration not found.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"409": {
"description": "Registration version changed.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}

PUT /api/v1/org/mcp/servers/{serverId}/authorization

Section titled “PUT /api/v1/org/mcp/servers/{serverId}/authorization”

Set or replace the Organization’s credential: a static token or OAuth client credentials.

In mode organization_static_token, send token. In mode organization_client_credentials, send the OAuth clientId and clientSecret: Agent Service discovers the authorization server from the MCP server’s protected resource metadata, which may name another public host, obtains an access token with a client_credentials grant for the MCP server, and renews it at dispatch once it expires. The authorization becomes usable and its catalog is discovered with the credential. When the authorization server rejects the token request, the authorization is returned invalid with token_rejected. A replacement takes effect for the next call of AgentRuns already bound to the registration. The credential is write-only.

Authorization: OrganizationApiKey; persisted credentials determine Organization scope; no End User scope. Changes are attributed to the authentic Organization API Key in management audit; a Key revoked or rotated before the change commits is refused. User API Keys have no MCP routes. MCP Server Registrations belong to the Organization.

OrganizationMcpServersController_putAuthorization

[
{
"OrganizationApiKey": []
}
]
[
{
"name": "serverId",
"required": true,
"in": "path",
"schema": {
"type": "string",
"pattern": "^mcp_[a-f0-9-]{36}$"
}
}
]
{
"required": true,
"content": {
"application/json": {
"schema": {
"oneOf": [
{
"type": "object",
"title": "Static token",
"required": [
"token"
],
"additionalProperties": false,
"properties": {
"token": {
"type": "string",
"minLength": 1,
"maxLength": 8192,
"writeOnly": true
}
}
},
{
"type": "object",
"title": "OAuth client credentials",
"required": [
"clientId",
"clientSecret"
],
"additionalProperties": false,
"properties": {
"clientId": {
"type": "string",
"minLength": 1,
"maxLength": 1024,
"writeOnly": true
},
"clientSecret": {
"type": "string",
"minLength": 1,
"maxLength": 4096,
"writeOnly": true
}
}
}
]
}
}
}
}
{
"200": {
"description": "The Organization's MCP Authorization.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"authorization"
],
"additionalProperties": false,
"properties": {
"authorization": {
"type": "object",
"description": "The Organization's MCP Authorization of this registration. Its credential is write-only.",
"required": [
"owner",
"state",
"invalidReason",
"requiredScope",
"hasCredential",
"catalog",
"updatedAt"
],
"additionalProperties": false,
"properties": {
"owner": {
"type": "object",
"required": [
"kind"
],
"additionalProperties": false,
"properties": {
"kind": {
"type": "string",
"enum": [
"organization"
]
}
}
},
"state": {
"type": "string",
"enum": [
"usable",
"invalid",
"revoked"
]
},
"invalidReason": {
"type": "string",
"nullable": true,
"enum": [
"endpoint_changed",
"mode_changed",
"unauthorized",
"forbidden",
"insufficient_scope",
"token_rejected",
"client_changed"
],
"description": "Why an invalid authorization stopped being usable; null otherwise. endpoint_changed, mode_changed and client_changed (another OAuth client ID) follow a registration change. During a Turn the server refused the credential: unauthorized (HTTP 401), forbidden (403) or insufficient_scope (403 with that challenge). token_rejected: the authorization server rejected the request for an access token, with the client credentials or the refresh token, or an expired OAuth token has no refresh token. Setting the credential again, or authorizing again with OAuth, makes the authorization usable again."
},
"requiredScope": {
"type": "string",
"nullable": true,
"maxLength": 512,
"description": "The scope the server said it requires when it refused the credential with insufficient_scope, when it named a valid one; null otherwise. Authorizing again with OAuth requests it together with the scope the authorization was granted."
},
"hasCredential": {
"type": "boolean"
},
"catalog": {
"type": "object",
"nullable": true,
"description": "The catalog new AgentRuns freeze; null until discovery succeeds under this authorization.",
"required": [
"discoveredAt",
"toolNames"
],
"additionalProperties": false,
"properties": {
"discoveredAt": {
"type": "string",
"format": "date-time",
"description": "When the server's tools were last listed, by discovery or before a call."
},
"toolNames": {
"type": "array",
"items": {
"type": "string"
}
}
}
},
"updatedAt": {
"type": "string",
"format": "date-time"
}
}
}
}
}
}
}
},
"400": {
"description": "Invalid MCP request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"401": {
"description": "authentication_required: missing credentials, or the acting credential was revoked or rotated before the change committed.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "The credential cannot manage this Organization's MCP registrations; auth_kind_forbidden for an API Key that is not an Organization API Key.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"404": {
"description": "MCP registration not found.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"409": {
"description": "The registration's mode does not take the credential sent, or it changed concurrently.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}

DELETE /api/v1/org/mcp/servers/{serverId}/authorization

Section titled “DELETE /api/v1/org/mcp/servers/{serverId}/authorization”

Revoke the Organization’s credential.

The authorization and its catalog stop being usable, and its stored token or client credentials and access token are revoked; bound AgentRuns dispatch no further call until a credential is set again.

Authorization: OrganizationApiKey; persisted credentials determine Organization scope; no End User scope. Changes are attributed to the authentic Organization API Key in management audit; a Key revoked or rotated before the change commits is refused. User API Keys have no MCP routes. MCP Server Registrations belong to the Organization.

OrganizationMcpServersController_revokeAuthorization

[
{
"OrganizationApiKey": []
}
]
[
{
"name": "serverId",
"required": true,
"in": "path",
"schema": {
"type": "string",
"pattern": "^mcp_[a-f0-9-]{36}$"
}
}
]
{
"204": {
"description": "Authorization revoked or already absent."
},
"400": {
"description": "Invalid MCP request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"401": {
"description": "authentication_required: missing credentials, or the acting credential was revoked or rotated before the change committed.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "The credential cannot manage this Organization's MCP registrations; auth_kind_forbidden for an API Key that is not an Organization API Key.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"404": {
"description": "MCP registration not found.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"409": {
"description": "The registration's mode holds no token, or it changed concurrently.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}

POST /api/v1/org/mcp/servers/{serverId}/refresh-catalog

Section titled “POST /api/v1/org/mcp/servers/{serverId}/refresh-catalog”

Rediscover the catalog of the Organization’s MCP Authorization.

Future AgentRuns freeze the refreshed catalog; bound AgentRuns keep theirs.

Authorization: OrganizationApiKey; persisted credentials determine Organization scope; no End User scope. Changes are attributed to the authentic Organization API Key in management audit; a Key revoked or rotated before the change commits is refused. User API Keys have no MCP routes. MCP Server Registrations belong to the Organization.

OrganizationMcpServersController_refreshCatalog

[
{
"OrganizationApiKey": []
}
]
[
{
"name": "serverId",
"required": true,
"in": "path",
"schema": {
"type": "string",
"pattern": "^mcp_[a-f0-9-]{36}$"
}
}
]
{
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"properties": {}
}
}
}
}
{
"200": {
"description": "MCP registration with its refreshed catalog.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"serverId",
"organizationId",
"displayName",
"endpointUrl",
"endpointVersion",
"transport",
"authorizationMode",
"status",
"serverVersion",
"createdByUserId",
"createdByPlatformAccountId",
"createdByOrganizationMemberId",
"createdAt",
"updatedAt",
"observation",
"oauthClient",
"authorization"
],
"additionalProperties": false,
"properties": {
"serverId": {
"type": "string",
"pattern": "^mcp_[a-f0-9-]{36}$"
},
"organizationId": {
"type": "string"
},
"displayName": {
"type": "string"
},
"endpointUrl": {
"type": "string",
"format": "uri",
"pattern": "^https:\\/\\/(?![^/?#]*@)[^#]+$"
},
"endpointVersion": {
"type": "integer",
"minimum": 1
},
"transport": {
"type": "string",
"enum": [
"streamable_http"
]
},
"authorizationMode": {
"type": "string",
"enum": [
"none",
"organization_static_token",
"end_user_static_token",
"organization_client_credentials",
"organization_oauth",
"end_user_oauth"
]
},
"status": {
"type": "string",
"enum": [
"enabled",
"disabled"
]
},
"serverVersion": {
"type": "integer",
"minimum": 1
},
"createdByUserId": {
"type": "string",
"nullable": true
},
"createdByPlatformAccountId": {
"type": "string",
"nullable": true
},
"createdByOrganizationMemberId": {
"type": "string",
"nullable": true
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"updatedAt": {
"type": "string",
"format": "date-time"
},
"observation": {
"type": "object",
"nullable": true,
"description": "The protocol era last detected at the current endpoint; diagnostic, never permission.",
"required": [
"era",
"protocolVersion"
],
"additionalProperties": false,
"properties": {
"era": {
"type": "string",
"enum": [
"modern",
"legacy"
]
},
"protocolVersion": {
"type": "string"
}
}
},
"oauthClient": {
"type": "object",
"nullable": true,
"description": "The registration's pre-registered OAuth client, by its client ID; null when none is set. Its secret is write-only.",
"required": [
"clientId"
],
"additionalProperties": false,
"properties": {
"clientId": {
"type": "string"
}
}
},
"authorization": {
"type": "object",
"description": "The Organization's MCP Authorization of this registration. Its credential is write-only. Null while it has none, and always for modes `end_user_static_token` and `end_user_oauth`, whose authorizations belong to each End User.",
"required": [
"owner",
"state",
"invalidReason",
"requiredScope",
"hasCredential",
"catalog",
"updatedAt"
],
"additionalProperties": false,
"properties": {
"owner": {
"type": "object",
"required": [
"kind"
],
"additionalProperties": false,
"properties": {
"kind": {
"type": "string",
"enum": [
"organization"
]
}
}
},
"state": {
"type": "string",
"enum": [
"usable",
"invalid",
"revoked"
]
},
"invalidReason": {
"type": "string",
"nullable": true,
"enum": [
"endpoint_changed",
"mode_changed",
"unauthorized",
"forbidden",
"insufficient_scope",
"token_rejected",
"client_changed"
],
"description": "Why an invalid authorization stopped being usable; null otherwise. endpoint_changed, mode_changed and client_changed (another OAuth client ID) follow a registration change. During a Turn the server refused the credential: unauthorized (HTTP 401), forbidden (403) or insufficient_scope (403 with that challenge). token_rejected: the authorization server rejected the request for an access token, with the client credentials or the refresh token, or an expired OAuth token has no refresh token. Setting the credential again, or authorizing again with OAuth, makes the authorization usable again."
},
"requiredScope": {
"type": "string",
"nullable": true,
"maxLength": 512,
"description": "The scope the server said it requires when it refused the credential with insufficient_scope, when it named a valid one; null otherwise. Authorizing again with OAuth requests it together with the scope the authorization was granted."
},
"hasCredential": {
"type": "boolean"
},
"catalog": {
"type": "object",
"nullable": true,
"description": "The catalog new AgentRuns freeze; null until discovery succeeds under this authorization.",
"required": [
"discoveredAt",
"toolNames"
],
"additionalProperties": false,
"properties": {
"discoveredAt": {
"type": "string",
"format": "date-time",
"description": "When the server's tools were last listed, by discovery or before a call."
},
"toolNames": {
"type": "array",
"items": {
"type": "string"
}
}
}
},
"updatedAt": {
"type": "string",
"format": "date-time"
}
},
"nullable": true
}
}
}
}
}
},
"400": {
"description": "Invalid MCP request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"401": {
"description": "authentication_required: missing credentials, or the acting credential was revoked or rotated before the change committed.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "The credential cannot manage this Organization's MCP registrations; auth_kind_forbidden for an API Key that is not an Organization API Key.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"404": {
"description": "MCP registration not found.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"409": {
"description": "The authorization is not usable, or it changed during discovery.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"500": {
"description": "Tool catalog discovery failed. The previous catalog is retained."
}
}

PUT /api/v1/org/users/{userId}/mcp/servers/{serverId}/authorization

Section titled “PUT /api/v1/org/users/{userId}/mcp/servers/{serverId}/authorization”

Set or replace an End User’s MCP static token.

Only for mode end_user_static_token. The End User’s authorization becomes usable and that End User’s catalog is discovered with the token; it may differ from other End Users’ catalogs. New Turns of every Session the End User owns that references the registration use it, and a replacement takes effect for the next call of AgentRuns already bound to it.

Authorization: OrganizationApiKey; persisted credentials determine Organization scope. The path userId selects an ordinary End User that must belong to that Organization, and the change applies to that End User’s MCP Authorization only. Changes are attributed to the authentic Organization API Key; a Key revoked or rotated before the change commits is refused. User API Keys have no MCP routes. MCP Server Registrations belong to the Organization.

EndUserMcpAuthorizationsController_put

[
{
"OrganizationApiKey": []
}
]
[
{
"name": "userId",
"required": true,
"in": "path",
"schema": {
"type": "string"
}
},
{
"name": "serverId",
"required": true,
"in": "path",
"schema": {
"type": "string",
"pattern": "^mcp_[a-f0-9-]{36}$"
}
}
]
{
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"title": "Static token",
"required": [
"token"
],
"additionalProperties": false,
"properties": {
"token": {
"type": "string",
"minLength": 1,
"maxLength": 8192,
"writeOnly": true
}
}
}
}
}
}
{
"200": {
"description": "The End User's MCP Authorization.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"authorization"
],
"additionalProperties": false,
"properties": {
"authorization": {
"type": "object",
"description": "The End User's MCP Authorization of this registration. Its credential is write-only.",
"required": [
"owner",
"state",
"invalidReason",
"requiredScope",
"hasCredential",
"catalog",
"updatedAt"
],
"additionalProperties": false,
"properties": {
"owner": {
"type": "object",
"required": [
"kind"
],
"additionalProperties": false,
"properties": {
"kind": {
"type": "string",
"enum": [
"end_user"
]
}
}
},
"state": {
"type": "string",
"enum": [
"usable",
"invalid",
"revoked"
]
},
"invalidReason": {
"type": "string",
"nullable": true,
"enum": [
"endpoint_changed",
"mode_changed",
"unauthorized",
"forbidden",
"insufficient_scope",
"token_rejected",
"client_changed"
],
"description": "Why an invalid authorization stopped being usable; null otherwise. endpoint_changed, mode_changed and client_changed (another OAuth client ID) follow a registration change. During a Turn the server refused the credential: unauthorized (HTTP 401), forbidden (403) or insufficient_scope (403 with that challenge). token_rejected: the authorization server rejected the request for an access token, with the client credentials or the refresh token, or an expired OAuth token has no refresh token. Setting the credential again, or authorizing again with OAuth, makes the authorization usable again."
},
"requiredScope": {
"type": "string",
"nullable": true,
"maxLength": 512,
"description": "The scope the server said it requires when it refused the credential with insufficient_scope, when it named a valid one; null otherwise. Authorizing again with OAuth requests it together with the scope the authorization was granted."
},
"hasCredential": {
"type": "boolean"
},
"catalog": {
"type": "object",
"nullable": true,
"description": "The catalog new AgentRuns freeze; null until discovery succeeds under this authorization.",
"required": [
"discoveredAt",
"toolNames"
],
"additionalProperties": false,
"properties": {
"discoveredAt": {
"type": "string",
"format": "date-time",
"description": "When the server's tools were last listed, by discovery or before a call."
},
"toolNames": {
"type": "array",
"items": {
"type": "string"
}
}
}
},
"updatedAt": {
"type": "string",
"format": "date-time"
}
}
}
}
}
}
}
},
"400": {
"description": "Invalid MCP request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"401": {
"description": "authentication_required: missing credentials, or the acting credential was revoked or rotated before the change committed.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "The credential cannot manage this Organization's MCP registrations; auth_kind_forbidden for an API Key that is not an Organization API Key.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"404": {
"description": "The MCP registration was not found, or `resource_not_found`: the path userId is not an ordinary End User of the Organization.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"409": {
"description": "The registration's mode holds no End User static token, or it changed concurrently.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}

DELETE /api/v1/org/users/{userId}/mcp/servers/{serverId}/authorization

Section titled “DELETE /api/v1/org/users/{userId}/mcp/servers/{serverId}/authorization”

Revoke an End User’s MCP Authorization.

For modes end_user_static_token and end_user_oauth. The End User’s authorization and catalog stop being usable: that End User’s next Turn that references the registration is refused with mcp_authorization_required, and their bound AgentRuns dispatch no further call. Other End Users’ authorizations are unaffected. An end_user_oauth authorization’s tokens are also revoked at the authorization server when it offers revocation; a failure there does not keep the authorization.

Authorization: OrganizationApiKey; persisted credentials determine Organization scope. The path userId selects an ordinary End User that must belong to that Organization, and the change applies to that End User’s MCP Authorization only. Changes are attributed to the authentic Organization API Key; a Key revoked or rotated before the change commits is refused. User API Keys have no MCP routes. MCP Server Registrations belong to the Organization.

EndUserMcpAuthorizationsController_revoke

[
{
"OrganizationApiKey": []
}
]
[
{
"name": "userId",
"required": true,
"in": "path",
"schema": {
"type": "string"
}
},
{
"name": "serverId",
"required": true,
"in": "path",
"schema": {
"type": "string",
"pattern": "^mcp_[a-f0-9-]{36}$"
}
}
]
{
"204": {
"description": "Authorization revoked or already absent."
},
"400": {
"description": "Invalid MCP request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"401": {
"description": "authentication_required: missing credentials, or the acting credential was revoked or rotated before the change committed.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "The credential cannot manage this Organization's MCP registrations; auth_kind_forbidden for an API Key that is not an Organization API Key.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"404": {
"description": "The MCP registration was not found, or `resource_not_found`: the path userId is not an ordinary End User of the Organization.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"409": {
"description": "The registration's mode is not End User-owned, or it changed concurrently.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}

GET /api/v1/org/users/{userId}/agent-templates/{templateId}/mcp-authorization-requirements

Section titled “GET /api/v1/org/users/{userId}/agent-templates/{templateId}/mcp-authorization-requirements”

Read an End User’s MCP authorization requirements for an AgentTemplate.

For each MCP Server Registration the AgentTemplate’s current content references, what the first Turn of a Session this End User creates from it now would need: the registration’s status, its MCP Authorization Mode, whose authorization it uses, that authorization’s status, and who can satisfy it. Creating the Session needs no authorization.

Authorization: OrganizationApiKey; persisted credentials determine Organization scope. The path userId selects an ordinary End User that must belong to that Organization, and the read reports the MCP Authorizations a Turn of that End User would use. User API Keys have no MCP routes.

EndUserMcpAuthorizationRequirementsController_forTemplate

[
{
"OrganizationApiKey": []
}
]
[
{
"name": "userId",
"required": true,
"in": "path",
"schema": {
"type": "string"
}
},
{
"name": "templateId",
"required": true,
"in": "path",
"schema": {
"type": "string"
}
}
]
{
"200": {
"description": "The End User's MCP authorization requirements.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"ready",
"registrations"
],
"additionalProperties": false,
"properties": {
"ready": {
"type": "boolean",
"description": "True when every referenced registration is enabled and its authorization is usable: Turn admission then refuses no Turn for MCP. False when a Turn would be refused with `session_execution_dependency_unavailable` (a registration is disabled or unavailable) or `mcp_authorization_required`."
},
"registrations": {
"type": "array",
"description": "Each referenced MCP Server Registration, in bytewise serverId order.",
"items": {
"type": "object",
"required": [
"serverId",
"registrationStatus",
"authorizationMode",
"owner",
"authorizationStatus",
"satisfiedBy"
],
"additionalProperties": false,
"properties": {
"serverId": {
"type": "string"
},
"registrationStatus": {
"type": "string",
"enum": [
"enabled",
"disabled",
"unavailable"
],
"description": "disabled: the Organization disabled the registration; unavailable: it was deleted, and its mode, owner and authorization status are null. Either refuses the Turn with `session_execution_dependency_unavailable`, whatever the authorization status."
},
"authorizationMode": {
"type": "string",
"nullable": true,
"enum": [
"none",
"organization_static_token",
"end_user_static_token",
"organization_client_credentials",
"organization_oauth",
"end_user_oauth"
]
},
"owner": {
"type": "string",
"nullable": true,
"enum": [
"organization",
"end_user"
],
"description": "Whose MCP Authorization the registration's mode uses: the Organization's, or this End User's own."
},
"authorizationStatus": {
"type": "string",
"nullable": true,
"enum": [
"usable",
"missing",
"invalid",
"revoked",
"insufficient_scope"
],
"description": "usable, or the reason `mcp_authorization_required` would name: missing (no usable authorization with a catalog), invalid (invalidated by an endpoint or mode change, the server refused the credential with HTTP 401 or 403 during a Turn, or the authorization server rejected the client credentials), revoked, or insufficient_scope (the server answered 403 insufficient_scope)."
},
"satisfiedBy": {
"type": "string",
"nullable": true,
"enum": [
"organization",
"end_user"
],
"description": "Who can make the registration ready: end_user when this End User's own authorization, such as setting their static token, satisfies it; organization when it needs Organization authority, such as setting the Organization's token or client credentials, or enabling the registration. Null when it is ready."
}
}
}
}
}
}
}
},
"headers": {
"Cache-Control": {
"schema": {
"type": "string",
"example": "no-store"
}
}
}
},
"401": {
"description": "Authentication is required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "auth_kind_forbidden: an Organization API Key is required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"404": {
"description": "resource_not_found: the path userId is not an ordinary End User of the Organization; agent_template_unavailable: the AgentTemplate is unknown or archived.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}

GET /api/v1/org/users/{userId}/sessions/{id}/mcp-authorization-requirements

Section titled “GET /api/v1/org/users/{userId}/sessions/{id}/mcp-authorization-requirements”

Read an End User’s MCP authorization requirements for a Session.

For each MCP Server Registration the Session’s current Configuration Epoch references, what the Session’s next Turn would need. It reflects that Configuration Epoch, not the AgentTemplate’s current content, and agrees with what Turn admission would decide now.

Authorization: OrganizationApiKey; persisted credentials determine Organization scope. The path userId selects an ordinary End User that must belong to that Organization, and the read reports the MCP Authorizations a Turn of that End User would use. User API Keys have no MCP routes.

EndUserMcpAuthorizationRequirementsController_forSession

[
{
"OrganizationApiKey": []
}
]
[
{
"name": "userId",
"required": true,
"in": "path",
"schema": {
"type": "string"
}
},
{
"name": "id",
"required": true,
"in": "path",
"schema": {
"type": "string"
}
}
]
{
"200": {
"description": "The End User's MCP authorization requirements for the Session's next Turn.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"ready",
"registrations"
],
"additionalProperties": false,
"properties": {
"ready": {
"type": "boolean",
"description": "True when every referenced registration is enabled and its authorization is usable: Turn admission then refuses no Turn for MCP. False when a Turn would be refused with `session_execution_dependency_unavailable` (a registration is disabled or unavailable) or `mcp_authorization_required`."
},
"registrations": {
"type": "array",
"description": "Each referenced MCP Server Registration, in bytewise serverId order.",
"items": {
"type": "object",
"required": [
"serverId",
"registrationStatus",
"authorizationMode",
"owner",
"authorizationStatus",
"satisfiedBy"
],
"additionalProperties": false,
"properties": {
"serverId": {
"type": "string"
},
"registrationStatus": {
"type": "string",
"enum": [
"enabled",
"disabled",
"unavailable"
],
"description": "disabled: the Organization disabled the registration; unavailable: it was deleted, and its mode, owner and authorization status are null. Either refuses the Turn with `session_execution_dependency_unavailable`, whatever the authorization status."
},
"authorizationMode": {
"type": "string",
"nullable": true,
"enum": [
"none",
"organization_static_token",
"end_user_static_token",
"organization_client_credentials",
"organization_oauth",
"end_user_oauth"
]
},
"owner": {
"type": "string",
"nullable": true,
"enum": [
"organization",
"end_user"
],
"description": "Whose MCP Authorization the registration's mode uses: the Organization's, or this End User's own."
},
"authorizationStatus": {
"type": "string",
"nullable": true,
"enum": [
"usable",
"missing",
"invalid",
"revoked",
"insufficient_scope"
],
"description": "usable, or the reason `mcp_authorization_required` would name: missing (no usable authorization with a catalog), invalid (invalidated by an endpoint or mode change, the server refused the credential with HTTP 401 or 403 during a Turn, or the authorization server rejected the client credentials), revoked, or insufficient_scope (the server answered 403 insufficient_scope)."
},
"satisfiedBy": {
"type": "string",
"nullable": true,
"enum": [
"organization",
"end_user"
],
"description": "Who can make the registration ready: end_user when this End User's own authorization, such as setting their static token, satisfies it; organization when it needs Organization authority, such as setting the Organization's token or client credentials, or enabling the registration. Null when it is ready."
}
}
}
}
}
}
}
},
"headers": {
"Cache-Control": {
"schema": {
"type": "string",
"example": "no-store"
}
}
}
},
"401": {
"description": "Authentication is required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "auth_kind_forbidden: an Organization API Key is required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"404": {
"description": "session_not_found: the ordinary End User or the Session they own is unavailable.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}

List the Organization’s Connector registrations.

Authorization: OrganizationApiKey; persisted credentials determine Organization scope; no End User scope. Changes are attributed to the authentic Organization API Key; User API Keys neither manage nor read Connectors.

ConnectorsController_list

[
{
"OrganizationApiKey": []
}
]
{
"200": {
"description": "Connector registrations.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"connectors"
],
"additionalProperties": false,
"properties": {
"connectors": {
"type": "array",
"items": {
"type": "object",
"required": [
"connectorId",
"organizationId",
"displayName",
"endpointUrl",
"endpointVersion",
"transport",
"status",
"connectorVersion",
"createdAt",
"updatedAt",
"observation"
],
"additionalProperties": false,
"properties": {
"connectorId": {
"type": "string",
"pattern": "^conn_[a-f0-9-]{36}$"
},
"organizationId": {
"type": "string"
},
"displayName": {
"type": "string"
},
"endpointUrl": {
"type": "string",
"maxLength": 2048,
"description": "HTTPS endpoint for a streamable_http Connector; empty for a tunnel or backend_connection Connector, which the platform never dials."
},
"endpointVersion": {
"type": "integer",
"minimum": 1
},
"transport": {
"type": "string",
"enum": [
"streamable_http",
"tunnel",
"backend_connection"
],
"description": "backend_connection: created by connector.serve on a Backend Connection, active from its first declaration, with no observation; update, activate, refresh-catalog and deactivate answer 409 for it."
},
"status": {
"type": "string",
"enum": [
"inactive",
"active"
]
},
"connectorVersion": {
"type": "integer",
"minimum": 1
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"updatedAt": {
"type": "string",
"format": "date-time"
},
"observation": {
"type": "object",
"nullable": true,
"required": [
"era",
"protocolVersion",
"endpointVersion",
"probedAt",
"expiresAt"
],
"additionalProperties": false,
"properties": {
"era": {
"type": "string",
"enum": [
"modern",
"legacy"
]
},
"protocolVersion": {
"type": "string"
},
"endpointVersion": {
"type": "integer",
"minimum": 1
},
"probedAt": {
"type": "string",
"format": "date-time"
},
"expiresAt": {
"type": "string",
"format": "date-time"
}
}
}
}
}
}
}
}
}
}
},
"400": {
"description": "Invalid Connector request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"401": {
"description": "authentication_required: missing credentials, or the Organization API Key was revoked or rotated before the change committed.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "auth_kind_forbidden: requires an Organization API Key.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}

Register an inactive Connector without a dedicated credential.

Authorization: OrganizationApiKey; persisted credentials determine Organization scope; no End User scope. Changes are attributed to the authentic Organization API Key; User API Keys neither manage nor read Connectors.

ConnectorsController_create

[
{
"OrganizationApiKey": []
}
]
{
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"displayName"
],
"additionalProperties": false,
"properties": {
"displayName": {
"type": "string",
"minLength": 1,
"maxLength": 255
},
"transport": {
"type": "string",
"enum": [
"streamable_http",
"tunnel"
],
"default": "streamable_http",
"description": "streamable_http requires endpointUrl; tunnel takes no endpointUrl and serves tools over its own outbound WebSocket."
},
"endpointUrl": {
"type": "string",
"format": "uri",
"maxLength": 2048,
"pattern": "^https:\\/\\/(?![^/?#]*@)[^#]+$"
}
}
}
}
}
}
{
"201": {
"description": "Inactive Connector registration.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"connectorId",
"organizationId",
"displayName",
"endpointUrl",
"endpointVersion",
"transport",
"status",
"connectorVersion",
"createdAt",
"updatedAt",
"observation"
],
"additionalProperties": false,
"properties": {
"connectorId": {
"type": "string",
"pattern": "^conn_[a-f0-9-]{36}$"
},
"organizationId": {
"type": "string"
},
"displayName": {
"type": "string"
},
"endpointUrl": {
"type": "string",
"maxLength": 2048,
"description": "HTTPS endpoint for a streamable_http Connector; empty for a tunnel or backend_connection Connector, which the platform never dials."
},
"endpointVersion": {
"type": "integer",
"minimum": 1
},
"transport": {
"type": "string",
"enum": [
"streamable_http",
"tunnel",
"backend_connection"
],
"description": "backend_connection: created by connector.serve on a Backend Connection, active from its first declaration, with no observation; update, activate, refresh-catalog and deactivate answer 409 for it."
},
"status": {
"type": "string",
"enum": [
"inactive",
"active"
]
},
"connectorVersion": {
"type": "integer",
"minimum": 1
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"updatedAt": {
"type": "string",
"format": "date-time"
},
"observation": {
"type": "object",
"nullable": true,
"required": [
"era",
"protocolVersion",
"endpointVersion",
"probedAt",
"expiresAt"
],
"additionalProperties": false,
"properties": {
"era": {
"type": "string",
"enum": [
"modern",
"legacy"
]
},
"protocolVersion": {
"type": "string"
},
"endpointVersion": {
"type": "integer",
"minimum": 1
},
"probedAt": {
"type": "string",
"format": "date-time"
},
"expiresAt": {
"type": "string",
"format": "date-time"
}
}
}
}
}
}
}
},
"400": {
"description": "Invalid Connector request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"401": {
"description": "authentication_required: missing credentials, or the Organization API Key was revoked or rotated before the change committed.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "auth_kind_forbidden: requires an Organization API Key.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"409": {
"description": "A Connector with this display name already exists in the Organization.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}

Get one Connector registration.

Authorization: OrganizationApiKey; persisted credentials determine Organization scope; no End User scope. Changes are attributed to the authentic Organization API Key; User API Keys neither manage nor read Connectors.

ConnectorsController_get

[
{
"OrganizationApiKey": []
}
]
[
{
"name": "connectorId",
"required": true,
"in": "path",
"schema": {
"type": "string",
"pattern": "^conn_[a-f0-9-]{36}$"
}
}
]
{
"200": {
"description": "Connector registration.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"connectorId",
"organizationId",
"displayName",
"endpointUrl",
"endpointVersion",
"transport",
"status",
"connectorVersion",
"createdAt",
"updatedAt",
"observation"
],
"additionalProperties": false,
"properties": {
"connectorId": {
"type": "string",
"pattern": "^conn_[a-f0-9-]{36}$"
},
"organizationId": {
"type": "string"
},
"displayName": {
"type": "string"
},
"endpointUrl": {
"type": "string",
"maxLength": 2048,
"description": "HTTPS endpoint for a streamable_http Connector; empty for a tunnel or backend_connection Connector, which the platform never dials."
},
"endpointVersion": {
"type": "integer",
"minimum": 1
},
"transport": {
"type": "string",
"enum": [
"streamable_http",
"tunnel",
"backend_connection"
],
"description": "backend_connection: created by connector.serve on a Backend Connection, active from its first declaration, with no observation; update, activate, refresh-catalog and deactivate answer 409 for it."
},
"status": {
"type": "string",
"enum": [
"inactive",
"active"
]
},
"connectorVersion": {
"type": "integer",
"minimum": 1
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"updatedAt": {
"type": "string",
"format": "date-time"
},
"observation": {
"type": "object",
"nullable": true,
"required": [
"era",
"protocolVersion",
"endpointVersion",
"probedAt",
"expiresAt"
],
"additionalProperties": false,
"properties": {
"era": {
"type": "string",
"enum": [
"modern",
"legacy"
]
},
"protocolVersion": {
"type": "string"
},
"endpointVersion": {
"type": "integer",
"minimum": 1
},
"probedAt": {
"type": "string",
"format": "date-time"
},
"expiresAt": {
"type": "string",
"format": "date-time"
}
}
}
}
}
}
}
},
"400": {
"description": "Invalid Connector request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"401": {
"description": "authentication_required: missing credentials, or the Organization API Key was revoked or rotated before the change committed.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "auth_kind_forbidden: requires an Organization API Key.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"404": {
"description": "Connector not found.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}

PATCH /api/v1/org/connectors/{connectorId}

Section titled “PATCH /api/v1/org/connectors/{connectorId}”

Edit an inactive Connector registration.

Authorization: OrganizationApiKey; persisted credentials determine Organization scope; no End User scope. Changes are attributed to the authentic Organization API Key; User API Keys neither manage nor read Connectors.

ConnectorsController_update

[
{
"OrganizationApiKey": []
}
]
[
{
"name": "connectorId",
"required": true,
"in": "path",
"schema": {
"type": "string",
"pattern": "^conn_[a-f0-9-]{36}$"
}
}
]
{
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"expectedConnectorVersion"
],
"minProperties": 2,
"additionalProperties": false,
"properties": {
"expectedConnectorVersion": {
"type": "integer",
"minimum": 1
},
"displayName": {
"type": "string",
"minLength": 1,
"maxLength": 255
},
"endpointUrl": {
"type": "string",
"format": "uri",
"maxLength": 2048,
"pattern": "^https:\\/\\/(?![^/?#]*@)[^#]+$"
}
}
}
}
}
}
{
"200": {
"description": "Updated inactive Connector registration.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"connectorId",
"organizationId",
"displayName",
"endpointUrl",
"endpointVersion",
"transport",
"status",
"connectorVersion",
"createdAt",
"updatedAt",
"observation"
],
"additionalProperties": false,
"properties": {
"connectorId": {
"type": "string",
"pattern": "^conn_[a-f0-9-]{36}$"
},
"organizationId": {
"type": "string"
},
"displayName": {
"type": "string"
},
"endpointUrl": {
"type": "string",
"maxLength": 2048,
"description": "HTTPS endpoint for a streamable_http Connector; empty for a tunnel or backend_connection Connector, which the platform never dials."
},
"endpointVersion": {
"type": "integer",
"minimum": 1
},
"transport": {
"type": "string",
"enum": [
"streamable_http",
"tunnel",
"backend_connection"
],
"description": "backend_connection: created by connector.serve on a Backend Connection, active from its first declaration, with no observation; update, activate, refresh-catalog and deactivate answer 409 for it."
},
"status": {
"type": "string",
"enum": [
"inactive",
"active"
]
},
"connectorVersion": {
"type": "integer",
"minimum": 1
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"updatedAt": {
"type": "string",
"format": "date-time"
},
"observation": {
"type": "object",
"nullable": true,
"required": [
"era",
"protocolVersion",
"endpointVersion",
"probedAt",
"expiresAt"
],
"additionalProperties": false,
"properties": {
"era": {
"type": "string",
"enum": [
"modern",
"legacy"
]
},
"protocolVersion": {
"type": "string"
},
"endpointVersion": {
"type": "integer",
"minimum": 1
},
"probedAt": {
"type": "string",
"format": "date-time"
},
"expiresAt": {
"type": "string",
"format": "date-time"
}
}
}
}
}
}
}
},
"400": {
"description": "Invalid Connector request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"401": {
"description": "authentication_required: missing credentials, or the Organization API Key was revoked or rotated before the change committed.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "auth_kind_forbidden: requires an Organization API Key.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"404": {
"description": "Connector not found.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"409": {
"description": "Connector name, active state, or version conflicts. Also answered for a Connector declared on a Backend Connection (transport backend_connection), which has no Activation.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}

POST /api/v1/org/connectors/{connectorId}/activate

Section titled “POST /api/v1/org/connectors/{connectorId}/activate”

Discover the tool catalog and activate a Connector.

Authorization: OrganizationApiKey; persisted credentials determine Organization scope; no End User scope. Changes are attributed to the authentic Organization API Key; User API Keys neither manage nor read Connectors.

ConnectorsController_activate

[
{
"OrganizationApiKey": []
}
]
[
{
"name": "connectorId",
"required": true,
"in": "path",
"schema": {
"type": "string",
"pattern": "^conn_[a-f0-9-]{36}$"
}
}
]
{
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"expectedConnectorVersion"
],
"additionalProperties": false,
"properties": {
"expectedConnectorVersion": {
"type": "integer",
"minimum": 1
}
}
}
}
}
}
{
"201": {
"description": "Activated Connector registration.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"connectorId",
"organizationId",
"displayName",
"endpointUrl",
"endpointVersion",
"transport",
"status",
"connectorVersion",
"createdAt",
"updatedAt",
"observation"
],
"additionalProperties": false,
"properties": {
"connectorId": {
"type": "string",
"pattern": "^conn_[a-f0-9-]{36}$"
},
"organizationId": {
"type": "string"
},
"displayName": {
"type": "string"
},
"endpointUrl": {
"type": "string",
"maxLength": 2048,
"description": "HTTPS endpoint for a streamable_http Connector; empty for a tunnel or backend_connection Connector, which the platform never dials."
},
"endpointVersion": {
"type": "integer",
"minimum": 1
},
"transport": {
"type": "string",
"enum": [
"streamable_http",
"tunnel",
"backend_connection"
],
"description": "backend_connection: created by connector.serve on a Backend Connection, active from its first declaration, with no observation; update, activate, refresh-catalog and deactivate answer 409 for it."
},
"status": {
"type": "string",
"enum": [
"inactive",
"active"
]
},
"connectorVersion": {
"type": "integer",
"minimum": 1
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"updatedAt": {
"type": "string",
"format": "date-time"
},
"observation": {
"type": "object",
"nullable": true,
"required": [
"era",
"protocolVersion",
"endpointVersion",
"probedAt",
"expiresAt"
],
"additionalProperties": false,
"properties": {
"era": {
"type": "string",
"enum": [
"modern",
"legacy"
]
},
"protocolVersion": {
"type": "string"
},
"endpointVersion": {
"type": "integer",
"minimum": 1
},
"probedAt": {
"type": "string",
"format": "date-time"
},
"expiresAt": {
"type": "string",
"format": "date-time"
}
}
}
}
}
}
}
},
"400": {
"description": "Invalid Connector request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"401": {
"description": "authentication_required: missing credentials, or the Organization API Key was revoked or rotated before the change committed.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "auth_kind_forbidden: requires an Organization API Key.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"404": {
"description": "Connector not found.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"409": {
"description": "Connector state changed. Also answered for a Connector declared on a Backend Connection (transport backend_connection), which has no Activation.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}

POST /api/v1/org/connectors/{connectorId}/refresh-catalog

Section titled “POST /api/v1/org/connectors/{connectorId}/refresh-catalog”

Refresh the stored tool catalog of an active HTTP Connector.

Uses Activation discovery limits. Keeps the Connector and endpoint versions.

Authorization: OrganizationApiKey; persisted credentials determine Organization scope; no End User scope. Changes are attributed to the authentic Organization API Key; User API Keys neither manage nor read Connectors.

ConnectorsController_refreshCatalog

[
{
"OrganizationApiKey": []
}
]
[
{
"name": "connectorId",
"required": true,
"in": "path",
"schema": {
"type": "string",
"pattern": "^conn_[a-f0-9-]{36}$"
}
}
]
{
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"expectedConnectorVersion"
],
"additionalProperties": false,
"properties": {
"expectedConnectorVersion": {
"type": "integer",
"minimum": 1
}
}
}
}
}
}
{
"200": {
"description": "Connector registration with its refreshed observation.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"connectorId",
"organizationId",
"displayName",
"endpointUrl",
"endpointVersion",
"transport",
"status",
"connectorVersion",
"createdAt",
"updatedAt",
"observation"
],
"additionalProperties": false,
"properties": {
"connectorId": {
"type": "string",
"pattern": "^conn_[a-f0-9-]{36}$"
},
"organizationId": {
"type": "string"
},
"displayName": {
"type": "string"
},
"endpointUrl": {
"type": "string",
"maxLength": 2048,
"description": "HTTPS endpoint for a streamable_http Connector; empty for a tunnel or backend_connection Connector, which the platform never dials."
},
"endpointVersion": {
"type": "integer",
"minimum": 1
},
"transport": {
"type": "string",
"enum": [
"streamable_http",
"tunnel",
"backend_connection"
],
"description": "backend_connection: created by connector.serve on a Backend Connection, active from its first declaration, with no observation; update, activate, refresh-catalog and deactivate answer 409 for it."
},
"status": {
"type": "string",
"enum": [
"inactive",
"active"
]
},
"connectorVersion": {
"type": "integer",
"minimum": 1
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"updatedAt": {
"type": "string",
"format": "date-time"
},
"observation": {
"type": "object",
"nullable": true,
"required": [
"era",
"protocolVersion",
"endpointVersion",
"probedAt",
"expiresAt"
],
"additionalProperties": false,
"properties": {
"era": {
"type": "string",
"enum": [
"modern",
"legacy"
]
},
"protocolVersion": {
"type": "string"
},
"endpointVersion": {
"type": "integer",
"minimum": 1
},
"probedAt": {
"type": "string",
"format": "date-time"
},
"expiresAt": {
"type": "string",
"format": "date-time"
}
}
}
}
}
}
}
},
"400": {
"description": "Invalid Connector request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"401": {
"description": "authentication_required: missing credentials, or the Organization API Key was revoked or rotated before the change committed.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "auth_kind_forbidden: requires an Organization API Key.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"404": {
"description": "Connector not found.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"409": {
"description": "Connector is not active over HTTP, or the registration or catalog changed concurrently. Also answered for a Connector declared on a Backend Connection (transport backend_connection), which has no Activation.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"500": {
"description": "Tool catalog discovery failed. The previous catalog is retained."
},
"503": {
"description": "provider_unavailable: Connector callback signing is unavailable.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}

POST /api/v1/org/connectors/{connectorId}/deactivate

Section titled “POST /api/v1/org/connectors/{connectorId}/deactivate”

Deactivate a Connector.

Authorization: OrganizationApiKey; persisted credentials determine Organization scope; no End User scope. Changes are attributed to the authentic Organization API Key; User API Keys neither manage nor read Connectors.

ConnectorsController_deactivate

[
{
"OrganizationApiKey": []
}
]
[
{
"name": "connectorId",
"required": true,
"in": "path",
"schema": {
"type": "string",
"pattern": "^conn_[a-f0-9-]{36}$"
}
}
]
{
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"expectedConnectorVersion"
],
"additionalProperties": false,
"properties": {
"expectedConnectorVersion": {
"type": "integer",
"minimum": 1
}
}
}
}
}
}
{
"201": {
"description": "Deactivated Connector registration.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"connectorId",
"organizationId",
"displayName",
"endpointUrl",
"endpointVersion",
"transport",
"status",
"connectorVersion",
"createdAt",
"updatedAt",
"observation"
],
"additionalProperties": false,
"properties": {
"connectorId": {
"type": "string",
"pattern": "^conn_[a-f0-9-]{36}$"
},
"organizationId": {
"type": "string"
},
"displayName": {
"type": "string"
},
"endpointUrl": {
"type": "string",
"maxLength": 2048,
"description": "HTTPS endpoint for a streamable_http Connector; empty for a tunnel or backend_connection Connector, which the platform never dials."
},
"endpointVersion": {
"type": "integer",
"minimum": 1
},
"transport": {
"type": "string",
"enum": [
"streamable_http",
"tunnel",
"backend_connection"
],
"description": "backend_connection: created by connector.serve on a Backend Connection, active from its first declaration, with no observation; update, activate, refresh-catalog and deactivate answer 409 for it."
},
"status": {
"type": "string",
"enum": [
"inactive",
"active"
]
},
"connectorVersion": {
"type": "integer",
"minimum": 1
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"updatedAt": {
"type": "string",
"format": "date-time"
},
"observation": {
"type": "object",
"nullable": true,
"required": [
"era",
"protocolVersion",
"endpointVersion",
"probedAt",
"expiresAt"
],
"additionalProperties": false,
"properties": {
"era": {
"type": "string",
"enum": [
"modern",
"legacy"
]
},
"protocolVersion": {
"type": "string"
},
"endpointVersion": {
"type": "integer",
"minimum": 1
},
"probedAt": {
"type": "string",
"format": "date-time"
},
"expiresAt": {
"type": "string",
"format": "date-time"
}
}
}
}
}
}
}
},
"400": {
"description": "Invalid Connector request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"401": {
"description": "authentication_required: missing credentials, or the Organization API Key was revoked or rotated before the change committed.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "auth_kind_forbidden: requires an Organization API Key.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"404": {
"description": "Connector not found.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"409": {
"description": "Connector version changed. Also answered for a Connector declared on a Backend Connection (transport backend_connection), which has no Activation.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}

Authorization: OrganizationApiKey; persisted credentials determine Organization and End User scope.

SchedulerPublicController_organizationList

[
{
"OrganizationApiKey": []
}
]
[
{
"name": "userId",
"required": true,
"in": "path",
"schema": {
"type": "string"
}
},
{
"name": "cursor",
"required": false,
"in": "query",
"description": "Opaque keyset cursor bound to the caller scope and status filter.",
"schema": {
"type": "string"
}
},
{
"name": "limit",
"required": false,
"in": "query",
"schema": {
"minimum": 1,
"maximum": 100,
"type": "number"
}
},
{
"name": "status",
"required": false,
"in": "query",
"schema": {
"enum": [
"enabled",
"disabled",
"deleted"
],
"type": "string"
}
}
]
{
"200": {
"description": "One page of Schedulers. Defaults to enabled and disabled; use status=deleted for retained history.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/OrganizationSchedulerListResponseOpenApiDto"
}
}
},
"headers": {
"Cache-Control": {
"description": "Prevents Scheduler state from being cached.",
"schema": {
"type": "string",
"example": "private, no-store"
}
}
}
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
},
"headers": {
"Cache-Control": {
"description": "Prevents Scheduler state from being cached.",
"schema": {
"type": "string",
"example": "private, no-store"
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
},
"headers": {
"Cache-Control": {
"description": "Prevents Scheduler state from being cached.",
"schema": {
"type": "string",
"example": "private, no-store"
}
}
}
},
"403": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
},
"headers": {
"Cache-Control": {
"description": "Prevents Scheduler state from being cached.",
"schema": {
"type": "string",
"example": "private, no-store"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
},
"headers": {
"Cache-Control": {
"description": "Prevents Scheduler state from being cached.",
"schema": {
"type": "string",
"example": "private, no-store"
}
}
}
},
"500": {
"description": "Required audit persistence is unavailable.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
},
"headers": {
"Cache-Control": {
"description": "Prevents Scheduler state from being cached.",
"schema": {
"type": "string",
"example": "private, no-store"
}
}
}
}
}

POST /api/v1/org/users/{userId}/schedulers

Section titled “POST /api/v1/org/users/{userId}/schedulers”

Create or replay an Organization-Key Scheduler

New scheduling requires an active ordinary owner and binds the exact creating Key. Replaying a saved create response never replaces continuing authority; explicitly resume with a fresh Key after rotation or revocation.

Authorization: OrganizationApiKey; persisted credentials determine Organization and End User scope.

SchedulerPublicController_organizationCreate

[
{
"OrganizationApiKey": []
}
]
[
{
"name": "userId",
"required": true,
"in": "path",
"schema": {
"type": "string"
}
},
{
"name": "Idempotency-Key",
"in": "header",
"required": true,
"schema": {
"type": "string"
}
}
]
{
"required": true,
"content": {
"application/json": {
"schema": {
"oneOf": [
{
"$ref": "#/components/schemas/CreateNewSessionPublicSchedulerOpenApiDto"
},
{
"$ref": "#/components/schemas/CreateBoundSessionPublicSchedulerOpenApiDto"
}
]
}
}
}
}
{
"201": {
"description": "The created Scheduler.",
"headers": {
"ETag": {
"description": "The current Scheduler revision ETag",
"schema": {
"type": "string"
}
},
"Cache-Control": {
"description": "Prevents Scheduler state from being cached.",
"schema": {
"type": "string",
"example": "private, no-store"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicSchedulerResponseOpenApiDto"
}
}
}
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
},
"headers": {
"Cache-Control": {
"description": "Prevents Scheduler state from being cached.",
"schema": {
"type": "string",
"example": "private, no-store"
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
},
"headers": {
"Cache-Control": {
"description": "Prevents Scheduler state from being cached.",
"schema": {
"type": "string",
"example": "private, no-store"
}
}
}
},
"403": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
},
"headers": {
"Cache-Control": {
"description": "Prevents Scheduler state from being cached.",
"schema": {
"type": "string",
"example": "private, no-store"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
},
"headers": {
"Cache-Control": {
"description": "Prevents Scheduler state from being cached.",
"schema": {
"type": "string",
"example": "private, no-store"
}
}
}
},
"409": {
"headers": {
"Retry-After": {
"description": "Seconds to wait before retrying an in-progress idempotent request",
"schema": {
"type": "integer",
"minimum": 1
}
},
"Cache-Control": {
"description": "Prevents Scheduler state from being cached.",
"schema": {
"type": "string",
"example": "private, no-store"
}
}
},
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"500": {
"description": "Stored idempotency witness is invalid (idempotency_witness_invalid).",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
},
"headers": {
"Cache-Control": {
"description": "Prevents Scheduler state from being cached.",
"schema": {
"type": "string",
"example": "private, no-store"
}
}
}
}
}

GET /api/v1/org/users/{userId}/schedulers/{schedulerId}

Section titled “GET /api/v1/org/users/{userId}/schedulers/{schedulerId}”

Authorization: OrganizationApiKey; persisted credentials determine Organization and End User scope.

SchedulerPublicController_organizationGet

[
{
"OrganizationApiKey": []
}
]
[
{
"name": "userId",
"required": true,
"in": "path",
"schema": {
"type": "string"
}
},
{
"name": "schedulerId",
"required": true,
"in": "path",
"schema": {
"type": "string"
}
}
]
{
"200": {
"description": "The Scheduler.",
"headers": {
"ETag": {
"description": "The current Scheduler revision ETag",
"schema": {
"type": "string"
}
},
"Cache-Control": {
"description": "Prevents Scheduler state from being cached.",
"schema": {
"type": "string",
"example": "private, no-store"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicSchedulerResponseOpenApiDto"
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
},
"headers": {
"Cache-Control": {
"description": "Prevents Scheduler state from being cached.",
"schema": {
"type": "string",
"example": "private, no-store"
}
}
}
},
"403": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
},
"headers": {
"Cache-Control": {
"description": "Prevents Scheduler state from being cached.",
"schema": {
"type": "string",
"example": "private, no-store"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
},
"headers": {
"Cache-Control": {
"description": "Prevents Scheduler state from being cached.",
"schema": {
"type": "string",
"example": "private, no-store"
}
}
}
},
"500": {
"description": "Required audit persistence is unavailable.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
},
"headers": {
"Cache-Control": {
"description": "Prevents Scheduler state from being cached.",
"schema": {
"type": "string",
"example": "private, no-store"
}
}
}
}
}

DELETE /api/v1/org/users/{userId}/schedulers/{schedulerId}

Section titled “DELETE /api/v1/org/users/{userId}/schedulers/{schedulerId}”

Authorization: OrganizationApiKey; persisted credentials determine Organization and End User scope.

SchedulerPublicController_organizationRemove

[
{
"OrganizationApiKey": []
}
]
[
{
"name": "userId",
"required": true,
"in": "path",
"schema": {
"type": "string"
}
},
{
"name": "schedulerId",
"required": true,
"in": "path",
"schema": {
"type": "string"
}
},
{
"name": "If-Match",
"in": "header",
"required": true,
"schema": {
"type": "string"
}
}
]
{
"204": {
"description": "",
"headers": {
"Cache-Control": {
"description": "Prevents Scheduler state from being cached.",
"schema": {
"type": "string",
"example": "private, no-store"
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
},
"headers": {
"Cache-Control": {
"description": "Prevents Scheduler state from being cached.",
"schema": {
"type": "string",
"example": "private, no-store"
}
}
}
},
"403": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
},
"headers": {
"Cache-Control": {
"description": "Prevents Scheduler state from being cached.",
"schema": {
"type": "string",
"example": "private, no-store"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
},
"headers": {
"Cache-Control": {
"description": "Prevents Scheduler state from being cached.",
"schema": {
"type": "string",
"example": "private, no-store"
}
}
}
},
"412": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
},
"headers": {
"Cache-Control": {
"description": "Prevents Scheduler state from being cached.",
"schema": {
"type": "string",
"example": "private, no-store"
}
}
}
},
"428": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
},
"headers": {
"Cache-Control": {
"description": "Prevents Scheduler state from being cached.",
"schema": {
"type": "string",
"example": "private, no-store"
}
}
}
},
"500": {
"description": "Required audit persistence is unavailable.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
},
"headers": {
"Cache-Control": {
"description": "Prevents Scheduler state from being cached.",
"schema": {
"type": "string",
"example": "private, no-store"
}
}
}
}
}

PATCH /api/v1/org/users/{userId}/schedulers/{schedulerId}

Section titled “PATCH /api/v1/org/users/{userId}/schedulers/{schedulerId}”

Update or explicitly reauthorize a Scheduler

enabled:true binds future fires to this exact current Organization Key and cancels only unstarted queued fires. Accepted Turns and create receipts retain their original identity. A disabled owner cannot resume scheduling.

Authorization: OrganizationApiKey; persisted credentials determine Organization and End User scope.

SchedulerPublicController_organizationUpdate

[
{
"OrganizationApiKey": []
}
]
[
{
"name": "userId",
"required": true,
"in": "path",
"schema": {
"type": "string"
}
},
{
"name": "schedulerId",
"required": true,
"in": "path",
"schema": {
"type": "string"
}
},
{
"name": "If-Match",
"in": "header",
"required": true,
"schema": {
"type": "string"
}
}
]
{
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UpdatePublicSchedulerOpenApiDto"
}
}
}
}
{
"200": {
"description": "The updated Scheduler.",
"headers": {
"ETag": {
"description": "The current Scheduler revision ETag",
"schema": {
"type": "string"
}
},
"Cache-Control": {
"description": "Prevents Scheduler state from being cached.",
"schema": {
"type": "string",
"example": "private, no-store"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicSchedulerResponseOpenApiDto"
}
}
}
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
},
"headers": {
"Cache-Control": {
"description": "Prevents Scheduler state from being cached.",
"schema": {
"type": "string",
"example": "private, no-store"
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
},
"headers": {
"Cache-Control": {
"description": "Prevents Scheduler state from being cached.",
"schema": {
"type": "string",
"example": "private, no-store"
}
}
}
},
"403": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
},
"headers": {
"Cache-Control": {
"description": "Prevents Scheduler state from being cached.",
"schema": {
"type": "string",
"example": "private, no-store"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
},
"headers": {
"Cache-Control": {
"description": "Prevents Scheduler state from being cached.",
"schema": {
"type": "string",
"example": "private, no-store"
}
}
}
},
"409": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
},
"headers": {
"Cache-Control": {
"description": "Prevents Scheduler state from being cached.",
"schema": {
"type": "string",
"example": "private, no-store"
}
}
}
},
"412": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
},
"headers": {
"Cache-Control": {
"description": "Prevents Scheduler state from being cached.",
"schema": {
"type": "string",
"example": "private, no-store"
}
}
}
},
"428": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
},
"headers": {
"Cache-Control": {
"description": "Prevents Scheduler state from being cached.",
"schema": {
"type": "string",
"example": "private, no-store"
}
}
}
},
"500": {
"description": "Required audit persistence is unavailable.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
},
"headers": {
"Cache-Control": {
"description": "Prevents Scheduler state from being cached.",
"schema": {
"type": "string",
"example": "private, no-store"
}
}
}
}
}

GET /api/v1/org/users/{userId}/schedulers/{schedulerId}/fires

Section titled “GET /api/v1/org/users/{userId}/schedulers/{schedulerId}/fires”

Authorization: OrganizationApiKey; persisted credentials determine Organization and End User scope.

SchedulerPublicController_organizationFires

[
{
"OrganizationApiKey": []
}
]
[
{
"name": "userId",
"required": true,
"in": "path",
"schema": {
"type": "string"
}
},
{
"name": "schedulerId",
"required": true,
"in": "path",
"schema": {
"type": "string"
}
},
{
"name": "cursor",
"required": false,
"in": "query",
"description": "Opaque keyset cursor bound to the caller scope and Scheduler.",
"schema": {
"type": "string"
}
},
{
"name": "limit",
"required": false,
"in": "query",
"schema": {
"minimum": 1,
"maximum": 100,
"type": "number"
}
}
]
{
"200": {
"description": "One page of immutable Fire execution snapshots.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicSchedulerFiresResponseOpenApiDto"
}
}
},
"headers": {
"Cache-Control": {
"description": "Prevents Scheduler state from being cached.",
"schema": {
"type": "string",
"example": "private, no-store"
}
}
}
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
},
"headers": {
"Cache-Control": {
"description": "Prevents Scheduler state from being cached.",
"schema": {
"type": "string",
"example": "private, no-store"
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
},
"headers": {
"Cache-Control": {
"description": "Prevents Scheduler state from being cached.",
"schema": {
"type": "string",
"example": "private, no-store"
}
}
}
},
"403": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
},
"headers": {
"Cache-Control": {
"description": "Prevents Scheduler state from being cached.",
"schema": {
"type": "string",
"example": "private, no-store"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
},
"headers": {
"Cache-Control": {
"description": "Prevents Scheduler state from being cached.",
"schema": {
"type": "string",
"example": "private, no-store"
}
}
}
},
"500": {
"description": "Required audit persistence is unavailable.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
},
"headers": {
"Cache-Control": {
"description": "Prevents Scheduler state from being cached.",
"schema": {
"type": "string",
"example": "private, no-store"
}
}
}
}
}

GET /api/v1/org/agent-template-reference-catalog

Section titled “GET /api/v1/org/agent-template-reference-catalog”

Read Organization Template model, Sandbox and published Skill availability.

Authorization: OrganizationApiKey; persisted credentials determine Organization scope; no End User scope.

OrganizationAgentTemplatesController_referenceCatalog

[
{
"OrganizationApiKey": []
}
]
[
{
"name": "limit",
"required": false,
"in": "query",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 200,
"default": 100
}
}
]
{
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/OrganizationTemplateCatalogDto"
}
}
},
"headers": {
"Cache-Control": {
"schema": {
"type": "string",
"example": "no-store"
}
}
}
},
"400": {
"description": "Strict parameters or body are invalid.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
},
"headers": {
"Cache-Control": {
"schema": {
"type": "string",
"example": "no-store"
}
}
}
},
"401": {
"description": "Missing, revoked or rotated Organization Key.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
},
"headers": {
"Cache-Control": {
"schema": {
"type": "string",
"example": "no-store"
}
}
}
},
"403": {
"description": "Only an Organization API Key may use this surface.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
},
"headers": {
"Cache-Control": {
"schema": {
"type": "string",
"example": "no-store"
}
}
}
},
"404": {
"description": "The organization-scoped Template is not visible.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
},
"headers": {
"Cache-Control": {
"schema": {
"type": "string",
"example": "no-store"
}
}
}
}
}

List Organization Templates.

Authorization: OrganizationApiKey; persisted credentials determine Organization scope; no End User scope.

OrganizationAgentTemplatesController_list

[
{
"OrganizationApiKey": []
}
]
[
{
"name": "sort",
"required": false,
"in": "query",
"schema": {
"enum": [
"updated_desc",
"created_desc",
"name_asc"
],
"type": "string"
}
},
{
"name": "lifecycleStatus",
"required": false,
"in": "query",
"schema": {
"enum": [
"all",
"active",
"archived"
],
"type": "string"
}
},
{
"name": "q",
"required": false,
"in": "query",
"schema": {
"type": "string",
"maxLength": 255
}
},
{
"name": "cursor",
"required": false,
"in": "query",
"schema": {
"type": "string",
"maxLength": 4096
}
},
{
"name": "limit",
"required": false,
"in": "query",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 200,
"default": 25
}
}
]
{
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/OrganizationTemplateListDto"
}
}
},
"headers": {
"Cache-Control": {
"schema": {
"type": "string",
"example": "no-store"
}
}
}
},
"400": {
"description": "Strict parameters or body are invalid.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
},
"headers": {
"Cache-Control": {
"schema": {
"type": "string",
"example": "no-store"
}
}
}
},
"401": {
"description": "Missing, revoked or rotated Organization Key.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
},
"headers": {
"Cache-Control": {
"schema": {
"type": "string",
"example": "no-store"
}
}
}
},
"403": {
"description": "Only an Organization API Key may use this surface.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
},
"headers": {
"Cache-Control": {
"schema": {
"type": "string",
"example": "no-store"
}
}
}
},
"404": {
"description": "The organization-scoped Template is not visible.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
},
"headers": {
"Cache-Control": {
"schema": {
"type": "string",
"example": "no-store"
}
}
}
},
"409": {
"description": "The committed Template catalog changed while continuing a cursor.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
},
"headers": {
"Cache-Control": {
"schema": {
"type": "string",
"example": "no-store"
}
}
}
}
}

Authorization: OrganizationApiKey; persisted credentials determine Organization scope; no End User scope.

OrganizationAgentTemplatesController_create

[
{
"OrganizationApiKey": []
}
]
[
{
"name": "Idempotency-Key",
"in": "header",
"required": true,
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"pattern": "^[!-~]{1,255}$"
}
}
]
{
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/OrganizationTemplateCreateDto"
}
}
}
}
{
"201": {
"headers": {
"ETag": {
"schema": {
"type": "string"
}
},
"Location": {
"schema": {
"type": "string"
}
},
"Cache-Control": {
"schema": {
"type": "string",
"example": "no-store"
}
}
},
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/OrganizationTemplateResultDto"
}
}
}
},
"400": {
"description": "Strict parameters or body are invalid.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
},
"headers": {
"Cache-Control": {
"schema": {
"type": "string",
"example": "no-store"
}
}
}
},
"401": {
"description": "Missing, revoked or rotated Organization Key.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
},
"headers": {
"Cache-Control": {
"schema": {
"type": "string",
"example": "no-store"
}
}
}
},
"403": {
"description": "Only an Organization API Key may use this surface.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
},
"headers": {
"Cache-Control": {
"schema": {
"type": "string",
"example": "no-store"
}
}
}
},
"404": {
"description": "The organization-scoped Template is not visible.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
},
"headers": {
"Cache-Control": {
"schema": {
"type": "string",
"example": "no-store"
}
}
}
},
"409": {
"description": "Idempotency-Key conflict, unavailable dependency, or realtime_language_unavailable when the enabled language is not offered by the active Ops release.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
},
"headers": {
"Cache-Control": {
"schema": {
"type": "string",
"example": "no-store"
}
}
}
}
}

GET /api/v1/org/agent-templates/{templateId}

Section titled “GET /api/v1/org/agent-templates/{templateId}”

Authorization: OrganizationApiKey; persisted credentials determine Organization scope; no End User scope.

OrganizationAgentTemplatesController_get

[
{
"OrganizationApiKey": []
}
]
[
{
"name": "templateId",
"required": true,
"in": "path",
"schema": {
"type": "string"
}
}
]
{
"200": {
"headers": {
"ETag": {
"schema": {
"type": "string"
}
},
"Cache-Control": {
"schema": {
"type": "string",
"example": "no-store"
}
}
},
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/OrganizationTemplateResultDto"
}
}
}
},
"400": {
"description": "Strict parameters or body are invalid.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
},
"headers": {
"Cache-Control": {
"schema": {
"type": "string",
"example": "no-store"
}
}
}
},
"401": {
"description": "Missing, revoked or rotated Organization Key.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
},
"headers": {
"Cache-Control": {
"schema": {
"type": "string",
"example": "no-store"
}
}
}
},
"403": {
"description": "Only an Organization API Key may use this surface.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
},
"headers": {
"Cache-Control": {
"schema": {
"type": "string",
"example": "no-store"
}
}
}
},
"404": {
"description": "The organization-scoped Template is not visible.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
},
"headers": {
"Cache-Control": {
"schema": {
"type": "string",
"example": "no-store"
}
}
}
}
}

PUT /api/v1/org/agent-templates/{templateId}

Section titled “PUT /api/v1/org/agent-templates/{templateId}”

Authorization: OrganizationApiKey; persisted credentials determine Organization scope; no End User scope.

OrganizationAgentTemplatesController_replace

[
{
"OrganizationApiKey": []
}
]
[
{
"name": "templateId",
"required": true,
"in": "path",
"schema": {
"type": "string"
}
},
{
"name": "Idempotency-Key",
"in": "header",
"required": true,
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"pattern": "^[!-~]{1,255}$"
}
},
{
"name": "If-Match",
"in": "header",
"required": true,
"schema": {
"type": "string",
"pattern": "^\"cvc1\\.[A-Za-z0-9_-]{43}\"$"
}
}
]
{
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/OrganizationTemplateReplaceDto"
}
}
}
}
{
"200": {
"headers": {
"ETag": {
"schema": {
"type": "string"
}
},
"Cache-Control": {
"schema": {
"type": "string",
"example": "no-store"
}
}
},
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/OrganizationTemplateResultDto"
}
}
}
},
"400": {
"description": "Strict parameters or body are invalid.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
},
"headers": {
"Cache-Control": {
"schema": {
"type": "string",
"example": "no-store"
}
}
}
},
"401": {
"description": "Missing, revoked or rotated Organization Key.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
},
"headers": {
"Cache-Control": {
"schema": {
"type": "string",
"example": "no-store"
}
}
}
},
"403": {
"description": "Only an Organization API Key may use this surface.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
},
"headers": {
"Cache-Control": {
"schema": {
"type": "string",
"example": "no-store"
}
}
}
},
"404": {
"description": "The organization-scoped Template is not visible.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
},
"headers": {
"Cache-Control": {
"schema": {
"type": "string",
"example": "no-store"
}
}
}
},
"409": {
"description": "The Template ETag is stale, the Idempotency-Key conflicts, a dependency is unavailable, or realtime_language_unavailable when the enabled language is not offered by the active Ops release.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
},
"headers": {
"Cache-Control": {
"schema": {
"type": "string",
"example": "no-store"
}
}
}
},
"412": {
"description": "If-Match is malformed.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
},
"headers": {
"Cache-Control": {
"schema": {
"type": "string",
"example": "no-store"
}
}
}
},
"428": {
"description": "If-Match is required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
},
"headers": {
"Cache-Control": {
"schema": {
"type": "string",
"example": "no-store"
}
}
}
}
}

POST /api/v1/org/agent-templates/{templateId}/archive

Section titled “POST /api/v1/org/agent-templates/{templateId}/archive”

Authorization: OrganizationApiKey; persisted credentials determine Organization scope; no End User scope.

OrganizationAgentTemplatesController_archive

[
{
"OrganizationApiKey": []
}
]
[
{
"name": "templateId",
"required": true,
"in": "path",
"schema": {
"type": "string"
}
},
{
"name": "Idempotency-Key",
"in": "header",
"required": true,
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"pattern": "^[!-~]{1,255}$"
}
},
{
"name": "If-Match",
"in": "header",
"required": true,
"schema": {
"type": "string",
"pattern": "^\"cvc1\\.[A-Za-z0-9_-]{43}\"$"
}
}
]
{
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/OrganizationTemplateEmptyBodyDto"
}
}
}
}
{
"200": {
"headers": {
"ETag": {
"schema": {
"type": "string"
}
},
"Cache-Control": {
"schema": {
"type": "string",
"example": "no-store"
}
}
},
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/OrganizationTemplateResultDto"
}
}
}
},
"400": {
"description": "Strict parameters or body are invalid.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
},
"headers": {
"Cache-Control": {
"schema": {
"type": "string",
"example": "no-store"
}
}
}
},
"401": {
"description": "Missing, revoked or rotated Organization Key.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
},
"headers": {
"Cache-Control": {
"schema": {
"type": "string",
"example": "no-store"
}
}
}
},
"403": {
"description": "Only an Organization API Key may use this surface.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
},
"headers": {
"Cache-Control": {
"schema": {
"type": "string",
"example": "no-store"
}
}
}
},
"404": {
"description": "The organization-scoped Template is not visible.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
},
"headers": {
"Cache-Control": {
"schema": {
"type": "string",
"example": "no-store"
}
}
}
},
"409": {
"description": "The Template ETag is stale or the Idempotency-Key conflicts.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
},
"headers": {
"Cache-Control": {
"schema": {
"type": "string",
"example": "no-store"
}
}
}
},
"412": {
"description": "If-Match is malformed.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
},
"headers": {
"Cache-Control": {
"schema": {
"type": "string",
"example": "no-store"
}
}
}
},
"428": {
"description": "If-Match is required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
},
"headers": {
"Cache-Control": {
"schema": {
"type": "string",
"example": "no-store"
}
}
}
}
}

Open a Backend Connection WebSocket

Upgrade to WebSocket with an Organization API Key Bearer header and the tidb-link.backend.v1 subprotocol. One JSON-RPC 2.0 message per text frame; the published message definitions are docs/backend-connection-v1.schema.json. The core sends the hello notification first (connectionId, maxSessions, claimWindowMs, heartbeatMs, maxFrameBytes); the Application Server sends nothing before it. session.attach {userId, sessionId, kind?, tools?, cursor?} takes a Session Attachment on this connection of an active Session owned by that ordinary End User in the Organization of the Key and answers {generation, cursor}; an executing attachment (the default) supersedes the executing attachment of the Session on any other connection, advances generation and may replace the Client Tools of the Session with tools; an observing attachment receives events only. Every attachment then receives session.event {sessionId, cursor, event} for each Session event after the attach, or after the requested cursor, which replays the missed events first; event is the public Session event envelope {type, sessionId, turnId, createdAt, data}, in order without gaps or repeats. Resume with the cursor of the last session.event processed. session.detach {sessionId} releases it. The core sends session.detached {sessionId, reason: superseded or session_deleted} when it ends an attachment. An attachment lapses within 10 seconds after the core loses its connection. Refusals answer -32000 with error.data.reason connection_full (maxSessions reached), connection_draining (after connection.drain), session_not_found, session_read_only or authentication_required; invalid params answer -32602. The executing attachment also receives tool.call {callId, sessionId, userId, turnId, name, arguments, claimBy, deadlineAt} for each Client Tool call published while it holds the Session, and after an executing attach for each call still awaiting a claim; a call published while the Session has no executing attachment is not performed at once and is never sent; execute a call only after tool.claim {callId} answers {claimed: true}, which only the connection holding the current executing attachment obtains before claimBy, and answer it with tool.result {callId, output or error} from any connection of the Organization, which answers {accepted}. A refused claim answers {claimed: false, reason: call_not_found, superseded, claim_window_closed or call_settled}; a refused result {accepted: false, reason: call_not_found, not_claimed or call_settled}, or error -32000 authentication_required when the Key is no longer valid, after which the connection closes with 4001; submit it again through a connection of a valid Key. An unclaimed call is reported as not performed at claimBy or when its Turn ends first, a claimed one without a result as unknown at deadlineAt or when its Turn ends first. session.send {sessionId, clientEventId, data} submits the message command of POST /api/v1/org/users/{userId}/sessions/{id}/events (type agent.session.input.message, same data and clientEventId namespace) for the End User of the attachment of the Session on this connection, of either kind, and answers the receipt {interaction, replayed}; replayed is true where REST answers 200. A Turn it starts runs on the replica holding this connection, and its events arrive as session.event, possibly before the receipt. The agent.session.idle event of the Session follows each Turn once the Session has released it; send the next message after it. Its refusals answer -32000 with error.data.reason session_not_attached (no attachment of the Session on this connection), connection_draining, or the REST ErrorEnvelope code with its details in error.data.details; a session.send frame over 1 MiB, the REST body limit, answers -32602. connector.serve {name, tools} declares the functions this connection serves of the Connector with that name in the Organization, finding or creating it, and answers {connectorId}; name and each function name must equal their own slug (lowercase letters and digits joined by single underscores, at most 29 characters), and tools take the session.attach declaration shape. Serving the name again on this connection replaces its declaration; connector.withdraw {name} ends it and answers {}, as does the end of the connection. Templates reference the Connector by connectorId, and the model sees each function as mcp___. A call of a served function arrives as tool.call {callId, sessionId, userId, turnId, name, connector: {id, name}, arguments, claimBy, deadlineAt} on exactly one connection serving the Connector whose declaration of that function matches the one the Run froze, preferring the connection holding the executing attachment of the Session, then one on the replica running the Turn; it needs no attachment, is never offered to another connection, and with no such connection is not performed at once. name is the declared function name and userId the End User owner of the Session. Only that connection obtains tool.claim {claimed: true}, before claimBy; any connection of the Organization may answer it with tool.result, and the outcomes are those of a Client Tool call. A streamable_http or tunnel Connector with that name is taken over in place: it keeps its connectorId and becomes a backend_connection Connector. connector.serve refusals answer -32000 with error.data.reason connection_draining or authentication_required. Any request refused with authentication_required (session.attach, session.send, connector.serve or tool.result) closes the connection with 4001, which ends its declarations and attachments. Before stopping, the core sends connection.drain with closeAfterMs; open a new connection, then close this one. The core pings every heartbeatMs and disconnects after two missed pongs. An Application Server that cannot send or observe WebSocket ping frames sends the ping request, params absent or {}, which the core answers at once with {time}, the clock of the answering replica. Close codes: 1001 heartbeat timeout, 1002, 1007 or 1009 WebSocket protocol violation (1009: frame over maxFrameBytes), 1011 internal error or the peer stopped reading (more than 8 MiB waiting), 1012 closed after drain, 1013 lease lost or Key unconfirmed (reconnect), 4001 Organization Key invalid, revoked or rotated, or Organization inactive, 4009 protocol error (binary frame or a frame before hello). A plain HTTP request with an Organization API Key receives 426.

Authorization: OrganizationApiKey in the upgrade request; the persisted Key determines Organization scope. Revoking or rotating that Key, or the Organization becoming inactive, closes the connection; no End User scope.

BackendConnectionController_get

[
{
"OrganizationApiKey": []
}
]
[
{
"name": "Sec-WebSocket-Protocol",
"in": "header",
"required": true,
"schema": {
"type": "string",
"enum": [
"tidb-link.backend.v1"
]
}
}
]
{
"101": {
"description": "WebSocket upgraded; the core authenticates the Key, then sends hello."
},
"400": {
"description": "Invalid upgrade, a query string, or an unsupported subprotocol.",
"headers": {
"Cache-Control": {
"schema": {
"type": "string",
"enum": [
"no-store"
]
}
}
}
},
"401": {
"description": "Plain HTTP only. ErrorEnvelope code: authentication_required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
},
"headers": {
"Cache-Control": {
"schema": {
"type": "string",
"enum": [
"no-store"
]
}
}
}
},
"403": {
"description": "Plain HTTP only. ErrorEnvelope code: auth_kind_forbidden.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
},
"headers": {
"Cache-Control": {
"schema": {
"type": "string",
"enum": [
"no-store"
]
}
}
}
},
"426": {
"description": "ErrorEnvelope code: websocket_required. WebSocket upgrade required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
},
"headers": {
"Cache-Control": {
"schema": {
"type": "string",
"enum": [
"no-store"
]
}
}
}
},
"429": {
"description": "This replica is at its connection limit; back off and retry.",
"headers": {
"Cache-Control": {
"schema": {
"type": "string",
"enum": [
"no-store"
]
}
}
}
},
"503": {
"description": "This replica is stopping; retry.",
"headers": {
"Cache-Control": {
"schema": {
"type": "string",
"enum": [
"no-store"
]
}
}
}
}
}

Redeem a short-lived download ticket.

Anonymous, ticket-authorized endpoint for every authenticated download resource kind. Returns complete same-path inline bytes or an HTTPS Drive9 storage redirect with bounded presign exposure. Organization-issued Drive tickets require their exact issuing credential to remain current at new redemption admission; revoked or rotated issuers return 404. An admitted transfer may finish within existing limits. A returned provider URL retains its own expiry and is not revoked by this core check. Legacy unattributed v3.drive tickets are refused; obtain a fresh ticket.

Authorization: short-lived download ticket; no API Key required.

DriveDownloadController_redeem

无需认证。

[
{
"name": "ticket",
"required": true,
"in": "path",
"description": "Opaque 60-second download ticket; consumers must follow the current maxLength.",
"schema": {
"type": "string",
"maxLength": 538
}
}
]
{
"200": {
"description": "Complete bytes currently stored at the ticket-bound path.",
"content": {
"application/octet-stream": {
"schema": {
"type": "string",
"format": "binary"
}
}
},
"headers": {
"Cache-Control": {
"schema": {
"type": "string",
"example": "no-store"
}
},
"Content-Disposition": {
"schema": {
"type": "string"
}
},
"Content-Length": {
"schema": {
"type": "string"
}
},
"Content-Type": {
"schema": {
"type": "string",
"example": "application/octet-stream"
}
},
"Referrer-Policy": {
"schema": {
"type": "string",
"example": "no-referrer"
}
},
"X-Content-Type-Options": {
"schema": {
"type": "string",
"example": "nosniff"
}
}
}
},
"302": {
"description": "HTTPS Drive9 storage redirect with bounded presign exposure.",
"headers": {
"Cache-Control": {
"schema": {
"type": "string",
"example": "no-store"
}
},
"Content-Length": {
"schema": {
"type": "string",
"example": "0"
}
},
"Location": {
"description": "Validated Drive9 storage URL.",
"schema": {
"type": "string",
"format": "uri"
}
},
"Referrer-Policy": {
"schema": {
"type": "string",
"example": "no-referrer"
}
},
"X-Content-Type-Options": {
"schema": {
"type": "string",
"example": "nosniff"
}
}
}
},
"404": {
"description": "Invalid, expired, or missing file.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"429": {
"description": "Download redemption rate limit exceeded.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"502": {
"description": "Drive9 returned an invalid response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"503": {
"description": "Download service temporarily unavailable.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}

Read the current Organization

Returns safe Organization information derived only from the active Organization Key. Caller-supplied Organization selectors do not change its scope.

Authorization: OrganizationApiKey; persisted credentials determine Organization and End User scope.

AdminController_getOrganization

[
{
"OrganizationApiKey": []
}
]
{
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CustomerOrganizationResponseDto"
}
}
}
},
"401": {
"description": "authentication_required: invalid or revoked credential.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "auth_kind_forbidden: requires an Organization Key.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"404": {
"description": "resource_not_found: Organization no longer exists.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}

List native End Users in the current Organization

Requires an Organization Key. Returns ordinary End Users only, with externalId for application identity mapping. Hidden Template Test Identities are excluded.

Authorization: OrganizationApiKey; persisted credentials determine Organization and End User scope.

AdminController_listEndUsers

[
{
"OrganizationApiKey": []
}
]
{
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CustomerEndUsersResponseDto"
}
}
}
},
"401": {
"description": "authentication_required: invalid or revoked credential.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "auth_kind_forbidden: requires an Organization Key.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}

Create a native End User in the current Organization, or return it by externalId

Requires an Organization Key. Shares Console End User field rules. With an externalId exactly equal (after trimming) to that of an End User of this Organization, whichever surface created it, returns that End User unchanged with 200: request fields are not applied and a disabled End User is returned with its status. An externalId equal to another only under the case- and accent-insensitive comparison (which also equates forms such as ß and ss) returns 409. Otherwise creates the End User and returns 201; without an externalId every request creates a new End User. Retrying a creation with the same externalId is safe, and concurrent creations with one new externalId create one End User. Creates no Platform Account, Membership, Agent or management authority. Save user.userId as your application mapping.

Authorization: OrganizationApiKey; persisted credentials determine Organization and End User scope.

AdminController_createEndUser

[
{
"OrganizationApiKey": []
}
]
{
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateEndUserRequestDto"
}
}
}
}
{
"200": {
"description": "externalId exactly identifies this End User in the Organization; it is unchanged.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CustomerEndUserResponseDto"
}
}
}
},
"201": {
"description": "End User created.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CustomerEndUserResponseDto"
}
}
}
},
"400": {
"description": "validation_error: strict native End User fields only.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"401": {
"description": "authentication_required: invalid or revoked credential.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "auth_kind_forbidden: requires an Organization Key.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"409": {
"description": "resource_conflict: externalId differs from another End User externalId in this Organization but equals it under the case- and accent-insensitive comparison. It identifies neither that End User nor a new one.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}

Read a native End User in the current Organization

Requires an Organization Key. A foreign User or hidden Template Test Identity is indistinguishable from a missing User.

Authorization: OrganizationApiKey; persisted credentials determine Organization and End User scope.

AdminController_getEndUser

[
{
"OrganizationApiKey": []
}
]
[
{
"name": "userId",
"required": true,
"in": "path",
"schema": {
"type": "string"
}
}
]
{
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CustomerEndUserResponseDto"
}
}
}
},
"401": {
"description": "authentication_required: invalid or revoked credential.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "auth_kind_forbidden: requires an Organization Key.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"404": {
"description": "resource_not_found: missing, foreign or hidden End User.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}

List User API Keys for an ordinary End User

Requires an Organization Key and an active ordinary End User in the current Organization. Returns active and revoked Key metadata without tokens or stored secret hashes.

Authorization: OrganizationApiKey; persisted credentials determine Organization and End User scope.

AdminController_listUserApiKeys

[
{
"OrganizationApiKey": []
}
]
[
{
"name": "userId",
"required": true,
"in": "path",
"schema": {
"type": "string"
}
}
]
{
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ListUserApiKeysResponseDto"
}
}
}
},
"400": {
"description": "validation_error: missing, foreign, hidden or disabled End User.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"401": {
"description": "authentication_required: invalid or revoked credential.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "auth_kind_forbidden: requires an Organization Key.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}

Create a User API Key for an ordinary End User

Creates a key only for an active ordinary End User in the current Organization. Requires an Organization Key. The name is trimmed before enforcing 1–100 characters; additional request fields are ignored. Returns the issued token without exposing its stored secret hash.

Authorization: OrganizationApiKey; persisted credentials determine Organization and End User scope.

AdminController_createUserApiKey

[
{
"OrganizationApiKey": []
}
]
[
{
"name": "userId",
"required": true,
"in": "path",
"schema": {
"type": "string"
}
}
]
{
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateUserApiKeyBodyDto"
}
}
}
}
{
"201": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateUserApiKeyResponseDto"
}
}
}
},
"400": {
"description": "validation_error: invalid name, or missing, foreign, hidden or disabled End User.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"401": {
"description": "authentication_required: invalid or revoked credential.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "auth_kind_forbidden: requires an Organization Key.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}

POST /api/v1/org/user-api-keys/{id}/rotate

Section titled “POST /api/v1/org/user-api-keys/{id}/rotate”

Rotate an ordinary End User API Key

Requires an Organization Key and an active Key owned by an active ordinary End User in the current Organization. Returns a new token for the same Key; the previous token no longer authenticates.

Authorization: OrganizationApiKey; persisted credentials determine Organization and End User scope.

AdminController_rotateUserApiKey

[
{
"OrganizationApiKey": []
}
]
[
{
"name": "id",
"required": true,
"in": "path",
"schema": {
"type": "string"
}
}
]
{
"201": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateUserApiKeyResponseDto"
}
}
}
},
"400": {
"description": "validation_error: missing, foreign or revoked Key, or missing, foreign, hidden or disabled End User.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"401": {
"description": "authentication_required: invalid or revoked credential.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "auth_kind_forbidden: requires an Organization Key.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}

POST /api/v1/org/user-api-keys/{id}/revoke

Section titled “POST /api/v1/org/user-api-keys/{id}/revoke”

Revoke an ordinary End User API Key

Requires an Organization Key and an active ordinary End User in the current Organization. Returns the revoked Key metadata without a token; the token no longer authenticates. An already revoked Key remains revoked.

Authorization: OrganizationApiKey; persisted credentials determine Organization and End User scope.

AdminController_revokeUserApiKey

[
{
"OrganizationApiKey": []
}
]
[
{
"name": "id",
"required": true,
"in": "path",
"schema": {
"type": "string"
}
}
]
{
"201": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RevokeUserApiKeyResponseDto"
}
}
}
},
"400": {
"description": "validation_error: missing or foreign Key, or missing, foreign, hidden or disabled End User.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"401": {
"description": "authentication_required: invalid or revoked credential.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "auth_kind_forbidden: requires an Organization Key.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}

Read the Session’s Realtime connection

Returns the Session’s newest Realtime connection: the live one when it exists, otherwise the most recently ended one with its final usage.

Authorization: UserApiKey; persisted credentials determine Organization and End User scope.

getRealtimeConnection

[
{
"UserApiKey": []
}
]
[
{
"name": "id",
"required": true,
"in": "path",
"schema": {
"type": "string"
}
}
]
{
"200": {
"description": "Realtime connection.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RealtimeConnectionResponseOpenApiDto"
}
}
}
},
"401": {
"description": "ErrorEnvelope code: authentication_required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "ErrorEnvelope code: user_api_key_required. Only a User API Key is accepted; a browser Session or an Organization API Key is refused.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"404": {
"description": "ErrorEnvelope code: session_not_found, realtime_connection_not_found (the Session never had one).",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"503": {
"description": "ErrorEnvelope code: admission_unavailable. Retry the request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}

Open the Session’s Realtime connection

Admits a Realtime connection on an existing Session owned by the authenticated End User. The connection inherits the Session’s Agent and Billing Tag and freezes the Session’s selected Realtime Model and its provider identity. A null Session selection uses the release default; a withdrawn selection is refused without fallback. Changing the Session selection affects only the next connection. The response carries a first one-time connect token; mint more with POST /api/v1/user/sessions/{id}/realtime/connect-tokens. A Session has at most one live (connecting, active or paused) Realtime connection: while one exists this route answers 409 realtime_connection_live with details [{ “path”: “/”, “reason”: “live realtime connection ” }]. Text and Realtime interaction may alternate on the same Session. A connection that never connects within 120 seconds, or whose server runtime stopped renewing its lease for 60 seconds, is ended automatically.

Authorization: UserApiKey; persisted credentials determine Organization and End User scope.

openRealtimeConnection

[
{
"UserApiKey": []
}
]
[
{
"name": "id",
"required": true,
"in": "path",
"schema": {
"type": "string"
}
}
]
{
"required": false,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/OpenRealtimeConnectionOpenApiDto"
}
}
}
}
{
"201": {
"description": "The admitted Realtime connection and a one-time connect token.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/OpenRealtimeConnectionResponseOpenApiDto"
}
}
}
},
"400": {
"description": "ErrorEnvelope code: validation_error, audio_format_unsupported.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"401": {
"description": "ErrorEnvelope code: authentication_required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "ErrorEnvelope code: user_api_key_required. Only a User API Key is accepted; a browser Session or an Organization API Key is refused.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"404": {
"description": "ErrorEnvelope code: session_not_found (missing, deleted or not owned).",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"409": {
"description": "ErrorEnvelope code: realtime_connection_live, session_read_only, session_switch_in_progress, realtime_not_enabled, realtime_language_unsupported, realtime_model_unavailable.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"503": {
"description": "ErrorEnvelope code: admission_unavailable. Retry the request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}

DELETE /api/v1/user/sessions/{id}/realtime

Section titled “DELETE /api/v1/user/sessions/{id}/realtime”

End the Session’s Realtime connection

Ends the live Realtime connection on whichever server owns it, settles its usage and closes its WebSocket with session.ended. Ending an already-ended newest connection returns it unchanged.

Authorization: UserApiKey; persisted credentials determine Organization and End User scope.

endRealtimeConnection

[
{
"UserApiKey": []
}
]
[
{
"name": "id",
"required": true,
"in": "path",
"schema": {
"type": "string"
}
}
]
{
"200": {
"description": "The ended Realtime connection.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RealtimeConnectionResponseOpenApiDto"
}
}
}
},
"401": {
"description": "ErrorEnvelope code: authentication_required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "ErrorEnvelope code: user_api_key_required. Only a User API Key is accepted; a browser Session or an Organization API Key is refused.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"404": {
"description": "ErrorEnvelope code: session_not_found, realtime_connection_not_found.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"503": {
"description": "ErrorEnvelope code: admission_unavailable. Retry the request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}

POST /api/v1/user/sessions/{id}/realtime/connect-tokens

Section titled “POST /api/v1/user/sessions/{id}/realtime/connect-tokens”

Mint a one-time connect token for the live Realtime connection

Use it to connect or reconnect the WebSocket, for example from a device that has no API key. Reconnecting within 60 seconds of a drop keeps the connection and its running task; send resume_after_event_id to replay missed task events.

Authorization: UserApiKey; persisted credentials determine Organization and End User scope.

createRealtimeConnectToken

[
{
"UserApiKey": []
}
]
[
{
"name": "id",
"required": true,
"in": "path",
"schema": {
"type": "string"
}
}
]
{
"201": {
"description": "A one-time connect token.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RealtimeConnectGrantOpenApiDto"
}
}
}
},
"401": {
"description": "ErrorEnvelope code: authentication_required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "ErrorEnvelope code: user_api_key_required. Only a User API Key is accepted; a browser Session or an Organization API Key is refused.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"404": {
"description": "ErrorEnvelope code: session_not_found, realtime_connection_not_found.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"409": {
"description": "ErrorEnvelope code: realtime_connection_ended.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"503": {
"description": "ErrorEnvelope code: admission_unavailable. Retry the request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}

GET /api/v1/user/sessions/{id}/realtime/ws

Section titled “GET /api/v1/user/sessions/{id}/realtime/ws”

Open the Realtime connection WebSocket

Upgrade to WebSocket with the tidb-link.realtime.v1 subprotocol, then send session.connect with a one-time connect token for this Session as the first frame (default handshake deadline 10 seconds); see the Realtime voice guide for the protocol. A replica holding too many sockets that await session.connect, or too many sockets in total, refuses the upgrade with 429 before the handshake without spending the token; retry with bounded backoff. 401, 403 and 404 apply only to plain HTTP.

Authorization: the WebSocket upgrade carries no API Key; the one-time connect token in its first session.connect frame admits it. A plain HTTP request with the owning UserApiKey receives 426.

openRealtimeWebSocket

[
{
"UserApiKey": []
}
]
[
{
"name": "id",
"required": true,
"in": "path",
"schema": {
"type": "string"
}
},
{
"name": "Sec-WebSocket-Protocol",
"in": "header",
"required": true,
"schema": {
"type": "string",
"enum": [
"tidb-link.realtime.v1"
]
}
}
]
{
"101": {
"description": "WebSocket upgraded; send session.connect first."
},
"400": {
"description": "WebSocket upgrade without the tidb-link.realtime.v1 subprotocol."
},
"401": {
"description": "ErrorEnvelope code: authentication_required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "ErrorEnvelope code: user_api_key_required. Only a User API Key is accepted; a browser Session or an Organization API Key is refused.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"404": {
"description": "ErrorEnvelope code: session_not_found (missing, deleted or not owned).",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"426": {
"description": "ErrorEnvelope code: websocket_required. WebSocket upgrade required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
},
"headers": {
"Cache-Control": {
"schema": {
"type": "string",
"enum": [
"no-store"
]
}
}
}
},
"429": {
"description": "Replica connection admission limit reached; back off. The connect token is not spent."
}
}

GET /api/v1/org/users/{userId}/sessions/{id}/realtime

Section titled “GET /api/v1/org/users/{userId}/sessions/{id}/realtime”

Read an ordinary User’s latest Realtime connection

Authorization: OrganizationApiKey; persisted credentials determine Organization and End User scope.

getOrganizationRealtimeConnection

[
{
"OrganizationApiKey": []
}
]
[
{
"name": "userId",
"required": true,
"in": "path",
"schema": {
"type": "string"
}
},
{
"name": "id",
"required": true,
"in": "path",
"schema": {
"type": "string"
}
}
]
{
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RealtimeConnectionResponseOpenApiDto"
}
}
}
},
"401": {
"description": "ErrorEnvelope code: authentication_required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "auth_kind_forbidden: an Organization API Key is required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"404": {
"description": "session_not_found or realtime_connection_not_found: missing, hidden, foreign or mismatched ordinary owner and Session.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"503": {
"description": "ErrorEnvelope code: admission_unavailable. Retry the request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}

POST /api/v1/org/users/{userId}/sessions/{id}/realtime

Section titled “POST /api/v1/org/users/{userId}/sessions/{id}/realtime”

Open an ordinary User’s Realtime connection

Uses the actual Organization Key and explicit owner. Rotation or revocation of that exact credential ends this connection and invalidates its connect tokens; accepted Turns continue. Fresh authority opens a new connection on the retained Session.

Authorization: OrganizationApiKey; persisted credentials determine Organization and End User scope.

openOrganizationRealtimeConnection

[
{
"OrganizationApiKey": []
}
]
[
{
"name": "userId",
"required": true,
"in": "path",
"schema": {
"type": "string"
}
},
{
"name": "id",
"required": true,
"in": "path",
"schema": {
"type": "string"
}
}
]
{
"required": false,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/OpenRealtimeConnectionOpenApiDto"
}
}
}
}
{
"201": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/OpenRealtimeConnectionResponseOpenApiDto"
}
}
}
},
"400": {
"description": "validation_error, audio_format_unsupported.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"401": {
"description": "ErrorEnvelope code: authentication_required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "auth_kind_forbidden: an Organization API Key is required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"404": {
"description": "session_not_found or realtime_connection_not_found: missing, hidden, foreign or mismatched ordinary owner and Session.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"409": {
"description": "realtime_connection_live, session_read_only, session_switch_in_progress, realtime_not_enabled, realtime_model_unavailable, realtime_language_unsupported.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"503": {
"description": "ErrorEnvelope code: admission_unavailable. Retry the request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}

DELETE /api/v1/org/users/{userId}/sessions/{id}/realtime

Section titled “DELETE /api/v1/org/users/{userId}/sessions/{id}/realtime”

End an ordinary User’s Realtime connection

Authorization: OrganizationApiKey; persisted credentials determine Organization and End User scope.

endOrganizationRealtimeConnection

[
{
"OrganizationApiKey": []
}
]
[
{
"name": "userId",
"required": true,
"in": "path",
"schema": {
"type": "string"
}
},
{
"name": "id",
"required": true,
"in": "path",
"schema": {
"type": "string"
}
}
]
{
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RealtimeConnectionResponseOpenApiDto"
}
}
}
},
"401": {
"description": "ErrorEnvelope code: authentication_required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "auth_kind_forbidden: an Organization API Key is required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"404": {
"description": "session_not_found or realtime_connection_not_found: missing, hidden, foreign or mismatched ordinary owner and Session.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"503": {
"description": "ErrorEnvelope code: admission_unavailable. Retry the request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}

POST /api/v1/org/users/{userId}/sessions/{id}/realtime/connect-tokens

Section titled “POST /api/v1/org/users/{userId}/sessions/{id}/realtime/connect-tokens”

Mint a connect token for an ordinary User’s live Realtime connection

The terminal redeems the token at the returned WebSocket URL without presenting an API key. Neither fresh authority nor a new token revives an ended connection.

Authorization: OrganizationApiKey; persisted credentials determine Organization and End User scope.

createOrganizationRealtimeConnectToken

[
{
"OrganizationApiKey": []
}
]
[
{
"name": "userId",
"required": true,
"in": "path",
"schema": {
"type": "string"
}
},
{
"name": "id",
"required": true,
"in": "path",
"schema": {
"type": "string"
}
}
]
{
"201": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RealtimeConnectGrantOpenApiDto"
}
}
}
},
"401": {
"description": "ErrorEnvelope code: authentication_required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "auth_kind_forbidden: an Organization API Key is required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"404": {
"description": "session_not_found or realtime_connection_not_found: missing, hidden, foreign or mismatched ordinary owner and Session.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"409": {
"description": "realtime_connection_ended.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"503": {
"description": "ErrorEnvelope code: admission_unavailable. Retry the request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}

Read the Organization’s MCP OAuth return URL allowlist.

Authorization: OrganizationApiKey; persisted credentials determine Organization scope; no End User scope. Console owners manage the same allowlist; a Key revoked or rotated before the change commits is refused. User API Keys have no MCP routes.

OrganizationMcpOAuthController_listReturnUrls

[
{
"OrganizationApiKey": []
}
]
{
"200": {
"description": "The allowlist.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"returnUrls"
],
"additionalProperties": false,
"properties": {
"returnUrls": {
"type": "array",
"maxItems": 20,
"items": {
"type": "string",
"format": "uri",
"maxLength": 2048
},
"description": "Absolute `https` URLs (`http` only on `localhost`, `127.0.0.1` or `[::1]`) without credentials, query or fragment."
}
}
}
}
}
},
"400": {
"description": "Invalid MCP request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"401": {
"description": "authentication_required: missing credentials, or the acting credential was revoked or rotated before the change committed.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "The credential cannot manage this Organization's MCP registrations; auth_kind_forbidden for an API Key that is not an Organization API Key.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}

Replace the Organization’s MCP OAuth return URL allowlist.

An MCP OAuth authorization an Application Server starts returns the browser, with its one-time confirmation value, only to a return URL whose origin and path equal an entry. Removing an entry refuses later starts; flows already started keep their return URL. Console owners manage the same allowlist.

Authorization: OrganizationApiKey; persisted credentials determine Organization scope; no End User scope. Console owners manage the same allowlist; a Key revoked or rotated before the change commits is refused. User API Keys have no MCP routes.

OrganizationMcpOAuthController_replaceReturnUrls

[
{
"OrganizationApiKey": []
}
]
{
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"returnUrls"
],
"additionalProperties": false,
"properties": {
"returnUrls": {
"type": "array",
"maxItems": 20,
"items": {
"type": "string",
"format": "uri",
"maxLength": 2048
},
"description": "Absolute `https` URLs (`http` only on `localhost`, `127.0.0.1` or `[::1]`) without credentials, query or fragment."
}
}
}
}
}
}
{
"200": {
"description": "The allowlist.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"returnUrls"
],
"additionalProperties": false,
"properties": {
"returnUrls": {
"type": "array",
"maxItems": 20,
"items": {
"type": "string",
"format": "uri",
"maxLength": 2048
},
"description": "Absolute `https` URLs (`http` only on `localhost`, `127.0.0.1` or `[::1]`) without credentials, query or fragment."
}
}
}
}
}
},
"400": {
"description": "Invalid MCP request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"401": {
"description": "authentication_required: missing credentials, or the acting credential was revoked or rotated before the change committed.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "The credential cannot manage this Organization's MCP registrations; auth_kind_forbidden for an API Key that is not an Organization API Key.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}

POST /api/v1/org/mcp/servers/{serverId}/authorization/oauth/start

Section titled “POST /api/v1/org/mcp/servers/{serverId}/authorization/oauth/start”

Start authorizing the Organization’s MCP Authorization with OAuth.

For mode organization_oauth. Agent Service reads the MCP server’s 401 challenge and its OAuth protected resource metadata (RFC 9728), which names the authorization server, possibly on another public host, and that server’s metadata (RFC 8414). It prepares an authorization code request with PKCE (S256), the MCP server as resource, a single-use state, the registration’s MCP OAuth Client and Agent Service’s OAuth callback, https://<PUBLIC_API_URL host>/api/v1/mcp/oauth/callback, as redirect URI; the scope is the one the server’s 401 challenge names, otherwise the metadata’s scopes_supported. After the server refused the authorization with insufficient_scope, the scope is the one it was granted together with the scope the server required (requiredScope). The MCP OAuth Client is the registration’s pre-registered client; without one, the deployment’s Client ID Metadata Document, https://<PUBLIC_API_URL host>/api/v1/mcp/oauth/client-metadata.json, when the authorization server advertises client_id_metadata_document_supported; otherwise a client Agent Service registers once for the registration with Dynamic Client Registration (RFC 7591) through MCP egress and reuses. A registered client is registered again when the authorization server changes or its secret is about to expire, which invalidates the registration’s MCP Authorizations (client_changed). Send the browser to authorizationUrl before expiresAt. After consent the callback redeems the code, holds the tokens pending confirmation and redirects the browser to returnUrl with mcpOAuth=pending_confirmation, serverId and a one-time confirmation value, or with mcpOAuth=failed, serverId and a reason. Nothing is usable until the confirmation is submitted. The return URL must match an entry of the Organization’s MCP OAuth return URL allowlist, at the start and again when the browser returns. Confirm with …/authorization/oauth/confirm once you have verified that the person who consented may authorize the Organization’s shared account.

Authorization: OrganizationApiKey; persisted credentials determine Organization scope; no End User scope. Changes are attributed to the authentic Organization API Key in management audit; a Key revoked or rotated before the change commits is refused. User API Keys have no MCP routes. MCP Server Registrations belong to the Organization.

OrganizationMcpOAuthController_start

[
{
"OrganizationApiKey": []
}
]
[
{
"name": "serverId",
"required": true,
"in": "path",
"schema": {
"type": "string",
"pattern": "^mcp_[a-f0-9-]{36}$"
}
}
]
{
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"returnUrl"
],
"additionalProperties": false,
"properties": {
"returnUrl": {
"type": "string",
"format": "uri",
"maxLength": 2048,
"description": "Where the browser returns after consent: a URL whose origin and path match an entry of the Organization's MCP OAuth return URL allowlist. Its query is kept, and Agent Service adds `mcpOAuth`, `serverId` and either `confirmation` or `reason`."
}
}
}
}
}
}
{
"200": {
"description": "Where to send the browser.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"authorizationUrl",
"expiresAt"
],
"additionalProperties": false,
"properties": {
"authorizationUrl": {
"type": "string",
"format": "uri"
},
"expiresAt": {
"type": "string",
"format": "date-time",
"description": "The callback accepts the authorization until then."
}
}
}
}
}
},
"400": {
"description": "Invalid MCP request.\n\n`validation_error` with `details.reason` `return_url_not_allowed`: the return URL matches no entry of the allowlist.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"401": {
"description": "authentication_required: missing credentials, or the acting credential was revoked or rotated before the change committed.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "The credential cannot manage this Organization's MCP registrations; auth_kind_forbidden for an API Key that is not an Organization API Key.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"404": {
"description": "MCP registration not found.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"409": {
"description": "`validation_error`: the registration's mode is not authorized this way, or it changed during the start. `mcp_oauth_unavailable` with `details.reason`: `callback_unconfigured` (the deployment has no `PUBLIC_API_URL`) or `client_registration_unsupported` (no pre-registered OAuth client, and the authorization server accepts neither the deployment's Client ID Metadata Document nor Dynamic Client Registration).",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"502": {
"description": "`mcp_oauth_unavailable` with `details.reason`: `authorization_server_unavailable` (the protected resource or authorization server metadata could not be read through MCP egress), `authorization_server_unsupported` (no HTTPS authorization endpoint, or no PKCE with S256) or `client_registration_failed` (Dynamic Client Registration was refused, failed or was redirected).",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}

POST /api/v1/org/mcp/servers/{serverId}/authorization/oauth/confirm

Section titled “POST /api/v1/org/mcp/servers/{serverId}/authorization/oauth/confirm”

Confirm an OAuth authorization of the Organization’s MCP Authorization.

Submit the confirmation value the browser returned with. The tokens become the Organization’s credential, replacing any it held, the authorization becomes usable and its catalog is discovered. The value works once and expires shortly after the callback; any submission uses it up.

Authorization: OrganizationApiKey; persisted credentials determine Organization scope; no End User scope. Changes are attributed to the authentic Organization API Key in management audit; a Key revoked or rotated before the change commits is refused. User API Keys have no MCP routes. MCP Server Registrations belong to the Organization.

OrganizationMcpOAuthController_confirm

[
{
"OrganizationApiKey": []
}
]
[
{
"name": "serverId",
"required": true,
"in": "path",
"schema": {
"type": "string",
"pattern": "^mcp_[a-f0-9-]{36}$"
}
}
]
{
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"confirmation"
],
"additionalProperties": false,
"properties": {
"confirmation": {
"type": "string",
"minLength": 1,
"maxLength": 256,
"writeOnly": true,
"description": "The `confirmation` query parameter the browser returned with."
}
}
}
}
}
}
{
"200": {
"description": "The Organization's MCP Authorization.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"authorization"
],
"additionalProperties": false,
"properties": {
"authorization": {
"type": "object",
"description": "The Organization's MCP Authorization of this registration. Its credential is write-only.",
"required": [
"owner",
"state",
"invalidReason",
"requiredScope",
"hasCredential",
"catalog",
"updatedAt"
],
"additionalProperties": false,
"properties": {
"owner": {
"type": "object",
"required": [
"kind"
],
"additionalProperties": false,
"properties": {
"kind": {
"type": "string",
"enum": [
"organization"
]
}
}
},
"state": {
"type": "string",
"enum": [
"usable",
"invalid",
"revoked"
]
},
"invalidReason": {
"type": "string",
"nullable": true,
"enum": [
"endpoint_changed",
"mode_changed",
"unauthorized",
"forbidden",
"insufficient_scope",
"token_rejected",
"client_changed"
],
"description": "Why an invalid authorization stopped being usable; null otherwise. endpoint_changed, mode_changed and client_changed (another OAuth client ID) follow a registration change. During a Turn the server refused the credential: unauthorized (HTTP 401), forbidden (403) or insufficient_scope (403 with that challenge). token_rejected: the authorization server rejected the request for an access token, with the client credentials or the refresh token, or an expired OAuth token has no refresh token. Setting the credential again, or authorizing again with OAuth, makes the authorization usable again."
},
"requiredScope": {
"type": "string",
"nullable": true,
"maxLength": 512,
"description": "The scope the server said it requires when it refused the credential with insufficient_scope, when it named a valid one; null otherwise. Authorizing again with OAuth requests it together with the scope the authorization was granted."
},
"hasCredential": {
"type": "boolean"
},
"catalog": {
"type": "object",
"nullable": true,
"description": "The catalog new AgentRuns freeze; null until discovery succeeds under this authorization.",
"required": [
"discoveredAt",
"toolNames"
],
"additionalProperties": false,
"properties": {
"discoveredAt": {
"type": "string",
"format": "date-time",
"description": "When the server's tools were last listed, by discovery or before a call."
},
"toolNames": {
"type": "array",
"items": {
"type": "string"
}
}
}
},
"updatedAt": {
"type": "string",
"format": "date-time"
}
}
}
}
}
}
}
},
"400": {
"description": "Invalid MCP request.\n\n`mcp_oauth_confirmation_invalid`: the value is unknown, already submitted or expired, or was issued for another owner or registration, or the registration's endpoint, mode or OAuth client changed since the start. Nothing becomes usable; start the authorization again.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"401": {
"description": "authentication_required: missing credentials, or the acting credential was revoked or rotated before the change committed.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "The credential cannot manage this Organization's MCP registrations; auth_kind_forbidden for an API Key that is not an Organization API Key.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"404": {
"description": "MCP registration not found.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}

POST /api/v1/org/users/{userId}/mcp/servers/{serverId}/authorization/oauth/start

Section titled “POST /api/v1/org/users/{userId}/mcp/servers/{serverId}/authorization/oauth/start”

Start an End User’s OAuth authorization of an MCP registration.

For mode end_user_oauth. Agent Service reads the MCP server’s 401 challenge and its OAuth protected resource metadata (RFC 9728), which names the authorization server, possibly on another public host, and that server’s metadata (RFC 8414). It prepares an authorization code request with PKCE (S256), the MCP server as resource, a single-use state, the registration’s MCP OAuth Client and Agent Service’s OAuth callback, https://<PUBLIC_API_URL host>/api/v1/mcp/oauth/callback, as redirect URI; the scope is the one the server’s 401 challenge names, otherwise the metadata’s scopes_supported. After the server refused the authorization with insufficient_scope, the scope is the one it was granted together with the scope the server required (requiredScope). The MCP OAuth Client is the registration’s pre-registered client; without one, the deployment’s Client ID Metadata Document, https://<PUBLIC_API_URL host>/api/v1/mcp/oauth/client-metadata.json, when the authorization server advertises client_id_metadata_document_supported; otherwise a client Agent Service registers once for the registration with Dynamic Client Registration (RFC 7591) through MCP egress and reuses. A registered client is registered again when the authorization server changes or its secret is about to expire, which invalidates the registration’s MCP Authorizations (client_changed). Send the browser to authorizationUrl before expiresAt. After consent the callback redeems the code, holds the tokens pending confirmation and redirects the browser to returnUrl with mcpOAuth=pending_confirmation, serverId and a one-time confirmation value, or with mcpOAuth=failed, serverId and a reason. Nothing is usable until the confirmation is submitted. The return URL must match an entry of the Organization’s MCP OAuth return URL allowlist, at the start and again when the browser returns. Show the End User the link; when their browser comes back, verify which End User is signed in to your application and confirm for that End User with …/authorization/oauth/confirm. A link opened by someone else then binds nothing: their confirmation names another End User, or none.

Authorization: OrganizationApiKey; persisted credentials determine Organization scope. The path userId selects an ordinary End User that must belong to that Organization, and the change applies to that End User’s MCP Authorization only. Changes are attributed to the authentic Organization API Key; a Key revoked or rotated before the change commits is refused. User API Keys have no MCP routes. MCP Server Registrations belong to the Organization.

EndUserMcpOAuthController_start

[
{
"OrganizationApiKey": []
}
]
[
{
"name": "userId",
"required": true,
"in": "path",
"schema": {
"type": "string"
}
},
{
"name": "serverId",
"required": true,
"in": "path",
"schema": {
"type": "string",
"pattern": "^mcp_[a-f0-9-]{36}$"
}
}
]
{
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"returnUrl"
],
"additionalProperties": false,
"properties": {
"returnUrl": {
"type": "string",
"format": "uri",
"maxLength": 2048,
"description": "Where the browser returns after consent: a URL whose origin and path match an entry of the Organization's MCP OAuth return URL allowlist. Its query is kept, and Agent Service adds `mcpOAuth`, `serverId` and either `confirmation` or `reason`."
}
}
}
}
}
}
{
"200": {
"description": "Where to send the browser.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"authorizationUrl",
"expiresAt"
],
"additionalProperties": false,
"properties": {
"authorizationUrl": {
"type": "string",
"format": "uri"
},
"expiresAt": {
"type": "string",
"format": "date-time",
"description": "The callback accepts the authorization until then."
}
}
}
}
}
},
"400": {
"description": "Invalid MCP request.\n\n`validation_error` with `details.reason` `return_url_not_allowed`: the return URL matches no entry of the allowlist.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"401": {
"description": "authentication_required: missing credentials, or the acting credential was revoked or rotated before the change committed.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "The credential cannot manage this Organization's MCP registrations; auth_kind_forbidden for an API Key that is not an Organization API Key.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"404": {
"description": "The MCP registration was not found, or `resource_not_found`: the path userId is not an ordinary End User of the Organization.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"409": {
"description": "`validation_error`: the registration's mode is not authorized this way, or it changed during the start. `mcp_oauth_unavailable` with `details.reason`: `callback_unconfigured` (the deployment has no `PUBLIC_API_URL`) or `client_registration_unsupported` (no pre-registered OAuth client, and the authorization server accepts neither the deployment's Client ID Metadata Document nor Dynamic Client Registration).",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"502": {
"description": "`mcp_oauth_unavailable` with `details.reason`: `authorization_server_unavailable` (the protected resource or authorization server metadata could not be read through MCP egress), `authorization_server_unsupported` (no HTTPS authorization endpoint, or no PKCE with S256) or `client_registration_failed` (Dynamic Client Registration was refused, failed or was redirected).",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}

POST /api/v1/org/users/{userId}/mcp/servers/{serverId}/authorization/oauth/confirm

Section titled “POST /api/v1/org/users/{userId}/mcp/servers/{serverId}/authorization/oauth/confirm”

Confirm an End User’s OAuth authorization of an MCP registration.

Submit the confirmation value the browser returned with, for the End User you verified is signed in. Only a value issued for this End User and registration is accepted: the tokens become the End User’s credential, replacing any they held, the authorization becomes usable and that End User’s catalog is discovered. The value works once and expires shortly after the callback; any submission uses it up, so a value submitted for another End User binds nobody.

Authorization: OrganizationApiKey; persisted credentials determine Organization scope. The path userId selects an ordinary End User that must belong to that Organization, and the change applies to that End User’s MCP Authorization only. Changes are attributed to the authentic Organization API Key; a Key revoked or rotated before the change commits is refused. User API Keys have no MCP routes. MCP Server Registrations belong to the Organization.

EndUserMcpOAuthController_confirm

[
{
"OrganizationApiKey": []
}
]
[
{
"name": "userId",
"required": true,
"in": "path",
"schema": {
"type": "string"
}
},
{
"name": "serverId",
"required": true,
"in": "path",
"schema": {
"type": "string",
"pattern": "^mcp_[a-f0-9-]{36}$"
}
}
]
{
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"confirmation"
],
"additionalProperties": false,
"properties": {
"confirmation": {
"type": "string",
"minLength": 1,
"maxLength": 256,
"writeOnly": true,
"description": "The `confirmation` query parameter the browser returned with."
}
}
}
}
}
}
{
"200": {
"description": "The End User's MCP Authorization.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"authorization"
],
"additionalProperties": false,
"properties": {
"authorization": {
"type": "object",
"description": "The End User's MCP Authorization of this registration. Its credential is write-only.",
"required": [
"owner",
"state",
"invalidReason",
"requiredScope",
"hasCredential",
"catalog",
"updatedAt"
],
"additionalProperties": false,
"properties": {
"owner": {
"type": "object",
"required": [
"kind"
],
"additionalProperties": false,
"properties": {
"kind": {
"type": "string",
"enum": [
"end_user"
]
}
}
},
"state": {
"type": "string",
"enum": [
"usable",
"invalid",
"revoked"
]
},
"invalidReason": {
"type": "string",
"nullable": true,
"enum": [
"endpoint_changed",
"mode_changed",
"unauthorized",
"forbidden",
"insufficient_scope",
"token_rejected",
"client_changed"
],
"description": "Why an invalid authorization stopped being usable; null otherwise. endpoint_changed, mode_changed and client_changed (another OAuth client ID) follow a registration change. During a Turn the server refused the credential: unauthorized (HTTP 401), forbidden (403) or insufficient_scope (403 with that challenge). token_rejected: the authorization server rejected the request for an access token, with the client credentials or the refresh token, or an expired OAuth token has no refresh token. Setting the credential again, or authorizing again with OAuth, makes the authorization usable again."
},
"requiredScope": {
"type": "string",
"nullable": true,
"maxLength": 512,
"description": "The scope the server said it requires when it refused the credential with insufficient_scope, when it named a valid one; null otherwise. Authorizing again with OAuth requests it together with the scope the authorization was granted."
},
"hasCredential": {
"type": "boolean"
},
"catalog": {
"type": "object",
"nullable": true,
"description": "The catalog new AgentRuns freeze; null until discovery succeeds under this authorization.",
"required": [
"discoveredAt",
"toolNames"
],
"additionalProperties": false,
"properties": {
"discoveredAt": {
"type": "string",
"format": "date-time",
"description": "When the server's tools were last listed, by discovery or before a call."
},
"toolNames": {
"type": "array",
"items": {
"type": "string"
}
}
}
},
"updatedAt": {
"type": "string",
"format": "date-time"
}
}
}
}
}
}
}
},
"400": {
"description": "Invalid MCP request.\n\n`mcp_oauth_confirmation_invalid`: the value is unknown, already submitted or expired, or was issued for another owner or registration, or the registration's endpoint, mode or OAuth client changed since the start. Nothing becomes usable; start the authorization again.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"401": {
"description": "authentication_required: missing credentials, or the acting credential was revoked or rotated before the change committed.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "The credential cannot manage this Organization's MCP registrations; auth_kind_forbidden for an API Key that is not an Organization API Key.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"404": {
"description": "The MCP registration was not found, or `resource_not_found`: the path userId is not an ordinary End User of the Organization.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}

GET /api/v1/org/users/{userId}/billing/usage

Section titled “GET /api/v1/org/users/{userId}/billing/usage”

Aggregate one organization user billing range

Authorization: OrganizationApiKey; persisted credentials determine Organization and End User scope.

OrganizationBillingApiController_aggregate

[
{
"OrganizationApiKey": []
}
]
[
{
"name": "userId",
"required": true,
"in": "path",
"schema": {
"type": "string",
"pattern": "^[a-z0-9_-]{1,64}$"
}
},
{
"name": "tagValue",
"required": false,
"in": "query",
"schema": {
"type": "string"
},
"description": "Exact case-sensitive Billing Tag value. Must be supplied together with tagKey."
},
{
"name": "tagKey",
"required": false,
"in": "query",
"schema": {
"type": "string",
"pattern": "^[a-z][a-z0-9_.-]{0,63}$"
},
"description": "Exact Billing Tag key. Must be supplied together with tagValue."
},
{
"name": "agentTemplateId",
"required": false,
"in": "query",
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 64
},
"description": "Select facts with this frozen AgentTemplate identity."
},
{
"name": "interval",
"required": false,
"in": "query",
"description": "UTC time bucket. Weeks start Monday at 00:00 UTC; months start on day 1 at 00:00 UTC. The first and last buckets may be partial for an unaligned half-open range.",
"schema": {
"type": "string",
"enum": [
"hour",
"day",
"week",
"month"
],
"default": "day"
}
},
{
"name": "to",
"required": true,
"in": "query",
"schema": {
"type": "string",
"format": "date-time",
"pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$"
}
},
{
"name": "from",
"required": true,
"in": "query",
"schema": {
"type": "string",
"format": "date-time",
"pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$"
}
}
]
{
"200": {
"description": "Priced and unpriced aggregate usage for one organization user and exact range.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/OrganizationBillingUsageAggregateResponseOpenApiDto"
}
}
}
},
"400": {
"description": "Invalid target or query.",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/ErrorEnvelope"
},
{
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "string",
"enum": [
"invalid_billing_usage_query"
]
}
}
}
}
}
]
}
}
}
},
"401": {
"description": "Organization API key authentication failed.",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/ErrorEnvelope"
},
{
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "string",
"enum": [
"authentication_required"
]
}
}
}
}
}
]
}
}
}
},
"403": {
"description": "This authentication kind cannot use the route.",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/ErrorEnvelope"
},
{
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "string",
"enum": [
"auth_kind_forbidden"
]
}
}
}
}
}
]
}
}
}
},
"404": {
"description": "The target is outside this organization billing scope.",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/ErrorEnvelope"
},
{
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "string",
"enum": [
"billing_target_not_found"
]
}
}
}
}
}
]
}
}
}
},
"503": {
"description": "The durable audit could not be recorded.",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/ErrorEnvelope"
},
{
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "string",
"enum": [
"billing_audit_unavailable"
]
}
}
}
}
}
]
}
}
}
}
}

GET /api/v1/org/users/{userId}/billing/usage/details

Section titled “GET /api/v1/org/users/{userId}/billing/usage/details”

List one organization user billing stream using an organization API key

Authorization: OrganizationApiKey; persisted credentials determine Organization and End User scope.

OrganizationBillingApiController_details

[
{
"OrganizationApiKey": []
}
]
[
{
"name": "userId",
"required": true,
"in": "path",
"schema": {
"type": "string",
"pattern": "^[a-z0-9_-]{1,64}$"
}
},
{
"name": "tagValue",
"required": false,
"in": "query",
"schema": {
"type": "string"
},
"description": "Exact case-sensitive Billing Tag value. Must be supplied together with tagKey."
},
{
"name": "tagKey",
"required": false,
"in": "query",
"schema": {
"type": "string",
"pattern": "^[a-z][a-z0-9_.-]{0,63}$"
},
"description": "Exact Billing Tag key. Must be supplied together with tagValue."
},
{
"name": "agentTemplateId",
"required": false,
"in": "query",
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 64
},
"description": "Select facts with this frozen AgentTemplate identity."
},
{
"name": "cursor",
"required": false,
"in": "query",
"schema": {
"type": "string"
}
},
{
"name": "limit",
"required": false,
"in": "query",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 500,
"default": 100
}
},
{
"name": "kind",
"required": false,
"in": "query",
"schema": {
"enum": [
"llm",
"sandbox",
"web_search"
],
"type": "string"
}
},
{
"name": "to",
"required": true,
"in": "query",
"schema": {
"type": "string",
"format": "date-time",
"pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$"
}
},
{
"name": "from",
"required": true,
"in": "query",
"schema": {
"type": "string",
"format": "date-time",
"pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$"
}
}
]
{
"200": {
"description": "A display-safe, globally ordered billing usage page.",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"items",
"nextCursor",
"factCompleteness"
],
"properties": {
"items": {
"type": "array",
"items": {
"oneOf": [
{
"type": "object",
"additionalProperties": false,
"required": [
"kind",
"id",
"occurredAt",
"sessionId",
"turnId",
"agentRunId",
"agentTemplateId",
"attributionKind",
"costMicros",
"currency",
"pricingVersion",
"pricingEffectiveAt",
"valuationStatus",
"valuationReason",
"rateCardDigest",
"billingTag",
"realtimeConnectionId",
"realtimeConnectionLive",
"operationId",
"requestPurpose",
"provider",
"model",
"observedResponseModel",
"inputTokens",
"cachedInputTokens",
"uncachedInputTokens",
"cacheReadTokens",
"cacheWrite5mTokens",
"cacheWrite1hTokens",
"cacheWriteUnspecifiedTokens",
"outputTokens",
"inputCostMicros",
"cachedInputCostMicros",
"cacheWrite5mCostMicros",
"cacheWrite1hCostMicros",
"cacheWriteUnspecifiedCostMicros",
"outputCostMicros",
"pricingStatus",
"estimateBasis",
"contextTier"
],
"properties": {
"kind": {
"type": "string",
"enum": [
"llm"
]
},
"id": {
"type": "string"
},
"occurredAt": {
"type": "string",
"format": "date-time"
},
"sessionId": {
"type": "string"
},
"turnId": {
"type": "string",
"nullable": true,
"description": "Null for Realtime connection-scoped usage (requestPurpose voice_realtime)."
},
"agentRunId": {
"type": "string",
"nullable": true
},
"agentTemplateId": {
"type": "string",
"nullable": true
},
"attributionKind": {
"type": "string",
"enum": [
"user_level",
"system",
"unattributed"
]
},
"costMicros": {
"type": "integer",
"nullable": true
},
"currency": {
"type": "string",
"nullable": true
},
"pricingVersion": {
"type": "string"
},
"pricingEffectiveAt": {
"type": "string",
"format": "date-time"
},
"valuationStatus": {
"type": "string",
"enum": [
"priced",
"unpriced"
],
"description": "Whether this usage fact contributes to priced totals. A stored cost does not override an unpriced status."
},
"valuationReason": {
"type": "string",
"nullable": true,
"description": "Why the item is unpriced, such as no_active_sale_price, or unsettled for a Sandbox run priced at its frozen sale price that has not ended; null when priced."
},
"rateCardDigest": {
"type": "string",
"nullable": true
},
"billingTag": {
"nullable": true,
"description": "One immutable Billing Tag snapshot for this resource. Null means untagged; request fields may be omitted only where the operation documents inheritance.",
"allOf": [
{
"$ref": "#/components/schemas/BillingTag"
}
]
},
"realtimeConnectionId": {
"type": "string",
"nullable": true,
"description": "The Realtime connection of requestPurpose voice_realtime usage; null otherwise. A connection reports its usage while live and once more when it ends; each report is a separate item with the usage since the previous report, priced at the Ops sale price active at its own time, so the items of one connection sum to its settled usage."
},
"realtimeConnectionLive": {
"type": "boolean",
"nullable": true,
"description": "For requestPurpose voice_realtime usage, whether its Realtime connection is still live at read time (false once it has ended); null otherwise. The usage of a live connection appears in interim reports normally at most 60 seconds behind consumption; its final report follows when it ends."
},
"operationId": {
"type": "string",
"nullable": true
},
"requestPurpose": {
"type": "string",
"enum": [
"agent_turn",
"compaction",
"auto_title",
"manual_title",
"asr",
"voice_realtime"
]
},
"provider": {
"type": "string"
},
"model": {
"type": "string"
},
"observedResponseModel": {
"type": "string",
"nullable": true
},
"inputTokens": {
"type": "integer"
},
"cachedInputTokens": {
"type": "integer"
},
"uncachedInputTokens": {
"type": "integer"
},
"cacheReadTokens": {
"type": "integer"
},
"cacheWrite5mTokens": {
"type": "integer"
},
"cacheWrite1hTokens": {
"type": "integer"
},
"cacheWriteUnspecifiedTokens": {
"type": "integer"
},
"outputTokens": {
"type": "integer"
},
"inputCostMicros": {
"type": "integer",
"nullable": true
},
"cachedInputCostMicros": {
"type": "integer",
"nullable": true
},
"cacheWrite5mCostMicros": {
"type": "integer",
"nullable": true
},
"cacheWrite1hCostMicros": {
"type": "integer",
"nullable": true
},
"cacheWriteUnspecifiedCostMicros": {
"type": "integer",
"nullable": true
},
"outputCostMicros": {
"type": "integer",
"nullable": true
},
"pricingStatus": {
"type": "string",
"enum": [
"estimated",
"unknown"
]
},
"estimateBasis": {
"type": "string",
"enum": [
"public_list_placeholder",
"contract"
],
"nullable": true,
"description": "`contract` is the Ops sale price; `public_list_placeholder` appears only on historical usage."
},
"contextTier": {
"type": "string",
"enum": [
"short",
"long",
"all_context",
"unknown"
]
}
}
},
{
"type": "object",
"additionalProperties": false,
"required": [
"kind",
"id",
"occurredAt",
"sessionId",
"turnId",
"agentRunId",
"agentTemplateId",
"attributionKind",
"costMicros",
"currency",
"pricingVersion",
"pricingEffectiveAt",
"valuationStatus",
"valuationReason",
"rateCardDigest",
"billingTag",
"provider",
"profileId",
"specKey",
"startedAt",
"endedAt",
"durationSeconds",
"status"
],
"properties": {
"kind": {
"type": "string",
"enum": [
"sandbox"
]
},
"id": {
"type": "string"
},
"occurredAt": {
"type": "string",
"format": "date-time"
},
"sessionId": {
"type": "string"
},
"turnId": {
"type": "string"
},
"agentRunId": {
"type": "string",
"nullable": true
},
"agentTemplateId": {
"type": "string",
"nullable": true
},
"attributionKind": {
"type": "string",
"enum": [
"user_level",
"system",
"unattributed"
]
},
"costMicros": {
"type": "integer",
"nullable": true
},
"currency": {
"type": "string",
"nullable": true
},
"pricingVersion": {
"type": "string"
},
"pricingEffectiveAt": {
"type": "string",
"format": "date-time"
},
"valuationStatus": {
"type": "string",
"enum": [
"priced",
"unpriced"
],
"description": "Whether this usage fact contributes to priced totals. A stored cost does not override an unpriced status."
},
"valuationReason": {
"type": "string",
"nullable": true,
"description": "Why the item is unpriced, such as no_active_sale_price, or unsettled for a Sandbox run priced at its frozen sale price that has not ended; null when priced."
},
"rateCardDigest": {
"type": "string",
"nullable": true
},
"billingTag": {
"nullable": true,
"description": "One immutable Billing Tag snapshot for this resource. Null means untagged; request fields may be omitted only where the operation documents inheritance.",
"allOf": [
{
"$ref": "#/components/schemas/BillingTag"
}
]
},
"provider": {
"type": "string",
"enum": [
"e2b",
"tencent_ags",
"run9"
]
},
"profileId": {
"type": "string"
},
"specKey": {
"type": "string"
},
"startedAt": {
"type": "string",
"format": "date-time"
},
"endedAt": {
"type": "string",
"format": "date-time",
"nullable": true
},
"durationSeconds": {
"type": "integer",
"nullable": true
},
"status": {
"type": "string",
"enum": [
"running",
"closed",
"close_failed",
"abandoned"
]
}
}
},
{
"type": "object",
"additionalProperties": false,
"required": [
"kind",
"id",
"occurredAt",
"sessionId",
"turnId",
"agentRunId",
"agentTemplateId",
"attributionKind",
"costMicros",
"currency",
"pricingVersion",
"pricingEffectiveAt",
"valuationStatus",
"valuationReason",
"rateCardDigest",
"billingTag",
"operationId",
"provider",
"searchType",
"requestCount",
"requestedResultCount",
"returnedResultCount",
"contentTextRequested",
"requestOutcome",
"usageEvidenceStatus"
],
"properties": {
"kind": {
"type": "string",
"enum": [
"web_search"
]
},
"id": {
"type": "string"
},
"occurredAt": {
"type": "string",
"format": "date-time"
},
"sessionId": {
"type": "string"
},
"turnId": {
"type": "string"
},
"agentRunId": {
"type": "string",
"nullable": true
},
"agentTemplateId": {
"type": "string",
"nullable": true
},
"attributionKind": {
"type": "string",
"enum": [
"user_level",
"system",
"unattributed"
]
},
"costMicros": {
"type": "integer",
"nullable": true
},
"currency": {
"type": "string",
"nullable": true
},
"pricingVersion": {
"type": "string"
},
"pricingEffectiveAt": {
"type": "string",
"format": "date-time"
},
"valuationStatus": {
"type": "string",
"enum": [
"priced",
"unpriced"
],
"description": "Whether this usage fact contributes to priced totals. A stored cost does not override an unpriced status."
},
"valuationReason": {
"type": "string",
"nullable": true,
"description": "Why the item is unpriced, such as no_active_sale_price, or unsettled for a Sandbox run priced at its frozen sale price that has not ended; null when priced."
},
"rateCardDigest": {
"type": "string",
"nullable": true
},
"billingTag": {
"nullable": true,
"description": "One immutable Billing Tag snapshot for this resource. Null means untagged; request fields may be omitted only where the operation documents inheritance.",
"allOf": [
{
"$ref": "#/components/schemas/BillingTag"
}
]
},
"operationId": {
"type": "string"
},
"provider": {
"type": "string",
"enum": [
"exa"
]
},
"searchType": {
"type": "string",
"enum": [
"auto"
]
},
"requestCount": {
"type": "integer",
"enum": [
1
]
},
"requestedResultCount": {
"type": "integer"
},
"returnedResultCount": {
"type": "integer",
"nullable": true
},
"contentTextRequested": {
"type": "boolean",
"enum": [
true
]
},
"requestOutcome": {
"type": "string",
"enum": [
"succeeded",
"failed",
"aborted"
]
},
"usageEvidenceStatus": {
"type": "string",
"enum": [
"complete",
"partial",
"missing",
"unsupported"
]
}
}
}
]
}
},
"nextCursor": {
"type": "string",
"nullable": true
},
"factCompleteness": {
"type": "object",
"additionalProperties": false,
"required": [
"status",
"projectedFactCount",
"pendingIntentCount",
"indeterminateIntentCount",
"failedIntentCount",
"byKind"
],
"properties": {
"status": {
"type": "string",
"enum": [
"complete",
"incomplete"
]
},
"projectedFactCount": {
"type": "integer"
},
"pendingIntentCount": {
"type": "integer"
},
"indeterminateIntentCount": {
"type": "integer"
},
"failedIntentCount": {
"type": "integer"
},
"byKind": {
"type": "object",
"additionalProperties": {
"type": "object",
"required": [
"status",
"projectedFactCount",
"pendingIntentCount",
"indeterminateIntentCount",
"failedIntentCount"
],
"properties": {
"status": {
"type": "string",
"enum": [
"complete",
"incomplete"
]
},
"projectedFactCount": {
"type": "integer"
},
"pendingIntentCount": {
"type": "integer"
},
"indeterminateIntentCount": {
"type": "integer"
},
"failedIntentCount": {
"type": "integer"
}
}
}
}
},
"description": "Durable usage-fact completeness, with independent counters for every requested kind."
}
}
}
}
}
},
"400": {
"description": "Invalid target, query, or cursor.",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/ErrorEnvelope"
},
{
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "string",
"enum": [
"invalid_billing_usage_query",
"invalid_billing_usage_cursor"
]
}
}
}
}
}
]
}
}
}
},
"401": {
"description": "Organization API key authentication failed.",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/ErrorEnvelope"
},
{
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "string",
"enum": [
"authentication_required"
]
}
}
}
}
}
]
}
}
}
},
"403": {
"description": "This authentication kind cannot use the route.",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/ErrorEnvelope"
},
{
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "string",
"enum": [
"auth_kind_forbidden"
]
}
}
}
}
}
]
}
}
}
},
"404": {
"description": "The target is outside this organization billing scope.",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/ErrorEnvelope"
},
{
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "string",
"enum": [
"billing_target_not_found"
]
}
}
}
}
}
]
}
}
}
},
"503": {
"description": "The durable audit could not be recorded.",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/ErrorEnvelope"
},
{
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "string",
"enum": [
"billing_audit_unavailable"
]
}
}
}
}
}
]
}
}
}
}
}

List this Organization’s published, available shared Skills

Only Organization-scope Skills with a loadable published head are returned. Stable created-at/ID keyset pagination; no private or all-scopes selector.

Authorization: OrganizationApiKey; persisted credentials determine Organization scope; no End User scope. Uploads and publication are attributed to the authentic Organization API Key.

listOrganizationSkills

[
{
"OrganizationApiKey": []
}
]
[
{
"name": "If-None-Match",
"in": "header",
"description": "Authenticated conditional GET; weak tags, tag lists and * are supported.",
"required": false,
"schema": {
"type": "string",
"maxLength": 4096
}
},
{
"name": "limit",
"required": false,
"in": "query",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 200,
"default": 50
}
},
{
"name": "cursor",
"required": false,
"in": "query",
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 4096
},
"description": "Opaque signed cursor for this Organization and resource."
}
]
{
"200": {
"headers": {
"ETag": {
"description": "Representation-specific strong validator.",
"schema": {
"type": "string"
}
},
"Cache-Control": {
"schema": {
"type": "string",
"enum": [
"no-store"
]
}
}
},
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/OrganizationSkillListDto"
}
}
}
},
"304": {
"description": "The currently authorized representation matches If-None-Match; no body.",
"headers": {
"ETag": {
"description": "Representation-specific strong validator.",
"schema": {
"type": "string"
}
},
"Cache-Control": {
"schema": {
"type": "string",
"enum": [
"no-store"
]
}
}
}
},
"400": {
"description": "validation_error or invalid_cursor: invalid strict query, identifier, version, relative file path, cursor or conditional header.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
},
"headers": {
"Cache-Control": {
"schema": {
"type": "string",
"enum": [
"no-store"
]
}
}
}
},
"401": {
"description": "authentication_required: current Organization Key authority is missing, revoked, rotated or inactive.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
},
"headers": {
"Cache-Control": {
"schema": {
"type": "string",
"enum": [
"no-store"
]
}
}
}
},
"403": {
"description": "auth_kind_forbidden: requires an Organization API Key.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
},
"headers": {
"Cache-Control": {
"schema": {
"type": "string",
"enum": [
"no-store"
]
}
}
}
},
"404": {
"description": "resource_not_found or skill_file_not_found: shared Skill, published loadable Version or safe file is unavailable; foreign and private resources are indistinguishable from missing.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
},
"headers": {
"Cache-Control": {
"schema": {
"type": "string",
"enum": [
"no-store"
]
}
}
}
},
"503": {
"description": "auth_temporarily_unavailable or skill_package_store_unavailable: credential resolution or content storage is temporarily unavailable.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
},
"headers": {
"Cache-Control": {
"schema": {
"type": "string",
"enum": [
"no-store"
]
}
}
}
}
}

List actual files in one published shared Skill Version

Both canonical source trees and retained ZIP Versions expose file metadata without storage locations. Stable UTF-8 path ordering and a Version-bound cursor.

Authorization: OrganizationApiKey; persisted credentials determine Organization scope; no End User scope. Uploads and publication are attributed to the authentic Organization API Key.

listOrganizationSkillFiles

[
{
"OrganizationApiKey": []
}
]
[
{
"name": "If-None-Match",
"in": "header",
"description": "Authenticated conditional GET; weak tags, tag lists and * are supported.",
"required": false,
"schema": {
"type": "string",
"maxLength": 4096
}
},
{
"name": "skillId",
"required": true,
"in": "path",
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 64
}
},
{
"name": "limit",
"required": false,
"in": "query",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 1000,
"default": 200
}
},
{
"name": "cursor",
"required": false,
"in": "query",
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 4096
},
"description": "Opaque signed cursor for this Organization and resource."
},
{
"name": "version",
"required": true,
"in": "query",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 9007199254740991
}
}
]
{
"200": {
"headers": {
"ETag": {
"description": "Representation-specific strong validator.",
"schema": {
"type": "string"
}
},
"Cache-Control": {
"schema": {
"type": "string",
"enum": [
"no-store"
]
}
}
},
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/OrganizationSkillFilesDto"
}
}
}
},
"304": {
"description": "The currently authorized representation matches If-None-Match; no body.",
"headers": {
"ETag": {
"description": "Representation-specific strong validator.",
"schema": {
"type": "string"
}
},
"Cache-Control": {
"schema": {
"type": "string",
"enum": [
"no-store"
]
}
}
}
},
"400": {
"description": "validation_error or invalid_cursor: invalid strict query, identifier, version, relative file path, cursor or conditional header.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
},
"headers": {
"Cache-Control": {
"schema": {
"type": "string",
"enum": [
"no-store"
]
}
}
}
},
"401": {
"description": "authentication_required: current Organization Key authority is missing, revoked, rotated or inactive.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
},
"headers": {
"Cache-Control": {
"schema": {
"type": "string",
"enum": [
"no-store"
]
}
}
}
},
"403": {
"description": "auth_kind_forbidden: requires an Organization API Key.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
},
"headers": {
"Cache-Control": {
"schema": {
"type": "string",
"enum": [
"no-store"
]
}
}
}
},
"404": {
"description": "resource_not_found or skill_file_not_found: shared Skill, published loadable Version or safe file is unavailable; foreign and private resources are indistinguishable from missing.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
},
"headers": {
"Cache-Control": {
"schema": {
"type": "string",
"enum": [
"no-store"
]
}
}
}
},
"503": {
"description": "auth_temporarily_unavailable or skill_package_store_unavailable: credential resolution or content storage is temporarily unavailable, or the 4 per-process ZIP Version file listings are busy; retry later.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
},
"headers": {
"Cache-Control": {
"schema": {
"type": "string",
"enum": [
"no-store"
]
}
}
}
}
}

Read one published shared Skill file as inert bytes

Authorization: OrganizationApiKey; persisted credentials determine Organization scope; no End User scope. Uploads and publication are attributed to the authentic Organization API Key.

readOrganizationSkillFile

[
{
"OrganizationApiKey": []
}
]
[
{
"name": "If-None-Match",
"in": "header",
"description": "Authenticated conditional GET; weak tags, tag lists and * are supported.",
"required": false,
"schema": {
"type": "string",
"maxLength": 4096
}
},
{
"name": "skillId",
"required": true,
"in": "path",
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 64
}
},
{
"name": "path",
"required": true,
"in": "query",
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 4096
},
"description": "Canonical relative package path; traversal and absolute paths are invalid."
},
{
"name": "version",
"required": true,
"in": "query",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 9007199254740991
}
}
]
{
"200": {
"description": "Exact inert file bytes.",
"headers": {
"ETag": {
"description": "Representation-specific strong validator.",
"schema": {
"type": "string"
}
},
"Cache-Control": {
"schema": {
"type": "string",
"enum": [
"no-store"
]
}
},
"X-Content-Type-Options": {
"schema": {
"type": "string",
"enum": [
"nosniff"
]
}
},
"Content-Disposition": {
"schema": {
"type": "string"
}
}
},
"content": {
"application/octet-stream": {
"schema": {
"type": "string",
"format": "binary"
}
}
}
},
"304": {
"description": "The currently authorized representation matches If-None-Match; no body.",
"headers": {
"ETag": {
"description": "Representation-specific strong validator.",
"schema": {
"type": "string"
}
},
"Cache-Control": {
"schema": {
"type": "string",
"enum": [
"no-store"
]
}
}
}
},
"400": {
"description": "validation_error or invalid_cursor: invalid strict query, identifier, version, relative file path, cursor or conditional header.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
},
"headers": {
"Cache-Control": {
"schema": {
"type": "string",
"enum": [
"no-store"
]
}
}
}
},
"401": {
"description": "authentication_required: current Organization Key authority is missing, revoked, rotated or inactive.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
},
"headers": {
"Cache-Control": {
"schema": {
"type": "string",
"enum": [
"no-store"
]
}
}
}
},
"403": {
"description": "auth_kind_forbidden: requires an Organization API Key.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
},
"headers": {
"Cache-Control": {
"schema": {
"type": "string",
"enum": [
"no-store"
]
}
}
}
},
"404": {
"description": "resource_not_found or skill_file_not_found: shared Skill, published loadable Version or safe file is unavailable; foreign and private resources are indistinguishable from missing.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
},
"headers": {
"Cache-Control": {
"schema": {
"type": "string",
"enum": [
"no-store"
]
}
}
}
},
"503": {
"description": "auth_temporarily_unavailable or skill_package_store_unavailable: credential resolution or content storage is temporarily unavailable.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
},
"headers": {
"Cache-Control": {
"schema": {
"type": "string",
"enum": [
"no-store"
]
}
}
}
}
}

Download the complete installation ZIP of one published shared Skill Version

Authorization: OrganizationApiKey; persisted credentials determine Organization scope; no End User scope. Uploads and publication are attributed to the authentic Organization API Key.

downloadOrganizationSkillPackage

[
{
"OrganizationApiKey": []
}
]
[
{
"name": "If-None-Match",
"in": "header",
"description": "Authenticated conditional GET; weak tags, tag lists and * are supported.",
"required": false,
"schema": {
"type": "string",
"maxLength": 4096
}
},
{
"name": "skillId",
"required": true,
"in": "path",
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 64
}
},
{
"name": "version",
"required": true,
"in": "query",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 9007199254740991
}
}
]
{
"200": {
"description": "Complete canonical ZIP or integrity-checked retained ZIP; never executed.",
"headers": {
"ETag": {
"description": "Representation-specific strong validator.",
"schema": {
"type": "string"
}
},
"Cache-Control": {
"schema": {
"type": "string",
"enum": [
"no-store"
]
}
},
"X-Content-Type-Options": {
"schema": {
"type": "string",
"enum": [
"nosniff"
]
}
},
"Content-Disposition": {
"schema": {
"type": "string"
}
}
},
"content": {
"application/zip": {
"schema": {
"type": "string",
"format": "binary"
}
}
}
},
"304": {
"description": "The currently authorized representation matches If-None-Match; no body.",
"headers": {
"ETag": {
"description": "Representation-specific strong validator.",
"schema": {
"type": "string"
}
},
"Cache-Control": {
"schema": {
"type": "string",
"enum": [
"no-store"
]
}
}
}
},
"400": {
"description": "validation_error or invalid_cursor: invalid strict query, identifier, version, relative file path, cursor or conditional header.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
},
"headers": {
"Cache-Control": {
"schema": {
"type": "string",
"enum": [
"no-store"
]
}
}
}
},
"401": {
"description": "authentication_required: current Organization Key authority is missing, revoked, rotated or inactive.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
},
"headers": {
"Cache-Control": {
"schema": {
"type": "string",
"enum": [
"no-store"
]
}
}
}
},
"403": {
"description": "auth_kind_forbidden: requires an Organization API Key.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
},
"headers": {
"Cache-Control": {
"schema": {
"type": "string",
"enum": [
"no-store"
]
}
}
}
},
"404": {
"description": "resource_not_found or skill_file_not_found: shared Skill, published loadable Version or safe file is unavailable; foreign and private resources are indistinguishable from missing.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
},
"headers": {
"Cache-Control": {
"schema": {
"type": "string",
"enum": [
"no-store"
]
}
}
}
},
"503": {
"description": "auth_temporarily_unavailable or skill_package_store_unavailable: credential resolution or content storage is temporarily unavailable.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
},
"headers": {
"Cache-Control": {
"schema": {
"type": "string",
"enum": [
"no-store"
]
}
}
}
}
}

Read shared Skill metadata and its published loadable Versions

Descending Version pagination. User authors, private publication provenance and installation relations are omitted. ETag covers this entire returned page.

Authorization: OrganizationApiKey; persisted credentials determine Organization scope; no End User scope. Uploads and publication are attributed to the authentic Organization API Key.

getOrganizationSkill

[
{
"OrganizationApiKey": []
}
]
[
{
"name": "If-None-Match",
"in": "header",
"description": "Authenticated conditional GET; weak tags, tag lists and * are supported.",
"required": false,
"schema": {
"type": "string",
"maxLength": 4096
}
},
{
"name": "skillId",
"required": true,
"in": "path",
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 64
}
},
{
"name": "limit",
"required": false,
"in": "query",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 200,
"default": 50
}
},
{
"name": "cursor",
"required": false,
"in": "query",
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 4096
},
"description": "Opaque signed cursor for this Organization and resource."
}
]
{
"200": {
"headers": {
"ETag": {
"description": "Representation-specific strong validator.",
"schema": {
"type": "string"
}
},
"Cache-Control": {
"schema": {
"type": "string",
"enum": [
"no-store"
]
}
}
},
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/OrganizationSkillDetailDto"
}
}
}
},
"304": {
"description": "The currently authorized representation matches If-None-Match; no body.",
"headers": {
"ETag": {
"description": "Representation-specific strong validator.",
"schema": {
"type": "string"
}
},
"Cache-Control": {
"schema": {
"type": "string",
"enum": [
"no-store"
]
}
}
}
},
"400": {
"description": "validation_error or invalid_cursor: invalid strict query, identifier, version, relative file path, cursor or conditional header.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
},
"headers": {
"Cache-Control": {
"schema": {
"type": "string",
"enum": [
"no-store"
]
}
}
}
},
"401": {
"description": "authentication_required: current Organization Key authority is missing, revoked, rotated or inactive.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
},
"headers": {
"Cache-Control": {
"schema": {
"type": "string",
"enum": [
"no-store"
]
}
}
}
},
"403": {
"description": "auth_kind_forbidden: requires an Organization API Key.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
},
"headers": {
"Cache-Control": {
"schema": {
"type": "string",
"enum": [
"no-store"
]
}
}
}
},
"404": {
"description": "resource_not_found or skill_file_not_found: shared Skill, published loadable Version or safe file is unavailable; foreign and private resources are indistinguishable from missing.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
},
"headers": {
"Cache-Control": {
"schema": {
"type": "string",
"enum": [
"no-store"
]
}
}
}
},
"503": {
"description": "auth_temporarily_unavailable or skill_package_store_unavailable: credential resolution or content storage is temporarily unavailable.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
},
"headers": {
"Cache-Control": {
"schema": {
"type": "string",
"enum": [
"no-store"
]
}
}
}
}
}

Upload and validate an Organization Skill ZIP without publishing it

Retrying the same ZIP with the same Idempotency-Key and Organization Key returns the original upload and its current state, including when requests overlap. A terminal upload is not restarted. Different ZIP bytes with the same key return 409.

Authorization: OrganizationApiKey; persisted credentials determine Organization scope; no End User scope. Uploads and publication are attributed to the authentic Organization API Key.

createOrganizationSkillUpload

[
{
"OrganizationApiKey": []
}
]
[
{
"name": "Content-Length",
"in": "header",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "Idempotency-Key",
"in": "header",
"required": true,
"schema": {
"type": "string"
}
}
]
{
"required": true,
"content": {
"application/octet-stream": {
"schema": {
"type": "string",
"format": "binary",
"maxLength": 209715200
}
}
}
}
{
"202": {
"description": "Upload accepted for asynchronous validation.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"upload"
],
"properties": {
"upload": {
"type": "object",
"required": [
"uploadId",
"skillId",
"state",
"byteSize",
"sha256",
"expiresAt",
"validation",
"version",
"createdAt",
"updatedAt"
],
"properties": {
"uploadId": {
"type": "string"
},
"skillId": {
"type": "string"
},
"state": {
"type": "string",
"enum": [
"uploading",
"pending",
"uploaded",
"fetching",
"validating",
"extracting",
"awaiting_confirmation",
"finalizing",
"done",
"failed",
"aborted"
]
},
"byteSize": {
"type": "integer",
"minimum": 0
},
"sha256": {
"type": "string",
"pattern": "^[0-9a-f]{64}$"
},
"expiresAt": {
"type": "string",
"format": "date-time",
"nullable": true
},
"validation": {
"type": "object",
"required": [
"entriesTotal",
"fileCount",
"entriesDone",
"declaredBytes",
"bytesDone",
"diagnostics",
"failureCode",
"failurePath"
],
"properties": {
"entriesTotal": {
"type": "integer",
"minimum": 0,
"nullable": true
},
"fileCount": {
"type": "integer",
"minimum": 0,
"nullable": true
},
"entriesDone": {
"type": "integer",
"minimum": 0
},
"declaredBytes": {
"type": "integer",
"minimum": 0,
"nullable": true
},
"bytesDone": {
"type": "integer",
"minimum": 0
},
"diagnostics": {
"type": "array",
"items": {
"type": "object"
}
},
"failureCode": {
"type": "string",
"nullable": true
},
"failurePath": {
"type": "string",
"nullable": true
}
},
"additionalProperties": false
},
"version": {
"type": "integer",
"minimum": 1,
"nullable": true
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"updatedAt": {
"type": "string",
"format": "date-time"
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
}
},
"headers": {
"Cache-Control": {
"schema": {
"type": "string",
"example": "no-store"
}
}
}
},
"400": {
"description": "The ZIP body, Content-Length or Idempotency-Key is invalid.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
},
"headers": {
"Cache-Control": {
"schema": {
"type": "string",
"example": "no-store"
}
}
}
},
"401": {
"description": "The Organization API Key is absent, revoked or inactive.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
},
"headers": {
"Cache-Control": {
"schema": {
"type": "string",
"example": "no-store"
}
}
}
},
"403": {
"description": "A User API Key cannot access Organization Skill uploads.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
},
"headers": {
"Cache-Control": {
"schema": {
"type": "string",
"example": "no-store"
}
}
}
},
"409": {
"description": "The idempotency key conflicts with an existing upload.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
},
"headers": {
"Cache-Control": {
"schema": {
"type": "string",
"example": "no-store"
}
}
}
},
"413": {
"description": "The ZIP exceeds the maximum accepted size.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
},
"headers": {
"Cache-Control": {
"schema": {
"type": "string",
"example": "no-store"
}
}
}
},
"503": {
"description": "upload_temporarily_unavailable: upload storage is temporarily unavailable, the process byte budget cannot hold the declared Content-Length, or the 4 per-process upload slots are busy. A budget or slot refusal reads no body and creates no upload. Retry later with the same Idempotency-Key.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
},
"headers": {
"Cache-Control": {
"schema": {
"type": "string",
"example": "no-store"
}
}
}
}
}

Read Organization Skill upload validation and staging state

Authorization: OrganizationApiKey; persisted credentials determine Organization scope; no End User scope. Uploads and publication are attributed to the authentic Organization API Key.

getOrganizationSkillUpload

[
{
"OrganizationApiKey": []
}
]
[
{
"name": "uploadId",
"required": true,
"in": "path",
"schema": {
"type": "string"
}
},
{
"name": "If-None-Match",
"in": "header",
"required": false,
"schema": {
"type": "string"
}
}
]
{
"200": {
"description": "Current upload state and validation result.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"upload"
],
"properties": {
"upload": {
"type": "object",
"required": [
"uploadId",
"skillId",
"state",
"byteSize",
"sha256",
"expiresAt",
"validation",
"version",
"createdAt",
"updatedAt"
],
"properties": {
"uploadId": {
"type": "string"
},
"skillId": {
"type": "string"
},
"state": {
"type": "string",
"enum": [
"uploading",
"pending",
"uploaded",
"fetching",
"validating",
"extracting",
"awaiting_confirmation",
"finalizing",
"done",
"failed",
"aborted"
]
},
"byteSize": {
"type": "integer",
"minimum": 0
},
"sha256": {
"type": "string",
"pattern": "^[0-9a-f]{64}$"
},
"expiresAt": {
"type": "string",
"format": "date-time",
"nullable": true
},
"validation": {
"type": "object",
"required": [
"entriesTotal",
"fileCount",
"entriesDone",
"declaredBytes",
"bytesDone",
"diagnostics",
"failureCode",
"failurePath"
],
"properties": {
"entriesTotal": {
"type": "integer",
"minimum": 0,
"nullable": true
},
"fileCount": {
"type": "integer",
"minimum": 0,
"nullable": true
},
"entriesDone": {
"type": "integer",
"minimum": 0
},
"declaredBytes": {
"type": "integer",
"minimum": 0,
"nullable": true
},
"bytesDone": {
"type": "integer",
"minimum": 0
},
"diagnostics": {
"type": "array",
"items": {
"type": "object"
}
},
"failureCode": {
"type": "string",
"nullable": true
},
"failurePath": {
"type": "string",
"nullable": true
}
},
"additionalProperties": false
},
"version": {
"type": "integer",
"minimum": 1,
"nullable": true
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"updatedAt": {
"type": "string",
"format": "date-time"
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
}
},
"headers": {
"ETag": {
"schema": {
"type": "string"
}
},
"Cache-Control": {
"schema": {
"type": "string",
"example": "no-store"
}
}
}
},
"304": {
"description": "The upload representation has not changed.",
"headers": {
"ETag": {
"schema": {
"type": "string"
}
},
"Cache-Control": {
"schema": {
"type": "string",
"example": "no-store"
}
}
}
},
"400": {
"description": "The If-None-Match value is invalid.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
},
"headers": {
"Cache-Control": {
"schema": {
"type": "string",
"example": "no-store"
}
}
}
},
"401": {
"description": "The Organization API Key is absent, revoked or inactive.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
},
"headers": {
"Cache-Control": {
"schema": {
"type": "string",
"example": "no-store"
}
}
}
},
"403": {
"description": "A User API Key cannot access Organization Skill uploads.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
},
"headers": {
"Cache-Control": {
"schema": {
"type": "string",
"example": "no-store"
}
}
}
},
"404": {
"description": "The upload is absent or belongs to another Organization API Key.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
},
"headers": {
"Cache-Control": {
"schema": {
"type": "string",
"example": "no-store"
}
}
}
}
}

DELETE /api/v1/org/skills/uploads/{uploadId}

Section titled “DELETE /api/v1/org/skills/uploads/{uploadId}”

Cancel an unpublished Organization Skill upload

Authorization: OrganizationApiKey; persisted credentials determine Organization scope; no End User scope. Uploads and publication are attributed to the authentic Organization API Key.

cancelOrganizationSkillUpload

[
{
"OrganizationApiKey": []
}
]
[
{
"name": "uploadId",
"required": true,
"in": "path",
"schema": {
"type": "string"
}
}
]
{
"204": {
"description": "The upload was cancelled.",
"headers": {
"Cache-Control": {
"schema": {
"type": "string",
"example": "no-store"
}
}
}
},
"401": {
"description": "The Organization API Key is absent, revoked or inactive.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
},
"headers": {
"Cache-Control": {
"schema": {
"type": "string",
"example": "no-store"
}
}
}
},
"403": {
"description": "A User API Key cannot access Organization Skill uploads.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
},
"headers": {
"Cache-Control": {
"schema": {
"type": "string",
"example": "no-store"
}
}
}
},
"404": {
"description": "The upload is absent or belongs to another Organization API Key.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
},
"headers": {
"Cache-Control": {
"schema": {
"type": "string",
"example": "no-store"
}
}
}
},
"409": {
"description": "The upload is no longer unpublished and cannot be cancelled.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
},
"headers": {
"Cache-Control": {
"schema": {
"type": "string",
"example": "no-store"
}
}
}
}
}

POST /api/v1/org/skills/uploads/{uploadId}/publish

Section titled “POST /api/v1/org/skills/uploads/{uploadId}/publish”

Publish a validated Organization Skill upload as a formal version

Authorization: OrganizationApiKey; persisted credentials determine Organization scope; no End User scope. Uploads and publication are attributed to the authentic Organization API Key.

publishOrganizationSkillUpload

[
{
"OrganizationApiKey": []
}
]
[
{
"name": "uploadId",
"required": true,
"in": "path",
"schema": {
"type": "string"
}
},
{
"name": "Idempotency-Key",
"in": "header",
"required": true,
"schema": {
"type": "string"
}
}
]
{
"202": {
"description": "Publication queued for durable finalization.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"upload"
],
"properties": {
"upload": {
"type": "object",
"required": [
"uploadId",
"skillId",
"state",
"byteSize",
"sha256",
"expiresAt",
"validation",
"version",
"createdAt",
"updatedAt"
],
"properties": {
"uploadId": {
"type": "string"
},
"skillId": {
"type": "string"
},
"state": {
"type": "string",
"enum": [
"uploading",
"pending",
"uploaded",
"fetching",
"validating",
"extracting",
"awaiting_confirmation",
"finalizing",
"done",
"failed",
"aborted"
]
},
"byteSize": {
"type": "integer",
"minimum": 0
},
"sha256": {
"type": "string",
"pattern": "^[0-9a-f]{64}$"
},
"expiresAt": {
"type": "string",
"format": "date-time",
"nullable": true
},
"validation": {
"type": "object",
"required": [
"entriesTotal",
"fileCount",
"entriesDone",
"declaredBytes",
"bytesDone",
"diagnostics",
"failureCode",
"failurePath"
],
"properties": {
"entriesTotal": {
"type": "integer",
"minimum": 0,
"nullable": true
},
"fileCount": {
"type": "integer",
"minimum": 0,
"nullable": true
},
"entriesDone": {
"type": "integer",
"minimum": 0
},
"declaredBytes": {
"type": "integer",
"minimum": 0,
"nullable": true
},
"bytesDone": {
"type": "integer",
"minimum": 0
},
"diagnostics": {
"type": "array",
"items": {
"type": "object"
}
},
"failureCode": {
"type": "string",
"nullable": true
},
"failurePath": {
"type": "string",
"nullable": true
}
},
"additionalProperties": false
},
"version": {
"type": "integer",
"minimum": 1,
"nullable": true
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"updatedAt": {
"type": "string",
"format": "date-time"
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
}
},
"headers": {
"Cache-Control": {
"schema": {
"type": "string",
"example": "no-store"
}
}
}
},
"400": {
"description": "The Idempotency-Key is invalid.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
},
"headers": {
"Cache-Control": {
"schema": {
"type": "string",
"example": "no-store"
}
}
}
},
"401": {
"description": "The Organization API Key is absent, revoked or inactive.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
},
"headers": {
"Cache-Control": {
"schema": {
"type": "string",
"example": "no-store"
}
}
}
},
"403": {
"description": "A User API Key cannot access Organization Skill uploads.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
},
"headers": {
"Cache-Control": {
"schema": {
"type": "string",
"example": "no-store"
}
}
}
},
"404": {
"description": "The upload is absent or belongs to another Organization API Key.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
},
"headers": {
"Cache-Control": {
"schema": {
"type": "string",
"example": "no-store"
}
}
}
},
"409": {
"description": "The idempotency key or upload state conflicts with this request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
},
"headers": {
"Cache-Control": {
"schema": {
"type": "string",
"example": "no-store"
}
}
}
},
"410": {
"description": "The upload has expired and can no longer be published.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
},
"headers": {
"Cache-Control": {
"schema": {
"type": "string",
"example": "no-store"
}
}
}
}
}