Schemas
Organization and End User API reference. Operation fields come from the customer specification; source descriptions keep their original language.
securitySchemes/OrganizationApiKey
Section titled “securitySchemes/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."}securitySchemes/UserApiKey
Section titled “securitySchemes/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."}schemas/RealtimeModelsResponseOpenApiDto
Section titled “schemas/RealtimeModelsResponseOpenApiDto”{ "type": "object", "properties": { "defaultModel": { "type": "string", "nullable": true }, "models": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "available": { "type": "boolean" }, "isDefault": { "type": "boolean" }, "languages": { "type": "array", "items": { "type": "string", "enum": [ "zh-CN", "en-US" ] } }, "endpointingModes": { "type": "array", "items": { "type": "string", "enum": [ "client", "server" ] } }, "audio": { "type": "object", "properties": { "input": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "encoding": { "type": "string", "enum": [ "pcm16" ] }, "sampleRate": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "channels": { "type": "number", "minimum": 1, "maximum": 1 } }, "required": [ "encoding", "sampleRate", "channels" ] }, { "type": "object", "properties": { "encoding": { "type": "string", "enum": [ "opus" ] }, "sampleRate": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "channels": { "type": "number", "minimum": 1, "maximum": 1 }, "packetDurationMs": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "bitrate": { "oneOf": [ { "type": "number", "minimum": 16000, "maximum": 16000 }, { "type": "number", "minimum": 24000, "maximum": 24000 }, { "type": "number", "minimum": 32000, "maximum": 32000 } ] } }, "required": [ "encoding", "sampleRate", "channels", "packetDurationMs" ] } ] } }, "output": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "encoding": { "type": "string", "enum": [ "pcm16" ] }, "sampleRate": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "channels": { "type": "number", "minimum": 1, "maximum": 1 } }, "required": [ "encoding", "sampleRate", "channels" ] }, { "type": "object", "properties": { "encoding": { "type": "string", "enum": [ "opus" ] }, "sampleRate": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "channels": { "type": "number", "minimum": 1, "maximum": 1 }, "packetDurationMs": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "bitrate": { "oneOf": [ { "type": "number", "minimum": 16000, "maximum": 16000 }, { "type": "number", "minimum": 24000, "maximum": 24000 }, { "type": "number", "minimum": 32000, "maximum": 32000 } ] } }, "required": [ "encoding", "sampleRate", "channels", "packetDurationMs" ] } ] } } }, "required": [ "input", "output" ] } }, "required": [ "id", "label", "available", "isDefault", "languages", "endpointingModes", "audio" ] } } }, "required": [ "defaultModel", "models" ]}schemas/ErrorEnvelope
Section titled “schemas/ErrorEnvelope”{ "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "agent_instructions_too_large", "websocket_required", "binding_commit_unknown", "binding_receipt_integrity", "validation_error", "template_test_busy", "template_test_closed", "template_test_expired", "template_test_dependency_unavailable", "template_test_model_unavailable", "template_test_authority_lost", "invalid_organization_context", "authentication_required", "organization_owner_required", "organization_last_owner", "organization_already_joined", "resource_not_found", "invalid_cursor", "console_temporarily_unavailable", "service_configuration_unavailable", "human_principal_required", "user_api_key_required", "organization_membership_required", "admin_required", "org_admin_required", "agent_template_recall_acknowledgment_required", "agent_template_dependency_conflict", "agent_template_unavailable", "session_model_not_allowed", "session_execution_dependency_unavailable", "mcp_authorization_required", "mcp_oauth_unavailable", "mcp_oauth_confirmation_invalid", "model_provider_unconfigured", "sandbox_unconfigured", "sandbox_validation_pending", "sandbox_scope_incompatible", "sandbox_configuration_incompatible", "sandbox_unavailable", "vision_model_unsupported", "vision_image_count_exceeded", "vision_image_unsupported", "vision_image_source_too_large", "vision_image_invalid", "vision_image_decode_limit_exceeded", "vision_image_payload_too_large", "vision_image_processing_unavailable", "session_not_found", "session_read_only", "session_switch_in_progress", "session_switch_busy", "session_switch_unsupported", "session_configuration_epoch_changed", "provider_unavailable", "realtime_connection_not_found", "realtime_connection_live", "realtime_model_conflict", "realtime_model_unavailable", "realtime_not_enabled", "realtime_language_unsupported", "realtime_language_unavailable", "realtime_connection_ended", "audio_format_unsupported", "admission_unavailable", "turn_not_found", "checkpoint_runtime_unavailable", "artifact_not_found", "chat_image_not_found", "artifact_cursor_invalid", "artifact_idempotency_conflict", "artifact_quota_exceeded", "artifact_not_writable", "artifact_revision_conflict", "artifact_source_not_found", "artifact_source_not_file", "artifact_source_changed", "artifact_storage_contract_unavailable", "artifact_publish_failed", "artifact_bytes_need_repair", "drive_file_not_found", "drive_path_too_long", "drive_download_rate_limited", "drive_download_provider_error", "drive_download_unavailable", "invalid_idempotency_key", "idempotency_key_required", "session_creation_conflict", "interaction_input_conflict", "interaction_not_found", "interaction_admission_closed", "interaction_target_conflict", "client_tool_call_unavailable", "client_tool_call_settled", "idempotency_key_reused", "identity_conversion_command_retired", "idempotency_in_progress", "idempotency_key_expired", "secret_delivery_expired", "idempotency_completion_failed", "idempotency_witness_invalid", "skill_name_conflict", "skill_delete_blocked", "mcp_server_delete_blocked", "invalid_skill_package", "skill_ingestion_not_found", "skill_import_job_not_found", "skill_import_state_conflict", "skill_ingestion_expired", "precondition_required", "precondition_failed", "resource_conflict", "agent_template_profile_unavailable", "agent_template_dependency_unavailable", "agent_template_archived", "agent_template_conflict", "agent_template_list_changed", "skill_not_found", "skill_version_not_found", "skill_file_not_found", "skill_package_file_rejected", "skill_package_store_unavailable", "skill_already_installed", "skill_installation_not_found", "skill_upgrade_not_forward", "unsupported_media_type", "raw_upload_too_large", "upload_too_large", "upload_ticket_invalid", "upload_failed", "upload_expired", "upload_incomplete", "upload_integrity_failed", "upload_requires_multipart", "upload_temporarily_unavailable", "skill_authoring_forbidden", "skill_read_forbidden", "restore_requires_historical_version", "private_skill_required", "publication_head_required", "open_publication_request_exists", "publication_target_changed", "publication_conflict", "publication_request_not_found", "publication_request_already_decided", "publication_request_invalidated", "publication_request_conflict", "publication_snapshot_not_found", "scheduler_not_found", "asr_disabled", "asr_failed", "turn_admission_closed", "session_has_active_turn", "clarification_source_conflict", "configuration_unavailable", "organization_api_key_rotation_conflict", "auth_kind_forbidden", "billing_target_not_found", "invalid_billing_usage_query", "invalid_billing_usage_cursor", "billing_audit_unavailable", "session_observation_audit_unavailable", "drive9_provision_config_conflict", "runtime_error", "invalid_credentials", "invalid_current_password", "account_already_exists", "account_not_found", "password_already_configured", "google_identity_already_linked", "verification_not_found", "verification_code_invalid", "verification_replaced", "verification_already_completed", "verification_expired", "verification_attempts_exhausted", "verification_rate_limited", "login_rate_limited", "password_rate_limited", "auth_temporarily_unavailable", "auth_outcome_unknown", "password_changed", "invalid_origin", "platform_operator_required", "personal_organization_eligibility_concurrent_change", "personal_organization_eligibility_unavailable", "personal_organization_eligibility_outcome_unknown", "personal_organization_creation_unavailable", "onboarding_temporarily_unavailable", "onboarding_outcome_unknown", "organization_destination_not_available", "invitation_not_available", "invitation_not_actionable", "invite_delivery_failed", "access_request_not_available", "access_requests_unavailable" ] }, "message": { "type": "string" }, "details": { "nullable": true } } } }}schemas/PublishedTemplateSummariesDto
Section titled “schemas/PublishedTemplateSummariesDto”{ "type": "object", "properties": { "templates": { "type": "array", "items": { "type": "object", "properties": { "agentTemplateId": { "type": "string" }, "displayName": { "type": "string" }, "description": { "type": "string" }, "contentDigest": { "type": "string", "pattern": "^[0-9a-f]{64}$" } }, "required": [ "agentTemplateId", "displayName", "description", "contentDigest" ], "additionalProperties": false } }, "hasMore": { "type": "boolean" }, "nextCursor": { "type": "string", "nullable": true } }, "required": [ "templates", "hasMore", "nextCursor" ], "additionalProperties": false}schemas/AgentModelsResponseOpenApiDto
Section titled “schemas/AgentModelsResponseOpenApiDto”{ "type": "object", "properties": { "defaultModel": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[A-Za-z0-9][A-Za-z0-9_.-]*$" }, "organizationDefaultModel": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[A-Za-z0-9][A-Za-z0-9_.-]*$" }, "effectiveDefaultModel": { "description": "Suggested default for new Sessions: the active release default when selectable, else the Organization default when selectable, else the first selectable model. Session creation without a model applies only the first two and otherwise refuses with model_provider_unconfigured.", "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[A-Za-z0-9][A-Za-z0-9_.-]*$" }, "organizationAllowedModels": { "description": "Stored Organization allow-list. It does not currently limit selection.", "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[A-Za-z0-9][A-Za-z0-9_.-]*$" } }, "effectiveAllowedModels": { "description": "Models the Organization can select now: every model the active release serves.", "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[A-Za-z0-9][A-Za-z0-9_.-]*$" } }, "models": { "type": "array", "items": { "type": "object", "properties": { "model": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[A-Za-z0-9][A-Za-z0-9_.-]*$" }, "label": { "type": "string" }, "availability": { "type": "string", "enum": [ "available", "provider_unconfigured" ] } }, "required": [ "model", "label", "availability" ] } } }, "required": [ "defaultModel", "organizationDefaultModel", "effectiveDefaultModel", "organizationAllowedModels", "effectiveAllowedModels", "models" ]}schemas/SessionClientToolsResponseOpenApiDto
Section titled “schemas/SessionClientToolsResponseOpenApiDto”{ "type": "object", "properties": { "revision": { "description": "Increments on each replacement that changes the set; 0 before any declaration.", "type": "integer", "minimum": 0, "exclusiveMinimum": false }, "tools": { "type": "array", "maxItems": 64, "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "function" ] }, "name": { "description": "Client function name; platform tool names, the mcp_ prefix and double underscores are reserved.", "type": "string", "pattern": "^[a-zA-Z0-9_-]{1,64}$" }, "description": { "type": "string", "minLength": 1, "maxLength": 4096 }, "parameters": { "type": "object", "additionalProperties": {} } }, "required": [ "type", "name", "description", "parameters" ] } } }, "required": [ "revision", "tools" ]}schemas/ReplaceSessionToolsOpenApiDto
Section titled “schemas/ReplaceSessionToolsOpenApiDto”{ "type": "object", "properties": { "tools": { "type": "array", "maxItems": 64, "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "function" ] }, "name": { "description": "Client function name; platform tool names, the mcp_ prefix and double underscores are reserved.", "type": "string", "pattern": "^[a-zA-Z0-9_-]{1,64}$" }, "description": { "type": "string", "minLength": 1, "maxLength": 4096 }, "parameters": { "type": "object", "additionalProperties": {} } }, "required": [ "type", "name", "description", "parameters" ], "additionalProperties": false } } }, "required": [ "tools" ], "additionalProperties": false}schemas/SessionsResponseOpenApiDto
Section titled “schemas/SessionsResponseOpenApiDto”{ "type": "object", "properties": { "sessions": { "type": "array", "items": { "type": "object", "properties": { "organizationId": { "type": "string" }, "sessionId": { "type": "string" }, "name": { "type": "string", "nullable": true }, "autoTitle": { "type": "string", "nullable": true }, "ownerUserId": { "type": "string" }, "startedByUserId": { "type": "string" }, "createdByType": { "type": "string", "enum": [ "user", "scheduler" ] }, "readOnly": { "type": "boolean" }, "sourceSchedulerId": { "type": "string", "nullable": true }, "sourceSchedulerFireId": { "type": "string", "nullable": true }, "model": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[A-Za-z0-9][A-Za-z0-9_.-]*$" }, "modelRevision": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "realtimeModel": { "description": "Selection for the next Realtime Connection; null uses the active release default.", "type": "string", "nullable": true }, "realtimeModelRevision": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "realtimeModelEtag": { "description": "Opaque If-Match token for PATCH /api/v1/user/sessions/{id}/realtime-model; independent of the text model ETag.", "type": "string" }, "configurationEpoch": { "description": "Current immutable Session Configuration Epoch; null for retained read-only or provider-owned snapshots outside the epoch model.", "type": "integer", "minimum": 1, "exclusiveMinimum": false, "nullable": true }, "switching": { "description": "True while a durable Session Template-switch command fences new interaction.", "type": "boolean" }, "template": { "type": "object", "properties": { "templateId": { "type": "string" }, "contentDigest": { "type": "string" } }, "required": [ "templateId", "contentDigest" ], "nullable": true }, "modelPolicyStatus": { "type": "string", "enum": [ "allowed", "organization_disallowed" ] }, "status": { "type": "string", "enum": [ "active", "deleted" ] }, "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" } ] }, "activeTurnId": { "type": "string", "nullable": true }, "realtimeVoice": { "description": "Fixed Session voice setting; null disables voice. This does not guarantee current provider availability.", "type": "object", "properties": { "language": { "type": "string", "enum": [ "zh-CN", "en-US" ] } }, "required": [ "language" ], "nullable": true }, "realtime": { "description": "The live Realtime connection of this Session, read when the response is produced; null when none is live or the Session is deleted.", "type": "object", "properties": { "id": { "description": "Realtime connection ID.", "type": "string" }, "status": { "description": "connecting: admitted, but the realtime audio stream is not open yet. active: the stream is open and the user can speak, including while a task runs. paused: the stream is still open, but the current task is waiting for the user to answer a clarification question; answering resumes it.", "type": "string", "enum": [ "connecting", "active", "paused" ] }, "audio": { "type": "object", "properties": { "input": { "description": "One direction of the Realtime connection audio format.", "oneOf": [ { "type": "object", "properties": { "encoding": { "description": "Little-endian mono samples.", "type": "string", "enum": [ "pcm16" ] }, "sampleRate": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "channels": { "type": "number", "minimum": 1, "maximum": 1 } }, "required": [ "encoding", "sampleRate", "channels" ] }, { "type": "object", "properties": { "encoding": { "description": "One Opus packet per audio frame, decoded at sampleRate.", "type": "string", "enum": [ "opus" ] }, "sampleRate": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "channels": { "type": "number", "minimum": 1, "maximum": 1 }, "packetDurationMs": { "description": "Duration of each Opus packet.", "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "bitrate": { "description": "Output CBR in bps; absent on input and historical connections.", "oneOf": [ { "type": "number", "minimum": 16000, "maximum": 16000 }, { "type": "number", "minimum": 24000, "maximum": 24000 }, { "type": "number", "minimum": 32000, "maximum": 32000 } ] } }, "required": [ "encoding", "sampleRate", "channels", "packetDurationMs" ] } ] }, "output": { "description": "One direction of the Realtime connection audio format.", "oneOf": [ { "type": "object", "properties": { "encoding": { "description": "Little-endian mono samples.", "type": "string", "enum": [ "pcm16" ] }, "sampleRate": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "channels": { "type": "number", "minimum": 1, "maximum": 1 } }, "required": [ "encoding", "sampleRate", "channels" ] }, { "type": "object", "properties": { "encoding": { "description": "One Opus packet per audio frame, decoded at sampleRate.", "type": "string", "enum": [ "opus" ] }, "sampleRate": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "channels": { "type": "number", "minimum": 1, "maximum": 1 }, "packetDurationMs": { "description": "Duration of each Opus packet.", "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "bitrate": { "description": "Output CBR in bps; absent on input and historical connections.", "oneOf": [ { "type": "number", "minimum": 16000, "maximum": 16000 }, { "type": "number", "minimum": 24000, "maximum": 24000 }, { "type": "number", "minimum": 32000, "maximum": 32000 } ] } }, "required": [ "encoding", "sampleRate", "channels", "packetDurationMs" ] } ] } }, "required": [ "input", "output" ] }, "startedAt": { "description": "When the Realtime connection was admitted.", "type": "string" } }, "required": [ "id", "status", "audio", "startedAt" ], "nullable": true }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "deletedAt": { "type": "string", "nullable": true } }, "required": [ "organizationId", "sessionId", "name", "autoTitle", "ownerUserId", "startedByUserId", "createdByType", "readOnly", "sourceSchedulerId", "sourceSchedulerFireId", "model", "modelRevision", "realtimeModel", "realtimeModelRevision", "realtimeModelEtag", "configurationEpoch", "switching", "template", "modelPolicyStatus", "status", "billingTag", "activeTurnId", "realtimeVoice", "realtime", "createdAt", "updatedAt", "deletedAt" ] } }, "hasMore": { "type": "boolean" }, "nextCursor": { "type": "string", "nullable": true } }, "required": [ "sessions", "hasMore", "nextCursor" ]}schemas/BillingTag
Section titled “schemas/BillingTag”{ "type": "object", "additionalProperties": false, "required": [ "key", "value" ], "description": "A non-secret attribution label. The pair is matched exactly and is not an authorization boundary.", "properties": { "key": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[a-z][a-z0-9_.-]{0,63}$", "description": "Case-sensitive key: a lowercase ASCII letter followed by up to 63 lowercase ASCII letters, digits, underscores, dots, or hyphens." }, "value": { "type": "string", "description": "Case-sensitive value normalized to NFC and limited to 1–128 bytes in UTF-8. Leading or trailing Unicode whitespace and Unicode control or format characters are rejected." } }}schemas/CreateTemplateSessionOpenApiDto
Section titled “schemas/CreateTemplateSessionOpenApiDto”{ "type": "object", "properties": { "agentTemplateId": { "type": "string", "minLength": 1, "maxLength": 64 }, "model": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[A-Za-z0-9][A-Za-z0-9_.-]*$" }, "realtimeModel": { "type": "string", "minLength": 1, "maxLength": 128 }, "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" } ] }, "tools": { "description": "Client Tools this Session client declares and executes; each client-started Turn uses the set current at its admission.", "type": "array", "maxItems": 64, "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "function" ] }, "name": { "description": "Client function name; platform tool names, the mcp_ prefix and double underscores are reserved.", "type": "string", "pattern": "^[a-zA-Z0-9_-]{1,64}$" }, "description": { "type": "string", "minLength": 1, "maxLength": 4096 }, "parameters": { "type": "object", "additionalProperties": {} } }, "required": [ "type", "name", "description", "parameters" ], "additionalProperties": false } }, "additionalInstructions": { "type": "string", "nullable": true }, "sandbox": { "type": "object", "properties": { "profileId": { "type": "string", "minLength": 1, "maxLength": 64, "nullable": true, "default": null }, "workingDirectory": { "type": "string", "minLength": 1, "maxLength": 512, "pattern": "^(?:\\.|(?![A-Za-z]:\\/)(?!\\.tidb-link(?:\\/|$))(?!\\s)(?!.*\\s$)(?!(?:.*\\/)?\\.{1,2}(?:\\/|$))[^/\\\\\\u0000-\\u001f\\u007f]+(?:\\/[^/\\\\\\u0000-\\u001f\\u007f]+)*)$", "default": "." } }, "additionalProperties": false }, "acknowledgeSessionRecall": { "type": "boolean" } }, "required": [ "agentTemplateId" ], "additionalProperties": false}schemas/SessionResponseOpenApiDto
Section titled “schemas/SessionResponseOpenApiDto”{ "type": "object", "properties": { "session": { "type": "object", "properties": { "organizationId": { "type": "string" }, "sessionId": { "type": "string" }, "name": { "type": "string", "nullable": true }, "autoTitle": { "type": "string", "nullable": true }, "ownerUserId": { "type": "string" }, "startedByUserId": { "type": "string" }, "createdByType": { "type": "string", "enum": [ "user", "scheduler" ] }, "readOnly": { "type": "boolean" }, "sourceSchedulerId": { "type": "string", "nullable": true }, "sourceSchedulerFireId": { "type": "string", "nullable": true }, "model": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[A-Za-z0-9][A-Za-z0-9_.-]*$" }, "modelRevision": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "realtimeModel": { "description": "Selection for the next Realtime Connection; null uses the active release default.", "type": "string", "nullable": true }, "realtimeModelRevision": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "realtimeModelEtag": { "description": "Opaque If-Match token for PATCH /api/v1/user/sessions/{id}/realtime-model; independent of the text model ETag.", "type": "string" }, "configurationEpoch": { "description": "Current immutable Session Configuration Epoch; null for retained read-only or provider-owned snapshots outside the epoch model.", "type": "integer", "minimum": 1, "exclusiveMinimum": false, "nullable": true }, "switching": { "description": "True while a durable Session Template-switch command fences new interaction.", "type": "boolean" }, "template": { "type": "object", "properties": { "templateId": { "type": "string" }, "contentDigest": { "type": "string" } }, "required": [ "templateId", "contentDigest" ], "nullable": true }, "modelPolicyStatus": { "type": "string", "enum": [ "allowed", "organization_disallowed" ] }, "status": { "type": "string", "enum": [ "active", "deleted" ] }, "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" } ] }, "activeTurnId": { "type": "string", "nullable": true }, "realtimeVoice": { "description": "Fixed Session voice setting; null disables voice. This does not guarantee current provider availability.", "type": "object", "properties": { "language": { "type": "string", "enum": [ "zh-CN", "en-US" ] } }, "required": [ "language" ], "nullable": true }, "realtime": { "description": "The live Realtime connection of this Session, read when the response is produced; null when none is live or the Session is deleted.", "type": "object", "properties": { "id": { "description": "Realtime connection ID.", "type": "string" }, "status": { "description": "connecting: admitted, but the realtime audio stream is not open yet. active: the stream is open and the user can speak, including while a task runs. paused: the stream is still open, but the current task is waiting for the user to answer a clarification question; answering resumes it.", "type": "string", "enum": [ "connecting", "active", "paused" ] }, "audio": { "type": "object", "properties": { "input": { "description": "One direction of the Realtime connection audio format.", "oneOf": [ { "type": "object", "properties": { "encoding": { "description": "Little-endian mono samples.", "type": "string", "enum": [ "pcm16" ] }, "sampleRate": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "channels": { "type": "number", "minimum": 1, "maximum": 1 } }, "required": [ "encoding", "sampleRate", "channels" ] }, { "type": "object", "properties": { "encoding": { "description": "One Opus packet per audio frame, decoded at sampleRate.", "type": "string", "enum": [ "opus" ] }, "sampleRate": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "channels": { "type": "number", "minimum": 1, "maximum": 1 }, "packetDurationMs": { "description": "Duration of each Opus packet.", "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "bitrate": { "description": "Output CBR in bps; absent on input and historical connections.", "oneOf": [ { "type": "number", "minimum": 16000, "maximum": 16000 }, { "type": "number", "minimum": 24000, "maximum": 24000 }, { "type": "number", "minimum": 32000, "maximum": 32000 } ] } }, "required": [ "encoding", "sampleRate", "channels", "packetDurationMs" ] } ] }, "output": { "description": "One direction of the Realtime connection audio format.", "oneOf": [ { "type": "object", "properties": { "encoding": { "description": "Little-endian mono samples.", "type": "string", "enum": [ "pcm16" ] }, "sampleRate": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "channels": { "type": "number", "minimum": 1, "maximum": 1 } }, "required": [ "encoding", "sampleRate", "channels" ] }, { "type": "object", "properties": { "encoding": { "description": "One Opus packet per audio frame, decoded at sampleRate.", "type": "string", "enum": [ "opus" ] }, "sampleRate": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "channels": { "type": "number", "minimum": 1, "maximum": 1 }, "packetDurationMs": { "description": "Duration of each Opus packet.", "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "bitrate": { "description": "Output CBR in bps; absent on input and historical connections.", "oneOf": [ { "type": "number", "minimum": 16000, "maximum": 16000 }, { "type": "number", "minimum": 24000, "maximum": 24000 }, { "type": "number", "minimum": 32000, "maximum": 32000 } ] } }, "required": [ "encoding", "sampleRate", "channels", "packetDurationMs" ] } ] } }, "required": [ "input", "output" ] }, "startedAt": { "description": "When the Realtime connection was admitted.", "type": "string" } }, "required": [ "id", "status", "audio", "startedAt" ], "nullable": true }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "deletedAt": { "type": "string", "nullable": true } }, "required": [ "organizationId", "sessionId", "name", "autoTitle", "ownerUserId", "startedByUserId", "createdByType", "readOnly", "sourceSchedulerId", "sourceSchedulerFireId", "model", "modelRevision", "realtimeModel", "realtimeModelRevision", "realtimeModelEtag", "configurationEpoch", "switching", "template", "modelPolicyStatus", "status", "billingTag", "activeTurnId", "realtimeVoice", "realtime", "createdAt", "updatedAt", "deletedAt" ] } }, "required": [ "session" ]}schemas/UpdateSessionModelOpenApiDto
Section titled “schemas/UpdateSessionModelOpenApiDto”{ "type": "object", "properties": { "model": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[A-Za-z0-9][A-Za-z0-9_.-]*$" } }, "required": [ "model" ], "additionalProperties": false}schemas/UpdateSessionRealtimeModelOpenApiDto
Section titled “schemas/UpdateSessionRealtimeModelOpenApiDto”{ "type": "object", "properties": { "realtimeModel": { "type": "string", "minLength": 1, "maxLength": 128 } }, "required": [ "realtimeModel" ]}schemas/UpdateSessionBillingTagOpenApiDto
Section titled “schemas/UpdateSessionBillingTagOpenApiDto”{ "type": "object", "properties": { "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" } ] } }, "required": [ "billingTag" ], "additionalProperties": false}schemas/RenameSessionOpenApiDto
Section titled “schemas/RenameSessionOpenApiDto”{ "type": "object", "properties": { "name": { "description": "Trimmed before storage; the trimmed name must contain 1 to 80 characters.", "type": "string", "minLength": 1, "pattern": "^\\s*\\S(?:[\\s\\S]{0,78}\\S)?\\s*$" } }, "required": [ "name" ]}schemas/SuggestSessionNameOpenApiDto
Section titled “schemas/SuggestSessionNameOpenApiDto”{ "type": "object", "properties": { "userText": { "type": "string", "minLength": 1, "maxLength": 4000 }, "assistantText": { "type": "string", "maxLength": 4000 } }, "required": [ "userText" ]}schemas/SuggestSessionNameResponseOpenApiDto
Section titled “schemas/SuggestSessionNameResponseOpenApiDto”{ "type": "object", "properties": { "name": { "type": "string" }, "session": { "type": "object", "properties": { "organizationId": { "type": "string" }, "sessionId": { "type": "string" }, "name": { "type": "string", "nullable": true }, "autoTitle": { "type": "string", "nullable": true }, "ownerUserId": { "type": "string" }, "startedByUserId": { "type": "string" }, "createdByType": { "type": "string", "enum": [ "user", "scheduler" ] }, "readOnly": { "type": "boolean" }, "sourceSchedulerId": { "type": "string", "nullable": true }, "sourceSchedulerFireId": { "type": "string", "nullable": true }, "model": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[A-Za-z0-9][A-Za-z0-9_.-]*$" }, "modelRevision": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "realtimeModel": { "description": "Selection for the next Realtime Connection; null uses the active release default.", "type": "string", "nullable": true }, "realtimeModelRevision": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "realtimeModelEtag": { "description": "Opaque If-Match token for PATCH /api/v1/user/sessions/{id}/realtime-model; independent of the text model ETag.", "type": "string" }, "configurationEpoch": { "description": "Current immutable Session Configuration Epoch; null for retained read-only or provider-owned snapshots outside the epoch model.", "type": "integer", "minimum": 1, "exclusiveMinimum": false, "nullable": true }, "switching": { "description": "True while a durable Session Template-switch command fences new interaction.", "type": "boolean" }, "template": { "type": "object", "properties": { "templateId": { "type": "string" }, "contentDigest": { "type": "string" } }, "required": [ "templateId", "contentDigest" ], "nullable": true }, "modelPolicyStatus": { "type": "string", "enum": [ "allowed", "organization_disallowed" ] }, "status": { "type": "string", "enum": [ "active", "deleted" ] }, "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" } ] }, "activeTurnId": { "type": "string", "nullable": true }, "realtimeVoice": { "description": "Fixed Session voice setting; null disables voice. This does not guarantee current provider availability.", "type": "object", "properties": { "language": { "type": "string", "enum": [ "zh-CN", "en-US" ] } }, "required": [ "language" ], "nullable": true }, "realtime": { "description": "The live Realtime connection of this Session, read when the response is produced; null when none is live or the Session is deleted.", "type": "object", "properties": { "id": { "description": "Realtime connection ID.", "type": "string" }, "status": { "description": "connecting: admitted, but the realtime audio stream is not open yet. active: the stream is open and the user can speak, including while a task runs. paused: the stream is still open, but the current task is waiting for the user to answer a clarification question; answering resumes it.", "type": "string", "enum": [ "connecting", "active", "paused" ] }, "audio": { "type": "object", "properties": { "input": { "description": "One direction of the Realtime connection audio format.", "oneOf": [ { "type": "object", "properties": { "encoding": { "description": "Little-endian mono samples.", "type": "string", "enum": [ "pcm16" ] }, "sampleRate": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "channels": { "type": "number", "minimum": 1, "maximum": 1 } }, "required": [ "encoding", "sampleRate", "channels" ] }, { "type": "object", "properties": { "encoding": { "description": "One Opus packet per audio frame, decoded at sampleRate.", "type": "string", "enum": [ "opus" ] }, "sampleRate": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "channels": { "type": "number", "minimum": 1, "maximum": 1 }, "packetDurationMs": { "description": "Duration of each Opus packet.", "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "bitrate": { "description": "Output CBR in bps; absent on input and historical connections.", "oneOf": [ { "type": "number", "minimum": 16000, "maximum": 16000 }, { "type": "number", "minimum": 24000, "maximum": 24000 }, { "type": "number", "minimum": 32000, "maximum": 32000 } ] } }, "required": [ "encoding", "sampleRate", "channels", "packetDurationMs" ] } ] }, "output": { "description": "One direction of the Realtime connection audio format.", "oneOf": [ { "type": "object", "properties": { "encoding": { "description": "Little-endian mono samples.", "type": "string", "enum": [ "pcm16" ] }, "sampleRate": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "channels": { "type": "number", "minimum": 1, "maximum": 1 } }, "required": [ "encoding", "sampleRate", "channels" ] }, { "type": "object", "properties": { "encoding": { "description": "One Opus packet per audio frame, decoded at sampleRate.", "type": "string", "enum": [ "opus" ] }, "sampleRate": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "channels": { "type": "number", "minimum": 1, "maximum": 1 }, "packetDurationMs": { "description": "Duration of each Opus packet.", "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "bitrate": { "description": "Output CBR in bps; absent on input and historical connections.", "oneOf": [ { "type": "number", "minimum": 16000, "maximum": 16000 }, { "type": "number", "minimum": 24000, "maximum": 24000 }, { "type": "number", "minimum": 32000, "maximum": 32000 } ] } }, "required": [ "encoding", "sampleRate", "channels", "packetDurationMs" ] } ] } }, "required": [ "input", "output" ] }, "startedAt": { "description": "When the Realtime connection was admitted.", "type": "string" } }, "required": [ "id", "status", "audio", "startedAt" ], "nullable": true }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "deletedAt": { "type": "string", "nullable": true } }, "required": [ "organizationId", "sessionId", "name", "autoTitle", "ownerUserId", "startedByUserId", "createdByType", "readOnly", "sourceSchedulerId", "sourceSchedulerFireId", "model", "modelRevision", "realtimeModel", "realtimeModelRevision", "realtimeModelEtag", "configurationEpoch", "switching", "template", "modelPolicyStatus", "status", "billingTag", "activeTurnId", "realtimeVoice", "realtime", "createdAt", "updatedAt", "deletedAt" ] } }, "required": [ "name", "session" ]}schemas/UploadSessionFileOpenApiDto
Section titled “schemas/UploadSessionFileOpenApiDto”{ "type": "object", "properties": { "path": { "type": "string", "minLength": 1, "maxLength": 512 }, "content": { "type": "string", "maxLength": 1048576 } }, "required": [ "path", "content" ]}schemas/UploadSessionFileResponseOpenApiDto
Section titled “schemas/UploadSessionFileResponseOpenApiDto”{ "type": "object", "properties": { "file": { "type": "object", "properties": { "path": { "type": "string" }, "size": { "type": "integer", "minimum": 0, "exclusiveMinimum": false } }, "required": [ "path", "size" ] } }, "required": [ "file" ]}schemas/UploadSessionFilesOpenApiDto
Section titled “schemas/UploadSessionFilesOpenApiDto”{ "type": "object", "properties": { "files": { "type": "array", "minItems": 1, "maxItems": 128, "items": { "type": "object", "properties": { "path": { "type": "string", "minLength": 1, "maxLength": 512 }, "content": { "type": "string", "maxLength": 1048576 } }, "required": [ "path", "content" ] } } }, "required": [ "files" ]}schemas/UploadSessionFilesResponseOpenApiDto
Section titled “schemas/UploadSessionFilesResponseOpenApiDto”{ "type": "object", "properties": { "files": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "size": { "type": "integer", "minimum": 0, "exclusiveMinimum": false } }, "required": [ "path", "size" ] } } }, "required": [ "files" ]}schemas/SessionEventOpenApiDto
Section titled “schemas/SessionEventOpenApiDto”{ "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "message", "InputMessageEvent", "agent.session.input.message" ] }, "clientEventId": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:-]{0,127}$" }, "data": { "anyOf": [ { "type": "object", "properties": { "content": { "oneOf": [ { "type": "string", "minLength": 1 }, { "type": "array", "minItems": 1, "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string", "minLength": 1 } }, "required": [ "type", "text" ], "additionalProperties": false } } ] }, "text": { "description": "Ordinary Turns require readable string text. A linked single-select clarification accepts a string or one-element string array; a linked multi-select clarification requires a non-empty string array.", "oneOf": [ { "type": "string", "minLength": 1 }, { "type": "array", "minItems": 1, "maxItems": 9, "items": { "type": "string", "minLength": 1 } } ] }, "userFileIds": { "type": "array", "maxItems": 20, "items": { "type": "string", "minLength": 1, "maxLength": 64 } }, "clarificationSourceTurnId": { "type": "string", "minLength": 1, "maxLength": 64 }, "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" } ] } }, "required": [ "content" ], "additionalProperties": false }, { "type": "object", "properties": { "content": { "oneOf": [ { "type": "string", "minLength": 1 }, { "type": "array", "minItems": 1, "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string", "minLength": 1 } }, "required": [ "type", "text" ], "additionalProperties": false } } ] }, "text": { "description": "Ordinary Turns require readable string text. A linked single-select clarification accepts a string or one-element string array; a linked multi-select clarification requires a non-empty string array.", "oneOf": [ { "type": "string", "minLength": 1 }, { "type": "array", "minItems": 1, "maxItems": 9, "items": { "type": "string", "minLength": 1 } } ] }, "userFileIds": { "type": "array", "maxItems": 20, "items": { "type": "string", "minLength": 1, "maxLength": 64 } }, "clarificationSourceTurnId": { "type": "string", "minLength": 1, "maxLength": 64 }, "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" } ] } }, "required": [ "text" ], "additionalProperties": false } ] } }, "required": [ "type", "clientEventId", "data" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "cancel", "InputCancelEvent", "agent.session.input.cancel" ] }, "clientEventId": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:-]{0,127}$" }, "data": { "type": "object", "properties": { "turnId": { "type": "string", "minLength": 1, "maxLength": 64 } }, "additionalProperties": false } }, "required": [ "type", "clientEventId", "data" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "retry", "InputRetryEvent", "agent.session.input.retry" ] }, "clientEventId": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:-]{0,127}$" }, "data": { "type": "object", "properties": { "turnId": { "type": "string", "minLength": 1, "maxLength": 64 } }, "required": [ "turnId" ], "additionalProperties": false } }, "required": [ "type", "clientEventId", "data" ], "additionalProperties": false } ]}schemas/SessionInteractionResponseOpenApiDto
Section titled “schemas/SessionInteractionResponseOpenApiDto”{ "type": "object", "properties": { "interaction": { "type": "object", "properties": { "inputId": { "type": "string" }, "sequence": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "kind": { "type": "string", "enum": [ "message", "cancel", "retry", "client_tool_output" ] }, "mode": { "type": "string", "enum": [ "started", "steered", "cancelled", "accepted", "rejected" ] }, "turnId": { "type": "string" }, "message": { "type": "object", "properties": { "id": { "type": "string" }, "role": { "type": "string", "enum": [ "user" ] }, "content": { "type": "string" }, "createdAt": { "type": "string" } }, "required": [ "id", "role", "content", "createdAt" ], "nullable": true }, "createdAt": { "type": "string" }, "appliedAt": { "type": "string", "nullable": true }, "rejection": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "interaction_admission_closed", "interaction_target_conflict", "client_tool_call_unavailable", "client_tool_call_settled" ] } }, "required": [ "code" ], "nullable": true }, "result": { "description": "Original execution-generation settlement. Immutable after terminal publication, including across explicit checkpoint retry.", "type": "object", "properties": { "status": { "type": "string", "enum": [ "running", "succeeded", "failed", "interrupted" ] }, "completedAt": { "type": "string", "nullable": true } }, "required": [ "status", "completedAt" ] } }, "required": [ "inputId", "sequence", "kind", "mode", "turnId", "message", "createdAt", "appliedAt", "rejection", "result" ] } }, "required": [ "interaction" ]}schemas/SessionEventRetryResponseOpenApiDto
Section titled “schemas/SessionEventRetryResponseOpenApiDto”{ "type": "object", "properties": { "event": { "type": "object", "properties": { "clientEventId": { "type": "string" }, "sessionId": { "type": "string" }, "turnId": { "type": "string" }, "disposition": { "type": "string", "enum": [ "retrying" ] } }, "required": [ "clientEventId", "sessionId", "turnId", "disposition" ] } }, "required": [ "event" ]}schemas/SessionInteractionsResponseOpenApiDto
Section titled “schemas/SessionInteractionsResponseOpenApiDto”{ "type": "object", "properties": { "interactions": { "type": "array", "items": { "type": "object", "properties": { "inputId": { "type": "string" }, "sequence": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "kind": { "type": "string", "enum": [ "message", "cancel", "retry", "client_tool_output" ] }, "mode": { "type": "string", "enum": [ "started", "steered", "cancelled", "accepted", "rejected" ] }, "turnId": { "type": "string" }, "message": { "type": "object", "properties": { "id": { "type": "string" }, "role": { "type": "string", "enum": [ "user" ] }, "content": { "type": "string" }, "createdAt": { "type": "string" } }, "required": [ "id", "role", "content", "createdAt" ], "nullable": true }, "createdAt": { "type": "string" }, "appliedAt": { "type": "string", "nullable": true }, "rejection": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "interaction_admission_closed", "interaction_target_conflict", "client_tool_call_unavailable", "client_tool_call_settled" ] } }, "required": [ "code" ], "nullable": true }, "result": { "description": "Original execution-generation settlement. Immutable after terminal publication, including across explicit checkpoint retry.", "type": "object", "properties": { "status": { "type": "string", "enum": [ "running", "succeeded", "failed", "interrupted" ] }, "completedAt": { "type": "string", "nullable": true } }, "required": [ "status", "completedAt" ] } }, "required": [ "inputId", "sequence", "kind", "mode", "turnId", "message", "createdAt", "appliedAt", "rejection", "result" ] } }, "hasMore": { "type": "boolean" }, "nextCursor": { "type": "string", "nullable": true } }, "required": [ "interactions", "hasMore", "nextCursor" ]}schemas/TurnStreamEvent
Section titled “schemas/TurnStreamEvent”{ "oneOf": [ { "type": "object", "required": [ "event", "turnId", "sessionId", "seq", "createdAt", "payload" ], "properties": { "event": { "type": "string", "enum": [ "turn_started" ] }, "turnId": { "type": "string" }, "sessionId": { "type": "string" }, "agentRunId": { "description": "Physical AgentRun that emitted this event. Historical replay rows may omit it.", "type": "string" }, "seq": { "type": "integer" }, "createdAt": { "type": "string", "format": "date-time" }, "payload": { "type": "object", "properties": { "inputId": { "type": "string", "description": "Stable customer input identity, required on ordinary JSON text starts. Historical, checkpoint retry and retained advanced audio/internal starts may omit it." }, "execution": { "description": "Display-safe frozen Runtime request settings for this AgentRun. Historical persisted events may omit it.", "type": "object", "properties": { "model": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[A-Za-z0-9][A-Za-z0-9_.-]*$" } }, "required": [ "model" ], "additionalProperties": false } }, "additionalProperties": false } } }, { "type": "object", "required": [ "event", "turnId", "sessionId", "seq", "createdAt", "payload" ], "properties": { "event": { "type": "string", "enum": [ "progress" ] }, "turnId": { "type": "string" }, "sessionId": { "type": "string" }, "agentRunId": { "description": "Physical AgentRun that emitted this event. Historical replay rows may omit it.", "type": "string" }, "seq": { "type": "integer" }, "createdAt": { "type": "string", "format": "date-time" }, "payload": { "type": "object", "required": [ "text" ], "properties": { "text": { "type": "string" } } } } }, { "type": "object", "required": [ "event", "turnId", "sessionId", "seq", "createdAt", "payload" ], "properties": { "event": { "type": "string", "enum": [ "assistant_draft" ] }, "turnId": { "type": "string" }, "sessionId": { "type": "string" }, "agentRunId": { "description": "Physical AgentRun that emitted this event. Historical replay rows may omit it.", "type": "string" }, "seq": { "type": "integer" }, "createdAt": { "type": "string", "format": "date-time" }, "payload": { "type": "object", "required": [ "text" ], "properties": { "text": { "type": "string" } } } } }, { "type": "object", "required": [ "event", "turnId", "sessionId", "seq", "createdAt", "payload" ], "properties": { "event": { "type": "string", "enum": [ "operation_step" ] }, "turnId": { "type": "string" }, "sessionId": { "type": "string" }, "agentRunId": { "description": "Physical AgentRun that emitted this event. Historical replay rows may omit it.", "type": "string" }, "seq": { "type": "integer" }, "createdAt": { "type": "string", "format": "date-time" }, "payload": { "type": "object", "required": [ "operationId", "status", "label" ], "properties": { "operationId": { "type": "string" }, "status": { "type": "string", "enum": [ "running", "succeeded", "failed", "interrupted", "unknown_result" ] }, "label": { "type": "string" }, "category": { "type": "string", "enum": [ "tool_call", "skill_read" ], "description": "The same grouping as the Operation's category in Turn reads. Absent on non-tool and metadata-only Operations and on events saved before this field existed." }, "skill": { "$ref": "#/components/schemas/OperationSkill" }, "source": { "$ref": "#/components/schemas/ClientToolOperationSource" } } } } }, { "type": "object", "required": [ "event", "turnId", "sessionId", "seq", "createdAt", "payload" ], "properties": { "event": { "type": "string", "enum": [ "assistant_message" ] }, "turnId": { "type": "string" }, "sessionId": { "type": "string" }, "agentRunId": { "description": "Physical AgentRun that emitted this event. Historical replay rows may omit it.", "type": "string" }, "seq": { "type": "integer" }, "createdAt": { "type": "string", "format": "date-time" }, "payload": { "type": "object", "required": [ "messageId", "text" ], "properties": { "messageId": { "type": "string" }, "text": { "type": "string" }, "clarificationItem": { "$ref": "#/components/schemas/ClarificationItem" } } } }, "example": { "event": "assistant_message", "turnId": "turn_123", "sessionId": "sess_123", "seq": 3, "createdAt": "2026-07-13T00:00:00.000Z", "payload": { "messageId": "msg_123", "text": "Choose a deployment target.", "clarificationItem": { "prompt": "Where should I deploy?", "selectionMode": "single", "answerChoices": [ "Staging", "Production" ] } } } }, { "type": "object", "required": [ "event", "turnId", "sessionId", "seq", "createdAt", "payload" ], "properties": { "event": { "type": "string", "enum": [ "client_tool_calls" ] }, "turnId": { "type": "string" }, "sessionId": { "type": "string" }, "agentRunId": { "description": "Physical AgentRun that emitted this event. Historical replay rows may omit it.", "type": "string" }, "seq": { "type": "integer" }, "createdAt": { "type": "string", "format": "date-time" }, "payload": { "type": "object", "description": "The Client Tool calls of one model step, published together to the Session's executing Backend Connection attachment, which claims each with tool.claim before claimBy and answers it with tool.result. No REST command answers them.", "required": [ "calls" ], "properties": { "calls": { "type": "array", "items": { "type": "object", "required": [ "callId", "name", "arguments", "deadlineAt" ], "properties": { "callId": { "type": "string" }, "name": { "type": "string" }, "arguments": { "type": "object", "additionalProperties": {} }, "deadlineAt": { "type": "string", "format": "date-time" }, "claimBy": { "description": "The end of the call's claim window. Only the Session's executing Backend Connection attachment executes the call, after tool.claim succeeds before this time, and answers it with tool.result. Absent only on calls published before the per-Session subscription was removed.", "type": "string", "format": "date-time" } } } } } } } }, { "type": "object", "required": [ "event", "turnId", "sessionId", "seq", "createdAt", "payload" ], "properties": { "event": { "type": "string", "enum": [ "turn_error" ] }, "turnId": { "type": "string" }, "sessionId": { "type": "string" }, "agentRunId": { "description": "Physical AgentRun that emitted this event. Historical replay rows may omit it.", "type": "string" }, "seq": { "type": "integer" }, "createdAt": { "type": "string", "format": "date-time" }, "payload": { "$ref": "#/components/schemas/TurnFailure" } } }, { "type": "object", "required": [ "event", "turnId", "sessionId", "seq", "createdAt", "payload" ], "properties": { "event": { "type": "string", "enum": [ "turn_finished" ] }, "turnId": { "type": "string" }, "sessionId": { "type": "string" }, "agentRunId": { "description": "Physical AgentRun that emitted this event. Historical replay rows may omit it.", "type": "string" }, "seq": { "type": "integer" }, "createdAt": { "type": "string", "format": "date-time" }, "payload": { "type": "object", "required": [ "status" ], "properties": { "status": { "type": "string", "enum": [ "succeeded", "failed", "interrupted" ] } } } } } ]}schemas/OperationSkill
Section titled “schemas/OperationSkill”{ "type": "object", "description": "The Skill a skill_read Operation read from; present only with category skill_read.", "required": [ "skillId", "name" ], "properties": { "skillId": { "type": "string" }, "name": { "type": "string" } }}schemas/ClientToolOperationSource
Section titled “schemas/ClientToolOperationSource”{ "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "session_client" ] } } }, { "type": "object", "additionalProperties": false, "required": [ "type", "hardwareRequirementId", "method" ], "properties": { "type": { "type": "string", "enum": [ "hardware" ] }, "hardwareRequirementId": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z][a-z0-9_.-]{0,99}$" }, "method": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[a-zA-Z0-9_-]{1,64}$" } } } ], "description": "Client Tool source; only safe requirement and original method are exposed for Hardware. Absent on metadata-only Operations. Current reads default older Session-client Operations to session_client; persisted historical progress events may omit source."}schemas/ClarificationItem
Section titled “schemas/ClarificationItem”{ "description": "A structured blocking question and its optional canonical persisted response. The linked user Message remains the readable conversation projection.", "discriminator": { "propertyName": "selectionMode" }, "oneOf": [ { "type": "object", "required": [ "prompt", "selectionMode", "answerChoices" ], "properties": { "prompt": { "type": "string" }, "selectionMode": { "type": "string", "enum": [ "single" ], "description": "Requires exactly one answer and two or three mutually exclusive candidates." }, "answerChoices": { "type": "array", "minItems": 2, "maxItems": 3, "description": "Candidate display order is also the canonical structured-answer order.", "items": { "type": "string", "minLength": 1 } }, "response": { "type": "object", "required": [ "answers", "responseTurnId" ], "properties": { "answers": { "type": "array", "minItems": 1, "maxItems": 1, "description": "The single structured answer.", "items": { "type": "string", "minLength": 1 } }, "responseTurnId": { "type": "string" } } } } }, { "type": "object", "required": [ "prompt", "selectionMode", "answerChoices" ], "properties": { "prompt": { "type": "string" }, "selectionMode": { "type": "string", "enum": [ "multiple" ], "description": "Accepts a non-empty selection containing candidate values and/or at most one user-supplied value, with two through eight compatible candidates." }, "answerChoices": { "type": "array", "minItems": 2, "maxItems": 8, "description": "Candidate display order is also the canonical structured-answer order.", "items": { "type": "string", "minLength": 1 } }, "response": { "type": "object", "required": [ "answers", "responseTurnId" ], "properties": { "answers": { "type": "array", "minItems": 1, "maxItems": 9, "description": "Distinct structured values in candidate display order, followed by at most one user-supplied answer.", "items": { "type": "string", "minLength": 1 } }, "responseTurnId": { "type": "string" } } } } } ]}schemas/TurnFailure
Section titled “schemas/TurnFailure”{ "type": "object", "description": "A failed Turn's public error, as carried by its turn_error event and Turn.failure. The message is fixed text for the code and never contains supplier or internal error text.", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "service_configuration_unavailable (details.reason names the missing service), model_provider_failed (details.provider carries bounded supplier facts), mcp_authorization_required (details.registrations names each MCP Server Registration whose MCP Authorization is not usable), session_execution_dependency_unavailable (an MCP Server Registration the Session references became unavailable after admission, or two references would offer tools under the same model-visible name), runtime_error, interrupted, or another stable failure code." }, "message": { "type": "string" }, "details": { "type": "object", "properties": { "reason": { "description": "Present only with code service_configuration_unavailable, when the Turn failed because the deployment or Organization lacks a service it needs. The reason and message match the service_configuration_unavailable error response.", "type": "string", "enum": [ "model_provider_unconfigured", "sandbox_unconfigured", "drive9_unconfigured", "drive9_disabled_for_organization" ] }, "provider": { "description": "Present only with code model_provider_failed. The failure category, the HTTP status the supplier returned and the supplier's own error type and code, each null when unknown. A supplier redirect is never followed and reads as supplier_error with the 3xx status and errorType redirect. Never supplier message text, request paths or credentials.", "type": "object", "required": [ "category", "httpStatus", "errorType", "errorCode" ], "properties": { "category": { "type": "string", "enum": [ "authentication", "supplier_error", "supplier_unavailable", "network", "provider_stream_error" ] }, "httpStatus": { "type": "integer", "nullable": true }, "errorType": { "type": "string", "nullable": true }, "errorCode": { "type": "string", "nullable": true } } }, "registrations": { "description": "Present only with code mcp_authorization_required. Each MCP Server Registration the Turn needs whose MCP Authorization is not usable, in serverId order, with the same entries as the mcp_authorization_required error response's details.registrations. A Turn fails with it when a tool call finds the authorization unusable (revoked, or refused by the server with HTTP 401 or 403) or the Turn's AgentRun cannot freeze it; the call is recorded as failed and not dispatched, and the Turn is not resumed.", "type": "array", "minItems": 1, "items": { "type": "object", "additionalProperties": false, "required": [ "serverId", "owner", "reason" ], "properties": { "serverId": { "type": "string" }, "owner": { "description": "Who must authorize the registration.", "type": "string", "enum": [ "organization", "end_user" ] }, "reason": { "description": "missing (no usable authorization with a catalog exists), invalid (it was invalidated by an endpoint or mode change, or the server refused its credential with HTTP 401 or 403 during a Turn), revoked (its credential was revoked) or insufficient_scope (the server answered 403 insufficient_scope, requiring a scope it lacks).", "type": "string", "enum": [ "missing", "invalid", "revoked", "insufficient_scope" ] } } } } } } }}schemas/SessionTimelineResponseOpenApiDto
Section titled “schemas/SessionTimelineResponseOpenApiDto”{ "type": "object", "properties": { "entries": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "turn" ] }, "turn": { "oneOf": [ { "type": "object", "properties": { "executor": { "description": "Always returned by /turns list and detail; older Turn surfaces may omit it.", "type": "string", "enum": [ "full_agent", "realtime_model" ] }, "realtime": { "type": "object", "properties": { "connectionId": { "type": "string" }, "linkedTurnIds": { "type": "array", "items": { "type": "string" } } }, "required": [ "connectionId", "linkedTurnIds" ] }, "realtimeResponses": { "description": "Narration-only Realtime responses about this Full Agent Turn, in Session sequence order.", "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "sessionId": { "type": "string" }, "turnId": { "type": "string" }, "role": { "type": "string", "enum": [ "user", "assistant" ] }, "content": { "type": "string" }, "createdAt": { "type": "string" }, "inputContext": { "description": "Server-recorded channel of a user input; clients cannot set it. Present on user Messages except Scheduler-triggered Turns and Messages saved before it existed; absent on assistant Messages. Tolerate channel values added later.", "oneOf": [ { "type": "object", "properties": { "channel": { "type": "string", "enum": [ "text" ] } }, "required": [ "channel" ] }, { "type": "object", "properties": { "channel": { "type": "string", "enum": [ "audio" ] }, "utterance": { "description": "Transcript of the user's own speech when the Message content is a task delegated from it.", "type": "string", "minLength": 1, "maxLength": 8000 }, "emotion": { "description": "Emotion the Realtime model perceived in the speech; not a verified fact.", "type": "object", "properties": { "label": { "type": "string", "minLength": 1, "maxLength": 64 }, "confidence": { "type": "number", "minimum": 0, "exclusiveMinimum": false, "maximum": 1, "exclusiveMaximum": false }, "source": { "type": "string", "enum": [ "realtime_model" ] } }, "required": [ "label", "confidence", "source" ] }, "realtimeSummary": { "description": "Legacy field on Messages saved by earlier releases; new Messages omit it. The Realtime model's own summary of the preceding voice conversation; model-written, not a durable transcript.", "type": "string", "minLength": 1, "maxLength": 8000 } }, "required": [ "channel" ] }, { "description": "A Realtime Standing Task cycle: the platform started this Turn with the Template's standing goal while a Realtime Connection was live; nobody typed or spoke it.", "type": "object", "properties": { "channel": { "type": "string", "enum": [ "standing_task" ] } }, "required": [ "channel" ] } ] }, "realtime": { "oneOf": [ { "type": "object", "properties": { "startsTurn": { "type": "boolean" }, "linkedTurnId": { "type": "string", "nullable": true } }, "required": [ "startsTurn", "linkedTurnId" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "chat", "task_ack", "task_progress", "task_result", "clarify", "device_ack" ] }, "interrupted": { "description": "The reply was interrupted; its transcript may include speech the user did not hear.", "type": "boolean" }, "responseId": { "type": "string", "nullable": true }, "linkedTurnId": { "type": "string", "nullable": true } }, "required": [ "kind", "interrupted", "responseId", "linkedTurnId" ] } ] } }, "required": [ "id", "sessionId", "turnId", "role", "content", "createdAt" ] } }, "id": { "type": "string" }, "sessionId": { "type": "string" }, "status": { "type": "string", "enum": [ "running", "succeeded", "failed", "interrupted" ] }, "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" } ] }, "agentTemplateId": { "description": "AgentTemplate frozen when the Turn was admitted.", "type": "string", "nullable": true }, "userMessage": { "type": "object", "properties": { "id": { "type": "string" }, "sessionId": { "type": "string" }, "turnId": { "type": "string" }, "role": { "type": "string", "enum": [ "user", "assistant" ] }, "content": { "type": "string" }, "createdAt": { "type": "string" }, "inputContext": { "description": "Server-recorded channel of a user input; clients cannot set it. Present on user Messages except Scheduler-triggered Turns and Messages saved before it existed; absent on assistant Messages. Tolerate channel values added later.", "oneOf": [ { "type": "object", "properties": { "channel": { "type": "string", "enum": [ "text" ] } }, "required": [ "channel" ] }, { "type": "object", "properties": { "channel": { "type": "string", "enum": [ "audio" ] }, "utterance": { "description": "Transcript of the user's own speech when the Message content is a task delegated from it.", "type": "string", "minLength": 1, "maxLength": 8000 }, "emotion": { "description": "Emotion the Realtime model perceived in the speech; not a verified fact.", "type": "object", "properties": { "label": { "type": "string", "minLength": 1, "maxLength": 64 }, "confidence": { "type": "number", "minimum": 0, "exclusiveMinimum": false, "maximum": 1, "exclusiveMaximum": false }, "source": { "type": "string", "enum": [ "realtime_model" ] } }, "required": [ "label", "confidence", "source" ] }, "realtimeSummary": { "description": "Legacy field on Messages saved by earlier releases; new Messages omit it. The Realtime model's own summary of the preceding voice conversation; model-written, not a durable transcript.", "type": "string", "minLength": 1, "maxLength": 8000 } }, "required": [ "channel" ] }, { "description": "A Realtime Standing Task cycle: the platform started this Turn with the Template's standing goal while a Realtime Connection was live; nobody typed or spoke it.", "type": "object", "properties": { "channel": { "type": "string", "enum": [ "standing_task" ] } }, "required": [ "channel" ] } ] }, "realtime": { "oneOf": [ { "type": "object", "properties": { "startsTurn": { "type": "boolean" }, "linkedTurnId": { "type": "string", "nullable": true } }, "required": [ "startsTurn", "linkedTurnId" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "chat", "task_ack", "task_progress", "task_result", "clarify", "device_ack" ] }, "interrupted": { "description": "The reply was interrupted; its transcript may include speech the user did not hear.", "type": "boolean" }, "responseId": { "type": "string", "nullable": true }, "linkedTurnId": { "type": "string", "nullable": true } }, "required": [ "kind", "interrupted", "responseId", "linkedTurnId" ] } ] } }, "required": [ "id", "sessionId", "turnId", "role", "content", "createdAt" ] }, "userMessages": { "description": "Canonical admitted user Messages in input order; includes accepted inputs interrupted before incorporation.", "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "sessionId": { "type": "string" }, "turnId": { "type": "string" }, "role": { "type": "string", "enum": [ "user", "assistant" ] }, "content": { "type": "string" }, "createdAt": { "type": "string" }, "inputContext": { "description": "Server-recorded channel of a user input; clients cannot set it. Present on user Messages except Scheduler-triggered Turns and Messages saved before it existed; absent on assistant Messages. Tolerate channel values added later.", "oneOf": [ { "type": "object", "properties": { "channel": { "type": "string", "enum": [ "text" ] } }, "required": [ "channel" ] }, { "type": "object", "properties": { "channel": { "type": "string", "enum": [ "audio" ] }, "utterance": { "description": "Transcript of the user's own speech when the Message content is a task delegated from it.", "type": "string", "minLength": 1, "maxLength": 8000 }, "emotion": { "description": "Emotion the Realtime model perceived in the speech; not a verified fact.", "type": "object", "properties": { "label": { "type": "string", "minLength": 1, "maxLength": 64 }, "confidence": { "type": "number", "minimum": 0, "exclusiveMinimum": false, "maximum": 1, "exclusiveMaximum": false }, "source": { "type": "string", "enum": [ "realtime_model" ] } }, "required": [ "label", "confidence", "source" ] }, "realtimeSummary": { "description": "Legacy field on Messages saved by earlier releases; new Messages omit it. The Realtime model's own summary of the preceding voice conversation; model-written, not a durable transcript.", "type": "string", "minLength": 1, "maxLength": 8000 } }, "required": [ "channel" ] }, { "description": "A Realtime Standing Task cycle: the platform started this Turn with the Template's standing goal while a Realtime Connection was live; nobody typed or spoke it.", "type": "object", "properties": { "channel": { "type": "string", "enum": [ "standing_task" ] } }, "required": [ "channel" ] } ] }, "realtime": { "oneOf": [ { "type": "object", "properties": { "startsTurn": { "type": "boolean" }, "linkedTurnId": { "type": "string", "nullable": true } }, "required": [ "startsTurn", "linkedTurnId" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "chat", "task_ack", "task_progress", "task_result", "clarify", "device_ack" ] }, "interrupted": { "description": "The reply was interrupted; its transcript may include speech the user did not hear.", "type": "boolean" }, "responseId": { "type": "string", "nullable": true }, "linkedTurnId": { "type": "string", "nullable": true } }, "required": [ "kind", "interrupted", "responseId", "linkedTurnId" ] } ] } }, "required": [ "id", "sessionId", "turnId", "role", "content", "createdAt" ] } }, "userFiles": { "type": "array", "items": { "type": "object", "properties": { "turnId": { "type": "string" }, "sessionId": { "type": "string" }, "organizationId": { "type": "string" }, "userFileId": { "type": "string" }, "ordinal": { "type": "integer" }, "originalName": { "type": "string" }, "safeName": { "type": "string" }, "drivePath": { "type": "string" }, "byteSize": { "type": "integer" }, "sha256": { "type": "string" }, "checksumVerification": { "description": "Verified fact for a ready file; null until settlement. whole verifies the complete file, while part_only verifies every multipart part.", "type": "string", "enum": [ "whole", "part_only" ], "nullable": true }, "contentType": { "type": "string", "nullable": true }, "createdAt": { "type": "string" } }, "required": [ "turnId", "sessionId", "organizationId", "userFileId", "ordinal", "originalName", "safeName", "drivePath", "byteSize", "sha256", "checksumVerification", "contentType", "createdAt" ] } }, "operations": { "description": "Operations performed by the Turn. drive.commit is recorded only after a workspace tool attempt.", "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "sessionId": { "type": "string" }, "turnId": { "type": "string" }, "scope": { "type": "object", "additionalProperties": {} }, "kind": { "type": "string" }, "backend": { "type": "string" }, "targetKind": { "type": "string" }, "mediator": { "type": "string", "enum": [ "aos" ] }, "status": { "type": "string", "enum": [ "running", "succeeded", "failed", "interrupted", "unknown_result" ] }, "category": { "description": "How to group a tool Operation: skill_read when it reads a file inside one of its AgentRun's frozen Skill packages, whether Runtime loaded the Skill instructions or the model read a package file; tool_call for every other tool Operation. Absent on non-tool Operations such as llm.complete and on metadata-only Operations.", "type": "string", "enum": [ "tool_call", "skill_read" ] }, "skill": { "description": "The Skill a skill_read Operation read from; present only with category skill_read.", "type": "object", "properties": { "skillId": { "type": "string" }, "name": { "type": "string" } }, "required": [ "skillId", "name" ] }, "source": { "description": "Client Tool source: session_client for every new call. Hardware sources appear only on calls recorded before native Hardware retired and expose the Session binding or requirement identifier and original method. Private device and Registration identities are omitted. Absent on metadata-only Operations. Current reads default older Session-client Operations to session_client; persisted historical progress events may omit source.", "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "session_client" ] } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "hardware" ] }, "method": { "type": "string", "pattern": "^[a-zA-Z0-9_-]{1,64}$" }, "hardwareRequirementId": { "type": "string", "pattern": "^[a-z][a-z0-9_.-]{0,99}$" } }, "required": [ "type", "method", "hardwareRequirementId" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "hardware" ] }, "method": { "type": "string", "pattern": "^[a-zA-Z0-9_-]{1,64}$" }, "hardwareBindingId": { "type": "string", "pattern": "^hbind_[0-9a-f]{32}$" } }, "required": [ "type", "method", "hardwareBindingId" ] } ] }, "label": { "description": "Readable label of a historical Hardware Client Tool, for example Speaker · set_volume. Absent on metadata-only Operations.", "type": "string", "maxLength": 322 }, "input": { "description": "Kind-specific input. A tool Operation has toolName and args; a historical Hardware Client Tool exposes only toolName, callId and mode, omitting device arguments. Neither input nor output carries the model supplier's tool-call id; use the Operation id to identify a tool call and its result." }, "output": { "description": "Kind-specific result. Hardware Client Tool Operations, recorded before native Hardware retired, omit output in every status. An llm.complete Operation exposes usage as token counts only: input, output, cacheRead, cacheWrite, totalTokens, and optional cacheWrite1h and reasoning. Counts that are unavailable or invalid are omitted; absent usage is omitted. Supplier SDK cost is not exposed. Customer fees are available from the Billing usage APIs. A failed or interrupted llm.complete Operation has error {code, message, details?} with fixed text only; model_provider_failed carries details.provider (category, httpStatus, errorType, errorCode); other failures use runtime_error or a ledger outcome code. Any other failed, interrupted or unknown_result Operation with an error, including tool Operations, has error {code, message, details} with fixed text naming only the tool: an intentional tool code (for example mcp_unavailable or validation_error) is kept; an allow-listed web_search_* or session_recall_* reason becomes the code and is repeated as details.code with a boolean details.retryable; anything else reads tool_failed. A memory.recall Operation keeps only memory_recall_failed, turn_interrupted or operation_result_unknown, and otherwise reads tool_failed. details also carries tool, category (rejected, unavailable, remote_error, failed, unknown_result, interrupted or unexpected) and, when known, dispatch and retryContract." }, "resultPointer": { "type": "object", "additionalProperties": {} }, "createdAt": { "type": "string" }, "completedAt": { "type": "string" } }, "required": [ "id", "sessionId", "turnId", "scope", "kind", "backend", "targetKind", "mediator", "status", "input", "resultPointer", "createdAt" ] } }, "assistantMessage": { "type": "object", "properties": { "id": { "type": "string" }, "sessionId": { "type": "string" }, "turnId": { "type": "string" }, "role": { "type": "string", "enum": [ "user", "assistant" ] }, "content": { "type": "string" }, "createdAt": { "type": "string" }, "inputContext": { "description": "Server-recorded channel of a user input; clients cannot set it. Present on user Messages except Scheduler-triggered Turns and Messages saved before it existed; absent on assistant Messages. Tolerate channel values added later.", "oneOf": [ { "type": "object", "properties": { "channel": { "type": "string", "enum": [ "text" ] } }, "required": [ "channel" ] }, { "type": "object", "properties": { "channel": { "type": "string", "enum": [ "audio" ] }, "utterance": { "description": "Transcript of the user's own speech when the Message content is a task delegated from it.", "type": "string", "minLength": 1, "maxLength": 8000 }, "emotion": { "description": "Emotion the Realtime model perceived in the speech; not a verified fact.", "type": "object", "properties": { "label": { "type": "string", "minLength": 1, "maxLength": 64 }, "confidence": { "type": "number", "minimum": 0, "exclusiveMinimum": false, "maximum": 1, "exclusiveMaximum": false }, "source": { "type": "string", "enum": [ "realtime_model" ] } }, "required": [ "label", "confidence", "source" ] }, "realtimeSummary": { "description": "Legacy field on Messages saved by earlier releases; new Messages omit it. The Realtime model's own summary of the preceding voice conversation; model-written, not a durable transcript.", "type": "string", "minLength": 1, "maxLength": 8000 } }, "required": [ "channel" ] }, { "description": "A Realtime Standing Task cycle: the platform started this Turn with the Template's standing goal while a Realtime Connection was live; nobody typed or spoke it.", "type": "object", "properties": { "channel": { "type": "string", "enum": [ "standing_task" ] } }, "required": [ "channel" ] } ] }, "realtime": { "oneOf": [ { "type": "object", "properties": { "startsTurn": { "type": "boolean" }, "linkedTurnId": { "type": "string", "nullable": true } }, "required": [ "startsTurn", "linkedTurnId" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "chat", "task_ack", "task_progress", "task_result", "clarify", "device_ack" ] }, "interrupted": { "description": "The reply was interrupted; its transcript may include speech the user did not hear.", "type": "boolean" }, "responseId": { "type": "string", "nullable": true }, "linkedTurnId": { "type": "string", "nullable": true } }, "required": [ "kind", "interrupted", "responseId", "linkedTurnId" ] } ] } }, "required": [ "id", "sessionId", "turnId", "role", "content", "createdAt" ], "nullable": true }, "clarificationItem": { "description": "A structured blocking question and its optional persisted response.", "oneOf": [ { "type": "object", "properties": { "prompt": { "type": "string" }, "selectionMode": { "description": "Requires exactly one answer and two or three mutually exclusive candidates.", "type": "string", "enum": [ "single" ] }, "answerChoices": { "description": "Candidate display order is also the canonical structured-answer order.", "type": "array", "minItems": 2, "maxItems": 3, "items": { "type": "string", "minLength": 1 } }, "response": { "type": "object", "properties": { "responseTurnId": { "type": "string" }, "answers": { "description": "The single structured answer.", "type": "array", "items": { "type": "string", "minLength": 1 } } }, "required": [ "responseTurnId", "answers" ] } }, "required": [ "prompt", "selectionMode", "answerChoices" ] }, { "type": "object", "properties": { "prompt": { "type": "string" }, "selectionMode": { "description": "Accepts a non-empty selection containing candidate values and/or at most one user-supplied value, with two through eight compatible candidates.", "type": "string", "enum": [ "multiple" ] }, "answerChoices": { "description": "Candidate display order is also the canonical structured-answer order.", "type": "array", "minItems": 2, "maxItems": 8, "items": { "type": "string", "minLength": 1 } }, "response": { "type": "object", "properties": { "responseTurnId": { "type": "string" }, "answers": { "description": "Distinct structured values in candidate display order, followed by at most one user-supplied answer.", "type": "array", "minItems": 1, "maxItems": 9, "items": { "type": "string", "minLength": 1 } } }, "required": [ "responseTurnId", "answers" ] } }, "required": [ "prompt", "selectionMode", "answerChoices" ] } ] }, "createdAt": { "type": "string" }, "completedAt": { "type": "string" }, "sourceFireId": { "type": "string", "nullable": true }, "failure": { "description": "A failed Turn's saved turn_error payload, identical to its turn_error event.", "type": "object", "properties": { "code": { "description": "service_configuration_unavailable, model_provider_failed, runtime_error or another stable failure code.", "type": "string" }, "message": { "description": "Fixed text for the code; never supplier or internal error text.", "type": "string" }, "details": { "type": "object", "properties": { "reason": { "description": "With service_configuration_unavailable: the missing service.", "type": "string", "enum": [ "model_provider_unconfigured", "sandbox_unconfigured", "drive9_unconfigured", "drive9_disabled_for_organization" ] }, "provider": { "description": "With model_provider_failed: the failure category, supplier HTTP status and supplier error type and code. Never supplier message text, request paths or credentials.", "type": "object", "properties": { "category": { "type": "string", "enum": [ "authentication", "supplier_error", "supplier_unavailable", "network", "provider_stream_error" ] }, "httpStatus": { "type": "integer", "nullable": true }, "errorType": { "type": "string", "nullable": true }, "errorCode": { "type": "string", "nullable": true } }, "required": [ "category", "httpStatus", "errorType", "errorCode" ] }, "registrations": { "description": "Each referenced registration whose authorization is not usable, by serverId.", "type": "array", "minItems": 1, "items": { "type": "object", "properties": { "serverId": { "description": "The MCP Server Registration that needs authorization.", "type": "string" }, "owner": { "description": "Who must authorize it: the Organization, or the Session End User.", "type": "string", "enum": [ "organization", "end_user" ] }, "reason": { "description": "missing: no usable authorization with a catalog exists; invalid: it was invalidated by an endpoint or mode change, or the server refused its credential with HTTP 401 or 403 during a Turn; revoked: its credential was revoked; insufficient_scope: the server answered 403 insufficient_scope, requiring a scope it lacks.", "type": "string", "enum": [ "missing", "invalid", "revoked", "insufficient_scope" ] } }, "required": [ "serverId", "owner", "reason" ] } } } } }, "required": [ "code", "message" ] } }, "required": [ "id", "sessionId", "status", "billingTag", "agentTemplateId", "userMessage", "userMessages", "operations", "assistantMessage", "createdAt" ] }, { "type": "object", "properties": { "executor": { "type": "string", "enum": [ "full_agent" ] }, "id": { "type": "string" }, "sessionId": { "type": "string" }, "status": { "type": "string", "enum": [ "running", "succeeded", "failed", "interrupted" ] }, "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" } ] }, "agentTemplateId": { "type": "string" }, "userMessages": { "type": "array", "maxItems": 0, "items": { "type": "object", "properties": { "id": { "type": "string" }, "sessionId": { "type": "string" }, "turnId": { "type": "string" }, "role": { "type": "string", "enum": [ "user", "assistant" ] }, "content": { "type": "string" }, "createdAt": { "type": "string" }, "inputContext": { "description": "Server-recorded channel of a user input; clients cannot set it. Present on user Messages except Scheduler-triggered Turns and Messages saved before it existed; absent on assistant Messages. Tolerate channel values added later.", "oneOf": [ { "type": "object", "properties": { "channel": { "type": "string", "enum": [ "text" ] } }, "required": [ "channel" ] }, { "type": "object", "properties": { "channel": { "type": "string", "enum": [ "audio" ] }, "utterance": { "description": "Transcript of the user's own speech when the Message content is a task delegated from it.", "type": "string", "minLength": 1, "maxLength": 8000 }, "emotion": { "description": "Emotion the Realtime model perceived in the speech; not a verified fact.", "type": "object", "properties": { "label": { "type": "string", "minLength": 1, "maxLength": 64 }, "confidence": { "type": "number", "minimum": 0, "exclusiveMinimum": false, "maximum": 1, "exclusiveMaximum": false }, "source": { "type": "string", "enum": [ "realtime_model" ] } }, "required": [ "label", "confidence", "source" ] }, "realtimeSummary": { "description": "Legacy field on Messages saved by earlier releases; new Messages omit it. The Realtime model's own summary of the preceding voice conversation; model-written, not a durable transcript.", "type": "string", "minLength": 1, "maxLength": 8000 } }, "required": [ "channel" ] }, { "description": "A Realtime Standing Task cycle: the platform started this Turn with the Template's standing goal while a Realtime Connection was live; nobody typed or spoke it.", "type": "object", "properties": { "channel": { "type": "string", "enum": [ "standing_task" ] } }, "required": [ "channel" ] } ] }, "realtime": { "oneOf": [ { "type": "object", "properties": { "startsTurn": { "type": "boolean" }, "linkedTurnId": { "type": "string", "nullable": true } }, "required": [ "startsTurn", "linkedTurnId" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "chat", "task_ack", "task_progress", "task_result", "clarify", "device_ack" ] }, "interrupted": { "description": "The reply was interrupted; its transcript may include speech the user did not hear.", "type": "boolean" }, "responseId": { "type": "string", "nullable": true }, "linkedTurnId": { "type": "string", "nullable": true } }, "required": [ "kind", "interrupted", "responseId", "linkedTurnId" ] } ] } }, "required": [ "id", "sessionId", "turnId", "role", "content", "createdAt" ] } }, "operations": { "description": "Operations performed by the Turn. drive.commit is recorded only after a workspace tool attempt.", "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "sessionId": { "type": "string" }, "turnId": { "type": "string" }, "scope": { "type": "object", "additionalProperties": {} }, "kind": { "type": "string" }, "backend": { "type": "string" }, "targetKind": { "type": "string" }, "mediator": { "type": "string", "enum": [ "aos" ] }, "status": { "type": "string", "enum": [ "running", "succeeded", "failed", "interrupted", "unknown_result" ] }, "category": { "description": "How to group a tool Operation: skill_read when it reads a file inside one of its AgentRun's frozen Skill packages, whether Runtime loaded the Skill instructions or the model read a package file; tool_call for every other tool Operation. Absent on non-tool Operations such as llm.complete and on metadata-only Operations.", "type": "string", "enum": [ "tool_call", "skill_read" ] }, "skill": { "description": "The Skill a skill_read Operation read from; present only with category skill_read.", "type": "object", "properties": { "skillId": { "type": "string" }, "name": { "type": "string" } }, "required": [ "skillId", "name" ] }, "source": { "description": "Client Tool source: session_client for every new call. Hardware sources appear only on calls recorded before native Hardware retired and expose the Session binding or requirement identifier and original method. Private device and Registration identities are omitted. Absent on metadata-only Operations. Current reads default older Session-client Operations to session_client; persisted historical progress events may omit source.", "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "session_client" ] } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "hardware" ] }, "method": { "type": "string", "pattern": "^[a-zA-Z0-9_-]{1,64}$" }, "hardwareRequirementId": { "type": "string", "pattern": "^[a-z][a-z0-9_.-]{0,99}$" } }, "required": [ "type", "method", "hardwareRequirementId" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "hardware" ] }, "method": { "type": "string", "pattern": "^[a-zA-Z0-9_-]{1,64}$" }, "hardwareBindingId": { "type": "string", "pattern": "^hbind_[0-9a-f]{32}$" } }, "required": [ "type", "method", "hardwareBindingId" ] } ] }, "label": { "description": "Readable label of a historical Hardware Client Tool, for example Speaker · set_volume. Absent on metadata-only Operations.", "type": "string", "maxLength": 322 }, "input": { "description": "Kind-specific input. A tool Operation has toolName and args; a historical Hardware Client Tool exposes only toolName, callId and mode, omitting device arguments. Neither input nor output carries the model supplier's tool-call id; use the Operation id to identify a tool call and its result." }, "output": { "description": "Kind-specific result. Hardware Client Tool Operations, recorded before native Hardware retired, omit output in every status. An llm.complete Operation exposes usage as token counts only: input, output, cacheRead, cacheWrite, totalTokens, and optional cacheWrite1h and reasoning. Counts that are unavailable or invalid are omitted; absent usage is omitted. Supplier SDK cost is not exposed. Customer fees are available from the Billing usage APIs. A failed or interrupted llm.complete Operation has error {code, message, details?} with fixed text only; model_provider_failed carries details.provider (category, httpStatus, errorType, errorCode); other failures use runtime_error or a ledger outcome code. Any other failed, interrupted or unknown_result Operation with an error, including tool Operations, has error {code, message, details} with fixed text naming only the tool: an intentional tool code (for example mcp_unavailable or validation_error) is kept; an allow-listed web_search_* or session_recall_* reason becomes the code and is repeated as details.code with a boolean details.retryable; anything else reads tool_failed. A memory.recall Operation keeps only memory_recall_failed, turn_interrupted or operation_result_unknown, and otherwise reads tool_failed. details also carries tool, category (rejected, unavailable, remote_error, failed, unknown_result, interrupted or unexpected) and, when known, dispatch and retryContract." }, "resultPointer": { "type": "object", "additionalProperties": {} }, "createdAt": { "type": "string" }, "completedAt": { "type": "string" } }, "required": [ "id", "sessionId", "turnId", "scope", "kind", "backend", "targetKind", "mediator", "status", "input", "resultPointer", "createdAt" ] } }, "assistantMessage": { "type": "object", "properties": { "id": { "type": "string" }, "sessionId": { "type": "string" }, "turnId": { "type": "string" }, "role": { "type": "string", "enum": [ "user", "assistant" ] }, "content": { "type": "string" }, "createdAt": { "type": "string" }, "inputContext": { "description": "Server-recorded channel of a user input; clients cannot set it. Present on user Messages except Scheduler-triggered Turns and Messages saved before it existed; absent on assistant Messages. Tolerate channel values added later.", "oneOf": [ { "type": "object", "properties": { "channel": { "type": "string", "enum": [ "text" ] } }, "required": [ "channel" ] }, { "type": "object", "properties": { "channel": { "type": "string", "enum": [ "audio" ] }, "utterance": { "description": "Transcript of the user's own speech when the Message content is a task delegated from it.", "type": "string", "minLength": 1, "maxLength": 8000 }, "emotion": { "description": "Emotion the Realtime model perceived in the speech; not a verified fact.", "type": "object", "properties": { "label": { "type": "string", "minLength": 1, "maxLength": 64 }, "confidence": { "type": "number", "minimum": 0, "exclusiveMinimum": false, "maximum": 1, "exclusiveMaximum": false }, "source": { "type": "string", "enum": [ "realtime_model" ] } }, "required": [ "label", "confidence", "source" ] }, "realtimeSummary": { "description": "Legacy field on Messages saved by earlier releases; new Messages omit it. The Realtime model's own summary of the preceding voice conversation; model-written, not a durable transcript.", "type": "string", "minLength": 1, "maxLength": 8000 } }, "required": [ "channel" ] }, { "description": "A Realtime Standing Task cycle: the platform started this Turn with the Template's standing goal while a Realtime Connection was live; nobody typed or spoke it.", "type": "object", "properties": { "channel": { "type": "string", "enum": [ "standing_task" ] } }, "required": [ "channel" ] } ] }, "realtime": { "oneOf": [ { "type": "object", "properties": { "startsTurn": { "type": "boolean" }, "linkedTurnId": { "type": "string", "nullable": true } }, "required": [ "startsTurn", "linkedTurnId" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "chat", "task_ack", "task_progress", "task_result", "clarify", "device_ack" ] }, "interrupted": { "description": "The reply was interrupted; its transcript may include speech the user did not hear.", "type": "boolean" }, "responseId": { "type": "string", "nullable": true }, "linkedTurnId": { "type": "string", "nullable": true } }, "required": [ "kind", "interrupted", "responseId", "linkedTurnId" ] } ] } }, "required": [ "id", "sessionId", "turnId", "role", "content", "createdAt" ], "nullable": true }, "createdAt": { "type": "string" }, "completedAt": { "type": "string" }, "failure": { "description": "A failed Turn's saved turn_error payload, identical to its turn_error event.", "type": "object", "properties": { "code": { "description": "service_configuration_unavailable, model_provider_failed, runtime_error or another stable failure code.", "type": "string" }, "message": { "description": "Fixed text for the code; never supplier or internal error text.", "type": "string" }, "details": { "type": "object", "properties": { "reason": { "description": "With service_configuration_unavailable: the missing service.", "type": "string", "enum": [ "model_provider_unconfigured", "sandbox_unconfigured", "drive9_unconfigured", "drive9_disabled_for_organization" ] }, "provider": { "description": "With model_provider_failed: the failure category, supplier HTTP status and supplier error type and code. Never supplier message text, request paths or credentials.", "type": "object", "properties": { "category": { "type": "string", "enum": [ "authentication", "supplier_error", "supplier_unavailable", "network", "provider_stream_error" ] }, "httpStatus": { "type": "integer", "nullable": true }, "errorType": { "type": "string", "nullable": true }, "errorCode": { "type": "string", "nullable": true } }, "required": [ "category", "httpStatus", "errorType", "errorCode" ] }, "registrations": { "description": "Each referenced registration whose authorization is not usable, by serverId.", "type": "array", "minItems": 1, "items": { "type": "object", "properties": { "serverId": { "description": "The MCP Server Registration that needs authorization.", "type": "string" }, "owner": { "description": "Who must authorize it: the Organization, or the Session End User.", "type": "string", "enum": [ "organization", "end_user" ] }, "reason": { "description": "missing: no usable authorization with a catalog exists; invalid: it was invalidated by an endpoint or mode change, or the server refused its credential with HTTP 401 or 403 during a Turn; revoked: its credential was revoked; insufficient_scope: the server answered 403 insufficient_scope, requiring a scope it lacks.", "type": "string", "enum": [ "missing", "invalid", "revoked", "insufficient_scope" ] } }, "required": [ "serverId", "owner", "reason" ] } } } } }, "required": [ "code", "message" ] }, "kind": { "type": "string", "enum": [ "template_handoff" ] } }, "required": [ "id", "sessionId", "status", "billingTag", "agentTemplateId", "userMessages", "operations", "assistantMessage", "createdAt", "kind" ] } ] } }, "required": [ "type", "turn" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "realtime" ] }, "realtime": { "description": "A durable Realtime fact of the Session timeline. It is never a Turn, Message or task result.", "oneOf": [ { "description": "A final user transcript received through a Realtime connection.", "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "input_transcript" ] }, "realtimeConnectionId": { "type": "string" }, "text": { "type": "string" }, "turnId": { "description": "The Turn this utterance started or steered; null when the Realtime model answered it alone.", "type": "string", "nullable": true }, "createdAt": { "type": "string" } }, "required": [ "id", "type", "realtimeConnectionId", "text", "turnId", "createdAt" ] }, { "description": "One completed Realtime model response.", "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "response" ] }, "realtimeConnectionId": { "type": "string" }, "responseId": { "description": "The realtime protocol response_id when audio was produced, to replace live partial transcripts.", "type": "string", "nullable": true }, "kind": { "type": "string", "enum": [ "chat", "task_ack", "task_progress", "task_result", "clarify", "device_ack" ] }, "text": { "description": "The transcript of the Realtime model output.", "type": "string" }, "turnId": { "description": "The Turn this response speaks about: set for task_ack, task_progress, task_result and clarify.", "type": "string", "nullable": true }, "interrupted": { "description": "The response was cut off; its text may include speech the user did not hear.", "type": "boolean" }, "createdAt": { "type": "string" } }, "required": [ "id", "type", "realtimeConnectionId", "responseId", "kind", "text", "turnId", "interrupted", "createdAt" ] } ] } }, "required": [ "type", "realtime" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "template_switch" ] }, "templateSwitch": { "type": "object", "properties": { "id": { "type": "string" }, "commandId": { "type": "string" }, "status": { "type": "string", "enum": [ "succeeded" ] }, "configurationEpoch": { "type": "integer", "minimum": 2, "exclusiveMinimum": false }, "agentTemplateId": { "type": "string" }, "contentDigest": { "type": "string" }, "createdAt": { "type": "string" } }, "required": [ "id", "commandId", "status", "configurationEpoch", "agentTemplateId", "contentDigest", "createdAt" ] } }, "required": [ "type", "templateSwitch" ] } ] } }, "hasMore": { "type": "boolean" }, "nextCursor": { "type": "string", "nullable": true } }, "required": [ "entries", "hasMore", "nextCursor" ]}schemas/TurnsResponseOpenApiDto
Section titled “schemas/TurnsResponseOpenApiDto”{ "type": "object", "properties": { "turns": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "executor": { "type": "string", "enum": [ "full_agent", "realtime_model" ] }, "realtime": { "type": "object", "properties": { "connectionId": { "type": "string" }, "linkedTurnIds": { "type": "array", "items": { "type": "string" } } }, "required": [ "connectionId", "linkedTurnIds" ] }, "realtimeResponses": { "description": "Narration-only Realtime responses about this Full Agent Turn, in Session sequence order.", "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "sessionId": { "type": "string" }, "turnId": { "type": "string" }, "role": { "type": "string", "enum": [ "user", "assistant" ] }, "content": { "type": "string" }, "createdAt": { "type": "string" }, "inputContext": { "description": "Server-recorded channel of a user input; clients cannot set it. Present on user Messages except Scheduler-triggered Turns and Messages saved before it existed; absent on assistant Messages. Tolerate channel values added later.", "oneOf": [ { "type": "object", "properties": { "channel": { "type": "string", "enum": [ "text" ] } }, "required": [ "channel" ] }, { "type": "object", "properties": { "channel": { "type": "string", "enum": [ "audio" ] }, "utterance": { "description": "Transcript of the user's own speech when the Message content is a task delegated from it.", "type": "string", "minLength": 1, "maxLength": 8000 }, "emotion": { "description": "Emotion the Realtime model perceived in the speech; not a verified fact.", "type": "object", "properties": { "label": { "type": "string", "minLength": 1, "maxLength": 64 }, "confidence": { "type": "number", "minimum": 0, "exclusiveMinimum": false, "maximum": 1, "exclusiveMaximum": false }, "source": { "type": "string", "enum": [ "realtime_model" ] } }, "required": [ "label", "confidence", "source" ] }, "realtimeSummary": { "description": "Legacy field on Messages saved by earlier releases; new Messages omit it. The Realtime model's own summary of the preceding voice conversation; model-written, not a durable transcript.", "type": "string", "minLength": 1, "maxLength": 8000 } }, "required": [ "channel" ] }, { "description": "A Realtime Standing Task cycle: the platform started this Turn with the Template's standing goal while a Realtime Connection was live; nobody typed or spoke it.", "type": "object", "properties": { "channel": { "type": "string", "enum": [ "standing_task" ] } }, "required": [ "channel" ] } ] }, "realtime": { "oneOf": [ { "type": "object", "properties": { "startsTurn": { "type": "boolean" }, "linkedTurnId": { "type": "string", "nullable": true } }, "required": [ "startsTurn", "linkedTurnId" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "chat", "task_ack", "task_progress", "task_result", "clarify", "device_ack" ] }, "interrupted": { "description": "The reply was interrupted; its transcript may include speech the user did not hear.", "type": "boolean" }, "responseId": { "type": "string", "nullable": true }, "linkedTurnId": { "type": "string", "nullable": true } }, "required": [ "kind", "interrupted", "responseId", "linkedTurnId" ] } ] } }, "required": [ "id", "sessionId", "turnId", "role", "content", "createdAt" ] } }, "id": { "type": "string" }, "sessionId": { "type": "string" }, "status": { "type": "string", "enum": [ "running", "succeeded", "failed", "interrupted" ] }, "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" } ] }, "agentTemplateId": { "description": "AgentTemplate frozen when the Turn was admitted.", "type": "string", "nullable": true }, "userMessage": { "type": "object", "properties": { "id": { "type": "string" }, "sessionId": { "type": "string" }, "turnId": { "type": "string" }, "role": { "type": "string", "enum": [ "user", "assistant" ] }, "content": { "type": "string" }, "createdAt": { "type": "string" }, "inputContext": { "description": "Server-recorded channel of a user input; clients cannot set it. Present on user Messages except Scheduler-triggered Turns and Messages saved before it existed; absent on assistant Messages. Tolerate channel values added later.", "oneOf": [ { "type": "object", "properties": { "channel": { "type": "string", "enum": [ "text" ] } }, "required": [ "channel" ] }, { "type": "object", "properties": { "channel": { "type": "string", "enum": [ "audio" ] }, "utterance": { "description": "Transcript of the user's own speech when the Message content is a task delegated from it.", "type": "string", "minLength": 1, "maxLength": 8000 }, "emotion": { "description": "Emotion the Realtime model perceived in the speech; not a verified fact.", "type": "object", "properties": { "label": { "type": "string", "minLength": 1, "maxLength": 64 }, "confidence": { "type": "number", "minimum": 0, "exclusiveMinimum": false, "maximum": 1, "exclusiveMaximum": false }, "source": { "type": "string", "enum": [ "realtime_model" ] } }, "required": [ "label", "confidence", "source" ] }, "realtimeSummary": { "description": "Legacy field on Messages saved by earlier releases; new Messages omit it. The Realtime model's own summary of the preceding voice conversation; model-written, not a durable transcript.", "type": "string", "minLength": 1, "maxLength": 8000 } }, "required": [ "channel" ] }, { "description": "A Realtime Standing Task cycle: the platform started this Turn with the Template's standing goal while a Realtime Connection was live; nobody typed or spoke it.", "type": "object", "properties": { "channel": { "type": "string", "enum": [ "standing_task" ] } }, "required": [ "channel" ] } ] }, "realtime": { "oneOf": [ { "type": "object", "properties": { "startsTurn": { "type": "boolean" }, "linkedTurnId": { "type": "string", "nullable": true } }, "required": [ "startsTurn", "linkedTurnId" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "chat", "task_ack", "task_progress", "task_result", "clarify", "device_ack" ] }, "interrupted": { "description": "The reply was interrupted; its transcript may include speech the user did not hear.", "type": "boolean" }, "responseId": { "type": "string", "nullable": true }, "linkedTurnId": { "type": "string", "nullable": true } }, "required": [ "kind", "interrupted", "responseId", "linkedTurnId" ] } ] } }, "required": [ "id", "sessionId", "turnId", "role", "content", "createdAt" ] }, "userMessages": { "description": "Canonical admitted user Messages in input order; includes accepted inputs interrupted before incorporation.", "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "sessionId": { "type": "string" }, "turnId": { "type": "string" }, "role": { "type": "string", "enum": [ "user", "assistant" ] }, "content": { "type": "string" }, "createdAt": { "type": "string" }, "inputContext": { "description": "Server-recorded channel of a user input; clients cannot set it. Present on user Messages except Scheduler-triggered Turns and Messages saved before it existed; absent on assistant Messages. Tolerate channel values added later.", "oneOf": [ { "type": "object", "properties": { "channel": { "type": "string", "enum": [ "text" ] } }, "required": [ "channel" ] }, { "type": "object", "properties": { "channel": { "type": "string", "enum": [ "audio" ] }, "utterance": { "description": "Transcript of the user's own speech when the Message content is a task delegated from it.", "type": "string", "minLength": 1, "maxLength": 8000 }, "emotion": { "description": "Emotion the Realtime model perceived in the speech; not a verified fact.", "type": "object", "properties": { "label": { "type": "string", "minLength": 1, "maxLength": 64 }, "confidence": { "type": "number", "minimum": 0, "exclusiveMinimum": false, "maximum": 1, "exclusiveMaximum": false }, "source": { "type": "string", "enum": [ "realtime_model" ] } }, "required": [ "label", "confidence", "source" ] }, "realtimeSummary": { "description": "Legacy field on Messages saved by earlier releases; new Messages omit it. The Realtime model's own summary of the preceding voice conversation; model-written, not a durable transcript.", "type": "string", "minLength": 1, "maxLength": 8000 } }, "required": [ "channel" ] }, { "description": "A Realtime Standing Task cycle: the platform started this Turn with the Template's standing goal while a Realtime Connection was live; nobody typed or spoke it.", "type": "object", "properties": { "channel": { "type": "string", "enum": [ "standing_task" ] } }, "required": [ "channel" ] } ] }, "realtime": { "oneOf": [ { "type": "object", "properties": { "startsTurn": { "type": "boolean" }, "linkedTurnId": { "type": "string", "nullable": true } }, "required": [ "startsTurn", "linkedTurnId" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "chat", "task_ack", "task_progress", "task_result", "clarify", "device_ack" ] }, "interrupted": { "description": "The reply was interrupted; its transcript may include speech the user did not hear.", "type": "boolean" }, "responseId": { "type": "string", "nullable": true }, "linkedTurnId": { "type": "string", "nullable": true } }, "required": [ "kind", "interrupted", "responseId", "linkedTurnId" ] } ] } }, "required": [ "id", "sessionId", "turnId", "role", "content", "createdAt" ] } }, "userFiles": { "type": "array", "items": { "type": "object", "properties": { "turnId": { "type": "string" }, "sessionId": { "type": "string" }, "organizationId": { "type": "string" }, "userFileId": { "type": "string" }, "ordinal": { "type": "integer" }, "originalName": { "type": "string" }, "safeName": { "type": "string" }, "drivePath": { "type": "string" }, "byteSize": { "type": "integer" }, "sha256": { "type": "string" }, "checksumVerification": { "description": "Verified fact for a ready file; null until settlement. whole verifies the complete file, while part_only verifies every multipart part.", "type": "string", "enum": [ "whole", "part_only" ], "nullable": true }, "contentType": { "type": "string", "nullable": true }, "createdAt": { "type": "string" } }, "required": [ "turnId", "sessionId", "organizationId", "userFileId", "ordinal", "originalName", "safeName", "drivePath", "byteSize", "sha256", "checksumVerification", "contentType", "createdAt" ] } }, "operations": { "description": "Operations performed by the Turn. drive.commit is recorded only after a workspace tool attempt.", "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "sessionId": { "type": "string" }, "turnId": { "type": "string" }, "scope": { "type": "object", "additionalProperties": {} }, "kind": { "type": "string" }, "backend": { "type": "string" }, "targetKind": { "type": "string" }, "mediator": { "type": "string", "enum": [ "aos" ] }, "status": { "type": "string", "enum": [ "running", "succeeded", "failed", "interrupted", "unknown_result" ] }, "category": { "description": "How to group a tool Operation: skill_read when it reads a file inside one of its AgentRun's frozen Skill packages, whether Runtime loaded the Skill instructions or the model read a package file; tool_call for every other tool Operation. Absent on non-tool Operations such as llm.complete and on metadata-only Operations.", "type": "string", "enum": [ "tool_call", "skill_read" ] }, "skill": { "description": "The Skill a skill_read Operation read from; present only with category skill_read.", "type": "object", "properties": { "skillId": { "type": "string" }, "name": { "type": "string" } }, "required": [ "skillId", "name" ] }, "source": { "description": "Client Tool source: session_client for every new call. Hardware sources appear only on calls recorded before native Hardware retired and expose the Session binding or requirement identifier and original method. Private device and Registration identities are omitted. Absent on metadata-only Operations. Current reads default older Session-client Operations to session_client; persisted historical progress events may omit source.", "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "session_client" ] } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "hardware" ] }, "method": { "type": "string", "pattern": "^[a-zA-Z0-9_-]{1,64}$" }, "hardwareRequirementId": { "type": "string", "pattern": "^[a-z][a-z0-9_.-]{0,99}$" } }, "required": [ "type", "method", "hardwareRequirementId" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "hardware" ] }, "method": { "type": "string", "pattern": "^[a-zA-Z0-9_-]{1,64}$" }, "hardwareBindingId": { "type": "string", "pattern": "^hbind_[0-9a-f]{32}$" } }, "required": [ "type", "method", "hardwareBindingId" ] } ] }, "label": { "description": "Readable label of a historical Hardware Client Tool, for example Speaker · set_volume. Absent on metadata-only Operations.", "type": "string", "maxLength": 322 }, "input": { "description": "Kind-specific input. A tool Operation has toolName and args; a historical Hardware Client Tool exposes only toolName, callId and mode, omitting device arguments. Neither input nor output carries the model supplier's tool-call id; use the Operation id to identify a tool call and its result." }, "output": { "description": "Kind-specific result. Hardware Client Tool Operations, recorded before native Hardware retired, omit output in every status. An llm.complete Operation exposes usage as token counts only: input, output, cacheRead, cacheWrite, totalTokens, and optional cacheWrite1h and reasoning. Counts that are unavailable or invalid are omitted; absent usage is omitted. Supplier SDK cost is not exposed. Customer fees are available from the Billing usage APIs. A failed or interrupted llm.complete Operation has error {code, message, details?} with fixed text only; model_provider_failed carries details.provider (category, httpStatus, errorType, errorCode); other failures use runtime_error or a ledger outcome code. Any other failed, interrupted or unknown_result Operation with an error, including tool Operations, has error {code, message, details} with fixed text naming only the tool: an intentional tool code (for example mcp_unavailable or validation_error) is kept; an allow-listed web_search_* or session_recall_* reason becomes the code and is repeated as details.code with a boolean details.retryable; anything else reads tool_failed. A memory.recall Operation keeps only memory_recall_failed, turn_interrupted or operation_result_unknown, and otherwise reads tool_failed. details also carries tool, category (rejected, unavailable, remote_error, failed, unknown_result, interrupted or unexpected) and, when known, dispatch and retryContract." }, "resultPointer": { "type": "object", "additionalProperties": {} }, "createdAt": { "type": "string" }, "completedAt": { "type": "string" } }, "required": [ "id", "sessionId", "turnId", "scope", "kind", "backend", "targetKind", "mediator", "status", "input", "resultPointer", "createdAt" ] } }, "assistantMessage": { "type": "object", "properties": { "id": { "type": "string" }, "sessionId": { "type": "string" }, "turnId": { "type": "string" }, "role": { "type": "string", "enum": [ "user", "assistant" ] }, "content": { "type": "string" }, "createdAt": { "type": "string" }, "inputContext": { "description": "Server-recorded channel of a user input; clients cannot set it. Present on user Messages except Scheduler-triggered Turns and Messages saved before it existed; absent on assistant Messages. Tolerate channel values added later.", "oneOf": [ { "type": "object", "properties": { "channel": { "type": "string", "enum": [ "text" ] } }, "required": [ "channel" ] }, { "type": "object", "properties": { "channel": { "type": "string", "enum": [ "audio" ] }, "utterance": { "description": "Transcript of the user's own speech when the Message content is a task delegated from it.", "type": "string", "minLength": 1, "maxLength": 8000 }, "emotion": { "description": "Emotion the Realtime model perceived in the speech; not a verified fact.", "type": "object", "properties": { "label": { "type": "string", "minLength": 1, "maxLength": 64 }, "confidence": { "type": "number", "minimum": 0, "exclusiveMinimum": false, "maximum": 1, "exclusiveMaximum": false }, "source": { "type": "string", "enum": [ "realtime_model" ] } }, "required": [ "label", "confidence", "source" ] }, "realtimeSummary": { "description": "Legacy field on Messages saved by earlier releases; new Messages omit it. The Realtime model's own summary of the preceding voice conversation; model-written, not a durable transcript.", "type": "string", "minLength": 1, "maxLength": 8000 } }, "required": [ "channel" ] }, { "description": "A Realtime Standing Task cycle: the platform started this Turn with the Template's standing goal while a Realtime Connection was live; nobody typed or spoke it.", "type": "object", "properties": { "channel": { "type": "string", "enum": [ "standing_task" ] } }, "required": [ "channel" ] } ] }, "realtime": { "oneOf": [ { "type": "object", "properties": { "startsTurn": { "type": "boolean" }, "linkedTurnId": { "type": "string", "nullable": true } }, "required": [ "startsTurn", "linkedTurnId" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "chat", "task_ack", "task_progress", "task_result", "clarify", "device_ack" ] }, "interrupted": { "description": "The reply was interrupted; its transcript may include speech the user did not hear.", "type": "boolean" }, "responseId": { "type": "string", "nullable": true }, "linkedTurnId": { "type": "string", "nullable": true } }, "required": [ "kind", "interrupted", "responseId", "linkedTurnId" ] } ] } }, "required": [ "id", "sessionId", "turnId", "role", "content", "createdAt" ], "nullable": true }, "clarificationItem": { "description": "A structured blocking question and its optional persisted response.", "oneOf": [ { "type": "object", "properties": { "prompt": { "type": "string" }, "selectionMode": { "description": "Requires exactly one answer and two or three mutually exclusive candidates.", "type": "string", "enum": [ "single" ] }, "answerChoices": { "description": "Candidate display order is also the canonical structured-answer order.", "type": "array", "minItems": 2, "maxItems": 3, "items": { "type": "string", "minLength": 1 } }, "response": { "type": "object", "properties": { "responseTurnId": { "type": "string" }, "answers": { "description": "The single structured answer.", "type": "array", "items": { "type": "string", "minLength": 1 } } }, "required": [ "responseTurnId", "answers" ] } }, "required": [ "prompt", "selectionMode", "answerChoices" ] }, { "type": "object", "properties": { "prompt": { "type": "string" }, "selectionMode": { "description": "Accepts a non-empty selection containing candidate values and/or at most one user-supplied value, with two through eight compatible candidates.", "type": "string", "enum": [ "multiple" ] }, "answerChoices": { "description": "Candidate display order is also the canonical structured-answer order.", "type": "array", "minItems": 2, "maxItems": 8, "items": { "type": "string", "minLength": 1 } }, "response": { "type": "object", "properties": { "responseTurnId": { "type": "string" }, "answers": { "description": "Distinct structured values in candidate display order, followed by at most one user-supplied answer.", "type": "array", "minItems": 1, "maxItems": 9, "items": { "type": "string", "minLength": 1 } } }, "required": [ "responseTurnId", "answers" ] } }, "required": [ "prompt", "selectionMode", "answerChoices" ] } ] }, "createdAt": { "type": "string" }, "completedAt": { "type": "string" }, "sourceFireId": { "type": "string", "nullable": true }, "failure": { "description": "A failed Turn's saved turn_error payload, identical to its turn_error event.", "type": "object", "properties": { "code": { "description": "service_configuration_unavailable, model_provider_failed, runtime_error or another stable failure code.", "type": "string" }, "message": { "description": "Fixed text for the code; never supplier or internal error text.", "type": "string" }, "details": { "type": "object", "properties": { "reason": { "description": "With service_configuration_unavailable: the missing service.", "type": "string", "enum": [ "model_provider_unconfigured", "sandbox_unconfigured", "drive9_unconfigured", "drive9_disabled_for_organization" ] }, "provider": { "description": "With model_provider_failed: the failure category, supplier HTTP status and supplier error type and code. Never supplier message text, request paths or credentials.", "type": "object", "properties": { "category": { "type": "string", "enum": [ "authentication", "supplier_error", "supplier_unavailable", "network", "provider_stream_error" ] }, "httpStatus": { "type": "integer", "nullable": true }, "errorType": { "type": "string", "nullable": true }, "errorCode": { "type": "string", "nullable": true } }, "required": [ "category", "httpStatus", "errorType", "errorCode" ] }, "registrations": { "description": "Each referenced registration whose authorization is not usable, by serverId.", "type": "array", "minItems": 1, "items": { "type": "object", "properties": { "serverId": { "description": "The MCP Server Registration that needs authorization.", "type": "string" }, "owner": { "description": "Who must authorize it: the Organization, or the Session End User.", "type": "string", "enum": [ "organization", "end_user" ] }, "reason": { "description": "missing: no usable authorization with a catalog exists; invalid: it was invalidated by an endpoint or mode change, or the server refused its credential with HTTP 401 or 403 during a Turn; revoked: its credential was revoked; insufficient_scope: the server answered 403 insufficient_scope, requiring a scope it lacks.", "type": "string", "enum": [ "missing", "invalid", "revoked", "insufficient_scope" ] } }, "required": [ "serverId", "owner", "reason" ] } } } } }, "required": [ "code", "message" ] } }, "required": [ "executor", "id", "sessionId", "status", "billingTag", "agentTemplateId", "userMessage", "userMessages", "operations", "assistantMessage", "createdAt" ] }, { "type": "object", "properties": { "executor": { "type": "string", "enum": [ "full_agent" ] }, "id": { "type": "string" }, "sessionId": { "type": "string" }, "status": { "type": "string", "enum": [ "running", "succeeded", "failed", "interrupted" ] }, "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" } ] }, "agentTemplateId": { "type": "string" }, "userMessages": { "type": "array", "maxItems": 0, "items": { "type": "object", "properties": { "id": { "type": "string" }, "sessionId": { "type": "string" }, "turnId": { "type": "string" }, "role": { "type": "string", "enum": [ "user", "assistant" ] }, "content": { "type": "string" }, "createdAt": { "type": "string" }, "inputContext": { "description": "Server-recorded channel of a user input; clients cannot set it. Present on user Messages except Scheduler-triggered Turns and Messages saved before it existed; absent on assistant Messages. Tolerate channel values added later.", "oneOf": [ { "type": "object", "properties": { "channel": { "type": "string", "enum": [ "text" ] } }, "required": [ "channel" ] }, { "type": "object", "properties": { "channel": { "type": "string", "enum": [ "audio" ] }, "utterance": { "description": "Transcript of the user's own speech when the Message content is a task delegated from it.", "type": "string", "minLength": 1, "maxLength": 8000 }, "emotion": { "description": "Emotion the Realtime model perceived in the speech; not a verified fact.", "type": "object", "properties": { "label": { "type": "string", "minLength": 1, "maxLength": 64 }, "confidence": { "type": "number", "minimum": 0, "exclusiveMinimum": false, "maximum": 1, "exclusiveMaximum": false }, "source": { "type": "string", "enum": [ "realtime_model" ] } }, "required": [ "label", "confidence", "source" ] }, "realtimeSummary": { "description": "Legacy field on Messages saved by earlier releases; new Messages omit it. The Realtime model's own summary of the preceding voice conversation; model-written, not a durable transcript.", "type": "string", "minLength": 1, "maxLength": 8000 } }, "required": [ "channel" ] }, { "description": "A Realtime Standing Task cycle: the platform started this Turn with the Template's standing goal while a Realtime Connection was live; nobody typed or spoke it.", "type": "object", "properties": { "channel": { "type": "string", "enum": [ "standing_task" ] } }, "required": [ "channel" ] } ] }, "realtime": { "oneOf": [ { "type": "object", "properties": { "startsTurn": { "type": "boolean" }, "linkedTurnId": { "type": "string", "nullable": true } }, "required": [ "startsTurn", "linkedTurnId" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "chat", "task_ack", "task_progress", "task_result", "clarify", "device_ack" ] }, "interrupted": { "description": "The reply was interrupted; its transcript may include speech the user did not hear.", "type": "boolean" }, "responseId": { "type": "string", "nullable": true }, "linkedTurnId": { "type": "string", "nullable": true } }, "required": [ "kind", "interrupted", "responseId", "linkedTurnId" ] } ] } }, "required": [ "id", "sessionId", "turnId", "role", "content", "createdAt" ] } }, "operations": { "description": "Operations performed by the Turn. drive.commit is recorded only after a workspace tool attempt.", "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "sessionId": { "type": "string" }, "turnId": { "type": "string" }, "scope": { "type": "object", "additionalProperties": {} }, "kind": { "type": "string" }, "backend": { "type": "string" }, "targetKind": { "type": "string" }, "mediator": { "type": "string", "enum": [ "aos" ] }, "status": { "type": "string", "enum": [ "running", "succeeded", "failed", "interrupted", "unknown_result" ] }, "category": { "description": "How to group a tool Operation: skill_read when it reads a file inside one of its AgentRun's frozen Skill packages, whether Runtime loaded the Skill instructions or the model read a package file; tool_call for every other tool Operation. Absent on non-tool Operations such as llm.complete and on metadata-only Operations.", "type": "string", "enum": [ "tool_call", "skill_read" ] }, "skill": { "description": "The Skill a skill_read Operation read from; present only with category skill_read.", "type": "object", "properties": { "skillId": { "type": "string" }, "name": { "type": "string" } }, "required": [ "skillId", "name" ] }, "source": { "description": "Client Tool source: session_client for every new call. Hardware sources appear only on calls recorded before native Hardware retired and expose the Session binding or requirement identifier and original method. Private device and Registration identities are omitted. Absent on metadata-only Operations. Current reads default older Session-client Operations to session_client; persisted historical progress events may omit source.", "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "session_client" ] } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "hardware" ] }, "method": { "type": "string", "pattern": "^[a-zA-Z0-9_-]{1,64}$" }, "hardwareRequirementId": { "type": "string", "pattern": "^[a-z][a-z0-9_.-]{0,99}$" } }, "required": [ "type", "method", "hardwareRequirementId" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "hardware" ] }, "method": { "type": "string", "pattern": "^[a-zA-Z0-9_-]{1,64}$" }, "hardwareBindingId": { "type": "string", "pattern": "^hbind_[0-9a-f]{32}$" } }, "required": [ "type", "method", "hardwareBindingId" ] } ] }, "label": { "description": "Readable label of a historical Hardware Client Tool, for example Speaker · set_volume. Absent on metadata-only Operations.", "type": "string", "maxLength": 322 }, "input": { "description": "Kind-specific input. A tool Operation has toolName and args; a historical Hardware Client Tool exposes only toolName, callId and mode, omitting device arguments. Neither input nor output carries the model supplier's tool-call id; use the Operation id to identify a tool call and its result." }, "output": { "description": "Kind-specific result. Hardware Client Tool Operations, recorded before native Hardware retired, omit output in every status. An llm.complete Operation exposes usage as token counts only: input, output, cacheRead, cacheWrite, totalTokens, and optional cacheWrite1h and reasoning. Counts that are unavailable or invalid are omitted; absent usage is omitted. Supplier SDK cost is not exposed. Customer fees are available from the Billing usage APIs. A failed or interrupted llm.complete Operation has error {code, message, details?} with fixed text only; model_provider_failed carries details.provider (category, httpStatus, errorType, errorCode); other failures use runtime_error or a ledger outcome code. Any other failed, interrupted or unknown_result Operation with an error, including tool Operations, has error {code, message, details} with fixed text naming only the tool: an intentional tool code (for example mcp_unavailable or validation_error) is kept; an allow-listed web_search_* or session_recall_* reason becomes the code and is repeated as details.code with a boolean details.retryable; anything else reads tool_failed. A memory.recall Operation keeps only memory_recall_failed, turn_interrupted or operation_result_unknown, and otherwise reads tool_failed. details also carries tool, category (rejected, unavailable, remote_error, failed, unknown_result, interrupted or unexpected) and, when known, dispatch and retryContract." }, "resultPointer": { "type": "object", "additionalProperties": {} }, "createdAt": { "type": "string" }, "completedAt": { "type": "string" } }, "required": [ "id", "sessionId", "turnId", "scope", "kind", "backend", "targetKind", "mediator", "status", "input", "resultPointer", "createdAt" ] } }, "assistantMessage": { "type": "object", "properties": { "id": { "type": "string" }, "sessionId": { "type": "string" }, "turnId": { "type": "string" }, "role": { "type": "string", "enum": [ "user", "assistant" ] }, "content": { "type": "string" }, "createdAt": { "type": "string" }, "inputContext": { "description": "Server-recorded channel of a user input; clients cannot set it. Present on user Messages except Scheduler-triggered Turns and Messages saved before it existed; absent on assistant Messages. Tolerate channel values added later.", "oneOf": [ { "type": "object", "properties": { "channel": { "type": "string", "enum": [ "text" ] } }, "required": [ "channel" ] }, { "type": "object", "properties": { "channel": { "type": "string", "enum": [ "audio" ] }, "utterance": { "description": "Transcript of the user's own speech when the Message content is a task delegated from it.", "type": "string", "minLength": 1, "maxLength": 8000 }, "emotion": { "description": "Emotion the Realtime model perceived in the speech; not a verified fact.", "type": "object", "properties": { "label": { "type": "string", "minLength": 1, "maxLength": 64 }, "confidence": { "type": "number", "minimum": 0, "exclusiveMinimum": false, "maximum": 1, "exclusiveMaximum": false }, "source": { "type": "string", "enum": [ "realtime_model" ] } }, "required": [ "label", "confidence", "source" ] }, "realtimeSummary": { "description": "Legacy field on Messages saved by earlier releases; new Messages omit it. The Realtime model's own summary of the preceding voice conversation; model-written, not a durable transcript.", "type": "string", "minLength": 1, "maxLength": 8000 } }, "required": [ "channel" ] }, { "description": "A Realtime Standing Task cycle: the platform started this Turn with the Template's standing goal while a Realtime Connection was live; nobody typed or spoke it.", "type": "object", "properties": { "channel": { "type": "string", "enum": [ "standing_task" ] } }, "required": [ "channel" ] } ] }, "realtime": { "oneOf": [ { "type": "object", "properties": { "startsTurn": { "type": "boolean" }, "linkedTurnId": { "type": "string", "nullable": true } }, "required": [ "startsTurn", "linkedTurnId" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "chat", "task_ack", "task_progress", "task_result", "clarify", "device_ack" ] }, "interrupted": { "description": "The reply was interrupted; its transcript may include speech the user did not hear.", "type": "boolean" }, "responseId": { "type": "string", "nullable": true }, "linkedTurnId": { "type": "string", "nullable": true } }, "required": [ "kind", "interrupted", "responseId", "linkedTurnId" ] } ] } }, "required": [ "id", "sessionId", "turnId", "role", "content", "createdAt" ], "nullable": true }, "createdAt": { "type": "string" }, "completedAt": { "type": "string" }, "failure": { "description": "A failed Turn's saved turn_error payload, identical to its turn_error event.", "type": "object", "properties": { "code": { "description": "service_configuration_unavailable, model_provider_failed, runtime_error or another stable failure code.", "type": "string" }, "message": { "description": "Fixed text for the code; never supplier or internal error text.", "type": "string" }, "details": { "type": "object", "properties": { "reason": { "description": "With service_configuration_unavailable: the missing service.", "type": "string", "enum": [ "model_provider_unconfigured", "sandbox_unconfigured", "drive9_unconfigured", "drive9_disabled_for_organization" ] }, "provider": { "description": "With model_provider_failed: the failure category, supplier HTTP status and supplier error type and code. Never supplier message text, request paths or credentials.", "type": "object", "properties": { "category": { "type": "string", "enum": [ "authentication", "supplier_error", "supplier_unavailable", "network", "provider_stream_error" ] }, "httpStatus": { "type": "integer", "nullable": true }, "errorType": { "type": "string", "nullable": true }, "errorCode": { "type": "string", "nullable": true } }, "required": [ "category", "httpStatus", "errorType", "errorCode" ] }, "registrations": { "description": "Each referenced registration whose authorization is not usable, by serverId.", "type": "array", "minItems": 1, "items": { "type": "object", "properties": { "serverId": { "description": "The MCP Server Registration that needs authorization.", "type": "string" }, "owner": { "description": "Who must authorize it: the Organization, or the Session End User.", "type": "string", "enum": [ "organization", "end_user" ] }, "reason": { "description": "missing: no usable authorization with a catalog exists; invalid: it was invalidated by an endpoint or mode change, or the server refused its credential with HTTP 401 or 403 during a Turn; revoked: its credential was revoked; insufficient_scope: the server answered 403 insufficient_scope, requiring a scope it lacks.", "type": "string", "enum": [ "missing", "invalid", "revoked", "insufficient_scope" ] } }, "required": [ "serverId", "owner", "reason" ] } } } } }, "required": [ "code", "message" ] }, "kind": { "type": "string", "enum": [ "template_handoff" ] } }, "required": [ "executor", "id", "sessionId", "status", "billingTag", "agentTemplateId", "userMessages", "operations", "assistantMessage", "createdAt", "kind" ] } ] } }, "hasMore": { "type": "boolean" }, "nextCursor": { "type": "string", "nullable": true } }, "required": [ "turns", "hasMore", "nextCursor" ]}schemas/TurnResponse
Section titled “schemas/TurnResponse”{ "type": "object", "required": [ "turn", "stopRequestedAt" ], "properties": { "turn": { "$ref": "#/components/schemas/Turn" }, "stopRequestedAt": { "type": "string", "format": "date-time", "nullable": true, "description": "When the stop request was durably accepted, or null. The Turn can still be running while the stop converges." } }}schemas/Turn
Section titled “schemas/Turn”{ "oneOf": [ { "$ref": "#/components/schemas/UserInputTurn" }, { "$ref": "#/components/schemas/TemplateHandoffTurn" } ]}schemas/UserInputTurn
Section titled “schemas/UserInputTurn”{ "type": "object", "required": [ "id", "sessionId", "status", "userMessage", "userMessages", "operations", "assistantMessage", "createdAt", "billingTag", "agentTemplateId" ], "properties": { "id": { "type": "string" }, "sessionId": { "type": "string" }, "status": { "type": "string", "enum": [ "running", "succeeded", "failed", "interrupted" ] }, "userMessage": { "$ref": "#/components/schemas/Message" }, "userMessages": { "type": "array", "description": "Canonical admitted user Messages in input order; includes accepted inputs interrupted before incorporation.", "items": { "$ref": "#/components/schemas/Message" } }, "userFiles": { "type": "array", "items": { "$ref": "#/components/schemas/TurnUserFile" } }, "operations": { "description": "Operations performed by the Turn. drive.commit is recorded only after a workspace tool attempt.", "type": "array", "items": { "$ref": "#/components/schemas/Operation" } }, "assistantMessage": { "allOf": [ { "$ref": "#/components/schemas/Message" } ], "nullable": true }, "clarificationItem": { "$ref": "#/components/schemas/ClarificationItem" }, "createdAt": { "type": "string", "format": "date-time" }, "completedAt": { "type": "string", "format": "date-time" }, "sourceFireId": { "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" } ] }, "agentTemplateId": { "type": "string", "nullable": true, "description": "AgentTemplate frozen when the Turn was admitted." }, "failure": { "description": "Present only on a failed Turn that saved a turn_error event; identical to that event's payload. Older failed Turns without one omit it.", "allOf": [ { "$ref": "#/components/schemas/TurnFailure" } ] }, "executor": { "type": "string", "enum": [ "full_agent", "realtime_model" ] }, "realtime": { "type": "object", "properties": { "connectionId": { "type": "string" }, "linkedTurnIds": { "type": "array", "items": { "type": "string" } } }, "required": [ "connectionId", "linkedTurnIds" ] }, "realtimeResponses": { "description": "Narration-only Realtime responses about this Full Agent Turn, in Session sequence order.", "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "sessionId": { "type": "string" }, "turnId": { "type": "string" }, "role": { "type": "string", "enum": [ "user", "assistant" ] }, "content": { "type": "string" }, "createdAt": { "type": "string" }, "inputContext": { "description": "Server-recorded channel of a user input; clients cannot set it. Present on user Messages except Scheduler-triggered Turns and Messages saved before it existed; absent on assistant Messages. Tolerate channel values added later.", "oneOf": [ { "type": "object", "properties": { "channel": { "type": "string", "enum": [ "text" ] } }, "required": [ "channel" ] }, { "type": "object", "properties": { "channel": { "type": "string", "enum": [ "audio" ] }, "utterance": { "description": "Transcript of the user's own speech when the Message content is a task delegated from it.", "type": "string", "minLength": 1, "maxLength": 8000 }, "emotion": { "description": "Emotion the Realtime model perceived in the speech; not a verified fact.", "type": "object", "properties": { "label": { "type": "string", "minLength": 1, "maxLength": 64 }, "confidence": { "type": "number", "minimum": 0, "exclusiveMinimum": false, "maximum": 1, "exclusiveMaximum": false }, "source": { "type": "string", "enum": [ "realtime_model" ] } }, "required": [ "label", "confidence", "source" ] }, "realtimeSummary": { "description": "Legacy field on Messages saved by earlier releases; new Messages omit it. The Realtime model's own summary of the preceding voice conversation; model-written, not a durable transcript.", "type": "string", "minLength": 1, "maxLength": 8000 } }, "required": [ "channel" ] }, { "description": "A Realtime Standing Task cycle: the platform started this Turn with the Template's standing goal while a Realtime Connection was live; nobody typed or spoke it.", "type": "object", "properties": { "channel": { "type": "string", "enum": [ "standing_task" ] } }, "required": [ "channel" ] } ] }, "realtime": { "oneOf": [ { "type": "object", "properties": { "startsTurn": { "type": "boolean" }, "linkedTurnId": { "type": "string", "nullable": true } }, "required": [ "startsTurn", "linkedTurnId" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "chat", "task_ack", "task_progress", "task_result", "clarify", "device_ack" ] }, "interrupted": { "description": "The reply was interrupted; its transcript may include speech the user did not hear.", "type": "boolean" }, "responseId": { "type": "string", "nullable": true }, "linkedTurnId": { "type": "string", "nullable": true } }, "required": [ "kind", "interrupted", "responseId", "linkedTurnId" ] } ] } }, "required": [ "id", "sessionId", "turnId", "role", "content", "createdAt" ] } } }, "additionalProperties": false}schemas/Message
Section titled “schemas/Message”{ "type": "object", "required": [ "id", "sessionId", "turnId", "role", "content", "createdAt" ], "properties": { "id": { "type": "string" }, "sessionId": { "type": "string" }, "turnId": { "type": "string" }, "role": { "type": "string", "enum": [ "user", "assistant" ] }, "content": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "inputContext": { "$ref": "#/components/schemas/MessageInputContext" }, "realtime": { "oneOf": [ { "type": "object", "properties": { "startsTurn": { "type": "boolean" }, "linkedTurnId": { "type": "string", "nullable": true } }, "required": [ "startsTurn", "linkedTurnId" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "chat", "task_ack", "task_progress", "task_result", "clarify", "device_ack" ] }, "interrupted": { "description": "The reply was interrupted; its transcript may include speech the user did not hear.", "type": "boolean" }, "responseId": { "type": "string", "nullable": true }, "linkedTurnId": { "type": "string", "nullable": true } }, "required": [ "kind", "interrupted", "responseId", "linkedTurnId" ] } ] } }}schemas/MessageInputContext
Section titled “schemas/MessageInputContext”{ "description": "Server-recorded channel of a user input; clients cannot set it. Present on user Messages except Scheduler-triggered Turns and Messages saved before it existed; absent on assistant Messages. Tolerate channel values added later.", "oneOf": [ { "type": "object", "required": [ "channel" ], "properties": { "channel": { "type": "string", "enum": [ "text" ] } } }, { "type": "object", "required": [ "channel" ], "properties": { "channel": { "type": "string", "enum": [ "audio" ] }, "utterance": { "description": "Transcript of the user's own speech when the Message content is a task delegated from it.", "type": "string", "minLength": 1, "maxLength": 8000 }, "emotion": { "description": "Emotion the Realtime model perceived in the speech; not a verified fact.", "type": "object", "required": [ "label", "confidence", "source" ], "properties": { "label": { "type": "string", "minLength": 1, "maxLength": 64 }, "confidence": { "type": "number", "minimum": 0, "maximum": 1 }, "source": { "type": "string", "enum": [ "realtime_model" ] } } }, "realtimeSummary": { "description": "Legacy field on Messages saved by earlier releases; new Messages omit it. The Realtime model's own summary of the preceding voice conversation; model-written, not a durable transcript.", "type": "string", "minLength": 1, "maxLength": 8000 } } }, { "description": "A Realtime Standing Task cycle: the platform started this Turn with the Template's standing goal while a Realtime Connection was live; nobody typed or spoke it.", "type": "object", "required": [ "channel" ], "properties": { "channel": { "type": "string", "enum": [ "standing_task" ] } } } ]}schemas/TurnUserFile
Section titled “schemas/TurnUserFile”{ "type": "object", "properties": { "turnId": { "type": "string" }, "sessionId": { "type": "string" }, "organizationId": { "type": "string" }, "userFileId": { "type": "string" }, "ordinal": { "type": "integer" }, "originalName": { "type": "string" }, "safeName": { "type": "string" }, "drivePath": { "type": "string" }, "byteSize": { "type": "integer" }, "sha256": { "type": "string" }, "checksumVerification": { "type": "string", "enum": [ "whole", "part_only" ], "nullable": true }, "contentType": { "type": "string", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "turnId", "sessionId", "organizationId", "userFileId", "ordinal", "originalName", "safeName", "drivePath", "byteSize", "sha256", "checksumVerification", "contentType", "createdAt" ]}schemas/Operation
Section titled “schemas/Operation”{ "type": "object", "required": [ "id", "sessionId", "turnId", "scope", "kind", "backend", "targetKind", "mediator", "status", "input", "resultPointer", "createdAt" ], "properties": { "id": { "type": "string" }, "sessionId": { "type": "string" }, "turnId": { "type": "string" }, "scope": { "type": "object", "additionalProperties": true }, "kind": { "type": "string", "description": "Historical long-term Memory Operations remain records only." }, "backend": { "type": "string", "description": "Historical long-term Memory Operations may retain the `mem9` backend value." }, "targetKind": { "type": "string", "description": "Historical long-term Memory Operations may retain the `memory` target kind." }, "mediator": { "type": "string", "enum": [ "aos" ] }, "status": { "type": "string", "enum": [ "running", "succeeded", "failed", "interrupted", "unknown_result" ] }, "category": { "type": "string", "enum": [ "tool_call", "skill_read" ], "description": "How to group a tool Operation: skill_read when it reads a file inside one of its AgentRun's frozen Skill packages, whether Runtime loaded the Skill instructions or the model read a package file; tool_call for every other tool Operation. Absent on non-tool Operations such as llm.complete and on metadata-only Operations." }, "skill": { "$ref": "#/components/schemas/OperationSkill" }, "input": { "description": "Kind-specific input. Hardware Client Tool Operations expose only toolName, callId and mode, omitting device arguments." }, "output": { "description": "Hardware Client Tool Operations omit output in every status. Kind-specific result. An llm.complete Operation exposes usage as token counts only: input, output, cacheRead, cacheWrite, totalTokens, and optional cacheWrite1h and reasoning. Counts that are unavailable or invalid are omitted; absent usage is omitted. Supplier SDK cost is not exposed. Customer fees are available from the Billing usage APIs. A failed or interrupted llm.complete Operation has error {code, message, details?} with fixed text only; model_provider_failed carries details.provider (category, (category, httpStatus, errorType, errorCode); other failures use runtime_error or a ledger outcome code. Any other failed, interrupted or unknown_result Operation with an error, including tool Operations, has error {code, message, details} with fixed text naming only the tool: an intentional tool code (for example mcp_unavailable or validation_error) is kept; an allow-listed web_search_* or session_recall_* reason becomes the code and is repeated as details.code with a boolean details.retryable; anything else reads tool_failed. A memory.recall Operation keeps only memory_recall_failed, turn_interrupted or operation_result_unknown, and otherwise reads tool_failed. details also carries tool, category (rejected, unavailable, remote_error, failed, unknown_result, interrupted or unexpected) and, when known, dispatch and retryContract." }, "resultPointer": { "type": "object", "additionalProperties": true }, "createdAt": { "type": "string", "format": "date-time" }, "completedAt": { "type": "string", "format": "date-time" }, "source": { "$ref": "#/components/schemas/ClientToolOperationSource" }, "label": { "type": "string", "maxLength": 322, "description": "Readable Hardware Client Tool label, for example Speaker · set_volume. Absent on metadata-only Operations." } }}schemas/TemplateHandoffTurn
Section titled “schemas/TemplateHandoffTurn”{ "type": "object", "properties": { "executor": { "type": "string", "enum": [ "full_agent" ] }, "id": { "type": "string" }, "sessionId": { "type": "string" }, "status": { "type": "string", "enum": [ "running", "succeeded", "failed", "interrupted" ] }, "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" } ] }, "agentTemplateId": { "type": "string" }, "userMessages": { "type": "array", "maxItems": 0, "items": { "type": "object", "properties": { "id": { "type": "string" }, "sessionId": { "type": "string" }, "turnId": { "type": "string" }, "role": { "type": "string", "enum": [ "user", "assistant" ] }, "content": { "type": "string" }, "createdAt": { "type": "string" }, "inputContext": { "description": "Server-recorded channel of a user input; clients cannot set it. Present on user Messages except Scheduler-triggered Turns and Messages saved before it existed; absent on assistant Messages. Tolerate channel values added later.", "oneOf": [ { "type": "object", "properties": { "channel": { "type": "string", "enum": [ "text" ] } }, "required": [ "channel" ] }, { "type": "object", "properties": { "channel": { "type": "string", "enum": [ "audio" ] }, "utterance": { "description": "Transcript of the user's own speech when the Message content is a task delegated from it.", "type": "string", "minLength": 1, "maxLength": 8000 }, "emotion": { "description": "Emotion the Realtime model perceived in the speech; not a verified fact.", "type": "object", "properties": { "label": { "type": "string", "minLength": 1, "maxLength": 64 }, "confidence": { "type": "number", "minimum": 0, "exclusiveMinimum": false, "maximum": 1, "exclusiveMaximum": false }, "source": { "type": "string", "enum": [ "realtime_model" ] } }, "required": [ "label", "confidence", "source" ] }, "realtimeSummary": { "description": "Legacy field on Messages saved by earlier releases; new Messages omit it. The Realtime model's own summary of the preceding voice conversation; model-written, not a durable transcript.", "type": "string", "minLength": 1, "maxLength": 8000 } }, "required": [ "channel" ] }, { "description": "A Realtime Standing Task cycle: the platform started this Turn with the Template's standing goal while a Realtime Connection was live; nobody typed or spoke it.", "type": "object", "properties": { "channel": { "type": "string", "enum": [ "standing_task" ] } }, "required": [ "channel" ] } ] }, "realtime": { "oneOf": [ { "type": "object", "properties": { "startsTurn": { "type": "boolean" }, "linkedTurnId": { "type": "string", "nullable": true } }, "required": [ "startsTurn", "linkedTurnId" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "chat", "task_ack", "task_progress", "task_result", "clarify", "device_ack" ] }, "interrupted": { "description": "The reply was interrupted; its transcript may include speech the user did not hear.", "type": "boolean" }, "responseId": { "type": "string", "nullable": true }, "linkedTurnId": { "type": "string", "nullable": true } }, "required": [ "kind", "interrupted", "responseId", "linkedTurnId" ] } ] } }, "required": [ "id", "sessionId", "turnId", "role", "content", "createdAt" ] } }, "operations": { "description": "Operations performed by the Turn. drive.commit is recorded only after a workspace tool attempt.", "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "sessionId": { "type": "string" }, "turnId": { "type": "string" }, "scope": { "type": "object", "additionalProperties": {} }, "kind": { "type": "string" }, "backend": { "type": "string" }, "targetKind": { "type": "string" }, "mediator": { "type": "string", "enum": [ "aos" ] }, "status": { "type": "string", "enum": [ "running", "succeeded", "failed", "interrupted", "unknown_result" ] }, "category": { "description": "How to group a tool Operation: skill_read when it reads a file inside one of its AgentRun's frozen Skill packages, whether Runtime loaded the Skill instructions or the model read a package file; tool_call for every other tool Operation. Absent on non-tool Operations such as llm.complete and on metadata-only Operations.", "type": "string", "enum": [ "tool_call", "skill_read" ] }, "skill": { "description": "The Skill a skill_read Operation read from; present only with category skill_read.", "type": "object", "properties": { "skillId": { "type": "string" }, "name": { "type": "string" } }, "required": [ "skillId", "name" ] }, "source": { "description": "Client Tool source: session_client for every new call. Hardware sources appear only on calls recorded before native Hardware retired and expose the Session binding or requirement identifier and original method. Private device and Registration identities are omitted. Absent on metadata-only Operations. Current reads default older Session-client Operations to session_client; persisted historical progress events may omit source.", "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "session_client" ] } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "hardware" ] }, "method": { "type": "string", "pattern": "^[a-zA-Z0-9_-]{1,64}$" }, "hardwareRequirementId": { "type": "string", "pattern": "^[a-z][a-z0-9_.-]{0,99}$" } }, "required": [ "type", "method", "hardwareRequirementId" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "hardware" ] }, "method": { "type": "string", "pattern": "^[a-zA-Z0-9_-]{1,64}$" }, "hardwareBindingId": { "type": "string", "pattern": "^hbind_[0-9a-f]{32}$" } }, "required": [ "type", "method", "hardwareBindingId" ] } ] }, "label": { "description": "Readable label of a historical Hardware Client Tool, for example Speaker · set_volume. Absent on metadata-only Operations.", "type": "string", "maxLength": 322 }, "input": { "description": "Kind-specific input. A tool Operation has toolName and args; a historical Hardware Client Tool exposes only toolName, callId and mode, omitting device arguments. Neither input nor output carries the model supplier's tool-call id; use the Operation id to identify a tool call and its result." }, "output": { "description": "Kind-specific result. Hardware Client Tool Operations, recorded before native Hardware retired, omit output in every status. An llm.complete Operation exposes usage as token counts only: input, output, cacheRead, cacheWrite, totalTokens, and optional cacheWrite1h and reasoning. Counts that are unavailable or invalid are omitted; absent usage is omitted. Supplier SDK cost is not exposed. Customer fees are available from the Billing usage APIs. A failed or interrupted llm.complete Operation has error {code, message, details?} with fixed text only; model_provider_failed carries details.provider (category, httpStatus, errorType, errorCode); other failures use runtime_error or a ledger outcome code. Any other failed, interrupted or unknown_result Operation with an error, including tool Operations, has error {code, message, details} with fixed text naming only the tool: an intentional tool code (for example mcp_unavailable or validation_error) is kept; an allow-listed web_search_* or session_recall_* reason becomes the code and is repeated as details.code with a boolean details.retryable; anything else reads tool_failed. A memory.recall Operation keeps only memory_recall_failed, turn_interrupted or operation_result_unknown, and otherwise reads tool_failed. details also carries tool, category (rejected, unavailable, remote_error, failed, unknown_result, interrupted or unexpected) and, when known, dispatch and retryContract." }, "resultPointer": { "type": "object", "additionalProperties": {} }, "createdAt": { "type": "string" }, "completedAt": { "type": "string" } }, "required": [ "id", "sessionId", "turnId", "scope", "kind", "backend", "targetKind", "mediator", "status", "input", "resultPointer", "createdAt" ] } }, "assistantMessage": { "type": "object", "properties": { "id": { "type": "string" }, "sessionId": { "type": "string" }, "turnId": { "type": "string" }, "role": { "type": "string", "enum": [ "user", "assistant" ] }, "content": { "type": "string" }, "createdAt": { "type": "string" }, "inputContext": { "description": "Server-recorded channel of a user input; clients cannot set it. Present on user Messages except Scheduler-triggered Turns and Messages saved before it existed; absent on assistant Messages. Tolerate channel values added later.", "oneOf": [ { "type": "object", "properties": { "channel": { "type": "string", "enum": [ "text" ] } }, "required": [ "channel" ] }, { "type": "object", "properties": { "channel": { "type": "string", "enum": [ "audio" ] }, "utterance": { "description": "Transcript of the user's own speech when the Message content is a task delegated from it.", "type": "string", "minLength": 1, "maxLength": 8000 }, "emotion": { "description": "Emotion the Realtime model perceived in the speech; not a verified fact.", "type": "object", "properties": { "label": { "type": "string", "minLength": 1, "maxLength": 64 }, "confidence": { "type": "number", "minimum": 0, "exclusiveMinimum": false, "maximum": 1, "exclusiveMaximum": false }, "source": { "type": "string", "enum": [ "realtime_model" ] } }, "required": [ "label", "confidence", "source" ] }, "realtimeSummary": { "description": "Legacy field on Messages saved by earlier releases; new Messages omit it. The Realtime model's own summary of the preceding voice conversation; model-written, not a durable transcript.", "type": "string", "minLength": 1, "maxLength": 8000 } }, "required": [ "channel" ] }, { "description": "A Realtime Standing Task cycle: the platform started this Turn with the Template's standing goal while a Realtime Connection was live; nobody typed or spoke it.", "type": "object", "properties": { "channel": { "type": "string", "enum": [ "standing_task" ] } }, "required": [ "channel" ] } ] }, "realtime": { "oneOf": [ { "type": "object", "properties": { "startsTurn": { "type": "boolean" }, "linkedTurnId": { "type": "string", "nullable": true } }, "required": [ "startsTurn", "linkedTurnId" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "chat", "task_ack", "task_progress", "task_result", "clarify", "device_ack" ] }, "interrupted": { "description": "The reply was interrupted; its transcript may include speech the user did not hear.", "type": "boolean" }, "responseId": { "type": "string", "nullable": true }, "linkedTurnId": { "type": "string", "nullable": true } }, "required": [ "kind", "interrupted", "responseId", "linkedTurnId" ] } ] } }, "required": [ "id", "sessionId", "turnId", "role", "content", "createdAt" ], "nullable": true }, "createdAt": { "type": "string" }, "completedAt": { "type": "string" }, "failure": { "description": "A failed Turn's saved turn_error payload, identical to its turn_error event.", "type": "object", "properties": { "code": { "description": "service_configuration_unavailable, model_provider_failed, runtime_error or another stable failure code.", "type": "string" }, "message": { "description": "Fixed text for the code; never supplier or internal error text.", "type": "string" }, "details": { "type": "object", "properties": { "reason": { "description": "With service_configuration_unavailable: the missing service.", "type": "string", "enum": [ "model_provider_unconfigured", "sandbox_unconfigured", "drive9_unconfigured", "drive9_disabled_for_organization" ] }, "provider": { "description": "With model_provider_failed: the failure category, supplier HTTP status and supplier error type and code. Never supplier message text, request paths or credentials.", "type": "object", "properties": { "category": { "type": "string", "enum": [ "authentication", "supplier_error", "supplier_unavailable", "network", "provider_stream_error" ] }, "httpStatus": { "type": "integer", "nullable": true }, "errorType": { "type": "string", "nullable": true }, "errorCode": { "type": "string", "nullable": true } }, "required": [ "category", "httpStatus", "errorType", "errorCode" ] }, "registrations": { "description": "Each referenced registration whose authorization is not usable, by serverId.", "type": "array", "minItems": 1, "items": { "type": "object", "properties": { "serverId": { "description": "The MCP Server Registration that needs authorization.", "type": "string" }, "owner": { "description": "Who must authorize it: the Organization, or the Session End User.", "type": "string", "enum": [ "organization", "end_user" ] }, "reason": { "description": "missing: no usable authorization with a catalog exists; invalid: it was invalidated by an endpoint or mode change, or the server refused its credential with HTTP 401 or 403 during a Turn; revoked: its credential was revoked; insufficient_scope: the server answered 403 insufficient_scope, requiring a scope it lacks.", "type": "string", "enum": [ "missing", "invalid", "revoked", "insufficient_scope" ] } }, "required": [ "serverId", "owner", "reason" ] } } } } }, "required": [ "code", "message" ] }, "kind": { "type": "string", "enum": [ "template_handoff" ] } }, "required": [ "id", "sessionId", "status", "billingTag", "agentTemplateId", "userMessages", "operations", "assistantMessage", "createdAt", "kind" ]}schemas/SwitchSessionTemplateOpenApiDto
Section titled “schemas/SwitchSessionTemplateOpenApiDto”{ "type": "object", "properties": { "agentTemplateId": { "type": "string", "minLength": 1, "maxLength": 64 }, "acknowledgeSessionRecall": { "description": "Required when the target enables cross-Session Recall.", "type": "boolean" } }, "required": [ "agentTemplateId" ]}schemas/SessionTemplateSwitchResponseOpenApiDto
Section titled “schemas/SessionTemplateSwitchResponseOpenApiDto”{ "type": "object", "properties": { "receipt": { "type": "object", "properties": { "commandId": { "type": "string" }, "sessionId": { "type": "string" }, "agentTemplateId": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "succeeded", "failed", "unchanged" ] }, "configurationEpoch": { "type": "integer", "minimum": 1, "exclusiveMinimum": false }, "handoffTurnId": { "type": "string" }, "createdAt": { "type": "string" }, "completedAt": { "type": "string" }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "session_switch_conflict", "agent_template_unavailable", "session_switch_unsupported" ] } }, "required": [ "code" ] } }, "required": [ "commandId", "sessionId", "agentTemplateId", "status", "configurationEpoch", "createdAt" ] } }, "required": [ "receipt" ]}schemas/CreateUserDriveDirectoryBodyDto
Section titled “schemas/CreateUserDriveDirectoryBodyDto”{ "type": "object", "properties": { "path": { "type": "string", "minLength": 1, "maxLength": 1024 } }, "required": [ "path" ]}schemas/UserDriveEntryResponseDto
Section titled “schemas/UserDriveEntryResponseDto”{ "type": "object", "properties": { "fileId": { "type": "string" }, "name": { "type": "string" }, "path": { "type": "string" }, "type": { "type": "string", "enum": [ "file", "directory" ] }, "byteSize": { "type": "integer", "minimum": 0, "exclusiveMinimum": false, "nullable": true }, "contentType": { "type": "string", "nullable": true }, "sha256": { "type": "string", "nullable": true }, "etag": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "fileId", "name", "path", "type", "byteSize", "contentType", "sha256", "etag", "createdAt", "updatedAt" ]}schemas/UserDriveDownloadTicketBodyDto
Section titled “schemas/UserDriveDownloadTicketBodyDto”{ "type": "object", "properties": { "fileId": { "type": "string", "minLength": 1, "maxLength": 128 }, "path": { "type": "string", "minLength": 1, "maxLength": 1024 } }}schemas/UserDriveEntryMutationBodyDto
Section titled “schemas/UserDriveEntryMutationBodyDto”{ "type": "object", "properties": { "fileId": { "type": "string", "minLength": 1, "maxLength": 128 }, "path": { "type": "string", "minLength": 1, "maxLength": 1024 } }}schemas/UserDriveEntriesResponseDto
Section titled “schemas/UserDriveEntriesResponseDto”{ "type": "object", "properties": { "path": { "type": "string" }, "entry": { "type": "object", "properties": { "fileId": { "type": "string" }, "name": { "type": "string" }, "path": { "type": "string" }, "type": { "type": "string", "enum": [ "file", "directory" ] }, "byteSize": { "type": "integer", "minimum": 0, "exclusiveMinimum": false, "nullable": true }, "contentType": { "type": "string", "nullable": true }, "sha256": { "type": "string", "nullable": true }, "etag": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "fileId", "name", "path", "type", "byteSize", "contentType", "sha256", "etag", "createdAt", "updatedAt" ], "nullable": true }, "entries": { "type": "array", "items": { "type": "object", "properties": { "fileId": { "type": "string" }, "name": { "type": "string" }, "path": { "type": "string" }, "type": { "type": "string", "enum": [ "file", "directory" ] }, "byteSize": { "type": "integer", "minimum": 0, "exclusiveMinimum": false, "nullable": true }, "contentType": { "type": "string", "nullable": true }, "sha256": { "type": "string", "nullable": true }, "etag": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "fileId", "name", "path", "type", "byteSize", "contentType", "sha256", "etag", "createdAt", "updatedAt" ] } }, "nextCursor": { "type": "string", "nullable": true } }, "required": [ "path", "entries", "nextCursor" ]}schemas/PublicUserFileUploadCapabilitiesOpenApiDto
Section titled “schemas/PublicUserFileUploadCapabilitiesOpenApiDto”{ "type": "object", "properties": { "capabilities": { "type": "object", "properties": { "protocol": { "type": "string", "enum": [ "tidb-link.user-files.v2" ] }, "inlineThreshold": { "description": "Files below this current threshold use Agent Service inline transfer.", "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "maxUploadBytes": { "description": "Effective limit: min(200 MiB, the current Drive9 maximum).", "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "checksum": { "type": "string", "enum": [ "sha-256" ] } }, "required": [ "protocol", "inlineThreshold", "maxUploadBytes", "checksum" ] } }, "required": [ "capabilities" ]}schemas/CreatePublicUserFileUploadBodyOpenApiDto
Section titled “schemas/CreatePublicUserFileUploadBodyOpenApiDto”{ "type": "object", "properties": { "originalName": { "description": "Original caller-visible file name.", "type": "string", "minLength": 1, "maxLength": 255 }, "byteSize": { "description": "Declared bytes. Read upload capabilities for the current effective maximum.", "type": "integer", "minimum": 0, "exclusiveMinimum": false }, "sha256": { "description": "Lowercase hexadecimal SHA-256 of the complete file.", "type": "string", "pattern": "^[a-f0-9]{64}$" }, "contentType": { "description": "Optional media type stored with the ready file.", "type": "string", "maxLength": 255, "nullable": true } }, "required": [ "originalName", "byteSize", "sha256", "contentType" ]}schemas/FileUploadResponseDto
Section titled “schemas/FileUploadResponseDto”{ "type": "object", "properties": { "upload": { "type": "object", "properties": { "uploadId": { "description": "Opaque identity of the persisted upload intent.", "type": "string" }, "file": { "type": "object", "properties": { "fileId": { "type": "string" }, "originalName": { "type": "string" }, "status": { "type": "string", "enum": [ "uploading", "ready", "failed" ] }, "byteSize": { "type": "integer", "minimum": 0, "exclusiveMinimum": false, "nullable": true }, "sha256": { "type": "string", "nullable": true }, "checksumVerification": { "type": "string", "enum": [ "whole", "part_only" ], "nullable": true, "description": "Verified fact for a ready file; null until settlement. whole verifies the complete file, while part_only verifies every multipart part." }, "contentType": { "type": "string", "nullable": true }, "lastError": { "type": "string", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "source": { "description": "`user_upload` for an upload by the owner; `session` for a Session file that an Operation of the owner's Session produced, such as an image or binary MCP tool result.", "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "user_upload" ] } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "session" ] }, "sessionId": { "type": "string", "minLength": 1, "maxLength": 64 }, "operationId": { "type": "string", "minLength": 1, "maxLength": 64 } }, "required": [ "kind", "sessionId", "operationId" ] } ] } }, "required": [ "fileId", "originalName", "status", "byteSize", "sha256", "checksumVerification", "contentType", "lastError", "createdAt", "updatedAt", "source" ] }, "mode": { "type": "string", "enum": [ "tidb-link", "s3" ] }, "expectedChecksumVerification": { "type": "string", "enum": [ "whole" ] }, "expiresAt": { "type": "string", "format": "date-time" }, "contentUrl": { "type": "string" }, "uploadUrl": { "description": "Fresh 60-second bearer URL on active inline create/replay only. Send every returned header; no API Key is needed. Omitted when the ticket key is unavailable. Status reads do not issue URLs.", "type": "object", "properties": { "method": { "type": "string", "enum": [ "PUT" ] }, "url": { "type": "string" }, "headers": { "type": "object", "properties": { "content-type": { "type": "string", "enum": [ "application/octet-stream" ] }, "content-digest": { "type": "string" } }, "required": [ "content-type", "content-digest" ] }, "expiresAt": { "type": "string", "format": "date-time" } }, "required": [ "method", "url", "headers", "expiresAt" ] }, "partSize": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "totalParts": { "type": "integer", "minimum": 0, "exclusiveMinimum": true } }, "required": [ "uploadId", "file", "mode", "expectedChecksumVerification", "expiresAt" ] } }, "required": [ "upload" ]}schemas/UploadStatusResponseDto
Section titled “schemas/UploadStatusResponseDto”{ "type": "object", "properties": { "upload": { "type": "object", "properties": { "uploadId": { "type": "string" }, "mode": { "type": "string", "enum": [ "tidb-link", "s3", "initializing" ] }, "state": { "type": "string", "enum": [ "active", "completing", "aborting", "completed", "aborted" ] }, "expiresAt": { "type": "string", "format": "date-time" }, "file": { "type": "object", "properties": { "fileId": { "type": "string" }, "originalName": { "type": "string" }, "status": { "type": "string", "enum": [ "uploading", "ready", "failed" ] }, "byteSize": { "type": "integer", "minimum": 0, "exclusiveMinimum": false, "nullable": true }, "sha256": { "type": "string", "nullable": true }, "checksumVerification": { "type": "string", "enum": [ "whole", "part_only" ], "nullable": true, "description": "Verified fact for a ready file; null until settlement. whole verifies the complete file, while part_only verifies every multipart part." }, "contentType": { "type": "string", "nullable": true }, "lastError": { "type": "string", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "source": { "description": "`user_upload` for an upload by the owner; `session` for a Session file that an Operation of the owner's Session produced, such as an image or binary MCP tool result.", "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "user_upload" ] } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "session" ] }, "sessionId": { "type": "string", "minLength": 1, "maxLength": 64 }, "operationId": { "type": "string", "minLength": 1, "maxLength": 64 } }, "required": [ "kind", "sessionId", "operationId" ] } ] } }, "required": [ "fileId", "originalName", "status", "byteSize", "sha256", "checksumVerification", "contentType", "lastError", "createdAt", "updatedAt", "source" ] } }, "required": [ "uploadId", "mode", "state", "expiresAt", "file" ] } }, "required": [ "upload" ]}schemas/FileResponseDto
Section titled “schemas/FileResponseDto”{ "type": "object", "properties": { "file": { "type": "object", "properties": { "fileId": { "type": "string" }, "originalName": { "type": "string" }, "status": { "type": "string", "enum": [ "uploading", "ready", "failed" ] }, "byteSize": { "type": "integer", "minimum": 0, "exclusiveMinimum": false, "nullable": true }, "sha256": { "type": "string", "nullable": true }, "checksumVerification": { "type": "string", "enum": [ "whole", "part_only" ], "nullable": true, "description": "Verified fact for a ready file; null until settlement. whole verifies the complete file, while part_only verifies every multipart part." }, "contentType": { "type": "string", "nullable": true }, "lastError": { "type": "string", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "source": { "description": "`user_upload` for an upload by the owner; `session` for a Session file that an Operation of the owner's Session produced, such as an image or binary MCP tool result.", "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "user_upload" ] } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "session" ] }, "sessionId": { "type": "string", "minLength": 1, "maxLength": 64 }, "operationId": { "type": "string", "minLength": 1, "maxLength": 64 } }, "required": [ "kind", "sessionId", "operationId" ] } ] } }, "required": [ "fileId", "originalName", "status", "byteSize", "sha256", "checksumVerification", "contentType", "lastError", "createdAt", "updatedAt", "source" ] } }, "required": [ "file" ]}schemas/PresignPublicUserFileUploadPartBodyOpenApiDto
Section titled “schemas/PresignPublicUserFileUploadPartBodyOpenApiDto”{ "type": "object", "properties": { "sha256": { "description": "Lowercase hexadecimal SHA-256 of this exact part.", "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "required": [ "sha256" ]}schemas/PublicUserFileUploadPartResponseOpenApiDto
Section titled “schemas/PublicUserFileUploadPartResponseOpenApiDto”{ "type": "object", "properties": { "part": { "type": "object", "properties": { "number": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "url": { "type": "string", "format": "uri" }, "size": { "description": "PUT exactly this many bytes to the returned URL.", "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "headers": { "description": "Send every returned header unchanged on the S3 PUT request.", "type": "object", "additionalProperties": { "type": "string" } }, "expiresAt": { "type": "string" } }, "required": [ "number", "url", "size", "headers", "expiresAt" ] } }, "required": [ "part" ]}schemas/FileConfirmationDto
Section titled “schemas/FileConfirmationDto”{ "type": "object", "properties": { "parts": { "type": "array", "items": { "type": "object", "properties": { "number": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "etag": { "type": "string", "minLength": 1, "maxLength": 255 }, "sha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "required": [ "number", "etag", "sha256" ] } } }}schemas/FilesPageDto
Section titled “schemas/FilesPageDto”{ "type": "object", "properties": { "files": { "type": "array", "items": { "type": "object", "properties": { "fileId": { "type": "string" }, "originalName": { "type": "string" }, "status": { "type": "string", "enum": [ "uploading", "ready", "failed" ] }, "byteSize": { "type": "integer", "minimum": 0, "exclusiveMinimum": false, "nullable": true }, "sha256": { "type": "string", "nullable": true }, "checksumVerification": { "type": "string", "enum": [ "whole", "part_only" ], "nullable": true, "description": "Verified fact for a ready file; null until settlement. whole verifies the complete file, while part_only verifies every multipart part." }, "contentType": { "type": "string", "nullable": true }, "lastError": { "type": "string", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "source": { "description": "`user_upload` for an upload by the owner; `session` for a Session file that an Operation of the owner's Session produced, such as an image or binary MCP tool result.", "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "user_upload" ] } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "session" ] }, "sessionId": { "type": "string", "minLength": 1, "maxLength": 64 }, "operationId": { "type": "string", "minLength": 1, "maxLength": 64 } }, "required": [ "kind", "sessionId", "operationId" ] } ] } }, "required": [ "fileId", "originalName", "status", "byteSize", "sha256", "checksumVerification", "contentType", "lastError", "createdAt", "updatedAt", "source" ] } }, "nextCursor": { "type": "string", "nullable": true } }, "required": [ "files", "nextCursor" ]}schemas/CreateNewSessionPublicSchedulerOpenApiDto
Section titled “schemas/CreateNewSessionPublicSchedulerOpenApiDto”{ "type": "object", "properties": { "title": { "type": "string", "maxLength": 255 }, "prompt": { "type": "string" }, "schedule": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "once" ] }, "runAt": { "type": "string", "format": "date-time" } }, "required": [ "kind", "runAt" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "once" ] }, "after": { "type": "string", "minLength": 1 } }, "required": [ "kind", "after" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "cron" ] }, "cronExpr": { "description": "The server trims surrounding whitespace, then enforces a 128-character maximum.", "type": "string", "minLength": 1 }, "timezone": { "type": "string", "minLength": 1 } }, "required": [ "kind", "cronExpr", "timezone" ], "additionalProperties": false } ] }, "validFrom": { "type": "string", "format": "date-time", "nullable": true }, "validUntil": { "type": "string", "format": "date-time", "nullable": true }, "delivery": { "type": "object", "properties": { "target": { "type": "string", "enum": [ "new_session" ] }, "agentTemplateId": { "type": "string", "minLength": 1 }, "acknowledgeSessionRecall": { "type": "boolean" } }, "required": [ "target", "agentTemplateId" ], "additionalProperties": false } }, "required": [ "title", "prompt", "schedule", "delivery" ], "additionalProperties": false}schemas/CreateBoundSessionPublicSchedulerOpenApiDto
Section titled “schemas/CreateBoundSessionPublicSchedulerOpenApiDto”{ "type": "object", "properties": { "title": { "type": "string", "maxLength": 255 }, "prompt": { "type": "string" }, "schedule": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "once" ] }, "runAt": { "type": "string", "format": "date-time" } }, "required": [ "kind", "runAt" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "once" ] }, "after": { "type": "string", "minLength": 1 } }, "required": [ "kind", "after" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "cron" ] }, "cronExpr": { "description": "The server trims surrounding whitespace, then enforces a 128-character maximum.", "type": "string", "minLength": 1 }, "timezone": { "type": "string", "minLength": 1 } }, "required": [ "kind", "cronExpr", "timezone" ], "additionalProperties": false } ] }, "validFrom": { "type": "string", "format": "date-time", "nullable": true }, "validUntil": { "type": "string", "format": "date-time", "nullable": true }, "delivery": { "type": "object", "properties": { "target": { "type": "string", "enum": [ "bound_session" ] }, "sessionId": { "type": "string", "minLength": 1 } }, "required": [ "target", "sessionId" ], "additionalProperties": false } }, "required": [ "title", "prompt", "schedule", "delivery" ], "additionalProperties": false}schemas/PublicSchedulerResponseOpenApiDto
Section titled “schemas/PublicSchedulerResponseOpenApiDto”{ "type": "object", "properties": { "scheduler": { "type": "object", "properties": { "schedulerId": { "type": "string" }, "ownerUserId": { "type": "string" }, "organizationId": { "type": "string" }, "title": { "type": "string" }, "prompt": { "type": "string" }, "delivery": { "type": "object", "properties": { "target": { "type": "string", "enum": [ "new_session", "bound_session" ] }, "sessionId": { "type": "string", "nullable": true }, "agentTemplateId": { "type": "string", "nullable": true }, "acknowledgeSessionRecall": { "type": "boolean" } }, "required": [ "target", "sessionId", "agentTemplateId", "acknowledgeSessionRecall" ], "additionalProperties": false }, "schedule": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "once", "cron" ] }, "cronExpr": { "type": "string", "maxLength": 128, "nullable": true }, "runAt": { "type": "string", "nullable": true }, "timezone": { "type": "string" } }, "required": [ "kind", "cronExpr", "runAt", "timezone" ], "additionalProperties": false }, "validFrom": { "type": "string", "nullable": true }, "validUntil": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": [ "enabled", "disabled" ] }, "nextFireAt": { "type": "string", "nullable": true }, "lastFiredAt": { "type": "string", "nullable": true }, "revision": { "type": "integer", "minimum": 0, "exclusiveMinimum": false }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "schedulerId", "ownerUserId", "organizationId", "title", "prompt", "delivery", "schedule", "validFrom", "validUntil", "status", "nextFireAt", "lastFiredAt", "revision", "createdAt", "updatedAt" ], "additionalProperties": false } }, "required": [ "scheduler" ], "additionalProperties": false}schemas/OrganizationSchedulerListResponseOpenApiDto
Section titled “schemas/OrganizationSchedulerListResponseOpenApiDto”{ "type": "object", "properties": { "schedulers": { "type": "array", "items": { "type": "object", "properties": { "schedulerId": { "type": "string" }, "ownerUserId": { "type": "string" }, "organizationId": { "type": "string" }, "title": { "type": "string" }, "prompt": { "type": "string" }, "delivery": { "type": "object", "properties": { "target": { "type": "string", "enum": [ "new_session", "bound_session" ] }, "sessionId": { "type": "string", "nullable": true }, "agentTemplateId": { "type": "string", "nullable": true }, "acknowledgeSessionRecall": { "type": "boolean" } }, "required": [ "target", "sessionId", "agentTemplateId", "acknowledgeSessionRecall" ] }, "schedule": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "once", "cron" ] }, "cronExpr": { "type": "string", "maxLength": 128, "nullable": true }, "runAt": { "type": "string", "nullable": true }, "timezone": { "type": "string" } }, "required": [ "kind", "cronExpr", "runAt", "timezone" ] }, "validFrom": { "type": "string", "nullable": true }, "validUntil": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": [ "enabled", "disabled", "deleted" ] }, "nextFireAt": { "type": "string", "nullable": true }, "lastFiredAt": { "type": "string", "nullable": true }, "revision": { "type": "integer", "minimum": 0, "exclusiveMinimum": false }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "schedulerId", "ownerUserId", "organizationId", "title", "prompt", "delivery", "schedule", "validFrom", "validUntil", "status", "nextFireAt", "lastFiredAt", "revision", "createdAt", "updatedAt" ] } }, "nextCursor": { "type": "string", "nullable": true } }, "required": [ "schedulers", "nextCursor" ]}schemas/UpdatePublicSchedulerOpenApiDto
Section titled “schemas/UpdatePublicSchedulerOpenApiDto”{ "type": "object", "properties": { "title": { "type": "string", "maxLength": 255 }, "prompt": { "type": "string" }, "delivery": { "oneOf": [ { "type": "object", "properties": { "target": { "type": "string", "enum": [ "new_session" ] }, "agentTemplateId": { "type": "string", "minLength": 1 }, "acknowledgeSessionRecall": { "type": "boolean" } }, "required": [ "target", "agentTemplateId" ], "additionalProperties": false }, { "type": "object", "properties": { "target": { "type": "string", "enum": [ "bound_session" ] }, "sessionId": { "type": "string", "minLength": 1 } }, "required": [ "target", "sessionId" ], "additionalProperties": false } ] }, "schedule": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "once" ] }, "runAt": { "type": "string", "format": "date-time" } }, "required": [ "kind", "runAt" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "once" ] }, "after": { "type": "string", "minLength": 1 } }, "required": [ "kind", "after" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "cron" ] }, "cronExpr": { "description": "The server trims surrounding whitespace, then enforces a 128-character maximum.", "type": "string", "minLength": 1 }, "timezone": { "type": "string", "minLength": 1 } }, "required": [ "kind", "cronExpr", "timezone" ], "additionalProperties": false } ] }, "enabled": { "type": "boolean" }, "validFrom": { "type": "string", "format": "date-time", "nullable": true }, "validUntil": { "type": "string", "format": "date-time", "nullable": true }, "snoozeUntil": { "type": "string", "format": "date-time" } }, "additionalProperties": false}schemas/PublicSchedulerFiresResponseOpenApiDto
Section titled “schemas/PublicSchedulerFiresResponseOpenApiDto”{ "type": "object", "properties": { "fires": { "type": "array", "items": { "type": "object", "properties": { "fireId": { "type": "string" }, "schedulerId": { "type": "string" }, "scheduledFor": { "type": "string", "format": "date-time" }, "executionStatus": { "type": "string", "enum": [ "pending", "completed", "failed" ] }, "execution": { "type": "object", "properties": { "prompt": { "type": "string" }, "delivery": { "type": "object", "properties": { "target": { "type": "string", "enum": [ "new_session", "bound_session" ] }, "sessionId": { "type": "string", "nullable": true }, "agentTemplateId": { "type": "string", "nullable": true }, "acknowledgeSessionRecall": { "type": "boolean" } }, "required": [ "target", "sessionId", "agentTemplateId", "acknowledgeSessionRecall" ], "additionalProperties": false } }, "required": [ "prompt", "delivery" ], "additionalProperties": false }, "result": { "type": "object", "properties": { "sessionId": { "type": "string", "nullable": true }, "turnId": { "type": "string", "nullable": true }, "messageId": { "type": "string", "nullable": true }, "failureCode": { "description": "Why the fire failed or was skipped, else null. mcp_authorization_required and session_execution_dependency_unavailable (a referenced MCP Server Registration is disabled or deleted) fail the fire at once, without retry and without starting a Turn.", "type": "string", "nullable": true }, "failureDetails": { "description": "Present only with failureCode mcp_authorization_required: the registrations whose MCP Authorization was not usable when the fire was due. The fire failed without retry and started no Turn.", "type": "object", "properties": { "registrations": { "description": "Each referenced registration whose authorization is not usable, by serverId.", "type": "array", "minItems": 1, "items": { "type": "object", "properties": { "serverId": { "description": "The MCP Server Registration that needs authorization.", "type": "string" }, "owner": { "description": "Who must authorize it: the Organization, or the Session End User.", "type": "string", "enum": [ "organization", "end_user" ] }, "reason": { "description": "missing: no usable authorization with a catalog exists; invalid: it was invalidated by an endpoint or mode change, or the server refused its credential with HTTP 401 or 403 during a Turn; revoked: its credential was revoked; insufficient_scope: the server answered 403 insufficient_scope, requiring a scope it lacks.", "type": "string", "enum": [ "missing", "invalid", "revoked", "insufficient_scope" ] } }, "required": [ "serverId", "owner", "reason" ], "additionalProperties": false } } }, "required": [ "registrations" ], "additionalProperties": false } }, "required": [ "sessionId", "turnId", "messageId", "failureCode" ], "additionalProperties": false }, "createdAt": { "type": "string", "format": "date-time" }, "settledAt": { "type": "string", "nullable": true } }, "required": [ "fireId", "schedulerId", "scheduledFor", "executionStatus", "execution", "result", "createdAt", "settledAt" ], "additionalProperties": false } }, "nextCursor": { "type": "string", "nullable": true } }, "required": [ "fires", "nextCursor" ], "additionalProperties": false}schemas/OrganizationTemplateCatalogDto
Section titled “schemas/OrganizationTemplateCatalogDto”{ "type": "object", "properties": { "models": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 64 }, "available": { "type": "boolean" } }, "required": [ "id", "available" ], "additionalProperties": false } }, "sandboxes": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 64 }, "label": { "type": "string" }, "capabilities": { "type": "array", "items": { "type": "string" } } }, "required": [ "id", "label", "capabilities" ], "additionalProperties": false } }, "skills": { "type": "array", "items": { "type": "object", "properties": { "skillId": { "type": "string", "minLength": 1, "maxLength": 64 }, "name": { "type": "string" }, "description": { "type": "string" }, "version": { "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 2147483647, "exclusiveMaximum": false }, "available": { "type": "boolean" } }, "required": [ "skillId", "name", "description", "version", "available" ], "additionalProperties": false } } }, "required": [ "models", "sandboxes", "skills" ], "additionalProperties": false}schemas/OrganizationTemplateListDto
Section titled “schemas/OrganizationTemplateListDto”{ "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 64 }, "organizationId": { "type": "string", "minLength": 1, "maxLength": 64 }, "name": { "type": "string" }, "displayName": { "type": "string" }, "sandboxProfile": { "type": "string", "minLength": 1, "maxLength": 64 }, "lifecycleStatus": { "type": "string", "enum": [ "active", "archived" ] }, "etag": { "type": "string", "pattern": "^\"cvc1\\.[A-Za-z0-9_-]{43}\"$" }, "contentDigest": { "type": "string", "pattern": "^[0-9a-f]{64}$", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "organizationId", "name", "displayName", "sandboxProfile", "lifecycleStatus", "etag", "contentDigest", "createdAt", "updatedAt" ], "additionalProperties": false } }, "hasMore": { "type": "boolean" }, "nextCursor": { "type": "string", "nullable": true }, "readAt": { "type": "string", "format": "date-time" } }, "required": [ "data", "hasMore", "nextCursor", "readAt" ], "additionalProperties": false}schemas/OrganizationTemplateCreateDto
Section titled “schemas/OrganizationTemplateCreateDto”{ "type": "object", "properties": { "displayName": { "type": "string", "minLength": 1, "maxLength": 255 }, "content": { "type": "object", "properties": { "realtime": { "type": "object", "properties": { "language": { "type": "string", "enum": [ "zh-CN", "en-US" ] } }, "required": [ "language" ], "nullable": true, "additionalProperties": false }, "standingTask": { "description": "Optional Realtime Standing Task: a live Realtime Connection of a voice-enabled Session keeps one Full Agent task with this goal running while a client is attached and the Realtime Model has no task of its own. Ignored when realtime is null and by Template Tests.", "type": "object", "properties": { "goal": { "description": "What the Full Agent does in each Standing Task Turn. Line endings are normalized and surrounding whitespace trimmed; the result must have 1 to 4000 characters, counted as UTF-16 code units.", "type": "string" } }, "required": [ "goal" ], "additionalProperties": false }, "schemaVersion": { "type": "string", "enum": [ "agent-template-content@7" ], "default": "agent-template-content@7" }, "hardware": { "description": "Retired native Hardware field. Retained for older Template payloads; writes discard its requirements.", "type": "object", "properties": { "hardwareRequirements": { "type": "array", "maxItems": 64, "items": { "type": "object", "properties": { "hardwareRequirementId": { "type": "string", "pattern": "^[a-z][a-z0-9_.-]{0,99}$" }, "label": { "type": "string", "minLength": 1, "maxLength": 255 }, "hardwareModelId": { "type": "string", "pattern": "^hmod_[0-9a-f]{32}$" } }, "required": [ "hardwareRequirementId", "label", "hardwareModelId" ], "additionalProperties": false }, "default": [] } }, "default": { "hardwareRequirements": [] }, "additionalProperties": false }, "instructions": { "type": "string", "default": "" }, "capabilities": { "type": "object", "properties": { "sessionRecall": { "type": "object", "properties": { "enabled": { "type": "boolean", "default": false } }, "default": { "enabled": false }, "additionalProperties": false } }, "default": { "sessionRecall": { "enabled": false } }, "additionalProperties": false }, "tools": { "description": "Organization-shared MCP Server and Connector references. On create, omission selects no references. On replace, omission preserves references and an explicit list replaces them.", "type": "object", "properties": { "mcp": { "type": "array", "maxItems": 64, "items": { "type": "object", "properties": { "serverId": { "type": "string", "pattern": "^(?:mcp|conn)_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "toolNames": { "description": "MCP Server Registration references only: the remote tool names this Template exposes from the registration; omit the field to expose every tool. Names absent from the registration's catalog are accepted and ignored. The list is part of the Template content and its digest, and a Session keeps the list of its Session Configuration Epoch until a Template switch. Connector references refuse this field.", "type": "array", "minItems": 1, "maxItems": 200, "items": { "type": "string", "minLength": 1, "maxLength": 128 } } }, "required": [ "serverId" ], "additionalProperties": false } } }, "required": [ "mcp" ], "additionalProperties": false }, "skills": { "type": "array", "maxItems": 100, "items": { "type": "object", "properties": { "skillId": { "type": "string", "minLength": 1, "maxLength": 64 }, "version": { "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 9007199254740991, "exclusiveMaximum": false } }, "required": [ "skillId", "version" ], "additionalProperties": false }, "default": [] }, "identity": { "type": "object", "properties": { "agentName": { "type": "string", "minLength": 1, "maxLength": 255 }, "description": { "type": "string", "maxLength": 2000, "default": "" } }, "required": [ "agentName" ], "additionalProperties": false }, "sandbox": { "type": "object", "properties": { "profileId": { "type": "string", "minLength": 1, "maxLength": 64 } }, "required": [ "profileId" ], "additionalProperties": false } }, "required": [ "realtime", "identity", "sandbox" ], "additionalProperties": false } }, "required": [ "displayName", "content" ], "additionalProperties": false}schemas/OrganizationTemplateResultDto
Section titled “schemas/OrganizationTemplateResultDto”{ "type": "object", "properties": { "template": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 64 }, "organizationId": { "type": "string", "minLength": 1, "maxLength": 64 }, "name": { "type": "string" }, "displayName": { "type": "string" }, "sandboxProfile": { "type": "string", "minLength": 1, "maxLength": 64 }, "lifecycleStatus": { "type": "string", "enum": [ "active", "archived" ] }, "etag": { "type": "string", "pattern": "^\"cvc1\\.[A-Za-z0-9_-]{43}\"$" }, "contentDigest": { "type": "string", "pattern": "^[0-9a-f]{64}$", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "organizationId", "name", "displayName", "sandboxProfile", "lifecycleStatus", "etag", "contentDigest", "createdAt", "updatedAt" ], "additionalProperties": false }, "content": { "type": "object", "properties": { "realtime": { "type": "object", "properties": { "language": { "type": "string", "enum": [ "zh-CN", "en-US" ] } }, "required": [ "language" ], "nullable": true, "additionalProperties": false }, "standingTask": { "description": "Optional Realtime Standing Task: a live Realtime Connection of a voice-enabled Session keeps one Full Agent task with this goal running while a client is attached and the Realtime Model has no task of its own. Ignored when realtime is null and by Template Tests.", "type": "object", "properties": { "goal": { "description": "What the Full Agent does in each Standing Task Turn. Line endings are normalized and surrounding whitespace trimmed; the result must have 1 to 4000 characters, counted as UTF-16 code units.", "type": "string" } }, "required": [ "goal" ], "additionalProperties": false }, "schemaVersion": { "type": "string", "enum": [ "agent-template-content@7" ], "default": "agent-template-content@7" }, "hardware": { "description": "Retired native Hardware field. Retained for older Template payloads; writes discard its requirements.", "type": "object", "properties": { "hardwareRequirements": { "type": "array", "maxItems": 64, "items": { "type": "object", "properties": { "hardwareRequirementId": { "type": "string", "pattern": "^[a-z][a-z0-9_.-]{0,99}$" }, "label": { "type": "string", "minLength": 1, "maxLength": 255 }, "hardwareModelId": { "type": "string", "pattern": "^hmod_[0-9a-f]{32}$" } }, "required": [ "hardwareRequirementId", "label", "hardwareModelId" ], "additionalProperties": false }, "default": [] } }, "default": { "hardwareRequirements": [] }, "additionalProperties": false }, "instructions": { "type": "string", "default": "" }, "capabilities": { "type": "object", "properties": { "sessionRecall": { "type": "object", "properties": { "enabled": { "type": "boolean", "default": false } }, "default": { "enabled": false }, "additionalProperties": false } }, "default": { "sessionRecall": { "enabled": false } }, "additionalProperties": false }, "tools": { "description": "Organization-shared MCP Server and Connector references. On create, omission selects no references. On replace, omission preserves references and an explicit list replaces them.", "type": "object", "properties": { "mcp": { "type": "array", "maxItems": 64, "items": { "type": "object", "properties": { "serverId": { "type": "string", "pattern": "^(?:mcp|conn)_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "toolNames": { "description": "MCP Server Registration references only: the remote tool names this Template exposes from the registration; omit the field to expose every tool. Names absent from the registration's catalog are accepted and ignored. The list is part of the Template content and its digest, and a Session keeps the list of its Session Configuration Epoch until a Template switch. Connector references refuse this field.", "type": "array", "minItems": 1, "maxItems": 200, "items": { "type": "string", "minLength": 1, "maxLength": 128 } } }, "required": [ "serverId" ], "additionalProperties": false } } }, "required": [ "mcp" ], "additionalProperties": false }, "skills": { "type": "array", "maxItems": 100, "items": { "type": "object", "properties": { "skillId": { "type": "string", "minLength": 1, "maxLength": 64 }, "version": { "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 9007199254740991, "exclusiveMaximum": false } }, "required": [ "skillId", "version" ], "additionalProperties": false }, "default": [] }, "identity": { "type": "object", "properties": { "agentName": { "type": "string", "minLength": 1, "maxLength": 255 }, "description": { "type": "string", "maxLength": 2000, "default": "" } }, "required": [ "agentName" ], "additionalProperties": false }, "sandbox": { "type": "object", "properties": { "profileId": { "type": "string", "minLength": 1, "maxLength": 64 } }, "required": [ "profileId" ], "additionalProperties": false } }, "required": [ "realtime", "identity", "sandbox" ], "nullable": true, "additionalProperties": false } }, "required": [ "template", "content" ], "additionalProperties": false}schemas/OrganizationTemplateReplaceDto
Section titled “schemas/OrganizationTemplateReplaceDto”{ "type": "object", "properties": { "displayName": { "type": "string", "minLength": 1, "maxLength": 255 }, "content": { "type": "object", "properties": { "realtime": { "type": "object", "properties": { "language": { "type": "string", "enum": [ "zh-CN", "en-US" ] } }, "required": [ "language" ], "nullable": true, "additionalProperties": false }, "standingTask": { "description": "Optional Realtime Standing Task: a live Realtime Connection of a voice-enabled Session keeps one Full Agent task with this goal running while a client is attached and the Realtime Model has no task of its own. Ignored when realtime is null and by Template Tests.", "type": "object", "properties": { "goal": { "description": "What the Full Agent does in each Standing Task Turn. Line endings are normalized and surrounding whitespace trimmed; the result must have 1 to 4000 characters, counted as UTF-16 code units.", "type": "string" } }, "required": [ "goal" ], "additionalProperties": false }, "schemaVersion": { "type": "string", "enum": [ "agent-template-content@7" ], "default": "agent-template-content@7" }, "hardware": { "description": "Retired native Hardware field. Retained for older Template payloads; writes discard its requirements.", "type": "object", "properties": { "hardwareRequirements": { "type": "array", "maxItems": 64, "items": { "type": "object", "properties": { "hardwareRequirementId": { "type": "string", "pattern": "^[a-z][a-z0-9_.-]{0,99}$" }, "label": { "type": "string", "minLength": 1, "maxLength": 255 }, "hardwareModelId": { "type": "string", "pattern": "^hmod_[0-9a-f]{32}$" } }, "required": [ "hardwareRequirementId", "label", "hardwareModelId" ], "additionalProperties": false }, "default": [] } }, "default": { "hardwareRequirements": [] }, "additionalProperties": false }, "instructions": { "type": "string", "default": "" }, "capabilities": { "type": "object", "properties": { "sessionRecall": { "type": "object", "properties": { "enabled": { "type": "boolean", "default": false } }, "default": { "enabled": false }, "additionalProperties": false } }, "default": { "sessionRecall": { "enabled": false } }, "additionalProperties": false }, "tools": { "description": "Organization-shared MCP Server and Connector references. On create, omission selects no references. On replace, omission preserves references and an explicit list replaces them.", "type": "object", "properties": { "mcp": { "type": "array", "maxItems": 64, "items": { "type": "object", "properties": { "serverId": { "type": "string", "pattern": "^(?:mcp|conn)_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "toolNames": { "description": "MCP Server Registration references only: the remote tool names this Template exposes from the registration; omit the field to expose every tool. Names absent from the registration's catalog are accepted and ignored. The list is part of the Template content and its digest, and a Session keeps the list of its Session Configuration Epoch until a Template switch. Connector references refuse this field.", "type": "array", "minItems": 1, "maxItems": 200, "items": { "type": "string", "minLength": 1, "maxLength": 128 } } }, "required": [ "serverId" ], "additionalProperties": false } } }, "required": [ "mcp" ], "additionalProperties": false }, "skills": { "type": "array", "maxItems": 100, "items": { "type": "object", "properties": { "skillId": { "type": "string", "minLength": 1, "maxLength": 64 }, "version": { "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 9007199254740991, "exclusiveMaximum": false } }, "required": [ "skillId", "version" ], "additionalProperties": false }, "default": [] }, "identity": { "type": "object", "properties": { "agentName": { "type": "string", "minLength": 1, "maxLength": 255 }, "description": { "type": "string", "maxLength": 2000, "default": "" } }, "required": [ "agentName" ], "additionalProperties": false }, "sandbox": { "type": "object", "properties": { "profileId": { "type": "string", "minLength": 1, "maxLength": 64 } }, "required": [ "profileId" ], "additionalProperties": false } }, "required": [ "realtime", "identity", "sandbox" ], "additionalProperties": false } }, "required": [ "displayName", "content" ], "additionalProperties": false}schemas/OrganizationTemplateEmptyBodyDto
Section titled “schemas/OrganizationTemplateEmptyBodyDto”{ "type": "object", "properties": {}, "additionalProperties": false}schemas/CustomerOrganizationResponseDto
Section titled “schemas/CustomerOrganizationResponseDto”{ "type": "object", "properties": { "organization": { "type": "object", "properties": { "organizationId": { "type": "string", "minLength": 1 }, "slug": { "type": "string" }, "name": { "type": "string", "nullable": true }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "organizationId", "slug", "name", "createdAt", "updatedAt" ], "additionalProperties": false } }, "required": [ "organization" ], "additionalProperties": false}schemas/CreateEndUserRequestDto
Section titled “schemas/CreateEndUserRequestDto”{ "type": "object", "properties": { "displayName": { "description": "Optional field, trimmed before enforcing 1–255 characters. Whitespace-only values are rejected.", "type": "string", "minLength": 1, "pattern": "^\\s*\\S(?:[\\s\\S]{0,253}\\S)?\\s*$" }, "externalId": { "description": "Optional field, trimmed before enforcing 1–255 characters. Whitespace-only values are rejected.", "type": "string", "minLength": 1, "pattern": "^\\s*\\S(?:[\\s\\S]{0,253}\\S)?\\s*$" } }, "additionalProperties": false}schemas/CustomerEndUserResponseDto
Section titled “schemas/CustomerEndUserResponseDto”{ "type": "object", "properties": { "user": { "type": "object", "properties": { "userId": { "type": "string" }, "organizationId": { "type": "string", "minLength": 1 }, "displayName": { "type": "string", "nullable": true }, "externalId": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": [ "active", "disabled" ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "userId", "organizationId", "displayName", "externalId", "status", "createdAt", "updatedAt" ], "additionalProperties": false } }, "required": [ "user" ], "additionalProperties": false}schemas/CustomerEndUsersResponseDto
Section titled “schemas/CustomerEndUsersResponseDto”{ "type": "object", "properties": { "users": { "type": "array", "items": { "type": "object", "properties": { "userId": { "type": "string" }, "organizationId": { "type": "string", "minLength": 1 }, "displayName": { "type": "string", "nullable": true }, "externalId": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": [ "active", "disabled" ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "userId", "organizationId", "displayName", "externalId", "status", "createdAt", "updatedAt" ], "additionalProperties": false } } }, "required": [ "users" ], "additionalProperties": false}schemas/CreateUserApiKeyBodyDto
Section titled “schemas/CreateUserApiKeyBodyDto”{ "type": "object", "properties": { "name": { "description": "Required name, trimmed before enforcing 1–100 characters. Whitespace-only names are rejected. Additional request fields are ignored.", "type": "string", "minLength": 1, "pattern": "^\\s*\\S(?:[\\s\\S]{0,98}\\S)?\\s*$" } }, "required": [ "name" ]}schemas/CreateUserApiKeyResponseDto
Section titled “schemas/CreateUserApiKeyResponseDto”{ "type": "object", "properties": { "apiKey": { "type": "object", "properties": { "apiKeyId": { "type": "string" }, "organizationId": { "type": "string" }, "userId": { "type": "string" }, "name": { "type": "string" }, "tokenPrefix": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "revoked" ] }, "createdByUserId": { "type": "string", "nullable": true }, "createdByOrganizationApiKeyId": { "type": "string", "nullable": true }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "lastUsedAt": { "type": "string", "description": "Most recent recorded use of this key. Recording is best effort, at most once per minute per key; null means no use has been recorded.", "nullable": true }, "revokedAt": { "type": "string", "nullable": true } }, "required": [ "apiKeyId", "organizationId", "userId", "name", "tokenPrefix", "status", "createdByUserId", "createdByOrganizationApiKeyId", "createdAt", "updatedAt", "lastUsedAt", "revokedAt" ], "additionalProperties": false }, "token": { "type": "string" } }, "required": [ "apiKey", "token" ], "additionalProperties": false}schemas/ListUserApiKeysResponseDto
Section titled “schemas/ListUserApiKeysResponseDto”{ "type": "object", "properties": { "apiKeys": { "type": "array", "items": { "type": "object", "properties": { "apiKeyId": { "type": "string" }, "organizationId": { "type": "string" }, "userId": { "type": "string" }, "name": { "type": "string" }, "tokenPrefix": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "revoked" ] }, "createdByUserId": { "type": "string", "nullable": true }, "createdByOrganizationApiKeyId": { "type": "string", "nullable": true }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "lastUsedAt": { "type": "string", "description": "Most recent recorded use of this key. Recording is best effort, at most once per minute per key; null means no use has been recorded.", "nullable": true }, "revokedAt": { "type": "string", "nullable": true } }, "required": [ "apiKeyId", "organizationId", "userId", "name", "tokenPrefix", "status", "createdByUserId", "createdByOrganizationApiKeyId", "createdAt", "updatedAt", "lastUsedAt", "revokedAt" ], "additionalProperties": false } } }, "required": [ "apiKeys" ], "additionalProperties": false}schemas/RevokeUserApiKeyResponseDto
Section titled “schemas/RevokeUserApiKeyResponseDto”{ "type": "object", "properties": { "apiKey": { "type": "object", "properties": { "apiKeyId": { "type": "string" }, "organizationId": { "type": "string" }, "userId": { "type": "string" }, "name": { "type": "string" }, "tokenPrefix": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "revoked" ] }, "createdByUserId": { "type": "string", "nullable": true }, "createdByOrganizationApiKeyId": { "type": "string", "nullable": true }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "lastUsedAt": { "type": "string", "description": "Most recent recorded use of this key. Recording is best effort, at most once per minute per key; null means no use has been recorded.", "nullable": true }, "revokedAt": { "type": "string", "nullable": true } }, "required": [ "apiKeyId", "organizationId", "userId", "name", "tokenPrefix", "status", "createdByUserId", "createdByOrganizationApiKeyId", "createdAt", "updatedAt", "lastUsedAt", "revokedAt" ], "additionalProperties": false } }, "required": [ "apiKey" ], "additionalProperties": false}schemas/OpenRealtimeConnectionOpenApiDto
Section titled “schemas/OpenRealtimeConnectionOpenApiDto”{ "type": "object", "properties": { "audio": { "description": "Client audio formats, chosen independently per direction; mono only. Input: pcm16 8000 or 16000 Hz (default), or opus 16000 Hz with packetDurationMs 20 (default), 40 or 60. Output: pcm16 8000, 16000 or 24000 Hz (default), or opus 24000 Hz with packetDurationMs 20 and fixed bitrate 16000, 24000 or 32000 bps (default 32000). bitrate is accepted only on opus output. PCM16 8000 Hz input is resampled to 16000 Hz, and 24000 Hz provider output to the selected lower PCM16 rate, when required; 8000 Hz has telephone quality and can reduce recognition accuracy. Anything else, or a format the configured Realtime model cannot be served with, answers 400 audio_format_unsupported with one detail per refused direction, naming its first unsupported field.", "type": "object", "properties": { "input": { "type": "object", "properties": { "encoding": { "description": "pcm16 or opus.", "type": "string", "minLength": 1, "maxLength": 32 }, "sampleRate": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "channels": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "packetDurationMs": { "description": "Opus only: the duration of each packet; one packet travels in one audio frame.", "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "bitrate": { "description": "Opus output only: fixed bitrate in bps, 16000, 24000 or 32000 (default). Rejected on input and pcm16. Unsupported numeric values answer 400 audio_format_unsupported.", "type": "number" } }, "required": [ "encoding", "sampleRate", "channels" ] }, "output": { "type": "object", "properties": { "encoding": { "description": "pcm16 or opus.", "type": "string", "minLength": 1, "maxLength": 32 }, "sampleRate": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "channels": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "packetDurationMs": { "description": "Opus only: the duration of each packet; one packet travels in one audio frame.", "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "bitrate": { "description": "Opus output only: fixed bitrate in bps, 16000, 24000 or 32000 (default). Rejected on input and pcm16. Unsupported numeric values answer 400 audio_format_unsupported.", "type": "number" } }, "required": [ "encoding", "sampleRate", "channels" ] } } }, "metadata": { "description": "Client string metadata, stored verbatim and echoed on the Realtime connection.", "type": "object", "additionalProperties": { "type": "string", "maxLength": 512 } } }}schemas/OpenRealtimeConnectionResponseOpenApiDto
Section titled “schemas/OpenRealtimeConnectionResponseOpenApiDto”{ "type": "object", "properties": { "realtimeConnection": { "description": "A Realtime connection of the Session. status connecting: admitted, but no WebSocket has connected yet; active: the realtime stream is open; paused: a task waits for the user to answer a clarification question; ended: terminal.", "type": "object", "properties": { "object": { "type": "string", "enum": [ "realtime_connection" ] }, "id": { "type": "string", "minLength": 1, "maxLength": 64 }, "sessionId": { "type": "string", "minLength": 1 }, "provider": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "region": { "type": "string", "minLength": 1, "nullable": true }, "model": { "type": "string", "minLength": 1, "nullable": true } }, "required": [ "name", "region", "model" ] }, "status": { "type": "string", "enum": [ "connecting", "active", "paused", "ended" ] }, "audio": { "type": "object", "properties": { "input": { "oneOf": [ { "type": "object", "properties": { "encoding": { "type": "string", "enum": [ "pcm16" ] }, "sampleRate": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "channels": { "type": "number", "minimum": 1, "maximum": 1 } }, "required": [ "encoding", "sampleRate", "channels" ] }, { "type": "object", "properties": { "encoding": { "type": "string", "enum": [ "opus" ] }, "sampleRate": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "channels": { "type": "number", "minimum": 1, "maximum": 1 }, "packetDurationMs": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "bitrate": { "oneOf": [ { "type": "number", "minimum": 16000, "maximum": 16000 }, { "type": "number", "minimum": 24000, "maximum": 24000 }, { "type": "number", "minimum": 32000, "maximum": 32000 } ] } }, "required": [ "encoding", "sampleRate", "channels", "packetDurationMs" ] } ] }, "output": { "oneOf": [ { "type": "object", "properties": { "encoding": { "type": "string", "enum": [ "pcm16" ] }, "sampleRate": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "channels": { "type": "number", "minimum": 1, "maximum": 1 } }, "required": [ "encoding", "sampleRate", "channels" ] }, { "type": "object", "properties": { "encoding": { "type": "string", "enum": [ "opus" ] }, "sampleRate": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "channels": { "type": "number", "minimum": 1, "maximum": 1 }, "packetDurationMs": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "bitrate": { "oneOf": [ { "type": "number", "minimum": 16000, "maximum": 16000 }, { "type": "number", "minimum": 24000, "maximum": 24000 }, { "type": "number", "minimum": 32000, "maximum": 32000 } ] } }, "required": [ "encoding", "sampleRate", "channels", "packetDurationMs" ] } ] } }, "required": [ "input", "output" ] }, "activeTaskTurnId": { "type": "string", "minLength": 1, "nullable": true }, "usage": { "type": "object", "properties": { "inputAudioSec": { "type": "number", "minimum": 0, "exclusiveMinimum": false }, "outputAudioSec": { "type": "number", "minimum": 0, "exclusiveMinimum": false }, "thoughtTokens": { "type": "integer", "minimum": 0, "exclusiveMinimum": false }, "textTokens": { "type": "integer", "minimum": 0, "exclusiveMinimum": false } }, "required": [ "inputAudioSec", "outputAudioSec", "thoughtTokens", "textTokens" ] }, "metadata": { "type": "object", "additionalProperties": { "type": "string" } }, "createdAt": { "type": "string", "minLength": 1 }, "endedAt": { "type": "string", "minLength": 1, "nullable": true } }, "required": [ "object", "id", "sessionId", "provider", "status", "audio", "activeTaskTurnId", "usage", "metadata", "createdAt", "endedAt" ] }, "websocketUrl": { "description": "WebSocket URL of /api/v1/user/sessions/{id}/realtime/ws. Open it with subprotocol tidb-link.realtime.v1 and send session.connect with connectToken as the first frame.", "type": "string" }, "connectToken": { "description": "One-time connect token. It authorizes exactly one session.connect on any replica and needs no API key, so a customer backend can hand it to a device.", "type": "string" }, "connectTokenExpiresAt": { "description": "When the connect token expires: 60 seconds after it was minted.", "type": "string", "format": "date-time" } }, "required": [ "realtimeConnection", "websocketUrl", "connectToken", "connectTokenExpiresAt" ]}schemas/RealtimeConnectionResponseOpenApiDto
Section titled “schemas/RealtimeConnectionResponseOpenApiDto”{ "type": "object", "properties": { "realtimeConnection": { "description": "A Realtime connection of the Session. status connecting: admitted, but no WebSocket has connected yet; active: the realtime stream is open; paused: a task waits for the user to answer a clarification question; ended: terminal.", "type": "object", "properties": { "object": { "type": "string", "enum": [ "realtime_connection" ] }, "id": { "type": "string", "minLength": 1, "maxLength": 64 }, "sessionId": { "type": "string", "minLength": 1 }, "provider": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "region": { "type": "string", "minLength": 1, "nullable": true }, "model": { "type": "string", "minLength": 1, "nullable": true } }, "required": [ "name", "region", "model" ] }, "status": { "type": "string", "enum": [ "connecting", "active", "paused", "ended" ] }, "audio": { "type": "object", "properties": { "input": { "oneOf": [ { "type": "object", "properties": { "encoding": { "type": "string", "enum": [ "pcm16" ] }, "sampleRate": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "channels": { "type": "number", "minimum": 1, "maximum": 1 } }, "required": [ "encoding", "sampleRate", "channels" ] }, { "type": "object", "properties": { "encoding": { "type": "string", "enum": [ "opus" ] }, "sampleRate": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "channels": { "type": "number", "minimum": 1, "maximum": 1 }, "packetDurationMs": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "bitrate": { "oneOf": [ { "type": "number", "minimum": 16000, "maximum": 16000 }, { "type": "number", "minimum": 24000, "maximum": 24000 }, { "type": "number", "minimum": 32000, "maximum": 32000 } ] } }, "required": [ "encoding", "sampleRate", "channels", "packetDurationMs" ] } ] }, "output": { "oneOf": [ { "type": "object", "properties": { "encoding": { "type": "string", "enum": [ "pcm16" ] }, "sampleRate": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "channels": { "type": "number", "minimum": 1, "maximum": 1 } }, "required": [ "encoding", "sampleRate", "channels" ] }, { "type": "object", "properties": { "encoding": { "type": "string", "enum": [ "opus" ] }, "sampleRate": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "channels": { "type": "number", "minimum": 1, "maximum": 1 }, "packetDurationMs": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "bitrate": { "oneOf": [ { "type": "number", "minimum": 16000, "maximum": 16000 }, { "type": "number", "minimum": 24000, "maximum": 24000 }, { "type": "number", "minimum": 32000, "maximum": 32000 } ] } }, "required": [ "encoding", "sampleRate", "channels", "packetDurationMs" ] } ] } }, "required": [ "input", "output" ] }, "activeTaskTurnId": { "type": "string", "minLength": 1, "nullable": true }, "usage": { "type": "object", "properties": { "inputAudioSec": { "type": "number", "minimum": 0, "exclusiveMinimum": false }, "outputAudioSec": { "type": "number", "minimum": 0, "exclusiveMinimum": false }, "thoughtTokens": { "type": "integer", "minimum": 0, "exclusiveMinimum": false }, "textTokens": { "type": "integer", "minimum": 0, "exclusiveMinimum": false } }, "required": [ "inputAudioSec", "outputAudioSec", "thoughtTokens", "textTokens" ] }, "metadata": { "type": "object", "additionalProperties": { "type": "string" } }, "createdAt": { "type": "string", "minLength": 1 }, "endedAt": { "type": "string", "minLength": 1, "nullable": true } }, "required": [ "object", "id", "sessionId", "provider", "status", "audio", "activeTaskTurnId", "usage", "metadata", "createdAt", "endedAt" ] } }, "required": [ "realtimeConnection" ]}schemas/RealtimeConnectGrantOpenApiDto
Section titled “schemas/RealtimeConnectGrantOpenApiDto”{ "type": "object", "properties": { "websocketUrl": { "description": "WebSocket URL of /api/v1/user/sessions/{id}/realtime/ws. Open it with subprotocol tidb-link.realtime.v1 and send session.connect with connectToken as the first frame.", "type": "string" }, "connectToken": { "description": "One-time connect token. It authorizes exactly one session.connect on any replica and needs no API key, so a customer backend can hand it to a device.", "type": "string" }, "connectTokenExpiresAt": { "description": "When the connect token expires: 60 seconds after it was minted.", "type": "string", "format": "date-time" } }, "required": [ "websocketUrl", "connectToken", "connectTokenExpiresAt" ]}schemas/OrganizationBillingUsageAggregateResponseOpenApiDto
Section titled “schemas/OrganizationBillingUsageAggregateResponseOpenApiDto”{ "type": "object", "properties": { "range": { "type": "object", "properties": { "from": { "type": "string" }, "to": { "type": "string" }, "interval": { "type": "string", "enum": [ "hour", "day", "week", "month" ] } }, "required": [ "from", "to", "interval" ] }, "factCompleteness": { "type": "object", "properties": { "status": { "description": "Completeness of durable LLM and sandbox usage facts. Valuation completeness is reported separately.", "type": "string", "enum": [ "complete", "incomplete" ] }, "projectedFactCount": { "type": "integer" }, "pendingIntentCount": { "type": "integer" }, "indeterminateIntentCount": { "type": "integer" }, "failedIntentCount": { "type": "integer" }, "byKind": { "type": "object", "additionalProperties": { "type": "object", "properties": { "status": { "description": "Completeness of durable LLM and sandbox usage facts. Valuation completeness is reported separately.", "type": "string", "enum": [ "complete", "incomplete" ] }, "projectedFactCount": { "type": "integer" }, "pendingIntentCount": { "type": "integer" }, "indeterminateIntentCount": { "type": "integer" }, "failedIntentCount": { "type": "integer" } }, "required": [ "status", "projectedFactCount", "pendingIntentCount", "indeterminateIntentCount", "failedIntentCount" ] } } }, "required": [ "status", "projectedFactCount", "pendingIntentCount", "indeterminateIntentCount", "failedIntentCount", "byKind" ] }, "totals": { "type": "object", "properties": { "currency": { "type": "string", "enum": [ "USD", "CNY" ] }, "totalCostMicros": { "description": "Platform-borne priced cost only.", "type": "integer" }, "llmCostMicros": { "description": "Platform-borne priced LLM cost only.", "type": "integer" }, "sandboxCostMicros": { "description": "Platform-borne priced sandbox cost only.", "type": "integer" }, "webSearchCostMicros": { "description": "Platform-borne priced web-search cost only.", "type": "integer" }, "costByBearer": { "description": "Priced costs split by who bears them. No combined total across bearer groups is provided.", "type": "object", "properties": { "platform": { "type": "object", "properties": { "totalCostMicros": { "type": "integer" }, "llmCostMicros": { "type": "integer" }, "sandboxCostMicros": { "type": "integer" }, "webSearchCostMicros": { "type": "integer" } }, "required": [ "totalCostMicros", "llmCostMicros", "sandboxCostMicros", "webSearchCostMicros" ] }, "customer": { "type": "object", "properties": { "totalCostMicros": { "type": "integer" }, "llmCostMicros": { "type": "integer" }, "sandboxCostMicros": { "type": "integer" }, "webSearchCostMicros": { "type": "integer" } }, "required": [ "totalCostMicros", "llmCostMicros", "sandboxCostMicros", "webSearchCostMicros" ] }, "unknown": { "type": "object", "properties": { "totalCostMicros": { "type": "integer" }, "llmCostMicros": { "type": "integer" }, "sandboxCostMicros": { "type": "integer" }, "webSearchCostMicros": { "type": "integer" } }, "required": [ "totalCostMicros", "llmCostMicros", "sandboxCostMicros", "webSearchCostMicros" ] } }, "required": [ "platform", "customer", "unknown" ] }, "organizationMachineCostMicros": { "description": "Platform-borne priced cost attributed to Organization-machine activity only.", "type": "integer" }, "llmRequestCount": { "type": "integer" }, "unknownLlmRequestCount": { "type": "integer" }, "sandboxUsageCount": { "type": "integer" }, "webSearchRequestCount": { "type": "integer" }, "unsettledCount": { "type": "integer" }, "inputTokens": { "type": "integer" }, "cachedInputTokens": { "type": "integer" }, "outputTokens": { "type": "integer" }, "unpricedLlmTokens": { "description": "Raw token subtotals for unpriced LLM facts. Cached input is a subset of input tokens.", "type": "object", "properties": { "inputTokens": { "type": "integer" }, "cachedInputTokens": { "type": "integer" }, "outputTokens": { "type": "integer" } }, "required": [ "inputTokens", "cachedInputTokens", "outputTokens" ] }, "sandboxDurationSeconds": { "type": "integer" }, "valuation": { "type": "object", "properties": { "status": { "description": "Complete only when every usage fact in this aggregate is priced.", "type": "string", "enum": [ "complete", "incomplete" ] }, "pricedUsageCount": { "type": "integer" }, "unpricedUsageCount": { "type": "integer" }, "pricedCostMicros": { "description": "Platform-borne priced cost only; customer-borne and unknown-bearer costs are excluded.", "type": "integer" }, "byKind": { "type": "object", "additionalProperties": { "type": "object", "properties": { "status": { "description": "Complete only when every usage fact in this aggregate is priced.", "type": "string", "enum": [ "complete", "incomplete" ] }, "pricedUsageCount": { "type": "integer" }, "unpricedUsageCount": { "type": "integer" }, "pricedCostMicros": { "description": "Platform-borne priced cost only; customer-borne and unknown-bearer costs are excluded.", "type": "integer" } }, "required": [ "status", "pricedUsageCount", "unpricedUsageCount", "pricedCostMicros" ] } } }, "required": [ "status", "pricedUsageCount", "unpricedUsageCount", "pricedCostMicros", "byKind" ] }, "attribution": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "complete", "incomplete" ] }, "classifiedUsageCount": { "type": "integer" }, "userLevelUsageCount": { "type": "integer" }, "systemUsageCount": { "type": "integer" }, "unattributedUsageCount": { "type": "integer" }, "byKind": { "type": "object", "additionalProperties": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "complete", "incomplete" ] }, "classifiedUsageCount": { "type": "integer" }, "userLevelUsageCount": { "type": "integer" }, "systemUsageCount": { "type": "integer" }, "unattributedUsageCount": { "type": "integer" } }, "required": [ "status", "classifiedUsageCount", "userLevelUsageCount", "systemUsageCount", "unattributedUsageCount" ] } } }, "required": [ "status", "classifiedUsageCount", "userLevelUsageCount", "systemUsageCount", "unattributedUsageCount", "byKind" ] } }, "required": [ "currency", "totalCostMicros", "llmCostMicros", "sandboxCostMicros", "webSearchCostMicros", "costByBearer", "organizationMachineCostMicros", "llmRequestCount", "unknownLlmRequestCount", "sandboxUsageCount", "webSearchRequestCount", "unsettledCount", "inputTokens", "cachedInputTokens", "outputTokens", "unpricedLlmTokens", "sandboxDurationSeconds", "valuation", "attribution" ] }, "llm": { "type": "object", "properties": { "aggregates": { "type": "array", "items": { "type": "object", "properties": { "costBearer": { "description": "The single cost bearer represented by this aggregate row.", "type": "string", "enum": [ "platform", "customer", "unknown" ] }, "provider": { "type": "string" }, "model": { "type": "string" }, "requestPurpose": { "type": "string", "enum": [ "agent_turn", "compaction", "auto_title", "manual_title", "asr", "voice_realtime" ] }, "principalBucket": { "type": "string", "enum": [ "human", "user_api_key", "organization_user", "organization_machine" ] }, "requestCount": { "type": "integer" }, "unknownRequestCount": { "type": "integer" }, "costMicros": { "type": "integer" }, "inputTokens": { "type": "integer" }, "cachedInputTokens": { "type": "integer" }, "outputTokens": { "type": "integer" }, "valuation": { "type": "object", "properties": { "status": { "description": "Complete only when every usage fact in this aggregate is priced.", "type": "string", "enum": [ "complete", "incomplete" ] }, "pricedUsageCount": { "type": "integer" }, "unpricedUsageCount": { "type": "integer" }, "pricedCostMicros": { "description": "Sum of priced usage facts only; unpriced facts are excluded rather than treated as zero.", "type": "integer" } }, "required": [ "status", "pricedUsageCount", "unpricedUsageCount", "pricedCostMicros" ] } }, "required": [ "costBearer", "provider", "model", "requestPurpose", "principalBucket", "requestCount", "unknownRequestCount", "costMicros", "inputTokens", "cachedInputTokens", "outputTokens", "valuation" ] } } }, "required": [ "aggregates" ] }, "sandbox": { "type": "object", "properties": { "aggregates": { "type": "array", "items": { "type": "object", "properties": { "costBearer": { "description": "The single cost bearer represented by this aggregate row.", "type": "string", "enum": [ "platform", "customer", "unknown" ] }, "provider": { "type": "string", "enum": [ "e2b", "tencent_ags", "run9" ] }, "profileId": { "type": "string" }, "specKey": { "type": "string" }, "principalBucket": { "type": "string", "enum": [ "human", "user_api_key", "organization_user", "organization_machine" ] }, "usageCount": { "type": "integer" }, "settledUsageCount": { "type": "integer" }, "unsettledCount": { "type": "integer" }, "costMicros": { "type": "integer" }, "durationSeconds": { "type": "integer" }, "valuation": { "type": "object", "properties": { "status": { "description": "Complete only when every usage fact in this aggregate is priced.", "type": "string", "enum": [ "complete", "incomplete" ] }, "pricedUsageCount": { "type": "integer" }, "unpricedUsageCount": { "type": "integer" }, "pricedCostMicros": { "description": "Sum of priced usage facts only; unpriced facts are excluded rather than treated as zero.", "type": "integer" } }, "required": [ "status", "pricedUsageCount", "unpricedUsageCount", "pricedCostMicros" ] } }, "required": [ "costBearer", "provider", "profileId", "specKey", "principalBucket", "usageCount", "settledUsageCount", "unsettledCount", "costMicros", "durationSeconds", "valuation" ] } } }, "required": [ "aggregates" ] }, "webSearch": { "type": "object", "properties": { "aggregates": { "type": "array", "items": { "type": "object", "properties": { "costBearer": { "description": "The single cost bearer represented by this aggregate row.", "type": "string", "enum": [ "platform", "customer", "unknown" ] }, "provider": { "type": "string", "enum": [ "exa" ] }, "searchType": { "type": "string", "enum": [ "auto" ] }, "principalBucket": { "type": "string", "enum": [ "human", "user_api_key", "organization_user", "organization_machine" ] }, "requestCount": { "type": "integer" }, "requestedResultCount": { "type": "integer" }, "returnedResultCount": { "type": "integer" }, "costMicros": { "type": "integer" }, "valuation": { "type": "object", "properties": { "status": { "description": "Complete only when every usage fact in this aggregate is priced.", "type": "string", "enum": [ "complete", "incomplete" ] }, "pricedUsageCount": { "type": "integer" }, "unpricedUsageCount": { "type": "integer" }, "pricedCostMicros": { "description": "Sum of priced usage facts only; unpriced facts are excluded rather than treated as zero.", "type": "integer" } }, "required": [ "status", "pricedUsageCount", "unpricedUsageCount", "pricedCostMicros" ] } }, "required": [ "costBearer", "provider", "searchType", "principalBucket", "requestCount", "requestedResultCount", "returnedResultCount", "costMicros", "valuation" ] } } }, "required": [ "aggregates" ] }, "series": { "type": "array", "items": { "type": "object", "properties": { "bucketStart": { "type": "string", "format": "date-time" }, "costMicros": { "description": "Platform-borne priced cost only.", "type": "integer" }, "llmCostMicros": { "description": "Platform-borne priced LLM cost only.", "type": "integer" }, "sandboxCostMicros": { "description": "Platform-borne priced sandbox cost only.", "type": "integer" }, "webSearchCostMicros": { "description": "Platform-borne priced web-search cost only.", "type": "integer" }, "unknownLlmRequestCount": { "type": "integer" }, "unsettledCount": { "type": "integer" }, "breakdown": { "description": "Sparse rows grouped by cost bearer. The three arrays contain at most 50 rows in total per bucket.", "type": "object", "properties": { "platform": { "type": "array", "maxItems": 50, "items": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "llm" ] }, "provider": { "type": "string" }, "costMicros": { "type": "integer" }, "truncatedCombinations": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "model": { "type": "string" }, "usage": { "type": "object", "properties": { "inputTokens": { "type": "integer" }, "cachedInputTokens": { "type": "integer" }, "outputTokens": { "type": "integer" } }, "required": [ "inputTokens", "cachedInputTokens", "outputTokens" ] } }, "required": [ "kind", "provider", "costMicros", "usage" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "sandbox" ] }, "provider": { "type": "string" }, "costMicros": { "type": "integer" }, "truncatedCombinations": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "usage": { "type": "object", "properties": { "durationSeconds": { "type": "integer" }, "usageCount": { "type": "integer" } }, "required": [ "durationSeconds", "usageCount" ] } }, "required": [ "kind", "provider", "costMicros", "usage" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "web_search" ] }, "provider": { "type": "string" }, "costMicros": { "type": "integer" }, "truncatedCombinations": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "usage": { "type": "object", "properties": { "requestCount": { "type": "integer" } }, "required": [ "requestCount" ] } }, "required": [ "kind", "provider", "costMicros", "usage" ] } ] } }, "customer": { "type": "array", "maxItems": 50, "items": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "llm" ] }, "provider": { "type": "string" }, "costMicros": { "type": "integer" }, "truncatedCombinations": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "model": { "type": "string" }, "usage": { "type": "object", "properties": { "inputTokens": { "type": "integer" }, "cachedInputTokens": { "type": "integer" }, "outputTokens": { "type": "integer" } }, "required": [ "inputTokens", "cachedInputTokens", "outputTokens" ] } }, "required": [ "kind", "provider", "costMicros", "usage" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "sandbox" ] }, "provider": { "type": "string" }, "costMicros": { "type": "integer" }, "truncatedCombinations": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "usage": { "type": "object", "properties": { "durationSeconds": { "type": "integer" }, "usageCount": { "type": "integer" } }, "required": [ "durationSeconds", "usageCount" ] } }, "required": [ "kind", "provider", "costMicros", "usage" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "web_search" ] }, "provider": { "type": "string" }, "costMicros": { "type": "integer" }, "truncatedCombinations": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "usage": { "type": "object", "properties": { "requestCount": { "type": "integer" } }, "required": [ "requestCount" ] } }, "required": [ "kind", "provider", "costMicros", "usage" ] } ] } }, "unknown": { "type": "array", "maxItems": 50, "items": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "llm" ] }, "provider": { "type": "string" }, "costMicros": { "type": "integer" }, "truncatedCombinations": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "model": { "type": "string" }, "usage": { "type": "object", "properties": { "inputTokens": { "type": "integer" }, "cachedInputTokens": { "type": "integer" }, "outputTokens": { "type": "integer" } }, "required": [ "inputTokens", "cachedInputTokens", "outputTokens" ] } }, "required": [ "kind", "provider", "costMicros", "usage" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "sandbox" ] }, "provider": { "type": "string" }, "costMicros": { "type": "integer" }, "truncatedCombinations": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "usage": { "type": "object", "properties": { "durationSeconds": { "type": "integer" }, "usageCount": { "type": "integer" } }, "required": [ "durationSeconds", "usageCount" ] } }, "required": [ "kind", "provider", "costMicros", "usage" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "web_search" ] }, "provider": { "type": "string" }, "costMicros": { "type": "integer" }, "truncatedCombinations": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "usage": { "type": "object", "properties": { "requestCount": { "type": "integer" } }, "required": [ "requestCount" ] } }, "required": [ "kind", "provider", "costMicros", "usage" ] } ] } } }, "required": [ "platform", "customer", "unknown" ] }, "valuation": { "type": "object", "properties": { "status": { "description": "Complete only when every usage fact in this aggregate is priced.", "type": "string", "enum": [ "complete", "incomplete" ] }, "pricedUsageCount": { "type": "integer" }, "unpricedUsageCount": { "type": "integer" }, "pricedCostMicros": { "description": "Platform-borne priced cost only; customer-borne and unknown-bearer costs are excluded.", "type": "integer" } }, "required": [ "status", "pricedUsageCount", "unpricedUsageCount", "pricedCostMicros" ] } }, "required": [ "bucketStart", "costMicros", "llmCostMicros", "sandboxCostMicros", "webSearchCostMicros", "unknownLlmRequestCount", "unsettledCount", "breakdown", "valuation" ] } } }, "required": [ "range", "factCompleteness", "totals", "llm", "sandbox", "webSearch", "series" ]}schemas/OrganizationSkillListDto
Section titled “schemas/OrganizationSkillListDto”{ "type": "object", "properties": { "skills": { "type": "array", "items": { "type": "object", "properties": { "skillId": { "type": "string", "minLength": 1, "maxLength": 64 }, "name": { "type": "string" }, "description": { "type": "string" }, "revision": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "headVersion": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "skillId", "name", "description", "revision", "headVersion", "createdAt", "updatedAt" ] } }, "nextCursor": { "type": "string", "nullable": true } }, "required": [ "skills", "nextCursor" ]}schemas/OrganizationSkillFilesDto
Section titled “schemas/OrganizationSkillFilesDto”{ "type": "object", "properties": { "skillId": { "type": "string", "minLength": 1, "maxLength": 64 }, "version": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "nextCursor": { "type": "string", "nullable": true }, "files": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "kind": { "type": "string", "enum": [ "file", "directory" ] }, "size": { "type": "integer", "minimum": 0, "exclusiveMinimum": false }, "compressedSize": { "type": "integer", "minimum": 0, "exclusiveMinimum": false } }, "required": [ "path", "kind", "size", "compressedSize" ] } } }, "required": [ "skillId", "version", "nextCursor", "files" ]}schemas/OrganizationSkillDetailDto
Section titled “schemas/OrganizationSkillDetailDto”{ "type": "object", "properties": { "skill": { "type": "object", "properties": { "skillId": { "type": "string", "minLength": 1, "maxLength": 64 }, "name": { "type": "string" }, "description": { "type": "string" }, "revision": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "headVersion": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "skillId", "name", "description", "revision", "headVersion", "createdAt", "updatedAt" ] }, "versions": { "type": "array", "items": { "type": "object", "properties": { "version": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "name": { "type": "string" }, "description": { "type": "string" }, "packageDigest": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "rawSize": { "type": "integer", "minimum": 0, "exclusiveMinimum": false }, "extractedSize": { "type": "integer", "minimum": 0, "exclusiveMinimum": false }, "loadable": { "type": "boolean" }, "portable": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "version", "name", "description", "packageDigest", "rawSize", "extractedSize", "loadable", "portable", "createdAt" ] } }, "nextCursor": { "type": "string", "nullable": true } }, "required": [ "skill", "versions", "nextCursor" ]}responses/Error
Section titled “responses/Error”{ "description": "Standard Agent Service error envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }}parameters/IdPath
Section titled “parameters/IdPath”{ "name": "id", "in": "path", "required": true, "schema": { "type": "string" }}parameters/TurnIdPath
Section titled “parameters/TurnIdPath”{ "name": "turnId", "in": "path", "required": true, "schema": { "type": "string" }}