[ { "provider": "anthropic", "name": "thinking (content block)", "kind": "content_block", "description": "Reasoning block preceding text; thinking text is a summary (or '' when display omitted); signature = encrypted full reasoning, opaque, must be passed back unchanged with tool results.", "schema": { "type": "thinking", "thinking": "string (summary or empty)", "signature": "string (opaque, long on Claude 4+)" }, "sdk_types": { "python": "ThinkingBlock / ThinkingBlockParam / BetaThinkingBlock", "node": "ThinkingBlock" }, "status": [ "DOCUMENTED", "LIVE_VERIFIED" ], "example": { "type": "thinking", "thinking": "The user is asking for 2+2, which equals 4…", "signature": "EtQCCpoBCBEYAipAGx2p…" }, "notes": null, "verification": { "method": "live_api", "verified_at": "2026-09-18", "result": "success", "http_status": 200, "request_note": "think_01 on Haiku" }, "sources": [ { "url": "https://platform.claude.com/docs/en/build-with-claude/thinking", "retrieved_at": "2026-09-18" } ], "last_verified": "2026-09-18", "_fragment": "generated/fragments/objects/anthropic-advanced-objects.json" }, { "provider": "anthropic", "name": "redacted_thinking (content block)", "kind": "content_block", "description": "Safety-redacted reasoning: encrypted data, no text. Must be round-tripped unchanged; filtering by type=='thinking' alone breaks tool-use turns.", "schema": { "type": "redacted_thinking", "data": "string (opaque)" }, "sdk_types": { "python": "RedactedThinkingBlock / RedactedThinkingBlockParam", "node": "RedactedThinkingBlock" }, "status": [ "DOCUMENTED" ], "example": null, "notes": null, "verification": null, "sources": [ { "url": "https://platform.claude.com/docs/en/build-with-claude/thinking", "retrieved_at": "2026-09-18" } ], "last_verified": "2026-09-18", "_fragment": "generated/fragments/objects/anthropic-advanced-objects.json" }, { "provider": "anthropic", "name": "ThinkingConfig (request)", "kind": "request_object", "description": "thinking parameter variants.", "schema": { "oneOf": [ { "type": "enabled", "budget_tokens": "int >= 1024, < max_tokens", "display": "summarized|omitted|updates(beta)", "block_binding": "beta" }, { "type": "adaptive", "display": "summarized|omitted|updates(beta)", "block_binding": "beta" }, { "type": "disabled" } ] }, "sdk_types": { "python": "ThinkingConfigEnabled / ThinkingConfigAdaptive / ThinkingConfigDisabled (+Beta*)", "node": "ThinkingConfigParam" }, "status": [ "DOCUMENTED", "LIVE_VERIFIED" ], "example": null, "notes": null, "verification": { "method": "live_api", "verified_at": "2026-09-18", "result": "success", "http_status": 200, "request_note": "" }, "sources": [ { "url": "https://platform.claude.com/docs/en/build-with-claude/thinking", "retrieved_at": "2026-09-18" } ], "last_verified": "2026-09-18", "_fragment": "generated/fragments/objects/anthropic-advanced-objects.json" }, { "provider": "anthropic", "name": "compaction (content block)", "kind": "content_block", "description": "Server-written summary replacing earlier context. Threshold compaction: content string (null if the summarizer called a tool), appears at the start of the assistant response. On-demand (compact-2026-09-04): signed block with signature, returned alone with stop_reason 'compaction'; must be sent first in messages on later requests. encrypted_content is opaque round-trip metadata. cache_control allowed.", "schema": { "type": "compaction", "content": "string | null", "signature": "string (on-demand beta)", "encrypted_content": "string | null", "cache_control": "CacheControlEphemeral?" }, "sdk_types": { "python": "BetaCompactionBlock / BetaCompactionBlockParam", "node": "BetaCompactionBlock" }, "status": [ "DOCUMENTED", "BETA", "LIVE_VERIFIED" ], "example": { "type": "compaction", "content": "Ada introduced herself and shared that she likes the color teal…", "signature": "CAISzAMKHggRGALyARdjb21wYWN0aW9uX3NpZ25hdHVyZV92MRIM…" }, "notes": null, "verification": { "method": "live_api", "verified_at": "2026-09-18", "result": "success", "http_status": 200, "request_note": "compact_04 on Sonnet 5" }, "sources": [ { "url": "https://platform.claude.com/docs/en/build-with-claude/compaction", "retrieved_at": "2026-09-18" } ], "last_verified": "2026-09-18", "_fragment": "generated/fragments/objects/anthropic-advanced-objects.json" }, { "provider": "anthropic", "name": "CompactionConfig (request)", "kind": "request_object", "description": "Top-level compaction parameter (compact-2026-09-04).", "schema": { "type": "summarize", "instructions": "string <= 16384 | null" }, "sdk_types": { "python": "BetaCompactionConfig" }, "status": [ "DOCUMENTED", "BETA", "LIVE_VERIFIED" ], "example": null, "notes": null, "verification": { "method": "live_api", "verified_at": "2026-09-18", "result": "success", "http_status": 200, "request_note": "" }, "sources": [ { "url": "https://platform.claude.com/docs/en/build-with-claude/compaction", "retrieved_at": "2026-09-18" } ], "last_verified": "2026-09-18", "_fragment": "generated/fragments/objects/anthropic-advanced-objects.json" }, { "provider": "anthropic", "name": "ContextManagementConfig (request)", "kind": "request_object", "description": "context_management.edits strategies.", "schema": { "edits": [ { "type": "clear_tool_uses_20250919", "trigger": { "type": "input_tokens|tool_uses", "value": "int>=1" }, "keep": { "type": "tool_uses", "value": "int>=0" }, "clear_at_least": { "type": "input_tokens", "value": "int>=0" }, "exclude_tools": [ "string" ], "clear_tool_inputs": "bool | string[]" }, { "type": "clear_thinking_20251015", "keep": "{type:'thinking_turns', value>=1} | {type:'all'} | 'all'" }, { "type": "compact_20260112", "trigger": { "type": "input_tokens", "value": "int>=50000" }, "pause_after_compaction": "bool", "instructions": "string|null" } ] }, "sdk_types": { "python": "BetaContextManagementConfig, BetaClearToolUses20250919Edit, BetaClearThinking20251015Edit, BetaCompact20260112Edit, BetaInputTokensTrigger, BetaToolUsesTrigger, BetaThinkingTurns", "node": "same names" }, "status": [ "DOCUMENTED", "BETA", "LIVE_VERIFIED" ], "example": null, "notes": null, "verification": { "method": "live_api", "verified_at": "2026-09-18", "result": "success", "http_status": 200, "request_note": "" }, "sources": [ { "url": "https://platform.claude.com/docs/en/build-with-claude/context-editing", "retrieved_at": "2026-09-18" } ], "last_verified": "2026-09-18", "_fragment": "generated/fragments/objects/anthropic-advanced-objects.json" }, { "provider": "anthropic", "name": "context_management (response)", "kind": "response_field", "description": "Edits applied during the request (also in the final message_delta when streaming, and in count_tokens as {original_input_tokens}).", "schema": { "applied_edits": [ { "type": "clear_tool_uses_20250919", "cleared_tool_uses": "int", "cleared_input_tokens": "int" }, { "type": "clear_thinking_20251015", "cleared_thinking_turns": "int", "cleared_input_tokens": "int" } ] }, "sdk_types": { "python": "BetaContextManagementResponse, BetaClearToolUses20250919EditResponse, BetaClearThinking20251015EditResponse" }, "status": [ "DOCUMENTED", "BETA", "LIVE_VERIFIED" ], "example": { "applied_edits": [ { "type": "clear_tool_uses_20250919", "cleared_input_tokens": 174, "cleared_tool_uses": 2 } ] }, "notes": null, "verification": { "method": "live_api", "verified_at": "2026-09-18", "result": "success", "http_status": 200, "request_note": "ctxedit_01; count_tokens -> input_tokens 838, context_management.original_input_tokens 928" }, "sources": [ { "url": "https://platform.claude.com/docs/en/build-with-claude/context-editing", "retrieved_at": "2026-09-18" } ], "last_verified": "2026-09-18", "_fragment": "generated/fragments/objects/anthropic-advanced-objects.json" }, { "provider": "anthropic", "name": "input_transformations (response)", "kind": "response_field", "description": "Beta thinking-binding-controls-2026-08-01: list of thinking blocks the API dropped or tolerated. [] when nothing happened. Streaming: on message_start (and message_delta after a mid-stream fallback).", "schema": { "input_transformations": [ { "type": "thinking_dropped | thinking_mismatch_allowed", "path": "messages.1.content.0", "reason": "prefix_binding_mismatch | model_binding_mismatch" } ] }, "sdk_types": { "python": "BetaInputTransformation" }, "status": [ "DOCUMENTED", "BETA", "LIVE_VERIFIED" ], "example": { "input_transformations": [] }, "notes": null, "verification": { "method": "live_api", "verified_at": "2026-09-18", "result": "success", "http_status": 200, "request_note": "adaptive_07 on Sonnet 5 -> []" }, "sources": [ { "url": "https://platform.claude.com/docs/en/build-with-claude/preserved-thinking", "retrieved_at": "2026-09-18" } ], "last_verified": "2026-09-18", "_fragment": "generated/fragments/objects/anthropic-advanced-objects.json" }, { "provider": "anthropic", "name": "usage (cache & thinking fields)", "kind": "response_field", "description": "Token accounting. input_tokens = tokens after the last cache breakpoint only; total input = input + cache_read + cache_creation. cache_creation_input_tokens == sum of cache_creation.*. output_tokens_details.thinking_tokens = billed reasoning tokens (final message_delta when streaming). speed present when the fast-mode beta is active. iterations present with compaction/task-budget betas (sum for billing; compaction entries are excluded from top-level counts). inference_geo ('global' | 'not_available' | region) observed but not documented on these pages.", "schema": { "input_tokens": "int", "cache_creation_input_tokens": "int|null", "cache_read_input_tokens": "int|null", "cache_creation": { "ephemeral_5m_input_tokens": "int", "ephemeral_1h_input_tokens": "int" }, "output_tokens": "int", "output_tokens_details": { "thinking_tokens": "int" }, "server_tool_use": { "web_search_requests": "int" }, "service_tier": "standard|priority|batch", "speed": "standard|fast (beta)", "iterations": [ { "type": "message|compaction", "input_tokens": "int", "output_tokens": "int", "cache_read_input_tokens": "int", "cache_creation_input_tokens": "int", "cache_creation": {} } ], "inference_geo": "string (observed)" }, "sdk_types": { "python": "Usage, CacheCreation, OutputTokensDetails, BetaUsage, BetaCompactionIterationUsage", "node": "Usage" }, "status": [ "DOCUMENTED", "LIVE_VERIFIED", "LIVE_DISCOVERED" ], "example": { "input_tokens": 10, "cache_creation_input_tokens": 5809, "cache_read_input_tokens": 0, "cache_creation": { "ephemeral_5m_input_tokens": 5809, "ephemeral_1h_input_tokens": 0 }, "output_tokens": 5, "service_tier": "standard", "inference_geo": "not_available" }, "notes": null, "verification": { "method": "live_api", "verified_at": "2026-09-18", "result": "success", "http_status": 200, "request_note": "cache_01..08, think_01, compact_01/04, fast_04" }, "sources": [ { "url": "https://platform.claude.com/docs/en/build-with-claude/prompt-caching", "retrieved_at": "2026-09-18" } ], "last_verified": "2026-09-18", "_fragment": "generated/fragments/objects/anthropic-advanced-objects.json" }, { "provider": "anthropic", "object": "CacheControlEphemeral", "kind": "request", "description": "Cache breakpoint marker.", "fields": { "type": "'ephemeral'", "ttl": "'5m' (default) | '1h'" }, "status": [ "DOCUMENTED", "LIVE_VERIFIED" ], "example": null, "source": "https://platform.claude.com/docs/en/api/messages", "_fragment": "generated/fragments/objects/anthropic-messages-objects.json" }, { "provider": "anthropic", "name": "OutputConfig", "kind": "request_object", "description": "output_config container.", "schema": { "effort": "low|medium|high|xhigh|max", "format": { "type": "json_schema", "schema": "object" }, "task_budget": { "type": "tokens", "total": "int", "remaining": "int?" } }, "sdk_types": { "python": "OutputConfig, JSONOutputFormat, BetaOutputConfig, BetaJSONOutputFormat, BetaTokenTaskBudget", "node": "OutputConfig, JSONOutputFormat" }, "status": [ "DOCUMENTED", "LIVE_VERIFIED" ], "example": null, "notes": null, "verification": { "method": "live_api", "verified_at": "2026-09-18", "result": "success", "http_status": 200, "request_note": "" }, "sources": [ { "url": "https://platform.claude.com/docs/en/build-with-claude/structured-outputs", "retrieved_at": "2026-09-18" } ], "last_verified": "2026-09-18", "_fragment": "generated/fragments/objects/anthropic-advanced-objects.json" }, { "provider": "anthropic", "name": "citation: char_location", "kind": "citation", "description": "Plain-text document citation (0-indexed chars, exclusive end). From Files API text documents the citation also carries file_id and document_title null (undocumented field).", "schema": { "type": "char_location", "cited_text": "string (not billed)", "document_index": "int", "document_title": "string|null", "start_char_index": "int", "end_char_index": "int (exclusive)", "file_id": "string (observed with file sources)" }, "sdk_types": { "python": "CitationCharLocation / CitationCharLocationParam" }, "status": [ "DOCUMENTED", "LIVE_VERIFIED", "LIVE_DISCOVERED" ], "example": { "type": "char_location", "cited_text": "Grass is green.", "document_index": 0, "document_title": "Colors", "start_char_index": 17, "end_char_index": 32 }, "notes": null, "verification": { "method": "live_api", "verified_at": "2026-09-18", "result": "success", "http_status": 200, "request_note": "cite_01; files_07 adds file_id" }, "sources": [ { "url": "https://platform.claude.com/docs/en/build-with-claude/citations", "retrieved_at": "2026-09-18" } ], "last_verified": "2026-09-18", "_fragment": "generated/fragments/objects/anthropic-advanced-objects.json" }, { "provider": "anthropic", "name": "citation: page_location", "kind": "citation", "description": "PDF citation, 1-indexed pages, exclusive end.", "schema": { "type": "page_location", "cited_text": "string", "document_index": "int", "document_title": "string|null", "start_page_number": "int", "end_page_number": "int (exclusive)" }, "sdk_types": { "python": "CitationPageLocation" }, "status": [ "DOCUMENTED", "LIVE_VERIFIED" ], "example": { "type": "page_location", "cited_text": "Grass is green.", "document_index": 0, "document_title": "Colors PDF", "start_page_number": 1, "end_page_number": 2 }, "notes": null, "verification": { "method": "live_api", "verified_at": "2026-09-18", "result": "success", "http_status": 200, "request_note": "cite_04 1-page generated PDF" }, "sources": [ { "url": "https://platform.claude.com/docs/en/build-with-claude/citations", "retrieved_at": "2026-09-18" } ], "last_verified": "2026-09-18", "_fragment": "generated/fragments/objects/anthropic-advanced-objects.json" }, { "provider": "anthropic", "name": "citation: content_block_location", "kind": "citation", "description": "Custom-content document citation, block indices 0-indexed exclusive end.", "schema": { "type": "content_block_location", "cited_text": "string", "document_index": "int", "document_title": "string|null", "start_block_index": "int", "end_block_index": "int" }, "sdk_types": { "python": "CitationContentBlockLocation" }, "status": [ "DOCUMENTED", "LIVE_VERIFIED" ], "example": { "type": "content_block_location", "cited_text": "Grass is green.", "document_index": 0, "document_title": "Colors", "start_block_index": 1, "end_block_index": 2 }, "notes": null, "verification": { "method": "live_api", "verified_at": "2026-09-18", "result": "success", "http_status": 200, "request_note": "cite_03" }, "sources": [ { "url": "https://platform.claude.com/docs/en/build-with-claude/citations", "retrieved_at": "2026-09-18" } ], "last_verified": "2026-09-18", "_fragment": "generated/fragments/objects/anthropic-advanced-objects.json" }, { "provider": "anthropic", "name": "citation: search_result_location", "kind": "citation", "description": "Citation of a search_result block.", "schema": { "type": "search_result_location", "cited_text": "string", "source": "string", "title": "string|null", "search_result_index": "int", "start_block_index": "int", "end_block_index": "int" }, "sdk_types": { "python": "CitationsSearchResultLocation / CitationSearchResultLocationParam" }, "status": [ "DOCUMENTED", "LIVE_VERIFIED" ], "example": { "type": "search_result_location", "cited_text": "Grass is green.", "source": "kb://colors/1", "title": "Color facts", "search_result_index": 0, "start_block_index": 1, "end_block_index": 2 }, "notes": null, "verification": { "method": "live_api", "verified_at": "2026-09-18", "result": "success", "http_status": 200, "request_note": "cite_02" }, "sources": [ { "url": "https://platform.claude.com/docs/en/build-with-claude/search-results", "retrieved_at": "2026-09-18" } ], "last_verified": "2026-09-18", "_fragment": "generated/fragments/objects/anthropic-advanced-objects.json" }, { "provider": "anthropic", "name": "citation: web_search_result_location", "kind": "citation", "description": "Citation of a web search tool result.", "schema": { "type": "web_search_result_location", "cited_text": "string", "url": "string", "title": "string|null", "encrypted_index": "string" }, "sdk_types": { "python": "CitationsWebSearchResultLocation" }, "status": [ "DOCUMENTED" ], "example": null, "notes": null, "verification": null, "sources": [ { "url": "https://platform.claude.com/docs/en/api/messages/create", "retrieved_at": "2026-09-18" } ], "last_verified": "2026-09-18", "_fragment": "generated/fragments/objects/anthropic-advanced-objects.json" }, { "provider": "anthropic", "name": "CitationsConfig", "kind": "request_object", "description": "citations field on document / search_result blocks.", "schema": { "enabled": "boolean" }, "sdk_types": { "python": "CitationsConfigParam" }, "status": [ "DOCUMENTED", "LIVE_VERIFIED" ], "example": null, "notes": null, "verification": { "method": "live_api", "verified_at": "2026-09-18", "result": "success", "http_status": 200, "request_note": "" }, "sources": [ { "url": "https://platform.claude.com/docs/en/build-with-claude/citations", "retrieved_at": "2026-09-18" } ], "last_verified": "2026-09-18", "_fragment": "generated/fragments/objects/anthropic-advanced-objects.json" }, { "provider": "anthropic", "name": "DocumentBlockParam", "kind": "content_block", "description": "Document input block.", "schema": { "type": "document", "source": { "oneOf": [ { "type": "base64", "media_type": "application/pdf", "data": "base64" }, { "type": "text", "media_type": "text/plain", "data": "string" }, { "type": "content", "content": "string | [text|image blocks]" }, { "type": "url", "url": "string" }, { "type": "file", "file_id": "string" } ] }, "title": "string?", "context": "string?", "citations": { "enabled": "bool" }, "cache_control": "?" }, "sdk_types": { "python": "DocumentBlockParam, Base64PDFSource, PlainTextSource, ContentBlockSource, URLPDFSource, FileDocumentSource" }, "status": [ "DOCUMENTED", "LIVE_VERIFIED" ], "example": null, "notes": null, "verification": { "method": "live_api", "verified_at": "2026-09-18", "result": "success", "http_status": 200, "request_note": "" }, "sources": [ { "url": "https://platform.claude.com/docs/en/build-with-claude/pdf-support", "retrieved_at": "2026-09-18" } ], "last_verified": "2026-09-18", "_fragment": "generated/fragments/objects/anthropic-advanced-objects.json" }, { "provider": "anthropic", "name": "ImageBlockParam", "kind": "content_block", "description": "Image input block.", "schema": { "type": "image", "source": { "oneOf": [ { "type": "base64", "media_type": "image/jpeg|image/png|image/gif|image/webp", "data": "base64" }, { "type": "url", "url": "string" }, { "type": "file", "file_id": "string" } ] }, "transformations": { "oversized_image": "downsize|error" }, "cache_control": "?" }, "sdk_types": { "python": "ImageBlockParam, Base64ImageSource, URLImageSource, FileImageSource" }, "status": [ "DOCUMENTED", "LIVE_VERIFIED" ], "example": null, "notes": null, "verification": { "method": "live_api", "verified_at": "2026-09-18", "result": "success", "http_status": 200, "request_note": "" }, "sources": [ { "url": "https://platform.claude.com/docs/en/build-with-claude/vision", "retrieved_at": "2026-09-18" } ], "last_verified": "2026-09-18", "_fragment": "generated/fragments/objects/anthropic-advanced-objects.json" }, { "provider": "anthropic", "name": "SearchResultBlockParam", "kind": "content_block", "description": "RAG search result block.", "schema": { "type": "search_result", "source": "string", "title": "string", "content": [ { "type": "text", "text": "non-empty" } ], "citations": { "enabled": "bool" }, "cache_control": "?" }, "sdk_types": { "python": "SearchResultBlockParam" }, "status": [ "DOCUMENTED", "LIVE_VERIFIED" ], "example": null, "notes": null, "verification": { "method": "live_api", "verified_at": "2026-09-18", "result": "success", "http_status": 200, "request_note": "" }, "sources": [ { "url": "https://platform.claude.com/docs/en/build-with-claude/search-results", "retrieved_at": "2026-09-18" } ], "last_verified": "2026-09-18", "_fragment": "generated/fragments/objects/anthropic-advanced-objects.json" }, { "provider": "anthropic", "name": "FileMetadata", "kind": "object", "description": "Files API object. downloadable false for uploads; expires_at null unless expires_in_seconds given (absent under the legacy beta header).", "schema": { "type": "file", "id": "file_…", "created_at": "RFC3339", "filename": "string 1..500", "mime_type": "string", "size_bytes": "int", "downloadable": "bool", "expires_at": "RFC3339|null" }, "sdk_types": { "python": "FileMetadata / BetaFileMetadata", "node": "FileMetadata" }, "status": [ "DOCUMENTED", "LIVE_VERIFIED" ], "example": { "type": "file", "id": "file_01EfVkMNzn7Yw7nQk38Rz6H2", "size_bytes": 607, "created_at": "2026-09-19T01:50:34.679190Z", "expires_at": "2026-09-19T02:50:34.679190Z", "filename": "atlas.pdf", "mime_type": "application/pdf", "downloadable": false }, "notes": null, "verification": { "method": "live_api", "verified_at": "2026-09-18", "result": "success", "http_status": 200, "request_note": "files_09" }, "sources": [ { "url": "https://platform.claude.com/docs/en/api/files", "retrieved_at": "2026-09-18" } ], "last_verified": "2026-09-18", "_fragment": "generated/fragments/objects/anthropic-advanced-objects.json" }, { "provider": "anthropic", "name": "DeletedFile", "kind": "object", "description": "DELETE response.", "schema": { "id": "string", "type": "file_deleted" }, "sdk_types": { "python": "DeletedFile" }, "status": [ "DOCUMENTED", "LIVE_VERIFIED" ], "example": { "id": "file_01TqegiQ7gLB7VNsPZaqHczC", "type": "file_deleted" }, "notes": null, "verification": { "method": "live_api", "verified_at": "2026-09-18", "result": "success", "http_status": 200, "request_note": "" }, "sources": [ { "url": "https://platform.claude.com/docs/en/api/files", "retrieved_at": "2026-09-18" } ], "last_verified": "2026-09-18", "_fragment": "generated/fragments/objects/anthropic-advanced-objects.json" }, { "provider": "anthropic", "name": "FileList", "kind": "object", "description": "GET /v1/files response.", "schema": { "data": [ "FileMetadata" ], "next_page": "string|null", "(legacy header)": { "has_more": "bool", "first_id": "string", "last_id": "string" } }, "sdk_types": {}, "status": [ "DOCUMENTED", "LIVE_VERIFIED" ], "example": null, "notes": null, "verification": { "method": "live_api", "verified_at": "2026-09-18", "result": "success", "http_status": 200, "request_note": "" }, "sources": [ { "url": "https://platform.claude.com/docs/en/api/files", "retrieved_at": "2026-09-18" } ], "last_verified": "2026-09-18", "_fragment": "generated/fragments/objects/anthropic-advanced-objects.json" }, { "provider": "anthropic", "name": "tool_use.caller (response)", "kind": "response_field", "description": "Observed on tool_use blocks: caller {type:'direct'} (direct call vs code_execution_20250825 / code_execution_20260120 programmatic callers per the reference).", "schema": { "caller": { "type": "direct | code_execution_20250825 | code_execution_20260120" } }, "sdk_types": {}, "status": [ "DOCUMENTED", "LIVE_VERIFIED" ], "example": { "caller": { "type": "direct" } }, "notes": null, "verification": { "method": "live_api", "verified_at": "2026-09-18", "result": "success", "http_status": 200, "request_note": "so_08" }, "sources": [ { "url": "https://platform.claude.com/docs/en/api/messages/create", "retrieved_at": "2026-09-18" } ], "last_verified": "2026-09-18", "_fragment": "generated/fragments/objects/anthropic-advanced-objects.json" }, { "provider": "anthropic", "name": "diagnostics (response)", "kind": "response_field", "description": "Cache diagnostics beta: null when there is nothing to compare; otherwise cache_miss_reason etc.", "schema": { "diagnostics": "object | null" }, "sdk_types": {}, "status": [ "DOCUMENTED", "BETA", "LIVE_VERIFIED" ], "example": null, "notes": null, "verification": { "method": "live_api", "verified_at": "2026-09-18", "result": "success", "http_status": 200, "request_note": "cache_12 -> null on first turn" }, "sources": [ { "url": "https://platform.claude.com/docs/en/build-with-claude/cache-diagnostics", "retrieved_at": "2026-09-18" } ], "last_verified": "2026-09-18", "_fragment": "generated/fragments/objects/anthropic-advanced-objects.json" }, { "provider": "anthropic", "object": "Message", "kind": "response", "description": "Response of POST /v1/messages (and message_start payload).", "fields": { "id": "string (msg_…)", "type": "'message'", "role": "'assistant'", "model": "string (resolved id)", "content": "ContentBlock[]", "stop_reason": "StopReason|null (null only in message_start)", "stop_sequence": "string|null", "stop_details": "RefusalStopDetails|null (null unless refusal)", "container": "Container|null {id, expires_at, skills[]}", "usage": "Usage", "context_management (beta)": "{applied_edits: []}", "diagnostics (beta)": "cache-miss reasons", "input_transformations (beta)": "thinking_dropped|thinking_mismatch_allowed[]" }, "status": [ "DOCUMENTED", "LIVE_VERIFIED" ], "example": { "model": "claude-haiku-4-5-20251001", "id": "msg_011CfBxdcZj7KMHsf2wSPauQ", "type": "message", "role": "assistant", "content": [ { "type": "text", "text": "OK." } ], "container": null, "stop_reason": "end_turn", "stop_sequence": null, "stop_details": null, "usage": { "input_tokens": 11, "cache_creation_input_tokens": 0, "cache_read_input_tokens": 0, "cache_creation": { "ephemeral_5m_input_tokens": 0, "ephemeral_1h_input_tokens": 0 }, "output_tokens": 5, "service_tier": "standard", "inference_geo": "not_available" } }, "source": "https://platform.claude.com/docs/en/api/messages", "_fragment": "generated/fragments/objects/anthropic-messages-objects.json" }, { "provider": "anthropic", "object": "Usage", "kind": "response", "description": "Billing/rate-limit usage. Total input = input_tokens + cache_creation_input_tokens + cache_read_input_tokens. output_tokens is non-zero even for empty text (except max_tokens=0 pre-warm: 0).", "fields": { "input_tokens": "int", "output_tokens": "int", "cache_creation_input_tokens": "int|null", "cache_read_input_tokens": "int|null", "cache_creation": "{ephemeral_5m_input_tokens, ephemeral_1h_input_tokens}|null", "output_tokens_details": "{thinking_tokens}|null (present when thinking ran)", "server_tool_use": "{web_search_requests, web_fetch_requests}|null", "service_tier": "'standard'|'priority'|'batch'|null", "inference_geo": "string|null — live value 'not_available' on Haiku 4.5 (value not enumerated in docs)", "iterations (beta)": "per-iteration usage entries type message|compaction|advisor_message|fallback_message", "speed (beta)": "'standard'|'fast'|null", "fallback_credit (beta)": "{token, status}" }, "status": [ "DOCUMENTED", "LIVE_VERIFIED" ], "example": null, "source": "https://platform.claude.com/docs/en/api/messages", "_fragment": "generated/fragments/objects/anthropic-messages-objects.json" }, { "provider": "anthropic", "object": "MessageDeltaUsage", "kind": "streaming", "description": "Cumulative usage in message_delta.", "fields": { "input_tokens": "int|null", "output_tokens": "int", "cache_creation_input_tokens": "int|null", "cache_read_input_tokens": "int|null", "output_tokens_details": "{thinking_tokens}|null", "server_tool_use": "ServerToolUsage|null" }, "status": [ "DOCUMENTED", "LIVE_VERIFIED" ], "example": null, "source": "https://platform.claude.com/docs/en/api/messages", "_fragment": "generated/fragments/objects/anthropic-messages-objects.json" }, { "provider": "anthropic", "object": "StopReason", "kind": "enum", "description": "Why generation stopped. In streaming: null in message_start, set in message_delta.", "fields": { "end_turn": "natural end — use the response (empty 2–3-token end_turn responses can follow tool results)", "max_tokens": "hit max_tokens or model max — raise max_tokens / continue; truncated tool_use blocks must be regenerated", "stop_sequence": "one of stop_sequences emitted — read `stop_sequence`; matched text excluded from content", "tool_use": "model calls client tool(s) — run them, return tool_result blocks (only) in the next user message; a server_tool_use without result finishes later", "pause_turn": "server-tool loop hit its iteration limit (default 10) — resend the assistant content as-is to continue", "refusal": "safety classifier stopped the response (HTTP 200) — read stop_details.category, retry on a fallback model", "model_context_window_exceeded": "output filled the context window — treat as truncated (Sonnet 4.5+ without beta; older models need model-context-window-exceeded-2025-08-26)", "compaction (beta)": "stopped after producing a compaction block (compact_20260112 with pause_after_compaction / compaction param)" }, "status": [ "DOCUMENTED", "LIVE_VERIFIED" ], "example": null, "source": "https://platform.claude.com/docs/en/build-with-claude/handling-stop-reasons", "live_observed": [ "end_turn", "max_tokens", "stop_sequence", "tool_use" ], "_fragment": "generated/fragments/objects/anthropic-messages-objects.json" }, { "provider": "anthropic", "object": "RefusalStopDetails", "kind": "response", "description": "stop_details when stop_reason=refusal.", "fields": { "type": "'refusal'", "category": "'cyber'|'bio'|'frontier_llm'|'reasoning_extraction'|'general_harms'|null", "explanation": "string|null (unstable text)" }, "status": [ "DOCUMENTED" ], "example": null, "source": "https://platform.claude.com/docs/en/api/messages", "_fragment": "generated/fragments/objects/anthropic-messages-objects.json" }, { "provider": "anthropic", "object": "Container", "kind": "response", "description": "Code-execution container info.", "fields": { "id": "string", "expires_at": "date-time", "skills": "[{type: anthropic|custom, skill_id, version}]|null" }, "status": [ "DOCUMENTED" ], "example": null, "source": "https://platform.claude.com/docs/en/api/messages", "live_note": "null on every plain request", "_fragment": "generated/fragments/objects/anthropic-messages-objects.json" }, { "provider": "anthropic", "object": "ModelInfo", "kind": "response", "description": "GET /v1/models item.", "fields": { "type": "'model'", "id": "string", "display_name": "string", "created_at": "RFC3339", "max_input_tokens": "int|null", "max_tokens": "int|null", "capabilities": "{batch, citations, code_execution, context_management{clear_tool_uses_20250919, clear_thinking_20251015, compact_20260112}, effort{low..max}, image_input, pdf_input, structured_outputs, thinking{types{enabled, adaptive}}} each {supported: bool}" }, "status": [ "DOCUMENTED", "LIVE_VERIFIED" ], "example": { "type": "model", "id": "claude-haiku-4-5-20251001", "display_name": "Claude Haiku 4.5", "created_at": "2025-10-15T00:00:00Z", "max_input_tokens": 200000, "max_tokens": 64000 }, "source": "https://platform.claude.com/docs/en/api/models/list", "_fragment": "generated/fragments/objects/anthropic-messages-objects.json" }, { "provider": "anthropic", "object": "Completion (legacy)", "kind": "response", "description": "POST /v1/complete response.", "fields": { "type": "'completion'", "id": "compl_…", "completion": "string (up to, excluding, the stop sequence)", "model": "string", "stop_reason": "'stop_sequence'|'max_tokens'|null" }, "status": [ "DOCUMENTED", "LEGACY", "DEPRECATED" ], "example": null, "source": "https://platform.claude.com/docs/en/api/completions", "_fragment": "generated/fragments/objects/anthropic-messages-objects.json" }, { "provider": "anthropic", "object": "ErrorResponse", "kind": "error", "description": "All errors: JSON with top-level error{type,message} and request_id (mirrors the request-id header). Streaming errors omit request_id.", "fields": { "type": "'error'", "error.type": "invalid_request_error|authentication_error|billing_error|permission_error|not_found_error|conflict_error|request_too_large|rate_limit_error|api_error|timeout_error|overloaded_error", "error.message": "string", "request_id": "req_…" }, "status": [ "DOCUMENTED", "LIVE_VERIFIED" ], "example": { "type": "error", "error": { "type": "not_found_error", "message": "model: claude-does-not-exist" }, "request_id": "req_011CfBxeBpDojVzndwYnobEw" }, "source": "https://platform.claude.com/docs/en/api/errors", "_fragment": "generated/fragments/objects/anthropic-messages-objects.json" }, { "provider": "anthropic", "object": "MessageTokensCount", "kind": "response", "description": "POST /v1/messages/count_tokens response.", "fields": { "input_tokens": "int (estimate; system-added tokens included but not billed)" }, "status": [ "DOCUMENTED", "LIVE_VERIFIED" ], "example": { "input_tokens": 11 }, "source": "https://platform.claude.com/docs/en/api/messages/count_tokens", "_fragment": "generated/fragments/objects/anthropic-messages-objects.json" }, { "provider": "anthropic", "object": "ContentBlock:text", "kind": "content_block (request+response)", "description": "Plain text; response may carry citations[].", "fields": { "type": "'text'", "text": "string", "citations": "TextCitation[]|null", "cache_control (request)": "CacheControlEphemeral|null" }, "status": [ "DOCUMENTED", "LIVE_VERIFIED" ], "example": { "type": "text", "text": "OK." }, "source": "https://platform.claude.com/docs/en/api/messages", "_fragment": "generated/fragments/objects/anthropic-messages-objects.json" }, { "provider": "anthropic", "object": "ContentBlock:image", "kind": "content_block (request)", "description": "Image input: base64 (jpeg/png/gif/webp), url, or Files API file. Optional transformations.oversized_image downsize|error.", "fields": { "type": "'image'", "source": "{type: base64, media_type, data} | {type: url, url} | {type: file, file_id}", "transformations": "{oversized_image}|null", "cache_control": "…" }, "status": [ "DOCUMENTED", "LIVE_VERIFIED" ], "example": null, "source": "https://platform.claude.com/docs/en/api/messages", "live_note": "1x1 PNG counted 5 extra tokens via count_tokens", "_fragment": "generated/fragments/objects/anthropic-messages-objects.json" }, { "provider": "anthropic", "object": "ContentBlock:document", "kind": "content_block (request)", "description": "Document input: base64 PDF, plain text, custom content blocks, url, or file; optional title/context/citations.enabled.", "fields": { "type": "'document'", "source": "{type: base64, media_type: application/pdf, data} | {type: text, media_type: text/plain, data} | {type: content, content} | {type: url, url} | {type: file, file_id}", "title": "string|null", "context": "string|null", "citations": "{enabled: bool}|null", "cache_control": "…" }, "status": [ "DOCUMENTED", "LIVE_VERIFIED" ], "example": null, "source": "https://platform.claude.com/docs/en/api/messages", "live_note": "text document + citations.enabled counted 562 tokens via count_tokens (11 without) — citations add fixed overhead", "_fragment": "generated/fragments/objects/anthropic-messages-objects.json" }, { "provider": "anthropic", "object": "ContentBlock:search_result", "kind": "content_block (request)", "description": "Your own search results with citations support.", "fields": { "type": "'search_result'", "source": "string", "title": "string", "content": "TextBlockParam[]", "citations": "{enabled}|null", "cache_control": "…" }, "status": [ "DOCUMENTED" ], "example": null, "source": "https://platform.claude.com/docs/en/api/messages", "_fragment": "generated/fragments/objects/anthropic-messages-objects.json" }, { "provider": "anthropic", "object": "ContentBlock:thinking", "kind": "content_block (request+response)", "description": "Reasoning block; replay unchanged (signature verified).", "fields": { "type": "'thinking'", "thinking": "string", "signature": "string" }, "status": [ "DOCUMENTED", "LIVE_VERIFIED" ], "example": null, "source": "https://platform.claude.com/docs/en/api/messages", "_fragment": "generated/fragments/objects/anthropic-messages-objects.json" }, { "provider": "anthropic", "object": "ContentBlock:redacted_thinking", "kind": "content_block (request+response)", "description": "Encrypted reasoning; replay `data` unchanged.", "fields": { "type": "'redacted_thinking'", "data": "string" }, "status": [ "DOCUMENTED" ], "example": null, "source": "https://platform.claude.com/docs/en/api/messages", "_fragment": "generated/fragments/objects/anthropic-messages-objects.json" }, { "provider": "anthropic", "object": "ContentBlock:tool_use", "kind": "content_block (request+response)", "description": "Client tool call.", "fields": { "type": "'tool_use'", "id": "toolu_…", "name": "string", "input": "object", "caller": "{type: direct}|{type: code_execution_2025…, tool_id}", "toolset_name": "string|null" }, "status": [ "DOCUMENTED", "LIVE_VERIFIED" ], "example": { "type": "tool_use", "id": "toolu_01S85RZWHSCzo537XxQrQw9e", "name": "get_weather", "input": { "city": "Paris" }, "caller": { "type": "direct" } }, "source": "https://platform.claude.com/docs/en/api/messages", "_fragment": "generated/fragments/objects/anthropic-messages-objects.json" }, { "provider": "anthropic", "object": "ContentBlock:tool_result", "kind": "content_block (request)", "description": "Result for a tool_use; content string or blocks (text, image, search_result, document, tool_reference, browser_state).", "fields": { "type": "'tool_result'", "tool_use_id": "string", "content": "string|Block[]", "is_error": "bool", "toolset_name": "string|null", "cache_control": "…" }, "status": [ "DOCUMENTED", "LIVE_VERIFIED" ], "example": null, "source": "https://platform.claude.com/docs/en/api/messages", "live_note": "missing tool_result → 400 'tool_use ids were found without tool_result blocks immediately after'", "_fragment": "generated/fragments/objects/anthropic-messages-objects.json" }, { "provider": "anthropic", "object": "ContentBlock:server_tool_use", "kind": "content_block (request+response)", "description": "Server tool call (web_search, web_fetch, code_execution, bash_code_execution, text_editor_code_execution, tool_search_tool_regex, tool_search_tool_bm25; beta adds advisor).", "fields": { "type": "'server_tool_use'", "id": "srvtoolu_…", "name": "enum", "input": "object", "caller": "…" }, "status": [ "DOCUMENTED" ], "example": null, "source": "https://platform.claude.com/docs/en/api/messages", "_fragment": "generated/fragments/objects/anthropic-messages-objects.json" }, { "provider": "anthropic", "object": "ContentBlock:web_search_tool_result", "kind": "content_block (request+response)", "description": "Server web search result.", "fields": { "type": "'web_search_tool_result'", "tool_use_id": "srvtoolu_…", "content": "web_search_result[] {type, url, title, encrypted_content, page_age} | {type: web_search_tool_result_error, error_code}", "error_code enum": "invalid_tool_input|unavailable|max_uses_exceeded|too_many_requests|query_too_long|request_too_large" }, "status": [ "DOCUMENTED" ], "example": null, "source": "https://platform.claude.com/docs/en/api/messages", "_fragment": "generated/fragments/objects/anthropic-messages-objects.json" }, { "provider": "anthropic", "object": "ContentBlock:web_fetch_tool_result", "kind": "content_block (request+response)", "description": "Server web fetch result.", "fields": { "type": "'web_fetch_tool_result'", "tool_use_id": "srvtoolu_…", "content": "{type: web_fetch_result, url, content: document, retrieved_at} | {type: web_fetch_tool_result_error, error_code}", "error_code enum": "invalid_tool_input|url_too_long|url_not_allowed|url_not_in_prior_context|url_not_accessible|unsupported_content_type|too_many_requests|max_uses_exceeded|unavailable|content_too_large" }, "status": [ "DOCUMENTED" ], "example": null, "source": "https://platform.claude.com/docs/en/api/messages", "_fragment": "generated/fragments/objects/anthropic-messages-objects.json" }, { "provider": "anthropic", "object": "ContentBlock:code_execution_tool_result", "kind": "content_block (request+response)", "description": "Code execution result.", "fields": { "type": "'code_execution_tool_result'", "tool_use_id": "srvtoolu_…", "content": "{type: code_execution_result, stdout, stderr, return_code, content: code_execution_output[] {file_id}} | {type: code_execution_tool_result_error, error_code}", "error_code enum": "invalid_tool_input|unavailable|too_many_requests|execution_time_exceeded" }, "status": [ "DOCUMENTED" ], "example": null, "source": "https://platform.claude.com/docs/en/api/messages", "_fragment": "generated/fragments/objects/anthropic-messages-objects.json" }, { "provider": "anthropic", "object": "ContentBlock:bash_code_execution_tool_result", "kind": "content_block (request+response)", "description": "Bash execution result (code_execution_20250825+).", "fields": { "type": "'bash_code_execution_tool_result'", "content": "{type: bash_code_execution_result, stdout, stderr, return_code, content[]} | error", "error_code enum": "invalid_tool_input|unavailable|too_many_requests|execution_time_exceeded|output_file_too_large" }, "status": [ "DOCUMENTED" ], "example": null, "source": "https://platform.claude.com/docs/en/api/messages", "_fragment": "generated/fragments/objects/anthropic-messages-objects.json" }, { "provider": "anthropic", "object": "ContentBlock:text_editor_code_execution_tool_result", "kind": "content_block (request+response)", "description": "Text editor in container result.", "fields": { "type": "'text_editor_code_execution_tool_result'", "content": "view_result {content, file_type, num_lines, start_line, total_lines} | create_result {is_file_update} | str_replace_result {lines, new_lines, new_start, old_lines, old_start} | error", "error_code enum": "invalid_tool_input|unavailable|too_many_requests|execution_time_exceeded|file_not_found" }, "status": [ "DOCUMENTED" ], "example": null, "source": "https://platform.claude.com/docs/en/api/messages", "_fragment": "generated/fragments/objects/anthropic-messages-objects.json" }, { "provider": "anthropic", "object": "ContentBlock:tool_search_tool_result", "kind": "content_block (request+response)", "description": "Tool search result.", "fields": { "type": "'tool_search_tool_result'", "content": "{type: tool_search_tool_search_result, tool_references: tool_reference[]} | {type: tool_search_tool_result_error, error_code}", "error_code enum": "invalid_tool_input|unavailable|too_many_requests|execution_time_exceeded" }, "status": [ "DOCUMENTED" ], "example": null, "source": "https://platform.claude.com/docs/en/api/messages", "_fragment": "generated/fragments/objects/anthropic-messages-objects.json" }, { "provider": "anthropic", "object": "ContentBlock:container_upload", "kind": "content_block (request+response)", "description": "File placed into the code-execution container.", "fields": { "type": "'container_upload'", "file_id": "string" }, "status": [ "DOCUMENTED" ], "example": null, "source": "https://platform.claude.com/docs/en/api/messages", "_fragment": "generated/fragments/objects/anthropic-messages-objects.json" }, { "provider": "anthropic", "object": "ContentBlock:tool_reference", "kind": "content_block (request (inside tool_result))", "description": "Reference to a deferred tool (tool search).", "fields": { "type": "'tool_reference'", "tool_name": "string" }, "status": [ "DOCUMENTED" ], "example": null, "source": "https://platform.claude.com/docs/en/api/messages", "_fragment": "generated/fragments/objects/anthropic-messages-objects.json" }, { "provider": "anthropic", "object": "ContentBlock:browser_state", "kind": "content_block (request (inside tool_result))", "description": "Browser toolset state (browser_toolset_20260801).", "fields": { "type": "'browser_state'", "…": "tabs, changes, screenshot" }, "status": [ "DOCUMENTED" ], "example": null, "source": "https://platform.claude.com/docs/en/api/messages", "_fragment": "generated/fragments/objects/anthropic-messages-objects.json" }, { "provider": "anthropic", "object": "ContentBlock:mcp_tool_use", "kind": "content_block (response (beta))", "description": "Call to a remote MCP server tool.", "fields": { "type": "'mcp_tool_use'", "id": "string", "name": "string", "server_name": "string", "input": "object" }, "status": [ "DOCUMENTED", "BETA" ], "example": null, "source": "https://platform.claude.com/docs/en/api/beta/messages", "_fragment": "generated/fragments/objects/anthropic-messages-objects.json" }, { "provider": "anthropic", "object": "ContentBlock:mcp_tool_result", "kind": "content_block (response (beta))", "description": "Result from a remote MCP tool.", "fields": { "type": "'mcp_tool_result'", "tool_use_id": "string", "is_error": "bool", "content": "string|TextBlock[]" }, "status": [ "DOCUMENTED", "BETA" ], "example": null, "source": "https://platform.claude.com/docs/en/api/beta/messages", "_fragment": "generated/fragments/objects/anthropic-messages-objects.json" }, { "provider": "anthropic", "object": "ContentBlock:advisor_tool_result", "kind": "content_block (response (beta))", "description": "Advisor tool result (advisor-tool-2026-03-01).", "fields": { "type": "'advisor_tool_result'", "tool_use_id": "string", "content": "advisor_result | advisor_redacted_result | error" }, "status": [ "DOCUMENTED", "BETA" ], "example": null, "source": "https://platform.claude.com/docs/en/api/beta/messages", "_fragment": "generated/fragments/objects/anthropic-messages-objects.json" }, { "provider": "anthropic", "object": "ContentBlock:compaction", "kind": "content_block (request+response (beta))", "description": "Signed summary replacing earlier messages; round-trip verbatim (null content = failed compaction, treated as no-op).", "fields": { "type": "'compaction'", "content": "string|null", "encrypted_content": "string|null", "signature": "string|null" }, "status": [ "DOCUMENTED", "BETA" ], "example": null, "source": "https://platform.claude.com/docs/en/api/beta/messages", "_fragment": "generated/fragments/objects/anthropic-messages-objects.json" }, { "provider": "anthropic", "object": "ContentBlock:fallback", "kind": "content_block (response (beta))", "description": "Boundary where one model's output gives way to a fallback model (streams as start/stop pair without deltas).", "fields": { "type": "'fallback'", "from": "{model}", "to": "{model}", "trigger": "{type: refusal, …}" }, "status": [ "DOCUMENTED", "BETA" ], "example": null, "source": "https://platform.claude.com/docs/en/api/beta/messages", "_fragment": "generated/fragments/objects/anthropic-messages-objects.json" }, { "provider": "anthropic", "object": "TextCitation", "kind": "response", "description": "Citation variants inside text.citations[] / citations_delta.", "fields": { "char_location": "{cited_text, document_index, document_title, start_char_index, end_char_index, file_id}", "page_location": "{…, start_page_number, end_page_number}", "content_block_location": "{…, start_block_index, end_block_index}", "web_search_result_location": "{cited_text, url, title, encrypted_index}", "search_result_location": "{cited_text, source, title, search_result_index, start_block_index, end_block_index}" }, "status": [ "DOCUMENTED" ], "example": null, "source": "https://platform.claude.com/docs/en/api/messages", "_fragment": "generated/fragments/objects/anthropic-messages-objects.json" }, { "provider": "anthropic", "api_family": "messages-batches", "name": "MessageBatch", "official_type_name": "BetaMessageBatch", "description": "Response object of POST /v1/messages/batches", "fields": [ { "name": "type", "type": "\"message_batch\"", "required": true, "description": "Object type. For Message Batches, this is always `\"message_batch\"`.", "default": "message_batch" }, { "name": "id", "type": "string", "required": true, "description": "Unique object identifier. The format and length of IDs may change over time." }, { "name": "archived_at", "type": "string or null", "required": true, "description": "RFC 3339 datetime string representing the time at which the Message Batch was archived and its results became unavailable.", "constraints": { "format": "date-time" } }, { "name": "cancel_initiated_at", "type": "string or null", "required": true, "description": "RFC 3339 datetime string representing the time at which cancellation was initiated for the Message Batch. Specified only if cancellation was initiated.", "constraints": { "format": "date-time" } }, { "name": "created_at", "type": "string", "required": true, "description": "RFC 3339 datetime string representing the time at which the Message Batch was created.", "constraints": { "format": "date-time" } }, { "name": "ended_at", "type": "string or null", "required": true, "description": "RFC 3339 datetime string representing the time at which processing for the Message Batch ended. Specified only once processing ends. Processing ends when every request in a Message Batch has either succeeded, errored, canceled, or expired.", "constraints": { "format": "date-time" } }, { "name": "expires_at", "type": "string", "required": true, "description": "RFC 3339 datetime string representing the time at which the Message Batch will expire and end processing, which is 24 hours after creation.", "constraints": { "format": "date-time" } }, { "name": "processing_status", "type": "\"in_progress\" or \"canceling\" or \"ended\"", "required": true, "description": "Processing status of the Message Batch.", "enum": [ "in_progress", "canceling", "ended" ] }, { "name": "request_counts", "type": "BetaMessageBatchRequestCounts", "required": true, "description": "Tallies requests within the Message Batch, categorized by their status. Requests start as `processing` and move to one of the other statuses only once processing of the entire batch ends. The sum of all values always matches the total number of requests in the batch." }, { "name": "request_counts.canceled", "type": "number", "required": true, "description": "Number of requests in the Message Batch that have been canceled. This is zero until processing of the entire Message Batch has ended.", "default": "0" }, { "name": "request_counts.errored", "type": "number", "required": true, "description": "Number of requests in the Message Batch that encountered an error. This is zero until processing of the entire Message Batch has ended.", "default": "0" }, { "name": "request_counts.expired", "type": "number", "required": true, "description": "Number of requests in the Message Batch that have expired. This is zero until processing of the entire Message Batch has ended.", "default": "0" }, { "name": "request_counts.processing", "type": "number", "required": true, "description": "Number of requests in the Message Batch that are processing.", "default": "0" }, { "name": "request_counts.succeeded", "type": "number", "required": true, "description": "Number of requests in the Message Batch that have completed successfully. This is zero until processing of the entire Message Batch has ended.", "default": "0" }, { "name": "results_url", "type": "string or null", "required": true, "description": "URL to a `.jsonl` file containing the results of the Message Batch requests. Specified only once processing ends. Results in the file are not guaranteed to be in the same order as requests. Use the `custom_id` field to match results to requests." } ], "example": { "id": "msgbatch_013Zva2CMHLNnXjNJJKqJ2EF", "archived_at": "2024-08-20T18:37:24.100435Z", "cancel_initiated_at": "2024-08-20T18:37:24.100435Z", "created_at": "2024-08-20T18:37:24.100435Z", "ended_at": "2024-08-20T18:37:24.100435Z", "expires_at": "2024-08-20T18:37:24.100435Z", "processing_status": "in_progress", "request_counts": { "canceled": 10, "errored": 30, "expired": 10, "processing": 100, "succeeded": 50 }, "results_url": "https://api.anthropic.com/v1/messages/batches/msgbatch_013Zva2CMHLNnXjNJJKqJ2EF/results", "type": "message_batch" }, "status": [ "DOCUMENTED", "LIVE_VERIFIED" ], "sources": [ { "url": "https://platform.claude.com/docs/en/api/beta/messages/batches/create", "retrieved_at": "2026-09-18" }, { "url": "https://platform.claude.com/docs/en/api/messages/batches/create", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/anthropic-platform-objects.json" }, { "provider": "anthropic", "api_family": "messages-batches", "name": "DeletedMessageBatch", "official_type_name": "BetaDeletedMessageBatch", "description": "Response object of DELETE /v1/messages/batches/{message_batch_id}", "fields": [ { "name": "type", "type": "\"message_batch_deleted\"", "required": true, "description": "Deleted object type. For Message Batches, this is always `\"message_batch_deleted\"`.", "default": "message_batch_deleted" }, { "name": "id", "type": "string", "required": true, "description": "ID of the Message Batch." } ], "example": { "id": "msgbatch_013Zva2CMHLNnXjNJJKqJ2EF", "type": "message_batch_deleted" }, "status": [ "DOCUMENTED", "LIVE_VERIFIED" ], "sources": [ { "url": "https://platform.claude.com/docs/en/api/beta/messages/batches/delete", "retrieved_at": "2026-09-18" }, { "url": "https://platform.claude.com/docs/en/api/messages/batches/delete", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/anthropic-platform-objects.json" }, { "provider": "anthropic", "api_family": "messages-batches", "name": "MessageBatchIndividualResponse", "official_type_name": "BetaMessageBatchIndividualResponse", "description": "This is a single line in the response `.jsonl` file and does not represent the response as a whole.", "fields": [ { "name": "custom_id", "type": "string", "required": true, "description": "Developer-provided ID created for each request in a Message Batch. Useful for matching results to requests, as results may be given out of request order. Must be unique for each request within the Message Batch." }, { "name": "result", "type": "BetaMessageBatchResult", "required": true, "description": "Processing result for this request. Contains a Message output if processing was successful, an error response if processing failed, or the reason why processing was not attempted, such as cancellation or expiration." }, { "name": "result.type", "type": "\"succeeded\"", "required": true, "description": "", "default": "succeeded" }, { "name": "result.message", "type": "BetaMessage", "required": true, "description": "" }, { "name": "result.message.type", "type": "\"message\"", "required": true, "description": "Object type. For Messages, this is always `\"message\"`.", "default": "message" }, { "name": "result.message.id", "type": "string", "required": true, "description": "Unique object identifier. The format and length of IDs may change over time." }, { "name": "result.message.container", "type": "BetaContainer or null", "required": true, "description": "Information about the container used in the request (for the code execution tool)" }, { "name": "result.message.content", "type": "array of BetaContentBlock", "required": true, "description": "Content generated by the model. This is an array of content blocks, each of which has a `type` that determines its shape. Example: ```json [{\"type\": \"text\", \"text\": \"Hi, I'm Claude.\"}] ``` If the request input `messages` ended with an `assistant` turn, then the response `content` will continue directly from that last turn. You can use this to constrain the model's output. For example, if the input `messages` were: ```json [ {\"role\": \"user\", \"content\": \"What's the Greek name for Sun? (A) Sol (B) Helios (C) Sun\"}, {\"role\": \"assistant\", \"content\": \"The best answer is (\"} ] ``` Then the response `content` might be: ```json [{\"type\": \"text\", \"text\": \"B)\"}] ```" }, { "name": "result.message.context_management", "type": "BetaContextManagementResponse or null", "required": true, "description": "Context management response. Information about context management strategies applied during the request." }, { "name": "result.message.diagnostics", "type": "BetaDiagnostics or null", "required": true, "description": "Response envelope for request-level diagnostics. Present (possibly null) whenever the caller supplied `diagnostics` on the request." }, { "name": "result.message.model", "type": "Model", "required": true, "description": "The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options." }, { "name": "result.message.role", "type": "\"assistant\"", "required": true, "description": "Conversational role of the generated message. This will always be `\"assistant\"`.", "default": "assistant" }, { "name": "result.message.stop_details", "type": "BetaRefusalStopDetails or null", "required": true, "description": "Structured information about a refusal." }, { "name": "result.message.stop_reason", "type": "BetaStopReason or null", "required": true, "description": "The reason that we stopped. This may be one the following values: * `\"end_turn\"`: the model reached a natural stopping point * `\"max_tokens\"`: we exceeded the requested `max_tokens` or the model's maximum * `\"stop_sequence\"`: one of your provided custom `stop_sequences` was generated * `\"tool_use\"`: the model invoked one or more tools * `\"pause_turn\"`: we paused a long-running turn. You may provide the response back as-is in a subsequent request to let the model continue. * `\"refusal\"`: when streaming classifiers intervene to handle potential policy violations * `\"model_context_window_exceeded\"`: we exceeded the model's context window In non-streaming mode this value is always non-null. In streaming mode, it is null in the `message_start` event and non-null otherwise.", "enum": [ "end_turn", "max_tokens", "stop_sequence", "tool_use", "pause_turn", "compaction", "refusal", "model_context_window_exceeded" ] }, { "name": "result.message.stop_sequence", "type": "string or null", "required": true, "description": "Which custom stop sequence was generated, if any. This value will be a non-null string if one of your custom stop sequences was generated." }, { "name": "result.message.usage", "type": "BetaUsage", "required": true, "description": "Billing and rate-limit usage. Anthropic's API bills and rate-limits by token counts, as tokens represent the underlying cost to our systems. Under the hood, the API transforms requests into a format suitable for the model. The model's output then goes through a parsing stage before becoming an API response. As a result, the token counts in `usage` will not match one-to-one with the exact visible content of an API request or response. For example, `output_tokens` will be non-zero, even for an empty string response from Claude. Total input tokens in a request is the summation of `input_tokens`, `cache_creation_input_tokens`, and `cache_read_input_tokens`." }, { "name": "result.message.input_transformations", "type": "array of BetaInputTransformation or null", "required": false, "description": "Changes the API made to the request's input before showing it to the model, and blocks that failed a binding check but were left unchanged: one entry per block, in request order. Two entry types today. `thinking_dropped` — a `thinking`, `redacted_thinking` or `connector_text` block from the request's `messages` that was removed from the prompt instead of being shown to the model because it failed a binding check. `thinking_mismatch_allowed` — a `thinking` or `redacted_thinking` block that failed the conversation check (the conversation before it differs from the one it was created in, or it carries no record of one on a model that requires it) and was shown to the model all the same, because that check is not enforced for this request. More entry types may be added over time; ignore types you do not recognize. Requires `anthropic-beta: thinking-binding-controls-2026-08-01`. Present on every such response from a model that supports extended thinking, as `[]` when there is no entry to report; without the beta, blocks are removed or left in place all the same but nothing is reported. Removed blocks contribute nothing to `usage.input_tokens`; blocks left in place count as sent. When streaming, the array is final in `message_start`; the final `message_delta` event carries it only when a server-side model fallback happened mid-stream, in which case it holds the serving model's entries and replaces the one in `message_start`." }, { "name": "result.type", "type": "\"errored\"", "required": true, "description": "", "default": "errored" }, { "name": "result.error", "type": "BetaErrorResponse", "required": true, "description": "" }, { "name": "result.error.type", "type": "\"error\"", "required": true, "description": "", "default": "error" }, { "name": "result.error.error", "type": "BetaError", "required": true, "description": "" }, { "name": "result.error.request_id", "type": "string or null", "required": true, "description": "" }, { "name": "result.type", "type": "\"canceled\"", "required": true, "description": "", "default": "canceled" }, { "name": "result.type", "type": "\"expired\"", "required": true, "description": "", "default": "expired" } ], "example": null, "status": [ "DOCUMENTED", "LIVE_VERIFIED" ], "sources": [ { "url": "https://platform.claude.com/docs/en/api/beta/messages/batches/results", "retrieved_at": "2026-09-18" }, { "url": "https://platform.claude.com/docs/en/api/messages/batches/results", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/anthropic-platform-objects.json" }, { "provider": "anthropic", "api_family": "admin", "name": "ChatProjectUsage", "official_type_name": "BetaChatProjectUsage", "description": "Response for GET /v1/organizations/analytics/apps/chat/projects.", "fields": [ { "name": "data", "type": "array of object", "required": true, "description": "" }, { "name": "data[].distinct_user_count", "type": "number", "required": true, "description": "Number of distinct users who used the project on the requested day, or, in date-range mode, over the requested window — recomputed as an exact distinct count over the window's per-member daily rows, never a sum of per-day values." }, { "name": "data[].message_count", "type": "number", "required": true, "description": "Number of messages sent in the project on the requested day" }, { "name": "data[].project_id", "type": "string", "required": true, "description": "Tagged project identifier (e.g. `claude_proj_...`)" }, { "name": "data[].project_name", "type": "string", "required": true, "description": "Name of the project" }, { "name": "data[].created_at", "type": "string or null", "required": false, "description": "Project creation timestamp in RFC 3339 format. Null if the project was deleted before attribution was recorded.", "constraints": { "format": "date-time" } }, { "name": "data[].created_by", "type": "BetaAnalyticsUser or null", "required": false, "description": "A user in the organization, identified by tagged id and email address." }, { "name": "data[].created_by.type", "type": "\"user\"", "required": true, "description": "Object type. Always `user`.", "default": "user" }, { "name": "data[].created_by.id", "type": "string", "required": true, "description": "Tagged user identifier (e.g. `user_...`)" }, { "name": "data[].created_by.email_address", "type": "string", "required": true, "description": "Email address of the user" }, { "name": "data[].distinct_conversation_count", "type": "number or null", "required": false, "description": "Number of distinct conversations in the project. Null on aggregated rows where a distinct count cannot be computed." }, { "name": "data[].product", "type": "string or null", "required": false, "description": "Product that produced this row's activity: one of `chat`, `claude_code`, `cowork`, or `office_agent` (the canonical Cost & Usage product naming; an `office_agent` row's per-surface breakdown is in its `office_metrics`). On `/plugins` only `cowork` and `claude_code` occur (the only surfaces with plugin attribution); on `/artifacts` only `chat`, `claude_code`, and `cowork` occur (the surfaces that create artifacts); `/apps/chat/projects` does not support the product dimension (a `product` entry in `group_by[]` or `filter[]` there is rejected). Present only when the request grouped by `product`." }, { "name": "data[].rbac_group_id", "type": "string or null", "required": false, "description": "Tagged RBAC group identifier (`rbac_group_...`), matching the spend-limits API spelling. Present only when the request grouped by `rbac_group_id`." }, { "name": "data[].rbac_group_name", "type": "string or null", "required": false, "description": "Resolved RBAC group display name, alongside `rbac_group_id` when name resolution is available. Null if the group has been deleted or its name could not be resolved; `rbac_group_id` remains the stable key." }, { "name": "data[].user_id", "type": "string or null", "required": false, "description": "Tagged user identifier (e.g. `user_...`). Present only when the request grouped by `user_id`." }, { "name": "next_page", "type": "string or null", "required": true, "description": "Opaque cursor for the next page, or null if no more results" } ], "example": { "data": [ { "distinct_user_count": 0, "message_count": 0, "project_id": "project_id", "project_name": "project_name", "created_at": "2019-12-27T18:11:19.117Z", "created_by": { "id": "id", "email_address": "email_address", "type": "user" }, "distinct_conversation_count": 0, "product": "product", "rbac_group_id": "rbac_group_id", "rbac_group_name": "rbac_group_name", "user_id": "user_id" } ], "next_page": "next_page" }, "status": [ "DOCUMENTED" ], "sources": [ { "url": "https://platform.claude.com/docs/en/api/beta/organization/analytics/chat_projects/list", "retrieved_at": "2026-09-18" }, { "url": "https://platform.claude.com/docs/en/api/beta/organization/analytics/chat_projects", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/anthropic-platform-objects.json" }, { "provider": "anthropic", "api_family": "admin", "name": "ArtifactUsage", "official_type_name": "BetaArtifactUsage", "description": "Response for GET /v1/organizations/analytics/artifacts. `next_page` is null on ungrouped queries — the artifact-type cube is finite and returned in full. Grouped queries (`group_by[]` on `product` / `user_id` / `rbac_group_id`) multiply the cube and paginate like the other analytics list endpoints.", "fields": [ { "name": "data", "type": "array of object", "required": true, "description": "" }, { "name": "data[].artifact_type", "type": "string", "required": true, "description": "Canonical artifact MIME type (e.g. `text/markdown`, `application/vnd.ant.react`, `image/svg+xml`), or `other`. Claude Code and Cowork artifacts report as `text/html`." }, { "name": "data[].artifacts_created_count", "type": "number", "required": true, "description": "Number of artifacts created in this bucket on the requested day" }, { "name": "data[].distinct_user_count", "type": "number", "required": true, "description": "Number of distinct users who created artifacts in this bucket on the requested day" }, { "name": "data[].is_shared", "type": "boolean", "required": true, "description": "Whether the artifacts in this bucket have ever been shared (a Claude Code / Cowork artifact is shared once anyone beyond its creator may open it: named members, the whole organization, or anyone with the link)." }, { "name": "data[].published_artifacts_created_count", "type": "number", "required": true, "description": "Number of those artifacts that have been published (for Claude Code / Cowork artifacts: open to anyone with the link); never exceeds `artifacts_created_count`" }, { "name": "data[].product", "type": "string or null", "required": false, "description": "Product that produced this row's activity: one of `chat`, `claude_code`, `cowork`, or `office_agent` (the canonical Cost & Usage product naming; an `office_agent` row's per-surface breakdown is in its `office_metrics`). On `/plugins` only `cowork` and `claude_code` occur (the only surfaces with plugin attribution); on `/artifacts` only `chat`, `claude_code`, and `cowork` occur (the surfaces that create artifacts); `/apps/chat/projects` does not support the product dimension (a `product` entry in `group_by[]` or `filter[]` there is rejected). Present only when the request grouped by `product`." }, { "name": "data[].rbac_group_id", "type": "string or null", "required": false, "description": "Tagged RBAC group identifier (`rbac_group_...`), matching the spend-limits API spelling. Present only when the request grouped by `rbac_group_id`." }, { "name": "data[].rbac_group_name", "type": "string or null", "required": false, "description": "Resolved RBAC group display name, alongside `rbac_group_id` when name resolution is available. Null if the group has been deleted or its name could not be resolved; `rbac_group_id` remains the stable key." }, { "name": "data[].user_id", "type": "string or null", "required": false, "description": "Tagged user identifier (e.g. `user_...`). Present only when the request grouped by `user_id`." }, { "name": "next_page", "type": "string or null", "required": true, "description": "Cursor for the next page of a grouped query; always null for the ungrouped artifact-type cube, which is returned in full." } ], "example": { "data": [ { "artifact_type": "artifact_type", "artifacts_created_count": 0, "distinct_user_count": 0, "is_shared": true, "published_artifacts_created_count": 0, "product": "product", "rbac_group_id": "rbac_group_id", "rbac_group_name": "rbac_group_name", "user_id": "user_id" } ], "next_page": "next_page" }, "status": [ "DOCUMENTED" ], "sources": [ { "url": "https://platform.claude.com/docs/en/api/beta/organization/analytics/artifacts/list", "retrieved_at": "2026-09-18" }, { "url": "https://platform.claude.com/docs/en/api/beta/organization/analytics/artifacts", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/anthropic-platform-objects.json" }, { "provider": "anthropic", "api_family": "admin", "name": "ConnectorUsage", "official_type_name": "BetaConnectorUsage", "description": "Response for GET /v1/organizations/analytics/connectors.", "fields": [ { "name": "data", "type": "array of object", "required": true, "description": "" }, { "name": "data[].chat_metrics", "type": "object", "required": true, "description": "Claude.ai activity metrics for a single connector on a given day." }, { "name": "data[].chat_metrics.distinct_conversation_connector_used_count", "type": "number or null", "required": true, "description": "Number of distinct conversations in which the connector was used. Approximate (HLL, typical error <2%) in date-range mode. Null on aggregated rows where a distinct count cannot be computed." }, { "name": "data[].claude_code_metrics", "type": "object", "required": true, "description": "Claude Code activity metrics for a single connector on a given day." }, { "name": "data[].claude_code_metrics.distinct_session_connector_used_count", "type": "number or null", "required": true, "description": "Number of distinct Claude Code sessions in which the connector was used. Approximate (HLL, typical error <2%) in date-range mode. Null on aggregated rows where a distinct count cannot be computed." }, { "name": "data[].connector_name", "type": "string", "required": true, "description": "Name of the connector. Some rows carry an opaque connector id here instead of a readable name; `connector_display_name` holds the resolved name for those rows." }, { "name": "data[].cowork_metrics", "type": "object", "required": true, "description": "Cowork activity metrics for a single connector on a given day." }, { "name": "data[].cowork_metrics.distinct_session_connector_used_count", "type": "number or null", "required": true, "description": "Number of distinct Cowork sessions in which the connector was used. Approximate (HLL, typical error <2%) in date-range mode. Null on aggregated rows where a distinct count cannot be computed." }, { "name": "data[].distinct_user_count", "type": "number", "required": true, "description": "Number of distinct users who used the connector on the requested day, or, in date-range mode, over the requested window — recomputed as an exact distinct count over the window's per-member daily rows, never a sum of per-day values." }, { "name": "data[].office_metrics", "type": "object", "required": true, "description": "Office Agent activity metrics for a single connector on a given day, broken out by Office product." }, { "name": "data[].office_metrics.excel", "type": "BetaConnectorOfficeProductMetrics", "required": true, "description": "Office Agent activity metrics for a single connector on a given day within one Office product." }, { "name": "data[].office_metrics.outlook", "type": "BetaConnectorOfficeProductMetrics", "required": true, "description": "Office Agent activity metrics for a single connector on a given day within one Office product." }, { "name": "data[].office_metrics.powerpoint", "type": "BetaConnectorOfficeProductMetrics", "required": true, "description": "Office Agent activity metrics for a single connector on a given day within one Office product." }, { "name": "data[].office_metrics.word", "type": "BetaConnectorOfficeProductMetrics", "required": true, "description": "Office Agent activity metrics for a single connector on a given day within one Office product." }, { "name": "data[].connector_display_name", "type": "string or null", "required": false, "description": "Human-readable display name for rows whose `connector_name` is an opaque connector id rather than a readable name, resolved at request time from the organization's connectors (including connectors that have since been removed). `connector_name` remains the row's stable key for sorting and pagination, and `filter[]=connector_name:{value}` also matches these rows by display name. Display names are not unique, and the same connector's claude.ai usage can appear under a separate row with a readable `connector_name`. Null when `connector_name` is already a readable name, when the id cannot be resolved to one of the organization's connectors, or when display-name resolution is not enabled for this organization." }, { "name": "data[].individual_auth_distinct_user_count", "type": "number or null", "required": false, "description": "Number of distinct users whose use of this connector on the requested day ran on their own individual credential, connected through their own consent flow. Companion bucket to `managed_auth_distinct_user_count`, which carries the measurement, attribution, and null rules. Users whose requests used no stored credential count in neither bucket." }, { "name": "data[].managed_auth_distinct_user_count", "type": "number or null", "required": false, "description": "Number of distinct users whose use of this connector on the requested day ran on Enterprise Managed Auth (an organization-managed credential provisioned through the organization's identity provider), read from the token record each request used. Null, never 0, when managed-auth reporting is not enabled for the organization, the value cannot be attributed to the row, no credentialed requests and no managed-token mint events (a managed credential being provisioned for a user's use of the connector) were observed that day, or the day predates 2026-07-01, the first day the backing data exists (forward-only data, no backfill). When credentialed requests or mint events were observed and attributed, both managed-auth fields populate, reporting 0 for a bucket with no users; the two counts are independent, not a partition — a user whose requests that day used both kinds of credential counts in both. Mint events carry user but not surface attribution, so they count as observed auth activity on `user_id` and `rbac_group_id` cuts — attributed to the user the credential was provisioned for — but never on a cut that references `product` (group or filter). Date-range rollup mode (`starting_date`/`ending_date`) computes both fields exactly over the window — distinct users with at least one qualifying day — when the whole window starts on or after 2026-07-01, with the null-versus-0 and mint-event rules applying with the window in place of the day; a range starting earlier reports every managed-auth field as null, never a partial-window value." }, { "name": "data[].product", "type": "string or null", "required": false, "description": "Product that produced this row's activity: one of `chat`, `claude_code`, `cowork`, or `office_agent` (the canonical Cost & Usage product naming; an `office_agent` row's per-surface breakdown is in its `office_metrics`). On `/plugins` only `cowork` and `claude_code` occur (the only surfaces with plugin attribution); on `/artifacts` only `chat`, `claude_code`, and `cowork` occur (the surfaces that create artifacts); `/apps/chat/projects` does not support the product dimension (a `product` entry in `group_by[]` or `filter[]` there is rejected). Present only when the request grouped by `product`." }, { "name": "data[].rbac_group_id", "type": "string or null", "required": false, "description": "Tagged RBAC group identifier (`rbac_group_...`), matching the spend-limits API spelling. Present only when the request grouped by `rbac_group_id`." }, { "name": "data[].rbac_group_name", "type": "string or null", "required": false, "description": "Resolved RBAC group display name, alongside `rbac_group_id` when name resolution is available. Null if the group has been deleted or its name could not be resolved; `rbac_group_id` remains the stable key." }, { "name": "data[].read_call_count", "type": "number or null", "required": false, "description": "Number of connector tool calls on the requested day whose trusted read-only annotation marked them read-only. Call count, not distinct users. Every call recorded on a classified surface lands in exactly one of `read_call_count`, `write_call_count`, or `unclassified_call_count`, so the three sum to the day's classified calls. Classification is forward-only per surface: claude.ai from 2026-06-01, Claude Code from 2026-05-30, Claude in Office from 2026-05-29, Cowork from 2026-06-02 (Cowork clients predating annotation forwarding land in `unclassified_call_count`). Null, never 0, when the value cannot be stated: the read/write split is not enabled for this organization, or the day predates 2026-05-29. For a date-range total, sum the per-day values, but treat a window that extends before 2026-05-29 as null rather than summing only its covered days — date-range rollup mode (`starting_date`/`ending_date`) applies both rules server-side." }, { "name": "data[].unclassified_call_count", "type": "number or null", "required": false, "description": "Number of connector tool calls on the requested day with no trusted read-only annotation — the annotation is optional in the MCP spec and is discarded when connector access controls are active, so unclassified calls are common. This field shows how much of the day's classified activity the read/write split actually covers. Call count, not distinct users. One of the three call-classification buckets; see `read_call_count` for the per-surface data-start dates, null conditions, and date-range guidance." }, { "name": "data[].user_id", "type": "string or null", "required": false, "description": "Tagged user identifier (e.g. `user_...`). Present only when the request grouped by `user_id`." }, { "name": "data[].write_call_count", "type": "number or null", "required": false, "description": "Number of connector tool calls on the requested day whose trusted read-only annotation marked them not read-only. Call count, not distinct users. One of the three call-classification buckets; see `read_call_count` for the per-surface data-start dates, null conditions, and date-range guidance." }, { "name": "next_page", "type": "string or null", "required": true, "description": "Opaque cursor for the next page, or null if no more results" } ], "example": { "data": [ { "chat_metrics": { "distinct_conversation_connector_used_count": 0 }, "claude_code_metrics": { "distinct_session_connector_used_count": 0 }, "connector_name": "connector_name", "cowork_metrics": { "distinct_session_connector_used_count": 0 }, "distinct_user_count": 0, "office_metrics": { "excel": { "distinct_session_connector_used_count": 0 }, "outlook": { "distinct_session_connector_used_count": 0 }, "powerpoint": { "distinct_session_connector_used_count": 0 }, "word": { "distinct_session_connector_used_count": 0 } }, "connector_display_name": "connector_display_name", "individual_auth_distinct_user_count": 0, "managed_auth_distinct_user_count": 0, "product": "product", "rbac_group_id": "rbac_group_id", "rbac_group_name": "rbac_group_name", "read_call_count": 0, "unclassified_call_count": 0, "user_id": "user_id", "write_call_count": 0 } ], "next_page": "next_page" }, "status": [ "DOCUMENTED" ], "sources": [ { "url": "https://platform.claude.com/docs/en/api/beta/organization/analytics/connectors/list", "retrieved_at": "2026-09-18" }, { "url": "https://platform.claude.com/docs/en/api/beta/organization/analytics/connectors", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/anthropic-platform-objects.json" }, { "provider": "anthropic", "api_family": "admin", "name": "CostBucket", "official_type_name": "BetaCostBucket", "description": "Response object of GET /v1/organizations/analytics/cost_report", "fields": [ { "name": "data", "type": "array of object", "required": true, "description": "Time buckets for this page, oldest first: one per `bucket_width` interval, including intervals with no data (their `results` list is empty). A page holds at most `limit` buckets." }, { "name": "data[].ending_at", "type": "string", "required": true, "description": "End of the time bucket (exclusive) in RFC 3339 format.", "constraints": { "format": "date-time" } }, { "name": "data[].results", "type": "array of object", "required": true, "description": "Rows for this time bucket. Empty when the bucket has no data; otherwise a single combined row when `group_by[]` is omitted, or one row per group (subject to the per-bucket group cap described on the `group_by[]` parameter)." }, { "name": "data[].results[].amount", "type": "string", "required": true, "description": "Amount (post-discount, pre-credit) in fractional cents." }, { "name": "data[].results[].claude_tag_category", "type": "\"dm\" or \"engaged\" or \"monitoring\" or 2 more or null", "required": true, "description": "Claude Tag (Claude in Slack) spend category: `engaged` (a person addressed Claude in a channel or thread), `proactive` (Claude responded without being addressed), `scheduled` (a scheduled routine ran), `monitoring` (Claude watching a channel it was asked to monitor), or `dm` (direct messages with Claude). Populated only when `claude_tag_category` is in `group_by[]`; null for usage that is not Claude Tag. Direct-message usage is billed to the individual user and is reported under that user's product, not under `claude-tag`. New categories may be added over time.", "enum": [ "dm", "engaged", "monitoring", "proactive", "scheduled" ] }, { "name": "data[].results[].claude_tag_user_id", "type": "string or null", "required": true, "description": "Slack user ID (for example `U0123ABCDEF`) of the member the Claude Tag (Claude in Slack) usage is attributed to, not a claude.ai user ID. Populated only when `claude_tag_user_id` is in `group_by[]`; null for usage that is not Claude Tag and for Claude Tag usage that is not attributed to a single user (for example `monitoring`, and `proactive` usage Claude initiated), so per-user rows can sum to less than the Claude Tag total. Cannot be combined with `group_by[]=rbac_group_id` or the `rbac_group_ids[]` filter." }, { "name": "data[].results[].context_window", "type": "\"0-200k\" or \"200k-1M\" or null", "required": true, "description": "Context-window pricing tier of the usage or cost. Null unless `context_window` is in `group_by[]`; it can also be null on grouped rows with no context-window tier, such as code execution.", "enum": [ "0-200k", "200k-1M" ] }, { "name": "data[].results[].cost_type", "type": "\"code_execution\" or \"tokens\" or \"web_search\" or null", "required": true, "description": "Cost component when `group_by[]=cost_type`; null otherwise (amount is the combined total).", "enum": [ "code_execution", "tokens", "web_search" ] }, { "name": "data[].results[].currency", "type": "\"USD\"", "required": true, "description": "Currency code for the cost amount. Currently always `\"USD\"`.", "default": "USD" }, { "name": "data[].results[].inference_geo", "type": "\"global\" or \"us\" or null", "required": true, "description": "Inference region of the usage or cost. Null unless `inference_geo` is in `group_by[]`; it can also be null on grouped rows where the region is not set (the rows that `inference_geos[]=not_available` matches).", "enum": [ "global", "us" ] }, { "name": "data[].results[].list_amount", "type": "string", "required": true, "description": "List-price amount (pre-discount) in fractional cents." }, { "name": "data[].results[].model", "type": "string or null", "required": true, "description": "Model that produced the usage or cost, as a model name in the form the `models[]` filter accepts (for example, `claude-opus-5`). Null unless `model` is in `group_by[]`; it can also be null on grouped rows whose usage or cost is not attributed to a specific model, such as code execution." }, { "name": "data[].results[].product", "type": "string or null", "required": true, "description": "Product surface that produced the usage or cost. Null unless product is in `group_by[]`; it can also be null on grouped rows whose usage cannot be attributed to a known surface. Values include `chat`, `claude_code`, `cowork`, `office_agent`, `claude_in_chrome`, `claude_design`, and `claude-tag`. `claude-tag` is Claude Tag, the Claude product in Slack. Some unattributed usage is reported as \"other\"." }, { "name": "data[].results[].rbac_group_id", "type": "string or null", "required": true, "description": "RBAC group (team) the usage is attributed to, in the public tagged `rbac_group_...` spelling — the same spelling the activity resources use for this key, so the same team has one id across resources and it round-trips as an `rbac_group_ids[]` filter value. Populated only when `rbac_group_id` is in `group_by[]`. Any-membership semantics: a user in several groups contributes their full usage to each of those groups' rows, so the named-group rows overlap and their sum can exceed the org total. A null value is the single unassigned row: users in no group on that (UTC) day. For the true org total, run the same query without `group_by[]`." }, { "name": "data[].results[].requests", "type": "number or null", "required": true, "description": "Number of API requests in this row's scope. Null when `group_by` includes `cost_type` or `token_type` (the count has no per-component attribution; read it from the ungrouped response). For sandbox / code-execution events, this counts execution spans rather than HTTP requests (these rows surface with `product: null`)." }, { "name": "data[].results[].slack_channel_id", "type": "string or null", "required": true, "description": "Slack channel the usage originated from. Populated only when `slack_channel_id` is in `group_by[]`; null for usage outside Slack (and for rows recorded before channel attribution was enabled)." }, { "name": "data[].results[].speed", "type": "\"fast\" or \"standard\" or null", "required": true, "description": "Inference speed mode of the usage or cost: `fast` or `standard`. Null unless `speed` is in `group_by[]`.", "enum": [ "fast", "standard" ] }, { "name": "data[].results[].token_type", "type": "\"cache_creation.ephemeral_1h_input_tokens\" or \"cache_creation.ephemeral_5m_input_tokens\" or \"cache_read_input_tokens\" or 2 more or null", "required": true, "description": "Token type when `group_by[]=token_type` and `cost_type=tokens`; null otherwise.", "enum": [ "cache_creation.ephemeral_1h_input_tokens", "cache_creation.ephemeral_5m_input_tokens", "cache_read_input_tokens", "output_tokens", "uncached_input_tokens" ] }, { "name": "data[].starting_at", "type": "string", "required": true, "description": "Start of the time bucket (inclusive) in RFC 3339 format.", "constraints": { "format": "date-time" } }, { "name": "data_refreshed_at", "type": "string or null", "required": true, "description": "RFC 3339 timestamp of the export this response was served from. Null when no export yet covers any part of the requested range, in which case every bucket's `results` list is empty. Buckets beyond this watermark are incomplete; for stable results, set `ending_at` to this value or earlier. Data is typically refreshed every 4 hours but not final until about 30 days after the usage date (late-arriving events, reconciliation adjustments).", "constraints": { "format": "date-time" } }, { "name": "has_more", "type": "boolean", "required": true, "description": "Whether another page is available. When true, pass `next_page` as the `page` parameter to fetch it." }, { "name": "next_page", "type": "string or null", "required": true, "description": "Opaque cursor for the next page, or null when `has_more` is false. Pass it as the `page` parameter, keeping the other parameters unchanged. A cursor can expire after the underlying data refreshes; the request then returns HTTP 410 and pagination must restart from the first page." }, { "name": "organization_id", "type": "string", "required": true, "description": "ID of the Organization." } ], "example": { "data": [ { "ending_at": "2019-12-27T18:11:19.117Z", "results": [ { "amount": "amount", "claude_tag_category": "dm", "claude_tag_user_id": "U0123ABCDEF", "context_window": "0-200k", "cost_type": "code_execution", "currency": "USD", "inference_geo": "global", "list_amount": "list_amount", "model": "claude-opus-5", "product": "chat", "rbac_group_id": "rbac_group_012rppKaSVsmTo6NqRDXQXNF", "requests": 0, "slack_channel_id": "C0123ABCDEF", "speed": "fast", "token_type": "cache_creation.ephemeral_1h_input_tokens" } ], "starting_at": "2019-12-27T18:11:19.117Z" } ], "data_refreshed_at": "2019-12-27T18:11:19.117Z", "has_more": true, "next_page": "next_page", "organization_id": "org_013FP9SaFPBg7Kw7fetjn6cF" }, "status": [ "DOCUMENTED" ], "sources": [ { "url": "https://platform.claude.com/docs/en/api/beta/organization/analytics/cost/list", "retrieved_at": "2026-09-18" }, { "url": "https://platform.claude.com/docs/en/api/beta/organization/analytics/cost", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/anthropic-platform-objects.json" }, { "provider": "anthropic", "api_family": "admin", "name": "PluginUsage", "official_type_name": "BetaPluginUsage", "description": "Response for GET /v1/organizations/analytics/plugins.", "fields": [ { "name": "data", "type": "array of object", "required": true, "description": "" }, { "name": "data[].claude_code_metrics", "type": "object", "required": true, "description": "Claude Code activity metrics for a single plugin on a given day." }, { "name": "data[].claude_code_metrics.distinct_session_plugin_used_count", "type": "number or null", "required": true, "description": "Number of distinct Claude Code sessions in which the plugin was invoked. Null on aggregated rows where a distinct count cannot be computed." }, { "name": "data[].cowork_metrics", "type": "object", "required": true, "description": "Cowork activity metrics for a single plugin on a given day." }, { "name": "data[].cowork_metrics.distinct_session_plugin_used_count", "type": "number or null", "required": true, "description": "Number of distinct Cowork sessions in which the plugin was invoked. Null on aggregated rows where a distinct count cannot be computed." }, { "name": "data[].distinct_user_count", "type": "number", "required": true, "description": "Number of distinct users with recorded install or invocation activity for the plugin on the requested day (install-only users count), or, in date-range mode, over the requested window — recomputed as an exact distinct count over the window's per-member daily rows, never a sum of per-day values." }, { "name": "data[].install_count", "type": "number or null", "required": true, "description": "Number of distinct users who installed the plugin on the requested day, or, in date-range mode, over the requested window — recomputed as an exact distinct count over the window's per-member daily rows, never a sum of per-day values." }, { "name": "data[].invocation_count", "type": "number", "required": true, "description": "Number of plugin invocations on the requested day" }, { "name": "data[].plugin_name", "type": "string", "required": true, "description": "Name of the plugin" }, { "name": "data[].plugin_id", "type": "string or null", "required": false, "description": "Stable plugin identifier when available (e.g. `serena@claude-plugins-official`). Null for third-party Claude Code plugins (redacted at the source) and Cowork slash commands that carry only a hashed id." }, { "name": "data[].product", "type": "string or null", "required": false, "description": "Product that produced this row's activity: one of `chat`, `claude_code`, `cowork`, or `office_agent` (the canonical Cost & Usage product naming; an `office_agent` row's per-surface breakdown is in its `office_metrics`). On `/plugins` only `cowork` and `claude_code` occur (the only surfaces with plugin attribution); on `/artifacts` only `chat`, `claude_code`, and `cowork` occur (the surfaces that create artifacts); `/apps/chat/projects` does not support the product dimension (a `product` entry in `group_by[]` or `filter[]` there is rejected). Present only when the request grouped by `product`." }, { "name": "data[].rbac_group_id", "type": "string or null", "required": false, "description": "Tagged RBAC group identifier (`rbac_group_...`), matching the spend-limits API spelling. Present only when the request grouped by `rbac_group_id`." }, { "name": "data[].rbac_group_name", "type": "string or null", "required": false, "description": "Resolved RBAC group display name, alongside `rbac_group_id` when name resolution is available. Null if the group has been deleted or its name could not be resolved; `rbac_group_id` remains the stable key." }, { "name": "data[].user_id", "type": "string or null", "required": false, "description": "Tagged user identifier (e.g. `user_...`). Present only when the request grouped by `user_id`." }, { "name": "next_page", "type": "string or null", "required": true, "description": "Opaque cursor for the next page, or null if no more results" } ], "example": { "data": [ { "claude_code_metrics": { "distinct_session_plugin_used_count": 0 }, "cowork_metrics": { "distinct_session_plugin_used_count": 0 }, "distinct_user_count": 0, "install_count": 0, "invocation_count": 0, "plugin_name": "plugin_name", "plugin_id": "plugin_id", "product": "product", "rbac_group_id": "rbac_group_id", "rbac_group_name": "rbac_group_name", "user_id": "user_id" } ], "next_page": "next_page" }, "status": [ "DOCUMENTED" ], "sources": [ { "url": "https://platform.claude.com/docs/en/api/beta/organization/analytics/plugins/list", "retrieved_at": "2026-09-18" }, { "url": "https://platform.claude.com/docs/en/api/beta/organization/analytics/plugins", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/anthropic-platform-objects.json" }, { "provider": "anthropic", "api_family": "admin", "name": "SkillUsage", "official_type_name": "BetaSkillUsage", "description": "Response for GET /v1/organizations/analytics/skills.", "fields": [ { "name": "data", "type": "array of object", "required": true, "description": "" }, { "name": "data[].chat_metrics", "type": "object", "required": true, "description": "Claude.ai activity metrics for a single skill on a given day." }, { "name": "data[].chat_metrics.distinct_conversation_skill_used_count", "type": "number or null", "required": true, "description": "Number of distinct conversations in which the skill was used. A skill counts as used only when it is explicitly activated — the model (or the user, via the skill's slash command) invokes it, reading its instructions into context as part of that activation. Skills that are merely installed or listed as available, or whose content reaches the context without an activation (preloaded, hook-injected, or read as a plain file), are not counted. Approximate (HLL, typical error <2%) in date-range mode. Null on aggregated rows where a distinct count cannot be computed." }, { "name": "data[].claude_code_metrics", "type": "object", "required": true, "description": "Claude Code activity metrics for a single skill on a given day." }, { "name": "data[].claude_code_metrics.distinct_session_skill_used_count", "type": "number or null", "required": true, "description": "Number of distinct Claude Code sessions in which the skill was used. A skill counts as used only when it is explicitly activated — the model (or the user, via the skill's slash command) invokes it, reading its instructions into context as part of that activation. Skills that are merely installed or listed as available, or whose content reaches the context without an activation (preloaded, hook-injected, or read as a plain file), are not counted. Approximate (HLL, typical error <2%) in date-range mode. Null on aggregated rows where a distinct count cannot be computed." }, { "name": "data[].cowork_metrics", "type": "object", "required": true, "description": "Cowork activity metrics for a single skill on a given day." }, { "name": "data[].cowork_metrics.distinct_session_skill_used_count", "type": "number or null", "required": true, "description": "Number of distinct Cowork sessions in which the skill was used. A skill counts as used only when it is explicitly activated — the model (or the user, via the skill's slash command) invokes it, reading its instructions into context as part of that activation. Skills that are merely installed or listed as available, or whose content reaches the context without an activation (preloaded, hook-injected, or read as a plain file), are not counted. Approximate (HLL, typical error <2%) in date-range mode. Null on aggregated rows where a distinct count cannot be computed." }, { "name": "data[].distinct_user_count", "type": "number", "required": true, "description": "Number of distinct users who used the skill on the requested day, or, in date-range mode, over the requested window — recomputed as an exact distinct count over the window's per-member daily rows, never a sum of per-day values. A skill counts as used only when it is explicitly activated — the model (or the user, via the skill's slash command) invokes it, reading its instructions into context as part of that activation. Skills that are merely installed or listed as available, or whose content reaches the context without an activation (preloaded, hook-injected, or read as a plain file), are not counted." }, { "name": "data[].office_metrics", "type": "object", "required": true, "description": "Office Agent activity metrics for a single skill on a given day, broken out by Office product." }, { "name": "data[].office_metrics.excel", "type": "BetaSkillOfficeProductMetrics", "required": true, "description": "Office Agent activity metrics for a single skill on a given day within one Office product." }, { "name": "data[].office_metrics.outlook", "type": "BetaSkillOfficeProductMetrics", "required": true, "description": "Office Agent activity metrics for a single skill on a given day within one Office product." }, { "name": "data[].office_metrics.powerpoint", "type": "BetaSkillOfficeProductMetrics", "required": true, "description": "Office Agent activity metrics for a single skill on a given day within one Office product." }, { "name": "data[].office_metrics.word", "type": "BetaSkillOfficeProductMetrics", "required": true, "description": "Office Agent activity metrics for a single skill on a given day within one Office product." }, { "name": "data[].skill_name", "type": "string", "required": true, "description": "Name of the skill" }, { "name": "data[].attributed_list_price", "type": "string or null", "required": false, "description": "List-price (rate-card) value of the member requests attributed to this skill, as a decimal string in the minor unit of `currency` (cents for USD), from Claude Code, Cowork, and Office Agent request-level attribution — the value of requests that involved the skill, not the skill's incremental cost. Unlike `estimated_overage_spend` this reflects usage value regardless of how it was funded — seat-covered usage counts — but it is undiscounted and does not tie to billed spend or the organization's spend reporting. claude.ai chat usage carries no request-level attribution and contributes nothing: the field is null on `chat` product rows and on `office_agent` product cuts dated before 2026-06-18 (the Office Agent attribution data-start), and on ungrouped rows it covers the Claude Code + Cowork + Office Agent share only (null when no attributable usage exists). Also null under the same conditions as `estimated_overage_spend` (spend reporting not enabled for this organization, `office_agent` product cuts before the 2026-06-18 data-start). \"0\" means attributable usage existed but none was attributed to this skill. Addable across days: date-range rollup mode returns the window's sum. On `group_by[]` and `filter[]` shapes both amounts can total below the ungrouped value for the same skill over the same date or range: spend attributed to a member–skill pair with no counted usage on that day is excluded from those cuts." }, { "name": "data[].currency", "type": "\"USD\" or null", "required": false, "description": "Currency for this row's monetary fields (`estimated_overage_spend` and `attributed_list_price`), as an uppercase ISO-4217 code. Always \"USD\" when either amount is populated; null whenever both amounts are null." }, { "name": "data[].enable_count", "type": "number or null", "required": false, "description": "Distinct accounts that enabled this skill on the requested day (claude.ai only — the skill analog of plugin `install_count`). The count is org-wide: null when enable reporting is not enabled for this organization, or when the request scopes to `user_id` / `rbac_group_id` / `product` via `group_by[]` or `filter[]` (an org-wide count would be misleading on per-cut rows). A distinct count, not an event count: summing across days double-counts members who enable the skill on more than one day, so it is also null in date-range rollup mode (`starting_date`/`ending_date`)." }, { "name": "data[].estimated_overage_spend", "type": "string or null", "required": false, "description": "Estimated overage spend attributed to this skill, as a decimal string in the minor unit of `currency` (cents for USD; \"1250\" is $12.50, fractional cents possible) — an allocation of each member's daily post-discount, pre-credit metered overage spend (the same cost basis as the organization's spend reporting and the Cost & Usage API, so per-skill figures are directly comparable; spend with no skill attribution — including any member-day without skill invocations — is not represented, so skill rows sum to at most those totals) across the skills the member used. Overage only: usage covered by included seat allowances bills nothing and allocates $0 here — see `attributed_list_price` for the funding-independent usage-value companion. Claude Code, Cowork, and Office Agent spend use request-level skill attribution; claude.ai chat spend is approximated proportionally to skill-invoking messages. An estimate, not a billing number — and the cost of the requests/messages that involved the skill, not the skill's incremental cost (the same request would still have cost something without the skill active). \"0\" means no overage spend was attributed; null when spend reporting is not enabled for this organization, on `office_agent` product cuts dated before 2026-06-18 (the Office Agent attribution data-start). Addable across days: date-range rollup mode (`starting_date`/`ending_date`) returns the window's sum. With `group_by[]=user_id` each row carries the user's own attributed spend. On `group_by[]` and `filter[]` shapes both amounts can total below the ungrouped value for the same skill over the same date or range: spend attributed to a member–skill pair with no counted usage on that day is excluded from those cuts." }, { "name": "data[].invocation_count", "type": "number or null", "required": false, "description": "Total number of times this skill was invoked on the requested day (the skill analog of plugin `invocation_count`). Unlike `distinct_user_count` — which answers '\\# of users' — this is the true '# of uses'. A skill counts as used only when it is explicitly activated — the model (or the user, via the skill's slash command) invokes it, reading its instructions into context as part of that activation. Skills that are merely installed or listed as available, or whose content reaches the context without an activation (preloaded, hook-injected, or read as a plain file), are not counted. Null when invocation reporting is not enabled for this organization. Sum across a date range for total uses in the window — date-range rollup mode (`starting_date`/`ending_date`) returns this sum directly." }, { "name": "data[].product", "type": "string or null", "required": false, "description": "Product that produced this row's activity: one of `chat`, `claude_code`, `cowork`, or `office_agent` (the canonical Cost & Usage product naming; an `office_agent` row's per-surface breakdown is in its `office_metrics`). On `/plugins` only `cowork` and `claude_code` occur (the only surfaces with plugin attribution); on `/artifacts` only `chat`, `claude_code`, and `cowork` occur (the surfaces that create artifacts); `/apps/chat/projects` does not support the product dimension (a `product` entry in `group_by[]` or `filter[]` there is rejected). Present only when the request grouped by `product`." }, { "name": "data[].rbac_group_id", "type": "string or null", "required": false, "description": "Tagged RBAC group identifier (`rbac_group_...`), matching the spend-limits API spelling. Present only when the request grouped by `rbac_group_id`." }, { "name": "data[].rbac_group_name", "type": "string or null", "required": false, "description": "Resolved RBAC group display name, alongside `rbac_group_id` when name resolution is available. Null if the group has been deleted or its name could not be resolved; `rbac_group_id` remains the stable key." }, { "name": "data[].share_status", "type": "\"organization\" or \"private\" or \"public\" or null", "required": false, "description": "Skill share status (claude.ai only): one of `private`, `organization`, or `public`. Null for skills used only in Claude Code or Office (no per-skill share-status concept) and when share-status reporting is not yet available for the organization. Filterable via `filter[]=share_status:{value}`.", "enum": [ "organization", "private", "public" ] }, { "name": "data[].skill_display_name", "type": "string or null", "required": false, "description": "Human-readable display name for rows whose `skill_name` is an opaque skill id (user/organization skill types and plugin-delivered skills — user-defined names are withheld from the analytics pipeline). Organization-shared skills and skills delivered by the organization's own plugins (its plugin marketplaces and its library) resolve; plugin skill names are shown without their 'plugin:' prefix. The literal 'unknown' bucket row gets a fixed 'Unknown skill' label. Null for private (user-defined) skills and members' personal-plugin skills — those names are not disclosed to analytics-key holders — and for Anthropic-provided plugin skills (not resolved), and null when `skill_name` is already a display name, when the skill or plugin was deleted, or when display-name resolution is not enabled for this organization." }, { "name": "data[].user_id", "type": "string or null", "required": false, "description": "Tagged user identifier (e.g. `user_...`). Present only when the request grouped by `user_id`." }, { "name": "next_page", "type": "string or null", "required": true, "description": "Opaque cursor for the next page, or null if no more results" } ], "example": { "data": [ { "chat_metrics": { "distinct_conversation_skill_used_count": 0 }, "claude_code_metrics": { "distinct_session_skill_used_count": 0 }, "cowork_metrics": { "distinct_session_skill_used_count": 0 }, "distinct_user_count": 0, "office_metrics": { "excel": { "distinct_session_skill_used_count": 0 }, "outlook": { "distinct_session_skill_used_count": 0 }, "powerpoint": { "distinct_session_skill_used_count": 0 }, "word": { "distinct_session_skill_used_count": 0 } }, "skill_name": "skill_name", "attributed_list_price": "attributed_list_price", "currency": "USD", "enable_count": 0, "estimated_overage_spend": "estimated_overage_spend", "invocation_count": 0, "product": "product", "rbac_group_id": "rbac_group_id", "rbac_group_name": "rbac_group_name", "share_status": "organization", "skill_display_name": "skill_display_name", "user_id": "user_id" } ], "next_page": "next_page" }, "status": [ "DOCUMENTED" ], "sources": [ { "url": "https://platform.claude.com/docs/en/api/beta/organization/analytics/skills/list", "retrieved_at": "2026-09-18" }, { "url": "https://platform.claude.com/docs/en/api/beta/organization/analytics/skills", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/anthropic-platform-objects.json" }, { "provider": "anthropic", "api_family": "admin", "name": "ActivitySummary", "official_type_name": "BetaActivitySummary", "description": "Response for GET /v1/organizations/analytics/summaries.", "fields": [ { "name": "summaries", "type": "array of object", "required": true, "description": "" }, { "name": "summaries[].assigned_seat_count", "type": "number or null", "required": true, "description": "Number of seats currently assigned to members. Null when the response is scoped to an RBAC group — seat assignment is org-wide and has no per-group analogue." }, { "name": "summaries[].cowork_daily_active_user_count", "type": "number", "required": true, "description": "Number of users with Cowork activity on the requested day" }, { "name": "summaries[].cowork_monthly_active_user_count", "type": "number", "required": true, "description": "Number of users with Cowork activity in the 30-day rolling window" }, { "name": "summaries[].cowork_weekly_active_user_count", "type": "number", "required": true, "description": "Number of users with Cowork activity in the 7-day rolling window" }, { "name": "summaries[].daily_active_user_count", "type": "number", "required": true, "description": "Number of users with token consumption on the requested day" }, { "name": "summaries[].daily_adoption_rate", "type": "number or null", "required": true, "description": "Percentage of assigned seats with activity on the requested day (`DAU / assigned_seat_count * 100`). Null when the response is scoped to an RBAC group." }, { "name": "summaries[].ending_at", "type": "string", "required": true, "description": "End of the aggregation period (exclusive), UTC midnight in RFC 3339 format (e.g. `2026-01-16T00:00:00Z`).", "constraints": { "format": "date-time" } }, { "name": "summaries[].monthly_active_user_count", "type": "number", "required": true, "description": "Number of users with token consumption in the 30-day rolling window" }, { "name": "summaries[].monthly_adoption_rate", "type": "number or null", "required": true, "description": "Percentage of assigned seats with activity in the 30-day rolling window (`MAU / assigned_seat_count * 100`). Null when the response is scoped to an RBAC group." }, { "name": "summaries[].pending_invite_count", "type": "number or null", "required": true, "description": "Number of pending invitations to join the organization. Null when the response is scoped to an RBAC group." }, { "name": "summaries[].starting_at", "type": "string", "required": true, "description": "Start of the aggregation period (inclusive), UTC midnight in RFC 3339 format (e.g. `2026-01-15T00:00:00Z`).", "constraints": { "format": "date-time" } }, { "name": "summaries[].weekly_active_user_count", "type": "number", "required": true, "description": "Number of users with token consumption in the 7-day rolling window" }, { "name": "summaries[].weekly_adoption_rate", "type": "number or null", "required": true, "description": "Percentage of assigned seats with activity in the 7-day rolling window (`WAU / assigned_seat_count * 100`). Null when the response is scoped to an RBAC group." }, { "name": "summaries[].chat_daily_active_user_count", "type": "number or null", "required": false, "description": "Number of users with claude.ai (chat) activity on the requested day. Omitted from the response while the per-product breakdown is not enabled for this organization." }, { "name": "summaries[].chat_monthly_active_user_count", "type": "number or null", "required": false, "description": "Number of users with claude.ai (chat) activity in the 30-day rolling window. Omitted from the response while the per-product breakdown is not enabled for this organization." }, { "name": "summaries[].chat_weekly_active_user_count", "type": "number or null", "required": false, "description": "Number of users with claude.ai (chat) activity in the 7-day rolling window. Omitted from the response while the per-product breakdown is not enabled for this organization." }, { "name": "summaries[].claude_code_daily_active_user_count", "type": "number or null", "required": false, "description": "Number of users with Claude Code activity on the requested day. Omitted from the response while the per-product breakdown is not enabled for this organization." }, { "name": "summaries[].claude_code_monthly_active_user_count", "type": "number or null", "required": false, "description": "Number of users with Claude Code activity in the 30-day rolling window. Omitted from the response while the per-product breakdown is not enabled for this organization." }, { "name": "summaries[].claude_code_weekly_active_user_count", "type": "number or null", "required": false, "description": "Number of users with Claude Code activity in the 7-day rolling window. Omitted from the response while the per-product breakdown is not enabled for this organization." }, { "name": "summaries[].claude_design_daily_active_user_count", "type": "number or null", "required": false, "description": "Number of users with Claude Design activity on the requested day. Omitted from the response while the per-product breakdown is not enabled for this organization." }, { "name": "summaries[].claude_design_monthly_active_user_count", "type": "number or null", "required": false, "description": "Number of users with Claude Design activity in the 30-day rolling window. Omitted from the response while the per-product breakdown is not enabled for this organization." }, { "name": "summaries[].claude_design_weekly_active_user_count", "type": "number or null", "required": false, "description": "Number of users with Claude Design activity in the 7-day rolling window. Omitted from the response while the per-product breakdown is not enabled for this organization." }, { "name": "summaries[].office_agent_daily_active_user_count", "type": "number or null", "required": false, "description": "Number of users with Claude in Office activity on the requested day. Omitted from the response while the per-product breakdown is not enabled for this organization." }, { "name": "summaries[].office_agent_monthly_active_user_count", "type": "number or null", "required": false, "description": "Number of users with Claude in Office activity in the 30-day rolling window. Omitted from the response while the per-product breakdown is not enabled for this organization." }, { "name": "summaries[].office_agent_weekly_active_user_count", "type": "number or null", "required": false, "description": "Number of users with Claude in Office activity in the 7-day rolling window. Omitted from the response while the per-product breakdown is not enabled for this organization." }, { "name": "summaries[].science_daily_active_user_count", "type": "number or null", "required": false, "description": "Number of users with Claude Science activity on the requested day. Omitted from the response while the per-product breakdown is not enabled for this organization." }, { "name": "summaries[].science_entitled_user_count", "type": "number or null", "required": false, "description": "Number of users with a Claude Science seat entitlement (per-seat RBAC) at the time of the daily snapshot. The funnel top; independent of the org-level Claude Science toggle. Null when the response is scoped to an RBAC group — entitlement is org-wide and has no per-group analogue. Omitted from the response while the per-product breakdown is not enabled for this organization." }, { "name": "summaries[].science_monthly_active_user_count", "type": "number or null", "required": false, "description": "Number of users with Claude Science activity in the 30-day rolling window. Omitted from the response while the per-product breakdown is not enabled for this organization." }, { "name": "summaries[].science_weekly_active_user_count", "type": "number or null", "required": false, "description": "Number of users with Claude Science activity in the 7-day rolling window. Omitted from the response while the per-product breakdown is not enabled for this organization." } ], "example": { "summaries": [ { "assigned_seat_count": 0, "cowork_daily_active_user_count": 0, "cowork_monthly_active_user_count": 0, "cowork_weekly_active_user_count": 0, "daily_active_user_count": 0, "daily_adoption_rate": 0, "ending_at": "2019-12-27T18:11:19.117Z", "monthly_active_user_count": 0, "monthly_adoption_rate": 0, "pending_invite_count": 0, "starting_at": "2019-12-27T18:11:19.117Z", "weekly_active_user_count": 0, "weekly_adoption_rate": 0, "chat_daily_active_user_count": 0, "chat_monthly_active_user_count": 0, "chat_weekly_active_user_count": 0, "claude_code_daily_active_user_count": 0, "claude_code_monthly_active_user_count": 0, "claude_code_weekly_active_user_count": 0, "claude_design_daily_active_user_count": 0, "claude_design_monthly_active_user_count": 0, "claude_design_weekly_active_user_count": 0, "office_agent_daily_active_user_count": 0, "office_agent_monthly_active_user_count": 0, "office_agent_weekly_active_user_count": 0, "science_daily_active_user_count": 0, "science_entitled_user_count": 0, "science_monthly_active_user_count": 0, "science_weekly_active_user_count": 0 } ] }, "status": [ "DOCUMENTED" ], "sources": [ { "url": "https://platform.claude.com/docs/en/api/beta/organization/analytics/retrieve_summaries", "retrieved_at": "2026-09-18" }, { "url": "https://platform.claude.com/docs/en/api/beta/organization/analytics", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/anthropic-platform-objects.json" }, { "provider": "anthropic", "api_family": "admin", "name": "UsageBucket", "official_type_name": "BetaUsageBucket", "description": "Response object of GET /v1/organizations/analytics/usage_report", "fields": [ { "name": "data", "type": "array of object", "required": true, "description": "Time buckets for this page, oldest first: one per `bucket_width` interval, including intervals with no data (their `results` list is empty). A page holds at most `limit` buckets." }, { "name": "data[].ending_at", "type": "string", "required": true, "description": "End of the time bucket (exclusive) in RFC 3339 format.", "constraints": { "format": "date-time" } }, { "name": "data[].results", "type": "array of object", "required": true, "description": "Rows for this time bucket. Empty when the bucket has no data; otherwise a single combined row when `group_by[]` is omitted, or one row per group (subject to the per-bucket group cap described on the `group_by[]` parameter)." }, { "name": "data[].results[].cache_creation", "type": "BetaCacheCreation", "required": true, "description": "The number of input tokens for cache creation." }, { "name": "data[].results[].cache_read_input_tokens", "type": "number", "required": true, "description": "The number of input tokens read from the cache." }, { "name": "data[].results[].claude_tag_category", "type": "\"dm\" or \"engaged\" or \"monitoring\" or 2 more or null", "required": true, "description": "Claude Tag (Claude in Slack) spend category: `engaged` (a person addressed Claude in a channel or thread), `proactive` (Claude responded without being addressed), `scheduled` (a scheduled routine ran), `monitoring` (Claude watching a channel it was asked to monitor), or `dm` (direct messages with Claude). Populated only when `claude_tag_category` is in `group_by[]`; null for usage that is not Claude Tag. Direct-message usage is billed to the individual user and is reported under that user's product, not under `claude-tag`. New categories may be added over time.", "enum": [ "dm", "engaged", "monitoring", "proactive", "scheduled" ] }, { "name": "data[].results[].claude_tag_user_id", "type": "string or null", "required": true, "description": "Slack user ID (for example `U0123ABCDEF`) of the member the Claude Tag (Claude in Slack) usage is attributed to, not a claude.ai user ID. Populated only when `claude_tag_user_id` is in `group_by[]`; null for usage that is not Claude Tag and for Claude Tag usage that is not attributed to a single user (for example `monitoring`, and `proactive` usage Claude initiated), so per-user rows can sum to less than the Claude Tag total. Cannot be combined with `group_by[]=rbac_group_id` or the `rbac_group_ids[]` filter." }, { "name": "data[].results[].context_window", "type": "\"0-200k\" or \"200k-1M\" or null", "required": true, "description": "Context-window pricing tier of the usage or cost. Null unless `context_window` is in `group_by[]`; it can also be null on grouped rows with no context-window tier, such as code execution.", "enum": [ "0-200k", "200k-1M" ] }, { "name": "data[].results[].inference_geo", "type": "\"global\" or \"us\" or null", "required": true, "description": "Inference region of the usage or cost. Null unless `inference_geo` is in `group_by[]`; it can also be null on grouped rows where the region is not set (the rows that `inference_geos[]=not_available` matches).", "enum": [ "global", "us" ] }, { "name": "data[].results[].model", "type": "string or null", "required": true, "description": "Model that produced the usage or cost, as a model name in the form the `models[]` filter accepts (for example, `claude-opus-5`). Null unless `model` is in `group_by[]`; it can also be null on grouped rows whose usage or cost is not attributed to a specific model, such as code execution." }, { "name": "data[].results[].output_tokens", "type": "number", "required": true, "description": "The number of output tokens generated." }, { "name": "data[].results[].product", "type": "string or null", "required": true, "description": "Product surface that produced the usage or cost. Null unless product is in `group_by[]`; it can also be null on grouped rows whose usage cannot be attributed to a known surface. Values include `chat`, `claude_code`, `cowork`, `office_agent`, `claude_in_chrome`, `claude_design`, and `claude-tag`. `claude-tag` is Claude Tag, the Claude product in Slack. Some unattributed usage is reported as \"other\"." }, { "name": "data[].results[].rbac_group_id", "type": "string or null", "required": true, "description": "RBAC group (team) the usage is attributed to, in the public tagged `rbac_group_...` spelling — the same spelling the activity resources use for this key, so the same team has one id across resources and it round-trips as an `rbac_group_ids[]` filter value. Populated only when `rbac_group_id` is in `group_by[]`. Any-membership semantics: a user in several groups contributes their full usage to each of those groups' rows, so the named-group rows overlap and their sum can exceed the org total. A null value is the single unassigned row: users in no group on that (UTC) day. For the true org total, run the same query without `group_by[]`." }, { "name": "data[].results[].requests", "type": "number or null", "required": true, "description": "Number of API requests in this row's scope. For sandbox / code-execution events, this counts execution spans rather than HTTP requests (these rows surface with `product: null`)." }, { "name": "data[].results[].server_tool_use", "type": "object", "required": true, "description": "Server-side tool usage metrics." }, { "name": "data[].results[].slack_channel_id", "type": "string or null", "required": true, "description": "Slack channel the usage originated from. Populated only when `slack_channel_id` is in `group_by[]`; null for usage outside Slack (and for rows recorded before channel attribution was enabled)." }, { "name": "data[].results[].speed", "type": "\"fast\" or \"standard\" or null", "required": true, "description": "Inference speed mode of the usage or cost: `fast` or `standard`. Null unless `speed` is in `group_by[]`.", "enum": [ "fast", "standard" ] }, { "name": "data[].results[].uncached_input_tokens", "type": "number", "required": true, "description": "The number of uncached input tokens processed." }, { "name": "data[].starting_at", "type": "string", "required": true, "description": "Start of the time bucket (inclusive) in RFC 3339 format.", "constraints": { "format": "date-time" } }, { "name": "data_refreshed_at", "type": "string or null", "required": true, "description": "RFC 3339 timestamp of the export this response was served from. Null when no export yet covers any part of the requested range, in which case every bucket's `results` list is empty. Buckets beyond this watermark are incomplete; for stable results, set `ending_at` to this value or earlier. Data is typically refreshed every 4 hours but not final until about 30 days after the usage date (late-arriving events, reconciliation adjustments).", "constraints": { "format": "date-time" } }, { "name": "has_more", "type": "boolean", "required": true, "description": "Whether another page is available. When true, pass `next_page` as the `page` parameter to fetch it." }, { "name": "next_page", "type": "string or null", "required": true, "description": "Opaque cursor for the next page, or null when `has_more` is false. Pass it as the `page` parameter, keeping the other parameters unchanged. A cursor can expire after the underlying data refreshes; the request then returns HTTP 410 and pagination must restart from the first page." }, { "name": "organization_id", "type": "string", "required": true, "description": "ID of the Organization." } ], "example": { "data": [ { "ending_at": "2019-12-27T18:11:19.117Z", "results": [ { "cache_creation": { "ephemeral_1h_input_tokens": 0, "ephemeral_5m_input_tokens": 0 }, "cache_read_input_tokens": 0, "claude_tag_category": "dm", "claude_tag_user_id": "U0123ABCDEF", "context_window": "0-200k", "inference_geo": "global", "model": "claude-opus-5", "output_tokens": 0, "product": "chat", "rbac_group_id": "rbac_group_012rppKaSVsmTo6NqRDXQXNF", "requests": 0, "server_tool_use": { "web_search_requests": 10 }, "slack_channel_id": "C0123ABCDEF", "speed": "fast", "uncached_input_tokens": 0 } ], "starting_at": "2019-12-27T18:11:19.117Z" } ], "data_refreshed_at": "2019-12-27T18:11:19.117Z", "has_more": true, "next_page": "next_page", "organization_id": "org_013FP9SaFPBg7Kw7fetjn6cF" }, "status": [ "DOCUMENTED" ], "sources": [ { "url": "https://platform.claude.com/docs/en/api/beta/organization/analytics/usage/list", "retrieved_at": "2026-09-18" }, { "url": "https://platform.claude.com/docs/en/api/beta/organization/analytics/usage", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/anthropic-platform-objects.json" }, { "provider": "anthropic", "api_family": "admin", "name": "UserCost", "official_type_name": "BetaUserCost", "description": "Response object of GET /v1/organizations/analytics/user_cost_report", "fields": [ { "name": "data", "type": "array of object", "required": true, "description": "Rows for this page, ranked by `order_by` in the `order` direction. One row per user, or several per user when `group_by[]` or `bucket_width` breaks that user's usage or cost out across rows. Rows split out by `cost_type` or `token_type` (cost endpoint only) stay adjacent and are ranked as one unit." }, { "name": "data[].actor", "type": "BetaAnalyticsUserActor", "required": true, "description": "The user this row's usage or cost is attributed to. Always a `user_actor`." }, { "name": "data[].actor.type", "type": "\"user_actor\"", "required": true, "description": "Actor type. Always `\"user_actor\"`." }, { "name": "data[].actor.deleted", "type": "boolean", "required": true, "description": "True when the account has been deleted, or when the user is no longer a member of the organization or its associated organizations (for example, their membership was removed or they were deprovisioned via your identity provider). `email` stays populated for removed users and is null when the account has been deleted. `name` follows the rules described on that field. The `user_id` is still populated for reconciliation." }, { "name": "data[].actor.email", "type": "string or null", "required": true, "description": "The user's email address, including for users who are no longer members of the organization or its associated organizations. Null when the account has been deleted (check `deleted`) and for system-minted service accounts, which have no person's mailbox behind them (check `name`)." }, { "name": "data[].actor.name", "type": "string or null", "required": true, "description": "The user's full name. Null when the user has not set a name. Returns `\"Deleted User\"` when the account itself has been deleted, or when the user is no longer a member of the organization or its associated organizations and the organization has chosen to hide the names of removed users. Otherwise, the name stays populated for removed users. Rows for system-minted service accounts render the service name (for example, `\"Claude Security\"` for usage by Anthropic's security-patching service) or null." }, { "name": "data[].actor.user_id", "type": "string", "required": true, "description": "Tagged user ID." }, { "name": "data[].amount", "type": "string", "required": true, "description": "Amount (post-discount, pre-credit) in fractional cents (minor units)." }, { "name": "data[].claude_tag_category", "type": "\"dm\" or \"engaged\" or \"monitoring\" or 2 more or null", "required": true, "description": "Claude Tag (Claude in Slack) spend category: `engaged` (a person addressed Claude in a channel or thread), `proactive` (Claude responded without being addressed), `scheduled` (a scheduled routine ran), `monitoring` (Claude watching a channel it was asked to monitor), or `dm` (direct messages with Claude). Populated only when `claude_tag_category` is in `group_by[]`; null for usage that is not Claude Tag. Direct-message usage is billed to the individual user and is reported under that user's product, not under `claude-tag`. New categories may be added over time.", "enum": [ "dm", "engaged", "monitoring", "proactive", "scheduled" ] }, { "name": "data[].claude_tag_user_id", "type": "string or null", "required": true, "description": "Slack user ID (for example `U0123ABCDEF`) of the member the Claude Tag (Claude in Slack) usage is attributed to, not a claude.ai user ID. Populated only when `claude_tag_user_id` is in `group_by[]`; null for usage that is not Claude Tag and for Claude Tag usage that is not attributed to a single user (for example `monitoring`, and `proactive` usage Claude initiated), so per-user rows can sum to less than the Claude Tag total. Cannot be combined with `group_by[]=rbac_group_id` or the `rbac_group_ids[]` filter." }, { "name": "data[].context_window", "type": "\"0-200k\" or \"200k-1M\" or null", "required": true, "description": "Context-window pricing tier of the usage or cost. Null unless `context_window` is in `group_by[]`; it can also be null on grouped rows with no context-window tier, such as code execution.", "enum": [ "0-200k", "200k-1M" ] }, { "name": "data[].cost_type", "type": "\"code_execution\" or \"tokens\" or \"web_search\" or null", "required": true, "description": "Cost component breakdown; null when returning the combined total.", "enum": [ "code_execution", "tokens", "web_search" ] }, { "name": "data[].currency", "type": "\"USD\"", "required": true, "description": "Currency code for the cost amount. Currently always `\"USD\"`.", "default": "USD" }, { "name": "data[].ending_at", "type": "string or null", "required": true, "description": "End of the row's UTC time bucket (exclusive), as an RFC 3339 timestamp; equal to `starting_at` plus one `bucket_width`. Null unless `bucket_width` is set.", "constraints": { "format": "date-time" } }, { "name": "data[].inference_geo", "type": "\"global\" or \"us\" or null", "required": true, "description": "Inference region of the usage or cost. Null unless `inference_geo` is in `group_by[]`; it can also be null on grouped rows where the region is not set (the rows that `inference_geos[]=not_available` matches).", "enum": [ "global", "us" ] }, { "name": "data[].list_amount", "type": "string", "required": true, "description": "List-price amount (pre-discount) in fractional cents." }, { "name": "data[].model", "type": "string or null", "required": true, "description": "Model that produced the usage or cost, as a model name in the form the `models[]` filter accepts (for example, `claude-opus-5`). Null unless `model` is in `group_by[]`; it can also be null on grouped rows whose usage or cost is not attributed to a specific model, such as code execution." }, { "name": "data[].product", "type": "string or null", "required": true, "description": "Product surface that produced the usage or cost. Null unless product is in `group_by[]`; it can also be null on grouped rows whose usage cannot be attributed to a known surface. Values include `chat`, `claude_code`, `cowork`, `office_agent`, `claude_in_chrome`, `claude_design`, and `claude-tag`. `claude-tag` is Claude Tag, the Claude product in Slack. Some unattributed usage is reported as \"other\"." }, { "name": "data[].rbac_group_id", "type": "string or null", "required": true, "description": "RBAC group (team) the usage is attributed to, in the public tagged `rbac_group_...` spelling — the same spelling the activity resources use for this key, so the same team has one id across resources and it round-trips as an `rbac_group_ids[]` filter value. Populated only when `rbac_group_id` is in `group_by[]`. Any-membership semantics: a user in several groups contributes their full usage to each of those groups' rows, so the named-group rows overlap and their sum can exceed the org total. A null value is the single unassigned row: users in no group on that (UTC) day. For the true org total, run the same query without `group_by[]`." }, { "name": "data[].requests", "type": "number or null", "required": true, "description": "Number of API requests in this row's scope. Null when `group_by` includes `cost_type` or `token_type` (the count has no per-component attribution; read it from the ungrouped response). For sandbox / code-execution events, this counts execution spans rather than HTTP requests (these rows surface with `product: null`)." }, { "name": "data[].slack_channel_id", "type": "string or null", "required": true, "description": "Slack channel the usage originated from. Populated only when `slack_channel_id` is in `group_by[]`; null for usage outside Slack (and for rows recorded before channel attribution was enabled)." }, { "name": "data[].speed", "type": "\"fast\" or \"standard\" or null", "required": true, "description": "Inference speed mode of the usage or cost: `fast` or `standard`. Null unless `speed` is in `group_by[]`.", "enum": [ "fast", "standard" ] }, { "name": "data[].starting_at", "type": "string or null", "required": true, "description": "Start of the row's UTC time bucket (inclusive), as an RFC 3339 timestamp. Null unless `bucket_width` is set; without `bucket_width`, each row aggregates the full requested range.", "constraints": { "format": "date-time" } }, { "name": "data[].token_type", "type": "\"cache_creation.ephemeral_1h_input_tokens\" or \"cache_creation.ephemeral_5m_input_tokens\" or \"cache_read_input_tokens\" or 2 more or null", "required": true, "description": "Token type when `cost_type` is `tokens`; null otherwise.", "enum": [ "cache_creation.ephemeral_1h_input_tokens", "cache_creation.ephemeral_5m_input_tokens", "cache_read_input_tokens", "output_tokens", "uncached_input_tokens" ] }, { "name": "data_refreshed_at", "type": "string or null", "required": true, "description": "RFC 3339 timestamp of the export this response was served from. Null when no export yet covers any part of the requested range, in which case `data` is empty. Data beyond this watermark is incomplete; for stable results, set `ending_at` to this value or earlier. Data is typically refreshed every 4 hours but not final until about 30 days after the usage date (late-arriving events, reconciliation adjustments).", "constraints": { "format": "date-time" } }, { "name": "has_more", "type": "boolean", "required": true, "description": "Whether another page is available. When true, pass `next_page` as the `page` parameter to fetch it." }, { "name": "next_page", "type": "string or null", "required": true, "description": "Opaque cursor for the next page, or null when `has_more` is false. Pass it as the `page` parameter, keeping the other parameters unchanged. A cursor can expire after the underlying data refreshes; the request then returns HTTP 410 and pagination must restart from the first page." }, { "name": "organization_id", "type": "string", "required": true, "description": "ID of the Organization." } ], "example": { "data": [ { "actor": { "deleted": true, "email": "jane@example.com", "name": "Jane Smith", "type": "user_actor", "user_id": "user_01AbCdEfGhIjKlMnOpQrSt" }, "amount": "41280.000000", "claude_tag_category": "dm", "claude_tag_user_id": "U0123ABCDEF", "context_window": "0-200k", "cost_type": "code_execution", "currency": "USD", "ending_at": "2019-12-27T18:11:19.117Z", "inference_geo": "global", "list_amount": "51600.000000", "model": "claude-opus-5", "product": "chat", "rbac_group_id": "rbac_group_012rppKaSVsmTo6NqRDXQXNF", "requests": 128, "slack_channel_id": "C0123ABCDEF", "speed": "fast", "starting_at": "2019-12-27T18:11:19.117Z", "token_type": "cache_creation.ephemeral_1h_input_tokens" } ], "data_refreshed_at": "2019-12-27T18:11:19.117Z", "has_more": true, "next_page": "next_page", "organization_id": "org_013FP9SaFPBg7Kw7fetjn6cF" }, "status": [ "DOCUMENTED" ], "sources": [ { "url": "https://platform.claude.com/docs/en/api/beta/organization/analytics/cost/list_by_user", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/anthropic-platform-objects.json" }, { "provider": "anthropic", "api_family": "admin", "name": "UserUsage", "official_type_name": "BetaUserUsage", "description": "Response object of GET /v1/organizations/analytics/user_usage_report", "fields": [ { "name": "data", "type": "array of object", "required": true, "description": "Rows for this page, ranked by `order_by` in the `order` direction. One row per user, or several per user when `group_by[]` or `bucket_width` breaks that user's usage or cost out across rows. Rows split out by `cost_type` or `token_type` (cost endpoint only) stay adjacent and are ranked as one unit." }, { "name": "data[].actor", "type": "BetaAnalyticsUserActor", "required": true, "description": "The user this row's usage or cost is attributed to. Always a `user_actor`." }, { "name": "data[].actor.type", "type": "\"user_actor\"", "required": true, "description": "Actor type. Always `\"user_actor\"`." }, { "name": "data[].actor.deleted", "type": "boolean", "required": true, "description": "True when the account has been deleted, or when the user is no longer a member of the organization or its associated organizations (for example, their membership was removed or they were deprovisioned via your identity provider). `email` stays populated for removed users and is null when the account has been deleted. `name` follows the rules described on that field. The `user_id` is still populated for reconciliation." }, { "name": "data[].actor.email", "type": "string or null", "required": true, "description": "The user's email address, including for users who are no longer members of the organization or its associated organizations. Null when the account has been deleted (check `deleted`) and for system-minted service accounts, which have no person's mailbox behind them (check `name`)." }, { "name": "data[].actor.name", "type": "string or null", "required": true, "description": "The user's full name. Null when the user has not set a name. Returns `\"Deleted User\"` when the account itself has been deleted, or when the user is no longer a member of the organization or its associated organizations and the organization has chosen to hide the names of removed users. Otherwise, the name stays populated for removed users. Rows for system-minted service accounts render the service name (for example, `\"Claude Security\"` for usage by Anthropic's security-patching service) or null." }, { "name": "data[].actor.user_id", "type": "string", "required": true, "description": "Tagged user ID." }, { "name": "data[].cache_creation", "type": "BetaCacheCreation", "required": true, "description": "The number of input tokens for cache creation." }, { "name": "data[].cache_creation.ephemeral_1h_input_tokens", "type": "number", "required": true, "description": "The number of input tokens used to create the 1 hour cache entry.", "default": "0", "minimum": 0 }, { "name": "data[].cache_creation.ephemeral_5m_input_tokens", "type": "number", "required": true, "description": "The number of input tokens used to create the 5 minute cache entry.", "default": "0", "minimum": 0 }, { "name": "data[].cache_read_input_tokens", "type": "number", "required": true, "description": "The number of input tokens read from the cache." }, { "name": "data[].claude_tag_category", "type": "\"dm\" or \"engaged\" or \"monitoring\" or 2 more or null", "required": true, "description": "Claude Tag (Claude in Slack) spend category: `engaged` (a person addressed Claude in a channel or thread), `proactive` (Claude responded without being addressed), `scheduled` (a scheduled routine ran), `monitoring` (Claude watching a channel it was asked to monitor), or `dm` (direct messages with Claude). Populated only when `claude_tag_category` is in `group_by[]`; null for usage that is not Claude Tag. Direct-message usage is billed to the individual user and is reported under that user's product, not under `claude-tag`. New categories may be added over time.", "enum": [ "dm", "engaged", "monitoring", "proactive", "scheduled" ] }, { "name": "data[].claude_tag_user_id", "type": "string or null", "required": true, "description": "Slack user ID (for example `U0123ABCDEF`) of the member the Claude Tag (Claude in Slack) usage is attributed to, not a claude.ai user ID. Populated only when `claude_tag_user_id` is in `group_by[]`; null for usage that is not Claude Tag and for Claude Tag usage that is not attributed to a single user (for example `monitoring`, and `proactive` usage Claude initiated), so per-user rows can sum to less than the Claude Tag total. Cannot be combined with `group_by[]=rbac_group_id` or the `rbac_group_ids[]` filter." }, { "name": "data[].context_window", "type": "\"0-200k\" or \"200k-1M\" or null", "required": true, "description": "Context-window pricing tier of the usage or cost. Null unless `context_window` is in `group_by[]`; it can also be null on grouped rows with no context-window tier, such as code execution.", "enum": [ "0-200k", "200k-1M" ] }, { "name": "data[].ending_at", "type": "string or null", "required": true, "description": "End of the row's UTC time bucket (exclusive), as an RFC 3339 timestamp; equal to `starting_at` plus one `bucket_width`. Null unless `bucket_width` is set.", "constraints": { "format": "date-time" } }, { "name": "data[].inference_geo", "type": "\"global\" or \"us\" or null", "required": true, "description": "Inference region of the usage or cost. Null unless `inference_geo` is in `group_by[]`; it can also be null on grouped rows where the region is not set (the rows that `inference_geos[]=not_available` matches).", "enum": [ "global", "us" ] }, { "name": "data[].model", "type": "string or null", "required": true, "description": "Model that produced the usage or cost, as a model name in the form the `models[]` filter accepts (for example, `claude-opus-5`). Null unless `model` is in `group_by[]`; it can also be null on grouped rows whose usage or cost is not attributed to a specific model, such as code execution." }, { "name": "data[].output_tokens", "type": "number", "required": true, "description": "The number of output tokens generated." }, { "name": "data[].product", "type": "string or null", "required": true, "description": "Product surface that produced the usage or cost. Null unless product is in `group_by[]`; it can also be null on grouped rows whose usage cannot be attributed to a known surface. Values include `chat`, `claude_code`, `cowork`, `office_agent`, `claude_in_chrome`, `claude_design`, and `claude-tag`. `claude-tag` is Claude Tag, the Claude product in Slack. Some unattributed usage is reported as \"other\"." }, { "name": "data[].rbac_group_id", "type": "string or null", "required": true, "description": "RBAC group (team) the usage is attributed to, in the public tagged `rbac_group_...` spelling — the same spelling the activity resources use for this key, so the same team has one id across resources and it round-trips as an `rbac_group_ids[]` filter value. Populated only when `rbac_group_id` is in `group_by[]`. Any-membership semantics: a user in several groups contributes their full usage to each of those groups' rows, so the named-group rows overlap and their sum can exceed the org total. A null value is the single unassigned row: users in no group on that (UTC) day. For the true org total, run the same query without `group_by[]`." }, { "name": "data[].requests", "type": "number or null", "required": true, "description": "Number of API requests in this row's scope. For sandbox / code-execution events, this counts execution spans rather than HTTP requests (these rows surface with `product: null`)." }, { "name": "data[].server_tool_use", "type": "object", "required": true, "description": "Server-side tool usage metrics." }, { "name": "data[].server_tool_use.web_search_requests", "type": "number", "required": true, "description": "The number of web search requests made." }, { "name": "data[].slack_channel_id", "type": "string or null", "required": true, "description": "Slack channel the usage originated from. Populated only when `slack_channel_id` is in `group_by[]`; null for usage outside Slack (and for rows recorded before channel attribution was enabled)." }, { "name": "data[].speed", "type": "\"fast\" or \"standard\" or null", "required": true, "description": "Inference speed mode of the usage or cost: `fast` or `standard`. Null unless `speed` is in `group_by[]`.", "enum": [ "fast", "standard" ] }, { "name": "data[].starting_at", "type": "string or null", "required": true, "description": "Start of the row's UTC time bucket (inclusive), as an RFC 3339 timestamp. Null unless `bucket_width` is set; without `bucket_width`, each row aggregates the full requested range.", "constraints": { "format": "date-time" } }, { "name": "data[].total_tokens", "type": "number", "required": true, "description": "Total token count across all token types. This is the value the default `order_by` (`total_tokens`) sorts on." }, { "name": "data[].uncached_input_tokens", "type": "number", "required": true, "description": "The number of uncached input tokens processed." }, { "name": "data_refreshed_at", "type": "string or null", "required": true, "description": "RFC 3339 timestamp of the export this response was served from. Null when no export yet covers any part of the requested range, in which case `data` is empty. Data beyond this watermark is incomplete; for stable results, set `ending_at` to this value or earlier. Data is typically refreshed every 4 hours but not final until about 30 days after the usage date (late-arriving events, reconciliation adjustments).", "constraints": { "format": "date-time" } }, { "name": "has_more", "type": "boolean", "required": true, "description": "Whether another page is available. When true, pass `next_page` as the `page` parameter to fetch it." }, { "name": "next_page", "type": "string or null", "required": true, "description": "Opaque cursor for the next page, or null when `has_more` is false. Pass it as the `page` parameter, keeping the other parameters unchanged. A cursor can expire after the underlying data refreshes; the request then returns HTTP 410 and pagination must restart from the first page." }, { "name": "organization_id", "type": "string", "required": true, "description": "ID of the Organization." } ], "example": { "data": [ { "actor": { "deleted": true, "email": "jane@example.com", "name": "Jane Smith", "type": "user_actor", "user_id": "user_01AbCdEfGhIjKlMnOpQrSt" }, "cache_creation": { "ephemeral_1h_input_tokens": 0, "ephemeral_5m_input_tokens": 0 }, "cache_read_input_tokens": 3200000, "claude_tag_category": "dm", "claude_tag_user_id": "U0123ABCDEF", "context_window": "0-200k", "ending_at": "2019-12-27T18:11:19.117Z", "inference_geo": "global", "model": "claude-opus-5", "output_tokens": 891000, "product": "chat", "rbac_group_id": "rbac_group_012rppKaSVsmTo6NqRDXQXNF", "requests": 128, "server_tool_use": { "web_search_requests": 10 }, "slack_channel_id": "C0123ABCDEF", "speed": "fast", "starting_at": "2019-12-27T18:11:19.117Z", "total_tokens": 5377000, "uncached_input_tokens": 1284500 } ], "data_refreshed_at": "2019-12-27T18:11:19.117Z", "has_more": true, "next_page": "next_page", "organization_id": "org_013FP9SaFPBg7Kw7fetjn6cF" }, "status": [ "DOCUMENTED" ], "sources": [ { "url": "https://platform.claude.com/docs/en/api/beta/organization/analytics/usage/list_by_user", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/anthropic-platform-objects.json" }, { "provider": "anthropic", "api_family": "admin", "name": "UserActivity", "official_type_name": "BetaUserActivity", "description": "Response for GET /v1/organizations/analytics/users.", "fields": [ { "name": "data", "type": "array of object", "required": true, "description": "" }, { "name": "data[].chat_metrics", "type": "object", "required": true, "description": "Claude.ai activity metrics for a single user on a given day." }, { "name": "data[].chat_metrics.connectors_used_count", "type": "number", "required": true, "description": "Number of MCP connector invocations." }, { "name": "data[].chat_metrics.distinct_artifacts_created_count", "type": "number", "required": true, "description": "Number of distinct artifacts created. Exact in date-range mode: a creation belongs to exactly one day, so the per-day counts never overlap and their sum over the window is the exact count of distinct creations in it." }, { "name": "data[].chat_metrics.distinct_connectors_used_count", "type": "number or null", "required": true, "description": "Distinct claude.ai connectors this user used. Excludes calls whose connector could not be identified and all calls from organizations with zero data retention. Approximate (HLL, typical error <2%) in date-range mode. Null on aggregated rows where a distinct count cannot be computed." }, { "name": "data[].chat_metrics.distinct_conversation_count", "type": "number or null", "required": true, "description": "Number of distinct conversations the user participated in. Approximate (HLL, typical error <2%) in date-range mode. Null on aggregated rows where a distinct count cannot be computed." }, { "name": "data[].chat_metrics.distinct_files_uploaded_count", "type": "number or null", "required": true, "description": "Number of distinct files uploaded. Approximate (HLL, typical error <2%) in date-range mode. Null on aggregated rows where a distinct count cannot be computed." }, { "name": "data[].chat_metrics.distinct_projects_created_count", "type": "number", "required": true, "description": "Number of distinct projects created. Exact in date-range mode: a creation belongs to exactly one day, so the per-day counts never overlap and their sum over the window is the exact count of distinct creations in it." }, { "name": "data[].chat_metrics.distinct_projects_used_count", "type": "number or null", "required": true, "description": "Number of distinct projects used. Approximate (HLL, typical error <2%) in date-range mode. Null on aggregated rows where a distinct count cannot be computed." }, { "name": "data[].chat_metrics.distinct_shared_artifacts_viewed_count", "type": "number or null", "required": true, "description": "Number of distinct shared artifacts the user viewed. Approximate (HLL, typical error <2%) in date-range mode. Null on aggregated rows where a distinct count cannot be computed." }, { "name": "data[].chat_metrics.distinct_skills_used_count", "type": "number or null", "required": true, "description": "Number of distinct skills used. Approximate (HLL, typical error <2%) in date-range mode. Null on aggregated rows where a distinct count cannot be computed." }, { "name": "data[].chat_metrics.message_count", "type": "number", "required": true, "description": "Number of messages sent" }, { "name": "data[].chat_metrics.shared_conversations_viewed_count", "type": "number", "required": true, "description": "Number of times the user opened a shared conversation in a project" }, { "name": "data[].chat_metrics.thinking_message_count", "type": "number", "required": true, "description": "Number of messages that used extended thinking" }, { "name": "data[].claude_code_metrics", "type": "object", "required": true, "description": "Claude Code activity metrics for a single user on a given day." }, { "name": "data[].claude_code_metrics.core_metrics", "type": "object", "required": true, "description": "Core Claude Code activity metrics for a single user on a given day." }, { "name": "data[].claude_code_metrics.tool_actions", "type": "object", "required": true, "description": "Per-tool accepted/rejected counts for Claude Code file modification tools." }, { "name": "data[].cowork_metrics", "type": "object", "required": true, "description": "Cowork activity metrics for a single user on a given day." }, { "name": "data[].cowork_metrics.action_count", "type": "number", "required": true, "description": "Number of tool actions completed in Cowork sessions" }, { "name": "data[].cowork_metrics.artifacts_created_count", "type": "number", "required": true, "description": "Number of artifacts created in Cowork sessions: an artifact counts once, on the day a session first saves it. Counted from 2026-08-17; 0 on earlier days. Exact in date-range mode: a creation belongs to exactly one day, so the per-day counts never overlap and their sum over the window is the exact count of distinct creations in it." }, { "name": "data[].cowork_metrics.connectors_used_count", "type": "number", "required": true, "description": "Total number of connector invocations in Cowork sessions" }, { "name": "data[].cowork_metrics.dispatch_turn_count", "type": "number", "required": true, "description": "Number of Dispatch (background agent) turns completed" }, { "name": "data[].cowork_metrics.distinct_connectors_used_count", "type": "number or null", "required": true, "description": "Number of distinct connectors used in Cowork sessions. Approximate (HLL, typical error <2%) in date-range mode. Null on aggregated rows where a distinct count cannot be computed." }, { "name": "data[].cowork_metrics.distinct_session_count", "type": "number or null", "required": true, "description": "Number of distinct Cowork sessions. Approximate (HLL, typical error <2%) in date-range mode. Null on aggregated rows where a distinct count cannot be computed." }, { "name": "data[].cowork_metrics.distinct_skills_used_count", "type": "number or null", "required": true, "description": "Number of distinct skills used in Cowork sessions. Approximate (HLL, typical error <2%) in date-range mode. Null on aggregated rows where a distinct count cannot be computed." }, { "name": "data[].cowork_metrics.message_count", "type": "number", "required": true, "description": "Number of messages sent in Cowork sessions" }, { "name": "data[].cowork_metrics.skills_used_count", "type": "number", "required": true, "description": "Total number of skill invocations in Cowork sessions" }, { "name": "data[].cowork_metrics.distinct_plugins_used_count", "type": "number or null", "required": false, "description": "Number of distinct plugins used in Cowork sessions. Null while Cowork plugin-use metrics are not enabled for this organization. Approximate (HLL, typical error <2%) in date-range mode. Null on aggregated rows where a distinct count cannot be computed." }, { "name": "data[].cowork_metrics.edit_tool_count", "type": "number or null", "required": false, "description": "Number of successful Edit tool calls in Cowork sessions. Null while the file-edit metrics are not enabled for this organization." }, { "name": "data[].cowork_metrics.file_edit_count", "type": "number or null", "required": false, "description": "Number of successful file-edit tool calls (Edit, MultiEdit, Write, NotebookEdit) in Cowork sessions. Null, never 0, while the file-edit metrics are not enabled for this organization." }, { "name": "data[].cowork_metrics.multi_edit_tool_count", "type": "number or null", "required": false, "description": "Number of successful MultiEdit tool calls in Cowork sessions. Null while the file-edit metrics are not enabled for this organization." }, { "name": "data[].cowork_metrics.notebook_edit_tool_count", "type": "number or null", "required": false, "description": "Number of successful NotebookEdit tool calls in Cowork sessions. Null while the file-edit metrics are not enabled for this organization." }, { "name": "data[].cowork_metrics.plugins_used_count", "type": "number or null", "required": false, "description": "Total number of plugin invocations in Cowork sessions. Null while Cowork plugin-use metrics are not enabled for this organization." }, { "name": "data[].cowork_metrics.sessions_with_file_edits_count", "type": "number or null", "required": false, "description": "Number of distinct Cowork sessions with at least one successful file-edit tool call. Null while the file-edit metrics are not enabled for this organization. Approximate (HLL, typical error <2%) in date-range mode. Null on aggregated rows where a distinct count cannot be computed." }, { "name": "data[].cowork_metrics.write_tool_count", "type": "number or null", "required": false, "description": "Number of successful Write tool calls in Cowork sessions. Null while the file-edit metrics are not enabled for this organization." }, { "name": "data[].design_metrics", "type": "object", "required": true, "description": "Claude Design activity metrics for a single user on a given day." }, { "name": "data[].design_metrics.distinct_projects_created_count", "type": "number", "required": true, "description": "Number of distinct Claude Design projects created. Exact in date-range mode: a creation belongs to exactly one day, so the per-day counts never overlap and their sum over the window is the exact count of distinct creations in it." }, { "name": "data[].design_metrics.distinct_projects_used_count", "type": "number or null", "required": true, "description": "Number of distinct Claude Design projects the user worked in. Approximate (HLL, typical error <2%) in date-range mode. Null on aggregated rows where a distinct count cannot be computed." }, { "name": "data[].design_metrics.distinct_session_count", "type": "number or null", "required": true, "description": "Number of distinct Claude Design sessions. Approximate (HLL, typical error <2%) in date-range mode. Null on aggregated rows where a distinct count cannot be computed." }, { "name": "data[].design_metrics.message_count", "type": "number", "required": true, "description": "Number of messages sent in Claude Design sessions" }, { "name": "data[].office_metrics", "type": "object", "required": true, "description": "Office Agent activity metrics for a single user on a given day, broken out by Office product." }, { "name": "data[].office_metrics.excel", "type": "BetaOfficeProductMetrics", "required": true, "description": "Office Agent activity metrics for a single user on a given day within one Office product." }, { "name": "data[].office_metrics.outlook", "type": "BetaOfficeProductMetrics", "required": true, "description": "Office Agent activity metrics for a single user on a given day within one Office product." }, { "name": "data[].office_metrics.powerpoint", "type": "BetaOfficeProductMetrics", "required": true, "description": "Office Agent activity metrics for a single user on a given day within one Office product." }, { "name": "data[].office_metrics.word", "type": "BetaOfficeProductMetrics", "required": true, "description": "Office Agent activity metrics for a single user on a given day within one Office product." }, { "name": "data[].science_metrics", "type": "object", "required": true, "description": "Claude Science activity metrics for a single user on a given day." }, { "name": "data[].science_metrics.delegation_count", "type": "number", "required": true, "description": "Number of delegations (handoffs to a specialized agent) in Claude Science sessions" }, { "name": "data[].science_metrics.distinct_session_count", "type": "number or null", "required": true, "description": "Number of distinct Claude Science sessions. Approximate (HLL, typical error <2%) in date-range mode. Null on aggregated rows where a distinct count cannot be computed." }, { "name": "data[].science_metrics.message_count", "type": "number", "required": true, "description": "Number of messages sent in Claude Science sessions" }, { "name": "data[].science_metrics.remote_compute_job_count", "type": "number", "required": true, "description": "Number of remote compute jobs launched from Claude Science sessions" }, { "name": "data[].science_metrics.skills_used_count", "type": "number", "required": true, "description": "Total number of skill invocations in Claude Science sessions" }, { "name": "data[].web_search_count", "type": "number", "required": true, "description": "Number of web searches performed" }, { "name": "data[].distinct_user_count", "type": "number or null", "required": false, "description": "Number of distinct active users represented by this row. Only set for grouped rollups (`group_by[]`); null for per-user rows. In date-range mode, recomputed as an exact distinct count of the group's active members over the requested window, never a sum of per-day values." }, { "name": "data[].last_activity_date", "type": "string or null", "required": false, "description": "Most recent UTC day (YYYY-MM-DD) on which the user had any counted activity, within the requested window: equal to the requested `date` in single-day mode, and to the latest active day from `starting_date` (inclusive) to `ending_date` (exclusive) in date-range rollup mode — never a day earlier than the window start. On filtered requests (`filter[]`) only days matching the filter count: with `filter[]=rbac_group_id:{id}` it is the last day the user was active while a member of that group, consistent with the row's other metrics. On grouped (`group_by[]`) rows it is the latest day any member of the group was active (the requested `date` in single-day mode). Omitted from the response while last-activity reporting is not enabled for this organization.", "constraints": { "format": "date" } }, { "name": "data[].rbac_group_id", "type": "string or null", "required": false, "description": "Tagged RBAC group identifier (`rbac_group_...`), matching the spend-limits API spelling. Present only when the request grouped by `rbac_group_id`." }, { "name": "data[].rbac_group_name", "type": "string or null", "required": false, "description": "Resolved RBAC group display name, alongside `rbac_group_id` when name resolution is available. Null if the group has been deleted or its name could not be resolved; `rbac_group_id` remains the stable key." }, { "name": "data[].user", "type": "BetaAnalyticsUser or null", "required": false, "description": "A user in the organization, identified by tagged id and email address." }, { "name": "data[].user.type", "type": "\"user\"", "required": true, "description": "Object type. Always `user`.", "default": "user" }, { "name": "data[].user.id", "type": "string", "required": true, "description": "Tagged user identifier (e.g. `user_...`)" }, { "name": "data[].user.email_address", "type": "string", "required": true, "description": "Email address of the user" }, { "name": "next_page", "type": "string or null", "required": true, "description": "Opaque cursor for the next page, or null if no more results" } ], "example": { "data": [ { "chat_metrics": { "connectors_used_count": 0, "distinct_artifacts_created_count": 0, "distinct_connectors_used_count": 0, "distinct_conversation_count": 0, "distinct_files_uploaded_count": 0, "distinct_projects_created_count": 0, "distinct_projects_used_count": 0, "distinct_shared_artifacts_viewed_count": 0, "distinct_skills_used_count": 0, "message_count": 0, "shared_conversations_viewed_count": 0, "thinking_message_count": 0 }, "claude_code_metrics": { "core_metrics": { "artifacts_created_count": 0, "commit_count": 0, "distinct_session_count": 0, "lines_of_code": { "added_count": 0, "removed_count": 0 }, "pull_request_count": 0 }, "tool_actions": { "edit_tool": { "accepted_count": 0, "rejected_count": 0 }, "multi_edit_tool": { "accepted_count": 0, "rejected_count": 0 }, "notebook_edit_tool": { "accepted_count": 0, "rejected_count": 0 }, "write_tool": { "accepted_count": 0, "rejected_count": 0 } } }, "cowork_metrics": { "action_count": 0, "artifacts_created_count": 0, "connectors_used_count": 0, "dispatch_turn_count": 0, "distinct_connectors_used_count": 0, "distinct_session_count": 0, "distinct_skills_used_count": 0, "message_count": 0, "skills_used_count": 0, "distinct_plugins_used_count": 0, "edit_tool_count": 0, "file_edit_count": 0, "multi_edit_tool_count": 0, "notebook_edit_tool_count": 0, "plugins_used_count": 0, "sessions_with_file_edits_count": 0, "write_tool_count": 0 }, "design_metrics": { "distinct_projects_created_count": 0, "distinct_projects_used_count": 0, "distinct_session_count": 0, "message_count": 0 }, "office_metrics": { "excel": { "connectors_used_count": 0, "distinct_connectors_used_count": 0, "distinct_session_count": 0, "distinct_skills_used_count": 0, "message_count": 0, "skills_used_count": 0 }, "outlook": { "connectors_used_count": 0, "distinct_connectors_used_count": 0, "distinct_session_count": 0, "distinct_skills_used_count": 0, "message_count": 0, "skills_used_count": 0 }, "powerpoint": { "connectors_used_count": 0, "distinct_connectors_used_count": 0, "distinct_session_count": 0, "distinct_skills_used_count": 0, "message_count": 0, "skills_used_count": 0 }, "word": { "connectors_used_count": 0, "distinct_connectors_used_count": 0, "distinct_session_count": 0, "distinct_skills_used_count": 0, "message_count": 0, "skills_used_count": 0 } }, "science_metrics": { "delegation_count": 0, "distinct_session_count": 0, "message_count": 0, "remote_compute_job_count": 0, "skills_used_count": 0 }, "web_search_count": 0, "distinct_user_count": 0, "last_activity_date": "2019-12-27", "rbac_group_id": "rbac_group_id", "rbac_group_name": "rbac_group_name", "user": { "id": "id", "email_address": "email_address", "type": "user" } } ], "next_page": "next_page" }, "status": [ "DOCUMENTED" ], "sources": [ { "url": "https://platform.claude.com/docs/en/api/beta/organization/analytics/users/list", "retrieved_at": "2026-09-18" }, { "url": "https://platform.claude.com/docs/en/api/beta/organization/analytics/users", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/anthropic-platform-objects.json" }, { "provider": "anthropic", "api_family": "admin", "name": "APIKey", "official_type_name": "BetaAPIKey", "description": "Response object of GET /v1/organizations/api_keys/{api_key_id}", "fields": [ { "name": "type", "type": "\"api_key\"", "required": true, "description": "Object type. For API Keys, this is always `\"api_key\"`.", "default": "api_key" }, { "name": "id", "type": "string", "required": true, "description": "ID of the API key." }, { "name": "created_at", "type": "string", "required": true, "description": "RFC 3339 datetime string indicating when the API Key was created.", "constraints": { "format": "date-time" } }, { "name": "created_by", "type": "BetaAPIKeyCreatedBy or null", "required": true, "description": "The ID and type of the actor that created the API key, or `null` when the creator is not recorded (legacy, workload-identity-federated, or system-created keys)." }, { "name": "created_by.type", "type": "\"service_account\" or \"user\"", "required": true, "description": "Type of the actor that created the object.", "enum": [ "service_account", "user" ] }, { "name": "created_by.id", "type": "string", "required": true, "description": "ID of the actor that created the object." }, { "name": "expires_at", "type": "string or null", "required": true, "description": "RFC 3339 datetime string indicating when the API Key expires, or `null` if it never expires.", "constraints": { "format": "date-time" } }, { "name": "name", "type": "string", "required": true, "description": "Name of the API key." }, { "name": "partial_key_hint", "type": "string or null", "required": true, "description": "Partially redacted hint for the API key." }, { "name": "principal", "type": "BetaAPIKeyUserActor or BetaAPIKeyServiceAccountActor or null", "required": true, "description": "The principal the API key acts as (a User or a Service Account), or `null` if the API key is not bound to a principal." }, { "name": "principal.type", "type": "\"user_actor\"", "required": true, "description": "Principal type. Always `\"user_actor\"` for a User.", "default": "user_actor" }, { "name": "principal.user_id", "type": "string", "required": true, "description": "ID of the User the API key acts as." }, { "name": "principal.type", "type": "\"service_account_actor\"", "required": true, "description": "Principal type. Always `\"service_account_actor\"` for a Service Account.", "default": "service_account_actor" }, { "name": "principal.service_account_id", "type": "string", "required": true, "description": "ID of the Service Account the API key acts as." }, { "name": "scope", "type": "BetaAPIKeyOrganizationScope or BetaAPIKeyWorkspaceScope", "required": true, "description": "Where the API key belongs: its Workspace (`{\"type\": \"workspace\", \"workspace_id\": \"wrkspc_...\"}`, with the Workspace's real ID even when it is the organization's default Workspace), or the organization (`{\"type\": \"organization\"}`) for a principal-bound API key that has no Workspace." }, { "name": "scope.type", "type": "\"organization\"", "required": true, "description": "Scope type. Always `\"organization\"`: the API key has no Workspace. Only a principal-bound API key can have this scope.", "default": "organization" }, { "name": "scope.type", "type": "\"workspace\"", "required": true, "description": "Scope type. Always `\"workspace\"`: the API key belongs to one Workspace.", "default": "workspace" }, { "name": "scope.workspace_id", "type": "string", "required": true, "description": "ID of the Workspace the API key belongs to. Unlike the deprecated top-level `workspace_id`, this is the Workspace's real ID even for the organization's default Workspace." }, { "name": "status", "type": "\"active\" or \"archived\" or \"expired\" or \"inactive\"", "required": true, "description": "Status of the API key.", "enum": [ "active", "archived", "expired", "inactive" ] }, { "name": "workspace_id", "type": "string or null", "required": true, "description": "**Deprecated**: Use `scope` instead. `workspace_id` is `null` both for an API key in the default Workspace and for a principal-bound API key that has no Workspace. Deprecated: use `scope` instead. ID of the Workspace associated with the API key, or `null` if the API key belongs to the default Workspace. Also `null` for a principal-bound API key that has no Workspace; `scope` tells the two apart." } ], "example": { "id": "apikey_01Rj2N8SVvo6BePZj99NhmiT", "created_at": "2024-10-30T23:58:27.427722Z", "created_by": { "id": "user_01WCz1FkmYMm4gnmykNKUu3Q", "type": "user" }, "expires_at": "2024-10-30T23:58:27.427722Z", "name": "Developer Key", "partial_key_hint": "sk-ant-api03-R2D...igAA", "principal": { "type": "user_actor", "user_id": "user_01WCz1FkmYMm4gnmykNKUu3Q" }, "scope": { "type": "workspace", "workspace_id": "wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ" }, "status": "active", "type": "api_key", "workspace_id": "wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ" }, "status": [ "DOCUMENTED" ], "sources": [ { "url": "https://platform.claude.com/docs/en/api/beta/organization/api_keys/retrieve", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/anthropic-platform-objects.json" }, { "provider": "anthropic", "api_family": "admin", "name": "ComplianceSettings", "official_type_name": "BetaComplianceSettings", "description": "Response object of GET /v1/organizations/compliance_settings", "fields": [ { "name": "type", "type": "\"compliance_settings\"", "required": true, "description": "", "default": "compliance_settings" }, { "name": "state", "type": "BetaComplianceSettingsState", "required": true, "description": "Whether the Compliance API is enabled for this organization." }, { "name": "state.type", "type": "\"enabled\"", "required": true, "description": "", "default": "enabled" }, { "name": "state.type", "type": "\"disabled\"", "required": true, "description": "", "default": "disabled" } ], "example": { "state": { "type": "enabled" }, "type": "compliance_settings" }, "status": [ "DOCUMENTED" ], "sources": [ { "url": "https://platform.claude.com/docs/en/api/beta/organization/compliance_settings/retrieve", "retrieved_at": "2026-09-18" }, { "url": "https://platform.claude.com/docs/en/api/beta/organization/compliance_settings", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/anthropic-platform-objects.json" }, { "provider": "anthropic", "api_family": "admin", "name": "CostReport", "official_type_name": "BetaCostReport", "description": "Response object of GET /v1/organizations/cost_report", "fields": [ { "name": "data", "type": "array of object", "required": true, "description": "List of time buckets for this page, oldest first: one per `bucket_width` interval, including intervals with no costs (their `results` list is empty). A page holds at most `limit` buckets." }, { "name": "data[].ending_at", "type": "string", "required": true, "description": "End of the time bucket (exclusive) in RFC 3339 format.", "constraints": { "format": "date-time" } }, { "name": "data[].results", "type": "array of object", "required": true, "description": "List of cost items for this time bucket. There may be multiple items if one or more `group_by[]` parameters are specified." }, { "name": "data[].results[].amount", "type": "string", "required": true, "description": "Cost amount in lowest currency units (e.g. cents) as a decimal string. For example, `\"123.45\"` in `\"USD\"` represents `$1.23`." }, { "name": "data[].results[].context_window", "type": "\"0-200k\" or \"200k-1M\" or null", "required": true, "description": "Input context window used. `null` if not grouping by description or for non-token costs.", "enum": [ "0-200k", "200k-1M" ] }, { "name": "data[].results[].cost_type", "type": "\"code_execution\" or \"session_usage\" or \"tokens\" or \"web_search\" or null", "required": true, "description": "Type of cost. `null` if not grouping by description.", "enum": [ "code_execution", "session_usage", "tokens", "web_search" ] }, { "name": "data[].results[].currency", "type": "string", "required": true, "description": "Currency code for the cost amount. Currently always `\"USD\"`." }, { "name": "data[].results[].description", "type": "string or null", "required": true, "description": "Description of the cost item. `null` if not grouping by description." }, { "name": "data[].results[].inference_geo", "type": "\"global\" or \"not_available\" or \"us\" or null", "required": true, "description": "Inference geo used matching requests' `inference_geo` parameter if set, otherwise the workspace's `default_inference_geo`. For models that do not support specifying `inference_geo` the value is `\"not_available\"`. Always `null` if not grouping by inference geo.", "enum": [ "global", "not_available", "us" ] }, { "name": "data[].results[].model", "type": "string or null", "required": true, "description": "Model name used. `null` if not grouping by description or for non-token costs." }, { "name": "data[].results[].service_tier", "type": "\"batch\" or \"standard\" or null", "required": true, "description": "Service tier used. `null` if not grouping by description or for non-token costs.", "enum": [ "batch", "standard" ] }, { "name": "data[].results[].token_type", "type": "\"cache_creation.ephemeral_1h_input_tokens\" or \"cache_creation.ephemeral_5m_input_tokens\" or \"cache_read_input_tokens\" or 2 more or null", "required": true, "description": "Type of token. `null` if not grouping by description or for non-token costs.", "enum": [ "cache_creation.ephemeral_1h_input_tokens", "cache_creation.ephemeral_5m_input_tokens", "cache_read_input_tokens", "output_tokens", "uncached_input_tokens" ] }, { "name": "data[].results[].workspace_id", "type": "string or null", "required": true, "description": "ID of the Workspace this cost is associated with. `null` if not grouping by workspace or for the default workspace." }, { "name": "data[].starting_at", "type": "string", "required": true, "description": "Start of the time bucket (inclusive) in RFC 3339 format.", "constraints": { "format": "date-time" } }, { "name": "has_more", "type": "boolean", "required": true, "description": "Indicates if there are more results." }, { "name": "next_page", "type": "string or null", "required": true, "description": "Opaque cursor for the next page, or `null` when `has_more` is false. Pass it as the `page` parameter in the next request." } ], "example": { "data": [ { "ending_at": "2025-08-02T00:00:00Z", "results": [ { "amount": "123.78912", "context_window": "0-200k", "cost_type": "tokens", "currency": "USD", "description": "Claude Opus 5 Usage - Input Tokens", "inference_geo": "global", "model": "claude-opus-5", "service_tier": "standard", "token_type": "uncached_input_tokens", "workspace_id": "wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ" } ], "starting_at": "2025-08-01T00:00:00Z" } ], "has_more": true, "next_page": "page_MjAyNS0wNS0xNFQwMDowMDowMFo=" }, "status": [ "DOCUMENTED" ], "sources": [ { "url": "https://platform.claude.com/docs/en/api/beta/organization/cost_report/retrieve", "retrieved_at": "2026-09-18" }, { "url": "https://platform.claude.com/docs/en/api/beta/organization/cost_report", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/anthropic-platform-objects.json" }, { "provider": "anthropic", "api_family": "admin", "name": "ExternalKey", "official_type_name": "BetaExternalKey", "description": "CMEK external key config belonging to the caller's organization. Configs are organization-scoped. Workspaces attach to a config; once any workspace references it, the provider fields become effectively immutable (existing encrypted data needs the config for decrypt).", "fields": [ { "name": "type", "type": "\"external_key\"", "required": true, "description": "", "default": "external_key" }, { "name": "id", "type": "string", "required": true, "description": "Identifier of the external key config. A tagged ID prefixed `ekey_`, or — for organizations on the Claude Platform on AWS — the AWS KMS key ARN." }, { "name": "attachment", "type": "BetaExternalKeyAttachedAttachment or BetaExternalKeyUnattachedAttachment", "required": true, "description": "Whether any workspace uses this config to encrypt its data — counting live and archived workspaces (an archived workspace's data remains encrypted under the config), excluding deleted ones. Only an attached config is used by the encryption path; an `unattached` config is inert and can be deleted." }, { "name": "attachment.type", "type": "\"attached\"", "required": true, "description": "", "default": "attached" }, { "name": "attachment.type", "type": "\"unattached\"", "required": true, "description": "", "default": "unattached" }, { "name": "created_at", "type": "string", "required": true, "description": "", "constraints": { "format": "date-time" } }, { "name": "display_name", "type": "string or null", "required": true, "description": "Human-friendly display name. Null if none was set." }, { "name": "geo", "type": "string", "required": true, "description": "Data residency geo. Selects which regional validator handles this key's encrypt/decrypt roundtrips." }, { "name": "provider_config", "type": "BetaAWSExternalKeyConfig or BetaGCPExternalKeyConfig or BetaAzureExternalKeyConfig", "required": true, "description": "KMS provider identity and auth coordinates." }, { "name": "provider_config.type", "type": "\"aws\"", "required": true, "description": "" }, { "name": "provider_config.kms_arn", "type": "string", "required": true, "description": "Full ARN of the AWS KMS key. On Claude Platform on AWS the key must be a single-Region key in your organization's own AWS account; cross-account keys, multi-Region keys, and alias ARNs are rejected.", "constraints": { "maxLength": "2048" } }, { "name": "provider_config.region", "type": "string or null", "required": false, "description": "AWS region. Derived from `kms_arn` if omitted." }, { "name": "provider_config.role_arn", "type": "string or null", "required": false, "description": "**Deprecated** IAM role ARN. Deprecated — Anthropic reaches the KMS key through its own intermediate role (or, on Claude Platform on AWS, with credentials AWS issues for the Workspace); this field is ignored." }, { "name": "provider_config.type", "type": "\"gcp\"", "required": true, "description": "" }, { "name": "provider_config.key_name", "type": "string", "required": true, "description": "Full resource name of the Cloud KMS key." }, { "name": "provider_config.type", "type": "\"azure\"", "required": true, "description": "" }, { "name": "provider_config.key_name", "type": "string", "required": true, "description": "Name of the key within the vault." }, { "name": "provider_config.tenant_id", "type": "string", "required": true, "description": "Azure AD tenant ID." }, { "name": "provider_config.vault_uri", "type": "string", "required": true, "description": "Key Vault data-plane URI — `https://{vault-name}.vault.azure.net` or `https://{hsm-name}.managedhsm.azure.net`." }, { "name": "provider_config.client_id", "type": "string or null", "required": false, "description": "Azure AD application (client) ID. Omit to use Anthropic's multitenant app. Provide only if using a single-tenant app registration in the customer's directory." }, { "name": "updated_at", "type": "string", "required": true, "description": "", "constraints": { "format": "date-time" } } ], "example": { "id": "ekey_01SDCCSbTxrXDpWc1phhtcfK", "attachment": { "type": "attached" }, "created_at": "2024-10-30T23:58:27.427722Z", "display_name": "prod-us-key", "geo": "us", "provider_config": { "kms_arn": "arn:aws:kms:us-east-1:111122223333:key/abcd1234-5678-90ab-cdef-000011112222", "type": "aws", "region": "us-east-1", "role_arn": "arn:aws:iam::111122223333:role/anthropic-cmek" }, "type": "external_key", "updated_at": "2024-10-30T23:58:27.427722Z" }, "status": [ "DOCUMENTED" ], "sources": [ { "url": "https://platform.claude.com/docs/en/api/beta/organization/external_keys/create", "retrieved_at": "2026-09-18" }, { "url": "https://platform.claude.com/docs/en/api/beta/organization/external_keys", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/anthropic-platform-objects.json" }, { "provider": "anthropic", "api_family": "admin", "name": "FederationIssuer", "official_type_name": "BetaFederationIssuer", "description": "Registered external OIDC identity provider. Records an external IdP the organization trusts for the RFC 7523 jwt-bearer grant. The `issuer_url` must match the JWT `iss` claim exactly.", "fields": [ { "name": "type", "type": "\"federation_issuer\"", "required": true, "description": "", "default": "federation_issuer" }, { "name": "id", "type": "string", "required": true, "description": "Tagged ID of the federation issuer." }, { "name": "archived_at", "type": "string or null", "required": true, "description": "If set, all rules referencing this issuer reject token exchange.", "constraints": { "format": "date-time" } }, { "name": "archived_by_actor_id", "type": "string or null", "required": true, "description": "Tagged ID (`user_`/`svac_`) of the actor that archived this issuer." }, { "name": "check_jti", "type": "boolean", "required": true, "description": "Whether the jwt-bearer exchange enforces JTI single-use (replay protection) for tokens from this issuer. Applies only to assertions carrying a `jti` claim; tokens without one are accepted without single-use enforcement." }, { "name": "created_at", "type": "string", "required": true, "description": "When this issuer was created.", "constraints": { "format": "date-time" } }, { "name": "created_by_actor_id", "type": "string or null", "required": true, "description": "Tagged ID (`user_`/`svac_`) of the actor that created this issuer." }, { "name": "issuer_url", "type": "string", "required": true, "description": "The `iss` claim value. Incoming JWTs must match exactly." }, { "name": "jwks", "type": "BetaJWKSDiscovery or BetaJWKSExplicitURL or BetaJWKSInline", "required": true, "description": "How signing keys are obtained for signature verification." }, { "name": "jwks.type", "type": "\"discovery\"", "required": true, "description": "" }, { "name": "jwks.ca_cert_pem", "type": "string or null", "required": false, "description": "Optional custom CA (PEM) for TLS verification of the JWKS fetch.", "constraints": { "maxLength": "8192" } }, { "name": "jwks.discovery_base", "type": "string or null", "required": false, "description": "Set when the discovery URL differs from `issuer_url`." }, { "name": "jwks.type", "type": "\"explicit_url\"", "required": true, "description": "" }, { "name": "jwks.url", "type": "string", "required": true, "description": "JWKS endpoint.", "constraints": { "minLength": "1" } }, { "name": "jwks.ca_cert_pem", "type": "string or null", "required": false, "description": "Optional custom CA (PEM) for TLS verification of the JWKS fetch.", "constraints": { "maxLength": "8192" } }, { "name": "jwks.type", "type": "\"inline\"", "required": true, "description": "" }, { "name": "jwks.keys", "type": "array of map[unknown]", "required": true, "description": "Inline JWK objects.", "constraints": { "minItems": "1" } }, { "name": "jwks_polling_disabled_at", "type": "string or null", "required": true, "description": "If set, Anthropic's JWKS poller has paused polling for this issuer after repeated fetch failures. Re-enable by sending `jwks_polling_disabled: false` via the issuer update endpoint (POST) once the upstream JWKS endpoint is fixed. An OAuth caller cannot send this when the issuer backs a rule with any scope other than `workspace:developer` or `workspace:inference`; use a Console session.", "constraints": { "format": "date-time" } }, { "name": "max_jwt_lifetime_seconds", "type": "number", "required": true, "description": "Maximum allowed iat→exp spread for assertions from this issuer (1-176400 seconds, i.e. up to 49h). Assertions must carry both `iat` and `exp`; a missing `iat` is rejected." }, { "name": "name", "type": "string", "required": true, "description": "Admin-chosen slug identifier." }, { "name": "poll_status", "type": "BetaFederationIssuerPollStatus or null", "required": true, "description": "Status of automatic JWKS polling for a federation issuer. Anthropic periodically fetches the issuer's signing keys in the background. These fields summarize the most recent fetches so the health of the JWKS endpoint can be monitored." }, { "name": "poll_status.consecutive_failures", "type": "number", "required": true, "description": "Consecutive fetch failures since the last success." }, { "name": "poll_status.last_fetched_at", "type": "string or null", "required": true, "description": "When the last successful fetch completed.", "constraints": { "format": "date-time" } }, { "name": "poll_status.next_poll_at", "type": "string or null", "required": true, "description": "When the next fetch is scheduled. Null if paused.", "constraints": { "format": "date-time" } }, { "name": "updated_at", "type": "string", "required": true, "description": "When this issuer was last updated.", "constraints": { "format": "date-time" } }, { "name": "updated_by_actor_id", "type": "string or null", "required": true, "description": "Tagged ID (`user_`/`svac_`) of the actor that last updated this issuer." } ], "example": { "id": "fdis_01SDCCSbTxrXDpWc1phhtcfK", "archived_at": "2019-12-27T18:11:19.117Z", "archived_by_actor_id": "archived_by_actor_id", "check_jti": true, "created_at": "2024-10-30T23:58:27.427722Z", "created_by_actor_id": "created_by_actor_id", "issuer_url": "https://token.actions.githubusercontent.com", "jwks": { "type": "discovery", "ca_cert_pem": "ca_cert_pem", "discovery_base": "discovery_base" }, "jwks_polling_disabled_at": "2019-12-27T18:11:19.117Z", "max_jwt_lifetime_seconds": 0, "name": "github-actions", "poll_status": { "consecutive_failures": 0, "last_fetched_at": "2019-12-27T18:11:19.117Z", "next_poll_at": "2019-12-27T18:11:19.117Z" }, "type": "federation_issuer", "updated_at": "2024-10-30T23:58:27.427722Z", "updated_by_actor_id": "updated_by_actor_id" }, "status": [ "DOCUMENTED" ], "sources": [ { "url": "https://platform.claude.com/docs/en/api/beta/organization/federation/issuers/create", "retrieved_at": "2026-09-18" }, { "url": "https://platform.claude.com/docs/en/api/beta/organization/federation/issuers", "retrieved_at": "2026-09-18" }, { "url": "https://platform.claude.com/docs/en/api/beta/organization/federation", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/anthropic-platform-objects.json" }, { "provider": "anthropic", "api_family": "admin", "name": "FederationRule", "official_type_name": "BetaFederationRule", "description": "Authorization rule binding an external OIDC identity to Anthropic. Evaluates the match conditions and mints an OAuth access token for the resolved target, scoped to a single workspace where the rule is enabled (chosen by the caller at exchange time when the rule is enabled for more than one). For rules enabled via `workspace_ids` or `applies_to_all_workspaces`, the target service account must be a member of that workspace (it is implicitly a member of the default workspace); rules carrying only the legacy `workspace_id` binding do not enforce this.", "fields": [ { "name": "type", "type": "\"federation_rule\"", "required": true, "description": "", "default": "federation_rule" }, { "name": "id", "type": "string", "required": true, "description": "Tagged ID of the federation rule." }, { "name": "applies_to_all_workspaces", "type": "boolean", "required": true, "description": "When true, this rule is enabled for every workspace in the org (including ones created after the rule). `workspace_ids` is ignored at exchange time." }, { "name": "archived_at", "type": "string or null", "required": true, "description": "If set, this rule is archived and rejects token exchange.", "constraints": { "format": "date-time" } }, { "name": "archived_by_actor_id", "type": "string or null", "required": true, "description": "Tagged ID (`user_`/`svac_`) of the actor that archived this rule." }, { "name": "attributes", "type": "map[string] or null", "required": true, "description": "CEL expressions extracting named values from claims. Not yet supported; always null." }, { "name": "created_at", "type": "string", "required": true, "description": "When this rule was created.", "constraints": { "format": "date-time" } }, { "name": "created_by_actor_id", "type": "string or null", "required": true, "description": "Tagged ID (`user_`/`svac_`) of the actor that created this rule." }, { "name": "description", "type": "string or null", "required": true, "description": "Optional free-text description." }, { "name": "issuer_id", "type": "string", "required": true, "description": "Tagged ID of the issuer whose tokens this rule accepts." }, { "name": "issuer_name", "type": "string or null", "required": true, "description": "Issuer's display name at read time." }, { "name": "match", "type": "BetaFederationRuleMatch", "required": true, "description": "Conditions the verified JWT must satisfy for this rule to apply. All populated matcher fields must pass." }, { "name": "match.audience", "type": "string or null", "required": false, "description": "Exact match against the `aud` claim (any element if array). When omitted, the JWT's `aud` must still equal Anthropic's expected audience for the issuer; setting this field overrides that default.", "constraints": { "maxLength": "1024" } }, { "name": "match.claims", "type": "map[string] or null", "required": false, "description": "Exact-match `{claim: value}` pairs against top-level claims. Only string-valued claims can be matched; use `condition` for non-string claims." }, { "name": "match.condition", "type": "string or null", "required": false, "description": "CEL expression over claims for logic the structural fields can't express. Must evaluate to a boolean and may reference only the `claims` variable; a constant-true expression (such as `true`) is rejected with 400.", "constraints": { "maxLength": "4096" } }, { "name": "match.subject_prefix", "type": "string or null", "required": false, "description": "Match the verified JWT `sub` claim. Exact match unless the value ends with `*`, in which case it is a prefix match. Example: `repo:my-org/my-repo:ref:refs/heads/main`.", "constraints": { "maxLength": "1024" } }, { "name": "name", "type": "string", "required": true, "description": "Admin-chosen slug identifier." }, { "name": "oauth_scope", "type": "string", "required": true, "description": "Space-separated OAuth scopes granted on the minted token." }, { "name": "target", "type": "BetaServiceAccountTarget", "required": true, "description": "Identity that tokens minted via this rule act as. Currently always a `service_account` target." }, { "name": "target.type", "type": "\"service_account\"", "required": true, "description": "" }, { "name": "target.service_account_id", "type": "string", "required": true, "description": "Tagged ID of the service account to mint tokens for." }, { "name": "target.service_account_name", "type": "string or null", "required": false, "description": "Service account's display name at read time. Ignored on writes." }, { "name": "token_lifetime_seconds", "type": "number", "required": true, "description": "Lifetime in seconds of access tokens minted via this rule. Minted tokens are capped at `max(60, min(this value, 2 × remaining assertion validity))` seconds." }, { "name": "updated_at", "type": "string", "required": true, "description": "When this rule was last updated.", "constraints": { "format": "date-time" } }, { "name": "updated_by_actor_id", "type": "string or null", "required": true, "description": "Tagged ID (`user_`/`svac_`) of the actor that last updated this rule." }, { "name": "workspace_id", "type": "string or null", "required": true, "description": "Legacy single-workspace binding. Prefer `workspace_ids` and the `/federation_rules/{federation_rule_id}/workspaces` sub-resource for managing workspace enablement." }, { "name": "workspace_ids", "type": "array of string", "required": true, "description": "Tagged IDs of the workspaces this rule is enabled for. May be empty for older rules that only carry the legacy `workspace_id` binding. Ignored at exchange time when `applies_to_all_workspaces` is true (the list may still be non-empty)." } ], "example": { "id": "fdrl_01SDCCSbTxrXDpWc1phhtcfK", "applies_to_all_workspaces": true, "archived_at": "2019-12-27T18:11:19.117Z", "archived_by_actor_id": "archived_by_actor_id", "attributes": { "foo": "string" }, "created_at": "2024-10-30T23:58:27.427722Z", "created_by_actor_id": "created_by_actor_id", "description": "description", "issuer_id": "issuer_id", "issuer_name": "issuer_name", "match": { "audience": "audience", "claims": { "foo": "string" }, "condition": "condition", "subject_prefix": "subject_prefix" }, "name": "prod-deploy-pipeline", "oauth_scope": "oauth_scope", "target": { "service_account_id": "svac_01SDCCSbTxrXDpWc1phhtcfK", "type": "service_account", "service_account_name": "service_account_name" }, "token_lifetime_seconds": 0, "type": "federation_rule", "updated_at": "2024-10-30T23:58:27.427722Z", "updated_by_actor_id": "updated_by_actor_id", "workspace_id": "workspace_id", "workspace_ids": [ "string" ] }, "status": [ "DOCUMENTED" ], "sources": [ { "url": "https://platform.claude.com/docs/en/api/beta/organization/federation/rules/create", "retrieved_at": "2026-09-18" }, { "url": "https://platform.claude.com/docs/en/api/beta/organization/federation/rules", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/anthropic-platform-objects.json" }, { "provider": "anthropic", "api_family": "admin", "name": "FederationRuleWorkspace", "official_type_name": "BetaFederationRuleWorkspace", "description": "Response object of POST /v1/organizations/federation_rules/{federation_rule_id}/workspaces", "fields": [ { "name": "type", "type": "\"federation_rule_workspace\"", "required": true, "description": "", "default": "federation_rule_workspace" }, { "name": "created_at", "type": "string", "required": true, "description": "When this workspace was enabled for the rule.", "constraints": { "format": "date-time" } }, { "name": "created_by_actor_id", "type": "string or null", "required": true, "description": "Tagged ID (`user_...` or `svac_...`) of the actor that enabled this workspace for the rule, if known." }, { "name": "federation_rule_id", "type": "string", "required": true, "description": "Tagged ID of the federation rule." }, { "name": "workspace_id", "type": "string", "required": true, "description": "Tagged ID of the workspace this rule is enabled for." }, { "name": "workspace_name", "type": "string or null", "required": true, "description": "Workspace display name. Populated when listing; null in the enable response." } ], "example": { "created_at": "2024-10-30T23:58:27.427722Z", "created_by_actor_id": "created_by_actor_id", "federation_rule_id": "federation_rule_id", "type": "federation_rule_workspace", "workspace_id": "workspace_id", "workspace_name": "workspace_name" }, "status": [ "DOCUMENTED" ], "sources": [ { "url": "https://platform.claude.com/docs/en/api/beta/organization/federation/rules/workspaces/add", "retrieved_at": "2026-09-18" }, { "url": "https://platform.claude.com/docs/en/api/beta/organization/federation/rules/workspaces", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/anthropic-platform-objects.json" }, { "provider": "anthropic", "api_family": "admin", "name": "OrganizationInvite", "official_type_name": "BetaOrganizationInvite", "description": "Response object of POST /v1/organizations/invites", "fields": [ { "name": "type", "type": "\"invite\"", "required": true, "description": "Object type. For Invites, this is always `\"invite\"`.", "default": "invite" }, { "name": "id", "type": "string", "required": true, "description": "ID of the Invite." }, { "name": "accepted_at", "type": "string or null", "required": true, "description": "RFC 3339 datetime string indicating when the Invite was accepted, or null.", "constraints": { "format": "date-time" } }, { "name": "email", "type": "string", "required": true, "description": "Email of the User being invited." }, { "name": "expires_at", "type": "string", "required": true, "description": "RFC 3339 datetime string indicating when the Invite expires.", "constraints": { "format": "date-time" } }, { "name": "invited_at", "type": "string", "required": true, "description": "RFC 3339 datetime string indicating when the Invite was created.", "constraints": { "format": "date-time" } }, { "name": "rbac_group_ids", "type": "array of string", "required": true, "description": "RBAC group IDs recorded on the Invite (Claude Enterprise organizations), to be assigned to the User when the Invite is accepted. `[]` when none." }, { "name": "role", "type": "BetaOrganizationRole", "required": true, "description": "Organization role of the User.", "enum": [ "admin", "billing", "claude_code_user", "developer", "managed", "membership_admin", "owner", "primary_owner", "user" ] }, { "name": "status", "type": "\"accepted\" or \"deleted\" or \"expired\" or \"pending\"", "required": true, "description": "Status of the Invite.", "enum": [ "accepted", "deleted", "expired", "pending" ] } ], "example": { "id": "invite_015gWxCN9Hfg2QhZwTK7Mdeu", "accepted_at": "2019-12-27T18:11:19.117Z", "email": "user@emaildomain.com", "expires_at": "2024-11-20T23:58:27.427722Z", "invited_at": "2024-10-30T23:58:27.427722Z", "rbac_group_ids": [ "string" ], "role": "admin", "status": "pending", "type": "invite" }, "status": [ "DOCUMENTED" ], "sources": [ { "url": "https://platform.claude.com/docs/en/api/beta/organization/invites/create", "retrieved_at": "2026-09-18" }, { "url": "https://platform.claude.com/docs/en/api/beta/organization/invites", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/anthropic-platform-objects.json" }, { "provider": "anthropic", "api_family": "admin", "name": "Organization", "official_type_name": "BetaOrganization", "description": "Response object of GET /v1/organizations/me", "fields": [ { "name": "type", "type": "\"organization\"", "required": true, "description": "Object type. For Organizations, this is always `\"organization\"`.", "default": "organization" }, { "name": "id", "type": "string", "required": true, "description": "ID of the Organization.", "constraints": { "format": "uuid" } }, { "name": "name", "type": "string", "required": true, "description": "Name of the Organization." } ], "example": { "id": "12345678-1234-5678-1234-567812345678", "name": "Organization Name", "type": "organization" }, "status": [ "DOCUMENTED", "LIVE_VERIFIED" ], "sources": [ { "url": "https://platform.claude.com/docs/en/api/beta/organization/retrieve", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/anthropic-platform-objects.json" }, { "provider": "anthropic", "api_family": "admin", "name": "RBACGroup", "official_type_name": "BetaRBACGroup", "description": "Response object of POST /v1/organizations/rbac_groups", "fields": [ { "name": "type", "type": "\"rbac_group\"", "required": true, "description": "Object type. For RBAC Groups, this is always `\"rbac_group\"`.", "default": "rbac_group" }, { "name": "id", "type": "string", "required": true, "description": "ID of the RBAC Group." }, { "name": "created_at", "type": "string", "required": true, "description": "RFC 3339 timestamp of when the RBAC Group was created.", "constraints": { "format": "date-time" } }, { "name": "name", "type": "string", "required": true, "description": "Name of the RBAC Group. Not uniqueness-enforced." }, { "name": "roles", "type": "array of string or null", "required": true, "description": "RBAC Role IDs attached to this RBAC Group. Role attachment is managed in the admin settings and is read-only on this API. `null` means role data was temporarily unavailable — retry to distinguish from an empty list." }, { "name": "source_type", "type": "\"direct\" or \"scim\"", "required": true, "description": "How the RBAC Group was created: `\"direct\"` for groups created directly (for example, in the organization's admin settings), `\"scim\"` for groups provisioned by the identity provider.", "enum": [ "direct", "scim" ] }, { "name": "updated_at", "type": "string", "required": true, "description": "RFC 3339 timestamp of when the RBAC Group was last updated.", "constraints": { "format": "date-time" } } ], "example": { "id": "rbac_group_012rppKaSVsmTo6NqRDXQXNF", "created_at": "2024-10-30T23:58:27.427722Z", "name": "Engineering", "roles": [ "rbac_role_016J8xVtKpDq3Wy9ZmN2hR4s" ], "source_type": "direct", "type": "rbac_group", "updated_at": "2024-10-30T23:58:27.427722Z" }, "status": [ "DOCUMENTED" ], "sources": [ { "url": "https://platform.claude.com/docs/en/api/beta/organization/rbac_groups/create", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/anthropic-platform-objects.json" }, { "provider": "anthropic", "api_family": "admin", "name": "RBACGroupDeleted", "official_type_name": "BetaRBACGroupDeleted", "description": "Response object of DELETE /v1/organizations/rbac_groups/{group_id}", "fields": [ { "name": "type", "type": "\"rbac_group_deleted\"", "required": true, "description": "Deleted object type. For RBAC Groups, this is always `\"rbac_group_deleted\"`.", "default": "rbac_group_deleted" }, { "name": "id", "type": "string", "required": true, "description": "ID of the RBAC Group." } ], "example": { "id": "rbac_group_012rppKaSVsmTo6NqRDXQXNF", "type": "rbac_group_deleted" }, "status": [ "DOCUMENTED" ], "sources": [ { "url": "https://platform.claude.com/docs/en/api/beta/organization/rbac_groups/delete", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/anthropic-platform-objects.json" }, { "provider": "anthropic", "api_family": "admin", "name": "RBACGroupMember", "official_type_name": "BetaRBACGroupMember", "description": "Response object of POST /v1/organizations/rbac_groups/{group_id}/members", "fields": [ { "name": "type", "type": "\"rbac_group_member\"", "required": true, "description": "Object type. For RBAC Group Members, this is always `\"rbac_group_member\"`.", "default": "rbac_group_member" }, { "name": "created_at", "type": "string", "required": true, "description": "RFC 3339 timestamp of when the User was added to the RBAC Group.", "constraints": { "format": "date-time" } }, { "name": "email", "type": "string", "required": true, "description": "Email of the User." }, { "name": "group_id", "type": "string", "required": true, "description": "ID of the RBAC Group." }, { "name": "user_id", "type": "string", "required": true, "description": "ID of the User." } ], "example": { "created_at": "2024-10-30T23:58:27.427722Z", "email": "user@emaildomain.com", "group_id": "rbac_group_012rppKaSVsmTo6NqRDXQXNF", "type": "rbac_group_member", "user_id": "user_01WCz1FkmYMm4gnmykNKUu3Q" }, "status": [ "DOCUMENTED" ], "sources": [ { "url": "https://platform.claude.com/docs/en/api/beta/organization/rbac_groups/members/create", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/anthropic-platform-objects.json" }, { "provider": "anthropic", "api_family": "admin", "name": "RBACGroupMemberDeleted", "official_type_name": "BetaRBACGroupMemberDeleted", "description": "Response object of DELETE /v1/organizations/rbac_groups/{group_id}/members/{user_id}", "fields": [ { "name": "type", "type": "\"rbac_group_member_deleted\"", "required": true, "description": "Deleted object type. For RBAC Group Members, this is always `\"rbac_group_member_deleted\"`.", "default": "rbac_group_member_deleted" }, { "name": "group_id", "type": "string", "required": true, "description": "ID of the RBAC Group." }, { "name": "user_id", "type": "string", "required": true, "description": "ID of the User." } ], "example": { "group_id": "rbac_group_012rppKaSVsmTo6NqRDXQXNF", "type": "rbac_group_member_deleted", "user_id": "user_01WCz1FkmYMm4gnmykNKUu3Q" }, "status": [ "DOCUMENTED" ], "sources": [ { "url": "https://platform.claude.com/docs/en/api/beta/organization/rbac_groups/members/delete", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/anthropic-platform-objects.json" }, { "provider": "anthropic", "api_family": "admin", "name": "RBACRole", "official_type_name": "BetaRBACRole", "description": "Response object of GET /v1/organizations/rbac_roles/{role_id}", "fields": [ { "name": "type", "type": "\"rbac_role\"", "required": true, "description": "Object type. For RBAC Roles, this is always `\"rbac_role\"`.", "default": "rbac_role" }, { "name": "id", "type": "string", "required": true, "description": "ID of the RBAC Role." }, { "name": "created_at", "type": "string", "required": true, "description": "RFC 3339 datetime string indicating when the RBAC Role was created.", "constraints": { "format": "date-time" } }, { "name": "name", "type": "string", "required": true, "description": "Name of the RBAC Role." }, { "name": "updated_at", "type": "string", "required": true, "description": "RFC 3339 datetime string indicating when the RBAC Role was last updated.", "constraints": { "format": "date-time" } } ], "example": { "id": "rbac_role_016J8xVtKpDq3Wy9ZmN2hR4s", "created_at": "2024-10-30T23:58:27.427722Z", "name": "Project Editor", "type": "rbac_role", "updated_at": "2024-10-30T23:58:27.427722Z" }, "status": [ "DOCUMENTED" ], "sources": [ { "url": "https://platform.claude.com/docs/en/api/beta/organization/rbac_roles/retrieve", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/anthropic-platform-objects.json" }, { "provider": "anthropic", "api_family": "admin", "name": "ServiceAccount", "official_type_name": "BetaServiceAccount", "description": "Named non-human identity within the caller's organization. A service account is a pure identity: name + org. Authorization lives on whatever references it (federation rules).", "fields": [ { "name": "type", "type": "\"service_account\"", "required": true, "description": "", "default": "service_account" }, { "name": "id", "type": "string", "required": true, "description": "Tagged ID of the service account." }, { "name": "archived_at", "type": "string or null", "required": true, "description": "If set, this service account is archived.", "constraints": { "format": "date-time" } }, { "name": "archived_by_actor_id", "type": "string or null", "required": true, "description": "Tagged ID (`user_`/`svac_`) of the actor that archived this service account." }, { "name": "created_at", "type": "string", "required": true, "description": "When this service account was created.", "constraints": { "format": "date-time" } }, { "name": "created_by_actor_id", "type": "string or null", "required": true, "description": "Tagged ID (`user_`/`svac_`) of the actor that created this service account." }, { "name": "description", "type": "string or null", "required": true, "description": "Optional free-text description." }, { "name": "name", "type": "string", "required": true, "description": "Admin-chosen slug identifier." }, { "name": "organization_role", "type": "\"admin\" or \"developer\"", "required": true, "description": "Org-level role. A federation rule may only be created or retargeted to grant `org:admin` scope when this is `admin`. A rule granting `org:admin` whose target is later demoted to `developer` is rejected at token exchange. Rules granting `org:admin` are managed in the Console.", "enum": [ "admin", "developer" ] }, { "name": "updated_at", "type": "string", "required": true, "description": "When this service account was last updated.", "constraints": { "format": "date-time" } }, { "name": "updated_by_actor_id", "type": "string or null", "required": true, "description": "Tagged ID (`user_`/`svac_`) of the actor that last updated this service account." } ], "example": { "id": "svac_01SDCCSbTxrXDpWc1phhtcfK", "archived_at": "2019-12-27T18:11:19.117Z", "archived_by_actor_id": "archived_by_actor_id", "created_at": "2024-10-30T23:58:27.427722Z", "created_by_actor_id": "created_by_actor_id", "description": "description", "name": "ci-deploy-bot", "organization_role": "admin", "type": "service_account", "updated_at": "2024-10-30T23:58:27.427722Z", "updated_by_actor_id": "updated_by_actor_id" }, "status": [ "DOCUMENTED" ], "sources": [ { "url": "https://platform.claude.com/docs/en/api/beta/organization/service_accounts/create", "retrieved_at": "2026-09-18" }, { "url": "https://platform.claude.com/docs/en/api/beta/organization/service_accounts", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/anthropic-platform-objects.json" }, { "provider": "anthropic", "api_family": "admin", "name": "ServiceAccountWorkspaceMember", "official_type_name": "BetaServiceAccountWorkspaceMember", "description": "Response object of POST /v1/organizations/service_accounts/{service_account_id}/workspaces", "fields": [ { "name": "type", "type": "\"service_account_workspace_member\"", "required": true, "description": "", "default": "service_account_workspace_member" }, { "name": "created_by_actor_id", "type": "string or null", "required": true, "description": "Tagged ID (`user_...`/`svac_...`) of the actor who created this membership." }, { "name": "implicit", "type": "boolean or null", "required": true, "description": "True when this is the implicit default-workspace membership every service account has when no explicit membership exists. Implicit memberships have role `workspace_user` and cannot be removed." }, { "name": "service_account_id", "type": "string", "required": true, "description": "Tagged service account ID (`svac_...`)." }, { "name": "workspace_id", "type": "string", "required": true, "description": "Tagged workspace ID (`wrkspc_...`)." }, { "name": "workspace_role", "type": "BetaWorkspaceRole", "required": true, "description": "Role of the service account in this workspace. Service accounts cannot hold the `workspace_billing` role.", "enum": [ "workspace_admin", "workspace_billing", "workspace_developer", "workspace_restricted_developer", "workspace_user" ] } ], "example": { "created_by_actor_id": "created_by_actor_id", "implicit": true, "service_account_id": "service_account_id", "type": "service_account_workspace_member", "workspace_id": "workspace_id", "workspace_role": "workspace_admin" }, "status": [ "DOCUMENTED" ], "sources": [ { "url": "https://platform.claude.com/docs/en/api/beta/organization/service_accounts/workspaces/add", "retrieved_at": "2026-09-18" }, { "url": "https://platform.claude.com/docs/en/api/beta/organization/service_accounts/workspaces", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/anthropic-platform-objects.json" }, { "provider": "anthropic", "api_family": "admin", "name": "SpendLimitIncreaseRequest", "official_type_name": "BetaSpendLimitIncreaseRequest", "description": "Response object of GET /v1/organizations/spend_limit_increase_requests/{spend_limit_increase_request_id}", "fields": [ { "name": "type", "type": "\"spend_limit_increase_request\"", "required": true, "description": "", "default": "spend_limit_increase_request" }, { "name": "id", "type": "string", "required": true, "description": "" }, { "name": "actor", "type": "object", "required": true, "description": "A user within the organization. `name` and `email_address` are null when the underlying account is unavailable or has been deleted; `deleted` is true only for deleted accounts." }, { "name": "actor.type", "type": "\"user_actor\"", "required": true, "description": "Actor type. Always `user_actor`.", "default": "user_actor" }, { "name": "actor.deleted", "type": "boolean", "required": true, "description": "True only when the underlying account has been deleted.", "default": "false" }, { "name": "actor.email_address", "type": "string or null", "required": true, "description": "The user's email address. Null when the account is unavailable or has been deleted." }, { "name": "actor.name", "type": "string or null", "required": true, "description": "The user's current display name. Null when the account is unavailable, has been deleted, or has no name set." }, { "name": "actor.user_id", "type": "string", "required": true, "description": "Tagged ID of the user." }, { "name": "created_at", "type": "string", "required": true, "description": "", "constraints": { "format": "date-time" } }, { "name": "period", "type": "\"daily\" or \"monthly\" or \"weekly\"", "required": true, "description": "", "enum": [ "daily", "monthly", "weekly" ] }, { "name": "resolved_at", "type": "string or null", "required": true, "description": "", "constraints": { "format": "date-time" } }, { "name": "resolved_by", "type": "UserActor or ScopedAPIKeyActor or null", "required": true, "description": "" }, { "name": "resolved_by.type", "type": "\"user_actor\"", "required": true, "description": "Actor type. Always `user_actor`.", "default": "user_actor" }, { "name": "resolved_by.deleted", "type": "boolean", "required": true, "description": "True only when the underlying account has been deleted.", "default": "false" }, { "name": "resolved_by.email_address", "type": "string or null", "required": true, "description": "The user's email address. Null when the account is unavailable or has been deleted." }, { "name": "resolved_by.name", "type": "string or null", "required": true, "description": "The user's current display name. Null when the account is unavailable, has been deleted, or has no name set." }, { "name": "resolved_by.user_id", "type": "string", "required": true, "description": "Tagged ID of the user." }, { "name": "resolved_by.type", "type": "\"scoped_api_key_actor\"", "required": true, "description": "", "default": "scoped_api_key_actor" }, { "name": "resolved_by.scoped_api_key_id", "type": "string", "required": true, "description": "" }, { "name": "spend_summary", "type": "BetaSpendSummary or null", "required": true, "description": "Per-member effective-limit report row (`GET /spend_limits/effective`)." }, { "name": "spend_summary.actor", "type": "UserActor or ScopedAPIKeyActor", "required": true, "description": "" }, { "name": "spend_summary.amount", "type": "string or null", "required": true, "description": "Effective limit amount as a non-negative integer decimal string in the minor unit of `currency` (cents for USD). `null` means no limit applies for this row's `period` — each period resolves independently, so another period may still cap this member." }, { "name": "spend_summary.currency", "type": "string", "required": true, "description": "ISO 4217 code of the organization's billing currency; the unit for `amount` and `period_to_date_spend`." }, { "name": "spend_summary.period", "type": "\"daily\" or \"monthly\" or \"weekly\"", "required": true, "description": "Period this row's effective limit and spend are reported for.", "enum": [ "daily", "monthly", "weekly" ] }, { "name": "spend_summary.period_to_date_spend", "type": "string", "required": true, "description": "The member's spend so far in the current period, as a non-negative decimal string in the minor unit of `currency` (cents for USD). May carry fractional minor units up to three decimal places (e.g. `\"12050.5\"`) — metered usage is not rounded to whole cents. Reads as `\"0\"` when the spend reading is temporarily unavailable." }, { "name": "spend_summary.scope", "type": "User or SeatTier or RBACGroup or 3 more", "required": true, "description": "" }, { "name": "spend_summary.source", "type": "User or SeatTier or RBACGroup or 3 more", "required": true, "description": "" }, { "name": "spend_summary.spend_limit_id", "type": "string", "required": true, "description": "" }, { "name": "status", "type": "\"approved\" or \"denied\" or \"pending\"", "required": true, "description": "", "enum": [ "approved", "denied", "pending" ] } ], "example": { "id": "id", "actor": { "deleted": true, "email_address": "email_address", "name": "name", "type": "user_actor", "user_id": "user_01WCz1FkmYMm4gnmykNKUu3Q" }, "created_at": "2019-12-27T18:11:19.117Z", "period": "monthly", "resolved_at": "2019-12-27T18:11:19.117Z", "resolved_by": { "deleted": true, "email_address": "email_address", "name": "name", "type": "user_actor", "user_id": "user_01WCz1FkmYMm4gnmykNKUu3Q" }, "spend_summary": { "actor": { "deleted": true, "email_address": "email_address", "name": "name", "type": "user_actor", "user_id": "user_01WCz1FkmYMm4gnmykNKUu3Q" }, "amount": "50000", "currency": "USD", "period": "monthly", "period_to_date_spend": "12050.5", "scope": { "type": "user", "user_id": "user_01WCz1FkmYMm4gnmykNKUu3Q" }, "source": { "type": "user", "user_id": "user_01WCz1FkmYMm4gnmykNKUu3Q" }, "spend_limit_id": "spend_limit_id" }, "status": "approved", "type": "spend_limit_increase_request" }, "status": [ "DOCUMENTED" ], "sources": [ { "url": "https://platform.claude.com/docs/en/api/beta/organization/spend_limits/increase_requests/retrieve", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/anthropic-platform-objects.json" }, { "provider": "anthropic", "api_family": "admin", "name": "SpendLimit", "official_type_name": "BetaSpendLimit", "description": "A configured spend limit: a cap on metered spend for one scope and period.", "fields": [ { "name": "type", "type": "\"spend_limit\"", "required": true, "description": "Object type. Always `spend_limit`.", "default": "spend_limit" }, { "name": "id", "type": "string", "required": true, "description": "Unique tagged ID of the spend limit (`spl_...`)." }, { "name": "amount", "type": "string or null", "required": true, "description": "Limit amount as a non-negative integer decimal string in the minor unit of `currency` (cents for USD): \"50000\" is $500.00. `null` means no numeric cap is configured at this scope — see the effective report for whether a limit applies." }, { "name": "created_at", "type": "string", "required": true, "description": "RFC 3339 datetime at which the spend limit was created.", "constraints": { "format": "date-time" } }, { "name": "currency", "type": "string", "required": true, "description": "ISO 4217 code of the organization's billing currency; the unit for `amount`." }, { "name": "period", "type": "\"daily\" or \"monthly\" or \"weekly\"", "required": true, "description": "Length of the window the limit resets over. `amount` caps spend within each period.", "enum": [ "daily", "monthly", "weekly" ] }, { "name": "scope", "type": "User or SeatTier or RBACGroup or 3 more", "required": true, "description": "What the limit applies to. A tagged union on `type`; each variant carries the identifier for its scope." }, { "name": "scope.type", "type": "\"user\"", "required": true, "description": "Scope type. Always `user` for this scope.", "default": "user" }, { "name": "scope.user_id", "type": "string", "required": true, "description": "Tagged ID of the member the spend limit applies to." }, { "name": "scope.type", "type": "\"seat_tier\"", "required": true, "description": "", "default": "seat_tier" }, { "name": "scope.seat_tier", "type": "string", "required": true, "description": "" }, { "name": "scope.type", "type": "\"rbac_group\"", "required": true, "description": "", "default": "rbac_group" }, { "name": "scope.rbac_group_id", "type": "string", "required": true, "description": "" }, { "name": "scope.type", "type": "\"organization_service\"", "required": true, "description": "", "default": "organization_service" }, { "name": "scope.service", "type": "string", "required": true, "description": "" }, { "name": "scope.type", "type": "\"organization\"", "required": true, "description": "", "default": "organization" }, { "name": "scope.type", "type": "\"workspace\"", "required": true, "description": "Scope type. Always `workspace` for this scope.", "default": "workspace" }, { "name": "scope.workspace_id", "type": "string", "required": true, "description": "Tagged ID of the workspace the spend limit applies to." }, { "name": "updated_at", "type": "string", "required": true, "description": "RFC 3339 datetime at which the spend limit was last modified.", "constraints": { "format": "date-time" } } ], "example": { "id": "id", "amount": "50000", "created_at": "2019-12-27T18:11:19.117Z", "currency": "USD", "period": "monthly", "scope": { "type": "user", "user_id": "user_01WCz1FkmYMm4gnmykNKUu3Q" }, "type": "spend_limit", "updated_at": "2019-12-27T18:11:19.117Z" }, "status": [ "DOCUMENTED" ], "sources": [ { "url": "https://platform.claude.com/docs/en/api/beta/organization/spend_limits/create", "retrieved_at": "2026-09-18" }, { "url": "https://platform.claude.com/docs/en/api/beta/organization/spend_limits", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/anthropic-platform-objects.json" }, { "provider": "anthropic", "api_family": "admin", "name": "OrganizationTunnel", "official_type_name": "BetaOrganizationTunnel", "description": "Response object of GET /v1/organizations/tunnels/{tunnel_id}", "fields": [ { "name": "type", "type": "\"tunnel\"", "required": true, "description": "Object type. Always `tunnel` for Tunnels.", "default": "tunnel" }, { "name": "id", "type": "string", "required": true, "description": "ID of the Tunnel." }, { "name": "archived_at", "type": "string or null", "required": true, "description": "RFC 3339 datetime string indicating when the Tunnel was archived, or `null` if it is not archived.", "constraints": { "format": "date-time" } }, { "name": "created_at", "type": "string", "required": true, "description": "RFC 3339 datetime string indicating when the Tunnel was created.", "constraints": { "format": "date-time" } }, { "name": "display_name", "type": "string or null", "required": true, "description": "Human-readable name for the Tunnel (1–255 characters), or `null` if unset." }, { "name": "domain", "type": "string", "required": true, "description": "Anthropic-assigned hostname for the Tunnel. MCP server URLs whose host is a subdomain of this value are routed through the Tunnel. Globally unique and never reused, even after the Tunnel is archived." }, { "name": "workspace_id", "type": "string or null", "required": true, "description": "ID of the Workspace this Tunnel belongs to, or `null` for the default Workspace. Immutable after creation." } ], "example": { "id": "tnl_01Hx9Kp2RtQvMn3sWbYdLcF8", "archived_at": "2024-11-01T23:59:27.427722Z", "created_at": "2024-10-30T23:58:27.427722Z", "display_name": "Production", "domain": "a1b2c3d4.tunnel.anthropic.com", "type": "tunnel", "workspace_id": "wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ" }, "status": [ "DOCUMENTED" ], "sources": [ { "url": "https://platform.claude.com/docs/en/api/beta/organization/mcp_tunnels/retrieve", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/anthropic-platform-objects.json" }, { "provider": "anthropic", "api_family": "admin", "name": "OrganizationTunnelCertificate", "official_type_name": "BetaOrganizationTunnelCertificate", "description": "Response object of POST /v1/organizations/tunnels/{tunnel_id}/certificates", "fields": [ { "name": "type", "type": "\"tunnel_certificate\"", "required": true, "description": "Object type. Always `tunnel_certificate` for Tunnel Certificates.", "default": "tunnel_certificate" }, { "name": "id", "type": "string", "required": true, "description": "ID of the Tunnel Certificate." }, { "name": "archived_at", "type": "string or null", "required": true, "description": "RFC 3339 datetime string indicating when the certificate was archived, or `null` if it is not archived.", "constraints": { "format": "date-time" } }, { "name": "created_at", "type": "string", "required": true, "description": "RFC 3339 datetime string indicating when the certificate was registered.", "constraints": { "format": "date-time" } }, { "name": "expires_at", "type": "string or null", "required": true, "description": "RFC 3339 datetime string indicating when the certificate expires, or `null` if it does not expire.", "constraints": { "format": "date-time" } }, { "name": "fingerprint", "type": "string", "required": true, "description": "The certificate's SHA-256 fingerprint, as a lowercase hex string." }, { "name": "tunnel_id", "type": "string", "required": true, "description": "ID of the Tunnel this certificate is registered against." } ], "example": { "id": "tcrt_01JmWq4ZxnBvR7tKpY2sLdH9", "archived_at": "2024-11-01T23:59:27.427722Z", "created_at": "2024-10-30T23:58:27.427722Z", "expires_at": "2024-10-30T23:58:27.427722Z", "fingerprint": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08", "tunnel_id": "tnl_01Hx9Kp2RtQvMn3sWbYdLcF8", "type": "tunnel_certificate" }, "status": [ "DOCUMENTED" ], "sources": [ { "url": "https://platform.claude.com/docs/en/api/beta/organization/mcp_tunnels/tunnel_certificates/create", "retrieved_at": "2026-09-18" }, { "url": "https://platform.claude.com/docs/en/api/beta/organization/mcp_tunnels/tunnel_certificates", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/anthropic-platform-objects.json" }, { "provider": "anthropic", "api_family": "admin", "name": "OrganizationTunnelToken", "official_type_name": "BetaOrganizationTunnelToken", "description": "Response object of POST /v1/organizations/tunnels/{tunnel_id}/reveal_token", "fields": [ { "name": "type", "type": "\"tunnel_token\"", "required": true, "description": "Object type. Always `tunnel_token` for Tunnel Tokens.", "default": "tunnel_token" }, { "name": "id", "type": "string", "required": true, "description": "Stable identifier for the current token value. Changes when the token is rotated." }, { "name": "tunnel_token", "type": "string", "required": true, "description": "The tunnel's connection token." } ], "example": { "id": "ttkn_bb97000eaec162831399ca9b6684a4fdf5be49ace5683057b017aab5c87e19e0", "tunnel_token": "eyJhIjoiRVhBTVBMRSIsInQiOiJFWEFNUExFIiwicyI6IkVYQU1QTEUifQ==", "type": "tunnel_token" }, "status": [ "DOCUMENTED" ], "sources": [ { "url": "https://platform.claude.com/docs/en/api/beta/organization/mcp_tunnels/reveal_token", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/anthropic-platform-objects.json" }, { "provider": "anthropic", "api_family": "admin", "name": "ClaudeCodeUsageReport", "official_type_name": "BetaClaudeCodeUsageReport", "description": "Response object of GET /v1/organizations/usage_report/claude_code", "fields": [ { "name": "data", "type": "array of object", "required": true, "description": "List of Claude Code usage records for the requested date." }, { "name": "data[].actor", "type": "UserActor or APIActor", "required": true, "description": "The user or API key that performed the Claude Code actions." }, { "name": "data[].core_metrics", "type": "object", "required": true, "description": "Core productivity metrics measuring Claude Code usage and impact." }, { "name": "data[].core_metrics.commits_by_claude_code", "type": "number", "required": true, "description": "Number of git commits created through Claude Code's commit functionality." }, { "name": "data[].core_metrics.lines_of_code", "type": "object", "required": true, "description": "Statistics on code changes made through Claude Code." }, { "name": "data[].core_metrics.num_sessions", "type": "number", "required": true, "description": "Number of distinct Claude Code sessions initiated by this actor." }, { "name": "data[].core_metrics.pull_requests_by_claude_code", "type": "number", "required": true, "description": "Number of pull requests created through Claude Code's PR functionality." }, { "name": "data[].customer_type", "type": "\"api\" or \"subscription\"", "required": true, "description": "Type of customer account (api for API customers, subscription for Pro/Team customers).", "enum": [ "api", "subscription" ] }, { "name": "data[].date", "type": "string", "required": true, "description": "UTC day the usage metrics cover, as an RFC 3339 timestamp at midnight UTC (for example `2025-08-08T00:00:00Z`).", "constraints": { "format": "date-time" } }, { "name": "data[].is_remote", "type": "boolean", "required": true, "description": "Whether the usage came from remote Claude Code sessions, such as Claude Code on the web. Remote and local usage are reported as separate rows." }, { "name": "data[].model_breakdown", "type": "array of object", "required": true, "description": "Token usage and cost breakdown by AI model used." }, { "name": "data[].model_breakdown[].estimated_cost", "type": "object", "required": true, "description": "Estimated cost for using this model" }, { "name": "data[].model_breakdown[].model", "type": "string", "required": true, "description": "Name of the AI model used for Claude Code interactions." }, { "name": "data[].model_breakdown[].tokens", "type": "object", "required": true, "description": "Token usage breakdown for this model" }, { "name": "data[].organization_id", "type": "string", "required": true, "description": "ID of the organization that owns the Claude Code usage." }, { "name": "data[].terminal_type", "type": "string", "required": true, "description": "Type of terminal or environment where Claude Code was used." }, { "name": "data[].tool_actions", "type": "map[object]", "required": true, "description": "Breakdown of tool action acceptance and rejection rates by tool type." }, { "name": "data[].tool_actions.accepted", "type": "number", "required": true, "description": "Number of tool action proposals that the user accepted." }, { "name": "data[].tool_actions.rejected", "type": "number", "required": true, "description": "Number of tool action proposals that the user rejected." }, { "name": "data[].subscription_type", "type": "\"enterprise\" or \"team\" or null", "required": false, "description": "Subscription tier for subscription customers. `null` for API customers.", "enum": [ "enterprise", "team" ] }, { "name": "has_more", "type": "boolean", "required": true, "description": "True if there are more records available beyond the current page." }, { "name": "next_page", "type": "string or null", "required": true, "description": "Opaque cursor token for fetching the next page of results, or null if no more pages are available." } ], "example": { "data": [ { "actor": { "email_address": "user@emaildomain.com", "type": "user_actor" }, "core_metrics": { "commits_by_claude_code": 8, "lines_of_code": { "added": 342, "removed": 128 }, "num_sessions": 15, "pull_requests_by_claude_code": 2 }, "customer_type": "api", "date": "2025-08-08T00:00:00Z", "is_remote": false, "model_breakdown": [ { "estimated_cost": { "amount": 186, "currency": "USD" }, "model": "claude-opus-5", "tokens": { "cache_creation": 2340, "cache_read": 8790, "input": 45230, "output": 12450 } }, { "estimated_cost": { "amount": 42, "currency": "USD" }, "model": "claude-sonnet-5", "tokens": { "cache_creation": 890, "cache_read": 3420, "input": 23100, "output": 5680 } } ], "organization_id": "12345678-1234-5678-1234-567812345678", "terminal_type": "iTerm.app", "tool_actions": { "edit_tool": { "accepted": 25, "rejected": 3 }, "multi_edit_tool": { "accepted": 12, "rejected": 1 }, "notebook_edit_tool": { "accepted": 5, "rejected": 2 }, "write_tool": { "accepted": 8, "rejected": 0 } }, "subscription_type": "enterprise" } ], "has_more": true, "next_page": "page_MjAyNS0wNS0xNFQwMDowMDowMFo=" }, "status": [ "DOCUMENTED" ], "sources": [ { "url": "https://platform.claude.com/docs/en/api/beta/organization/usage_report/retrieve_claude_code", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/anthropic-platform-objects.json" }, { "provider": "anthropic", "api_family": "admin", "name": "MessagesUsageReport", "official_type_name": "BetaMessagesUsageReport", "description": "Response object of GET /v1/organizations/usage_report/messages", "fields": [ { "name": "data", "type": "array of object", "required": true, "description": "List of time buckets for this page, oldest first: one per `bucket_width` interval, including intervals with no usage (their `results` list is empty). A page holds at most `limit` buckets." }, { "name": "data[].ending_at", "type": "string", "required": true, "description": "End of the time bucket (exclusive) in RFC 3339 format.", "constraints": { "format": "date-time" } }, { "name": "data[].results", "type": "array of object", "required": true, "description": "List of usage items for this time bucket. There may be multiple items if one or more `group_by[]` parameters are specified." }, { "name": "data[].results[].account_id", "type": "string or null", "required": true, "description": "ID of the user account that made the request. `null` if not grouping by account or for non-OAuth requests." }, { "name": "data[].results[].api_key_id", "type": "string or null", "required": true, "description": "ID of the API key used. `null` if not grouping by API key or for usage in the Anthropic Console." }, { "name": "data[].results[].cache_creation", "type": "BetaCacheCreation", "required": true, "description": "The number of input tokens for cache creation." }, { "name": "data[].results[].cache_read_input_tokens", "type": "number", "required": true, "description": "The number of input tokens read from the cache." }, { "name": "data[].results[].context_window", "type": "\"0-200k\" or \"200k-1M\" or null", "required": true, "description": "Context window used. `null` if not grouping by context window.", "enum": [ "0-200k", "200k-1M" ] }, { "name": "data[].results[].inference_geo", "type": "\"global\" or \"not_available\" or \"us\" or null", "required": true, "description": "Inference geo used matching requests' `inference_geo` parameter if set, otherwise the workspace's `default_inference_geo`. For models that do not support specifying `inference_geo` the value is `\"not_available\"`. Always `null` if not grouping by inference geo.", "enum": [ "global", "not_available", "us" ] }, { "name": "data[].results[].model", "type": "string or null", "required": true, "description": "Model used. `null` if not grouping by model." }, { "name": "data[].results[].output_tokens", "type": "number", "required": true, "description": "The number of output tokens generated." }, { "name": "data[].results[].server_tool_use", "type": "object", "required": true, "description": "Server-side tool usage metrics." }, { "name": "data[].results[].service_account_id", "type": "string or null", "required": true, "description": "ID of the service account that made the request. `null` if not grouping by service account or for non-OIDC-federation requests." }, { "name": "data[].results[].service_tier", "type": "\"batch\" or \"flex\" or \"flex_discount\" or 3 more or null", "required": true, "description": "Service tier used. `null` if not grouping by service tier.", "enum": [ "batch", "flex", "flex_discount", "priority", "priority_on_demand", "standard" ] }, { "name": "data[].results[].uncached_input_tokens", "type": "number", "required": true, "description": "The number of uncached input tokens processed." }, { "name": "data[].results[].workspace_id", "type": "string or null", "required": true, "description": "ID of the Workspace used. `null` if not grouping by workspace or for the default workspace." }, { "name": "data[].starting_at", "type": "string", "required": true, "description": "Start of the time bucket (inclusive) in RFC 3339 format.", "constraints": { "format": "date-time" } }, { "name": "has_more", "type": "boolean", "required": true, "description": "Indicates if there are more results." }, { "name": "next_page", "type": "string or null", "required": true, "description": "Opaque cursor for the next page, or `null` when `has_more` is false. Pass it as the `page` parameter in the next request." } ], "example": { "data": [ { "ending_at": "2025-08-02T00:00:00Z", "results": [ { "account_id": "user_01WCz1FkmYMm4gnmykNKUu3Q", "api_key_id": "apikey_01Rj2N8SVvo6BePZj99NhmiT", "cache_creation": { "ephemeral_1h_input_tokens": 0, "ephemeral_5m_input_tokens": 0 }, "cache_read_input_tokens": 200, "context_window": "0-200k", "inference_geo": "global", "model": "claude-opus-5", "output_tokens": 500, "server_tool_use": { "web_search_requests": 10 }, "service_account_id": "svac_01Hk3R9TWxq7CfQak00OiVw4", "service_tier": "standard", "uncached_input_tokens": 1500, "workspace_id": "wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ" } ], "starting_at": "2025-08-01T00:00:00Z" } ], "has_more": true, "next_page": "page_MjAyNS0wNS0xNFQwMDowMDowMFo=" }, "status": [ "DOCUMENTED" ], "sources": [ { "url": "https://platform.claude.com/docs/en/api/beta/organization/usage_report/retrieve_messages", "retrieved_at": "2026-09-18" }, { "url": "https://platform.claude.com/docs/en/api/beta/organization/usage_report", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/anthropic-platform-objects.json" }, { "provider": "anthropic", "api_family": "admin", "name": "OrganizationUser", "official_type_name": "BetaOrganizationUser", "description": "Response object of GET /v1/organizations/users/{user_id}", "fields": [ { "name": "type", "type": "\"user\"", "required": true, "description": "Object type. For Users, this is always `\"user\"`.", "default": "user" }, { "name": "id", "type": "string", "required": true, "description": "ID of the User." }, { "name": "added_at", "type": "string", "required": true, "description": "RFC 3339 datetime string indicating when the User joined the Organization.", "constraints": { "format": "date-time" } }, { "name": "email", "type": "string", "required": true, "description": "Email of the User." }, { "name": "name", "type": "string", "required": true, "description": "Name of the User." }, { "name": "role", "type": "BetaOrganizationRole", "required": true, "description": "Organization role of the User.", "enum": [ "admin", "billing", "claude_code_user", "developer", "managed", "membership_admin", "owner", "primary_owner", "user" ] } ], "example": { "id": "user_01WCz1FkmYMm4gnmykNKUu3Q", "added_at": "2024-10-30T23:58:27.427722Z", "email": "user@emaildomain.com", "name": "Jane Doe", "role": "admin", "type": "user" }, "status": [ "DOCUMENTED" ], "sources": [ { "url": "https://platform.claude.com/docs/en/api/beta/organization/users/retrieve", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/anthropic-platform-objects.json" }, { "provider": "anthropic", "api_family": "admin", "name": "Workspace", "official_type_name": "BetaWorkspace", "description": "Response object of POST /v1/organizations/workspaces", "fields": [ { "name": "type", "type": "\"workspace\"", "required": true, "description": "Object type. For Workspaces, this is always `\"workspace\"`.", "default": "workspace" }, { "name": "id", "type": "string", "required": true, "description": "ID of the Workspace." }, { "name": "archived_at", "type": "string or null", "required": true, "description": "RFC 3339 datetime string indicating when the Workspace was archived, or `null` if the Workspace is not archived.", "constraints": { "format": "date-time" } }, { "name": "compartment_id", "type": "string", "required": true, "description": "Identifier for this Workspace's encryption compartment. When you configure a customer-managed encryption key (CMEK) on AWS, reference this value in your KMS key-policy condition so the key is scoped to this compartment. On GCP and Azure, Anthropic enforces the compartment binding automatically; you do not need to reference this value in your key configuration. See the CMEK integration guide for the required key configuration; unless your organization is on Claude Platform on AWS, it includes a separate value used during key validation. On Claude Platform on AWS there is no separate validation value: the key is validated against this Workspace's own value when it is attached, so if your key policy uses the compartment condition, add this value to it before attaching the key." }, { "name": "created_at", "type": "string", "required": true, "description": "RFC 3339 datetime string indicating when the Workspace was created.", "constraints": { "format": "date-time" } }, { "name": "data_residency", "type": "BetaDataResidency", "required": true, "description": "Data residency configuration." }, { "name": "data_residency.allowed_inference_geos", "type": "array of BetaAllowedInferenceGeo or \"unrestricted\"", "required": true, "description": "Permitted inference geo values. 'unrestricted' means all geos are allowed." }, { "name": "data_residency.default_inference_geo", "type": "\"global\" or \"us\"", "required": true, "description": "Default inference geo applied when requests omit the parameter.", "enum": [ "global", "us" ] }, { "name": "data_residency.workspace_geo", "type": "\"us\"", "required": true, "description": "Geographic region for workspace data storage. Immutable after creation." }, { "name": "display_color", "type": "string", "required": true, "description": "Hex color code representing the Workspace in the Anthropic Console." }, { "name": "external_key_id", "type": "string or null", "required": true, "description": "ID of the customer-managed encryption key (CMEK) configuration to use for this Workspace. Setting this field requires CMEK to be enabled for your organization. When set, data stored for this Workspace is encrypted with the referenced key. Create key configurations with the External Keys API. On Claude Platform on AWS the value is the AWS KMS key ARN, and the key must be a single-Region key in the same AWS account and Region as the Workspace. On that platform the key is validated against this Workspace when it is attached, so a key-policy problem is reported as an error on this request. This field is write-once: once a key is attached to a Workspace it cannot be detached or replaced. To rotate key material, rotate the underlying key on your cloud KMS; the `external_key_id` stays the same." }, { "name": "name", "type": "string", "required": true, "description": "Name of the Workspace." }, { "name": "tags", "type": "map[string]", "required": true, "description": "User-defined tags as string key-value pairs. Keys may not begin with `anthropic`." } ], "example": { "id": "wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ", "archived_at": "2024-11-01T23:59:27.427722Z", "compartment_id": "f8a7b6c5-4d3e-4f1a-8b9c-0d1e2f3a4b5c", "created_at": "2024-10-30T23:58:27.427722Z", "data_residency": { "allowed_inference_geos": "unrestricted", "default_inference_geo": "global", "workspace_geo": "us" }, "display_color": "#6C5BB9", "external_key_id": "ekey_01SDCCSbTxrXDpWc1phhtcfK", "name": "Workspace Name", "tags": { "env": "prod", "team": "platform" }, "type": "workspace" }, "status": [ "DOCUMENTED" ], "sources": [ { "url": "https://platform.claude.com/docs/en/api/beta/organization/workspaces/create", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/anthropic-platform-objects.json" }, { "provider": "anthropic", "api_family": "admin", "name": "WorkspaceMember", "official_type_name": "BetaWorkspaceMember", "description": "Response object of POST /v1/organizations/workspaces/{workspace_id}/members", "fields": [ { "name": "type", "type": "\"workspace_member\"", "required": true, "description": "Object type. For Workspace Members, this is always `\"workspace_member\"`.", "default": "workspace_member" }, { "name": "user_id", "type": "string", "required": true, "description": "ID of the User." }, { "name": "workspace_id", "type": "string", "required": true, "description": "ID of the Workspace." }, { "name": "workspace_role", "type": "BetaWorkspaceRole", "required": true, "description": "Role of the Workspace Member.", "enum": [ "workspace_admin", "workspace_billing", "workspace_developer", "workspace_restricted_developer", "workspace_user" ] } ], "example": { "type": "workspace_member", "user_id": "user_01WCz1FkmYMm4gnmykNKUu3Q", "workspace_id": "wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ", "workspace_role": "workspace_admin" }, "status": [ "DOCUMENTED" ], "sources": [ { "url": "https://platform.claude.com/docs/en/api/beta/organization/workspaces/members/add", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/anthropic-platform-objects.json" }, { "provider": "anthropic", "api_family": "skills", "name": "Skill", "official_type_name": "BetaSkill", "description": "Response object of POST /v1/skills", "fields": [ { "name": "type", "type": "\"skill\"", "required": true, "description": "Object type. For Skills, this is always `\"skill\"`.", "default": "skill" }, { "name": "id", "type": "string", "required": true, "description": "Unique identifier for the skill. The format and length of IDs may change over time." }, { "name": "created_at", "type": "string", "required": true, "description": "ISO 8601 timestamp of when the skill was created.", "constraints": { "format": "date-time" } }, { "name": "display_name", "type": "string", "required": true, "description": "Human-readable, single-line label for the Skill. Maximum 255 characters. Always set: derived from the SKILL.md frontmatter `name` when omitted at creation. Not unique." }, { "name": "latest_version_id", "type": "string", "required": true, "description": "ID of the newest Skill Version — what `latest` references resolve to. Always set: a Skill holds at least one version." }, { "name": "source", "type": "BetaSkillSource", "required": true, "description": "Where the Skill comes from. Possible values: * `\"custom\"`: authored by the platform user; private to their workspace * `\"anthropic\"`: published by Anthropic; shared and read-only * `\"anthropic_example\"`: Anthropic-published sample Skill * `\"plugin\"`: resolved from an installed plugin" }, { "name": "source.type", "type": "\"custom\" or \"anthropic\" or \"anthropic_example\" or \"plugin\"", "required": true, "description": "Where the Skill comes from. Possible values: * `\"custom\"`: authored by the platform user; private to their workspace * `\"anthropic\"`: published by Anthropic; shared and read-only * `\"anthropic_example\"`: Anthropic-published sample Skill * `\"plugin\"`: resolved from an installed plugin", "enum": [ "custom", "anthropic", "anthropic_example", "plugin" ] }, { "name": "updated_at", "type": "string", "required": true, "description": "ISO 8601 timestamp of when the skill was last updated.", "constraints": { "format": "date-time" } } ], "example": { "id": "skill_01JAbcdefghijklmnopqrstuvw", "created_at": "2024-10-30T23:58:27.427722Z", "display_name": "display_name", "latest_version_id": "latest_version_id", "source": { "type": "custom" }, "type": "skill", "updated_at": "2024-10-30T23:58:27.427722Z" }, "status": [ "DOCUMENTED", "LIVE_VERIFIED" ], "sources": [ { "url": "https://platform.claude.com/docs/en/api/beta/skills/create", "retrieved_at": "2026-09-18" }, { "url": "https://platform.claude.com/docs/en/api/skills/create", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/anthropic-platform-objects.json" }, { "provider": "anthropic", "api_family": "skills", "name": "DeletedSkill", "official_type_name": "BetaDeletedSkill", "description": "Response object of DELETE /v1/skills/{skill_id}", "fields": [ { "name": "type", "type": "\"skill_deleted\"", "required": true, "description": "Deleted object type. For Skills, this is always `\"skill_deleted\"`.", "default": "skill_deleted" }, { "name": "id", "type": "string", "required": true, "description": "Unique identifier for the skill. The format and length of IDs may change over time." } ], "example": { "id": "skill_01JAbcdefghijklmnopqrstuvw", "type": "skill_deleted" }, "status": [ "DOCUMENTED", "LIVE_VERIFIED" ], "sources": [ { "url": "https://platform.claude.com/docs/en/api/beta/skills/delete", "retrieved_at": "2026-09-18" }, { "url": "https://platform.claude.com/docs/en/api/skills/delete", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/anthropic-platform-objects.json" }, { "provider": "anthropic", "api_family": "skills", "name": "SkillVersion", "official_type_name": "BetaSkillVersion", "description": "Response object of POST /v1/skills/{skill_id}/versions", "fields": [ { "name": "type", "type": "\"skill_version\"", "required": true, "description": "Object type. For Skill Versions, this is always `\"skill_version\"`.", "default": "skill_version" }, { "name": "id", "type": "string", "required": true, "description": "Unique identifier for this Skill Version. The id addresses the version in paths and pins it in references." }, { "name": "created_at", "type": "string", "required": true, "description": "ISO 8601 timestamp of when the skill was created.", "constraints": { "format": "date-time" } }, { "name": "description", "type": "string", "required": true, "description": "Description of the skill version. This is extracted from the SKILL.md file in the skill upload." }, { "name": "name", "type": "string", "required": true, "description": "The Skill's immutable kebab-case slug, set at creation from the first upload's SKILL.md frontmatter `name` (or its enclosing directory). Every later upload must resolve to the same value. Also the top-level directory of the Skill's mounted files and the base name of a downloaded archive." }, { "name": "skill_id", "type": "string", "required": true, "description": "Unique identifier for the skill. The format and length of IDs may change over time." } ], "example": { "id": "id", "created_at": "2024-10-30T23:58:27.427722Z", "description": "description", "name": "name", "skill_id": "skill_01JAbcdefghijklmnopqrstuvw", "type": "skill_version" }, "status": [ "DOCUMENTED", "LIVE_VERIFIED" ], "sources": [ { "url": "https://platform.claude.com/docs/en/api/beta/skills/versions/create", "retrieved_at": "2026-09-18" }, { "url": "https://platform.claude.com/docs/en/api/beta/skills/versions", "retrieved_at": "2026-09-18" }, { "url": "https://platform.claude.com/docs/en/api/skills/versions/create", "retrieved_at": "2026-09-18" }, { "url": "https://platform.claude.com/docs/en/api/skills/versions", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/anthropic-platform-objects.json" }, { "provider": "anthropic", "api_family": "skills", "name": "DeletedSkillVersion", "official_type_name": "BetaDeletedSkillVersion", "description": "Response object of DELETE /v1/skills/{skill_id}/versions/{version}", "fields": [ { "name": "type", "type": "\"skill_version_deleted\"", "required": true, "description": "Deleted object type. For Skill Versions, this is always `\"skill_version_deleted\"`.", "default": "skill_version_deleted" }, { "name": "id", "type": "string", "required": true, "description": "Unique identifier for this Skill Version. The id addresses the version in paths and pins it in references." } ], "example": { "id": "id", "type": "skill_version_deleted" }, "status": [ "DOCUMENTED", "LIVE_VERIFIED" ], "sources": [ { "url": "https://platform.claude.com/docs/en/api/beta/skills/versions/delete", "retrieved_at": "2026-09-18" }, { "url": "https://platform.claude.com/docs/en/api/skills/versions/delete", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/anthropic-platform-objects.json" }, { "provider": "anthropic", "api_family": "messages-batches", "name": "Beta Message Batch Canceled Result", "official_type_name": "BetaMessageBatchCanceledResult", "description": "", "fields": [ { "name": "type", "type": "\"canceled\"", "required": true, "description": "", "default": "canceled" } ], "status": [ "DOCUMENTED" ], "sources": [ { "url": "https://platform.claude.com/docs/en/api/beta/messages/batches", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/anthropic-platform-objects.json" }, { "provider": "anthropic", "api_family": "messages-batches", "name": "Beta Message Batch Errored Result", "official_type_name": "BetaMessageBatchErroredResult", "description": "", "fields": [ { "name": "type", "type": "\"errored\"", "required": true, "description": "", "default": "errored" }, { "name": "error", "type": "BetaErrorResponse", "required": true, "description": "" }, { "name": "error.type", "type": "\"error\"", "required": true, "description": "", "default": "error" }, { "name": "error.error", "type": "BetaError", "required": true, "description": "" }, { "name": "error.request_id", "type": "string or null", "required": true, "description": "" } ], "status": [ "DOCUMENTED" ], "sources": [ { "url": "https://platform.claude.com/docs/en/api/beta/messages/batches", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/anthropic-platform-objects.json" }, { "provider": "anthropic", "api_family": "messages-batches", "name": "Beta Message Batch Expired Result", "official_type_name": "BetaMessageBatchExpiredResult", "description": "", "fields": [ { "name": "type", "type": "\"expired\"", "required": true, "description": "", "default": "expired" } ], "status": [ "DOCUMENTED" ], "sources": [ { "url": "https://platform.claude.com/docs/en/api/beta/messages/batches", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/anthropic-platform-objects.json" }, { "provider": "anthropic", "api_family": "messages-batches", "name": "Beta Message Batch Request Counts", "official_type_name": "BetaMessageBatchRequestCounts", "description": "", "fields": [ { "name": "canceled", "type": "number", "required": true, "description": "Number of requests in the Message Batch that have been canceled. This is zero until processing of the entire Message Batch has ended.", "default": "0" }, { "name": "errored", "type": "number", "required": true, "description": "Number of requests in the Message Batch that encountered an error. This is zero until processing of the entire Message Batch has ended.", "default": "0" }, { "name": "expired", "type": "number", "required": true, "description": "Number of requests in the Message Batch that have expired. This is zero until processing of the entire Message Batch has ended.", "default": "0" }, { "name": "processing", "type": "number", "required": true, "description": "Number of requests in the Message Batch that are processing.", "default": "0" }, { "name": "succeeded", "type": "number", "required": true, "description": "Number of requests in the Message Batch that have completed successfully. This is zero until processing of the entire Message Batch has ended.", "default": "0" } ], "status": [ "DOCUMENTED" ], "sources": [ { "url": "https://platform.claude.com/docs/en/api/beta/messages/batches", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/anthropic-platform-objects.json" }, { "provider": "anthropic", "api_family": "messages-batches", "name": "Beta Message Batch Result", "official_type_name": "BetaMessageBatchResult", "description": "Processing result for this request. Contains a Message output if processing was successful, an error response if processing failed, or the reason why processing was not attempted, such as cancellation or expiration.", "fields": [ { "name": "type", "type": "\"succeeded\"", "required": true, "description": "", "default": "succeeded" }, { "name": "message", "type": "BetaMessage", "required": true, "description": "" }, { "name": "message.type", "type": "\"message\"", "required": true, "description": "Object type. For Messages, this is always `\"message\"`.", "default": "message" }, { "name": "message.id", "type": "string", "required": true, "description": "Unique object identifier. The format and length of IDs may change over time." }, { "name": "message.container", "type": "BetaContainer or null", "required": true, "description": "Information about the container used in the request (for the code execution tool)" }, { "name": "message.container.id", "type": "string", "required": true, "description": "Identifier for the container used in this request" }, { "name": "message.container.expires_at", "type": "string", "required": true, "description": "The time at which the container will expire.", "constraints": { "format": "date-time" } }, { "name": "message.container.skills", "type": "array of BetaContainerSkill or null", "required": true, "description": "Skills loaded in the container" }, { "name": "message.content", "type": "array of BetaContentBlock", "required": true, "description": "Content generated by the model. This is an array of content blocks, each of which has a `type` that determines its shape. Example: ```json [{\"type\": \"text\", \"text\": \"Hi, I'm Claude.\"}] ``` If the request input `messages` ended with an `assistant` turn, then the response `content` will continue directly from that last turn. You can use this to constrain the model's output. For example, if the input `messages` were: ```json [ {\"role\": \"user\", \"content\": \"What's the Greek name for Sun? (A) Sol (B) Helios (C) Sun\"}, {\"role\": \"assistant\", \"content\": \"The best answer is (\"} ] ``` Then the response `content` might be: ```json [{\"type\": \"text\", \"text\": \"B)\"}] ```" }, { "name": "message.context_management", "type": "BetaContextManagementResponse or null", "required": true, "description": "Context management response. Information about context management strategies applied during the request." }, { "name": "message.context_management.applied_edits", "type": "array of BetaClearToolUses20250919EditResponse or BetaClearThinking20251015EditResponse", "required": true, "description": "List of context management edits that were applied." }, { "name": "message.diagnostics", "type": "BetaDiagnostics or null", "required": true, "description": "Response envelope for request-level diagnostics. Present (possibly null) whenever the caller supplied `diagnostics` on the request." }, { "name": "message.diagnostics.cache_miss_reason", "type": "BetaCacheMissModelChanged or BetaCacheMissSystemChanged or BetaCacheMissToolsChanged or 3 more or null", "required": true, "description": "Explains why the prompt cache could not fully reuse the prefix from the request identified by `diagnostics.previous_message_id`. `null` means diagnosis is still pending — the response was serialized before the background comparison completed." }, { "name": "message.model", "type": "Model", "required": true, "description": "The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options." }, { "name": "message.role", "type": "\"assistant\"", "required": true, "description": "Conversational role of the generated message. This will always be `\"assistant\"`.", "default": "assistant" }, { "name": "message.stop_details", "type": "BetaRefusalStopDetails or null", "required": true, "description": "Structured information about a refusal." }, { "name": "message.stop_details.type", "type": "\"refusal\"", "required": true, "description": "", "default": "refusal" }, { "name": "message.stop_details.category", "type": "\"cyber\" or \"bio\" or \"frontier_llm\" or 2 more or null", "required": true, "description": "The policy category that triggered a refusal.", "enum": [ "cyber", "bio", "frontier_llm", "reasoning_extraction", "general_harms" ] }, { "name": "message.stop_details.explanation", "type": "string or null", "required": true, "description": "Human-readable explanation of the refusal. This text is not guaranteed to be stable. `null` when no explanation is available for the category." }, { "name": "message.stop_details.fallback_credit_token", "type": "string or null", "required": true, "description": "Opaque code that refunds the cache-miss cost when retrying this refused request on the fallback model. Pass it as `fallback_credit_token` on the retry request. Expires 5 minutes after the refusal. The retry is sent either with the same request body (`system`, `messages`, `tools`, and other render-shaping fields), or with the same body plus one appended `assistant` message whose content is the partial text (with any trailing whitespace stripped from the final text block) and paired server-tool blocks from this refusal — which also authorizes that appended turn as an assistant-prefill continuation on models that otherwise disallow prefill. A token minted mid-server-tool-loop whose partial content was continuable may only be redeemed the second way — if a same-body retry is rejected with a 400 saying the token must be redeemed by continuing the partial response, retry the second way instead. Either way: same workspace, same platform; a mismatch is a 400. Resending a token for an already-warm prefix is permitted but yields no additional credit. `null` when the refused model isn't eligible for a fallback credit." }, { "name": "message.stop_details.fallback_has_prefill_claim", "type": "boolean or null", "required": true, "description": "Whether the accompanying `fallback_credit_token` may be redeemed with the appended-assistant retry form. Only set when `fallback_credit_token` is present. `true`: retry by resending the same request body plus one appended `assistant` message whose content is this response's `content` with any trailing whitespace stripped from the final text block and unpaired `tool_use` blocks omitted (the same appended-turn shape described on `fallback_credit_token`), with the token attached. `false`: retry by resending the original request body unchanged, with the token attached — the appended-assistant form is not available for this refusal (no continuable partial content, or the request uses `output_format` or a `tool_choice` that forces tool use). One exception: when the request used `output_format` or a forced `tool_choice` and the refusal arrived after server tools (including MCP connector tools) had already executed, the token may not be redeemable by either retry form; if the exact-body retry is then rejected with a 400 saying the token must be redeemed by continuing the partial response, discard the token and retry without it. Advisory: if an appended-assistant retry is rejected with a 400 despite `true`, fall back to resending the original request body with the token." }, { "name": "message.stop_details.recommended_model", "type": "string or null", "required": true, "description": "The server's suggested retry target for this refusal. Populated when a fallback attempt could not be made (the fallback model's rate limit was exhausted, or it was overloaded); names the fallback model the caller can retry directly. Null otherwise." }, { "name": "message.stop_reason", "type": "BetaStopReason or null", "required": true, "description": "The reason that we stopped. This may be one the following values: * `\"end_turn\"`: the model reached a natural stopping point * `\"max_tokens\"`: we exceeded the requested `max_tokens` or the model's maximum * `\"stop_sequence\"`: one of your provided custom `stop_sequences` was generated * `\"tool_use\"`: the model invoked one or more tools * `\"pause_turn\"`: we paused a long-running turn. You may provide the response back as-is in a subsequent request to let the model continue. * `\"refusal\"`: when streaming classifiers intervene to handle potential policy violations * `\"model_context_window_exceeded\"`: we exceeded the model's context window In non-streaming mode this value is always non-null. In streaming mode, it is null in the `message_start` event and non-null otherwise.", "enum": [ "end_turn", "max_tokens", "stop_sequence", "tool_use", "pause_turn", "compaction", "refusal", "model_context_window_exceeded" ] }, { "name": "message.stop_sequence", "type": "string or null", "required": true, "description": "Which custom stop sequence was generated, if any. This value will be a non-null string if one of your custom stop sequences was generated." }, { "name": "message.usage", "type": "BetaUsage", "required": true, "description": "Billing and rate-limit usage. Anthropic's API bills and rate-limits by token counts, as tokens represent the underlying cost to our systems. Under the hood, the API transforms requests into a format suitable for the model. The model's output then goes through a parsing stage before becoming an API response. As a result, the token counts in `usage` will not match one-to-one with the exact visible content of an API request or response. For example, `output_tokens` will be non-zero, even for an empty string response from Claude. Total input tokens in a request is the summation of `input_tokens`, `cache_creation_input_tokens`, and `cache_read_input_tokens`." }, { "name": "message.usage.cache_creation", "type": "BetaCacheCreation or null", "required": true, "description": "Breakdown of cached tokens by TTL" }, { "name": "message.usage.cache_creation_input_tokens", "type": "number or null", "required": true, "description": "The number of input tokens used to create the cache entry.", "minimum": 0 }, { "name": "message.usage.cache_read_input_tokens", "type": "number or null", "required": true, "description": "The number of input tokens read from the cache.", "minimum": 0 }, { "name": "message.usage.fallback_credit", "type": "BetaFallbackCreditUsage or null", "required": true, "description": "Outcome of the `fallback_credit_token` presented on this request." }, { "name": "message.usage.inference_geo", "type": "string or null", "required": true, "description": "The geographic region where inference was performed for this request." }, { "name": "message.usage.input_tokens", "type": "number", "required": true, "description": "The number of input tokens which were used.", "minimum": 0 }, { "name": "message.usage.iterations", "type": "BetaIterationsUsage or null", "required": true, "description": "Per-iteration token usage breakdown. Each entry represents one sampling iteration, with its own input/output token counts and cache statistics, discriminated by `type`. For `message` entries (model sampling iterations, such as the turns of a server-side tool use loop), this allows you to: - Determine which iterations exceeded long context thresholds (>=200k tokens) - Calculate the context window size from the last `message` entry - Understand token accumulation across server-side tool use loops A `compaction` entry reports the token usage of the compaction operation itself — the server-side request that summarizes the context being closed — NOT the size of the context that was compacted away, and its token counts can be much smaller than that closed context (for example, a compaction that closes a ~200k-token context can report only a few thousand tokens). Do not derive the context window size from a `compaction` entry, even when it is the last entry. A `compaction` entry's tokens are not included in the top-level `usage` fields. When an input-token trigger is in effect (the default — 150,000 tokens unless configured otherwise), each `compaction` entry closes a context that had reached at least that threshold, though the context can exceed it by the final iteration's output and tool results." }, { "name": "message.usage.output_tokens", "type": "number", "required": true, "description": "The number of output tokens which were used.", "minimum": 0 }, { "name": "message.usage.output_tokens_details", "type": "BetaOutputTokensDetails or null", "required": true, "description": "Breakdown of output tokens by category. `output_tokens` remains the inclusive, authoritative total used for billing. This object provides a read-only decomposition for observability — for example, how many of the billed output tokens were spent on internal reasoning that may have been summarized before being returned to you." }, { "name": "message.usage.server_tool_use", "type": "BetaServerToolUsage or null", "required": true, "description": "The number of server tool requests." }, { "name": "message.usage.service_tier", "type": "\"standard\" or \"priority\" or \"batch\" or null", "required": true, "description": "If the request used the priority, standard, or batch tier.", "enum": [ "standard", "priority", "batch" ] }, { "name": "message.usage.speed", "type": "\"standard\" or \"fast\" or null", "required": true, "description": "Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time.", "enum": [ "standard", "fast" ] }, { "name": "message.input_transformations", "type": "array of BetaInputTransformation or null", "required": false, "description": "Changes the API made to the request's input before showing it to the model, and blocks that failed a binding check but were left unchanged: one entry per block, in request order. Two entry types today. `thinking_dropped` — a `thinking`, `redacted_thinking` or `connector_text` block from the request's `messages` that was removed from the prompt instead of being shown to the model because it failed a binding check. `thinking_mismatch_allowed` — a `thinking` or `redacted_thinking` block that failed the conversation check (the conversation before it differs from the one it was created in, or it carries no record of one on a model that requires it) and was shown to the model all the same, because that check is not enforced for this request. More entry types may be added over time; ignore types you do not recognize. Requires `anthropic-beta: thinking-binding-controls-2026-08-01`. Present on every such response from a model that supports extended thinking, as `[]` when there is no entry to report; without the beta, blocks are removed or left in place all the same but nothing is reported. Removed blocks contribute nothing to `usage.input_tokens`; blocks left in place count as sent. When streaming, the array is final in `message_start`; the final `message_delta` event carries it only when a server-side model fallback happened mid-stream, in which case it holds the serving model's entries and replaces the one in `message_start`." }, { "name": "type", "type": "\"errored\"", "required": true, "description": "", "default": "errored" }, { "name": "error", "type": "BetaErrorResponse", "required": true, "description": "" }, { "name": "error.type", "type": "\"error\"", "required": true, "description": "", "default": "error" }, { "name": "error.error", "type": "BetaError", "required": true, "description": "" }, { "name": "error.request_id", "type": "string or null", "required": true, "description": "" }, { "name": "type", "type": "\"canceled\"", "required": true, "description": "", "default": "canceled" }, { "name": "type", "type": "\"expired\"", "required": true, "description": "", "default": "expired" } ], "status": [ "DOCUMENTED" ], "sources": [ { "url": "https://platform.claude.com/docs/en/api/beta/messages/batches", "retrieved_at": "2026-09-18" } ], "union_of": "BetaMessageBatchSucceededResult or BetaMessageBatchErroredResult or BetaMessageBatchCanceledResult or BetaMessageBatchExpiredResult", "_fragment": "generated/fragments/objects/anthropic-platform-objects.json" }, { "provider": "anthropic", "api_family": "messages-batches", "name": "Beta Message Batch Succeeded Result", "official_type_name": "BetaMessageBatchSucceededResult", "description": "", "fields": [ { "name": "type", "type": "\"succeeded\"", "required": true, "description": "", "default": "succeeded" }, { "name": "message", "type": "BetaMessage", "required": true, "description": "" }, { "name": "message.type", "type": "\"message\"", "required": true, "description": "Object type. For Messages, this is always `\"message\"`.", "default": "message" }, { "name": "message.id", "type": "string", "required": true, "description": "Unique object identifier. The format and length of IDs may change over time." }, { "name": "message.container", "type": "BetaContainer or null", "required": true, "description": "Information about the container used in the request (for the code execution tool)" }, { "name": "message.container.id", "type": "string", "required": true, "description": "Identifier for the container used in this request" }, { "name": "message.container.expires_at", "type": "string", "required": true, "description": "The time at which the container will expire.", "constraints": { "format": "date-time" } }, { "name": "message.container.skills", "type": "array of BetaContainerSkill or null", "required": true, "description": "Skills loaded in the container" }, { "name": "message.content", "type": "array of BetaContentBlock", "required": true, "description": "Content generated by the model. This is an array of content blocks, each of which has a `type` that determines its shape. Example: ```json [{\"type\": \"text\", \"text\": \"Hi, I'm Claude.\"}] ``` If the request input `messages` ended with an `assistant` turn, then the response `content` will continue directly from that last turn. You can use this to constrain the model's output. For example, if the input `messages` were: ```json [ {\"role\": \"user\", \"content\": \"What's the Greek name for Sun? (A) Sol (B) Helios (C) Sun\"}, {\"role\": \"assistant\", \"content\": \"The best answer is (\"} ] ``` Then the response `content` might be: ```json [{\"type\": \"text\", \"text\": \"B)\"}] ```" }, { "name": "message.context_management", "type": "BetaContextManagementResponse or null", "required": true, "description": "Context management response. Information about context management strategies applied during the request." }, { "name": "message.context_management.applied_edits", "type": "array of BetaClearToolUses20250919EditResponse or BetaClearThinking20251015EditResponse", "required": true, "description": "List of context management edits that were applied." }, { "name": "message.diagnostics", "type": "BetaDiagnostics or null", "required": true, "description": "Response envelope for request-level diagnostics. Present (possibly null) whenever the caller supplied `diagnostics` on the request." }, { "name": "message.diagnostics.cache_miss_reason", "type": "BetaCacheMissModelChanged or BetaCacheMissSystemChanged or BetaCacheMissToolsChanged or 3 more or null", "required": true, "description": "Explains why the prompt cache could not fully reuse the prefix from the request identified by `diagnostics.previous_message_id`. `null` means diagnosis is still pending — the response was serialized before the background comparison completed." }, { "name": "message.model", "type": "Model", "required": true, "description": "The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options." }, { "name": "message.role", "type": "\"assistant\"", "required": true, "description": "Conversational role of the generated message. This will always be `\"assistant\"`.", "default": "assistant" }, { "name": "message.stop_details", "type": "BetaRefusalStopDetails or null", "required": true, "description": "Structured information about a refusal." }, { "name": "message.stop_details.type", "type": "\"refusal\"", "required": true, "description": "", "default": "refusal" }, { "name": "message.stop_details.category", "type": "\"cyber\" or \"bio\" or \"frontier_llm\" or 2 more or null", "required": true, "description": "The policy category that triggered a refusal.", "enum": [ "cyber", "bio", "frontier_llm", "reasoning_extraction", "general_harms" ] }, { "name": "message.stop_details.explanation", "type": "string or null", "required": true, "description": "Human-readable explanation of the refusal. This text is not guaranteed to be stable. `null` when no explanation is available for the category." }, { "name": "message.stop_details.fallback_credit_token", "type": "string or null", "required": true, "description": "Opaque code that refunds the cache-miss cost when retrying this refused request on the fallback model. Pass it as `fallback_credit_token` on the retry request. Expires 5 minutes after the refusal. The retry is sent either with the same request body (`system`, `messages`, `tools`, and other render-shaping fields), or with the same body plus one appended `assistant` message whose content is the partial text (with any trailing whitespace stripped from the final text block) and paired server-tool blocks from this refusal — which also authorizes that appended turn as an assistant-prefill continuation on models that otherwise disallow prefill. A token minted mid-server-tool-loop whose partial content was continuable may only be redeemed the second way — if a same-body retry is rejected with a 400 saying the token must be redeemed by continuing the partial response, retry the second way instead. Either way: same workspace, same platform; a mismatch is a 400. Resending a token for an already-warm prefix is permitted but yields no additional credit. `null` when the refused model isn't eligible for a fallback credit." }, { "name": "message.stop_details.fallback_has_prefill_claim", "type": "boolean or null", "required": true, "description": "Whether the accompanying `fallback_credit_token` may be redeemed with the appended-assistant retry form. Only set when `fallback_credit_token` is present. `true`: retry by resending the same request body plus one appended `assistant` message whose content is this response's `content` with any trailing whitespace stripped from the final text block and unpaired `tool_use` blocks omitted (the same appended-turn shape described on `fallback_credit_token`), with the token attached. `false`: retry by resending the original request body unchanged, with the token attached — the appended-assistant form is not available for this refusal (no continuable partial content, or the request uses `output_format` or a `tool_choice` that forces tool use). One exception: when the request used `output_format` or a forced `tool_choice` and the refusal arrived after server tools (including MCP connector tools) had already executed, the token may not be redeemable by either retry form; if the exact-body retry is then rejected with a 400 saying the token must be redeemed by continuing the partial response, discard the token and retry without it. Advisory: if an appended-assistant retry is rejected with a 400 despite `true`, fall back to resending the original request body with the token." }, { "name": "message.stop_details.recommended_model", "type": "string or null", "required": true, "description": "The server's suggested retry target for this refusal. Populated when a fallback attempt could not be made (the fallback model's rate limit was exhausted, or it was overloaded); names the fallback model the caller can retry directly. Null otherwise." }, { "name": "message.stop_reason", "type": "BetaStopReason or null", "required": true, "description": "The reason that we stopped. This may be one the following values: * `\"end_turn\"`: the model reached a natural stopping point * `\"max_tokens\"`: we exceeded the requested `max_tokens` or the model's maximum * `\"stop_sequence\"`: one of your provided custom `stop_sequences` was generated * `\"tool_use\"`: the model invoked one or more tools * `\"pause_turn\"`: we paused a long-running turn. You may provide the response back as-is in a subsequent request to let the model continue. * `\"refusal\"`: when streaming classifiers intervene to handle potential policy violations * `\"model_context_window_exceeded\"`: we exceeded the model's context window In non-streaming mode this value is always non-null. In streaming mode, it is null in the `message_start` event and non-null otherwise.", "enum": [ "end_turn", "max_tokens", "stop_sequence", "tool_use", "pause_turn", "compaction", "refusal", "model_context_window_exceeded" ] }, { "name": "message.stop_sequence", "type": "string or null", "required": true, "description": "Which custom stop sequence was generated, if any. This value will be a non-null string if one of your custom stop sequences was generated." }, { "name": "message.usage", "type": "BetaUsage", "required": true, "description": "Billing and rate-limit usage. Anthropic's API bills and rate-limits by token counts, as tokens represent the underlying cost to our systems. Under the hood, the API transforms requests into a format suitable for the model. The model's output then goes through a parsing stage before becoming an API response. As a result, the token counts in `usage` will not match one-to-one with the exact visible content of an API request or response. For example, `output_tokens` will be non-zero, even for an empty string response from Claude. Total input tokens in a request is the summation of `input_tokens`, `cache_creation_input_tokens`, and `cache_read_input_tokens`." }, { "name": "message.usage.cache_creation", "type": "BetaCacheCreation or null", "required": true, "description": "Breakdown of cached tokens by TTL" }, { "name": "message.usage.cache_creation_input_tokens", "type": "number or null", "required": true, "description": "The number of input tokens used to create the cache entry.", "minimum": 0 }, { "name": "message.usage.cache_read_input_tokens", "type": "number or null", "required": true, "description": "The number of input tokens read from the cache.", "minimum": 0 }, { "name": "message.usage.fallback_credit", "type": "BetaFallbackCreditUsage or null", "required": true, "description": "Outcome of the `fallback_credit_token` presented on this request." }, { "name": "message.usage.inference_geo", "type": "string or null", "required": true, "description": "The geographic region where inference was performed for this request." }, { "name": "message.usage.input_tokens", "type": "number", "required": true, "description": "The number of input tokens which were used.", "minimum": 0 }, { "name": "message.usage.iterations", "type": "BetaIterationsUsage or null", "required": true, "description": "Per-iteration token usage breakdown. Each entry represents one sampling iteration, with its own input/output token counts and cache statistics, discriminated by `type`. For `message` entries (model sampling iterations, such as the turns of a server-side tool use loop), this allows you to: - Determine which iterations exceeded long context thresholds (>=200k tokens) - Calculate the context window size from the last `message` entry - Understand token accumulation across server-side tool use loops A `compaction` entry reports the token usage of the compaction operation itself — the server-side request that summarizes the context being closed — NOT the size of the context that was compacted away, and its token counts can be much smaller than that closed context (for example, a compaction that closes a ~200k-token context can report only a few thousand tokens). Do not derive the context window size from a `compaction` entry, even when it is the last entry. A `compaction` entry's tokens are not included in the top-level `usage` fields. When an input-token trigger is in effect (the default — 150,000 tokens unless configured otherwise), each `compaction` entry closes a context that had reached at least that threshold, though the context can exceed it by the final iteration's output and tool results." }, { "name": "message.usage.output_tokens", "type": "number", "required": true, "description": "The number of output tokens which were used.", "minimum": 0 }, { "name": "message.usage.output_tokens_details", "type": "BetaOutputTokensDetails or null", "required": true, "description": "Breakdown of output tokens by category. `output_tokens` remains the inclusive, authoritative total used for billing. This object provides a read-only decomposition for observability — for example, how many of the billed output tokens were spent on internal reasoning that may have been summarized before being returned to you." }, { "name": "message.usage.server_tool_use", "type": "BetaServerToolUsage or null", "required": true, "description": "The number of server tool requests." }, { "name": "message.usage.service_tier", "type": "\"standard\" or \"priority\" or \"batch\" or null", "required": true, "description": "If the request used the priority, standard, or batch tier.", "enum": [ "standard", "priority", "batch" ] }, { "name": "message.usage.speed", "type": "\"standard\" or \"fast\" or null", "required": true, "description": "Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time.", "enum": [ "standard", "fast" ] }, { "name": "message.input_transformations", "type": "array of BetaInputTransformation or null", "required": false, "description": "Changes the API made to the request's input before showing it to the model, and blocks that failed a binding check but were left unchanged: one entry per block, in request order. Two entry types today. `thinking_dropped` — a `thinking`, `redacted_thinking` or `connector_text` block from the request's `messages` that was removed from the prompt instead of being shown to the model because it failed a binding check. `thinking_mismatch_allowed` — a `thinking` or `redacted_thinking` block that failed the conversation check (the conversation before it differs from the one it was created in, or it carries no record of one on a model that requires it) and was shown to the model all the same, because that check is not enforced for this request. More entry types may be added over time; ignore types you do not recognize. Requires `anthropic-beta: thinking-binding-controls-2026-08-01`. Present on every such response from a model that supports extended thinking, as `[]` when there is no entry to report; without the beta, blocks are removed or left in place all the same but nothing is reported. Removed blocks contribute nothing to `usage.input_tokens`; blocks left in place count as sent. When streaming, the array is final in `message_start`; the final `message_delta` event carries it only when a server-side model fallback happened mid-stream, in which case it holds the serving model's entries and replaces the one in `message_start`." } ], "status": [ "DOCUMENTED" ], "sources": [ { "url": "https://platform.claude.com/docs/en/api/beta/messages/batches", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/anthropic-platform-objects.json" }, { "provider": "anthropic", "api_family": "skills", "name": "Beta Skill Source", "official_type_name": "BetaSkillSource", "description": "", "fields": [ { "name": "type", "type": "\"custom\" or \"anthropic\" or \"anthropic_example\" or \"plugin\"", "required": true, "description": "Where the Skill comes from. Possible values: * `\"custom\"`: authored by the platform user; private to their workspace * `\"anthropic\"`: published by Anthropic; shared and read-only * `\"anthropic_example\"`: Anthropic-published sample Skill * `\"plugin\"`: resolved from an installed plugin", "enum": [ "custom", "anthropic", "anthropic_example", "plugin" ] } ], "status": [ "DOCUMENTED" ], "sources": [ { "url": "https://platform.claude.com/docs/en/api/beta/skills", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/anthropic-platform-objects.json" }, { "provider": "anthropic", "api_family": "admin", "name": "Beta Organization Role", "official_type_name": "BetaOrganizationRole", "description": "", "fields": [], "status": [ "DOCUMENTED" ], "sources": [ { "url": "https://platform.claude.com/docs/en/api/beta/organization", "retrieved_at": "2026-09-18" } ], "enum": [ "admin", "billing", "claude_code_user", "developer", "managed", "membership_admin", "owner", "primary_owner", "user" ], "union_of": "\"admin\" or \"billing\" or \"claude_code_user\" or 6 more", "_fragment": "generated/fragments/objects/anthropic-platform-objects.json" }, { "provider": "anthropic", "api_family": "admin", "name": "User Remove Response", "official_type_name": "UserRemoveResponse", "description": "", "fields": [ { "name": "type", "type": "\"user_deleted\"", "required": true, "description": "Deleted object type. For Users, this is always `\"user_deleted\"`.", "default": "user_deleted" }, { "name": "id", "type": "string", "required": true, "description": "ID of the User." } ], "status": [ "DOCUMENTED" ], "sources": [ { "url": "https://platform.claude.com/docs/en/api/beta/organization/users", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/anthropic-platform-objects.json" }, { "provider": "anthropic", "api_family": "admin", "name": "Invite Delete Response", "official_type_name": "InviteDeleteResponse", "description": "", "fields": [ { "name": "type", "type": "\"invite_deleted\"", "required": true, "description": "Deleted object type. For Invites, this is always `\"invite_deleted\"`.", "default": "invite_deleted" }, { "name": "id", "type": "string", "required": true, "description": "ID of the Invite." } ], "status": [ "DOCUMENTED" ], "sources": [ { "url": "https://platform.claude.com/docs/en/api/beta/organization/invites", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/anthropic-platform-objects.json" }, { "provider": "anthropic", "api_family": "admin", "name": "Beta Allowed Inference Geo", "official_type_name": "BetaAllowedInferenceGeo", "description": "", "fields": [], "status": [ "DOCUMENTED" ], "sources": [ { "url": "https://platform.claude.com/docs/en/api/beta/organization/workspaces", "retrieved_at": "2026-09-18" } ], "enum": [ "global", "us" ], "union_of": "\"global\" or \"us\"", "_fragment": "generated/fragments/objects/anthropic-platform-objects.json" }, { "provider": "anthropic", "api_family": "admin", "name": "Beta Data Residency", "official_type_name": "BetaDataResidency", "description": "", "fields": [ { "name": "allowed_inference_geos", "type": "array of BetaAllowedInferenceGeo or \"unrestricted\"", "required": true, "description": "Permitted inference geo values. 'unrestricted' means all geos are allowed." }, { "name": "default_inference_geo", "type": "\"global\" or \"us\"", "required": true, "description": "Default inference geo applied when requests omit the parameter.", "enum": [ "global", "us" ] }, { "name": "workspace_geo", "type": "\"us\"", "required": true, "description": "Geographic region for workspace data storage. Immutable after creation." } ], "status": [ "DOCUMENTED" ], "sources": [ { "url": "https://platform.claude.com/docs/en/api/beta/organization/workspaces", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/anthropic-platform-objects.json" }, { "provider": "anthropic", "api_family": "admin", "name": "Beta Data Residency Create Config", "official_type_name": "BetaDataResidencyCreateConfig", "description": "", "fields": [ { "name": "allowed_inference_geos", "type": "array of BetaAllowedInferenceGeo or \"unrestricted\" or null", "required": false, "description": "Permitted inference geo values. Defaults to 'unrestricted' if omitted, which allows all geos. Use the string 'unrestricted' to allow all geos, or a list of specific geos." }, { "name": "default_inference_geo", "type": "\"global\" or \"us\" or null", "required": false, "description": "Default inference geo applied when requests omit the parameter. Defaults to 'global' if omitted. Must be a member of `allowed_inference_geos` unless `allowed_inference_geos` is `\"unrestricted\"`.", "enum": [ "global", "us" ] }, { "name": "workspace_geo", "type": "\"us\" or null", "required": false, "description": "Geographic region for workspace data storage. Immutable after creation. Defaults to 'us' if omitted." } ], "status": [ "DOCUMENTED" ], "sources": [ { "url": "https://platform.claude.com/docs/en/api/beta/organization/workspaces", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/anthropic-platform-objects.json" }, { "provider": "anthropic", "api_family": "admin", "name": "Beta Data Residency Update Config", "official_type_name": "BetaDataResidencyUpdateConfig", "description": "", "fields": [ { "name": "allowed_inference_geos", "type": "array of BetaAllowedInferenceGeo or \"unrestricted\" or null", "required": false, "description": "Permitted inference geo values. Use 'unrestricted' to allow all geos, or a list of specific geos." }, { "name": "default_inference_geo", "type": "\"global\" or \"us\" or null", "required": false, "description": "Default inference geo applied when requests omit the parameter. Must be a member of `allowed_inference_geos` unless `allowed_inference_geos` is `\"unrestricted\"`.", "enum": [ "global", "us" ] } ], "status": [ "DOCUMENTED" ], "sources": [ { "url": "https://platform.claude.com/docs/en/api/beta/organization/workspaces", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/anthropic-platform-objects.json" }, { "provider": "anthropic", "api_family": "admin", "name": "Beta No Billing Workspace Role", "official_type_name": "BetaNoBillingWorkspaceRole", "description": "", "fields": [], "status": [ "DOCUMENTED" ], "sources": [ { "url": "https://platform.claude.com/docs/en/api/beta/organization/workspaces", "retrieved_at": "2026-09-18" } ], "enum": [ "workspace_admin", "workspace_developer", "workspace_restricted_developer", "workspace_user" ], "union_of": "\"workspace_admin\" or \"workspace_developer\" or \"workspace_restricted_developer\" or \"workspace_user\"", "_fragment": "generated/fragments/objects/anthropic-platform-objects.json" }, { "provider": "anthropic", "api_family": "admin", "name": "Beta Workspace Role", "official_type_name": "BetaWorkspaceRole", "description": "", "fields": [], "status": [ "DOCUMENTED" ], "sources": [ { "url": "https://platform.claude.com/docs/en/api/beta/organization/workspaces", "retrieved_at": "2026-09-18" } ], "enum": [ "workspace_admin", "workspace_billing", "workspace_developer", "workspace_restricted_developer", "workspace_user" ], "union_of": "\"workspace_admin\" or \"workspace_billing\" or \"workspace_developer\" or 2 more", "_fragment": "generated/fragments/objects/anthropic-platform-objects.json" }, { "provider": "anthropic", "api_family": "admin", "name": "Beta API Key Created By", "official_type_name": "BetaAPIKeyCreatedBy", "description": "", "fields": [ { "name": "type", "type": "\"service_account\" or \"user\"", "required": true, "description": "Type of the actor that created the object.", "enum": [ "service_account", "user" ] }, { "name": "id", "type": "string", "required": true, "description": "ID of the actor that created the object." } ], "status": [ "DOCUMENTED" ], "sources": [ { "url": "https://platform.claude.com/docs/en/api/beta/organization/api_keys", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/anthropic-platform-objects.json" }, { "provider": "anthropic", "api_family": "admin", "name": "Beta API Key Organization Scope", "official_type_name": "BetaAPIKeyOrganizationScope", "description": "", "fields": [ { "name": "type", "type": "\"organization\"", "required": true, "description": "Scope type. Always `\"organization\"`: the API key has no Workspace. Only a principal-bound API key can have this scope.", "default": "organization" } ], "status": [ "DOCUMENTED" ], "sources": [ { "url": "https://platform.claude.com/docs/en/api/beta/organization/api_keys", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/anthropic-platform-objects.json" }, { "provider": "anthropic", "api_family": "admin", "name": "Beta API Key Service Account Actor", "official_type_name": "BetaAPIKeyServiceAccountActor", "description": "", "fields": [ { "name": "type", "type": "\"service_account_actor\"", "required": true, "description": "Principal type. Always `\"service_account_actor\"` for a Service Account.", "default": "service_account_actor" }, { "name": "service_account_id", "type": "string", "required": true, "description": "ID of the Service Account the API key acts as." } ], "status": [ "DOCUMENTED" ], "sources": [ { "url": "https://platform.claude.com/docs/en/api/beta/organization/api_keys", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/anthropic-platform-objects.json" }, { "provider": "anthropic", "api_family": "admin", "name": "Beta API Key User Actor", "official_type_name": "BetaAPIKeyUserActor", "description": "", "fields": [ { "name": "type", "type": "\"user_actor\"", "required": true, "description": "Principal type. Always `\"user_actor\"` for a User.", "default": "user_actor" }, { "name": "user_id", "type": "string", "required": true, "description": "ID of the User the API key acts as." } ], "status": [ "DOCUMENTED" ], "sources": [ { "url": "https://platform.claude.com/docs/en/api/beta/organization/api_keys", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/anthropic-platform-objects.json" }, { "provider": "anthropic", "api_family": "admin", "name": "Beta API Key Workspace Scope", "official_type_name": "BetaAPIKeyWorkspaceScope", "description": "", "fields": [ { "name": "type", "type": "\"workspace\"", "required": true, "description": "Scope type. Always `\"workspace\"`: the API key belongs to one Workspace.", "default": "workspace" }, { "name": "workspace_id", "type": "string", "required": true, "description": "ID of the Workspace the API key belongs to. Unlike the deprecated top-level `workspace_id`, this is the Workspace's real ID even for the organization's default Workspace." } ], "status": [ "DOCUMENTED" ], "sources": [ { "url": "https://platform.claude.com/docs/en/api/beta/organization/api_keys", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/anthropic-platform-objects.json" }, { "provider": "anthropic", "api_family": "admin", "name": "Beta Spend Summary", "official_type_name": "BetaSpendSummary", "description": "Per-member effective-limit report row (`GET /spend_limits/effective`).", "fields": [ { "name": "actor", "type": "UserActor or ScopedAPIKeyActor", "required": true, "description": "" }, { "name": "actor.type", "type": "\"user_actor\"", "required": true, "description": "Actor type. Always `user_actor`.", "default": "user_actor" }, { "name": "actor.deleted", "type": "boolean", "required": true, "description": "True only when the underlying account has been deleted.", "default": "false" }, { "name": "actor.email_address", "type": "string or null", "required": true, "description": "The user's email address. Null when the account is unavailable or has been deleted." }, { "name": "actor.name", "type": "string or null", "required": true, "description": "The user's current display name. Null when the account is unavailable, has been deleted, or has no name set." }, { "name": "actor.user_id", "type": "string", "required": true, "description": "Tagged ID of the user." }, { "name": "actor.type", "type": "\"scoped_api_key_actor\"", "required": true, "description": "", "default": "scoped_api_key_actor" }, { "name": "actor.scoped_api_key_id", "type": "string", "required": true, "description": "" }, { "name": "amount", "type": "string or null", "required": true, "description": "Effective limit amount as a non-negative integer decimal string in the minor unit of `currency` (cents for USD). `null` means no limit applies for this row's `period` — each period resolves independently, so another period may still cap this member." }, { "name": "currency", "type": "string", "required": true, "description": "ISO 4217 code of the organization's billing currency; the unit for `amount` and `period_to_date_spend`." }, { "name": "period", "type": "\"daily\" or \"monthly\" or \"weekly\"", "required": true, "description": "Period this row's effective limit and spend are reported for.", "enum": [ "daily", "monthly", "weekly" ] }, { "name": "period_to_date_spend", "type": "string", "required": true, "description": "The member's spend so far in the current period, as a non-negative decimal string in the minor unit of `currency` (cents for USD). May carry fractional minor units up to three decimal places (e.g. `\"12050.5\"`) — metered usage is not rounded to whole cents. Reads as `\"0\"` when the spend reading is temporarily unavailable." }, { "name": "scope", "type": "User or SeatTier or RBACGroup or 3 more", "required": true, "description": "" }, { "name": "scope.type", "type": "\"user\"", "required": true, "description": "Scope type. Always `user` for this scope.", "default": "user" }, { "name": "scope.user_id", "type": "string", "required": true, "description": "Tagged ID of the member the spend limit applies to." }, { "name": "scope.type", "type": "\"seat_tier\"", "required": true, "description": "", "default": "seat_tier" }, { "name": "scope.seat_tier", "type": "string", "required": true, "description": "" }, { "name": "scope.type", "type": "\"rbac_group\"", "required": true, "description": "", "default": "rbac_group" }, { "name": "scope.rbac_group_id", "type": "string", "required": true, "description": "" }, { "name": "scope.type", "type": "\"organization_service\"", "required": true, "description": "", "default": "organization_service" }, { "name": "scope.service", "type": "string", "required": true, "description": "" }, { "name": "scope.type", "type": "\"organization\"", "required": true, "description": "", "default": "organization" }, { "name": "scope.type", "type": "\"workspace\"", "required": true, "description": "Scope type. Always `workspace` for this scope.", "default": "workspace" }, { "name": "scope.workspace_id", "type": "string", "required": true, "description": "Tagged ID of the workspace the spend limit applies to." }, { "name": "source", "type": "User or SeatTier or RBACGroup or 3 more", "required": true, "description": "" }, { "name": "source.type", "type": "\"user\"", "required": true, "description": "Scope type. Always `user` for this scope.", "default": "user" }, { "name": "source.user_id", "type": "string", "required": true, "description": "Tagged ID of the member the spend limit applies to." }, { "name": "source.type", "type": "\"seat_tier\"", "required": true, "description": "", "default": "seat_tier" }, { "name": "source.seat_tier", "type": "string", "required": true, "description": "" }, { "name": "source.type", "type": "\"rbac_group\"", "required": true, "description": "", "default": "rbac_group" }, { "name": "source.rbac_group_id", "type": "string", "required": true, "description": "" }, { "name": "source.type", "type": "\"organization_service\"", "required": true, "description": "", "default": "organization_service" }, { "name": "source.service", "type": "string", "required": true, "description": "" }, { "name": "source.type", "type": "\"organization\"", "required": true, "description": "", "default": "organization" }, { "name": "source.type", "type": "\"workspace\"", "required": true, "description": "Scope type. Always `workspace` for this scope.", "default": "workspace" }, { "name": "source.workspace_id", "type": "string", "required": true, "description": "Tagged ID of the workspace the spend limit applies to." }, { "name": "spend_limit_id", "type": "string", "required": true, "description": "" } ], "status": [ "DOCUMENTED" ], "sources": [ { "url": "https://platform.claude.com/docs/en/api/beta/organization/spend_limits", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/anthropic-platform-objects.json" }, { "provider": "anthropic", "api_family": "admin", "name": "Spend Limit Delete Response", "official_type_name": "SpendLimitDeleteResponse", "description": "", "fields": [ { "name": "type", "type": "\"spend_limit_deleted\"", "required": true, "description": "", "default": "spend_limit_deleted" }, { "name": "id", "type": "string", "required": true, "description": "" } ], "status": [ "DOCUMENTED" ], "sources": [ { "url": "https://platform.claude.com/docs/en/api/beta/organization/spend_limits", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/anthropic-platform-objects.json" }, { "provider": "anthropic", "api_family": "admin", "name": "Beta Organization Rate Limit", "official_type_name": "BetaOrganizationRateLimit", "description": "", "fields": [ { "name": "type", "type": "\"rate_limit\"", "required": true, "description": "Object type. Always `rate_limit` for organization rate-limit entries.", "default": "rate_limit" }, { "name": "id", "type": "string", "required": true, "description": "Stable identifier for this rate-limit group within the organization." }, { "name": "group_type", "type": "\"batch\" or \"files\" or \"model_group\" or 3 more", "required": true, "description": "The kind of rate-limit group this entry represents. `model_group` entries apply to a family of models (listed in `models`); other values apply to an API-surface category and have `models` set to `null`.", "enum": [ "batch", "files", "model_group", "skills", "token_count", "web_search" ] }, { "name": "limits", "type": "array of BetaOrganizationRateLimitValue", "required": true, "description": "The limiter values that apply to this group." }, { "name": "limits[].type", "type": "string", "required": true, "description": "The limiter type (for example, `requests_per_minute` or `input_tokens_per_minute`)." }, { "name": "limits[].value", "type": "number", "required": true, "description": "The configured limit value for this limiter type." }, { "name": "models", "type": "array of string or null", "required": true, "description": "Model names this entry's limits apply to, including aliases. `null` when `group_type` is not `\"model_group\"`." } ], "status": [ "DOCUMENTED" ], "sources": [ { "url": "https://platform.claude.com/docs/en/api/beta/organization/rate_limits", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/anthropic-platform-objects.json" }, { "provider": "anthropic", "api_family": "admin", "name": "Beta Organization Rate Limit Value", "official_type_name": "BetaOrganizationRateLimitValue", "description": "", "fields": [ { "name": "type", "type": "string", "required": true, "description": "The limiter type (for example, `requests_per_minute` or `input_tokens_per_minute`)." }, { "name": "value", "type": "number", "required": true, "description": "The configured limit value for this limiter type." } ], "status": [ "DOCUMENTED" ], "sources": [ { "url": "https://platform.claude.com/docs/en/api/beta/organization/rate_limits", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/anthropic-platform-objects.json" }, { "provider": "anthropic", "api_family": "admin", "name": "Beta Analytics User", "official_type_name": "BetaAnalyticsUser", "description": "A user in the organization, identified by tagged id and email address.", "fields": [ { "name": "type", "type": "\"user\"", "required": true, "description": "Object type. Always `user`.", "default": "user" }, { "name": "id", "type": "string", "required": true, "description": "Tagged user identifier (e.g. `user_...`)" }, { "name": "email_address", "type": "string", "required": true, "description": "Email address of the user" } ], "status": [ "DOCUMENTED" ], "sources": [ { "url": "https://platform.claude.com/docs/en/api/beta/organization/analytics", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/anthropic-platform-objects.json" }, { "provider": "anthropic", "api_family": "admin", "name": "Beta Analytics User Actor", "official_type_name": "BetaAnalyticsUserActor", "description": "", "fields": [ { "name": "type", "type": "\"user_actor\"", "required": true, "description": "Actor type. Always `\"user_actor\"`." }, { "name": "deleted", "type": "boolean", "required": true, "description": "True when the account has been deleted, or when the user is no longer a member of the organization or its associated organizations (for example, their membership was removed or they were deprovisioned via your identity provider). `email` stays populated for removed users and is null when the account has been deleted. `name` follows the rules described on that field. The `user_id` is still populated for reconciliation." }, { "name": "email", "type": "string or null", "required": true, "description": "The user's email address, including for users who are no longer members of the organization or its associated organizations. Null when the account has been deleted (check `deleted`) and for system-minted service accounts, which have no person's mailbox behind them (check `name`)." }, { "name": "name", "type": "string or null", "required": true, "description": "The user's full name. Null when the user has not set a name. Returns `\"Deleted User\"` when the account itself has been deleted, or when the user is no longer a member of the organization or its associated organizations and the organization has chosen to hide the names of removed users. Otherwise, the name stays populated for removed users. Rows for system-minted service accounts render the service name (for example, `\"Claude Security\"` for usage by Anthropic's security-patching service) or null." }, { "name": "user_id", "type": "string", "required": true, "description": "Tagged user ID." } ], "status": [ "DOCUMENTED" ], "sources": [ { "url": "https://platform.claude.com/docs/en/api/beta/organization/analytics", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/anthropic-platform-objects.json" }, { "provider": "anthropic", "api_family": "admin", "name": "Beta Connector Office Product Metrics", "official_type_name": "BetaConnectorOfficeProductMetrics", "description": "Office Agent activity metrics for a single connector on a given day within one Office product.", "fields": [ { "name": "distinct_session_connector_used_count", "type": "number or null", "required": true, "description": "Number of distinct Office Agent sessions in which the connector was used. Approximate (HLL, typical error <2%) in date-range mode. Null on aggregated rows where a distinct count cannot be computed." } ], "status": [ "DOCUMENTED" ], "sources": [ { "url": "https://platform.claude.com/docs/en/api/beta/organization/analytics", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/anthropic-platform-objects.json" }, { "provider": "anthropic", "api_family": "admin", "name": "Beta Office Product Metrics", "official_type_name": "BetaOfficeProductMetrics", "description": "Office Agent activity metrics for a single user on a given day within one Office product.", "fields": [ { "name": "connectors_used_count", "type": "number", "required": true, "description": "Number of MCP connector invocations" }, { "name": "distinct_connectors_used_count", "type": "number or null", "required": true, "description": "Number of distinct MCP connectors used. Approximate (HLL, typical error <2%) in date-range mode. Null on aggregated rows where a distinct count cannot be computed." }, { "name": "distinct_session_count", "type": "number or null", "required": true, "description": "Number of distinct Office Agent sessions. Approximate (HLL, typical error <2%) in date-range mode. Null on aggregated rows where a distinct count cannot be computed." }, { "name": "distinct_skills_used_count", "type": "number or null", "required": true, "description": "Number of distinct skills used. Approximate (HLL, typical error <2%) in date-range mode. Null on aggregated rows where a distinct count cannot be computed." }, { "name": "message_count", "type": "number", "required": true, "description": "Number of messages sent" }, { "name": "skills_used_count", "type": "number", "required": true, "description": "Number of skill invocations" } ], "status": [ "DOCUMENTED" ], "sources": [ { "url": "https://platform.claude.com/docs/en/api/beta/organization/analytics", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/anthropic-platform-objects.json" }, { "provider": "anthropic", "api_family": "admin", "name": "Beta Skill Office Product Metrics", "official_type_name": "BetaSkillOfficeProductMetrics", "description": "Office Agent activity metrics for a single skill on a given day within one Office product.", "fields": [ { "name": "distinct_session_skill_used_count", "type": "number or null", "required": true, "description": "Number of distinct Office Agent sessions in which the skill was used. A skill counts as used only when it is explicitly activated — the model (or the user, via the skill's slash command) invokes it, reading its instructions into context as part of that activation. Skills that are merely installed or listed as available, or whose content reaches the context without an activation (preloaded, hook-injected, or read as a plain file), are not counted. Approximate (HLL, typical error <2%) in date-range mode. Null on aggregated rows where a distinct count cannot be computed." } ], "status": [ "DOCUMENTED" ], "sources": [ { "url": "https://platform.claude.com/docs/en/api/beta/organization/analytics", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/anthropic-platform-objects.json" }, { "provider": "anthropic", "api_family": "admin", "name": "Beta Tool Action Counts", "official_type_name": "BetaToolActionCounts", "description": "Accepted/rejected counts for a single Claude Code tool type.", "fields": [ { "name": "accepted_count", "type": "number", "required": true, "description": "Number of tool proposals accepted" }, { "name": "rejected_count", "type": "number", "required": true, "description": "Number of tool proposals rejected" } ], "status": [ "DOCUMENTED" ], "sources": [ { "url": "https://platform.claude.com/docs/en/api/beta/organization/analytics", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/anthropic-platform-objects.json" }, { "provider": "anthropic", "api_family": "admin", "name": "Beta AWS External Key Config", "official_type_name": "BetaAWSExternalKeyConfig", "description": "", "fields": [ { "name": "type", "type": "\"aws\"", "required": true, "description": "" }, { "name": "kms_arn", "type": "string", "required": true, "description": "Full ARN of the AWS KMS key. On Claude Platform on AWS the key must be a single-Region key in your organization's own AWS account; cross-account keys, multi-Region keys, and alias ARNs are rejected.", "constraints": { "maxLength": "2048" } }, { "name": "region", "type": "string or null", "required": false, "description": "AWS region. Derived from `kms_arn` if omitted." }, { "name": "role_arn", "type": "string or null", "required": false, "description": "**Deprecated** IAM role ARN. Deprecated — Anthropic reaches the KMS key through its own intermediate role (or, on Claude Platform on AWS, with credentials AWS issues for the Workspace); this field is ignored." } ], "status": [ "DOCUMENTED" ], "sources": [ { "url": "https://platform.claude.com/docs/en/api/beta/organization/external_keys", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/anthropic-platform-objects.json" }, { "provider": "anthropic", "api_family": "admin", "name": "Beta Azure External Key Config", "official_type_name": "BetaAzureExternalKeyConfig", "description": "", "fields": [ { "name": "type", "type": "\"azure\"", "required": true, "description": "" }, { "name": "key_name", "type": "string", "required": true, "description": "Name of the key within the vault." }, { "name": "tenant_id", "type": "string", "required": true, "description": "Azure AD tenant ID." }, { "name": "vault_uri", "type": "string", "required": true, "description": "Key Vault data-plane URI — `https://{vault-name}.vault.azure.net` or `https://{hsm-name}.managedhsm.azure.net`." }, { "name": "client_id", "type": "string or null", "required": false, "description": "Azure AD application (client) ID. Omit to use Anthropic's multitenant app. Provide only if using a single-tenant app registration in the customer's directory." } ], "status": [ "DOCUMENTED" ], "sources": [ { "url": "https://platform.claude.com/docs/en/api/beta/organization/external_keys", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/anthropic-platform-objects.json" }, { "provider": "anthropic", "api_family": "admin", "name": "Beta Azure External Key Config Param", "official_type_name": "BetaAzureExternalKeyConfigParam", "description": "Azure Key Vault provider configuration.", "fields": [ { "name": "type", "type": "\"azure\"", "required": true, "description": "" }, { "name": "key_name", "type": "string", "required": true, "description": "Name of the key within the vault." }, { "name": "tenant_id", "type": "string", "required": true, "description": "Azure AD tenant ID." }, { "name": "vault_uri", "type": "string", "required": true, "description": "Key Vault data-plane URI — `https://{vault-name}.vault.azure.net` or `https://{hsm-name}.managedhsm.azure.net`." }, { "name": "client_id", "type": "string or null", "required": false, "description": "Azure AD application (client) ID. Omit to use Anthropic's multitenant app. Provide only if using a single-tenant app registration in the customer's directory." } ], "status": [ "DOCUMENTED" ], "sources": [ { "url": "https://platform.claude.com/docs/en/api/beta/organization/external_keys", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/anthropic-platform-objects.json" }, { "provider": "anthropic", "api_family": "admin", "name": "Beta External Key Attached Attachment", "official_type_name": "BetaExternalKeyAttachedAttachment", "description": "", "fields": [ { "name": "type", "type": "\"attached\"", "required": true, "description": "", "default": "attached" } ], "status": [ "DOCUMENTED" ], "sources": [ { "url": "https://platform.claude.com/docs/en/api/beta/organization/external_keys", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/anthropic-platform-objects.json" }, { "provider": "anthropic", "api_family": "admin", "name": "Beta External Key Unattached Attachment", "official_type_name": "BetaExternalKeyUnattachedAttachment", "description": "", "fields": [ { "name": "type", "type": "\"unattached\"", "required": true, "description": "", "default": "unattached" } ], "status": [ "DOCUMENTED" ], "sources": [ { "url": "https://platform.claude.com/docs/en/api/beta/organization/external_keys", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/anthropic-platform-objects.json" }, { "provider": "anthropic", "api_family": "admin", "name": "Beta GCP External Key Config", "official_type_name": "BetaGCPExternalKeyConfig", "description": "", "fields": [ { "name": "type", "type": "\"gcp\"", "required": true, "description": "" }, { "name": "key_name", "type": "string", "required": true, "description": "Full resource name of the Cloud KMS key." } ], "status": [ "DOCUMENTED" ], "sources": [ { "url": "https://platform.claude.com/docs/en/api/beta/organization/external_keys", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/anthropic-platform-objects.json" }, { "provider": "anthropic", "api_family": "admin", "name": "External Key Delete Response", "official_type_name": "ExternalKeyDeleteResponse", "description": "", "fields": [ { "name": "type", "type": "\"external_key_deleted\"", "required": true, "description": "", "default": "external_key_deleted" }, { "name": "id", "type": "string", "required": true, "description": "ID of the deleted External Key." } ], "status": [ "DOCUMENTED" ], "sources": [ { "url": "https://platform.claude.com/docs/en/api/beta/organization/external_keys", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/anthropic-platform-objects.json" }, { "provider": "anthropic", "api_family": "admin", "name": "External Key Validate Response", "official_type_name": "ExternalKeyValidateResponse", "description": "Result of a validation roundtrip against the customer's KMS. HTTP 200 for both outcomes — the operation completed; `status` says whether the key works.", "fields": [ { "name": "type", "type": "\"external_key_validation\"", "required": true, "description": "", "default": "external_key_validation" }, { "name": "error", "type": "string or null", "required": true, "description": "Error message when status is `failure`. Null otherwise." }, { "name": "status", "type": "\"failure\" or \"success\"", "required": true, "description": "`success` — encrypt/decrypt roundtrip succeeded. `failure` — the roundtrip failed or timed out; see `error`.", "enum": [ "failure", "success" ] } ], "status": [ "DOCUMENTED" ], "sources": [ { "url": "https://platform.claude.com/docs/en/api/beta/organization/external_keys", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/anthropic-platform-objects.json" }, { "provider": "anthropic", "api_family": "admin", "name": "Beta Compliance Settings State", "official_type_name": "BetaComplianceSettingsState", "description": "", "fields": [ { "name": "type", "type": "\"enabled\"", "required": true, "description": "", "default": "enabled" }, { "name": "type", "type": "\"disabled\"", "required": true, "description": "", "default": "disabled" } ], "status": [ "DOCUMENTED" ], "sources": [ { "url": "https://platform.claude.com/docs/en/api/beta/organization/compliance_settings", "retrieved_at": "2026-09-18" } ], "union_of": "BetaComplianceSettingsStateEnabled or BetaComplianceSettingsStateDisabled", "_fragment": "generated/fragments/objects/anthropic-platform-objects.json" }, { "provider": "anthropic", "api_family": "admin", "name": "Beta Compliance Settings State Disabled", "official_type_name": "BetaComplianceSettingsStateDisabled", "description": "", "fields": [ { "name": "type", "type": "\"disabled\"", "required": true, "description": "", "default": "disabled" } ], "status": [ "DOCUMENTED" ], "sources": [ { "url": "https://platform.claude.com/docs/en/api/beta/organization/compliance_settings", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/anthropic-platform-objects.json" }, { "provider": "anthropic", "api_family": "admin", "name": "Beta Compliance Settings State Disabled Param", "official_type_name": "BetaComplianceSettingsStateDisabledParam", "description": "", "fields": [ { "name": "type", "type": "\"disabled\"", "required": true, "description": "" } ], "status": [ "DOCUMENTED" ], "sources": [ { "url": "https://platform.claude.com/docs/en/api/beta/organization/compliance_settings", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/anthropic-platform-objects.json" }, { "provider": "anthropic", "api_family": "admin", "name": "Beta Compliance Settings State Enabled", "official_type_name": "BetaComplianceSettingsStateEnabled", "description": "", "fields": [ { "name": "type", "type": "\"enabled\"", "required": true, "description": "", "default": "enabled" } ], "status": [ "DOCUMENTED" ], "sources": [ { "url": "https://platform.claude.com/docs/en/api/beta/organization/compliance_settings", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/anthropic-platform-objects.json" }, { "provider": "anthropic", "api_family": "admin", "name": "Beta Compliance Settings State Enabled Param", "official_type_name": "BetaComplianceSettingsStateEnabledParam", "description": "", "fields": [ { "name": "type", "type": "\"enabled\"", "required": true, "description": "" } ], "status": [ "DOCUMENTED" ], "sources": [ { "url": "https://platform.claude.com/docs/en/api/beta/organization/compliance_settings", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/anthropic-platform-objects.json" }, { "provider": "anthropic", "api_family": "admin", "name": "Beta Compliance Settings State Param", "official_type_name": "BetaComplianceSettingsStateParam", "description": "", "fields": [ { "name": "type", "type": "\"enabled\"", "required": true, "description": "" }, { "name": "type", "type": "\"disabled\"", "required": true, "description": "" } ], "status": [ "DOCUMENTED" ], "sources": [ { "url": "https://platform.claude.com/docs/en/api/beta/organization/compliance_settings", "retrieved_at": "2026-09-18" } ], "union_of": "BetaComplianceSettingsStateEnabledParam or BetaComplianceSettingsStateDisabledParam", "_fragment": "generated/fragments/objects/anthropic-platform-objects.json" }, { "provider": "anthropic", "api_family": "managed-agents", "name": "Agent", "official_type_name": "BetaManagedAgentsAgent", "description": "A Managed Agents `agent`.", "fields": [ { "name": "type", "type": "\"agent\"", "required": true, "description": "" }, { "name": "id", "type": "string", "required": true, "description": "" }, { "name": "archived_at", "type": "string or null", "required": true, "description": "A timestamp in RFC 3339 format", "constraints": { "format": "date-time" } }, { "name": "created_at", "type": "string", "required": true, "description": "A timestamp in RFC 3339 format", "constraints": { "format": "date-time" } }, { "name": "description", "type": "string or null", "required": true, "description": "" }, { "name": "mcp_servers", "type": "array of BetaManagedAgentsMCPServerURLDefinition", "required": true, "description": "" }, { "name": "mcp_servers.type", "type": "\"url\"", "required": true, "description": "" }, { "name": "mcp_servers.name", "type": "string", "required": true, "description": "" }, { "name": "mcp_servers.url", "type": "string", "required": true, "description": "" }, { "name": "metadata", "type": "map[string]", "required": true, "description": "" }, { "name": "model", "type": "BetaManagedAgentsModelConfig", "required": true, "description": "Model identifier and configuration." }, { "name": "model.id", "type": "BetaManagedAgentsModel", "required": true, "description": "The model that will power your agent. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options." }, { "name": "model.id<\"claude-fable-5-1\" or \"claude-sonnet-5\" or \"claude-fable-5\" or 11 more>", "type": "\"claude-fable-5-1\" or \"claude-sonnet-5\" or \"claude-fable-5\" or 11 more", "required": false, "description": "The model that will power your agent. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options." }, { "name": "model.id", "type": "string", "required": false, "description": "" }, { "name": "model.effort", "type": "BetaManagedAgentsEffortLow or BetaManagedAgentsEffortMedium or BetaManagedAgentsEffortHigh or 2 more", "required": false, "description": "How hard Claude works on each turn. Sets `output_config.effort` on every Messages call the session makes." }, { "name": "model.effort", "type": "BetaManagedAgentsEffortLow object", "required": false, "description": "Low effort. Favors latency over reasoning depth." }, { "name": "model.effort.type", "type": "\"low\"", "required": true, "description": "" }, { "name": "model.effort", "type": "BetaManagedAgentsEffortMedium object", "required": false, "description": "Medium effort. Balances latency and reasoning depth." }, { "name": "model.effort.type", "type": "\"medium\"", "required": true, "description": "" }, { "name": "model.effort", "type": "BetaManagedAgentsEffortHigh object", "required": false, "description": "High effort. Favors reasoning depth." }, { "name": "model.effort.type", "type": "\"high\"", "required": true, "description": "" }, { "name": "model.effort", "type": "BetaManagedAgentsEffortXhigh object", "required": false, "description": "Extra-high effort. Not all models accept this level." }, { "name": "model.effort.type", "type": "\"xhigh\"", "required": true, "description": "" }, { "name": "model.effort", "type": "BetaManagedAgentsEffortMax object", "required": false, "description": "Maximum effort. Favors reasoning depth over latency." }, { "name": "model.effort.type", "type": "\"max\"", "required": true, "description": "" }, { "name": "model.inference_geo", "type": "string", "required": false, "description": "Geographic region for model inference. When unset, requests fall through to the workspace's default_inference_geo." }, { "name": "model.speed", "type": "\"standard\" or \"fast\"", "required": false, "description": "Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time.", "enum": [ "standard", "fast" ] }, { "name": "multiagent", "type": "BetaManagedAgentsMultiagent or null", "required": true, "description": "Resolved coordinator topology with a concrete agent roster." }, { "name": "multiagent.type", "type": "\"coordinator\"", "required": true, "description": "" }, { "name": "multiagent.agents", "type": "array of BetaManagedAgentsAgentReference or BetaManagedAgentsAdvisor", "required": true, "description": "Agents the coordinator may spawn as session threads, each resolved to a specific version." }, { "name": "multiagent.agents", "type": "BetaManagedAgentsAgentReference object", "required": false, "description": "A resolved agent reference with a concrete version." }, { "name": "multiagent.agents.type", "type": "\"agent\"", "required": true, "description": "" }, { "name": "multiagent.agents.id", "type": "string", "required": true, "description": "" }, { "name": "multiagent.agents.version", "type": "number", "required": true, "description": "", "constraints": { "format": "int32" } }, { "name": "multiagent.agents", "type": "BetaManagedAgentsAdvisor object", "required": false, "description": "Platform advisor roster entry: a model the session's primary thread may consult mid-turn." }, { "name": "multiagent.agents.type", "type": "\"advisor\"", "required": true, "description": "" }, { "name": "multiagent.agents.model", "type": "string", "required": true, "description": "The advisor model id." }, { "name": "name", "type": "string", "required": true, "description": "" }, { "name": "skills", "type": "array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill", "required": true, "description": "" }, { "name": "skills", "type": "BetaManagedAgentsAnthropicSkill object", "required": false, "description": "A resolved Anthropic-managed skill." }, { "name": "skills.type", "type": "\"anthropic\"", "required": true, "description": "" }, { "name": "skills.skill_id", "type": "string", "required": true, "description": "" }, { "name": "skills.version", "type": "string", "required": true, "description": "" }, { "name": "skills", "type": "BetaManagedAgentsCustomSkill object", "required": false, "description": "A resolved user-created custom skill." }, { "name": "skills.type", "type": "\"custom\"", "required": true, "description": "" }, { "name": "skills.skill_id", "type": "string", "required": true, "description": "" }, { "name": "skills.version", "type": "string", "required": true, "description": "" }, { "name": "system", "type": "string or null", "required": true, "description": "" }, { "name": "tools", "type": "array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool", "required": true, "description": "" }, { "name": "tools", "type": "BetaManagedAgentsAgentToolset20260401 object", "required": false, "description": "" }, { "name": "tools.type", "type": "\"agent_toolset_20260401\"", "required": true, "description": "" }, { "name": "tools.configs", "type": "array of BetaManagedAgentsAgentToolConfig", "required": true, "description": "" }, { "name": "tools.configs", "type": "BetaManagedAgentsBashToolConfig object", "required": false, "description": "Configuration for the bash tool." }, { "name": "tools.configs.type", "type": "\"bash\"", "required": true, "description": "" }, { "name": "tools.configs.enabled", "type": "boolean", "required": true, "description": "" }, { "name": "tools.configs.name", "type": "\"bash\"", "required": true, "description": "" }, { "name": "tools.configs.permission_policy", "type": "BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy", "required": true, "description": "Permission policy for tool execution." }, { "name": "tools.configs", "type": "BetaManagedAgentsEditToolConfig object", "required": false, "description": "Configuration for the edit tool." }, { "name": "tools.configs.type", "type": "\"edit\"", "required": true, "description": "" }, { "name": "tools.configs.enabled", "type": "boolean", "required": true, "description": "" }, { "name": "tools.configs.name", "type": "\"edit\"", "required": true, "description": "" }, { "name": "tools.configs.permission_policy", "type": "BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy", "required": true, "description": "Permission policy for tool execution." }, { "name": "tools.configs", "type": "BetaManagedAgentsReadToolConfig object", "required": false, "description": "Configuration for the read tool." }, { "name": "tools.configs.type", "type": "\"read\"", "required": true, "description": "" }, { "name": "tools.configs.enabled", "type": "boolean", "required": true, "description": "" }, { "name": "tools.configs.name", "type": "\"read\"", "required": true, "description": "" }, { "name": "tools.configs.permission_policy", "type": "BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy", "required": true, "description": "Permission policy for tool execution." }, { "name": "tools.configs", "type": "BetaManagedAgentsWriteToolConfig object", "required": false, "description": "Configuration for the write tool." }, { "name": "tools.configs.type", "type": "\"write\"", "required": true, "description": "" }, { "name": "tools.configs.enabled", "type": "boolean", "required": true, "description": "" }, { "name": "tools.configs.name", "type": "\"write\"", "required": true, "description": "" }, { "name": "tools.configs.permission_policy", "type": "BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy", "required": true, "description": "Permission policy for tool execution." }, { "name": "tools.configs", "type": "BetaManagedAgentsGlobToolConfig object", "required": false, "description": "Configuration for the glob tool." }, { "name": "tools.configs.type", "type": "\"glob\"", "required": true, "description": "" }, { "name": "tools.configs.enabled", "type": "boolean", "required": true, "description": "" }, { "name": "tools.configs.name", "type": "\"glob\"", "required": true, "description": "" }, { "name": "tools.configs.permission_policy", "type": "BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy", "required": true, "description": "Permission policy for tool execution." }, { "name": "tools.configs", "type": "BetaManagedAgentsGrepToolConfig object", "required": false, "description": "Configuration for the grep tool." }, { "name": "tools.configs.type", "type": "\"grep\"", "required": true, "description": "" }, { "name": "tools.configs.enabled", "type": "boolean", "required": true, "description": "" }, { "name": "tools.configs.name", "type": "\"grep\"", "required": true, "description": "" }, { "name": "tools.configs.permission_policy", "type": "BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy", "required": true, "description": "Permission policy for tool execution." }, { "name": "tools.configs", "type": "BetaManagedAgentsWebFetchToolConfig object", "required": false, "description": "Configuration for the web_fetch tool." }, { "name": "tools.configs.type", "type": "\"web_fetch\"", "required": true, "description": "" }, { "name": "tools.configs.enabled", "type": "boolean", "required": true, "description": "" }, { "name": "tools.configs.name", "type": "\"web_fetch\"", "required": true, "description": "" }, { "name": "tools.configs.permission_policy", "type": "BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy", "required": true, "description": "Permission policy for tool execution." }, { "name": "tools.configs.allowed_domains", "type": "array of string", "required": false, "description": "" }, { "name": "tools.configs.blocked_domains", "type": "array of string", "required": false, "description": "" }, { "name": "tools.configs.max_content_tokens", "type": "number or null", "required": false, "description": "", "constraints": { "format": "int32" } }, { "name": "tools.configs", "type": "BetaManagedAgentsWebSearchToolConfig object", "required": false, "description": "Configuration for the web_search tool." }, { "name": "tools.configs.type", "type": "\"web_search\"", "required": true, "description": "" }, { "name": "tools.configs.enabled", "type": "boolean", "required": true, "description": "" }, { "name": "tools.configs.name", "type": "\"web_search\"", "required": true, "description": "" }, { "name": "tools.configs.permission_policy", "type": "BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy", "required": true, "description": "Permission policy for tool execution." }, { "name": "tools.configs.allowed_domains", "type": "array of string", "required": false, "description": "" }, { "name": "tools.configs.blocked_domains", "type": "array of string", "required": false, "description": "" }, { "name": "tools.configs.user_location", "type": "BetaManagedAgentsUserLocation or null", "required": false, "description": "Approximate user location for search result localization." }, { "name": "tools.default_config", "type": "BetaManagedAgentsAgentToolsetDefaultConfig", "required": true, "description": "Resolved default configuration for agent tools." }, { "name": "tools.default_config.enabled", "type": "boolean", "required": true, "description": "" }, { "name": "tools.default_config.permission_policy", "type": "BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy", "required": true, "description": "Permission policy for tool execution." }, { "name": "tools.default_config.permission_policy", "type": "BetaManagedAgentsAlwaysAllowPolicy object", "required": false, "description": "Tool calls are automatically approved without user confirmation." }, { "name": "tools.default_config.permission_policy", "type": "BetaManagedAgentsAlwaysAskPolicy object", "required": false, "description": "Tool calls require user confirmation before execution." }, { "name": "tools.default_config.permission_policy", "type": "BetaManagedAgentsAutoPolicy object", "required": false, "description": "The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask." }, { "name": "tools", "type": "BetaManagedAgentsMCPToolset object", "required": false, "description": "" }, { "name": "tools.type", "type": "\"mcp_toolset\"", "required": true, "description": "" }, { "name": "tools.configs", "type": "array of BetaManagedAgentsMCPToolConfig", "required": true, "description": "" }, { "name": "tools.configs.enabled", "type": "boolean", "required": true, "description": "" }, { "name": "tools.configs.name", "type": "string", "required": true, "description": "" }, { "name": "tools.configs.permission_policy", "type": "BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy", "required": true, "description": "Permission policy for tool execution." }, { "name": "tools.configs.permission_policy", "type": "BetaManagedAgentsAlwaysAllowPolicy object", "required": false, "description": "Tool calls are automatically approved without user confirmation." }, { "name": "tools.configs.permission_policy", "type": "BetaManagedAgentsAlwaysAskPolicy object", "required": false, "description": "Tool calls require user confirmation before execution." }, { "name": "tools.configs.permission_policy", "type": "BetaManagedAgentsAutoPolicy object", "required": false, "description": "The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask." }, { "name": "tools.default_config", "type": "BetaManagedAgentsMCPToolsetDefaultConfig", "required": true, "description": "Resolved default configuration for all tools from an MCP server." }, { "name": "tools.default_config.enabled", "type": "boolean", "required": true, "description": "" }, { "name": "tools.default_config.permission_policy", "type": "BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy", "required": true, "description": "Permission policy for tool execution." }, { "name": "tools.default_config.permission_policy", "type": "BetaManagedAgentsAlwaysAllowPolicy object", "required": false, "description": "Tool calls are automatically approved without user confirmation." }, { "name": "tools.default_config.permission_policy", "type": "BetaManagedAgentsAlwaysAskPolicy object", "required": false, "description": "Tool calls require user confirmation before execution." }, { "name": "tools.default_config.permission_policy", "type": "BetaManagedAgentsAutoPolicy object", "required": false, "description": "The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask." }, { "name": "tools.mcp_server_name", "type": "string", "required": true, "description": "" }, { "name": "tools", "type": "BetaManagedAgentsCustomTool object", "required": false, "description": "A custom tool as returned in API responses." }, { "name": "tools.type", "type": "\"custom\"", "required": true, "description": "" }, { "name": "tools.description", "type": "string", "required": true, "description": "" }, { "name": "tools.input_schema", "type": "BetaManagedAgentsCustomToolInputSchema", "required": true, "description": "JSON Schema for custom tool input parameters." }, { "name": "tools.input_schema.type", "type": "\"object\"", "required": true, "description": "" }, { "name": "tools.input_schema.properties", "type": "map[unknown] or null", "required": false, "description": "" }, { "name": "tools.input_schema.required", "type": "array of string or null", "required": false, "description": "" }, { "name": "tools.name", "type": "string", "required": true, "description": "" }, { "name": "updated_at", "type": "string", "required": true, "description": "A timestamp in RFC 3339 format", "constraints": { "format": "date-time" } }, { "name": "version", "type": "number", "required": true, "description": "The agent's current version. Starts at 1 and increments when the agent is modified.", "constraints": { "format": "int32" } } ], "status": [ "DOCUMENTED", "BETA" ], "sources": [ { "url": "https://platform.claude.com/docs/en/api/beta/agents/create", "retrieved_at": "2026-09-18" }, { "url": "https://platform.claude.com/docs/en/managed-agents/agent-setup", "retrieved_at": "2026-09-18" } ], "beta_header": "managed-agents-2026-04-01", "_fragment": "generated/fragments/objects/anthropic-platform-objects.json" }, { "provider": "anthropic", "api_family": "managed-agents", "name": "AgentCreateParams (request body)", "official_type_name": "BetaManagedAgentsAgentCreateParams", "description": "Create Agent", "fields": [ { "name": "model", "type": "BetaManagedAgentsModel or BetaManagedAgentsModelConfigParams", "required": true, "description": "Model identifier. Accepts the [model string](https://platform.claude.com/docs/en/about-claude/models/overview#latest-models-comparison), e.g. `claude-opus-5`, or a `model_config` object for additional configuration control" }, { "name": "model", "type": "BetaManagedAgentsModel = \"claude-fable-5-1\" or \"claude-sonnet-5\" or \"claude-fable-5\" or 11 more or string", "required": false, "description": "The model that will power your agent. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options." }, { "name": "model<\"claude-fable-5-1\" or \"claude-sonnet-5\" or \"claude-fable-5\" or 11 more>", "type": "\"claude-fable-5-1\" or \"claude-sonnet-5\" or \"claude-fable-5\" or 11 more", "required": false, "description": "The model that will power your agent. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options." }, { "name": "model", "type": "string", "required": false, "description": "" }, { "name": "model", "type": "BetaManagedAgentsModelConfigParams object", "required": false, "description": "An object that defines additional configuration control over model use" }, { "name": "model.id", "type": "BetaManagedAgentsModel", "required": true, "description": "The model that will power your agent. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options." }, { "name": "model.effort", "type": "\"low\" or \"medium\" or \"high\" or 2 more or BetaManagedAgentsEffortLow or BetaManagedAgentsEffortMedium or 3 more or null", "required": false, "description": "How hard Claude works on each inference call. Accepts a bare level string (`\"high\"`) or `{\"type\": \"high\"}`. On create, omitting it resolves the per-model default; on update, omitting it leaves the stored value unchanged." }, { "name": "model.effort", "type": "BetaManagedAgentsEffortLevel = \"low\" or \"medium\" or \"high\" or 2 more", "required": false, "description": "How hard Claude works on each turn. Higher levels favor reasoning depth over latency. Not all models accept every level; invalid combinations are rejected at create time." }, { "name": "model.effort", "type": "BetaManagedAgentsEffortLow object", "required": false, "description": "Low effort. Favors latency over reasoning depth." }, { "name": "model.effort.type", "type": "\"low\"", "required": true, "description": "" }, { "name": "model.effort", "type": "BetaManagedAgentsEffortMedium object", "required": false, "description": "Medium effort. Balances latency and reasoning depth." }, { "name": "model.effort.type", "type": "\"medium\"", "required": true, "description": "" }, { "name": "model.effort", "type": "BetaManagedAgentsEffortHigh object", "required": false, "description": "High effort. Favors reasoning depth." }, { "name": "model.effort.type", "type": "\"high\"", "required": true, "description": "" }, { "name": "model.effort", "type": "BetaManagedAgentsEffortXhigh object", "required": false, "description": "Extra-high effort. Not all models accept this level." }, { "name": "model.effort.type", "type": "\"xhigh\"", "required": true, "description": "" }, { "name": "model.effort", "type": "BetaManagedAgentsEffortMax object", "required": false, "description": "Maximum effort. Favors reasoning depth over latency." }, { "name": "model.effort.type", "type": "\"max\"", "required": true, "description": "" }, { "name": "model.inference_geo", "type": "string or null", "required": false, "description": "Geographic region for model inference. When unset, requests fall through to the workspace's default_inference_geo. On update, `model` is whole-object replacement — omitting inference_geo clears it." }, { "name": "model.speed", "type": "\"standard\" or \"fast\" or null", "required": false, "description": "Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time.", "enum": [ "standard", "fast" ] }, { "name": "name", "type": "string", "required": true, "description": "Human-readable name for the agent.", "constraints": { "minLength": "1", "maxLength": "256" } }, { "name": "description", "type": "string or null", "required": false, "description": "Description of what the agent does.", "constraints": { "maxLength": "2048" } }, { "name": "mcp_servers", "type": "array of BetaManagedAgentsURLMCPServerParams", "required": false, "description": "MCP servers this agent connects to. Maximum 20. Names must be unique within the array. Every server must be referenced by an `mcp_toolset` in `tools`; unreferenced servers are rejected. See the [MCP connector guide](https://platform.claude.com/docs/en/managed-agents/mcp-connector)." }, { "name": "mcp_servers.type", "type": "\"url\"", "required": true, "description": "" }, { "name": "mcp_servers.name", "type": "string", "required": true, "description": "Unique name for this server, referenced by mcp_toolset configurations. 1-255 characters.", "constraints": { "minLength": "1", "maxLength": "255" } }, { "name": "mcp_servers.url", "type": "string", "required": true, "description": "Endpoint URL for the MCP server.", "constraints": { "maxLength": "2048" } }, { "name": "metadata", "type": "map[string]", "required": false, "description": "Arbitrary key-value metadata. Maximum 16 pairs, keys up to 64 chars, values up to 512 chars." }, { "name": "multiagent", "type": "BetaManagedAgentsMultiagentParams or null", "required": false, "description": "A coordinator topology: the session's primary thread orchestrates work by spawning session threads, each running an agent drawn from the `agents` roster." }, { "name": "multiagent.type", "type": "\"coordinator\"", "required": true, "description": "" }, { "name": "multiagent.agents", "type": "array of BetaManagedAgentsMultiagentRosterEntryParams", "required": true, "description": "Agents the coordinator may spawn as session threads. 1–20 entries. Each entry is an agent ID string, a versioned `{\"type\":\"agent\",\"id\",\"version\"}` reference, or `{\"type\":\"self\"}` to allow recursive self-invocation. Entries must reference distinct agents (after resolving `self` and string forms); at most one `self`. Referenced agents must exist, must not be archived, and must not themselves have `multiagent` set (depth limit 1)." }, { "name": "multiagent.agents", "type": "string", "required": false, "description": "" }, { "name": "multiagent.agents", "type": "BetaManagedAgentsAgentParams object", "required": false, "description": "Specification for an Agent. Provide a specific `version` or use the short-form `agent=\"agent_id\"` for the most recent version" }, { "name": "multiagent.agents.type", "type": "\"agent\"", "required": true, "description": "" }, { "name": "multiagent.agents.id", "type": "string", "required": true, "description": "The `agent` ID.", "constraints": { "minLength": "1", "maxLength": "128" } }, { "name": "multiagent.agents.version", "type": "number", "required": false, "description": "The specific `agent` version to use. Omit to use the latest version. Must be at least 1 if specified.", "constraints": { "format": "int32" } }, { "name": "multiagent.agents", "type": "BetaManagedAgentsMultiagentSelfParams object", "required": false, "description": "Sentinel roster entry meaning \"the agent that owns this configuration\". Resolved server-side to a concrete agent reference." }, { "name": "multiagent.agents.type", "type": "\"self\"", "required": true, "description": "" }, { "name": "multiagent.agents", "type": "BetaManagedAgentsAdvisorParams object", "required": false, "description": "Platform advisor roster entry: a model the session's primary thread may consult mid-turn. At most one per roster; the entry occupies the roster name `anthropic.advisor`." }, { "name": "multiagent.agents.type", "type": "\"advisor\"", "required": true, "description": "" }, { "name": "multiagent.agents.model", "type": "string", "required": true, "description": "A Claude model id. The model must be permitted as an advisor for this agent's model — see the sessions/threads/advisor spec.", "constraints": { "minLength": "1", "maxLength": "256" } }, { "name": "skills", "type": "array of BetaManagedAgentsSkillParams", "required": false, "description": "Skills available to the agent." }, { "name": "skills", "type": "BetaManagedAgentsAnthropicSkillParams object", "required": false, "description": "An Anthropic-managed skill." }, { "name": "skills.type", "type": "\"anthropic\"", "required": true, "description": "" }, { "name": "skills.skill_id", "type": "string", "required": true, "description": "Identifier of the Anthropic skill (e.g., \"xlsx\").", "constraints": { "minLength": "1", "maxLength": "64" } }, { "name": "skills.version", "type": "string or null", "required": false, "description": "Version to pin. Defaults to latest if omitted.", "constraints": { "minLength": "1", "maxLength": "64" } }, { "name": "skills", "type": "BetaManagedAgentsCustomSkillParams object", "required": false, "description": "A user-created custom skill." }, { "name": "skills.type", "type": "\"custom\"", "required": true, "description": "" }, { "name": "skills.skill_id", "type": "string", "required": true, "description": "Tagged ID of the custom skill (e.g., \"skill_01XJ5...\").", "constraints": { "minLength": "1", "maxLength": "64" } }, { "name": "skills.version", "type": "string or null", "required": false, "description": "Version to pin. Defaults to latest if omitted.", "constraints": { "minLength": "1", "maxLength": "64" } }, { "name": "system", "type": "string or null", "required": false, "description": "System prompt for the agent.", "constraints": { "maxLength": "100000" } }, { "name": "tools", "type": "array of BetaManagedAgentsAgentToolset20260401Params or BetaManagedAgentsMCPToolsetParams or BetaManagedAgentsCustomToolParams", "required": false, "description": "Tool configurations available to the agent. Maximum of 128 tools across all toolsets allowed." }, { "name": "tools", "type": "BetaManagedAgentsAgentToolset20260401Params object", "required": false, "description": "Configuration for built-in agent tools. Use this to enable or disable groups of tools available to the agent." }, { "name": "tools.type", "type": "\"agent_toolset_20260401\"", "required": true, "description": "" }, { "name": "tools.configs", "type": "array of BetaManagedAgentsAgentToolConfigParams", "required": false, "description": "Per-tool configuration overrides." }, { "name": "tools.configs", "type": "BetaManagedAgentsBashToolConfigParams object", "required": false, "description": "Configuration override for the bash tool." }, { "name": "tools.configs.type", "type": "\"bash\"", "required": false, "description": "" }, { "name": "tools.configs.name", "type": "\"bash\"", "required": true, "description": "Must be \"bash\"." }, { "name": "tools.configs.enabled", "type": "boolean or null", "required": false, "description": "Whether this tool is enabled and available to Claude. Overrides the default_config setting." }, { "name": "tools.configs.permission_policy", "type": "BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy or null", "required": false, "description": "Permission policy for tool execution." }, { "name": "tools.configs.permission_policy", "type": "BetaManagedAgentsAlwaysAllowPolicy object", "required": false, "description": "Tool calls are automatically approved without user confirmation." }, { "name": "tools.configs.permission_policy", "type": "BetaManagedAgentsAlwaysAskPolicy object", "required": false, "description": "Tool calls require user confirmation before execution." }, { "name": "tools.configs.permission_policy", "type": "BetaManagedAgentsAutoPolicy object", "required": false, "description": "The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask." }, { "name": "tools.configs", "type": "BetaManagedAgentsEditToolConfigParams object", "required": false, "description": "Configuration override for the edit tool." }, { "name": "tools.configs.type", "type": "\"edit\"", "required": false, "description": "" }, { "name": "tools.configs.name", "type": "\"edit\"", "required": true, "description": "Must be \"edit\"." }, { "name": "tools.configs.enabled", "type": "boolean or null", "required": false, "description": "Whether this tool is enabled and available to Claude. Overrides the default_config setting." }, { "name": "tools.configs.permission_policy", "type": "BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy or null", "required": false, "description": "Permission policy for tool execution." }, { "name": "tools.configs.permission_policy", "type": "BetaManagedAgentsAlwaysAllowPolicy object", "required": false, "description": "Tool calls are automatically approved without user confirmation." }, { "name": "tools.configs.permission_policy", "type": "BetaManagedAgentsAlwaysAskPolicy object", "required": false, "description": "Tool calls require user confirmation before execution." }, { "name": "tools.configs.permission_policy", "type": "BetaManagedAgentsAutoPolicy object", "required": false, "description": "The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask." }, { "name": "tools.configs", "type": "BetaManagedAgentsReadToolConfigParams object", "required": false, "description": "Configuration override for the read tool." }, { "name": "tools.configs.type", "type": "\"read\"", "required": false, "description": "" }, { "name": "tools.configs.name", "type": "\"read\"", "required": true, "description": "Must be \"read\"." }, { "name": "tools.configs.enabled", "type": "boolean or null", "required": false, "description": "Whether this tool is enabled and available to Claude. Overrides the default_config setting." }, { "name": "tools.configs.permission_policy", "type": "BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy or null", "required": false, "description": "Permission policy for tool execution." }, { "name": "tools.configs.permission_policy", "type": "BetaManagedAgentsAlwaysAllowPolicy object", "required": false, "description": "Tool calls are automatically approved without user confirmation." }, { "name": "tools.configs.permission_policy", "type": "BetaManagedAgentsAlwaysAskPolicy object", "required": false, "description": "Tool calls require user confirmation before execution." }, { "name": "tools.configs.permission_policy", "type": "BetaManagedAgentsAutoPolicy object", "required": false, "description": "The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask." }, { "name": "tools.configs", "type": "BetaManagedAgentsWriteToolConfigParams object", "required": false, "description": "Configuration override for the write tool." }, { "name": "tools.configs.type", "type": "\"write\"", "required": false, "description": "" }, { "name": "tools.configs.name", "type": "\"write\"", "required": true, "description": "Must be \"write\"." }, { "name": "tools.configs.enabled", "type": "boolean or null", "required": false, "description": "Whether this tool is enabled and available to Claude. Overrides the default_config setting." }, { "name": "tools.configs.permission_policy", "type": "BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy or null", "required": false, "description": "Permission policy for tool execution." }, { "name": "tools.configs.permission_policy", "type": "BetaManagedAgentsAlwaysAllowPolicy object", "required": false, "description": "Tool calls are automatically approved without user confirmation." }, { "name": "tools.configs.permission_policy", "type": "BetaManagedAgentsAlwaysAskPolicy object", "required": false, "description": "Tool calls require user confirmation before execution." }, { "name": "tools.configs.permission_policy", "type": "BetaManagedAgentsAutoPolicy object", "required": false, "description": "The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask." }, { "name": "tools.configs", "type": "BetaManagedAgentsGlobToolConfigParams object", "required": false, "description": "Configuration override for the glob tool." }, { "name": "tools.configs.type", "type": "\"glob\"", "required": false, "description": "" }, { "name": "tools.configs.name", "type": "\"glob\"", "required": true, "description": "Must be \"glob\"." }, { "name": "tools.configs.enabled", "type": "boolean or null", "required": false, "description": "Whether this tool is enabled and available to Claude. Overrides the default_config setting." }, { "name": "tools.configs.permission_policy", "type": "BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy or null", "required": false, "description": "Permission policy for tool execution." }, { "name": "tools.configs.permission_policy", "type": "BetaManagedAgentsAlwaysAllowPolicy object", "required": false, "description": "Tool calls are automatically approved without user confirmation." }, { "name": "tools.configs.permission_policy", "type": "BetaManagedAgentsAlwaysAskPolicy object", "required": false, "description": "Tool calls require user confirmation before execution." }, { "name": "tools.configs.permission_policy", "type": "BetaManagedAgentsAutoPolicy object", "required": false, "description": "The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask." }, { "name": "tools.configs", "type": "BetaManagedAgentsGrepToolConfigParams object", "required": false, "description": "Configuration override for the grep tool." }, { "name": "tools.configs.type", "type": "\"grep\"", "required": false, "description": "" }, { "name": "tools.configs.name", "type": "\"grep\"", "required": true, "description": "Must be \"grep\"." }, { "name": "tools.configs.enabled", "type": "boolean or null", "required": false, "description": "Whether this tool is enabled and available to Claude. Overrides the default_config setting." }, { "name": "tools.configs.permission_policy", "type": "BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy or null", "required": false, "description": "Permission policy for tool execution." }, { "name": "tools.configs.permission_policy", "type": "BetaManagedAgentsAlwaysAllowPolicy object", "required": false, "description": "Tool calls are automatically approved without user confirmation." }, { "name": "tools.configs.permission_policy", "type": "BetaManagedAgentsAlwaysAskPolicy object", "required": false, "description": "Tool calls require user confirmation before execution." }, { "name": "tools.configs.permission_policy", "type": "BetaManagedAgentsAutoPolicy object", "required": false, "description": "The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask." }, { "name": "tools.configs", "type": "BetaManagedAgentsWebFetchToolConfigParams object", "required": false, "description": "Configuration override for the web_fetch tool." }, { "name": "tools.configs.type", "type": "\"web_fetch\"", "required": false, "description": "" }, { "name": "tools.configs.name", "type": "\"web_fetch\"", "required": true, "description": "Must be \"web_fetch\"." }, { "name": "tools.configs.allowed_domains", "type": "array of string", "required": false, "description": "Only fetch URLs whose host is one of these domains or a subdomain of one. Each entry is a plain hostname like \"docs.example.com\" (no scheme, port, or path). At most 64 entries; an empty list is rejected (omit the field instead). Cannot be combined with blocked_domains." }, { "name": "tools.configs.blocked_domains", "type": "array of string", "required": false, "description": "Never fetch URLs whose host is one of these domains or a subdomain of one. Each entry is a plain hostname like \"ads.example.com\" (no scheme, port, or path). At most 64 entries; an empty list is rejected (omit the field instead). Cannot be combined with allowed_domains." }, { "name": "tools.configs.enabled", "type": "boolean or null", "required": false, "description": "Whether this tool is enabled and available to Claude. Overrides the default_config setting." }, { "name": "tools.configs.max_content_tokens", "type": "number or null", "required": false, "description": "Maximum number of tokens of fetched text content to include in context per call. Does not apply to binary content such as PDFs.", "constraints": { "format": "int32" } }, { "name": "tools.configs.permission_policy", "type": "BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy or null", "required": false, "description": "Permission policy for tool execution." }, { "name": "tools.configs.permission_policy", "type": "BetaManagedAgentsAlwaysAllowPolicy object", "required": false, "description": "Tool calls are automatically approved without user confirmation." }, { "name": "tools.configs.permission_policy", "type": "BetaManagedAgentsAlwaysAskPolicy object", "required": false, "description": "Tool calls require user confirmation before execution." }, { "name": "tools.configs.permission_policy", "type": "BetaManagedAgentsAutoPolicy object", "required": false, "description": "The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask." }, { "name": "tools.configs", "type": "BetaManagedAgentsWebSearchToolConfigParams object", "required": false, "description": "Configuration override for the web_search tool." }, { "name": "tools.configs.type", "type": "\"web_search\"", "required": false, "description": "" }, { "name": "tools.configs.name", "type": "\"web_search\"", "required": true, "description": "Must be \"web_search\"." }, { "name": "tools.configs.allowed_domains", "type": "array of string", "required": false, "description": "Only return search results whose host is one of these domains or a subdomain of one. Each entry is a plain hostname like \"docs.example.com\" (no scheme or port; an optional path suffix is accepted). At most 64 entries; an empty list is rejected (omit the field instead). Cannot be combined with blocked_domains." }, { "name": "tools.configs.blocked_domains", "type": "array of string", "required": false, "description": "Never return search results whose host is one of these domains or a subdomain of one. Each entry is a plain hostname like \"ads.example.com\" (no scheme or port; an optional path suffix is accepted). At most 64 entries; an empty list is rejected (omit the field instead). Cannot be combined with allowed_domains." }, { "name": "tools.configs.enabled", "type": "boolean or null", "required": false, "description": "Whether this tool is enabled and available to Claude. Overrides the default_config setting." }, { "name": "tools.configs.permission_policy", "type": "BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy or null", "required": false, "description": "Permission policy for tool execution." }, { "name": "tools.configs.permission_policy", "type": "BetaManagedAgentsAlwaysAllowPolicy object", "required": false, "description": "Tool calls are automatically approved without user confirmation." }, { "name": "tools.configs.permission_policy", "type": "BetaManagedAgentsAlwaysAskPolicy object", "required": false, "description": "Tool calls require user confirmation before execution." }, { "name": "tools.configs.permission_policy", "type": "BetaManagedAgentsAutoPolicy object", "required": false, "description": "The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask." }, { "name": "tools.configs.user_location", "type": "BetaManagedAgentsUserLocation or null", "required": false, "description": "Approximate user location for search result localization." }, { "name": "tools.configs.user_location.type", "type": "\"approximate\"", "required": true, "description": "Location precision. Only \"approximate\" is supported." }, { "name": "tools.configs.user_location.city", "type": "string or null", "required": false, "description": "City name.", "constraints": { "minLength": "1", "maxLength": "255" } }, { "name": "tools.configs.user_location.country", "type": "string or null", "required": false, "description": "Two-letter ISO 3166-1 country code, uppercase." }, { "name": "tools.configs.user_location.region", "type": "string or null", "required": false, "description": "Region or state name.", "constraints": { "minLength": "1", "maxLength": "255" } }, { "name": "tools.configs.user_location.timezone", "type": "string or null", "required": false, "description": "IANA timezone identifier, e.g. \"America/Los_Angeles\".", "constraints": { "minLength": "1", "maxLength": "255" } }, { "name": "tools.default_config", "type": "BetaManagedAgentsAgentToolsetDefaultConfigParams or null", "required": false, "description": "Default configuration for all tools in a toolset." }, { "name": "tools.default_config.enabled", "type": "boolean or null", "required": false, "description": "Whether tools are enabled and available to Claude by default. Defaults to true if not specified." }, { "name": "tools.default_config.permission_policy", "type": "BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy or null", "required": false, "description": "Permission policy for tool execution." }, { "name": "tools.default_config.permission_policy", "type": "BetaManagedAgentsAlwaysAllowPolicy object", "required": false, "description": "Tool calls are automatically approved without user confirmation." }, { "name": "tools.default_config.permission_policy", "type": "BetaManagedAgentsAlwaysAskPolicy object", "required": false, "description": "Tool calls require user confirmation before execution." }, { "name": "tools.default_config.permission_policy", "type": "BetaManagedAgentsAutoPolicy object", "required": false, "description": "The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask." }, { "name": "tools", "type": "BetaManagedAgentsMCPToolsetParams object", "required": false, "description": "Configuration for tools from an MCP server defined in `mcp_servers`." }, { "name": "tools.type", "type": "\"mcp_toolset\"", "required": true, "description": "" }, { "name": "tools.mcp_server_name", "type": "string", "required": true, "description": "Name of the MCP server. Must match a server name from the mcp_servers array. 1-255 characters.", "constraints": { "minLength": "1", "maxLength": "255" } }, { "name": "tools.configs", "type": "array of BetaManagedAgentsMCPToolConfigParams", "required": false, "description": "Per-tool configuration overrides." }, { "name": "tools.configs.name", "type": "string", "required": true, "description": "Name of the MCP tool to configure. 1-128 characters.", "constraints": { "minLength": "1", "maxLength": "128" } }, { "name": "tools.configs.enabled", "type": "boolean or null", "required": false, "description": "Whether this tool is enabled. Overrides the `default_config` setting." }, { "name": "tools.configs.permission_policy", "type": "BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy or null", "required": false, "description": "Permission policy for tool execution." }, { "name": "tools.configs.permission_policy", "type": "BetaManagedAgentsAlwaysAllowPolicy object", "required": false, "description": "Tool calls are automatically approved without user confirmation." }, { "name": "tools.configs.permission_policy", "type": "BetaManagedAgentsAlwaysAskPolicy object", "required": false, "description": "Tool calls require user confirmation before execution." }, { "name": "tools.configs.permission_policy", "type": "BetaManagedAgentsAutoPolicy object", "required": false, "description": "The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask." }, { "name": "tools.default_config", "type": "BetaManagedAgentsMCPToolsetDefaultConfigParams or null", "required": false, "description": "Default configuration for all tools from an MCP server." }, { "name": "tools.default_config.enabled", "type": "boolean or null", "required": false, "description": "Whether tools are enabled by default. Defaults to true if not specified." }, { "name": "tools.default_config.permission_policy", "type": "BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy or null", "required": false, "description": "Permission policy for tool execution." }, { "name": "tools.default_config.permission_policy", "type": "BetaManagedAgentsAlwaysAllowPolicy object", "required": false, "description": "Tool calls are automatically approved without user confirmation." }, { "name": "tools.default_config.permission_policy", "type": "BetaManagedAgentsAlwaysAskPolicy object", "required": false, "description": "Tool calls require user confirmation before execution." }, { "name": "tools.default_config.permission_policy", "type": "BetaManagedAgentsAutoPolicy object", "required": false, "description": "The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask." }, { "name": "tools", "type": "BetaManagedAgentsCustomToolParams object", "required": false, "description": "A custom tool that is executed by the API client rather than the agent. When the agent calls this tool, an `agent.custom_tool_use` event is emitted and the session goes idle, waiting for the client to provide the result via a `user.custom_tool_result` event." }, { "name": "tools.type", "type": "\"custom\"", "required": true, "description": "" }, { "name": "tools.description", "type": "string", "required": true, "description": "Description of what the tool does, shown to the agent to help it decide when to use the tool.", "constraints": { "minLength": "1" } }, { "name": "tools.input_schema", "type": "BetaManagedAgentsCustomToolInputSchema", "required": true, "description": "JSON Schema for custom tool input parameters." }, { "name": "tools.input_schema.type", "type": "\"object\"", "required": true, "description": "" }, { "name": "tools.input_schema.properties", "type": "map[unknown] or null", "required": false, "description": "" }, { "name": "tools.input_schema.required", "type": "array of string or null", "required": false, "description": "" }, { "name": "tools.name", "type": "string", "required": true, "description": "Unique name for the tool. 1-128 characters; letters, digits, underscores, and hyphens.", "constraints": { "minLength": "1", "maxLength": "128" } } ], "status": [ "DOCUMENTED", "BETA" ], "sources": [ { "url": "https://platform.claude.com/docs/en/api/beta/agents/create", "retrieved_at": "2026-09-18" }, { "url": "https://platform.claude.com/docs/en/managed-agents/agent-setup", "retrieved_at": "2026-09-18" }, { "url": "https://platform.claude.com/docs/en/managed-agents/tools", "retrieved_at": "2026-09-18" }, { "url": "https://platform.claude.com/docs/en/managed-agents/mcp-connector", "retrieved_at": "2026-09-18" }, { "url": "https://platform.claude.com/docs/en/managed-agents/skills", "retrieved_at": "2026-09-18" }, { "url": "https://platform.claude.com/docs/en/managed-agents/multiagent-orchestration", "retrieved_at": "2026-09-18" } ], "beta_header": "managed-agents-2026-04-01", "_fragment": "generated/fragments/objects/anthropic-platform-objects.json" }, { "provider": "anthropic", "api_family": "managed-agents", "name": "AgentUpdateParams (request body)", "official_type_name": "BetaManagedAgentsAgentUpdateParams", "description": "Update Agent", "fields": [ { "name": "description", "type": "string or null", "required": false, "description": "Description. Omit to preserve; send empty string or null to clear.", "constraints": { "maxLength": "2048" } }, { "name": "mcp_servers", "type": "array of BetaManagedAgentsURLMCPServerParams or null", "required": false, "description": "MCP servers. Full replacement. Omit to preserve; send empty array or `null` to clear. Names must be unique. Maximum 20. Every server must be referenced by an `mcp_toolset` in the agent's resulting `tools`; unreferenced servers are rejected. See the [MCP connector guide](https://platform.claude.com/docs/en/managed-agents/mcp-connector)." }, { "name": "mcp_servers.type", "type": "\"url\"", "required": true, "description": "" }, { "name": "mcp_servers.name", "type": "string", "required": true, "description": "Unique name for this server, referenced by mcp_toolset configurations. 1-255 characters.", "constraints": { "minLength": "1", "maxLength": "255" } }, { "name": "mcp_servers.url", "type": "string", "required": true, "description": "Endpoint URL for the MCP server.", "constraints": { "maxLength": "2048" } }, { "name": "metadata", "type": "map[string] or null", "required": false, "description": "Metadata patch. Set a key to a string to upsert it, or to null to delete it. Omit the field to preserve. The stored bag is limited to 16 keys (up to 64 chars each) with values up to 512 chars." }, { "name": "model", "type": "BetaManagedAgentsModel or BetaManagedAgentsModelConfigParams", "required": false, "description": "Model identifier. Accepts the [model string](https://platform.claude.com/docs/en/about-claude/models/overview#latest-models-comparison), e.g. `claude-opus-5`, or a `model_config` object for additional configuration control. Omit to preserve. Cannot be cleared." }, { "name": "model", "type": "BetaManagedAgentsModel = \"claude-fable-5-1\" or \"claude-sonnet-5\" or \"claude-fable-5\" or 11 more or string", "required": false, "description": "The model that will power your agent. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options." }, { "name": "model<\"claude-fable-5-1\" or \"claude-sonnet-5\" or \"claude-fable-5\" or 11 more>", "type": "\"claude-fable-5-1\" or \"claude-sonnet-5\" or \"claude-fable-5\" or 11 more", "required": false, "description": "The model that will power your agent. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options." }, { "name": "model", "type": "string", "required": false, "description": "" }, { "name": "model", "type": "BetaManagedAgentsModelConfigParams object", "required": false, "description": "An object that defines additional configuration control over model use" }, { "name": "model.id", "type": "BetaManagedAgentsModel", "required": true, "description": "The model that will power your agent. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options." }, { "name": "model.effort", "type": "\"low\" or \"medium\" or \"high\" or 2 more or BetaManagedAgentsEffortLow or BetaManagedAgentsEffortMedium or 3 more or null", "required": false, "description": "How hard Claude works on each inference call. Accepts a bare level string (`\"high\"`) or `{\"type\": \"high\"}`. On create, omitting it resolves the per-model default; on update, omitting it leaves the stored value unchanged." }, { "name": "model.effort", "type": "BetaManagedAgentsEffortLevel = \"low\" or \"medium\" or \"high\" or 2 more", "required": false, "description": "How hard Claude works on each turn. Higher levels favor reasoning depth over latency. Not all models accept every level; invalid combinations are rejected at create time." }, { "name": "model.effort", "type": "BetaManagedAgentsEffortLow object", "required": false, "description": "Low effort. Favors latency over reasoning depth." }, { "name": "model.effort", "type": "BetaManagedAgentsEffortMedium object", "required": false, "description": "Medium effort. Balances latency and reasoning depth." }, { "name": "model.effort", "type": "BetaManagedAgentsEffortHigh object", "required": false, "description": "High effort. Favors reasoning depth." }, { "name": "model.effort", "type": "BetaManagedAgentsEffortXhigh object", "required": false, "description": "Extra-high effort. Not all models accept this level." }, { "name": "model.effort", "type": "BetaManagedAgentsEffortMax object", "required": false, "description": "Maximum effort. Favors reasoning depth over latency." }, { "name": "model.inference_geo", "type": "string or null", "required": false, "description": "Geographic region for model inference. When unset, requests fall through to the workspace's default_inference_geo. On update, `model` is whole-object replacement — omitting inference_geo clears it." }, { "name": "model.speed", "type": "\"standard\" or \"fast\" or null", "required": false, "description": "Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time.", "enum": [ "standard", "fast" ] }, { "name": "multiagent", "type": "BetaManagedAgentsMultiagentParams or null", "required": false, "description": "A coordinator topology: the session's primary thread orchestrates work by spawning session threads, each running an agent drawn from the `agents` roster." }, { "name": "multiagent.type", "type": "\"coordinator\"", "required": true, "description": "" }, { "name": "multiagent.agents", "type": "array of BetaManagedAgentsMultiagentRosterEntryParams", "required": true, "description": "Agents the coordinator may spawn as session threads. 1–20 entries. Each entry is an agent ID string, a versioned `{\"type\":\"agent\",\"id\",\"version\"}` reference, or `{\"type\":\"self\"}` to allow recursive self-invocation. Entries must reference distinct agents (after resolving `self` and string forms); at most one `self`. Referenced agents must exist, must not be archived, and must not themselves have `multiagent` set (depth limit 1)." }, { "name": "multiagent.agents", "type": "string", "required": false, "description": "" }, { "name": "multiagent.agents", "type": "BetaManagedAgentsAgentParams object", "required": false, "description": "Specification for an Agent. Provide a specific `version` or use the short-form `agent=\"agent_id\"` for the most recent version" }, { "name": "multiagent.agents.type", "type": "\"agent\"", "required": true, "description": "" }, { "name": "multiagent.agents.id", "type": "string", "required": true, "description": "The `agent` ID.", "constraints": { "minLength": "1", "maxLength": "128" } }, { "name": "multiagent.agents.version", "type": "number", "required": false, "description": "The specific `agent` version to use. Omit to use the latest version. Must be at least 1 if specified.", "constraints": { "format": "int32" } }, { "name": "multiagent.agents", "type": "BetaManagedAgentsMultiagentSelfParams object", "required": false, "description": "Sentinel roster entry meaning \"the agent that owns this configuration\". Resolved server-side to a concrete agent reference." }, { "name": "multiagent.agents.type", "type": "\"self\"", "required": true, "description": "" }, { "name": "multiagent.agents", "type": "BetaManagedAgentsAdvisorParams object", "required": false, "description": "Platform advisor roster entry: a model the session's primary thread may consult mid-turn. At most one per roster; the entry occupies the roster name `anthropic.advisor`." }, { "name": "multiagent.agents.type", "type": "\"advisor\"", "required": true, "description": "" }, { "name": "multiagent.agents.model", "type": "string", "required": true, "description": "A Claude model id. The model must be permitted as an advisor for this agent's model — see the sessions/threads/advisor spec.", "constraints": { "minLength": "1", "maxLength": "256" } }, { "name": "name", "type": "string", "required": false, "description": "Human-readable name. Must be non-empty. Omit to preserve. Cannot be cleared.", "constraints": { "maxLength": "256" } }, { "name": "skills", "type": "array of BetaManagedAgentsSkillParams or null", "required": false, "description": "Skills. Full replacement. Omit to preserve; send empty array or null to clear." }, { "name": "skills", "type": "BetaManagedAgentsAnthropicSkillParams object", "required": false, "description": "An Anthropic-managed skill." }, { "name": "skills.type", "type": "\"anthropic\"", "required": true, "description": "" }, { "name": "skills.skill_id", "type": "string", "required": true, "description": "Identifier of the Anthropic skill (e.g., \"xlsx\").", "constraints": { "minLength": "1", "maxLength": "64" } }, { "name": "skills.version", "type": "string or null", "required": false, "description": "Version to pin. Defaults to latest if omitted.", "constraints": { "minLength": "1", "maxLength": "64" } }, { "name": "skills", "type": "BetaManagedAgentsCustomSkillParams object", "required": false, "description": "A user-created custom skill." }, { "name": "skills.type", "type": "\"custom\"", "required": true, "description": "" }, { "name": "skills.skill_id", "type": "string", "required": true, "description": "Tagged ID of the custom skill (e.g., \"skill_01XJ5...\").", "constraints": { "minLength": "1", "maxLength": "64" } }, { "name": "skills.version", "type": "string or null", "required": false, "description": "Version to pin. Defaults to latest if omitted.", "constraints": { "minLength": "1", "maxLength": "64" } }, { "name": "system", "type": "string or null", "required": false, "description": "System prompt. Omit to preserve; send empty string or null to clear.", "constraints": { "maxLength": "100000" } }, { "name": "tools", "type": "array of BetaManagedAgentsAgentToolset20260401Params or BetaManagedAgentsMCPToolsetParams or BetaManagedAgentsCustomToolParams or null", "required": false, "description": "Tool configurations available to the agent. Full replacement. Omit to preserve; send empty array or null to clear. Maximum of 128 tools across all toolsets allowed." }, { "name": "tools", "type": "BetaManagedAgentsAgentToolset20260401Params object", "required": false, "description": "Configuration for built-in agent tools. Use this to enable or disable groups of tools available to the agent." }, { "name": "tools.type", "type": "\"agent_toolset_20260401\"", "required": true, "description": "" }, { "name": "tools.configs", "type": "array of BetaManagedAgentsAgentToolConfigParams", "required": false, "description": "Per-tool configuration overrides." }, { "name": "tools.configs", "type": "BetaManagedAgentsBashToolConfigParams object", "required": false, "description": "Configuration override for the bash tool." }, { "name": "tools.configs", "type": "BetaManagedAgentsEditToolConfigParams object", "required": false, "description": "Configuration override for the edit tool." }, { "name": "tools.configs", "type": "BetaManagedAgentsReadToolConfigParams object", "required": false, "description": "Configuration override for the read tool." }, { "name": "tools.configs", "type": "BetaManagedAgentsWriteToolConfigParams object", "required": false, "description": "Configuration override for the write tool." }, { "name": "tools.configs", "type": "BetaManagedAgentsGlobToolConfigParams object", "required": false, "description": "Configuration override for the glob tool." }, { "name": "tools.configs", "type": "BetaManagedAgentsGrepToolConfigParams object", "required": false, "description": "Configuration override for the grep tool." }, { "name": "tools.configs", "type": "BetaManagedAgentsWebFetchToolConfigParams object", "required": false, "description": "Configuration override for the web_fetch tool." }, { "name": "tools.configs", "type": "BetaManagedAgentsWebSearchToolConfigParams object", "required": false, "description": "Configuration override for the web_search tool." }, { "name": "tools.default_config", "type": "BetaManagedAgentsAgentToolsetDefaultConfigParams or null", "required": false, "description": "Default configuration for all tools in a toolset." }, { "name": "tools.default_config.enabled", "type": "boolean or null", "required": false, "description": "Whether tools are enabled and available to Claude by default. Defaults to true if not specified." }, { "name": "tools.default_config.permission_policy", "type": "BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy or null", "required": false, "description": "Permission policy for tool execution." }, { "name": "tools", "type": "BetaManagedAgentsMCPToolsetParams object", "required": false, "description": "Configuration for tools from an MCP server defined in `mcp_servers`." }, { "name": "tools.type", "type": "\"mcp_toolset\"", "required": true, "description": "" }, { "name": "tools.mcp_server_name", "type": "string", "required": true, "description": "Name of the MCP server. Must match a server name from the mcp_servers array. 1-255 characters.", "constraints": { "minLength": "1", "maxLength": "255" } }, { "name": "tools.configs", "type": "array of BetaManagedAgentsMCPToolConfigParams", "required": false, "description": "Per-tool configuration overrides." }, { "name": "tools.configs.name", "type": "string", "required": true, "description": "Name of the MCP tool to configure. 1-128 characters.", "constraints": { "minLength": "1", "maxLength": "128" } }, { "name": "tools.configs.enabled", "type": "boolean or null", "required": false, "description": "Whether this tool is enabled. Overrides the `default_config` setting." }, { "name": "tools.configs.permission_policy", "type": "BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy or null", "required": false, "description": "Permission policy for tool execution." }, { "name": "tools.default_config", "type": "BetaManagedAgentsMCPToolsetDefaultConfigParams or null", "required": false, "description": "Default configuration for all tools from an MCP server." }, { "name": "tools.default_config.enabled", "type": "boolean or null", "required": false, "description": "Whether tools are enabled by default. Defaults to true if not specified." }, { "name": "tools.default_config.permission_policy", "type": "BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy or null", "required": false, "description": "Permission policy for tool execution." }, { "name": "tools", "type": "BetaManagedAgentsCustomToolParams object", "required": false, "description": "A custom tool that is executed by the API client rather than the agent. When the agent calls this tool, an `agent.custom_tool_use` event is emitted and the session goes idle, waiting for the client to provide the result via a `user.custom_tool_result` event." }, { "name": "tools.type", "type": "\"custom\"", "required": true, "description": "" }, { "name": "tools.description", "type": "string", "required": true, "description": "Description of what the tool does, shown to the agent to help it decide when to use the tool.", "constraints": { "minLength": "1" } }, { "name": "tools.input_schema", "type": "BetaManagedAgentsCustomToolInputSchema", "required": true, "description": "JSON Schema for custom tool input parameters." }, { "name": "tools.input_schema.type", "type": "\"object\"", "required": true, "description": "" }, { "name": "tools.input_schema.properties", "type": "map[unknown] or null", "required": false, "description": "" }, { "name": "tools.input_schema.required", "type": "array of string or null", "required": false, "description": "" }, { "name": "tools.name", "type": "string", "required": true, "description": "Unique name for the tool. 1-128 characters; letters, digits, underscores, and hyphens.", "constraints": { "minLength": "1", "maxLength": "128" } }, { "name": "version", "type": "number", "required": false, "description": "The agent's current version, used to prevent concurrent overwrites. Obtain this value from a create or retrieve response. Must be at least 1 if specified. When supplied, the request fails if it does not match the server's current version; omit to apply the update unconditionally.", "constraints": { "format": "int32" } } ], "status": [ "DOCUMENTED", "BETA" ], "sources": [ { "url": "https://platform.claude.com/docs/en/api/beta/agents/update", "retrieved_at": "2026-09-18" }, { "url": "https://platform.claude.com/docs/en/managed-agents/agent-setup", "retrieved_at": "2026-09-18" } ], "beta_header": "managed-agents-2026-04-01", "_fragment": "generated/fragments/objects/anthropic-platform-objects.json" }, { "provider": "anthropic", "api_family": "managed-agents", "name": "Session", "official_type_name": "BetaManagedAgentsSession", "description": "A Managed Agents `session`.", "fields": [ { "name": "type", "type": "\"session\"", "required": true, "description": "" }, { "name": "id", "type": "string", "required": true, "description": "" }, { "name": "agent", "type": "BetaManagedAgentsSessionAgent", "required": true, "description": "Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time." }, { "name": "agent.type", "type": "\"agent\"", "required": true, "description": "" }, { "name": "agent.id", "type": "string", "required": true, "description": "" }, { "name": "agent.description", "type": "string or null", "required": true, "description": "" }, { "name": "agent.mcp_servers", "type": "array of BetaManagedAgentsMCPServerURLDefinition", "required": true, "description": "" }, { "name": "agent.mcp_servers.type", "type": "\"url\"", "required": true, "description": "" }, { "name": "agent.mcp_servers.name", "type": "string", "required": true, "description": "" }, { "name": "agent.mcp_servers.url", "type": "string", "required": true, "description": "" }, { "name": "agent.model", "type": "BetaManagedAgentsModelConfig", "required": true, "description": "Model identifier and configuration." }, { "name": "agent.model.id", "type": "BetaManagedAgentsModel", "required": true, "description": "The model that will power your agent. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options." }, { "name": "agent.model.id<\"claude-fable-5-1\" or \"claude-sonnet-5\" or \"claude-fable-5\" or 11 more>", "type": "\"claude-fable-5-1\" or \"claude-sonnet-5\" or \"claude-fable-5\" or 11 more", "required": false, "description": "The model that will power your agent. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options." }, { "name": "agent.model.id", "type": "string", "required": false, "description": "" }, { "name": "agent.model.effort", "type": "BetaManagedAgentsEffortLow or BetaManagedAgentsEffortMedium or BetaManagedAgentsEffortHigh or 2 more", "required": false, "description": "How hard Claude works on each turn. Sets `output_config.effort` on every Messages call the session makes." }, { "name": "agent.model.effort", "type": "BetaManagedAgentsEffortLow object", "required": false, "description": "Low effort. Favors latency over reasoning depth." }, { "name": "agent.model.effort.type", "type": "\"low\"", "required": true, "description": "" }, { "name": "agent.model.effort", "type": "BetaManagedAgentsEffortMedium object", "required": false, "description": "Medium effort. Balances latency and reasoning depth." }, { "name": "agent.model.effort.type", "type": "\"medium\"", "required": true, "description": "" }, { "name": "agent.model.effort", "type": "BetaManagedAgentsEffortHigh object", "required": false, "description": "High effort. Favors reasoning depth." }, { "name": "agent.model.effort.type", "type": "\"high\"", "required": true, "description": "" }, { "name": "agent.model.effort", "type": "BetaManagedAgentsEffortXhigh object", "required": false, "description": "Extra-high effort. Not all models accept this level." }, { "name": "agent.model.effort.type", "type": "\"xhigh\"", "required": true, "description": "" }, { "name": "agent.model.effort", "type": "BetaManagedAgentsEffortMax object", "required": false, "description": "Maximum effort. Favors reasoning depth over latency." }, { "name": "agent.model.effort.type", "type": "\"max\"", "required": true, "description": "" }, { "name": "agent.model.inference_geo", "type": "string", "required": false, "description": "Geographic region for model inference. When unset, requests fall through to the workspace's default_inference_geo." }, { "name": "agent.model.speed", "type": "\"standard\" or \"fast\"", "required": false, "description": "Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time.", "enum": [ "standard", "fast" ] }, { "name": "agent.multiagent", "type": "BetaManagedAgentsSessionMultiagentCoordinator or null", "required": true, "description": "Resolved coordinator topology with full agent definitions for each roster member." }, { "name": "agent.multiagent.type", "type": "\"coordinator\"", "required": true, "description": "" }, { "name": "agent.multiagent.agents", "type": "array of BetaManagedAgentsSessionThreadAgent or BetaManagedAgentsAdvisor", "required": true, "description": "Full `agent` definitions the coordinator may spawn as session threads." }, { "name": "agent.multiagent.agents", "type": "BetaManagedAgentsSessionThreadAgent object", "required": false, "description": "Resolved `agent` definition for a single `session_thread`. Snapshot of the agent at thread creation time. The multiagent roster is not repeated here; read it from `Session.agent`." }, { "name": "agent.multiagent.agents.type", "type": "\"agent\"", "required": true, "description": "" }, { "name": "agent.multiagent.agents.id", "type": "string", "required": true, "description": "" }, { "name": "agent.multiagent.agents.description", "type": "string or null", "required": true, "description": "" }, { "name": "agent.multiagent.agents.mcp_servers", "type": "array of BetaManagedAgentsMCPServerURLDefinition", "required": true, "description": "" }, { "name": "agent.multiagent.agents.model", "type": "BetaManagedAgentsModelConfig", "required": true, "description": "Model identifier and configuration." }, { "name": "agent.multiagent.agents.name", "type": "string", "required": true, "description": "" }, { "name": "agent.multiagent.agents.skills", "type": "array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill", "required": true, "description": "" }, { "name": "agent.multiagent.agents.system", "type": "string or null", "required": true, "description": "" }, { "name": "agent.multiagent.agents.tools", "type": "array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool", "required": true, "description": "" }, { "name": "agent.multiagent.agents.version", "type": "number", "required": true, "description": "", "constraints": { "format": "int32" } }, { "name": "agent.multiagent.agents", "type": "BetaManagedAgentsAdvisor object", "required": false, "description": "Platform advisor roster entry: a model the session's primary thread may consult mid-turn." }, { "name": "agent.multiagent.agents.type", "type": "\"advisor\"", "required": true, "description": "" }, { "name": "agent.multiagent.agents.model", "type": "string", "required": true, "description": "The advisor model id." }, { "name": "agent.name", "type": "string", "required": true, "description": "" }, { "name": "agent.skills", "type": "array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill", "required": true, "description": "" }, { "name": "agent.skills", "type": "BetaManagedAgentsAnthropicSkill object", "required": false, "description": "A resolved Anthropic-managed skill." }, { "name": "agent.skills", "type": "BetaManagedAgentsCustomSkill object", "required": false, "description": "A resolved user-created custom skill." }, { "name": "agent.system", "type": "string or null", "required": true, "description": "" }, { "name": "agent.tools", "type": "array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool", "required": true, "description": "" }, { "name": "agent.tools", "type": "BetaManagedAgentsAgentToolset20260401 object", "required": false, "description": "" }, { "name": "agent.tools", "type": "BetaManagedAgentsMCPToolset object", "required": false, "description": "" }, { "name": "agent.tools", "type": "BetaManagedAgentsCustomTool object", "required": false, "description": "A custom tool as returned in API responses." }, { "name": "agent.version", "type": "number", "required": true, "description": "", "constraints": { "format": "int32" } }, { "name": "archived_at", "type": "string or null", "required": true, "description": "A timestamp in RFC 3339 format", "constraints": { "format": "date-time" } }, { "name": "budget", "type": "BetaManagedAgentsBudgetLimit or null", "required": true, "description": "A hard spend ceiling. The session stops issuing new model requests once the tracked list cost reaches `max_list_cost`." }, { "name": "budget.type", "type": "\"limit\"", "required": true, "description": "" }, { "name": "budget.max_list_cost", "type": "BetaMonetaryAmount", "required": true, "description": "A monetary amount in a specific currency." }, { "name": "budget.max_list_cost.amount", "type": "string", "required": true, "description": "Amount in minor units of the currency, as an integer decimal string with no leading zeros: \"2500\" is $25.00 and \"50\" is fifty cents. A string rather than a number so no float rounding is ever applied." }, { "name": "budget.max_list_cost.currency", "type": "BetaCurrency", "required": true, "description": "Uppercase ISO-4217 currency code. `USD` is the only currency currently supported; the accepted set is closed and grows only when a new currency is priced." }, { "name": "created_at", "type": "string", "required": true, "description": "A timestamp in RFC 3339 format", "constraints": { "format": "date-time" } }, { "name": "environment_id", "type": "string", "required": true, "description": "" }, { "name": "metadata", "type": "map[string]", "required": true, "description": "" }, { "name": "outcome_evaluations", "type": "array of BetaManagedAgentsOutcomeEvaluationResource", "required": true, "description": "Per-outcome evaluation state. One entry per `define_outcome` event sent to the session." }, { "name": "outcome_evaluations.type", "type": "\"outcome_evaluation\"", "required": true, "description": "" }, { "name": "outcome_evaluations.completed_at", "type": "string or null", "required": true, "description": "A timestamp in RFC 3339 format", "constraints": { "format": "date-time" } }, { "name": "outcome_evaluations.description", "type": "string", "required": true, "description": "What the agent should produce." }, { "name": "outcome_evaluations.explanation", "type": "string or null", "required": true, "description": "Grader's verdict text from the most recent evaluation. For `satisfied`, explains why criteria are met; for `needs_revision` (intermediate), what's missing; for `failed`, why unrecoverable." }, { "name": "outcome_evaluations.iteration", "type": "number", "required": true, "description": "0-indexed revision cycle the outcome is currently on.", "constraints": { "format": "int32" } }, { "name": "outcome_evaluations.outcome_id", "type": "string", "required": true, "description": "Server-generated outc_ ID for this outcome." }, { "name": "outcome_evaluations.result", "type": "string", "required": true, "description": "Current evaluation state. `pending` before the agent begins work; `running` while producing or revising; `evaluating` while the grader scores; `satisfied`/`max_iterations_reached`/`failed`/`interrupted` are terminal." }, { "name": "resources", "type": "array of BetaManagedAgentsSessionResource", "required": true, "description": "" }, { "name": "resources", "type": "BetaManagedAgentsGitHubRepositoryResource object", "required": false, "description": "" }, { "name": "resources.type", "type": "\"github_repository\"", "required": true, "description": "" }, { "name": "resources.id", "type": "string", "required": true, "description": "" }, { "name": "resources.created_at", "type": "string", "required": true, "description": "A timestamp in RFC 3339 format", "constraints": { "format": "date-time" } }, { "name": "resources.mount_path", "type": "string", "required": true, "description": "" }, { "name": "resources.updated_at", "type": "string", "required": true, "description": "A timestamp in RFC 3339 format", "constraints": { "format": "date-time" } }, { "name": "resources.url", "type": "string", "required": true, "description": "" }, { "name": "resources.checkout", "type": "BetaManagedAgentsBranchCheckout or BetaManagedAgentsCommitCheckout or null", "required": false, "description": "" }, { "name": "resources.checkout", "type": "BetaManagedAgentsBranchCheckout object", "required": false, "description": "" }, { "name": "resources.checkout.type", "type": "\"branch\"", "required": true, "description": "" }, { "name": "resources.checkout.name", "type": "string", "required": true, "description": "Branch name to check out.", "constraints": { "minLength": "1", "maxLength": "255" } }, { "name": "resources.checkout", "type": "BetaManagedAgentsCommitCheckout object", "required": false, "description": "" }, { "name": "resources.checkout.type", "type": "\"commit\"", "required": true, "description": "" }, { "name": "resources.checkout.sha", "type": "string", "required": true, "description": "Full commit SHA to check out.", "constraints": { "minLength": "7", "maxLength": "64" } }, { "name": "resources", "type": "BetaManagedAgentsFileResource object", "required": false, "description": "" }, { "name": "resources.type", "type": "\"file\"", "required": true, "description": "" }, { "name": "resources.id", "type": "string", "required": true, "description": "" }, { "name": "resources.created_at", "type": "string", "required": true, "description": "A timestamp in RFC 3339 format", "constraints": { "format": "date-time" } }, { "name": "resources.file_id", "type": "string", "required": true, "description": "" }, { "name": "resources.mount_path", "type": "string", "required": true, "description": "" }, { "name": "resources.updated_at", "type": "string", "required": true, "description": "A timestamp in RFC 3339 format", "constraints": { "format": "date-time" } }, { "name": "resources", "type": "BetaManagedAgentsMemoryStoreResource object", "required": false, "description": "A memory store attached to an agent session." }, { "name": "resources.type", "type": "\"memory_store\"", "required": true, "description": "" }, { "name": "resources.memory_store_id", "type": "string", "required": true, "description": "The memory store ID (memstore_...). Must belong to the caller's organization and workspace." }, { "name": "resources.access", "type": "\"read_write\" or \"read_only\" or null", "required": false, "description": "Access mode for an attached memory store.", "enum": [ "read_write", "read_only" ] }, { "name": "resources.description", "type": "string", "required": false, "description": "Description of the memory store, snapshotted at attach time. Rendered into the agent's system prompt. Empty string when the store has no description." }, { "name": "resources.instructions", "type": "string or null", "required": false, "description": "Per-attachment guidance for the agent on how to use this store. Rendered into the memory section of the system prompt. Max 4096 chars.", "constraints": { "maxLength": "4096" } }, { "name": "resources.mount_path", "type": "string or null", "required": false, "description": "Filesystem path where the store is mounted in the session container, e.g. /mnt/memory/user-preferences. Derived from the store's name. Output-only." }, { "name": "resources.name", "type": "string or null", "required": false, "description": "Display name of the memory store, snapshotted at attach time. Later edits to the store's name do not propagate to this resource." }, { "name": "stats", "type": "BetaManagedAgentsSessionStats", "required": true, "description": "Timing statistics for a session." }, { "name": "stats.active_seconds", "type": "number", "required": false, "description": "Cumulative time in seconds the session spent in `running` status. Excludes idle time.", "constraints": { "format": "double" } }, { "name": "stats.duration_seconds", "type": "number", "required": false, "description": "Elapsed time since session creation in seconds. For terminated sessions, frozen at the final update.", "constraints": { "format": "double" } }, { "name": "status", "type": "\"rescheduling\" or \"running\" or \"idle\" or \"terminated\"", "required": true, "description": "SessionStatus enum", "enum": [ "rescheduling", "running", "idle", "terminated" ] }, { "name": "title", "type": "string or null", "required": true, "description": "" }, { "name": "updated_at", "type": "string", "required": true, "description": "A timestamp in RFC 3339 format", "constraints": { "format": "date-time" } }, { "name": "usage", "type": "BetaManagedAgentsSessionUsage", "required": true, "description": "Cumulative token usage for a session across all turns." }, { "name": "usage.active_seconds", "type": "number", "required": false, "description": "Cumulative time in seconds during which the session had at least one thread in running status. Overlapping activity from concurrent threads is counted once, unlike `stats.active_seconds`, which sums each thread's own active time. This is the duration the session's runtime cost is priced on.", "constraints": { "format": "double" } }, { "name": "usage.cache_creation", "type": "BetaManagedAgentsCacheCreationUsage", "required": false, "description": "Prompt-cache creation token usage broken down by cache lifetime." }, { "name": "usage.cache_creation.ephemeral_1h_input_tokens", "type": "number", "required": false, "description": "Tokens used to create 1-hour ephemeral cache entries.", "constraints": { "format": "int32" } }, { "name": "usage.cache_creation.ephemeral_5m_input_tokens", "type": "number", "required": false, "description": "Tokens used to create 5-minute ephemeral cache entries.", "constraints": { "format": "int32" } }, { "name": "usage.cache_read_input_tokens", "type": "number", "required": false, "description": "Total tokens read from prompt cache.", "constraints": { "format": "int32" } }, { "name": "usage.input_tokens", "type": "number", "required": false, "description": "Total input tokens consumed across all turns.", "constraints": { "format": "int32" } }, { "name": "usage.list_cost", "type": "BetaMonetaryAmount or null", "required": false, "description": "A monetary amount in a specific currency." }, { "name": "usage.output_tokens", "type": "number", "required": false, "description": "Total output tokens generated across all turns.", "constraints": { "format": "int32" } }, { "name": "usage.server_tool_use", "type": "BetaManagedAgentsServerToolUsage or null", "required": false, "description": "Cumulative count of server-executed tool invocations, broken down by tool." }, { "name": "usage.server_tool_use.web_fetch_requests", "type": "number", "required": false, "description": "Number of server-executed web fetch requests.", "constraints": { "format": "int32" } }, { "name": "usage.server_tool_use.web_search_requests", "type": "number", "required": false, "description": "Number of server-executed web search requests.", "constraints": { "format": "int32" } }, { "name": "vault_ids", "type": "array of string", "required": true, "description": "Vault IDs attached to the session at creation. Empty when no vaults were supplied." }, { "name": "deployment_id", "type": "string or null", "required": false, "description": "Deployment ID when the session was created from a deployment reference. Null otherwise." } ], "status": [ "DOCUMENTED", "BETA" ], "sources": [ { "url": "https://platform.claude.com/docs/en/api/beta/sessions/create", "retrieved_at": "2026-09-18" }, { "url": "https://platform.claude.com/docs/en/managed-agents/sessions", "retrieved_at": "2026-09-18" }, { "url": "https://platform.claude.com/docs/en/managed-agents/session-operations", "retrieved_at": "2026-09-18" } ], "beta_header": "managed-agents-2026-04-01", "_fragment": "generated/fragments/objects/anthropic-platform-objects.json" }, { "provider": "anthropic", "api_family": "managed-agents", "name": "SessionCreateParams (request body)", "official_type_name": "BetaManagedAgentsSessionCreateParams", "description": "Create Session", "fields": [ { "name": "agent", "type": "string or BetaManagedAgentsAgentParams or BetaManagedAgentsAgentWithOverridesParams", "required": true, "description": "Agent identifier. Accepts the `agent` ID string, which pins the latest version for the session, or an `agent` object with both id and version specified." }, { "name": "agent", "type": "string", "required": false, "description": "" }, { "name": "agent", "type": "BetaManagedAgentsAgentParams object", "required": false, "description": "Specification for an Agent. Provide a specific `version` or use the short-form `agent=\"agent_id\"` for the most recent version" }, { "name": "agent.type", "type": "\"agent\"", "required": true, "description": "" }, { "name": "agent.id", "type": "string", "required": true, "description": "The `agent` ID.", "constraints": { "minLength": "1", "maxLength": "128" } }, { "name": "agent.version", "type": "number", "required": false, "description": "The specific `agent` version to use. Omit to use the latest version. Must be at least 1 if specified.", "constraints": { "format": "int32" } }, { "name": "agent", "type": "BetaManagedAgentsAgentWithOverridesParams object", "required": false, "description": "Reference to an `agent` plus optional configuration overrides. Each provided field replaces the agent's value for the caller's use; the agent resource is unchanged." }, { "name": "agent.type", "type": "\"agent_with_overrides\"", "required": true, "description": "" }, { "name": "agent.id", "type": "string", "required": true, "description": "The `agent` ID.", "constraints": { "minLength": "1", "maxLength": "128" } }, { "name": "agent.mcp_servers", "type": "array of BetaManagedAgentsURLMCPServerParams", "required": false, "description": "Replacement MCP server list. Full replacement: the provided array becomes the MCP servers. Send an empty array to clear; omit to preserve the agent's servers." }, { "name": "agent.mcp_servers.type", "type": "\"url\"", "required": true, "description": "" }, { "name": "agent.mcp_servers.name", "type": "string", "required": true, "description": "Unique name for this server, referenced by mcp_toolset configurations. 1-255 characters.", "constraints": { "minLength": "1", "maxLength": "255" } }, { "name": "agent.mcp_servers.url", "type": "string", "required": true, "description": "Endpoint URL for the MCP server.", "constraints": { "maxLength": "2048" } }, { "name": "agent.model", "type": "BetaManagedAgentsModel or BetaManagedAgentsModelConfigParams", "required": false, "description": "Replacement model. Accepts the model string, e.g. `claude-opus-5`, or a `model_config` object. Omit to use the agent's model." }, { "name": "agent.model", "type": "BetaManagedAgentsModel = \"claude-fable-5-1\" or \"claude-sonnet-5\" or \"claude-fable-5\" or 11 more or string", "required": false, "description": "The model that will power your agent. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options." }, { "name": "agent.model<\"claude-fable-5-1\" or \"claude-sonnet-5\" or \"claude-fable-5\" or 11 more>", "type": "\"claude-fable-5-1\" or \"claude-sonnet-5\" or \"claude-fable-5\" or 11 more", "required": false, "description": "The model that will power your agent. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options." }, { "name": "agent.model", "type": "string", "required": false, "description": "" }, { "name": "agent.model", "type": "BetaManagedAgentsModelConfigParams object", "required": false, "description": "An object that defines additional configuration control over model use" }, { "name": "agent.model.id", "type": "BetaManagedAgentsModel", "required": true, "description": "The model that will power your agent. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options." }, { "name": "agent.model.effort", "type": "\"low\" or \"medium\" or \"high\" or 2 more or BetaManagedAgentsEffortLow or BetaManagedAgentsEffortMedium or 3 more or null", "required": false, "description": "How hard Claude works on each inference call. Accepts a bare level string (`\"high\"`) or `{\"type\": \"high\"}`. On create, omitting it resolves the per-model default; on update, omitting it leaves the stored value unchanged." }, { "name": "agent.model.inference_geo", "type": "string or null", "required": false, "description": "Geographic region for model inference. When unset, requests fall through to the workspace's default_inference_geo. On update, `model` is whole-object replacement — omitting inference_geo clears it." }, { "name": "agent.model.speed", "type": "\"standard\" or \"fast\" or null", "required": false, "description": "Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time.", "enum": [ "standard", "fast" ] }, { "name": "agent.skills", "type": "array of BetaManagedAgentsSkillParams", "required": false, "description": "Replacement skill list. Full replacement: the provided array becomes the skills. Send an empty array to clear; omit to preserve the agent's skills." }, { "name": "agent.skills", "type": "BetaManagedAgentsAnthropicSkillParams object", "required": false, "description": "An Anthropic-managed skill." }, { "name": "agent.skills.type", "type": "\"anthropic\"", "required": true, "description": "" }, { "name": "agent.skills.skill_id", "type": "string", "required": true, "description": "Identifier of the Anthropic skill (e.g., \"xlsx\").", "constraints": { "minLength": "1", "maxLength": "64" } }, { "name": "agent.skills.version", "type": "string or null", "required": false, "description": "Version to pin. Defaults to latest if omitted.", "constraints": { "minLength": "1", "maxLength": "64" } }, { "name": "agent.skills", "type": "BetaManagedAgentsCustomSkillParams object", "required": false, "description": "A user-created custom skill." }, { "name": "agent.skills.type", "type": "\"custom\"", "required": true, "description": "" }, { "name": "agent.skills.skill_id", "type": "string", "required": true, "description": "Tagged ID of the custom skill (e.g., \"skill_01XJ5...\").", "constraints": { "minLength": "1", "maxLength": "64" } }, { "name": "agent.skills.version", "type": "string or null", "required": false, "description": "Version to pin. Defaults to latest if omitted.", "constraints": { "minLength": "1", "maxLength": "64" } }, { "name": "agent.system", "type": "string or null", "required": false, "description": "Replacement system prompt. Up to 100,000 characters. Set to null to clear the agent's system prompt; omit to preserve it.", "constraints": { "maxLength": "100000" } }, { "name": "agent.tools", "type": "array of BetaManagedAgentsAgentToolset20260401Params or BetaManagedAgentsMCPToolsetParams or BetaManagedAgentsCustomToolParams", "required": false, "description": "Replacement tool list. Full replacement: the provided array becomes the tool configuration. Send an empty array to clear; omit to preserve the agent's tools." }, { "name": "agent.tools", "type": "BetaManagedAgentsAgentToolset20260401Params object", "required": false, "description": "Configuration for built-in agent tools. Use this to enable or disable groups of tools available to the agent." }, { "name": "agent.tools.type", "type": "\"agent_toolset_20260401\"", "required": true, "description": "" }, { "name": "agent.tools.configs", "type": "array of BetaManagedAgentsAgentToolConfigParams", "required": false, "description": "Per-tool configuration overrides." }, { "name": "agent.tools.default_config", "type": "BetaManagedAgentsAgentToolsetDefaultConfigParams or null", "required": false, "description": "Default configuration for all tools in a toolset." }, { "name": "agent.tools", "type": "BetaManagedAgentsMCPToolsetParams object", "required": false, "description": "Configuration for tools from an MCP server defined in `mcp_servers`." }, { "name": "agent.tools.type", "type": "\"mcp_toolset\"", "required": true, "description": "" }, { "name": "agent.tools.mcp_server_name", "type": "string", "required": true, "description": "Name of the MCP server. Must match a server name from the mcp_servers array. 1-255 characters.", "constraints": { "minLength": "1", "maxLength": "255" } }, { "name": "agent.tools.configs", "type": "array of BetaManagedAgentsMCPToolConfigParams", "required": false, "description": "Per-tool configuration overrides." }, { "name": "agent.tools.default_config", "type": "BetaManagedAgentsMCPToolsetDefaultConfigParams or null", "required": false, "description": "Default configuration for all tools from an MCP server." }, { "name": "agent.tools", "type": "BetaManagedAgentsCustomToolParams object", "required": false, "description": "A custom tool that is executed by the API client rather than the agent. When the agent calls this tool, an `agent.custom_tool_use` event is emitted and the session goes idle, waiting for the client to provide the result via a `user.custom_tool_result` event." }, { "name": "agent.tools.type", "type": "\"custom\"", "required": true, "description": "" }, { "name": "agent.tools.description", "type": "string", "required": true, "description": "Description of what the tool does, shown to the agent to help it decide when to use the tool.", "constraints": { "minLength": "1" } }, { "name": "agent.tools.input_schema", "type": "BetaManagedAgentsCustomToolInputSchema", "required": true, "description": "JSON Schema for custom tool input parameters." }, { "name": "agent.tools.name", "type": "string", "required": true, "description": "Unique name for the tool. 1-128 characters; letters, digits, underscores, and hyphens.", "constraints": { "minLength": "1", "maxLength": "128" } }, { "name": "agent.version", "type": "number", "required": false, "description": "The specific `agent` version to use. Omit to use the latest version.", "constraints": { "format": "int32" } }, { "name": "environment_id", "type": "string", "required": true, "description": "ID of the `environment` defining the container configuration for this session.", "constraints": { "minLength": "1", "maxLength": "128" } }, { "name": "budget", "type": "BetaManagedAgentsBudgetLimit", "required": false, "description": "A hard spend ceiling. The session stops issuing new model requests once the tracked list cost reaches `max_list_cost`." }, { "name": "budget.type", "type": "\"limit\"", "required": true, "description": "" }, { "name": "budget.max_list_cost", "type": "BetaMonetaryAmount", "required": true, "description": "A monetary amount in a specific currency." }, { "name": "budget.max_list_cost.amount", "type": "string", "required": true, "description": "Amount in minor units of the currency, as an integer decimal string with no leading zeros: \"2500\" is $25.00 and \"50\" is fifty cents. A string rather than a number so no float rounding is ever applied." }, { "name": "budget.max_list_cost.currency", "type": "BetaCurrency", "required": true, "description": "Uppercase ISO-4217 currency code. `USD` is the only currency currently supported; the accepted set is closed and grows only when a new currency is priced." }, { "name": "initial_events", "type": "array of BetaManagedAgentsUserMessageEventParams or BetaManagedAgentsUserDefineOutcomeEventParams", "required": false, "description": "Initial events to send to the `session` at creation, processed in order. Supports `user.message` and `user.define_outcome` events. Maximum 50 events." }, { "name": "initial_events", "type": "BetaManagedAgentsUserMessageEventParams object", "required": false, "description": "Parameters for sending a user message to the session." }, { "name": "initial_events.type", "type": "\"user.message\"", "required": true, "description": "" }, { "name": "initial_events.content", "type": "array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsRedactedBlock", "required": true, "description": "Array of content blocks for the user message." }, { "name": "initial_events.content", "type": "BetaManagedAgentsTextBlock object", "required": false, "description": "Regular text content." }, { "name": "initial_events.content.type", "type": "\"text\"", "required": true, "description": "" }, { "name": "initial_events.content.text", "type": "string", "required": true, "description": "The text content.", "constraints": { "minLength": "1" } }, { "name": "initial_events.content", "type": "BetaManagedAgentsImageBlock object", "required": false, "description": "Image content specified directly as base64 data or as a reference via a URL." }, { "name": "initial_events.content.type", "type": "\"image\"", "required": true, "description": "" }, { "name": "initial_events.content.source", "type": "BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource", "required": true, "description": "Union type for image source variants." }, { "name": "initial_events.content", "type": "BetaManagedAgentsDocumentBlock object", "required": false, "description": "Document content, either specified directly as base64 data, as text, or as a reference via a URL." }, { "name": "initial_events.content.type", "type": "\"document\"", "required": true, "description": "" }, { "name": "initial_events.content.source", "type": "BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource", "required": true, "description": "Union type for document source variants." }, { "name": "initial_events.content.context", "type": "string or null", "required": false, "description": "Additional context about the document for the model." }, { "name": "initial_events.content.title", "type": "string or null", "required": false, "description": "The title of the document." }, { "name": "initial_events.content", "type": "BetaManagedAgentsRedactedBlock object", "required": false, "description": "Placeholder for content withheld by Anthropic model policy." }, { "name": "initial_events.content.type", "type": "\"redacted\"", "required": true, "description": "" }, { "name": "initial_events", "type": "BetaManagedAgentsUserDefineOutcomeEventParams object", "required": false, "description": "Parameters for defining an outcome the agent should work toward. The agent begins work on receipt." }, { "name": "initial_events.type", "type": "\"user.define_outcome\"", "required": true, "description": "" }, { "name": "initial_events.description", "type": "string", "required": true, "description": "What the agent should produce. This is the task specification." }, { "name": "initial_events.rubric", "type": "BetaManagedAgentsFileRubricParams or BetaManagedAgentsTextRubricParams", "required": true, "description": "Rubric for grading the quality of an outcome." }, { "name": "initial_events.rubric", "type": "BetaManagedAgentsFileRubricParams object", "required": false, "description": "Rubric referenced by a file uploaded via the Files API." }, { "name": "initial_events.rubric.type", "type": "\"file\"", "required": true, "description": "" }, { "name": "initial_events.rubric.file_id", "type": "string", "required": true, "description": "ID of the rubric file." }, { "name": "initial_events.rubric", "type": "BetaManagedAgentsTextRubricParams object", "required": false, "description": "Rubric content provided inline as text." }, { "name": "initial_events.rubric.type", "type": "\"text\"", "required": true, "description": "" }, { "name": "initial_events.rubric.content", "type": "string", "required": true, "description": "Rubric content. Plain text or markdown — the grader treats it as freeform text. Maximum 262144 characters.", "constraints": { "maxLength": "262144" } }, { "name": "initial_events.max_iterations", "type": "number or null", "required": false, "description": "Eval→revision cycles before giving up. Default 3, max 20.", "constraints": { "format": "int32" } }, { "name": "metadata", "type": "map[string]", "required": false, "description": "Arbitrary key-value metadata attached to the session. Maximum 16 pairs, keys up to 64 chars, values up to 512 chars." }, { "name": "resources", "type": "array of BetaManagedAgentsGitHubRepositoryResourceParams or BetaManagedAgentsFileResourceParams or BetaManagedAgentsMemoryStoreResourceParam", "required": false, "description": "Resources (e.g. repositories, files) to mount into the session's container." }, { "name": "resources", "type": "BetaManagedAgentsGitHubRepositoryResourceParams object", "required": false, "description": "Mount a GitHub repository into the session's container." }, { "name": "resources.type", "type": "\"github_repository\"", "required": true, "description": "" }, { "name": "resources.url", "type": "string", "required": true, "description": "Github URL of the repository", "constraints": { "minLength": "1", "maxLength": "2048" } }, { "name": "resources.authorization_token", "type": "string", "required": false, "description": "GitHub authorization token used to clone the repository. Required for private repositories; optional for public ones.", "constraints": { "minLength": "1", "maxLength": "4096" } }, { "name": "resources.checkout", "type": "BetaManagedAgentsBranchCheckout or BetaManagedAgentsCommitCheckout or null", "required": false, "description": "Branch or commit to check out. Defaults to the repository's default branch." }, { "name": "resources.checkout", "type": "BetaManagedAgentsBranchCheckout object", "required": false, "description": "" }, { "name": "resources.checkout.type", "type": "\"branch\"", "required": true, "description": "" }, { "name": "resources.checkout.name", "type": "string", "required": true, "description": "Branch name to check out.", "constraints": { "minLength": "1", "maxLength": "255" } }, { "name": "resources.checkout", "type": "BetaManagedAgentsCommitCheckout object", "required": false, "description": "" }, { "name": "resources.checkout.type", "type": "\"commit\"", "required": true, "description": "" }, { "name": "resources.checkout.sha", "type": "string", "required": true, "description": "Full commit SHA to check out.", "constraints": { "minLength": "7", "maxLength": "64" } }, { "name": "resources.mount_path", "type": "string or null", "required": false, "description": "Mount path in the container. Defaults to `/workspace/`.", "constraints": { "minLength": "1", "maxLength": "4096" } }, { "name": "resources", "type": "BetaManagedAgentsFileResourceParams object", "required": false, "description": "Mount a file uploaded via the Files API into the session." }, { "name": "resources.type", "type": "\"file\"", "required": true, "description": "" }, { "name": "resources.file_id", "type": "string", "required": true, "description": "ID of a previously uploaded file.", "constraints": { "minLength": "1", "maxLength": "128" } }, { "name": "resources.mount_path", "type": "string or null", "required": false, "description": "Mount path in the container. Defaults to `/mnt/session/uploads/`.", "constraints": { "minLength": "1", "maxLength": "4096" } }, { "name": "resources", "type": "BetaManagedAgentsMemoryStoreResourceParam object", "required": false, "description": "Parameters for attaching a memory store to an agent session." }, { "name": "resources.type", "type": "\"memory_store\"", "required": true, "description": "" }, { "name": "resources.memory_store_id", "type": "string", "required": true, "description": "The memory store ID (memstore_...). Must belong to the caller's organization and workspace." }, { "name": "resources.access", "type": "\"read_write\" or \"read_only\" or null", "required": false, "description": "Access mode for an attached memory store.", "enum": [ "read_write", "read_only" ] }, { "name": "resources.instructions", "type": "string or null", "required": false, "description": "Per-attachment guidance for the agent on how to use this store. Rendered into the memory section of the system prompt. Max 4096 chars.", "constraints": { "maxLength": "4096" } }, { "name": "title", "type": "string or null", "required": false, "description": "Human-readable session title.", "constraints": { "maxLength": "500" } }, { "name": "vault_ids", "type": "array of string", "required": false, "description": "Vault IDs for stored credentials the agent can use during the session." } ], "status": [ "DOCUMENTED", "BETA" ], "sources": [ { "url": "https://platform.claude.com/docs/en/api/beta/sessions/create", "retrieved_at": "2026-09-18" }, { "url": "https://platform.claude.com/docs/en/managed-agents/sessions", "retrieved_at": "2026-09-18" }, { "url": "https://platform.claude.com/docs/en/managed-agents/files", "retrieved_at": "2026-09-18" }, { "url": "https://platform.claude.com/docs/en/managed-agents/github", "retrieved_at": "2026-09-18" }, { "url": "https://platform.claude.com/docs/en/managed-agents/memory", "retrieved_at": "2026-09-18" }, { "url": "https://platform.claude.com/docs/en/managed-agents/budgets", "retrieved_at": "2026-09-18" } ], "beta_header": "managed-agents-2026-04-01", "_fragment": "generated/fragments/objects/anthropic-platform-objects.json" }, { "provider": "anthropic", "api_family": "managed-agents", "name": "SessionUpdateParams (request body)", "official_type_name": "BetaManagedAgentsSessionUpdateParams", "description": "Update Session", "fields": [ { "name": "agent", "type": "BetaManagedAgentsSessionAgentUpdate", "required": false, "description": "Mid-session agent configuration update. Only `tools` and `mcp_servers` are updatable. Full replacement: the provided array becomes the new value. To preserve existing entries, GET the session, modify the array, and POST it back." }, { "name": "agent.mcp_servers", "type": "array of BetaManagedAgentsURLMCPServerParams", "required": false, "description": "Replacement MCP server list. Full replacement: the provided array becomes the new value. Send an empty array to clear; omit to preserve." }, { "name": "agent.mcp_servers.type", "type": "\"url\"", "required": true, "description": "" }, { "name": "agent.mcp_servers.name", "type": "string", "required": true, "description": "Unique name for this server, referenced by mcp_toolset configurations. 1-255 characters.", "constraints": { "minLength": "1", "maxLength": "255" } }, { "name": "agent.mcp_servers.url", "type": "string", "required": true, "description": "Endpoint URL for the MCP server.", "constraints": { "maxLength": "2048" } }, { "name": "agent.tools", "type": "array of BetaManagedAgentsAgentToolset20260401Params or BetaManagedAgentsMCPToolsetParams or BetaManagedAgentsCustomToolParams", "required": false, "description": "Replacement tool list. Full replacement: the provided array becomes the new value. Send an empty array to clear; omit to preserve." }, { "name": "agent.tools", "type": "BetaManagedAgentsAgentToolset20260401Params object", "required": false, "description": "Configuration for built-in agent tools. Use this to enable or disable groups of tools available to the agent." }, { "name": "agent.tools.type", "type": "\"agent_toolset_20260401\"", "required": true, "description": "" }, { "name": "agent.tools.configs", "type": "array of BetaManagedAgentsAgentToolConfigParams", "required": false, "description": "Per-tool configuration overrides." }, { "name": "agent.tools.configs", "type": "BetaManagedAgentsBashToolConfigParams object", "required": false, "description": "Configuration override for the bash tool." }, { "name": "agent.tools.configs.type", "type": "\"bash\"", "required": false, "description": "" }, { "name": "agent.tools.configs.name", "type": "\"bash\"", "required": true, "description": "Must be \"bash\"." }, { "name": "agent.tools.configs.enabled", "type": "boolean or null", "required": false, "description": "Whether this tool is enabled and available to Claude. Overrides the default_config setting." }, { "name": "agent.tools.configs.permission_policy", "type": "BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy or null", "required": false, "description": "Permission policy for tool execution." }, { "name": "agent.tools.configs", "type": "BetaManagedAgentsEditToolConfigParams object", "required": false, "description": "Configuration override for the edit tool." }, { "name": "agent.tools.configs.type", "type": "\"edit\"", "required": false, "description": "" }, { "name": "agent.tools.configs.name", "type": "\"edit\"", "required": true, "description": "Must be \"edit\"." }, { "name": "agent.tools.configs.enabled", "type": "boolean or null", "required": false, "description": "Whether this tool is enabled and available to Claude. Overrides the default_config setting." }, { "name": "agent.tools.configs.permission_policy", "type": "BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy or null", "required": false, "description": "Permission policy for tool execution." }, { "name": "agent.tools.configs", "type": "BetaManagedAgentsReadToolConfigParams object", "required": false, "description": "Configuration override for the read tool." }, { "name": "agent.tools.configs.type", "type": "\"read\"", "required": false, "description": "" }, { "name": "agent.tools.configs.name", "type": "\"read\"", "required": true, "description": "Must be \"read\"." }, { "name": "agent.tools.configs.enabled", "type": "boolean or null", "required": false, "description": "Whether this tool is enabled and available to Claude. Overrides the default_config setting." }, { "name": "agent.tools.configs.permission_policy", "type": "BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy or null", "required": false, "description": "Permission policy for tool execution." }, { "name": "agent.tools.configs", "type": "BetaManagedAgentsWriteToolConfigParams object", "required": false, "description": "Configuration override for the write tool." }, { "name": "agent.tools.configs.type", "type": "\"write\"", "required": false, "description": "" }, { "name": "agent.tools.configs.name", "type": "\"write\"", "required": true, "description": "Must be \"write\"." }, { "name": "agent.tools.configs.enabled", "type": "boolean or null", "required": false, "description": "Whether this tool is enabled and available to Claude. Overrides the default_config setting." }, { "name": "agent.tools.configs.permission_policy", "type": "BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy or null", "required": false, "description": "Permission policy for tool execution." }, { "name": "agent.tools.configs", "type": "BetaManagedAgentsGlobToolConfigParams object", "required": false, "description": "Configuration override for the glob tool." }, { "name": "agent.tools.configs.type", "type": "\"glob\"", "required": false, "description": "" }, { "name": "agent.tools.configs.name", "type": "\"glob\"", "required": true, "description": "Must be \"glob\"." }, { "name": "agent.tools.configs.enabled", "type": "boolean or null", "required": false, "description": "Whether this tool is enabled and available to Claude. Overrides the default_config setting." }, { "name": "agent.tools.configs.permission_policy", "type": "BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy or null", "required": false, "description": "Permission policy for tool execution." }, { "name": "agent.tools.configs", "type": "BetaManagedAgentsGrepToolConfigParams object", "required": false, "description": "Configuration override for the grep tool." }, { "name": "agent.tools.configs.type", "type": "\"grep\"", "required": false, "description": "" }, { "name": "agent.tools.configs.name", "type": "\"grep\"", "required": true, "description": "Must be \"grep\"." }, { "name": "agent.tools.configs.enabled", "type": "boolean or null", "required": false, "description": "Whether this tool is enabled and available to Claude. Overrides the default_config setting." }, { "name": "agent.tools.configs.permission_policy", "type": "BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy or null", "required": false, "description": "Permission policy for tool execution." }, { "name": "agent.tools.configs", "type": "BetaManagedAgentsWebFetchToolConfigParams object", "required": false, "description": "Configuration override for the web_fetch tool." }, { "name": "agent.tools.configs.type", "type": "\"web_fetch\"", "required": false, "description": "" }, { "name": "agent.tools.configs.name", "type": "\"web_fetch\"", "required": true, "description": "Must be \"web_fetch\"." }, { "name": "agent.tools.configs.allowed_domains", "type": "array of string", "required": false, "description": "Only fetch URLs whose host is one of these domains or a subdomain of one. Each entry is a plain hostname like \"docs.example.com\" (no scheme, port, or path). At most 64 entries; an empty list is rejected (omit the field instead). Cannot be combined with blocked_domains." }, { "name": "agent.tools.configs.blocked_domains", "type": "array of string", "required": false, "description": "Never fetch URLs whose host is one of these domains or a subdomain of one. Each entry is a plain hostname like \"ads.example.com\" (no scheme, port, or path). At most 64 entries; an empty list is rejected (omit the field instead). Cannot be combined with allowed_domains." }, { "name": "agent.tools.configs.enabled", "type": "boolean or null", "required": false, "description": "Whether this tool is enabled and available to Claude. Overrides the default_config setting." }, { "name": "agent.tools.configs.max_content_tokens", "type": "number or null", "required": false, "description": "Maximum number of tokens of fetched text content to include in context per call. Does not apply to binary content such as PDFs.", "constraints": { "format": "int32" } }, { "name": "agent.tools.configs.permission_policy", "type": "BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy or null", "required": false, "description": "Permission policy for tool execution." }, { "name": "agent.tools.configs", "type": "BetaManagedAgentsWebSearchToolConfigParams object", "required": false, "description": "Configuration override for the web_search tool." }, { "name": "agent.tools.configs.type", "type": "\"web_search\"", "required": false, "description": "" }, { "name": "agent.tools.configs.name", "type": "\"web_search\"", "required": true, "description": "Must be \"web_search\"." }, { "name": "agent.tools.configs.allowed_domains", "type": "array of string", "required": false, "description": "Only return search results whose host is one of these domains or a subdomain of one. Each entry is a plain hostname like \"docs.example.com\" (no scheme or port; an optional path suffix is accepted). At most 64 entries; an empty list is rejected (omit the field instead). Cannot be combined with blocked_domains." }, { "name": "agent.tools.configs.blocked_domains", "type": "array of string", "required": false, "description": "Never return search results whose host is one of these domains or a subdomain of one. Each entry is a plain hostname like \"ads.example.com\" (no scheme or port; an optional path suffix is accepted). At most 64 entries; an empty list is rejected (omit the field instead). Cannot be combined with allowed_domains." }, { "name": "agent.tools.configs.enabled", "type": "boolean or null", "required": false, "description": "Whether this tool is enabled and available to Claude. Overrides the default_config setting." }, { "name": "agent.tools.configs.permission_policy", "type": "BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy or null", "required": false, "description": "Permission policy for tool execution." }, { "name": "agent.tools.configs.user_location", "type": "BetaManagedAgentsUserLocation or null", "required": false, "description": "Approximate user location for search result localization." }, { "name": "agent.tools.default_config", "type": "BetaManagedAgentsAgentToolsetDefaultConfigParams or null", "required": false, "description": "Default configuration for all tools in a toolset." }, { "name": "agent.tools.default_config.enabled", "type": "boolean or null", "required": false, "description": "Whether tools are enabled and available to Claude by default. Defaults to true if not specified." }, { "name": "agent.tools.default_config.permission_policy", "type": "BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy or null", "required": false, "description": "Permission policy for tool execution." }, { "name": "agent.tools.default_config.permission_policy", "type": "BetaManagedAgentsAlwaysAllowPolicy object", "required": false, "description": "Tool calls are automatically approved without user confirmation." }, { "name": "agent.tools.default_config.permission_policy", "type": "BetaManagedAgentsAlwaysAskPolicy object", "required": false, "description": "Tool calls require user confirmation before execution." }, { "name": "agent.tools.default_config.permission_policy", "type": "BetaManagedAgentsAutoPolicy object", "required": false, "description": "The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask." }, { "name": "agent.tools", "type": "BetaManagedAgentsMCPToolsetParams object", "required": false, "description": "Configuration for tools from an MCP server defined in `mcp_servers`." }, { "name": "agent.tools.type", "type": "\"mcp_toolset\"", "required": true, "description": "" }, { "name": "agent.tools.mcp_server_name", "type": "string", "required": true, "description": "Name of the MCP server. Must match a server name from the mcp_servers array. 1-255 characters.", "constraints": { "minLength": "1", "maxLength": "255" } }, { "name": "agent.tools.configs", "type": "array of BetaManagedAgentsMCPToolConfigParams", "required": false, "description": "Per-tool configuration overrides." }, { "name": "agent.tools.configs.name", "type": "string", "required": true, "description": "Name of the MCP tool to configure. 1-128 characters.", "constraints": { "minLength": "1", "maxLength": "128" } }, { "name": "agent.tools.configs.enabled", "type": "boolean or null", "required": false, "description": "Whether this tool is enabled. Overrides the `default_config` setting." }, { "name": "agent.tools.configs.permission_policy", "type": "BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy or null", "required": false, "description": "Permission policy for tool execution." }, { "name": "agent.tools.configs.permission_policy", "type": "BetaManagedAgentsAlwaysAllowPolicy object", "required": false, "description": "Tool calls are automatically approved without user confirmation." }, { "name": "agent.tools.configs.permission_policy", "type": "BetaManagedAgentsAlwaysAskPolicy object", "required": false, "description": "Tool calls require user confirmation before execution." }, { "name": "agent.tools.configs.permission_policy", "type": "BetaManagedAgentsAutoPolicy object", "required": false, "description": "The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask." }, { "name": "agent.tools.default_config", "type": "BetaManagedAgentsMCPToolsetDefaultConfigParams or null", "required": false, "description": "Default configuration for all tools from an MCP server." }, { "name": "agent.tools.default_config.enabled", "type": "boolean or null", "required": false, "description": "Whether tools are enabled by default. Defaults to true if not specified." }, { "name": "agent.tools.default_config.permission_policy", "type": "BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy or null", "required": false, "description": "Permission policy for tool execution." }, { "name": "agent.tools.default_config.permission_policy", "type": "BetaManagedAgentsAlwaysAllowPolicy object", "required": false, "description": "Tool calls are automatically approved without user confirmation." }, { "name": "agent.tools.default_config.permission_policy", "type": "BetaManagedAgentsAlwaysAskPolicy object", "required": false, "description": "Tool calls require user confirmation before execution." }, { "name": "agent.tools.default_config.permission_policy", "type": "BetaManagedAgentsAutoPolicy object", "required": false, "description": "The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask." }, { "name": "agent.tools", "type": "BetaManagedAgentsCustomToolParams object", "required": false, "description": "A custom tool that is executed by the API client rather than the agent. When the agent calls this tool, an `agent.custom_tool_use` event is emitted and the session goes idle, waiting for the client to provide the result via a `user.custom_tool_result` event." }, { "name": "agent.tools.type", "type": "\"custom\"", "required": true, "description": "" }, { "name": "agent.tools.description", "type": "string", "required": true, "description": "Description of what the tool does, shown to the agent to help it decide when to use the tool.", "constraints": { "minLength": "1" } }, { "name": "agent.tools.input_schema", "type": "BetaManagedAgentsCustomToolInputSchema", "required": true, "description": "JSON Schema for custom tool input parameters." }, { "name": "agent.tools.input_schema.type", "type": "\"object\"", "required": true, "description": "" }, { "name": "agent.tools.input_schema.properties", "type": "map[unknown] or null", "required": false, "description": "" }, { "name": "agent.tools.input_schema.required", "type": "array of string or null", "required": false, "description": "" }, { "name": "agent.tools.name", "type": "string", "required": true, "description": "Unique name for the tool. 1-128 characters; letters, digits, underscores, and hyphens.", "constraints": { "minLength": "1", "maxLength": "128" } }, { "name": "budget", "type": "BetaManagedAgentsBudgetLimit or null", "required": false, "description": "A hard spend ceiling. The session stops issuing new model requests once the tracked list cost reaches `max_list_cost`." }, { "name": "budget.type", "type": "\"limit\"", "required": true, "description": "" }, { "name": "budget.max_list_cost", "type": "BetaMonetaryAmount", "required": true, "description": "A monetary amount in a specific currency." }, { "name": "budget.max_list_cost.amount", "type": "string", "required": true, "description": "Amount in minor units of the currency, as an integer decimal string with no leading zeros: \"2500\" is $25.00 and \"50\" is fifty cents. A string rather than a number so no float rounding is ever applied." }, { "name": "budget.max_list_cost.currency", "type": "BetaCurrency", "required": true, "description": "Uppercase ISO-4217 currency code. `USD` is the only currency currently supported; the accepted set is closed and grows only when a new currency is priced." }, { "name": "metadata", "type": "map[string] or null", "required": false, "description": "Metadata patch. Set a key to a string to upsert it, or to null to delete it. Omit the field to preserve." }, { "name": "title", "type": "string or null", "required": false, "description": "Human-readable session title.", "constraints": { "minLength": "1", "maxLength": "500" } }, { "name": "vault_ids", "type": "array of string", "required": false, "description": "Vault IDs (`vlt_*`) to attach to the session. Not yet supported; requests setting this field are rejected. Reserved for future use." } ], "status": [ "DOCUMENTED", "BETA" ], "sources": [ { "url": "https://platform.claude.com/docs/en/api/beta/sessions/update", "retrieved_at": "2026-09-18" }, { "url": "https://platform.claude.com/docs/en/managed-agents/session-operations", "retrieved_at": "2026-09-18" } ], "beta_header": "managed-agents-2026-04-01", "_fragment": "generated/fragments/objects/anthropic-platform-objects.json" }, { "provider": "anthropic", "api_family": "managed-agents", "name": "SessionResource (union: file | github_repository | memory_store)", "official_type_name": "BetaManagedAgentsSessionResource", "description": "Resources for the session, ordered by `created_at`.", "fields": [ { "name": "", "type": "BetaManagedAgentsGitHubRepositoryResource object", "required": false, "description": "" }, { "name": ".type", "type": "\"github_repository\"", "required": true, "description": "" }, { "name": ".id", "type": "string", "required": true, "description": "" }, { "name": ".created_at", "type": "string", "required": true, "description": "A timestamp in RFC 3339 format", "constraints": { "format": "date-time" } }, { "name": ".mount_path", "type": "string", "required": true, "description": "" }, { "name": ".updated_at", "type": "string", "required": true, "description": "A timestamp in RFC 3339 format", "constraints": { "format": "date-time" } }, { "name": ".url", "type": "string", "required": true, "description": "" }, { "name": ".checkout", "type": "BetaManagedAgentsBranchCheckout or BetaManagedAgentsCommitCheckout or null", "required": false, "description": "" }, { "name": ".checkout", "type": "BetaManagedAgentsBranchCheckout object", "required": false, "description": "" }, { "name": ".checkout.type", "type": "\"branch\"", "required": true, "description": "" }, { "name": ".checkout.name", "type": "string", "required": true, "description": "Branch name to check out.", "constraints": { "minLength": "1", "maxLength": "255" } }, { "name": ".checkout", "type": "BetaManagedAgentsCommitCheckout object", "required": false, "description": "" }, { "name": ".checkout.type", "type": "\"commit\"", "required": true, "description": "" }, { "name": ".checkout.sha", "type": "string", "required": true, "description": "Full commit SHA to check out.", "constraints": { "minLength": "7", "maxLength": "64" } }, { "name": "", "type": "BetaManagedAgentsFileResource object", "required": false, "description": "" }, { "name": ".type", "type": "\"file\"", "required": true, "description": "" }, { "name": ".id", "type": "string", "required": true, "description": "" }, { "name": ".created_at", "type": "string", "required": true, "description": "A timestamp in RFC 3339 format", "constraints": { "format": "date-time" } }, { "name": ".file_id", "type": "string", "required": true, "description": "" }, { "name": ".mount_path", "type": "string", "required": true, "description": "" }, { "name": ".updated_at", "type": "string", "required": true, "description": "A timestamp in RFC 3339 format", "constraints": { "format": "date-time" } }, { "name": "", "type": "BetaManagedAgentsMemoryStoreResource object", "required": false, "description": "A memory store attached to an agent session." }, { "name": ".type", "type": "\"memory_store\"", "required": true, "description": "" }, { "name": ".memory_store_id", "type": "string", "required": true, "description": "The memory store ID (memstore_...). Must belong to the caller's organization and workspace." }, { "name": ".access", "type": "\"read_write\" or \"read_only\" or null", "required": false, "description": "Access mode for an attached memory store.", "enum": [ "read_write", "read_only" ] }, { "name": ".description", "type": "string", "required": false, "description": "Description of the memory store, snapshotted at attach time. Rendered into the agent's system prompt. Empty string when the store has no description." }, { "name": ".instructions", "type": "string or null", "required": false, "description": "Per-attachment guidance for the agent on how to use this store. Rendered into the memory section of the system prompt. Max 4096 chars.", "constraints": { "maxLength": "4096" } }, { "name": ".mount_path", "type": "string or null", "required": false, "description": "Filesystem path where the store is mounted in the session container, e.g. /mnt/memory/user-preferences. Derived from the store's name. Output-only." }, { "name": ".name", "type": "string or null", "required": false, "description": "Display name of the memory store, snapshotted at attach time. Later edits to the store's name do not propagate to this resource." } ], "status": [ "DOCUMENTED", "BETA" ], "sources": [ { "url": "https://platform.claude.com/docs/en/api/beta/sessions/resources/list", "retrieved_at": "2026-09-18" }, { "url": "https://platform.claude.com/docs/en/managed-agents/files", "retrieved_at": "2026-09-18" }, { "url": "https://platform.claude.com/docs/en/managed-agents/github", "retrieved_at": "2026-09-18" }, { "url": "https://platform.claude.com/docs/en/managed-agents/memory", "retrieved_at": "2026-09-18" } ], "beta_header": "managed-agents-2026-04-01", "_fragment": "generated/fragments/objects/anthropic-platform-objects.json" }, { "provider": "anthropic", "api_family": "managed-agents", "name": "SessionThread", "official_type_name": "BetaManagedAgentsSessionThread", "description": "An execution thread within a `session`. Each session has one primary thread plus zero or more child threads spawned by the coordinator.", "fields": [ { "name": "type", "type": "\"session_thread\"", "required": true, "description": "" }, { "name": "id", "type": "string", "required": true, "description": "Unique identifier for this thread." }, { "name": "agent", "type": "BetaManagedAgentsSessionThreadAgent or BetaManagedAgentsAdvisor", "required": true, "description": "The resolved agent a session thread runs: a saved-agent snapshot, the platform advisor entry, or an inline-defined (ephemeral) agent snapshot." }, { "name": "agent", "type": "BetaManagedAgentsSessionThreadAgent object", "required": false, "description": "Resolved `agent` definition for a single `session_thread`. Snapshot of the agent at thread creation time. The multiagent roster is not repeated here; read it from `Session.agent`." }, { "name": "agent.type", "type": "\"agent\"", "required": true, "description": "" }, { "name": "agent.id", "type": "string", "required": true, "description": "" }, { "name": "agent.description", "type": "string or null", "required": true, "description": "" }, { "name": "agent.mcp_servers", "type": "array of BetaManagedAgentsMCPServerURLDefinition", "required": true, "description": "" }, { "name": "agent.mcp_servers.type", "type": "\"url\"", "required": true, "description": "" }, { "name": "agent.mcp_servers.name", "type": "string", "required": true, "description": "" }, { "name": "agent.mcp_servers.url", "type": "string", "required": true, "description": "" }, { "name": "agent.model", "type": "BetaManagedAgentsModelConfig", "required": true, "description": "Model identifier and configuration." }, { "name": "agent.model.id", "type": "BetaManagedAgentsModel", "required": true, "description": "The model that will power your agent. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options." }, { "name": "agent.model.id<\"claude-fable-5-1\" or \"claude-sonnet-5\" or \"claude-fable-5\" or 11 more>", "type": "\"claude-fable-5-1\" or \"claude-sonnet-5\" or \"claude-fable-5\" or 11 more", "required": false, "description": "The model that will power your agent. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options." }, { "name": "agent.model.id", "type": "string", "required": false, "description": "" }, { "name": "agent.model.effort", "type": "BetaManagedAgentsEffortLow or BetaManagedAgentsEffortMedium or BetaManagedAgentsEffortHigh or 2 more", "required": false, "description": "How hard Claude works on each turn. Sets `output_config.effort` on every Messages call the session makes." }, { "name": "agent.model.effort", "type": "BetaManagedAgentsEffortLow object", "required": false, "description": "Low effort. Favors latency over reasoning depth." }, { "name": "agent.model.effort", "type": "BetaManagedAgentsEffortMedium object", "required": false, "description": "Medium effort. Balances latency and reasoning depth." }, { "name": "agent.model.effort", "type": "BetaManagedAgentsEffortHigh object", "required": false, "description": "High effort. Favors reasoning depth." }, { "name": "agent.model.effort", "type": "BetaManagedAgentsEffortXhigh object", "required": false, "description": "Extra-high effort. Not all models accept this level." }, { "name": "agent.model.effort", "type": "BetaManagedAgentsEffortMax object", "required": false, "description": "Maximum effort. Favors reasoning depth over latency." }, { "name": "agent.model.inference_geo", "type": "string", "required": false, "description": "Geographic region for model inference. When unset, requests fall through to the workspace's default_inference_geo." }, { "name": "agent.model.speed", "type": "\"standard\" or \"fast\"", "required": false, "description": "Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time.", "enum": [ "standard", "fast" ] }, { "name": "agent.name", "type": "string", "required": true, "description": "" }, { "name": "agent.skills", "type": "array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill", "required": true, "description": "" }, { "name": "agent.skills", "type": "BetaManagedAgentsAnthropicSkill object", "required": false, "description": "A resolved Anthropic-managed skill." }, { "name": "agent.skills.type", "type": "\"anthropic\"", "required": true, "description": "" }, { "name": "agent.skills.skill_id", "type": "string", "required": true, "description": "" }, { "name": "agent.skills.version", "type": "string", "required": true, "description": "" }, { "name": "agent.skills", "type": "BetaManagedAgentsCustomSkill object", "required": false, "description": "A resolved user-created custom skill." }, { "name": "agent.skills.type", "type": "\"custom\"", "required": true, "description": "" }, { "name": "agent.skills.skill_id", "type": "string", "required": true, "description": "" }, { "name": "agent.skills.version", "type": "string", "required": true, "description": "" }, { "name": "agent.system", "type": "string or null", "required": true, "description": "" }, { "name": "agent.tools", "type": "array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool", "required": true, "description": "" }, { "name": "agent.tools", "type": "BetaManagedAgentsAgentToolset20260401 object", "required": false, "description": "" }, { "name": "agent.tools.type", "type": "\"agent_toolset_20260401\"", "required": true, "description": "" }, { "name": "agent.tools.configs", "type": "array of BetaManagedAgentsAgentToolConfig", "required": true, "description": "" }, { "name": "agent.tools.default_config", "type": "BetaManagedAgentsAgentToolsetDefaultConfig", "required": true, "description": "Resolved default configuration for agent tools." }, { "name": "agent.tools", "type": "BetaManagedAgentsMCPToolset object", "required": false, "description": "" }, { "name": "agent.tools.type", "type": "\"mcp_toolset\"", "required": true, "description": "" }, { "name": "agent.tools.configs", "type": "array of BetaManagedAgentsMCPToolConfig", "required": true, "description": "" }, { "name": "agent.tools.default_config", "type": "BetaManagedAgentsMCPToolsetDefaultConfig", "required": true, "description": "Resolved default configuration for all tools from an MCP server." }, { "name": "agent.tools.mcp_server_name", "type": "string", "required": true, "description": "" }, { "name": "agent.tools", "type": "BetaManagedAgentsCustomTool object", "required": false, "description": "A custom tool as returned in API responses." }, { "name": "agent.tools.type", "type": "\"custom\"", "required": true, "description": "" }, { "name": "agent.tools.description", "type": "string", "required": true, "description": "" }, { "name": "agent.tools.input_schema", "type": "BetaManagedAgentsCustomToolInputSchema", "required": true, "description": "JSON Schema for custom tool input parameters." }, { "name": "agent.tools.name", "type": "string", "required": true, "description": "" }, { "name": "agent.version", "type": "number", "required": true, "description": "", "constraints": { "format": "int32" } }, { "name": "agent", "type": "BetaManagedAgentsAdvisor object", "required": false, "description": "Platform advisor roster entry: a model the session's primary thread may consult mid-turn." }, { "name": "agent.type", "type": "\"advisor\"", "required": true, "description": "" }, { "name": "agent.model", "type": "string", "required": true, "description": "The advisor model id." }, { "name": "archived_at", "type": "string or null", "required": true, "description": "A timestamp in RFC 3339 format", "constraints": { "format": "date-time" } }, { "name": "created_at", "type": "string", "required": true, "description": "A timestamp in RFC 3339 format", "constraints": { "format": "date-time" } }, { "name": "parent_thread_id", "type": "string or null", "required": true, "description": "Parent thread that spawned this thread. Null for the primary thread." }, { "name": "session_id", "type": "string", "required": true, "description": "The session this thread belongs to." }, { "name": "stats", "type": "BetaManagedAgentsSessionThreadStats or null", "required": true, "description": "Timing statistics for a session thread." }, { "name": "stats.active_seconds", "type": "number", "required": false, "description": "Cumulative time in seconds the thread spent actively running. Excludes idle time.", "constraints": { "format": "double" } }, { "name": "stats.duration_seconds", "type": "number", "required": false, "description": "Elapsed time since thread creation in seconds. For archived threads, frozen at the final update.", "constraints": { "format": "double" } }, { "name": "stats.startup_seconds", "type": "number", "required": false, "description": "Time in seconds for the thread to begin running. Zero for child threads, which start immediately.", "constraints": { "format": "double" } }, { "name": "status", "type": "BetaManagedAgentsSessionThreadStatus", "required": true, "description": "SessionThreadStatus enum", "enum": [ "running", "idle", "rescheduling", "terminated" ] }, { "name": "updated_at", "type": "string", "required": true, "description": "A timestamp in RFC 3339 format", "constraints": { "format": "date-time" } }, { "name": "usage", "type": "BetaManagedAgentsSessionThreadUsage or null", "required": true, "description": "Cumulative token usage for a session thread across all turns." }, { "name": "usage.active_seconds", "type": "number", "required": false, "description": "Cumulative time in seconds this thread spent in running status. Equal to `stats.active_seconds`; surfaced here so a thread's usage carries every quantity its cost is priced on.", "constraints": { "format": "double" } }, { "name": "usage.cache_creation", "type": "BetaManagedAgentsCacheCreationUsage", "required": false, "description": "Prompt-cache creation token usage broken down by cache lifetime." }, { "name": "usage.cache_creation.ephemeral_1h_input_tokens", "type": "number", "required": false, "description": "Tokens used to create 1-hour ephemeral cache entries.", "constraints": { "format": "int32" } }, { "name": "usage.cache_creation.ephemeral_5m_input_tokens", "type": "number", "required": false, "description": "Tokens used to create 5-minute ephemeral cache entries.", "constraints": { "format": "int32" } }, { "name": "usage.cache_read_input_tokens", "type": "number", "required": false, "description": "Total tokens read from prompt cache.", "constraints": { "format": "int32" } }, { "name": "usage.input_tokens", "type": "number", "required": false, "description": "Total input tokens consumed across all turns.", "constraints": { "format": "int32" } }, { "name": "usage.list_cost", "type": "BetaMonetaryAmount or null", "required": false, "description": "A monetary amount in a specific currency." }, { "name": "usage.list_cost.amount", "type": "string", "required": true, "description": "Amount in minor units of the currency, as an integer decimal string with no leading zeros: \"2500\" is $25.00 and \"50\" is fifty cents. A string rather than a number so no float rounding is ever applied." }, { "name": "usage.list_cost.currency", "type": "BetaCurrency", "required": true, "description": "Uppercase ISO-4217 currency code. `USD` is the only currency currently supported; the accepted set is closed and grows only when a new currency is priced." }, { "name": "usage.output_tokens", "type": "number", "required": false, "description": "Total output tokens generated across all turns.", "constraints": { "format": "int32" } }, { "name": "usage.server_tool_use", "type": "BetaManagedAgentsServerToolUsage or null", "required": false, "description": "Cumulative count of server-executed tool invocations, broken down by tool." }, { "name": "usage.server_tool_use.web_fetch_requests", "type": "number", "required": false, "description": "Number of server-executed web fetch requests.", "constraints": { "format": "int32" } }, { "name": "usage.server_tool_use.web_search_requests", "type": "number", "required": false, "description": "Number of server-executed web search requests.", "constraints": { "format": "int32" } } ], "status": [ "DOCUMENTED", "BETA" ], "sources": [ { "url": "https://platform.claude.com/docs/en/api/beta/sessions/threads/retrieve", "retrieved_at": "2026-09-18" }, { "url": "https://platform.claude.com/docs/en/managed-agents/multiagent-orchestration", "retrieved_at": "2026-09-18" } ], "beta_header": "managed-agents-2026-04-01", "_fragment": "generated/fragments/objects/anthropic-platform-objects.json" }, { "provider": "anthropic", "api_family": "managed-agents", "name": "SessionEvent (union of persisted event variants)", "official_type_name": "BetaManagedAgentsSessionEvent", "description": "Events for the session, ordered by `processed_at`.", "fields": [ { "name": "", "type": "BetaManagedAgentsUserMessageEvent object", "required": false, "description": "A user message event in the session conversation." }, { "name": ".type", "type": "\"user.message\"", "required": true, "description": "" }, { "name": ".id", "type": "string", "required": true, "description": "Unique identifier for this event." }, { "name": ".content", "type": "array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsRedactedBlock", "required": true, "description": "Array of content blocks comprising the user message." }, { "name": ".processed_at", "type": "string or null", "required": false, "description": "A timestamp in RFC 3339 format", "constraints": { "format": "date-time" } }, { "name": "", "type": "BetaManagedAgentsUserInterruptEvent object", "required": false, "description": "An interrupt event that pauses agent execution and returns control to the user." }, { "name": ".type", "type": "\"user.interrupt\"", "required": true, "description": "" }, { "name": ".id", "type": "string", "required": true, "description": "Unique identifier for this event." }, { "name": ".processed_at", "type": "string or null", "required": false, "description": "A timestamp in RFC 3339 format", "constraints": { "format": "date-time" } }, { "name": ".session_thread_id", "type": "string or null", "required": false, "description": "If absent, interrupts every non-archived thread in a multiagent session (or the primary alone in a single-agent session). If present, interrupts only the named thread." }, { "name": "", "type": "BetaManagedAgentsUserToolConfirmationEvent object", "required": false, "description": "A tool confirmation event that approves or denies a pending tool execution." }, { "name": ".type", "type": "\"user.tool_confirmation\"", "required": true, "description": "" }, { "name": ".id", "type": "string", "required": true, "description": "Unique identifier for this event." }, { "name": ".result", "type": "\"allow\" or \"deny\"", "required": true, "description": "UserToolConfirmationResult enum", "enum": [ "allow", "deny" ] }, { "name": ".tool_use_id", "type": "string", "required": true, "description": "The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field." }, { "name": ".deny_message", "type": "string or null", "required": false, "description": "Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'.", "constraints": { "maxLength": "10000" } }, { "name": ".processed_at", "type": "string or null", "required": false, "description": "A timestamp in RFC 3339 format", "constraints": { "format": "date-time" } }, { "name": ".session_thread_id", "type": "string or null", "required": false, "description": "Set by the server to the subagent thread this confirmation was routed to. Omitted when it was routed to the primary thread." }, { "name": "", "type": "BetaManagedAgentsUserCustomToolResultEvent object", "required": false, "description": "Event sent by the client providing the result of a custom tool execution." }, { "name": ".type", "type": "\"user.custom_tool_result\"", "required": true, "description": "" }, { "name": ".id", "type": "string", "required": true, "description": "Unique identifier for this event." }, { "name": ".custom_tool_use_id", "type": "string", "required": true, "description": "The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field." }, { "name": ".content", "type": "array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock", "required": false, "description": "The result content returned by the tool." }, { "name": ".is_error", "type": "boolean or null", "required": false, "description": "Whether the tool execution resulted in an error." }, { "name": ".processed_at", "type": "string or null", "required": false, "description": "A timestamp in RFC 3339 format", "constraints": { "format": "date-time" } }, { "name": ".session_thread_id", "type": "string or null", "required": false, "description": "Set by the server to the subagent thread this result was routed to. Omitted when it was routed to the primary thread." }, { "name": "", "type": "BetaManagedAgentsAgentCustomToolUseEvent object", "required": false, "description": "Event emitted when the agent calls a custom tool. The session goes idle until the client sends a `user.custom_tool_result` event with the result." }, { "name": ".type", "type": "\"agent.custom_tool_use\"", "required": true, "description": "" }, { "name": ".id", "type": "string", "required": true, "description": "Unique identifier for this event." }, { "name": ".input", "type": "map[unknown]", "required": true, "description": "Input parameters for the tool call." }, { "name": ".name", "type": "string", "required": true, "description": "Name of the custom tool being called." }, { "name": ".processed_at", "type": "string", "required": true, "description": "A timestamp in RFC 3339 format", "constraints": { "format": "date-time" } }, { "name": ".session_thread_id", "type": "string or null", "required": false, "description": "When set, this event was cross-posted from a subagent's thread to surface its custom tool use on the primary thread's stream. Empty on the thread's own events. Informational only: the server routes the matching `user.custom_tool_result` by `custom_tool_use_id`, so clients do not send it back." }, { "name": "", "type": "BetaManagedAgentsAgentMessageEvent object", "required": false, "description": "An agent response event in the session conversation." }, { "name": ".type", "type": "\"agent.message\"", "required": true, "description": "" }, { "name": ".id", "type": "string", "required": true, "description": "Unique identifier for this event." }, { "name": ".content", "type": "array of BetaManagedAgentsTextBlock or BetaManagedAgentsRedactedBlock", "required": true, "description": "Array of text blocks comprising the agent response." }, { "name": ".processed_at", "type": "string", "required": true, "description": "A timestamp in RFC 3339 format", "constraints": { "format": "date-time" } }, { "name": "", "type": "BetaManagedAgentsAgentThinkingEvent object", "required": false, "description": "Indicates the agent is making forward progress via extended thinking. A progress signal, not a content carrier." }, { "name": ".type", "type": "\"agent.thinking\"", "required": true, "description": "" }, { "name": ".id", "type": "string", "required": true, "description": "Unique identifier for this event." }, { "name": ".processed_at", "type": "string", "required": true, "description": "A timestamp in RFC 3339 format", "constraints": { "format": "date-time" } }, { "name": "", "type": "BetaManagedAgentsAgentMCPToolUseEvent object", "required": false, "description": "Event emitted when the agent invokes a tool provided by an MCP server." }, { "name": ".type", "type": "\"agent.mcp_tool_use\"", "required": true, "description": "" }, { "name": ".id", "type": "string", "required": true, "description": "Unique identifier for this event." }, { "name": ".input", "type": "map[unknown]", "required": true, "description": "Input parameters for the tool call." }, { "name": ".mcp_server_name", "type": "string", "required": true, "description": "Name of the MCP server providing the tool." }, { "name": ".name", "type": "string", "required": true, "description": "Name of the MCP tool being used." }, { "name": ".processed_at", "type": "string", "required": true, "description": "A timestamp in RFC 3339 format", "constraints": { "format": "date-time" } }, { "name": ".evaluated_permission", "type": "\"allow\" or \"ask\" or \"deny\"", "required": false, "description": "AgentEvaluatedPermission enum", "enum": [ "allow", "ask", "deny" ] }, { "name": ".evaluation", "type": "BetaManagedAgentsAgentToolEvaluation", "required": false, "description": "Names the resolved permission_policy that produced evaluated_permission, and under auto carries the judgement. Open union: clients must tolerate unknown variants." }, { "name": ".session_thread_id", "type": "string or null", "required": false, "description": "When set, this event was cross-posted from a subagent's thread to surface its permission request on the primary thread's stream. Empty on the thread's own events. Informational only: the server routes the matching `user.tool_confirmation` by `tool_use_id`, so clients do not send it back." }, { "name": "", "type": "BetaManagedAgentsAgentMCPToolResultEvent object", "required": false, "description": "Event representing the result of an MCP tool execution." }, { "name": ".type", "type": "\"agent.mcp_tool_result\"", "required": true, "description": "" }, { "name": ".id", "type": "string", "required": true, "description": "Unique identifier for this event." }, { "name": ".mcp_tool_use_id", "type": "string", "required": true, "description": "The id of the `agent.mcp_tool_use` event this result corresponds to." }, { "name": ".processed_at", "type": "string", "required": true, "description": "A timestamp in RFC 3339 format", "constraints": { "format": "date-time" } }, { "name": ".content", "type": "array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock", "required": false, "description": "The result content returned by the tool." }, { "name": ".is_error", "type": "boolean or null", "required": false, "description": "Whether the tool execution resulted in an error." }, { "name": "", "type": "BetaManagedAgentsAgentToolUseEvent object", "required": false, "description": "Event emitted when the agent invokes a built-in agent tool." }, { "name": ".type", "type": "\"agent.tool_use\"", "required": true, "description": "" }, { "name": ".id", "type": "string", "required": true, "description": "Unique identifier for this event." }, { "name": ".input", "type": "map[unknown]", "required": true, "description": "Input parameters for the tool call." }, { "name": ".name", "type": "string", "required": true, "description": "Name of the agent tool being used." }, { "name": ".processed_at", "type": "string", "required": true, "description": "A timestamp in RFC 3339 format", "constraints": { "format": "date-time" } }, { "name": ".evaluated_permission", "type": "\"allow\" or \"ask\" or \"deny\"", "required": false, "description": "AgentEvaluatedPermission enum", "enum": [ "allow", "ask", "deny" ] }, { "name": ".evaluation", "type": "BetaManagedAgentsAgentToolEvaluation", "required": false, "description": "Names the resolved permission_policy that produced evaluated_permission, and under auto carries the judgement. Open union: clients must tolerate unknown variants." }, { "name": ".session_thread_id", "type": "string or null", "required": false, "description": "When set, this event was cross-posted from a subagent's thread to surface its permission request on the primary thread's stream. Empty on the thread's own events. Informational only: the server routes the matching `user.tool_confirmation` or `user.tool_result` by `tool_use_id`, so clients do not send it back." }, { "name": "", "type": "BetaManagedAgentsAgentToolResultEvent object", "required": false, "description": "Event representing the result of an agent tool execution." }, { "name": ".type", "type": "\"agent.tool_result\"", "required": true, "description": "" }, { "name": ".id", "type": "string", "required": true, "description": "Unique identifier for this event." }, { "name": ".processed_at", "type": "string", "required": true, "description": "A timestamp in RFC 3339 format", "constraints": { "format": "date-time" } }, { "name": ".tool_use_id", "type": "string", "required": true, "description": "The id of the `agent.tool_use` event this result corresponds to." }, { "name": ".content", "type": "array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock", "required": false, "description": "The result content returned by the tool." }, { "name": ".is_error", "type": "boolean or null", "required": false, "description": "Whether the tool execution resulted in an error." }, { "name": "", "type": "BetaManagedAgentsAgentThreadMessageReceivedEvent object", "required": false, "description": "Delivery event written to the target thread's input stream when an agent-to-agent message arrives." }, { "name": ".type", "type": "\"agent.thread_message_received\"", "required": true, "description": "" }, { "name": ".id", "type": "string", "required": true, "description": "Unique identifier for this event." }, { "name": ".content", "type": "array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsRedactedBlock", "required": true, "description": "Message content blocks." }, { "name": ".from_session_thread_id", "type": "string", "required": true, "description": "Public `sthr_` ID of the thread that sent the message." }, { "name": ".processed_at", "type": "string", "required": true, "description": "A timestamp in RFC 3339 format", "constraints": { "format": "date-time" } }, { "name": ".from_agent_name", "type": "string or null", "required": false, "description": "Name of the callable agent this message came from. Absent when received from the primary agent." }, { "name": "", "type": "BetaManagedAgentsAgentThreadMessageSentEvent object", "required": false, "description": "Observability event emitted to the sender's output stream when an agent-to-agent message is sent." }, { "name": ".type", "type": "\"agent.thread_message_sent\"", "required": true, "description": "" }, { "name": ".id", "type": "string", "required": true, "description": "Unique identifier for this event." }, { "name": ".content", "type": "array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsRedactedBlock", "required": true, "description": "Message content blocks." }, { "name": ".processed_at", "type": "string", "required": true, "description": "A timestamp in RFC 3339 format", "constraints": { "format": "date-time" } }, { "name": ".to_session_thread_id", "type": "string", "required": true, "description": "Public `sthr_` ID of the thread the message was sent to." }, { "name": ".to_agent_name", "type": "string or null", "required": false, "description": "Name of the callable agent this message was sent to. Absent when sent to the primary agent." }, { "name": "", "type": "BetaManagedAgentsAgentThreadContextCompactedEvent object", "required": false, "description": "Indicates that context compaction (summarization) occurred during the session." }, { "name": ".type", "type": "\"agent.thread_context_compacted\"", "required": true, "description": "" }, { "name": ".id", "type": "string", "required": true, "description": "Unique identifier for this event." }, { "name": ".processed_at", "type": "string", "required": true, "description": "A timestamp in RFC 3339 format", "constraints": { "format": "date-time" } }, { "name": "", "type": "BetaManagedAgentsSessionErrorEvent object", "required": false, "description": "An error event indicating a problem occurred during session execution." }, { "name": ".type", "type": "\"session.error\"", "required": true, "description": "" }, { "name": ".id", "type": "string", "required": true, "description": "Unique identifier for this event." }, { "name": ".error", "type": "BetaManagedAgentsUnknownError or BetaManagedAgentsModelOverloadedError or BetaManagedAgentsModelRateLimitedError or 5 more", "required": true, "description": "" }, { "name": ".processed_at", "type": "string", "required": true, "description": "A timestamp in RFC 3339 format", "constraints": { "format": "date-time" } }, { "name": "", "type": "BetaManagedAgentsSessionStatusRescheduledEvent object", "required": false, "description": "Indicates the session is recovering from an error state and is rescheduled for execution." }, { "name": ".type", "type": "\"session.status_rescheduled\"", "required": true, "description": "" }, { "name": ".id", "type": "string", "required": true, "description": "Unique identifier for this event." }, { "name": ".processed_at", "type": "string", "required": true, "description": "A timestamp in RFC 3339 format", "constraints": { "format": "date-time" } }, { "name": "", "type": "BetaManagedAgentsSessionStatusRunningEvent object", "required": false, "description": "Indicates the session is actively running and the agent is working." }, { "name": ".type", "type": "\"session.status_running\"", "required": true, "description": "" }, { "name": ".id", "type": "string", "required": true, "description": "Unique identifier for this event." }, { "name": ".processed_at", "type": "string", "required": true, "description": "A timestamp in RFC 3339 format", "constraints": { "format": "date-time" } }, { "name": "", "type": "BetaManagedAgentsSessionStatusIdleEvent object", "required": false, "description": "Indicates the agent has paused and is awaiting user input." }, { "name": ".type", "type": "\"session.status_idle\"", "required": true, "description": "" }, { "name": ".id", "type": "string", "required": true, "description": "Unique identifier for this event." }, { "name": ".processed_at", "type": "string", "required": true, "description": "A timestamp in RFC 3339 format", "constraints": { "format": "date-time" } }, { "name": ".stop_reason", "type": "BetaManagedAgentsSessionEndTurn or BetaManagedAgentsSessionRequiresAction or BetaManagedAgentsSessionRetriesExhausted or BetaManagedAgentsSessionBudgetReached", "required": true, "description": "" }, { "name": "", "type": "BetaManagedAgentsSessionStatusTerminatedEvent object", "required": false, "description": "Indicates the session has terminated, either due to an error or completion." }, { "name": ".type", "type": "\"session.status_terminated\"", "required": true, "description": "" }, { "name": ".id", "type": "string", "required": true, "description": "Unique identifier for this event." }, { "name": ".processed_at", "type": "string", "required": true, "description": "A timestamp in RFC 3339 format", "constraints": { "format": "date-time" } }, { "name": "", "type": "BetaManagedAgentsSessionThreadCreatedEvent object", "required": false, "description": "Emitted when a subagent is spawned as a new thread. Written to the parent thread's output stream so clients observing the session see child creation." }, { "name": ".type", "type": "\"session.thread_created\"", "required": true, "description": "" }, { "name": ".id", "type": "string", "required": true, "description": "Unique identifier for this event." }, { "name": ".agent_name", "type": "string", "required": true, "description": "Name of the callable agent the thread runs." }, { "name": ".processed_at", "type": "string", "required": true, "description": "A timestamp in RFC 3339 format", "constraints": { "format": "date-time" } }, { "name": ".session_thread_id", "type": "string", "required": true, "description": "Public `sthr_` ID of the newly created thread." }, { "name": "", "type": "BetaManagedAgentsSpanOutcomeEvaluationStartEvent object", "required": false, "description": "Emitted when an outcome evaluation cycle begins." }, { "name": ".type", "type": "\"span.outcome_evaluation_start\"", "required": true, "description": "" }, { "name": ".id", "type": "string", "required": true, "description": "Unique identifier for this event." }, { "name": ".iteration", "type": "number", "required": true, "description": "0-indexed revision cycle. 0 is the first evaluation; 1 is the re-evaluation after the first revision; etc.", "constraints": { "format": "int32" } }, { "name": ".outcome_id", "type": "string", "required": true, "description": "The `outc_` ID of the outcome being evaluated." }, { "name": ".processed_at", "type": "string", "required": true, "description": "A timestamp in RFC 3339 format", "constraints": { "format": "date-time" } }, { "name": "", "type": "BetaManagedAgentsSpanOutcomeEvaluationEndEvent object", "required": false, "description": "Emitted when an outcome evaluation cycle completes. Carries the verdict and aggregate token usage. A verdict of `needs_revision` means another evaluation cycle follows; `satisfied`, `max_iterations_reached`, `failed`, or `interrupted` are terminal — no further evaluation cycles follow." }, { "name": ".type", "type": "\"span.outcome_evaluation_end\"", "required": true, "description": "" }, { "name": ".id", "type": "string", "required": true, "description": "Unique identifier for this event." }, { "name": ".explanation", "type": "string", "required": true, "description": "Human-readable explanation of the verdict. For `needs_revision`, describes which criteria failed and why." }, { "name": ".iteration", "type": "number", "required": true, "description": "0-indexed revision cycle, matching the corresponding `span.outcome_evaluation_start`.", "constraints": { "format": "int32" } }, { "name": ".outcome_evaluation_start_id", "type": "string", "required": true, "description": "The id of the corresponding `span.outcome_evaluation_start` event." }, { "name": ".outcome_id", "type": "string", "required": true, "description": "The `outc_` ID of the outcome being evaluated." }, { "name": ".processed_at", "type": "string", "required": true, "description": "A timestamp in RFC 3339 format", "constraints": { "format": "date-time" } }, { "name": ".result", "type": "string", "required": true, "description": "Evaluation verdict. 'satisfied': criteria met, session goes idle. 'needs_revision': criteria not met, another revision cycle follows. 'max_iterations_reached': evaluation budget exhausted with criteria still unmet — one final acknowledgment turn follows before the session goes idle, but no further evaluation runs. 'failed': grader determined the rubric does not apply to the deliverables. 'interrupted': user sent an interrupt while evaluation was in progress." }, { "name": ".usage", "type": "BetaManagedAgentsSpanModelUsage", "required": true, "description": "Token usage for a single model request." }, { "name": "", "type": "BetaManagedAgentsSpanModelRequestStartEvent object", "required": false, "description": "Emitted when a model request is initiated by the agent." }, { "name": ".type", "type": "\"span.model_request_start\"", "required": true, "description": "" }, { "name": ".id", "type": "string", "required": true, "description": "Unique identifier for this event." }, { "name": ".processed_at", "type": "string", "required": true, "description": "A timestamp in RFC 3339 format", "constraints": { "format": "date-time" } }, { "name": "", "type": "BetaManagedAgentsSpanModelRequestEndEvent object", "required": false, "description": "Emitted when a model request completes." }, { "name": ".type", "type": "\"span.model_request_end\"", "required": true, "description": "" }, { "name": ".id", "type": "string", "required": true, "description": "Unique identifier for this event." }, { "name": ".is_error", "type": "boolean or null", "required": true, "description": "Whether the model request resulted in an error." }, { "name": ".model_request_start_id", "type": "string", "required": true, "description": "The id of the corresponding `span.model_request_start` event." }, { "name": ".model_usage", "type": "BetaManagedAgentsSpanModelUsage", "required": true, "description": "Token usage for a single model request." }, { "name": ".processed_at", "type": "string", "required": true, "description": "A timestamp in RFC 3339 format", "constraints": { "format": "date-time" } }, { "name": "", "type": "BetaManagedAgentsSpanOutcomeEvaluationOngoingEvent object", "required": false, "description": "Periodic heartbeat emitted while an outcome evaluation cycle is in progress. Distinguishes 'evaluation is actively running' from 'evaluation is stuck' between the corresponding `span.outcome_evaluation_start` and `span.outcome_evaluation_end` events." }, { "name": ".type", "type": "\"span.outcome_evaluation_ongoing\"", "required": true, "description": "" }, { "name": ".id", "type": "string", "required": true, "description": "Unique identifier for this event." }, { "name": ".iteration", "type": "number", "required": true, "description": "0-indexed revision cycle, matching the corresponding `span.outcome_evaluation_start`.", "constraints": { "format": "int32" } }, { "name": ".outcome_id", "type": "string", "required": true, "description": "The `outc_` ID of the outcome being evaluated." }, { "name": ".processed_at", "type": "string", "required": true, "description": "A timestamp in RFC 3339 format", "constraints": { "format": "date-time" } }, { "name": "", "type": "BetaManagedAgentsUserDefineOutcomeEvent object", "required": false, "description": "Echo of a `user.define_outcome` input event. Carries the server-generated `outcome_id` that subsequent `span.outcome_evaluation_*` events reference." }, { "name": ".type", "type": "\"user.define_outcome\"", "required": true, "description": "" }, { "name": ".id", "type": "string", "required": true, "description": "Unique identifier for this event." }, { "name": ".description", "type": "string", "required": true, "description": "What the agent should produce. Copied from the input event." }, { "name": ".max_iterations", "type": "number or null", "required": true, "description": "Evaluate-then-revise cycles before giving up. Default 3, max 20.", "constraints": { "format": "int32" } }, { "name": ".outcome_id", "type": "string", "required": true, "description": "Server-generated `outc_` ID for this outcome. Referenced by `span.outcome_evaluation_*` events and the session's `outcome_evaluations` list." }, { "name": ".processed_at", "type": "string", "required": true, "description": "A timestamp in RFC 3339 format", "constraints": { "format": "date-time" } }, { "name": ".rubric", "type": "BetaManagedAgentsFileRubric or BetaManagedAgentsTextRubric", "required": true, "description": "Rubric for grading the quality of an outcome." }, { "name": "", "type": "BetaManagedAgentsSessionDeletedEvent object", "required": false, "description": "Emitted when a session has been deleted. Terminates any active event stream — no further events will be emitted for this session." }, { "name": ".type", "type": "\"session.deleted\"", "required": true, "description": "" }, { "name": ".id", "type": "string", "required": true, "description": "Unique identifier for this event." }, { "name": ".processed_at", "type": "string", "required": true, "description": "A timestamp in RFC 3339 format", "constraints": { "format": "date-time" } }, { "name": "", "type": "BetaManagedAgentsSessionThreadStatusRunningEvent object", "required": false, "description": "A session thread has begun executing. Emitted on the thread's own stream and cross-posted to the primary stream for child threads." }, { "name": ".type", "type": "\"session.thread_status_running\"", "required": true, "description": "" }, { "name": ".id", "type": "string", "required": true, "description": "Unique identifier for this event." }, { "name": ".agent_name", "type": "string", "required": true, "description": "Name of the agent the thread runs." }, { "name": ".processed_at", "type": "string", "required": true, "description": "A timestamp in RFC 3339 format", "constraints": { "format": "date-time" } }, { "name": ".session_thread_id", "type": "string", "required": true, "description": "Public sthr_ ID of the thread that started running." }, { "name": "", "type": "BetaManagedAgentsSessionThreadStatusIdleEvent object", "required": false, "description": "A session thread has yielded and is awaiting input. Emitted on the thread's own stream and cross-posted to the primary stream for child threads." }, { "name": ".type", "type": "\"session.thread_status_idle\"", "required": true, "description": "" }, { "name": ".id", "type": "string", "required": true, "description": "Unique identifier for this event." }, { "name": ".agent_name", "type": "string", "required": true, "description": "Name of the agent the thread runs." }, { "name": ".processed_at", "type": "string", "required": true, "description": "A timestamp in RFC 3339 format", "constraints": { "format": "date-time" } }, { "name": ".session_thread_id", "type": "string", "required": true, "description": "Public sthr_ ID of the thread that went idle." }, { "name": ".stop_reason", "type": "BetaManagedAgentsSessionEndTurn or BetaManagedAgentsSessionRequiresAction or BetaManagedAgentsSessionRetriesExhausted or BetaManagedAgentsSessionBudgetReached", "required": true, "description": "" }, { "name": "", "type": "BetaManagedAgentsSessionThreadStatusTerminatedEvent object", "required": false, "description": "A session thread has terminated and will accept no further input. Emitted on the thread's own stream and cross-posted to the primary stream for child threads." }, { "name": ".type", "type": "\"session.thread_status_terminated\"", "required": true, "description": "" }, { "name": ".id", "type": "string", "required": true, "description": "Unique identifier for this event." }, { "name": ".agent_name", "type": "string", "required": true, "description": "Name of the agent the thread runs." }, { "name": ".processed_at", "type": "string", "required": true, "description": "A timestamp in RFC 3339 format", "constraints": { "format": "date-time" } }, { "name": ".session_thread_id", "type": "string", "required": true, "description": "Public sthr_ ID of the thread that terminated." }, { "name": "", "type": "BetaManagedAgentsUserToolResultEvent object", "required": false, "description": "Event sent by the client providing the result of an agent-toolset tool execution. Only valid on `self_hosted` environments, where sandbox-routed tools are executed by the client rather than the server." }, { "name": ".type", "type": "\"user.tool_result\"", "required": true, "description": "" }, { "name": ".id", "type": "string", "required": true, "description": "Unique identifier for this event." }, { "name": ".tool_use_id", "type": "string", "required": true, "description": "The id of the `agent.tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field." }, { "name": ".content", "type": "array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock", "required": false, "description": "The result content returned by the tool." }, { "name": ".is_error", "type": "boolean or null", "required": false, "description": "Whether the tool execution resulted in an error." }, { "name": ".processed_at", "type": "string or null", "required": false, "description": "A timestamp in RFC 3339 format", "constraints": { "format": "date-time" } }, { "name": ".session_thread_id", "type": "string or null", "required": false, "description": "Set by the server to the subagent thread this result was routed to. Omitted when it was routed to the primary thread." }, { "name": "", "type": "BetaManagedAgentsSessionThreadStatusRescheduledEvent object", "required": false, "description": "A session thread hit a transient error and is retrying automatically. Emitted on the thread's own stream and cross-posted to the primary stream for child threads." }, { "name": ".type", "type": "\"session.thread_status_rescheduled\"", "required": true, "description": "" }, { "name": ".id", "type": "string", "required": true, "description": "Unique identifier for this event." }, { "name": ".agent_name", "type": "string", "required": true, "description": "Name of the agent the thread runs." }, { "name": ".processed_at", "type": "string", "required": true, "description": "A timestamp in RFC 3339 format", "constraints": { "format": "date-time" } }, { "name": ".session_thread_id", "type": "string", "required": true, "description": "Public sthr_ ID of the thread that is retrying." }, { "name": "", "type": "BetaManagedAgentsSessionUpdatedEvent object", "required": false, "description": "Emitted when an UpdateSession request changed at least one field. Carries only the fields that changed; absent fields were not part of the update. The new configuration applies from the next turn." }, { "name": ".type", "type": "\"session.updated\"", "required": true, "description": "" }, { "name": ".id", "type": "string", "required": true, "description": "Unique identifier for this event." }, { "name": ".processed_at", "type": "string", "required": true, "description": "A timestamp in RFC 3339 format", "constraints": { "format": "date-time" } }, { "name": ".agent", "type": "BetaManagedAgentsSessionAgent or null", "required": false, "description": "Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time." }, { "name": ".budget", "type": "BetaManagedAgentsBudgetLimit or null", "required": false, "description": "A hard spend ceiling. The session stops issuing new model requests once the tracked list cost reaches `max_list_cost`." }, { "name": ".metadata", "type": "map[string]", "required": false, "description": "The session's full metadata bag after the update. Present when the update set non-empty metadata; absent when metadata was unchanged or cleared to empty." }, { "name": ".title", "type": "string or null", "required": false, "description": "The session's new title. Present only when the update changed it." }, { "name": "", "type": "BetaManagedAgentsSystemMessageEvent object", "required": false, "description": "A mid-conversation system message event. Carries system-role content that is appended to the session as a `role: \"system\"` turn." }, { "name": ".type", "type": "\"system.message\"", "required": true, "description": "" }, { "name": ".id", "type": "string", "required": true, "description": "Unique identifier for this event." }, { "name": ".content", "type": "array of BetaManagedAgentsSystemContentBlock", "required": true, "description": "System content blocks. Text-only." }, { "name": ".processed_at", "type": "string or null", "required": false, "description": "A timestamp in RFC 3339 format", "constraints": { "format": "date-time" } }, { "name": "", "type": "BetaManagedAgentsSessionUsageEvent object", "required": false, "description": "Periodic snapshot of the session's cumulative usage and tracked list cost." }, { "name": ".type", "type": "\"session.usage\"", "required": true, "description": "" }, { "name": ".id", "type": "string", "required": true, "description": "Unique identifier for this event." }, { "name": ".processed_at", "type": "string", "required": true, "description": "A timestamp in RFC 3339 format", "constraints": { "format": "date-time" } }, { "name": ".usage", "type": "BetaManagedAgentsSessionUsageSnapshot", "required": true, "description": "Point-in-time snapshot of a session's cumulative usage." }, { "name": ".budget", "type": "BetaManagedAgentsBudgetLimit or null", "required": false, "description": "A hard spend ceiling. The session stops issuing new model requests once the tracked list cost reaches `max_list_cost`." } ], "status": [ "DOCUMENTED", "BETA" ], "sources": [ { "url": "https://platform.claude.com/docs/en/api/beta/sessions/events/list", "retrieved_at": "2026-09-18" }, { "url": "https://platform.claude.com/docs/en/managed-agents/events-and-streaming", "retrieved_at": "2026-09-18" }, { "url": "https://platform.claude.com/docs/en/managed-agents/reference", "retrieved_at": "2026-09-18" } ], "beta_header": "managed-agents-2026-04-01", "_fragment": "generated/fragments/objects/anthropic-platform-objects.json" }, { "provider": "anthropic", "api_family": "managed-agents", "name": "StreamSessionEvents (SSE union incl. event_start/event_delta)", "official_type_name": "BetaManagedAgentsStreamSessionEvents", "description": "Server-sent event in the session stream.", "fields": [ { "name": "", "type": "BetaManagedAgentsUserMessageEvent object", "required": false, "description": "A user message event in the session conversation." }, { "name": ".type", "type": "\"user.message\"", "required": true, "description": "" }, { "name": ".id", "type": "string", "required": true, "description": "Unique identifier for this event." }, { "name": ".content", "type": "array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsRedactedBlock", "required": true, "description": "Array of content blocks comprising the user message." }, { "name": ".processed_at", "type": "string or null", "required": false, "description": "A timestamp in RFC 3339 format", "constraints": { "format": "date-time" } }, { "name": "", "type": "BetaManagedAgentsUserInterruptEvent object", "required": false, "description": "An interrupt event that pauses agent execution and returns control to the user." }, { "name": ".type", "type": "\"user.interrupt\"", "required": true, "description": "" }, { "name": ".id", "type": "string", "required": true, "description": "Unique identifier for this event." }, { "name": ".processed_at", "type": "string or null", "required": false, "description": "A timestamp in RFC 3339 format", "constraints": { "format": "date-time" } }, { "name": ".session_thread_id", "type": "string or null", "required": false, "description": "If absent, interrupts every non-archived thread in a multiagent session (or the primary alone in a single-agent session). If present, interrupts only the named thread." }, { "name": "", "type": "BetaManagedAgentsUserToolConfirmationEvent object", "required": false, "description": "A tool confirmation event that approves or denies a pending tool execution." }, { "name": ".type", "type": "\"user.tool_confirmation\"", "required": true, "description": "" }, { "name": ".id", "type": "string", "required": true, "description": "Unique identifier for this event." }, { "name": ".result", "type": "\"allow\" or \"deny\"", "required": true, "description": "UserToolConfirmationResult enum", "enum": [ "allow", "deny" ] }, { "name": ".tool_use_id", "type": "string", "required": true, "description": "The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field." }, { "name": ".deny_message", "type": "string or null", "required": false, "description": "Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'.", "constraints": { "maxLength": "10000" } }, { "name": ".processed_at", "type": "string or null", "required": false, "description": "A timestamp in RFC 3339 format", "constraints": { "format": "date-time" } }, { "name": ".session_thread_id", "type": "string or null", "required": false, "description": "Set by the server to the subagent thread this confirmation was routed to. Omitted when it was routed to the primary thread." }, { "name": "", "type": "BetaManagedAgentsUserCustomToolResultEvent object", "required": false, "description": "Event sent by the client providing the result of a custom tool execution." }, { "name": ".type", "type": "\"user.custom_tool_result\"", "required": true, "description": "" }, { "name": ".id", "type": "string", "required": true, "description": "Unique identifier for this event." }, { "name": ".custom_tool_use_id", "type": "string", "required": true, "description": "The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field." }, { "name": ".content", "type": "array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock", "required": false, "description": "The result content returned by the tool." }, { "name": ".is_error", "type": "boolean or null", "required": false, "description": "Whether the tool execution resulted in an error." }, { "name": ".processed_at", "type": "string or null", "required": false, "description": "A timestamp in RFC 3339 format", "constraints": { "format": "date-time" } }, { "name": ".session_thread_id", "type": "string or null", "required": false, "description": "Set by the server to the subagent thread this result was routed to. Omitted when it was routed to the primary thread." }, { "name": "", "type": "BetaManagedAgentsAgentCustomToolUseEvent object", "required": false, "description": "Event emitted when the agent calls a custom tool. The session goes idle until the client sends a `user.custom_tool_result` event with the result." }, { "name": ".type", "type": "\"agent.custom_tool_use\"", "required": true, "description": "" }, { "name": ".id", "type": "string", "required": true, "description": "Unique identifier for this event." }, { "name": ".input", "type": "map[unknown]", "required": true, "description": "Input parameters for the tool call." }, { "name": ".name", "type": "string", "required": true, "description": "Name of the custom tool being called." }, { "name": ".processed_at", "type": "string", "required": true, "description": "A timestamp in RFC 3339 format", "constraints": { "format": "date-time" } }, { "name": ".session_thread_id", "type": "string or null", "required": false, "description": "When set, this event was cross-posted from a subagent's thread to surface its custom tool use on the primary thread's stream. Empty on the thread's own events. Informational only: the server routes the matching `user.custom_tool_result` by `custom_tool_use_id`, so clients do not send it back." }, { "name": "", "type": "BetaManagedAgentsAgentMessageEvent object", "required": false, "description": "An agent response event in the session conversation." }, { "name": ".type", "type": "\"agent.message\"", "required": true, "description": "" }, { "name": ".id", "type": "string", "required": true, "description": "Unique identifier for this event." }, { "name": ".content", "type": "array of BetaManagedAgentsTextBlock or BetaManagedAgentsRedactedBlock", "required": true, "description": "Array of text blocks comprising the agent response." }, { "name": ".processed_at", "type": "string", "required": true, "description": "A timestamp in RFC 3339 format", "constraints": { "format": "date-time" } }, { "name": "", "type": "BetaManagedAgentsAgentThinkingEvent object", "required": false, "description": "Indicates the agent is making forward progress via extended thinking. A progress signal, not a content carrier." }, { "name": ".type", "type": "\"agent.thinking\"", "required": true, "description": "" }, { "name": ".id", "type": "string", "required": true, "description": "Unique identifier for this event." }, { "name": ".processed_at", "type": "string", "required": true, "description": "A timestamp in RFC 3339 format", "constraints": { "format": "date-time" } }, { "name": "", "type": "BetaManagedAgentsAgentMCPToolUseEvent object", "required": false, "description": "Event emitted when the agent invokes a tool provided by an MCP server." }, { "name": ".type", "type": "\"agent.mcp_tool_use\"", "required": true, "description": "" }, { "name": ".id", "type": "string", "required": true, "description": "Unique identifier for this event." }, { "name": ".input", "type": "map[unknown]", "required": true, "description": "Input parameters for the tool call." }, { "name": ".mcp_server_name", "type": "string", "required": true, "description": "Name of the MCP server providing the tool." }, { "name": ".name", "type": "string", "required": true, "description": "Name of the MCP tool being used." }, { "name": ".processed_at", "type": "string", "required": true, "description": "A timestamp in RFC 3339 format", "constraints": { "format": "date-time" } }, { "name": ".evaluated_permission", "type": "\"allow\" or \"ask\" or \"deny\"", "required": false, "description": "AgentEvaluatedPermission enum", "enum": [ "allow", "ask", "deny" ] }, { "name": ".evaluation", "type": "BetaManagedAgentsAgentToolEvaluation", "required": false, "description": "Names the resolved permission_policy that produced evaluated_permission, and under auto carries the judgement. Open union: clients must tolerate unknown variants." }, { "name": ".session_thread_id", "type": "string or null", "required": false, "description": "When set, this event was cross-posted from a subagent's thread to surface its permission request on the primary thread's stream. Empty on the thread's own events. Informational only: the server routes the matching `user.tool_confirmation` by `tool_use_id`, so clients do not send it back." }, { "name": "", "type": "BetaManagedAgentsAgentMCPToolResultEvent object", "required": false, "description": "Event representing the result of an MCP tool execution." }, { "name": ".type", "type": "\"agent.mcp_tool_result\"", "required": true, "description": "" }, { "name": ".id", "type": "string", "required": true, "description": "Unique identifier for this event." }, { "name": ".mcp_tool_use_id", "type": "string", "required": true, "description": "The id of the `agent.mcp_tool_use` event this result corresponds to." }, { "name": ".processed_at", "type": "string", "required": true, "description": "A timestamp in RFC 3339 format", "constraints": { "format": "date-time" } }, { "name": ".content", "type": "array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock", "required": false, "description": "The result content returned by the tool." }, { "name": ".is_error", "type": "boolean or null", "required": false, "description": "Whether the tool execution resulted in an error." }, { "name": "", "type": "BetaManagedAgentsAgentToolUseEvent object", "required": false, "description": "Event emitted when the agent invokes a built-in agent tool." }, { "name": ".type", "type": "\"agent.tool_use\"", "required": true, "description": "" }, { "name": ".id", "type": "string", "required": true, "description": "Unique identifier for this event." }, { "name": ".input", "type": "map[unknown]", "required": true, "description": "Input parameters for the tool call." }, { "name": ".name", "type": "string", "required": true, "description": "Name of the agent tool being used." }, { "name": ".processed_at", "type": "string", "required": true, "description": "A timestamp in RFC 3339 format", "constraints": { "format": "date-time" } }, { "name": ".evaluated_permission", "type": "\"allow\" or \"ask\" or \"deny\"", "required": false, "description": "AgentEvaluatedPermission enum", "enum": [ "allow", "ask", "deny" ] }, { "name": ".evaluation", "type": "BetaManagedAgentsAgentToolEvaluation", "required": false, "description": "Names the resolved permission_policy that produced evaluated_permission, and under auto carries the judgement. Open union: clients must tolerate unknown variants." }, { "name": ".session_thread_id", "type": "string or null", "required": false, "description": "When set, this event was cross-posted from a subagent's thread to surface its permission request on the primary thread's stream. Empty on the thread's own events. Informational only: the server routes the matching `user.tool_confirmation` or `user.tool_result` by `tool_use_id`, so clients do not send it back." }, { "name": "", "type": "BetaManagedAgentsAgentToolResultEvent object", "required": false, "description": "Event representing the result of an agent tool execution." }, { "name": ".type", "type": "\"agent.tool_result\"", "required": true, "description": "" }, { "name": ".id", "type": "string", "required": true, "description": "Unique identifier for this event." }, { "name": ".processed_at", "type": "string", "required": true, "description": "A timestamp in RFC 3339 format", "constraints": { "format": "date-time" } }, { "name": ".tool_use_id", "type": "string", "required": true, "description": "The id of the `agent.tool_use` event this result corresponds to." }, { "name": ".content", "type": "array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock", "required": false, "description": "The result content returned by the tool." }, { "name": ".is_error", "type": "boolean or null", "required": false, "description": "Whether the tool execution resulted in an error." }, { "name": "", "type": "BetaManagedAgentsAgentThreadMessageReceivedEvent object", "required": false, "description": "Delivery event written to the target thread's input stream when an agent-to-agent message arrives." }, { "name": ".type", "type": "\"agent.thread_message_received\"", "required": true, "description": "" }, { "name": ".id", "type": "string", "required": true, "description": "Unique identifier for this event." }, { "name": ".content", "type": "array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsRedactedBlock", "required": true, "description": "Message content blocks." }, { "name": ".from_session_thread_id", "type": "string", "required": true, "description": "Public `sthr_` ID of the thread that sent the message." }, { "name": ".processed_at", "type": "string", "required": true, "description": "A timestamp in RFC 3339 format", "constraints": { "format": "date-time" } }, { "name": ".from_agent_name", "type": "string or null", "required": false, "description": "Name of the callable agent this message came from. Absent when received from the primary agent." }, { "name": "", "type": "BetaManagedAgentsAgentThreadMessageSentEvent object", "required": false, "description": "Observability event emitted to the sender's output stream when an agent-to-agent message is sent." }, { "name": ".type", "type": "\"agent.thread_message_sent\"", "required": true, "description": "" }, { "name": ".id", "type": "string", "required": true, "description": "Unique identifier for this event." }, { "name": ".content", "type": "array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsRedactedBlock", "required": true, "description": "Message content blocks." }, { "name": ".processed_at", "type": "string", "required": true, "description": "A timestamp in RFC 3339 format", "constraints": { "format": "date-time" } }, { "name": ".to_session_thread_id", "type": "string", "required": true, "description": "Public `sthr_` ID of the thread the message was sent to." }, { "name": ".to_agent_name", "type": "string or null", "required": false, "description": "Name of the callable agent this message was sent to. Absent when sent to the primary agent." }, { "name": "", "type": "BetaManagedAgentsAgentThreadContextCompactedEvent object", "required": false, "description": "Indicates that context compaction (summarization) occurred during the session." }, { "name": ".type", "type": "\"agent.thread_context_compacted\"", "required": true, "description": "" }, { "name": ".id", "type": "string", "required": true, "description": "Unique identifier for this event." }, { "name": ".processed_at", "type": "string", "required": true, "description": "A timestamp in RFC 3339 format", "constraints": { "format": "date-time" } }, { "name": "", "type": "BetaManagedAgentsSessionErrorEvent object", "required": false, "description": "An error event indicating a problem occurred during session execution." }, { "name": ".type", "type": "\"session.error\"", "required": true, "description": "" }, { "name": ".id", "type": "string", "required": true, "description": "Unique identifier for this event." }, { "name": ".error", "type": "BetaManagedAgentsUnknownError or BetaManagedAgentsModelOverloadedError or BetaManagedAgentsModelRateLimitedError or 5 more", "required": true, "description": "" }, { "name": ".processed_at", "type": "string", "required": true, "description": "A timestamp in RFC 3339 format", "constraints": { "format": "date-time" } }, { "name": "", "type": "BetaManagedAgentsSessionStatusRescheduledEvent object", "required": false, "description": "Indicates the session is recovering from an error state and is rescheduled for execution." }, { "name": ".type", "type": "\"session.status_rescheduled\"", "required": true, "description": "" }, { "name": ".id", "type": "string", "required": true, "description": "Unique identifier for this event." }, { "name": ".processed_at", "type": "string", "required": true, "description": "A timestamp in RFC 3339 format", "constraints": { "format": "date-time" } }, { "name": "", "type": "BetaManagedAgentsSessionStatusRunningEvent object", "required": false, "description": "Indicates the session is actively running and the agent is working." }, { "name": ".type", "type": "\"session.status_running\"", "required": true, "description": "" }, { "name": ".id", "type": "string", "required": true, "description": "Unique identifier for this event." }, { "name": ".processed_at", "type": "string", "required": true, "description": "A timestamp in RFC 3339 format", "constraints": { "format": "date-time" } }, { "name": "", "type": "BetaManagedAgentsSessionStatusIdleEvent object", "required": false, "description": "Indicates the agent has paused and is awaiting user input." }, { "name": ".type", "type": "\"session.status_idle\"", "required": true, "description": "" }, { "name": ".id", "type": "string", "required": true, "description": "Unique identifier for this event." }, { "name": ".processed_at", "type": "string", "required": true, "description": "A timestamp in RFC 3339 format", "constraints": { "format": "date-time" } }, { "name": ".stop_reason", "type": "BetaManagedAgentsSessionEndTurn or BetaManagedAgentsSessionRequiresAction or BetaManagedAgentsSessionRetriesExhausted or BetaManagedAgentsSessionBudgetReached", "required": true, "description": "" }, { "name": "", "type": "BetaManagedAgentsSessionStatusTerminatedEvent object", "required": false, "description": "Indicates the session has terminated, either due to an error or completion." }, { "name": ".type", "type": "\"session.status_terminated\"", "required": true, "description": "" }, { "name": ".id", "type": "string", "required": true, "description": "Unique identifier for this event." }, { "name": ".processed_at", "type": "string", "required": true, "description": "A timestamp in RFC 3339 format", "constraints": { "format": "date-time" } }, { "name": "", "type": "BetaManagedAgentsSessionThreadCreatedEvent object", "required": false, "description": "Emitted when a subagent is spawned as a new thread. Written to the parent thread's output stream so clients observing the session see child creation." }, { "name": ".type", "type": "\"session.thread_created\"", "required": true, "description": "" }, { "name": ".id", "type": "string", "required": true, "description": "Unique identifier for this event." }, { "name": ".agent_name", "type": "string", "required": true, "description": "Name of the callable agent the thread runs." }, { "name": ".processed_at", "type": "string", "required": true, "description": "A timestamp in RFC 3339 format", "constraints": { "format": "date-time" } }, { "name": ".session_thread_id", "type": "string", "required": true, "description": "Public `sthr_` ID of the newly created thread." }, { "name": "", "type": "BetaManagedAgentsSpanOutcomeEvaluationStartEvent object", "required": false, "description": "Emitted when an outcome evaluation cycle begins." }, { "name": ".type", "type": "\"span.outcome_evaluation_start\"", "required": true, "description": "" }, { "name": ".id", "type": "string", "required": true, "description": "Unique identifier for this event." }, { "name": ".iteration", "type": "number", "required": true, "description": "0-indexed revision cycle. 0 is the first evaluation; 1 is the re-evaluation after the first revision; etc.", "constraints": { "format": "int32" } }, { "name": ".outcome_id", "type": "string", "required": true, "description": "The `outc_` ID of the outcome being evaluated." }, { "name": ".processed_at", "type": "string", "required": true, "description": "A timestamp in RFC 3339 format", "constraints": { "format": "date-time" } }, { "name": "", "type": "BetaManagedAgentsSpanOutcomeEvaluationEndEvent object", "required": false, "description": "Emitted when an outcome evaluation cycle completes. Carries the verdict and aggregate token usage. A verdict of `needs_revision` means another evaluation cycle follows; `satisfied`, `max_iterations_reached`, `failed`, or `interrupted` are terminal — no further evaluation cycles follow." }, { "name": ".type", "type": "\"span.outcome_evaluation_end\"", "required": true, "description": "" }, { "name": ".id", "type": "string", "required": true, "description": "Unique identifier for this event." }, { "name": ".explanation", "type": "string", "required": true, "description": "Human-readable explanation of the verdict. For `needs_revision`, describes which criteria failed and why." }, { "name": ".iteration", "type": "number", "required": true, "description": "0-indexed revision cycle, matching the corresponding `span.outcome_evaluation_start`.", "constraints": { "format": "int32" } }, { "name": ".outcome_evaluation_start_id", "type": "string", "required": true, "description": "The id of the corresponding `span.outcome_evaluation_start` event." }, { "name": ".outcome_id", "type": "string", "required": true, "description": "The `outc_` ID of the outcome being evaluated." }, { "name": ".processed_at", "type": "string", "required": true, "description": "A timestamp in RFC 3339 format", "constraints": { "format": "date-time" } }, { "name": ".result", "type": "string", "required": true, "description": "Evaluation verdict. 'satisfied': criteria met, session goes idle. 'needs_revision': criteria not met, another revision cycle follows. 'max_iterations_reached': evaluation budget exhausted with criteria still unmet — one final acknowledgment turn follows before the session goes idle, but no further evaluation runs. 'failed': grader determined the rubric does not apply to the deliverables. 'interrupted': user sent an interrupt while evaluation was in progress." }, { "name": ".usage", "type": "BetaManagedAgentsSpanModelUsage", "required": true, "description": "Token usage for a single model request." }, { "name": "", "type": "BetaManagedAgentsSpanModelRequestStartEvent object", "required": false, "description": "Emitted when a model request is initiated by the agent." }, { "name": ".type", "type": "\"span.model_request_start\"", "required": true, "description": "" }, { "name": ".id", "type": "string", "required": true, "description": "Unique identifier for this event." }, { "name": ".processed_at", "type": "string", "required": true, "description": "A timestamp in RFC 3339 format", "constraints": { "format": "date-time" } }, { "name": "", "type": "BetaManagedAgentsSpanModelRequestEndEvent object", "required": false, "description": "Emitted when a model request completes." }, { "name": ".type", "type": "\"span.model_request_end\"", "required": true, "description": "" }, { "name": ".id", "type": "string", "required": true, "description": "Unique identifier for this event." }, { "name": ".is_error", "type": "boolean or null", "required": true, "description": "Whether the model request resulted in an error." }, { "name": ".model_request_start_id", "type": "string", "required": true, "description": "The id of the corresponding `span.model_request_start` event." }, { "name": ".model_usage", "type": "BetaManagedAgentsSpanModelUsage", "required": true, "description": "Token usage for a single model request." }, { "name": ".processed_at", "type": "string", "required": true, "description": "A timestamp in RFC 3339 format", "constraints": { "format": "date-time" } }, { "name": "", "type": "BetaManagedAgentsSpanOutcomeEvaluationOngoingEvent object", "required": false, "description": "Periodic heartbeat emitted while an outcome evaluation cycle is in progress. Distinguishes 'evaluation is actively running' from 'evaluation is stuck' between the corresponding `span.outcome_evaluation_start` and `span.outcome_evaluation_end` events." }, { "name": ".type", "type": "\"span.outcome_evaluation_ongoing\"", "required": true, "description": "" }, { "name": ".id", "type": "string", "required": true, "description": "Unique identifier for this event." }, { "name": ".iteration", "type": "number", "required": true, "description": "0-indexed revision cycle, matching the corresponding `span.outcome_evaluation_start`.", "constraints": { "format": "int32" } }, { "name": ".outcome_id", "type": "string", "required": true, "description": "The `outc_` ID of the outcome being evaluated." }, { "name": ".processed_at", "type": "string", "required": true, "description": "A timestamp in RFC 3339 format", "constraints": { "format": "date-time" } }, { "name": "", "type": "BetaManagedAgentsUserDefineOutcomeEvent object", "required": false, "description": "Echo of a `user.define_outcome` input event. Carries the server-generated `outcome_id` that subsequent `span.outcome_evaluation_*` events reference." }, { "name": ".type", "type": "\"user.define_outcome\"", "required": true, "description": "" }, { "name": ".id", "type": "string", "required": true, "description": "Unique identifier for this event." }, { "name": ".description", "type": "string", "required": true, "description": "What the agent should produce. Copied from the input event." }, { "name": ".max_iterations", "type": "number or null", "required": true, "description": "Evaluate-then-revise cycles before giving up. Default 3, max 20.", "constraints": { "format": "int32" } }, { "name": ".outcome_id", "type": "string", "required": true, "description": "Server-generated `outc_` ID for this outcome. Referenced by `span.outcome_evaluation_*` events and the session's `outcome_evaluations` list." }, { "name": ".processed_at", "type": "string", "required": true, "description": "A timestamp in RFC 3339 format", "constraints": { "format": "date-time" } }, { "name": ".rubric", "type": "BetaManagedAgentsFileRubric or BetaManagedAgentsTextRubric", "required": true, "description": "Rubric for grading the quality of an outcome." }, { "name": "", "type": "BetaManagedAgentsSessionDeletedEvent object", "required": false, "description": "Emitted when a session has been deleted. Terminates any active event stream — no further events will be emitted for this session." }, { "name": ".type", "type": "\"session.deleted\"", "required": true, "description": "" }, { "name": ".id", "type": "string", "required": true, "description": "Unique identifier for this event." }, { "name": ".processed_at", "type": "string", "required": true, "description": "A timestamp in RFC 3339 format", "constraints": { "format": "date-time" } }, { "name": "", "type": "BetaManagedAgentsSessionThreadStatusRunningEvent object", "required": false, "description": "A session thread has begun executing. Emitted on the thread's own stream and cross-posted to the primary stream for child threads." }, { "name": ".type", "type": "\"session.thread_status_running\"", "required": true, "description": "" }, { "name": ".id", "type": "string", "required": true, "description": "Unique identifier for this event." }, { "name": ".agent_name", "type": "string", "required": true, "description": "Name of the agent the thread runs." }, { "name": ".processed_at", "type": "string", "required": true, "description": "A timestamp in RFC 3339 format", "constraints": { "format": "date-time" } }, { "name": ".session_thread_id", "type": "string", "required": true, "description": "Public sthr_ ID of the thread that started running." }, { "name": "", "type": "BetaManagedAgentsSessionThreadStatusIdleEvent object", "required": false, "description": "A session thread has yielded and is awaiting input. Emitted on the thread's own stream and cross-posted to the primary stream for child threads." }, { "name": ".type", "type": "\"session.thread_status_idle\"", "required": true, "description": "" }, { "name": ".id", "type": "string", "required": true, "description": "Unique identifier for this event." }, { "name": ".agent_name", "type": "string", "required": true, "description": "Name of the agent the thread runs." }, { "name": ".processed_at", "type": "string", "required": true, "description": "A timestamp in RFC 3339 format", "constraints": { "format": "date-time" } }, { "name": ".session_thread_id", "type": "string", "required": true, "description": "Public sthr_ ID of the thread that went idle." }, { "name": ".stop_reason", "type": "BetaManagedAgentsSessionEndTurn or BetaManagedAgentsSessionRequiresAction or BetaManagedAgentsSessionRetriesExhausted or BetaManagedAgentsSessionBudgetReached", "required": true, "description": "" }, { "name": "", "type": "BetaManagedAgentsSessionThreadStatusTerminatedEvent object", "required": false, "description": "A session thread has terminated and will accept no further input. Emitted on the thread's own stream and cross-posted to the primary stream for child threads." }, { "name": ".type", "type": "\"session.thread_status_terminated\"", "required": true, "description": "" }, { "name": ".id", "type": "string", "required": true, "description": "Unique identifier for this event." }, { "name": ".agent_name", "type": "string", "required": true, "description": "Name of the agent the thread runs." }, { "name": ".processed_at", "type": "string", "required": true, "description": "A timestamp in RFC 3339 format", "constraints": { "format": "date-time" } }, { "name": ".session_thread_id", "type": "string", "required": true, "description": "Public sthr_ ID of the thread that terminated." }, { "name": "", "type": "BetaManagedAgentsUserToolResultEvent object", "required": false, "description": "Event sent by the client providing the result of an agent-toolset tool execution. Only valid on `self_hosted` environments, where sandbox-routed tools are executed by the client rather than the server." }, { "name": ".type", "type": "\"user.tool_result\"", "required": true, "description": "" }, { "name": ".id", "type": "string", "required": true, "description": "Unique identifier for this event." }, { "name": ".tool_use_id", "type": "string", "required": true, "description": "The id of the `agent.tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field." }, { "name": ".content", "type": "array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock", "required": false, "description": "The result content returned by the tool." }, { "name": ".is_error", "type": "boolean or null", "required": false, "description": "Whether the tool execution resulted in an error." }, { "name": ".processed_at", "type": "string or null", "required": false, "description": "A timestamp in RFC 3339 format", "constraints": { "format": "date-time" } }, { "name": ".session_thread_id", "type": "string or null", "required": false, "description": "Set by the server to the subagent thread this result was routed to. Omitted when it was routed to the primary thread." }, { "name": "", "type": "BetaManagedAgentsSessionThreadStatusRescheduledEvent object", "required": false, "description": "A session thread hit a transient error and is retrying automatically. Emitted on the thread's own stream and cross-posted to the primary stream for child threads." }, { "name": ".type", "type": "\"session.thread_status_rescheduled\"", "required": true, "description": "" }, { "name": ".id", "type": "string", "required": true, "description": "Unique identifier for this event." }, { "name": ".agent_name", "type": "string", "required": true, "description": "Name of the agent the thread runs." }, { "name": ".processed_at", "type": "string", "required": true, "description": "A timestamp in RFC 3339 format", "constraints": { "format": "date-time" } }, { "name": ".session_thread_id", "type": "string", "required": true, "description": "Public sthr_ ID of the thread that is retrying." }, { "name": "", "type": "BetaManagedAgentsSessionUpdatedEvent object", "required": false, "description": "Emitted when an UpdateSession request changed at least one field. Carries only the fields that changed; absent fields were not part of the update. The new configuration applies from the next turn." }, { "name": ".type", "type": "\"session.updated\"", "required": true, "description": "" }, { "name": ".id", "type": "string", "required": true, "description": "Unique identifier for this event." }, { "name": ".processed_at", "type": "string", "required": true, "description": "A timestamp in RFC 3339 format", "constraints": { "format": "date-time" } }, { "name": ".agent", "type": "BetaManagedAgentsSessionAgent or null", "required": false, "description": "Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time." }, { "name": ".budget", "type": "BetaManagedAgentsBudgetLimit or null", "required": false, "description": "A hard spend ceiling. The session stops issuing new model requests once the tracked list cost reaches `max_list_cost`." }, { "name": ".metadata", "type": "map[string]", "required": false, "description": "The session's full metadata bag after the update. Present when the update set non-empty metadata; absent when metadata was unchanged or cleared to empty." }, { "name": ".title", "type": "string or null", "required": false, "description": "The session's new title. Present only when the update changed it." }, { "name": "", "type": "BetaManagedAgentsStartEvent object", "required": false, "description": "Opens a preview of a buffered event. Carries the previewed event's type and id only. Followed by zero or more event_delta events with the same event id, normally concluded by the buffered event carrying that id. If the producing model request ends without that event (an error or interrupt mid-stream), its terminal span.model_request_end closes the preview. Only sent on stream connections that opt in via event_deltas; never appears in event history." }, { "name": ".type", "type": "\"event_start\"", "required": true, "description": "" }, { "name": ".event", "type": "BetaManagedAgentsStartEventPreview", "required": true, "description": "The previewed event's type and id. The event type determines which delta types the preview's event_delta events carry: agent.message events stream content_delta fragments; agent.thinking previews are start-only — no deltas follow, and the buffered agent.thinking with the same id concludes them." }, { "name": "", "type": "BetaManagedAgentsDeltaEvent object", "required": false, "description": "An incremental update to an event that is still being streamed. Deltas are best-effort and may stop early; when the buffered event with id == event_id is produced it carries the complete content. A model request that ends early (an error or interrupt) produces no buffered event — its terminal span.model_request_end closes the preview. Only sent on stream connections that opt in via event_deltas; never appears in event history." }, { "name": ".type", "type": "\"event_delta\"", "required": true, "description": "" }, { "name": ".delta", "type": "BetaManagedAgentsDeltaContent", "required": true, "description": "One fragment of the previewed event. The delta type is named for the previewed event's field it streams into: agent.message events stream content_delta fragments, each a partial element of the content array." }, { "name": ".event_id", "type": "string", "required": true, "description": "The id of the event being previewed. Matches event.id on the corresponding event_start and the buffered event that reconciles the preview." }, { "name": "", "type": "BetaManagedAgentsSystemMessageEvent object", "required": false, "description": "A mid-conversation system message event. Carries system-role content that is appended to the session as a `role: \"system\"` turn." }, { "name": ".type", "type": "\"system.message\"", "required": true, "description": "" }, { "name": ".id", "type": "string", "required": true, "description": "Unique identifier for this event." }, { "name": ".content", "type": "array of BetaManagedAgentsSystemContentBlock", "required": true, "description": "System content blocks. Text-only." }, { "name": ".processed_at", "type": "string or null", "required": false, "description": "A timestamp in RFC 3339 format", "constraints": { "format": "date-time" } }, { "name": "", "type": "BetaManagedAgentsSessionUsageEvent object", "required": false, "description": "Periodic snapshot of the session's cumulative usage and tracked list cost." }, { "name": ".type", "type": "\"session.usage\"", "required": true, "description": "" }, { "name": ".id", "type": "string", "required": true, "description": "Unique identifier for this event." }, { "name": ".processed_at", "type": "string", "required": true, "description": "A timestamp in RFC 3339 format", "constraints": { "format": "date-time" } }, { "name": ".usage", "type": "BetaManagedAgentsSessionUsageSnapshot", "required": true, "description": "Point-in-time snapshot of a session's cumulative usage." }, { "name": ".budget", "type": "BetaManagedAgentsBudgetLimit or null", "required": false, "description": "A hard spend ceiling. The session stops issuing new model requests once the tracked list cost reaches `max_list_cost`." } ], "status": [ "DOCUMENTED", "BETA" ], "sources": [ { "url": "https://platform.claude.com/docs/en/api/beta/sessions/events/stream", "retrieved_at": "2026-09-18" }, { "url": "https://platform.claude.com/docs/en/managed-agents/events-and-streaming", "retrieved_at": "2026-09-18" } ], "beta_header": "managed-agents-2026-04-01", "_fragment": "generated/fragments/objects/anthropic-platform-objects.json" }, { "provider": "anthropic", "api_family": "managed-agents", "name": "SendSessionEventsParams (request body)", "official_type_name": "BetaManagedAgentsEventParams", "description": "Send Events", "fields": [ { "name": "events", "type": "array of BetaManagedAgentsEventParams", "required": true, "description": "Events to send to the `session`." }, { "name": "events", "type": "BetaManagedAgentsUserMessageEventParams object", "required": false, "description": "Parameters for sending a user message to the session." }, { "name": "events.type", "type": "\"user.message\"", "required": true, "description": "" }, { "name": "events.content", "type": "array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsRedactedBlock", "required": true, "description": "Array of content blocks for the user message." }, { "name": "events.content", "type": "BetaManagedAgentsTextBlock object", "required": false, "description": "Regular text content." }, { "name": "events.content.type", "type": "\"text\"", "required": true, "description": "" }, { "name": "events.content.text", "type": "string", "required": true, "description": "The text content.", "constraints": { "minLength": "1" } }, { "name": "events.content", "type": "BetaManagedAgentsImageBlock object", "required": false, "description": "Image content specified directly as base64 data or as a reference via a URL." }, { "name": "events.content.type", "type": "\"image\"", "required": true, "description": "" }, { "name": "events.content.source", "type": "BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource", "required": true, "description": "Union type for image source variants." }, { "name": "events.content.source", "type": "BetaManagedAgentsBase64ImageSource object", "required": false, "description": "Base64-encoded image data." }, { "name": "events.content.source.type", "type": "\"base64\"", "required": true, "description": "" }, { "name": "events.content.source.data", "type": "string", "required": true, "description": "Base64-encoded image data.", "constraints": { "minLength": "1" } }, { "name": "events.content.source.media_type", "type": "string", "required": true, "description": "MIME type of the image (e.g., \"image/png\", \"image/jpeg\", \"image/gif\", \"image/webp\").", "constraints": { "minLength": "1" } }, { "name": "events.content.source", "type": "BetaManagedAgentsURLImageSource object", "required": false, "description": "Image referenced by URL." }, { "name": "events.content.source.type", "type": "\"url\"", "required": true, "description": "" }, { "name": "events.content.source.url", "type": "string", "required": true, "description": "URL of the image to fetch.", "constraints": { "minLength": "1" } }, { "name": "events.content.source", "type": "BetaManagedAgentsFileImageSource object", "required": false, "description": "Image referenced by file ID." }, { "name": "events.content.source.type", "type": "\"file\"", "required": true, "description": "" }, { "name": "events.content.source.file_id", "type": "string", "required": true, "description": "ID of a previously uploaded file.", "constraints": { "minLength": "1" } }, { "name": "events.content", "type": "BetaManagedAgentsDocumentBlock object", "required": false, "description": "Document content, either specified directly as base64 data, as text, or as a reference via a URL." }, { "name": "events.content.type", "type": "\"document\"", "required": true, "description": "" }, { "name": "events.content.source", "type": "BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource", "required": true, "description": "Union type for document source variants." }, { "name": "events.content.source", "type": "BetaManagedAgentsBase64DocumentSource object", "required": false, "description": "Base64-encoded document data." }, { "name": "events.content.source.type", "type": "\"base64\"", "required": true, "description": "" }, { "name": "events.content.source.data", "type": "string", "required": true, "description": "Base64-encoded document data.", "constraints": { "minLength": "1" } }, { "name": "events.content.source.media_type", "type": "string", "required": true, "description": "MIME type of the document (e.g., \"application/pdf\").", "constraints": { "minLength": "1" } }, { "name": "events.content.source", "type": "BetaManagedAgentsPlainTextDocumentSource object", "required": false, "description": "Plain text document content." }, { "name": "events.content.source.type", "type": "\"text\"", "required": true, "description": "" }, { "name": "events.content.source.data", "type": "string", "required": true, "description": "The plain text content.", "constraints": { "minLength": "1" } }, { "name": "events.content.source.media_type", "type": "\"text/plain\"", "required": true, "description": "MIME type of the text content. Must be \"text/plain\"." }, { "name": "events.content.source", "type": "BetaManagedAgentsURLDocumentSource object", "required": false, "description": "Document referenced by URL." }, { "name": "events.content.source.type", "type": "\"url\"", "required": true, "description": "" }, { "name": "events.content.source.url", "type": "string", "required": true, "description": "URL of the document to fetch.", "constraints": { "minLength": "1" } }, { "name": "events.content.source", "type": "BetaManagedAgentsFileDocumentSource object", "required": false, "description": "Document referenced by file ID." }, { "name": "events.content.source.type", "type": "\"file\"", "required": true, "description": "" }, { "name": "events.content.source.file_id", "type": "string", "required": true, "description": "ID of a previously uploaded file.", "constraints": { "minLength": "1" } }, { "name": "events.content.context", "type": "string or null", "required": false, "description": "Additional context about the document for the model." }, { "name": "events.content.title", "type": "string or null", "required": false, "description": "The title of the document." }, { "name": "events.content", "type": "BetaManagedAgentsRedactedBlock object", "required": false, "description": "Placeholder for content withheld by Anthropic model policy." }, { "name": "events.content.type", "type": "\"redacted\"", "required": true, "description": "" }, { "name": "events", "type": "BetaManagedAgentsUserInterruptEventParams object", "required": false, "description": "Parameters for sending an interrupt to pause the agent." }, { "name": "events.type", "type": "\"user.interrupt\"", "required": true, "description": "" }, { "name": "events.session_thread_id", "type": "string or null", "required": false, "description": "If absent, interrupts every non-archived thread in a multiagent session (or the primary alone in a single-agent session). If present, interrupts only the named thread." }, { "name": "events", "type": "BetaManagedAgentsUserToolConfirmationEventParams object", "required": false, "description": "Parameters for confirming or denying a tool execution request." }, { "name": "events.type", "type": "\"user.tool_confirmation\"", "required": true, "description": "" }, { "name": "events.result", "type": "\"allow\" or \"deny\"", "required": true, "description": "UserToolConfirmationResult enum", "enum": [ "allow", "deny" ] }, { "name": "events.tool_use_id", "type": "string", "required": true, "description": "The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field.", "constraints": { "minLength": "1", "maxLength": "128" } }, { "name": "events.deny_message", "type": "string or null", "required": false, "description": "Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'.", "constraints": { "maxLength": "10000" } }, { "name": "events", "type": "BetaManagedAgentsUserCustomToolResultEventParams object", "required": false, "description": "Parameters for providing the result of a custom tool execution." }, { "name": "events.type", "type": "\"user.custom_tool_result\"", "required": true, "description": "" }, { "name": "events.custom_tool_use_id", "type": "string", "required": true, "description": "The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field.", "constraints": { "minLength": "1", "maxLength": "128" } }, { "name": "events.content", "type": "array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock", "required": false, "description": "The result content returned by the tool." }, { "name": "events.content", "type": "BetaManagedAgentsTextBlock object", "required": false, "description": "Regular text content." }, { "name": "events.content", "type": "BetaManagedAgentsImageBlock object", "required": false, "description": "Image content specified directly as base64 data or as a reference via a URL." }, { "name": "events.content", "type": "BetaManagedAgentsDocumentBlock object", "required": false, "description": "Document content, either specified directly as base64 data, as text, or as a reference via a URL." }, { "name": "events.content", "type": "BetaManagedAgentsSearchResultBlock object", "required": false, "description": "A block containing a web search result." }, { "name": "events.content.type", "type": "\"search_result\"", "required": true, "description": "" }, { "name": "events.content.citations", "type": "BetaManagedAgentsSearchResultCitations", "required": true, "description": "Citation settings for a search result." }, { "name": "events.content.citations.enabled", "type": "boolean", "required": true, "description": "Whether citations are enabled for this search result." }, { "name": "events.content.content", "type": "array of BetaManagedAgentsSearchResultContent", "required": true, "description": "Array of text content blocks from the search result." }, { "name": "events.content.content.type", "type": "\"text\"", "required": true, "description": "" }, { "name": "events.content.content.text", "type": "string", "required": true, "description": "The text content.", "constraints": { "minLength": "1" } }, { "name": "events.content.source", "type": "string", "required": true, "description": "The URL source of the search result.", "constraints": { "minLength": "1" } }, { "name": "events.content.title", "type": "string", "required": true, "description": "The title of the search result.", "constraints": { "minLength": "1" } }, { "name": "events.is_error", "type": "boolean or null", "required": false, "description": "Whether the tool execution resulted in an error." }, { "name": "events", "type": "BetaManagedAgentsUserDefineOutcomeEventParams object", "required": false, "description": "Parameters for defining an outcome the agent should work toward. The agent begins work on receipt." }, { "name": "events.type", "type": "\"user.define_outcome\"", "required": true, "description": "" }, { "name": "events.description", "type": "string", "required": true, "description": "What the agent should produce. This is the task specification." }, { "name": "events.rubric", "type": "BetaManagedAgentsFileRubricParams or BetaManagedAgentsTextRubricParams", "required": true, "description": "Rubric for grading the quality of an outcome." }, { "name": "events.rubric", "type": "BetaManagedAgentsFileRubricParams object", "required": false, "description": "Rubric referenced by a file uploaded via the Files API." }, { "name": "events.rubric.type", "type": "\"file\"", "required": true, "description": "" }, { "name": "events.rubric.file_id", "type": "string", "required": true, "description": "ID of the rubric file." }, { "name": "events.rubric", "type": "BetaManagedAgentsTextRubricParams object", "required": false, "description": "Rubric content provided inline as text." }, { "name": "events.rubric.type", "type": "\"text\"", "required": true, "description": "" }, { "name": "events.rubric.content", "type": "string", "required": true, "description": "Rubric content. Plain text or markdown — the grader treats it as freeform text. Maximum 262144 characters.", "constraints": { "maxLength": "262144" } }, { "name": "events.max_iterations", "type": "number or null", "required": false, "description": "Eval→revision cycles before giving up. Default 3, max 20.", "constraints": { "format": "int32" } }, { "name": "events", "type": "BetaManagedAgentsUserToolResultEventParams object", "required": false, "description": "Parameters for providing the result of an agent-toolset tool execution. Only valid on `self_hosted` environments, where sandbox-routed tools are executed by the client rather than the server." }, { "name": "events.type", "type": "\"user.tool_result\"", "required": true, "description": "" }, { "name": "events.tool_use_id", "type": "string", "required": true, "description": "The id of the `agent.tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field.", "constraints": { "minLength": "1", "maxLength": "128" } }, { "name": "events.content", "type": "array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock", "required": false, "description": "The result content returned by the tool." }, { "name": "events.content", "type": "BetaManagedAgentsTextBlock object", "required": false, "description": "Regular text content." }, { "name": "events.content", "type": "BetaManagedAgentsImageBlock object", "required": false, "description": "Image content specified directly as base64 data or as a reference via a URL." }, { "name": "events.content", "type": "BetaManagedAgentsDocumentBlock object", "required": false, "description": "Document content, either specified directly as base64 data, as text, or as a reference via a URL." }, { "name": "events.content", "type": "BetaManagedAgentsSearchResultBlock object", "required": false, "description": "A block containing a web search result." }, { "name": "events.is_error", "type": "boolean or null", "required": false, "description": "Whether the tool execution resulted in an error." }, { "name": "events", "type": "BetaManagedAgentsSystemMessageEventParams object", "required": false, "description": "Privileged context for the accompanying turn and all subsequent turns, appended to the session's system context as a `role: \"system\"` turn rather than replacing the top-level system prompt. At most one per request: it must be the final event and immediately follow the `user.message`, `user.tool_result`, or `user.custom_tool_result` it accompanies. Only supported on models that accept mid-conversation system messages." }, { "name": "events.type", "type": "\"system.message\"", "required": true, "description": "" }, { "name": "events.content", "type": "array of BetaManagedAgentsSystemContentBlock", "required": true, "description": "System content blocks to append. Text-only." }, { "name": "events.content.type", "type": "\"text\"", "required": true, "description": "" }, { "name": "events.content.text", "type": "string", "required": true, "description": "The text content.", "constraints": { "minLength": "1" } } ], "status": [ "DOCUMENTED", "BETA" ], "sources": [ { "url": "https://platform.claude.com/docs/en/api/beta/sessions/events/send", "retrieved_at": "2026-09-18" }, { "url": "https://platform.claude.com/docs/en/managed-agents/events-and-streaming", "retrieved_at": "2026-09-18" } ], "beta_header": "managed-agents-2026-04-01", "_fragment": "generated/fragments/objects/anthropic-platform-objects.json" }, { "provider": "anthropic", "api_family": "managed-agents", "name": "Environment", "official_type_name": "BetaEnvironment", "description": "Unified Environment resource for both cloud and self-hosted environments.", "fields": [ { "name": "type", "type": "\"environment\"", "required": true, "description": "The type of object (always 'environment')", "constraints": { "default": "environment" } }, { "name": "id", "type": "string", "required": true, "description": "Environment identifier (e.g., 'env_...')" }, { "name": "archived_at", "type": "string or null", "required": true, "description": "RFC 3339 timestamp when environment was archived, or null if not archived" }, { "name": "config", "type": "BetaCloudConfig or BetaSelfHostedConfig", "required": true, "description": "Environment configuration (either Anthropic Cloud or self-hosted)" }, { "name": "config", "type": "BetaCloudConfig object", "required": false, "description": "`cloud` environment configuration." }, { "name": "config.type", "type": "\"cloud\"", "required": true, "description": "Environment type" }, { "name": "config.networking", "type": "BetaUnrestrictedNetwork or BetaLimitedNetwork", "required": true, "description": "Network configuration policy." }, { "name": "config.networking", "type": "BetaUnrestrictedNetwork object", "required": false, "description": "Unrestricted network access." }, { "name": "config.networking.type", "type": "\"unrestricted\"", "required": true, "description": "Network policy type" }, { "name": "config.networking", "type": "BetaLimitedNetwork object", "required": false, "description": "Limited network access." }, { "name": "config.networking.type", "type": "\"limited\"", "required": true, "description": "Network policy type" }, { "name": "config.networking.allow_mcp_servers", "type": "boolean", "required": true, "description": "Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array." }, { "name": "config.networking.allow_package_managers", "type": "boolean", "required": true, "description": "Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array." }, { "name": "config.networking.allowed_hosts", "type": "array of string", "required": true, "description": "Specifies domains the container can reach." }, { "name": "config.packages", "type": "BetaPackages", "required": true, "description": "Package manager configuration." }, { "name": "config.packages.type", "type": "\"packages\"", "required": false, "description": "Package configuration type", "constraints": { "default": "packages" } }, { "name": "config.packages.apt", "type": "array of string", "required": true, "description": "Ubuntu/Debian packages to install" }, { "name": "config.packages.cargo", "type": "array of string", "required": true, "description": "Rust packages to install" }, { "name": "config.packages.gem", "type": "array of string", "required": true, "description": "Ruby packages to install" }, { "name": "config.packages.go", "type": "array of string", "required": true, "description": "Go packages to install" }, { "name": "config.packages.npm", "type": "array of string", "required": true, "description": "Node.js packages to install" }, { "name": "config.packages.pip", "type": "array of string", "required": true, "description": "Python packages to install" }, { "name": "config", "type": "BetaSelfHostedConfig object", "required": false, "description": "Configuration for self-hosted environments." }, { "name": "config.type", "type": "\"self_hosted\"", "required": true, "description": "Environment type" }, { "name": "created_at", "type": "string", "required": true, "description": "RFC 3339 timestamp when environment was created" }, { "name": "description", "type": "string or null", "required": true, "description": "User-provided description for the environment; null when unset" }, { "name": "metadata", "type": "map[string]", "required": true, "description": "User-provided metadata key-value pairs" }, { "name": "name", "type": "string", "required": true, "description": "Human-readable name for the environment" }, { "name": "updated_at", "type": "string", "required": true, "description": "RFC 3339 timestamp when environment was last updated" }, { "name": "scope", "type": "\"organization\" or \"account\"", "required": false, "description": "The visibility scope for this environment. 'organization' means visible to all accounts. 'account' means visible only to the owning account.", "enum": [ "organization", "account" ] } ], "status": [ "DOCUMENTED", "BETA" ], "sources": [ { "url": "https://platform.claude.com/docs/en/api/beta/environments/create", "retrieved_at": "2026-09-18" }, { "url": "https://platform.claude.com/docs/en/managed-agents/environments", "retrieved_at": "2026-09-18" }, { "url": "https://platform.claude.com/docs/en/managed-agents/self-hosted-sandboxes", "retrieved_at": "2026-09-18" } ], "beta_header": "managed-agents-2026-04-01", "_fragment": "generated/fragments/objects/anthropic-platform-objects.json" }, { "provider": "anthropic", "api_family": "managed-agents", "name": "EnvironmentCreateParams (request body: cloud | self_hosted config)", "official_type_name": "BetaEnvironmentCreateParams", "description": "Create a new environment with the specified configuration.", "fields": [ { "name": "name", "type": "string", "required": true, "description": "Human-readable name for the environment", "constraints": { "maxLength": "256", "minLength": "1" } }, { "name": "config", "type": "BetaCloudConfigParams or BetaSelfHostedConfigParams or null", "required": false, "description": "Environment configuration" }, { "name": "config", "type": "BetaCloudConfigParams object", "required": false, "description": "Request params for `cloud` environment configuration. Fields default to null; on update, omitted fields preserve the existing value." }, { "name": "config.type", "type": "\"cloud\"", "required": true, "description": "Environment type" }, { "name": "config.networking", "type": "BetaUnrestrictedNetwork or BetaLimitedNetworkParams or null", "required": false, "description": "Network configuration policy. Omit on update to preserve the existing value." }, { "name": "config.networking", "type": "BetaUnrestrictedNetwork object", "required": false, "description": "Unrestricted network access." }, { "name": "config.networking.type", "type": "\"unrestricted\"", "required": true, "description": "Network policy type" }, { "name": "config.networking", "type": "BetaLimitedNetworkParams object", "required": false, "description": "Limited network request params. Fields default to null; on update, omitted fields preserve the existing value." }, { "name": "config.networking.type", "type": "\"limited\"", "required": true, "description": "Network policy type" }, { "name": "config.networking.allow_mcp_servers", "type": "boolean or null", "required": false, "description": "Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. Defaults to `false`." }, { "name": "config.networking.allow_package_managers", "type": "boolean or null", "required": false, "description": "Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. Defaults to `false` on creation. Must be `true` when `packages` are specified." }, { "name": "config.networking.allowed_hosts", "type": "array of string or null", "required": false, "description": "Specifies domains the container can reach." }, { "name": "config.packages", "type": "BetaPackagesParams or null", "required": false, "description": "Specify packages (and optionally their versions) available in this environment. When versioning, use the version semantics relevant for the package manager, e.g. for `pip` use `package==1.0.0`. You are responsible for validating the package and version exist. Unversioned installs the latest. Under `limited` networking, requires `networking.allow_package_managers` to be `true`." }, { "name": "config.packages.type", "type": "\"packages\"", "required": false, "description": "Package configuration type", "constraints": { "default": "packages" } }, { "name": "config.packages.apt", "type": "array of string or null", "required": false, "description": "Ubuntu/Debian packages to install" }, { "name": "config.packages.cargo", "type": "array of string or null", "required": false, "description": "Rust packages to install" }, { "name": "config.packages.gem", "type": "array of string or null", "required": false, "description": "Ruby packages to install" }, { "name": "config.packages.go", "type": "array of string or null", "required": false, "description": "Go packages to install" }, { "name": "config.packages.npm", "type": "array of string or null", "required": false, "description": "Node.js packages to install" }, { "name": "config.packages.pip", "type": "array of string or null", "required": false, "description": "Python packages to install" }, { "name": "config", "type": "BetaSelfHostedConfigParams object", "required": false, "description": "Request params for `self_hosted` environment configuration." }, { "name": "config.type", "type": "\"self_hosted\"", "required": true, "description": "Environment type" }, { "name": "description", "type": "string or null", "required": false, "description": "Optional description of the environment", "constraints": { "maxLength": "1024" } }, { "name": "metadata", "type": "map[string]", "required": false, "description": "User-provided metadata key-value pairs" }, { "name": "scope", "type": "\"organization\" or \"account\" or null", "required": false, "description": "The visibility scope for this environment. 'organization' makes the environment visible to all accounts. 'account' restricts visibility to the owning account only. API organizations support only 'organization'; 'account' is rejected. If not specified, defaults based on organization type.", "enum": [ "organization", "account" ] } ], "status": [ "DOCUMENTED", "BETA" ], "sources": [ { "url": "https://platform.claude.com/docs/en/api/beta/environments/create", "retrieved_at": "2026-09-18" }, { "url": "https://platform.claude.com/docs/en/managed-agents/environments", "retrieved_at": "2026-09-18" }, { "url": "https://platform.claude.com/docs/en/managed-agents/self-hosted-sandboxes", "retrieved_at": "2026-09-18" } ], "beta_header": "managed-agents-2026-04-01", "_fragment": "generated/fragments/objects/anthropic-platform-objects.json" }, { "provider": "anthropic", "api_family": "managed-agents", "name": "WorkItem (self-hosted work queue)", "official_type_name": "BetaSelfHostedWork", "description": "Work resource representing a unit of work in a self-hosted environment. Work items are queued when sessions are created or when long-dormant sessions receive new messages. The environment worker polls for work to execute in a self-hosted sandbox.", "fields": [ { "name": "type", "type": "\"work\"", "required": true, "description": "The type of object (always 'work')", "constraints": { "default": "work" } }, { "name": "id", "type": "string", "required": true, "description": "Work identifier (e.g., 'work_...')" }, { "name": "acknowledged_at", "type": "string or null", "required": true, "description": "RFC 3339 timestamp when the work item was acknowledged and assigned to a self-hosted sandbox" }, { "name": "created_at", "type": "string", "required": true, "description": "RFC 3339 timestamp when work was created" }, { "name": "data", "type": "BetaSessionWorkData", "required": true, "description": "The actual work to be performed" }, { "name": "data.type", "type": "\"session\"", "required": true, "description": "Type of work data" }, { "name": "data.id", "type": "string", "required": true, "description": "Session identifier (e.g., 'session_...')" }, { "name": "environment_id", "type": "string", "required": true, "description": "Environment identifier this work belongs to (e.g., `env_...`)" }, { "name": "latest_heartbeat_at", "type": "string or null", "required": true, "description": "RFC 3339 timestamp of the most recent heartbeat" }, { "name": "metadata", "type": "map[string]", "required": true, "description": "User-provided metadata key-value pairs associated with this work item" }, { "name": "secret", "type": "string or null", "required": true, "description": "Credential payload used by the environment worker to execute this work item. May be populated when polling for work; null on all other retrieval paths." }, { "name": "started_at", "type": "string or null", "required": true, "description": "RFC 3339 timestamp when work execution started" }, { "name": "state", "type": "\"queued\" or \"starting\" or \"active\" or 2 more", "required": true, "description": "Current state of the work item", "enum": [ "queued", "starting", "active", "stopping", "stopped" ] }, { "name": "stop_requested_at", "type": "string or null", "required": true, "description": "RFC 3339 timestamp when stop was requested" }, { "name": "stopped_at", "type": "string or null", "required": true, "description": "RFC 3339 timestamp when work execution stopped" } ], "status": [ "DOCUMENTED", "BETA" ], "sources": [ { "url": "https://platform.claude.com/docs/en/api/beta/environments/work/poll", "retrieved_at": "2026-09-18" }, { "url": "https://platform.claude.com/docs/en/managed-agents/self-hosted-sandboxes", "retrieved_at": "2026-09-18" } ], "beta_header": "managed-agents-2026-04-01", "_fragment": "generated/fragments/objects/anthropic-platform-objects.json" }, { "provider": "anthropic", "api_family": "managed-agents", "name": "WorkQueueStats", "official_type_name": "BetaSelfHostedWorkQueueStats", "description": "Statistics about the work queue for an environment. Uses Redis Stream consumer group metrics for O(1) queries.", "fields": [ { "name": "type", "type": "\"work_queue_stats\"", "required": true, "description": "The type of object", "constraints": { "default": "work_queue_stats" } }, { "name": "depth", "type": "number", "required": true, "description": "Number of work items waiting to be picked up (lag from consumer group)" }, { "name": "oldest_queued_at", "type": "string or null", "required": true, "description": "RFC 3339 timestamp of oldest item in the work stream (includes both queued and pending items), null if stream empty" }, { "name": "pending", "type": "number", "required": true, "description": "Number of work items being processed (polled but not acknowledged)", "constraints": { "default": "0" } }, { "name": "workers_polling", "type": "number or null", "required": true, "description": "Number of workers that have polled for work in the last 30 seconds. Requires worker_id to be sent with poll requests." } ], "status": [ "DOCUMENTED", "BETA" ], "sources": [ { "url": "https://platform.claude.com/docs/en/api/beta/environments/work/stats", "retrieved_at": "2026-09-18" }, { "url": "https://platform.claude.com/docs/en/managed-agents/self-hosted-sandboxes", "retrieved_at": "2026-09-18" } ], "beta_header": "managed-agents-2026-04-01", "_fragment": "generated/fragments/objects/anthropic-platform-objects.json" }, { "provider": "anthropic", "api_family": "managed-agents", "name": "WorkHeartbeatResponse", "official_type_name": "BetaSelfHostedWorkHeartbeatResponse", "description": "Response after recording a heartbeat for a work item.", "fields": [ { "name": "type", "type": "\"work_heartbeat\"", "required": true, "description": "The type of response", "constraints": { "default": "work_heartbeat" } }, { "name": "last_heartbeat", "type": "string", "required": true, "description": "RFC 3339 timestamp of the actual heartbeat from DB" }, { "name": "lease_extended", "type": "boolean", "required": true, "description": "Whether the heartbeat succeeded in extending the lease" }, { "name": "state", "type": "\"queued\" or \"starting\" or \"active\" or 2 more", "required": true, "description": "Current state of the work item (active/stopping/stopped)", "enum": [ "queued", "starting", "active", "stopping", "stopped" ] }, { "name": "ttl_seconds", "type": "number", "required": true, "description": "Effective TTL applied to the lease" } ], "status": [ "DOCUMENTED", "BETA" ], "sources": [ { "url": "https://platform.claude.com/docs/en/api/beta/environments/work/heartbeat", "retrieved_at": "2026-09-18" } ], "beta_header": "managed-agents-2026-04-01", "_fragment": "generated/fragments/objects/anthropic-platform-objects.json" }, { "provider": "anthropic", "api_family": "managed-agents", "name": "Deployment", "official_type_name": "BetaManagedAgentsDeployment", "description": "A deployment is a configured instance of an agent — it binds the agent to everything needed to run it autonomously: an environment, credentials, initial events, and an optional schedule.", "fields": [ { "name": "type", "type": "\"deployment\"", "required": true, "description": "" }, { "name": "id", "type": "string", "required": true, "description": "Unique identifier for this deployment." }, { "name": "agent", "type": "BetaManagedAgentsAgentReference", "required": true, "description": "A resolved agent reference with a concrete version." }, { "name": "agent.type", "type": "\"agent\"", "required": true, "description": "" }, { "name": "agent.id", "type": "string", "required": true, "description": "" }, { "name": "agent.version", "type": "number", "required": true, "description": "", "constraints": { "format": "int32" } }, { "name": "archived_at", "type": "string or null", "required": true, "description": "A timestamp in RFC 3339 format", "constraints": { "format": "date-time" } }, { "name": "created_at", "type": "string", "required": true, "description": "A timestamp in RFC 3339 format", "constraints": { "format": "date-time" } }, { "name": "description", "type": "string or null", "required": true, "description": "Description of what the deployment does." }, { "name": "environment_id", "type": "string", "required": true, "description": "ID of the `environment` where sessions run." }, { "name": "initial_events", "type": "array of BetaManagedAgentsDeploymentInitialEvent", "required": true, "description": "Events sent to each session immediately after creation." }, { "name": "initial_events", "type": "BetaManagedAgentsDeploymentUserMessageEvent object", "required": false, "description": "A user message sent to the session." }, { "name": "initial_events.type", "type": "\"user.message\"", "required": true, "description": "" }, { "name": "initial_events.content", "type": "array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsRedactedBlock", "required": true, "description": "Array of content blocks for the user message." }, { "name": "initial_events.content", "type": "BetaManagedAgentsTextBlock object", "required": false, "description": "Regular text content." }, { "name": "initial_events.content.type", "type": "\"text\"", "required": true, "description": "" }, { "name": "initial_events.content.text", "type": "string", "required": true, "description": "The text content.", "constraints": { "minLength": "1" } }, { "name": "initial_events.content", "type": "BetaManagedAgentsImageBlock object", "required": false, "description": "Image content specified directly as base64 data or as a reference via a URL." }, { "name": "initial_events.content.type", "type": "\"image\"", "required": true, "description": "" }, { "name": "initial_events.content.source", "type": "BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource", "required": true, "description": "Union type for image source variants." }, { "name": "initial_events.content.source", "type": "BetaManagedAgentsBase64ImageSource object", "required": false, "description": "Base64-encoded image data." }, { "name": "initial_events.content.source", "type": "BetaManagedAgentsURLImageSource object", "required": false, "description": "Image referenced by URL." }, { "name": "initial_events.content.source", "type": "BetaManagedAgentsFileImageSource object", "required": false, "description": "Image referenced by file ID." }, { "name": "initial_events.content", "type": "BetaManagedAgentsDocumentBlock object", "required": false, "description": "Document content, either specified directly as base64 data, as text, or as a reference via a URL." }, { "name": "initial_events.content.type", "type": "\"document\"", "required": true, "description": "" }, { "name": "initial_events.content.source", "type": "BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource", "required": true, "description": "Union type for document source variants." }, { "name": "initial_events.content.source", "type": "BetaManagedAgentsBase64DocumentSource object", "required": false, "description": "Base64-encoded document data." }, { "name": "initial_events.content.source", "type": "BetaManagedAgentsPlainTextDocumentSource object", "required": false, "description": "Plain text document content." }, { "name": "initial_events.content.source", "type": "BetaManagedAgentsURLDocumentSource object", "required": false, "description": "Document referenced by URL." }, { "name": "initial_events.content.source", "type": "BetaManagedAgentsFileDocumentSource object", "required": false, "description": "Document referenced by file ID." }, { "name": "initial_events.content.context", "type": "string or null", "required": false, "description": "Additional context about the document for the model." }, { "name": "initial_events.content.title", "type": "string or null", "required": false, "description": "The title of the document." }, { "name": "initial_events.content", "type": "BetaManagedAgentsRedactedBlock object", "required": false, "description": "Placeholder for content withheld by Anthropic model policy." }, { "name": "initial_events.content.type", "type": "\"redacted\"", "required": true, "description": "" }, { "name": "initial_events", "type": "BetaManagedAgentsDeploymentUserDefineOutcomeEvent object", "required": false, "description": "An outcome the agent should work toward. The agent begins work on receipt." }, { "name": "initial_events.type", "type": "\"user.define_outcome\"", "required": true, "description": "" }, { "name": "initial_events.description", "type": "string", "required": true, "description": "What the agent should produce. This is the task specification." }, { "name": "initial_events.rubric", "type": "BetaManagedAgentsFileRubric or BetaManagedAgentsTextRubric", "required": true, "description": "Rubric for grading the quality of an outcome." }, { "name": "initial_events.rubric", "type": "BetaManagedAgentsFileRubric object", "required": false, "description": "Rubric referenced by a file uploaded via the Files API." }, { "name": "initial_events.rubric.type", "type": "\"file\"", "required": true, "description": "" }, { "name": "initial_events.rubric.file_id", "type": "string", "required": true, "description": "ID of the rubric file." }, { "name": "initial_events.rubric", "type": "BetaManagedAgentsTextRubric object", "required": false, "description": "Rubric content provided inline as text." }, { "name": "initial_events.rubric.type", "type": "\"text\"", "required": true, "description": "" }, { "name": "initial_events.rubric.content", "type": "string", "required": true, "description": "Rubric content. Plain text or markdown — the grader treats it as freeform text." }, { "name": "initial_events.max_iterations", "type": "number or null", "required": false, "description": "Eval→revision cycles before giving up. Default 3, max 20.", "constraints": { "format": "int32" } }, { "name": "initial_events", "type": "BetaManagedAgentsDeploymentSystemMessageEvent object", "required": false, "description": "Privileged context for the accompanying turn and all subsequent turns, appended to the session's system context as a `role: \"system\"` turn rather than replacing the top-level system prompt." }, { "name": "initial_events.type", "type": "\"system.message\"", "required": true, "description": "" }, { "name": "initial_events.content", "type": "array of BetaManagedAgentsSystemContentBlock", "required": true, "description": "System content blocks to append. Text-only." }, { "name": "initial_events.content.type", "type": "\"text\"", "required": true, "description": "" }, { "name": "initial_events.content.text", "type": "string", "required": true, "description": "The text content.", "constraints": { "minLength": "1" } }, { "name": "metadata", "type": "map[string]", "required": true, "description": "Arbitrary key-value metadata. Maximum 16 pairs." }, { "name": "name", "type": "string", "required": true, "description": "Human-readable name." }, { "name": "paused_reason", "type": "BetaManagedAgentsDeploymentPausedReason or null", "required": true, "description": "Why a deployment is paused. Non-null exactly when `status` is `paused`." }, { "name": "paused_reason", "type": "BetaManagedAgentsManualDeploymentPausedReason object", "required": false, "description": "The caller invoked the pause endpoint on the deployment." }, { "name": "paused_reason.type", "type": "\"manual\"", "required": true, "description": "" }, { "name": "paused_reason", "type": "BetaManagedAgentsErrorDeploymentPausedReason object", "required": false, "description": "A scheduled fire recorded a failed run whose error auto-pauses the deployment." }, { "name": "paused_reason.type", "type": "\"error\"", "required": true, "description": "" }, { "name": "paused_reason.error", "type": "BetaManagedAgentsDeploymentPausedReasonError", "required": true, "description": "The error that triggered an auto-pause. Matches the failed run's `error.type`." }, { "name": "paused_reason.error", "type": "BetaManagedAgentsEnvironmentArchivedDeploymentPausedReasonError object", "required": false, "description": "The deployment's environment was archived." }, { "name": "paused_reason.error.type", "type": "\"environment_archived_error\"", "required": true, "description": "" }, { "name": "paused_reason.error", "type": "BetaManagedAgentsAgentArchivedDeploymentPausedReasonError object", "required": false, "description": "The deployment's agent was archived." }, { "name": "paused_reason.error.type", "type": "\"agent_archived_error\"", "required": true, "description": "" }, { "name": "paused_reason.error", "type": "BetaManagedAgentsEnvironmentNotFoundDeploymentPausedReasonError object", "required": false, "description": "The deployment's environment no longer exists." }, { "name": "paused_reason.error.type", "type": "\"environment_not_found_error\"", "required": true, "description": "" }, { "name": "paused_reason.error", "type": "BetaManagedAgentsVaultNotFoundDeploymentPausedReasonError object", "required": false, "description": "A vault referenced by the deployment no longer exists." }, { "name": "paused_reason.error.type", "type": "\"vault_not_found_error\"", "required": true, "description": "" }, { "name": "paused_reason.error", "type": "BetaManagedAgentsFileNotFoundDeploymentPausedReasonError object", "required": false, "description": "A file resource referenced by the deployment no longer exists." }, { "name": "paused_reason.error.type", "type": "\"file_not_found_error\"", "required": true, "description": "" }, { "name": "paused_reason.error", "type": "BetaManagedAgentsSessionResourceNotFoundDeploymentPausedReasonError object", "required": false, "description": "A referenced resource no longer exists and its kind was not reported." }, { "name": "paused_reason.error.type", "type": "\"session_resource_not_found_error\"", "required": true, "description": "" }, { "name": "paused_reason.error", "type": "BetaManagedAgentsWorkspaceArchivedDeploymentPausedReasonError object", "required": false, "description": "The deployment's workspace was archived." }, { "name": "paused_reason.error.type", "type": "\"workspace_archived_error\"", "required": true, "description": "" }, { "name": "paused_reason.error", "type": "BetaManagedAgentsOrganizationDisabledDeploymentPausedReasonError object", "required": false, "description": "The deployment's organization is disabled." }, { "name": "paused_reason.error.type", "type": "\"organization_disabled_error\"", "required": true, "description": "" }, { "name": "paused_reason.error", "type": "BetaManagedAgentsMemoryStoreArchivedDeploymentPausedReasonError object", "required": false, "description": "A memory store referenced by the deployment is archived." }, { "name": "paused_reason.error.type", "type": "\"memory_store_archived_error\"", "required": true, "description": "" }, { "name": "paused_reason.error", "type": "BetaManagedAgentsSkillNotFoundDeploymentPausedReasonError object", "required": false, "description": "A skill referenced by the deployment's agent no longer exists." }, { "name": "paused_reason.error.type", "type": "\"skill_not_found_error\"", "required": true, "description": "" }, { "name": "paused_reason.error", "type": "BetaManagedAgentsVaultArchivedDeploymentPausedReasonError object", "required": false, "description": "A vault referenced by the deployment is archived." }, { "name": "paused_reason.error.type", "type": "\"vault_archived_error\"", "required": true, "description": "" }, { "name": "paused_reason.error", "type": "BetaManagedAgentsUnknownDeploymentPausedReasonError object", "required": false, "description": "An unrecognized error auto-paused the deployment. A fallback variant; matches a run whose `error.type` is `unknown_error`." }, { "name": "paused_reason.error.type", "type": "\"unknown_error\"", "required": true, "description": "" }, { "name": "paused_reason.error", "type": "BetaManagedAgentsSelfHostedResourcesUnsupportedDeploymentPausedReasonError object", "required": false, "description": "The deployment configures resources, but its environment is self-hosted and cannot mount them." }, { "name": "paused_reason.error.type", "type": "\"self_hosted_resources_unsupported_error\"", "required": true, "description": "" }, { "name": "paused_reason.error", "type": "BetaManagedAgentsMCPEgressBlockedDeploymentPausedReasonError object", "required": false, "description": "An MCP server host used by the deployment's agent is blocked by the environment's network policy." }, { "name": "paused_reason.error.type", "type": "\"mcp_egress_blocked_error\"", "required": true, "description": "" }, { "name": "resources", "type": "array of BetaManagedAgentsSessionResourceConfig", "required": true, "description": "Resources attached to sessions created from this deployment. Echoes the input minus write-only credentials." }, { "name": "resources", "type": "BetaManagedAgentsGitHubRepositoryResourceConfig object", "required": false, "description": "A GitHub repository mounted into each session's container. The authorization token is write-only and never returned." }, { "name": "resources.type", "type": "\"github_repository\"", "required": true, "description": "" }, { "name": "resources.url", "type": "string", "required": true, "description": "Github URL of the repository" }, { "name": "resources.checkout", "type": "BetaManagedAgentsBranchCheckout or BetaManagedAgentsCommitCheckout or null", "required": false, "description": "Branch or commit to check out. Defaults to the repository's default branch." }, { "name": "resources.checkout", "type": "BetaManagedAgentsBranchCheckout object", "required": false, "description": "" }, { "name": "resources.checkout.type", "type": "\"branch\"", "required": true, "description": "" }, { "name": "resources.checkout.name", "type": "string", "required": true, "description": "Branch name to check out.", "constraints": { "minLength": "1", "maxLength": "255" } }, { "name": "resources.checkout", "type": "BetaManagedAgentsCommitCheckout object", "required": false, "description": "" }, { "name": "resources.checkout.type", "type": "\"commit\"", "required": true, "description": "" }, { "name": "resources.checkout.sha", "type": "string", "required": true, "description": "Full commit SHA to check out.", "constraints": { "minLength": "7", "maxLength": "64" } }, { "name": "resources.mount_path", "type": "string or null", "required": false, "description": "Mount path in the container. Defaults to `/workspace/`." }, { "name": "resources", "type": "BetaManagedAgentsFileResourceConfig object", "required": false, "description": "A file mounted into each session's container." }, { "name": "resources.type", "type": "\"file\"", "required": true, "description": "" }, { "name": "resources.file_id", "type": "string", "required": true, "description": "ID of a previously uploaded file." }, { "name": "resources.mount_path", "type": "string or null", "required": false, "description": "Mount path in the container. Defaults to `/mnt/session/uploads/`." }, { "name": "resources", "type": "BetaManagedAgentsMemoryStoreResourceConfig object", "required": false, "description": "A memory store attached to each session created from this deployment." }, { "name": "resources.type", "type": "\"memory_store\"", "required": true, "description": "" }, { "name": "resources.memory_store_id", "type": "string", "required": true, "description": "The memory store ID (memstore_...). Must belong to the caller's organization and workspace." }, { "name": "resources.access", "type": "\"read_write\" or \"read_only\" or null", "required": false, "description": "Access mode for an attached memory store.", "enum": [ "read_write", "read_only" ] }, { "name": "resources.instructions", "type": "string or null", "required": false, "description": "Per-attachment guidance for the agent on how to use this store. Rendered into the memory section of the system prompt. Max 4096 chars." }, { "name": "schedule", "type": "BetaManagedAgentsSchedule or null", "required": true, "description": "5-field POSIX cron schedule with computed runtime timestamps." }, { "name": "schedule.type", "type": "\"cron\"", "required": true, "description": "" }, { "name": "schedule.expression", "type": "string", "required": true, "description": "5-field POSIX cron expression: minute hour day-of-month month day-of-week (e.g., \"0 9 * * 1-5\" for weekdays at 9am). Day-of-week is 0-7 where 0 and 7 both mean Sunday. Extended cron syntax - seconds or year fields, and the special characters L, W, #, and ? - is not supported, nor are predefined shortcuts (@daily).", "constraints": { "minLength": "1", "maxLength": "256" } }, { "name": "schedule.timezone", "type": "string", "required": true, "description": "IANA timezone identifier (e.g., \"America/Los_Angeles\", \"UTC\").", "constraints": { "minLength": "1" } }, { "name": "schedule.last_run_at", "type": "string or null", "required": false, "description": "A timestamp in RFC 3339 format", "constraints": { "format": "date-time" } }, { "name": "schedule.upcoming_runs_at", "type": "array of string", "required": false, "description": "Up to 5 timestamps of upcoming cron occurrences. Non-empty for active and paused deployments (reflects what the schedule would do if unpaused); empty once the deployment is archived (`archived_at` set). Each fire is offset by a small per-schedule jitter, so a run will actually start at or shortly after its listed time." }, { "name": "status", "type": "BetaManagedAgentsDeploymentStatus", "required": true, "description": "Lifecycle status of a deployment.", "enum": [ "active", "paused" ] }, { "name": "updated_at", "type": "string", "required": true, "description": "A timestamp in RFC 3339 format", "constraints": { "format": "date-time" } }, { "name": "vault_ids", "type": "array of string", "required": true, "description": "Vault IDs supplying stored credentials for sessions created from this deployment." }, { "name": "budget", "type": "BetaManagedAgentsBudgetLimit or null", "required": false, "description": "A hard spend ceiling. The session stops issuing new model requests once the tracked list cost reaches `max_list_cost`." }, { "name": "budget.type", "type": "\"limit\"", "required": true, "description": "" }, { "name": "budget.max_list_cost", "type": "BetaMonetaryAmount", "required": true, "description": "A monetary amount in a specific currency." }, { "name": "budget.max_list_cost.amount", "type": "string", "required": true, "description": "Amount in minor units of the currency, as an integer decimal string with no leading zeros: \"2500\" is $25.00 and \"50\" is fifty cents. A string rather than a number so no float rounding is ever applied." }, { "name": "budget.max_list_cost.currency", "type": "BetaCurrency", "required": true, "description": "Uppercase ISO-4217 currency code. `USD` is the only currency currently supported; the accepted set is closed and grows only when a new currency is priced." } ], "status": [ "DOCUMENTED", "BETA" ], "sources": [ { "url": "https://platform.claude.com/docs/en/api/beta/deployments/create", "retrieved_at": "2026-09-18" }, { "url": "https://platform.claude.com/docs/en/managed-agents/scheduled-deployments", "retrieved_at": "2026-09-18" } ], "beta_header": "managed-agents-2026-04-01", "_fragment": "generated/fragments/objects/anthropic-platform-objects.json" }, { "provider": "anthropic", "api_family": "managed-agents", "name": "DeploymentCreateParams (request body)", "official_type_name": "BetaManagedAgentsDeploymentCreateParams", "description": "Create Deployment", "fields": [ { "name": "agent", "type": "string or BetaManagedAgentsAgentParams", "required": true, "description": "Agent to deploy. Accepts the `agent` ID string, which pins the latest version, or an `agent` object with both id and version specified. The agent must exist and not be archived." }, { "name": "agent", "type": "string", "required": false, "description": "" }, { "name": "agent", "type": "BetaManagedAgentsAgentParams object", "required": false, "description": "Specification for an Agent. Provide a specific `version` or use the short-form `agent=\"agent_id\"` for the most recent version" }, { "name": "agent.type", "type": "\"agent\"", "required": true, "description": "" }, { "name": "agent.id", "type": "string", "required": true, "description": "The `agent` ID.", "constraints": { "minLength": "1", "maxLength": "128" } }, { "name": "agent.version", "type": "number", "required": false, "description": "The specific `agent` version to use. Omit to use the latest version. Must be at least 1 if specified.", "constraints": { "format": "int32" } }, { "name": "environment_id", "type": "string", "required": true, "description": "ID of the `environment` defining the container configuration for sessions created from this deployment.", "constraints": { "minLength": "1", "maxLength": "128" } }, { "name": "initial_events", "type": "array of BetaManagedAgentsDeploymentInitialEventParams", "required": true, "description": "Events to send to each session immediately after creation. At least 1, maximum 50." }, { "name": "initial_events", "type": "BetaManagedAgentsUserMessageEventParams object", "required": false, "description": "Parameters for sending a user message to the session." }, { "name": "initial_events.type", "type": "\"user.message\"", "required": true, "description": "" }, { "name": "initial_events.content", "type": "array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsRedactedBlock", "required": true, "description": "Array of content blocks for the user message." }, { "name": "initial_events.content", "type": "BetaManagedAgentsTextBlock object", "required": false, "description": "Regular text content." }, { "name": "initial_events.content.type", "type": "\"text\"", "required": true, "description": "" }, { "name": "initial_events.content.text", "type": "string", "required": true, "description": "The text content.", "constraints": { "minLength": "1" } }, { "name": "initial_events.content", "type": "BetaManagedAgentsImageBlock object", "required": false, "description": "Image content specified directly as base64 data or as a reference via a URL." }, { "name": "initial_events.content.type", "type": "\"image\"", "required": true, "description": "" }, { "name": "initial_events.content.source", "type": "BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource", "required": true, "description": "Union type for image source variants." }, { "name": "initial_events.content.source", "type": "BetaManagedAgentsBase64ImageSource object", "required": false, "description": "Base64-encoded image data." }, { "name": "initial_events.content.source", "type": "BetaManagedAgentsURLImageSource object", "required": false, "description": "Image referenced by URL." }, { "name": "initial_events.content.source", "type": "BetaManagedAgentsFileImageSource object", "required": false, "description": "Image referenced by file ID." }, { "name": "initial_events.content", "type": "BetaManagedAgentsDocumentBlock object", "required": false, "description": "Document content, either specified directly as base64 data, as text, or as a reference via a URL." }, { "name": "initial_events.content.type", "type": "\"document\"", "required": true, "description": "" }, { "name": "initial_events.content.source", "type": "BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource", "required": true, "description": "Union type for document source variants." }, { "name": "initial_events.content.source", "type": "BetaManagedAgentsBase64DocumentSource object", "required": false, "description": "Base64-encoded document data." }, { "name": "initial_events.content.source", "type": "BetaManagedAgentsPlainTextDocumentSource object", "required": false, "description": "Plain text document content." }, { "name": "initial_events.content.source", "type": "BetaManagedAgentsURLDocumentSource object", "required": false, "description": "Document referenced by URL." }, { "name": "initial_events.content.source", "type": "BetaManagedAgentsFileDocumentSource object", "required": false, "description": "Document referenced by file ID." }, { "name": "initial_events.content.context", "type": "string or null", "required": false, "description": "Additional context about the document for the model." }, { "name": "initial_events.content.title", "type": "string or null", "required": false, "description": "The title of the document." }, { "name": "initial_events.content", "type": "BetaManagedAgentsRedactedBlock object", "required": false, "description": "Placeholder for content withheld by Anthropic model policy." }, { "name": "initial_events.content.type", "type": "\"redacted\"", "required": true, "description": "" }, { "name": "initial_events", "type": "BetaManagedAgentsUserDefineOutcomeEventParams object", "required": false, "description": "Parameters for defining an outcome the agent should work toward. The agent begins work on receipt." }, { "name": "initial_events.type", "type": "\"user.define_outcome\"", "required": true, "description": "" }, { "name": "initial_events.description", "type": "string", "required": true, "description": "What the agent should produce. This is the task specification." }, { "name": "initial_events.rubric", "type": "BetaManagedAgentsFileRubricParams or BetaManagedAgentsTextRubricParams", "required": true, "description": "Rubric for grading the quality of an outcome." }, { "name": "initial_events.rubric", "type": "BetaManagedAgentsFileRubricParams object", "required": false, "description": "Rubric referenced by a file uploaded via the Files API." }, { "name": "initial_events.rubric.type", "type": "\"file\"", "required": true, "description": "" }, { "name": "initial_events.rubric.file_id", "type": "string", "required": true, "description": "ID of the rubric file." }, { "name": "initial_events.rubric", "type": "BetaManagedAgentsTextRubricParams object", "required": false, "description": "Rubric content provided inline as text." }, { "name": "initial_events.rubric.type", "type": "\"text\"", "required": true, "description": "" }, { "name": "initial_events.rubric.content", "type": "string", "required": true, "description": "Rubric content. Plain text or markdown — the grader treats it as freeform text. Maximum 262144 characters.", "constraints": { "maxLength": "262144" } }, { "name": "initial_events.max_iterations", "type": "number or null", "required": false, "description": "Eval→revision cycles before giving up. Default 3, max 20.", "constraints": { "format": "int32" } }, { "name": "initial_events", "type": "BetaManagedAgentsSystemMessageEventParams object", "required": false, "description": "Privileged context for the accompanying turn and all subsequent turns, appended to the session's system context as a `role: \"system\"` turn rather than replacing the top-level system prompt. At most one per request: it must be the final event and immediately follow the `user.message`, `user.tool_result`, or `user.custom_tool_result` it accompanies. Only supported on models that accept mid-conversation system messages." }, { "name": "initial_events.type", "type": "\"system.message\"", "required": true, "description": "" }, { "name": "initial_events.content", "type": "array of BetaManagedAgentsSystemContentBlock", "required": true, "description": "System content blocks to append. Text-only." }, { "name": "initial_events.content.type", "type": "\"text\"", "required": true, "description": "" }, { "name": "initial_events.content.text", "type": "string", "required": true, "description": "The text content.", "constraints": { "minLength": "1" } }, { "name": "name", "type": "string", "required": true, "description": "Human-readable name for the deployment.", "constraints": { "minLength": "1", "maxLength": "256" } }, { "name": "budget", "type": "BetaManagedAgentsBudgetLimit or null", "required": false, "description": "A hard spend ceiling. The session stops issuing new model requests once the tracked list cost reaches `max_list_cost`." }, { "name": "budget.type", "type": "\"limit\"", "required": true, "description": "" }, { "name": "budget.max_list_cost", "type": "BetaMonetaryAmount", "required": true, "description": "A monetary amount in a specific currency." }, { "name": "budget.max_list_cost.amount", "type": "string", "required": true, "description": "Amount in minor units of the currency, as an integer decimal string with no leading zeros: \"2500\" is $25.00 and \"50\" is fifty cents. A string rather than a number so no float rounding is ever applied." }, { "name": "budget.max_list_cost.currency", "type": "BetaCurrency", "required": true, "description": "Uppercase ISO-4217 currency code. `USD` is the only currency currently supported; the accepted set is closed and grows only when a new currency is priced." }, { "name": "description", "type": "string or null", "required": false, "description": "Description of what the deployment does.", "constraints": { "maxLength": "2048" } }, { "name": "metadata", "type": "map[string]", "required": false, "description": "Arbitrary key-value metadata. Maximum 16 pairs, keys up to 64 chars, values up to 512 chars." }, { "name": "resources", "type": "array of BetaManagedAgentsGitHubRepositoryResourceParams or BetaManagedAgentsFileResourceParams or BetaManagedAgentsMemoryStoreResourceParam", "required": false, "description": "Resources (e.g. repositories, files) to mount into each session's container. Maximum 500." }, { "name": "resources", "type": "BetaManagedAgentsGitHubRepositoryResourceParams object", "required": false, "description": "Mount a GitHub repository into the session's container." }, { "name": "resources.type", "type": "\"github_repository\"", "required": true, "description": "" }, { "name": "resources.url", "type": "string", "required": true, "description": "Github URL of the repository", "constraints": { "minLength": "1", "maxLength": "2048" } }, { "name": "resources.authorization_token", "type": "string", "required": false, "description": "GitHub authorization token used to clone the repository. Required for private repositories; optional for public ones.", "constraints": { "minLength": "1", "maxLength": "4096" } }, { "name": "resources.checkout", "type": "BetaManagedAgentsBranchCheckout or BetaManagedAgentsCommitCheckout or null", "required": false, "description": "Branch or commit to check out. Defaults to the repository's default branch." }, { "name": "resources.checkout", "type": "BetaManagedAgentsBranchCheckout object", "required": false, "description": "" }, { "name": "resources.checkout.type", "type": "\"branch\"", "required": true, "description": "" }, { "name": "resources.checkout.name", "type": "string", "required": true, "description": "Branch name to check out.", "constraints": { "minLength": "1", "maxLength": "255" } }, { "name": "resources.checkout", "type": "BetaManagedAgentsCommitCheckout object", "required": false, "description": "" }, { "name": "resources.checkout.type", "type": "\"commit\"", "required": true, "description": "" }, { "name": "resources.checkout.sha", "type": "string", "required": true, "description": "Full commit SHA to check out.", "constraints": { "minLength": "7", "maxLength": "64" } }, { "name": "resources.mount_path", "type": "string or null", "required": false, "description": "Mount path in the container. Defaults to `/workspace/`.", "constraints": { "minLength": "1", "maxLength": "4096" } }, { "name": "resources", "type": "BetaManagedAgentsFileResourceParams object", "required": false, "description": "Mount a file uploaded via the Files API into the session." }, { "name": "resources.type", "type": "\"file\"", "required": true, "description": "" }, { "name": "resources.file_id", "type": "string", "required": true, "description": "ID of a previously uploaded file.", "constraints": { "minLength": "1", "maxLength": "128" } }, { "name": "resources.mount_path", "type": "string or null", "required": false, "description": "Mount path in the container. Defaults to `/mnt/session/uploads/`.", "constraints": { "minLength": "1", "maxLength": "4096" } }, { "name": "resources", "type": "BetaManagedAgentsMemoryStoreResourceParam object", "required": false, "description": "Parameters for attaching a memory store to an agent session." }, { "name": "resources.type", "type": "\"memory_store\"", "required": true, "description": "" }, { "name": "resources.memory_store_id", "type": "string", "required": true, "description": "The memory store ID (memstore_...). Must belong to the caller's organization and workspace." }, { "name": "resources.access", "type": "\"read_write\" or \"read_only\" or null", "required": false, "description": "Access mode for an attached memory store.", "enum": [ "read_write", "read_only" ] }, { "name": "resources.instructions", "type": "string or null", "required": false, "description": "Per-attachment guidance for the agent on how to use this store. Rendered into the memory section of the system prompt. Max 4096 chars.", "constraints": { "maxLength": "4096" } }, { "name": "schedule", "type": "BetaManagedAgentsScheduleParams or null", "required": false, "description": "5-field POSIX cron schedule. Literal wall-clock matching in the configured timezone." }, { "name": "schedule.type", "type": "\"cron\"", "required": true, "description": "" }, { "name": "schedule.expression", "type": "string", "required": true, "description": "5-field POSIX cron expression: minute hour day-of-month month day-of-week (e.g., \"0 9 * * 1-5\" for weekdays at 9am). Day-of-week is 0-7 where 0 and 7 both mean Sunday. Extended cron syntax - seconds or year fields, and the special characters L, W, #, and ? - is not supported, nor are predefined shortcuts (@daily).", "constraints": { "minLength": "1", "maxLength": "256" } }, { "name": "schedule.timezone", "type": "string", "required": true, "description": "Required. IANA timezone identifier (e.g., \"America/Los_Angeles\", \"UTC\"). Validated against the IANA timezone database.", "constraints": { "minLength": "1" } }, { "name": "vault_ids", "type": "array of string", "required": false, "description": "Vault IDs for stored credentials the agent can use during sessions created from this deployment. Maximum 50." } ], "status": [ "DOCUMENTED", "BETA" ], "sources": [ { "url": "https://platform.claude.com/docs/en/api/beta/deployments/create", "retrieved_at": "2026-09-18" }, { "url": "https://platform.claude.com/docs/en/managed-agents/scheduled-deployments", "retrieved_at": "2026-09-18" }, { "url": "https://platform.claude.com/docs/en/managed-agents/budgets", "retrieved_at": "2026-09-18" } ], "beta_header": "managed-agents-2026-04-01", "_fragment": "generated/fragments/objects/anthropic-platform-objects.json" }, { "provider": "anthropic", "api_family": "managed-agents", "name": "DeploymentRun", "official_type_name": "BetaManagedAgentsDeploymentRun", "description": "A persistent, append-only record of a single deployment execution. Records session creation success or failure — no session lifecycle tracking.", "fields": [ { "name": "type", "type": "\"deployment_run\"", "required": true, "description": "" }, { "name": "id", "type": "string", "required": true, "description": "Unique identifier for this run (`drun_...`)." }, { "name": "agent", "type": "BetaManagedAgentsAgentReference", "required": true, "description": "A resolved agent reference with a concrete version." }, { "name": "agent.type", "type": "\"agent\"", "required": true, "description": "" }, { "name": "agent.id", "type": "string", "required": true, "description": "" }, { "name": "agent.version", "type": "number", "required": true, "description": "", "constraints": { "format": "int32" } }, { "name": "created_at", "type": "string", "required": true, "description": "A timestamp in RFC 3339 format", "constraints": { "format": "date-time" } }, { "name": "deployment_id", "type": "string", "required": true, "description": "ID of the deployment that produced this run." }, { "name": "error", "type": "BetaManagedAgentsEnvironmentArchivedRunError or BetaManagedAgentsAgentArchivedRunError or BetaManagedAgentsEnvironmentNotFoundRunError or 13 more or null", "required": true, "description": "Why the run failed to create a session. The type identifies the failure; message is human-readable detail." }, { "name": "error", "type": "BetaManagedAgentsEnvironmentArchivedRunError object", "required": false, "description": "The deployment's environment was archived." }, { "name": "error.type", "type": "\"environment_archived_error\"", "required": true, "description": "" }, { "name": "error.message", "type": "string", "required": true, "description": "Human-readable error description." }, { "name": "error", "type": "BetaManagedAgentsAgentArchivedRunError object", "required": false, "description": "The deployment's agent was archived." }, { "name": "error.type", "type": "\"agent_archived_error\"", "required": true, "description": "" }, { "name": "error.message", "type": "string", "required": true, "description": "Human-readable error description." }, { "name": "error", "type": "BetaManagedAgentsEnvironmentNotFoundRunError object", "required": false, "description": "The deployment's environment no longer exists." }, { "name": "error.type", "type": "\"environment_not_found_error\"", "required": true, "description": "" }, { "name": "error.message", "type": "string", "required": true, "description": "Human-readable error description." }, { "name": "error", "type": "BetaManagedAgentsVaultNotFoundRunError object", "required": false, "description": "A vault referenced by the deployment no longer exists." }, { "name": "error.type", "type": "\"vault_not_found_error\"", "required": true, "description": "" }, { "name": "error.message", "type": "string", "required": true, "description": "Human-readable error description." }, { "name": "error", "type": "BetaManagedAgentsVaultArchivedRunError object", "required": false, "description": "A vault referenced by the deployment is archived." }, { "name": "error.type", "type": "\"vault_archived_error\"", "required": true, "description": "" }, { "name": "error.message", "type": "string", "required": true, "description": "Human-readable error description." }, { "name": "error", "type": "BetaManagedAgentsFileNotFoundRunError object", "required": false, "description": "A file resource referenced by the deployment no longer exists." }, { "name": "error.type", "type": "\"file_not_found_error\"", "required": true, "description": "" }, { "name": "error.message", "type": "string", "required": true, "description": "Human-readable error description." }, { "name": "error", "type": "BetaManagedAgentsMemoryStoreArchivedRunError object", "required": false, "description": "A memory store referenced by the deployment is archived." }, { "name": "error.type", "type": "\"memory_store_archived_error\"", "required": true, "description": "" }, { "name": "error.message", "type": "string", "required": true, "description": "Human-readable error description." }, { "name": "error", "type": "BetaManagedAgentsSkillNotFoundRunError object", "required": false, "description": "A skill referenced by the deployment's agent no longer exists." }, { "name": "error.type", "type": "\"skill_not_found_error\"", "required": true, "description": "" }, { "name": "error.message", "type": "string", "required": true, "description": "Human-readable error description." }, { "name": "error", "type": "BetaManagedAgentsSessionResourceNotFoundRunError object", "required": false, "description": "A referenced resource no longer exists and its kind was not reported." }, { "name": "error.type", "type": "\"session_resource_not_found_error\"", "required": true, "description": "" }, { "name": "error.message", "type": "string", "required": true, "description": "Human-readable error description." }, { "name": "error", "type": "BetaManagedAgentsWorkspaceArchivedRunError object", "required": false, "description": "The deployment's workspace was archived." }, { "name": "error.type", "type": "\"workspace_archived_error\"", "required": true, "description": "" }, { "name": "error.message", "type": "string", "required": true, "description": "Human-readable error description." }, { "name": "error", "type": "BetaManagedAgentsOrganizationDisabledRunError object", "required": false, "description": "The deployment's organization is disabled." }, { "name": "error.type", "type": "\"organization_disabled_error\"", "required": true, "description": "" }, { "name": "error.message", "type": "string", "required": true, "description": "Human-readable error description." }, { "name": "error", "type": "BetaManagedAgentsSessionRateLimitedRunError object", "required": false, "description": "Session creation was rejected due to rate limiting. The schedule keeps firing; subsequent runs may succeed." }, { "name": "error.type", "type": "\"session_rate_limited_error\"", "required": true, "description": "" }, { "name": "error.message", "type": "string", "required": true, "description": "Human-readable error description." }, { "name": "error", "type": "BetaManagedAgentsSessionCreationRejectedRunError object", "required": false, "description": "The session create request was rejected with a non-retryable validation error." }, { "name": "error.type", "type": "\"session_creation_rejected_error\"", "required": true, "description": "" }, { "name": "error.message", "type": "string", "required": true, "description": "Human-readable error description." }, { "name": "error", "type": "BetaManagedAgentsUnknownRunError object", "required": false, "description": "An unknown or unexpected error caused the run to fail. A fallback variant; clients that do not recognize a new error type can match on message alone." }, { "name": "error.type", "type": "\"unknown_error\"", "required": true, "description": "" }, { "name": "error.message", "type": "string", "required": true, "description": "Human-readable error description." }, { "name": "error", "type": "BetaManagedAgentsSelfHostedResourcesUnsupportedRunError object", "required": false, "description": "The deployment configures resources, but its environment is self-hosted and cannot mount them." }, { "name": "error.type", "type": "\"self_hosted_resources_unsupported_error\"", "required": true, "description": "" }, { "name": "error.message", "type": "string", "required": true, "description": "Human-readable error description." }, { "name": "error", "type": "BetaManagedAgentsMCPEgressBlockedRunError object", "required": false, "description": "An MCP server host used by the deployment's agent is blocked by the environment's network policy." }, { "name": "error.type", "type": "\"mcp_egress_blocked_error\"", "required": true, "description": "" }, { "name": "error.message", "type": "string", "required": true, "description": "Human-readable error description." }, { "name": "session_id", "type": "string or null", "required": true, "description": "Populated on success. Null on creation failure. Exactly one of `session_id` or `error` is non-null." }, { "name": "trigger_context", "type": "BetaManagedAgentsTriggerContext", "required": true, "description": "Describes what triggered a deployment run, with trigger-specific metadata." }, { "name": "trigger_context", "type": "BetaManagedAgentsScheduleTriggerContext object", "required": false, "description": "The run was fired by the deployment's cron schedule." }, { "name": "trigger_context.type", "type": "\"schedule\"", "required": true, "description": "" }, { "name": "trigger_context.scheduled_at", "type": "string", "required": true, "description": "A timestamp in RFC 3339 format", "constraints": { "format": "date-time" } }, { "name": "trigger_context", "type": "BetaManagedAgentsManualTriggerContext object", "required": false, "description": "The run was started manually by creating a session directly against the deployment." }, { "name": "trigger_context.type", "type": "\"manual\"", "required": true, "description": "" } ], "status": [ "DOCUMENTED", "BETA" ], "sources": [ { "url": "https://platform.claude.com/docs/en/api/beta/deployment_runs/retrieve", "retrieved_at": "2026-09-18" }, { "url": "https://platform.claude.com/docs/en/managed-agents/scheduled-deployments", "retrieved_at": "2026-09-18" } ], "beta_header": "managed-agents-2026-04-01", "_fragment": "generated/fragments/objects/anthropic-platform-objects.json" }, { "provider": "anthropic", "api_family": "managed-agents", "name": "Dream", "official_type_name": "BetaDream", "description": "An asynchronous memory-consolidation job that reads a memory store plus a set of session transcripts and writes consolidated memories into an output memory store — a new store by default, or an existing store chosen via output_behavior. The Dreams API is in research preview: the request and response shapes are volatile and may change without the deprecation period that applies to generally-available endpoints.", "fields": [ { "name": "type", "type": "\"dream\"", "required": true, "description": "" }, { "name": "id", "type": "string", "required": true, "description": "" }, { "name": "archived_at", "type": "string or null", "required": true, "description": "A timestamp in RFC 3339 format", "constraints": { "format": "date-time" } }, { "name": "created_at", "type": "string", "required": true, "description": "A timestamp in RFC 3339 format", "constraints": { "format": "date-time" } }, { "name": "ended_at", "type": "string or null", "required": true, "description": "A timestamp in RFC 3339 format", "constraints": { "format": "date-time" } }, { "name": "error", "type": "BetaDreamError or null", "required": true, "description": "Failure detail for a Dream whose `status` is `failed`." }, { "name": "error.type", "type": "string", "required": true, "description": "" }, { "name": "error.message", "type": "string", "required": true, "description": "" }, { "name": "inputs", "type": "array of BetaDreamInput", "required": true, "description": "" }, { "name": "inputs", "type": "BetaDreamMemoryStoreInput object", "required": false, "description": "An input memory store the dream reads from. The dream never mutates this store unless it is also the destination: with output_behavior {type: \"update_existing\"} the job consolidates this store in place." }, { "name": "inputs.type", "type": "\"memory_store\"", "required": true, "description": "" }, { "name": "inputs.memory_store_id", "type": "string", "required": true, "description": "", "constraints": { "minLength": "1" } }, { "name": "inputs", "type": "BetaDreamSessionsInput object", "required": false, "description": "Input session transcripts the dream reads." }, { "name": "inputs.type", "type": "\"sessions\"", "required": true, "description": "" }, { "name": "inputs.session_ids", "type": "array of string", "required": true, "description": "" }, { "name": "instructions", "type": "string or null", "required": true, "description": "" }, { "name": "model", "type": "BetaDreamModelConfig", "required": true, "description": "Model identifier and configuration applied to every pipeline stage. Same wire shape as the Agents API ModelConfig." }, { "name": "model.id", "type": "string", "required": true, "description": "Model identifier, e.g. \"claude-opus-5\". 1-256 characters.", "constraints": { "minLength": "1", "maxLength": "256" } }, { "name": "model.speed", "type": "\"standard\" or \"fast\"", "required": false, "description": "Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time.", "enum": [ "standard", "fast" ] }, { "name": "output_behavior", "type": "BetaOutputBehavior", "required": true, "description": "" }, { "name": "output_behavior", "type": "BetaOutputBehaviorCreateNew object", "required": false, "description": "The default destination: the job creates a new output memory store as a clone of the memory_store input and writes the consolidated memories into it. The input store is never mutated." }, { "name": "output_behavior.type", "type": "\"create_new\"", "required": true, "description": "" }, { "name": "output_behavior", "type": "BetaOutputBehaviorUpdateExisting object", "required": false, "description": "The job writes the consolidated memories into this existing memory store instead of creating one. In EAP the store must be the job's own memory_store input, so the job consolidates the store in place." }, { "name": "output_behavior.type", "type": "\"update_existing\"", "required": true, "description": "" }, { "name": "output_behavior.memory_store_id", "type": "string", "required": true, "description": "", "constraints": { "minLength": "1" } }, { "name": "outputs", "type": "array of BetaDreamOutput", "required": true, "description": "" }, { "name": "outputs.type", "type": "\"memory_store\"", "required": true, "description": "" }, { "name": "outputs.memory_store_id", "type": "string", "required": true, "description": "" }, { "name": "session_id", "type": "string or null", "required": true, "description": "" }, { "name": "status", "type": "BetaDreamStatus", "required": true, "description": "Lifecycle status of a Dream.", "enum": [ "pending", "running", "completed", "failed", "canceled" ] }, { "name": "usage", "type": "BetaDreamUsage", "required": true, "description": "Cumulative token usage for the dream across every pipeline stage." }, { "name": "usage.cache_creation_input_tokens", "type": "number", "required": true, "description": "Total tokens used to create prompt-cache entries (sum of all TTL tiers).", "constraints": { "format": "int32" } }, { "name": "usage.cache_read_input_tokens", "type": "number", "required": true, "description": "Total tokens read from prompt cache.", "constraints": { "format": "int32" } }, { "name": "usage.input_tokens", "type": "number", "required": true, "description": "Total uncached input tokens consumed across every pipeline stage.", "constraints": { "format": "int32" } }, { "name": "usage.output_tokens", "type": "number", "required": true, "description": "Total output tokens generated across every pipeline stage.", "constraints": { "format": "int32" } } ], "status": [ "DOCUMENTED", "BETA", "PREVIEW" ], "sources": [ { "url": "https://platform.claude.com/docs/en/api/beta/dreams/create", "retrieved_at": "2026-09-18" }, { "url": "https://platform.claude.com/docs/en/managed-agents/dreams", "retrieved_at": "2026-09-18" } ], "beta_header": "managed-agents-2026-04-01,dreaming-2026-04-21", "_fragment": "generated/fragments/objects/anthropic-platform-objects.json" }, { "provider": "anthropic", "api_family": "managed-agents", "name": "DreamCreateParams (request body)", "official_type_name": "BetaDreamCreateParams", "description": "Create a Dream", "fields": [ { "name": "inputs", "type": "array of BetaDreamInput", "required": true, "description": "" }, { "name": "inputs", "type": "BetaDreamMemoryStoreInput object", "required": false, "description": "An input memory store the dream reads from. The dream never mutates this store unless it is also the destination: with output_behavior {type: \"update_existing\"} the job consolidates this store in place." }, { "name": "inputs.type", "type": "\"memory_store\"", "required": true, "description": "" }, { "name": "inputs.memory_store_id", "type": "string", "required": true, "description": "", "constraints": { "minLength": "1" } }, { "name": "inputs", "type": "BetaDreamSessionsInput object", "required": false, "description": "Input session transcripts the dream reads." }, { "name": "inputs.type", "type": "\"sessions\"", "required": true, "description": "" }, { "name": "inputs.session_ids", "type": "array of string", "required": true, "description": "" }, { "name": "model", "type": "string or BetaDreamModelConfigParam", "required": true, "description": "" }, { "name": "model", "type": "string", "required": false, "description": "" }, { "name": "model", "type": "BetaDreamModelConfigParam object", "required": false, "description": "Model identifier and configuration applied to every pipeline stage." }, { "name": "model.id", "type": "string", "required": true, "description": "Model identifier, e.g. \"claude-opus-5\". 1-256 characters.", "constraints": { "minLength": "1", "maxLength": "256" } }, { "name": "model.speed", "type": "\"standard\" or \"fast\" or null", "required": false, "description": "Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time.", "enum": [ "standard", "fast" ] }, { "name": "instructions", "type": "string or null", "required": false, "description": "", "constraints": { "minLength": "1", "maxLength": "4096" } }, { "name": "output_behavior", "type": "BetaOutputBehavior", "required": false, "description": "" }, { "name": "output_behavior", "type": "BetaOutputBehaviorCreateNew object", "required": false, "description": "The default destination: the job creates a new output memory store as a clone of the memory_store input and writes the consolidated memories into it. The input store is never mutated." }, { "name": "output_behavior.type", "type": "\"create_new\"", "required": true, "description": "" }, { "name": "output_behavior", "type": "BetaOutputBehaviorUpdateExisting object", "required": false, "description": "The job writes the consolidated memories into this existing memory store instead of creating one. In EAP the store must be the job's own memory_store input, so the job consolidates the store in place." }, { "name": "output_behavior.type", "type": "\"update_existing\"", "required": true, "description": "" }, { "name": "output_behavior.memory_store_id", "type": "string", "required": true, "description": "", "constraints": { "minLength": "1" } } ], "status": [ "DOCUMENTED", "BETA", "PREVIEW" ], "sources": [ { "url": "https://platform.claude.com/docs/en/api/beta/dreams/create", "retrieved_at": "2026-09-18" }, { "url": "https://platform.claude.com/docs/en/managed-agents/dreams", "retrieved_at": "2026-09-18" } ], "beta_header": "managed-agents-2026-04-01,dreaming-2026-04-21", "_fragment": "generated/fragments/objects/anthropic-platform-objects.json" }, { "provider": "anthropic", "api_family": "managed-agents", "name": "MemoryStore", "official_type_name": "BetaManagedAgentsMemoryStore", "description": "A `memory_store`: a named container for agent memories, scoped to a workspace. Attach a store to a session via `resources[]` to mount it as a directory the agent can read and write.", "fields": [ { "name": "type", "type": "\"memory_store\"", "required": true, "description": "" }, { "name": "id", "type": "string", "required": true, "description": "Unique identifier for the memory store (a `memstore_...` tagged ID). Use this when attaching the store to a session, or in the `{memory_store_id}` path parameter of subsequent calls." }, { "name": "created_at", "type": "string", "required": true, "description": "A timestamp in RFC 3339 format", "constraints": { "format": "date-time" } }, { "name": "name", "type": "string", "required": true, "description": "Human-readable name for the store. 1–255 characters. The store's mount-path slug under `/mnt/memory/` is derived from this name." }, { "name": "updated_at", "type": "string", "required": true, "description": "A timestamp in RFC 3339 format", "constraints": { "format": "date-time" } }, { "name": "archived_at", "type": "string or null", "required": false, "description": "A timestamp in RFC 3339 format", "constraints": { "format": "date-time" } }, { "name": "description", "type": "string", "required": false, "description": "Free-text description of what the store contains, up to 1024 characters. Included in the agent's system prompt when the store is attached, so word it to be useful to the agent. Empty string when unset." }, { "name": "metadata", "type": "map[string]", "required": false, "description": "Arbitrary key-value tags for your own bookkeeping (such as the end user a store belongs to). Up to 16 pairs; keys 1–64 characters; values up to 512 characters. Returned on retrieve/list but not filterable." } ], "status": [ "DOCUMENTED", "BETA" ], "sources": [ { "url": "https://platform.claude.com/docs/en/api/beta/memory_stores/create", "retrieved_at": "2026-09-18" }, { "url": "https://platform.claude.com/docs/en/managed-agents/memory", "retrieved_at": "2026-09-18" } ], "beta_header": "agent-memory-2026-07-22 (do not combine with managed-agents-2026-04-01 on memory store calls)", "_fragment": "generated/fragments/objects/anthropic-platform-objects.json" }, { "provider": "anthropic", "api_family": "managed-agents", "name": "Memory", "official_type_name": "BetaManagedAgentsMemory", "description": "A `memory` object: a single text document at a hierarchical path inside a memory store. The `content` field is populated when `view=full` and `null` when `view=basic`; the `content_size_bytes` and `content_sha256` fields are always populated so sync clients can diff without fetching content. Memories are addressed by their `mem_...` ID; the path is the create key and can be changed via update.", "fields": [ { "name": "type", "type": "\"memory\"", "required": true, "description": "" }, { "name": "id", "type": "string", "required": true, "description": "Unique identifier for this memory (a `mem_...` value). Stable across renames; use this ID, not the path, to read, update, or delete the memory." }, { "name": "content_sha256", "type": "string", "required": true, "description": "Lowercase hex SHA-256 digest of the UTF-8 `content` bytes (64 characters). The server applies no normalization, so clients can compute the same hash locally for staleness checks and as the value for a `content_sha256` precondition on update. Always populated, regardless of `view`." }, { "name": "content_size_bytes", "type": "number", "required": true, "description": "Size of `content` in bytes (the UTF-8 plaintext length). Always populated, regardless of `view`.", "constraints": { "format": "int32" } }, { "name": "created_at", "type": "string", "required": true, "description": "A timestamp in RFC 3339 format", "constraints": { "format": "date-time" } }, { "name": "memory_store_id", "type": "string", "required": true, "description": "ID of the memory store this memory belongs to (a `memstore_...` value)." }, { "name": "memory_version_id", "type": "string", "required": true, "description": "ID of the `memory_version` representing this memory's current content (a `memver_...` value). This is the authoritative head pointer; `memory_version` objects do not carry an `is_latest` flag, so compare against this field instead. Enumerate the history via [List memory versions](/docs/en/api/beta/memory_stores/memory_versions/list)." }, { "name": "path", "type": "string", "required": true, "description": "Hierarchical path of the memory within the store, e.g. `/projects/foo/notes.md`. Always starts with `/`. Paths are case-sensitive and unique within a store. Maximum 1,024 bytes." }, { "name": "updated_at", "type": "string", "required": true, "description": "A timestamp in RFC 3339 format", "constraints": { "format": "date-time" } }, { "name": "content", "type": "string or null", "required": false, "description": "The memory's UTF-8 text content. Populated when `view=full`; `null` when `view=basic`. Maximum 100 kB (102,400 bytes)." } ], "status": [ "DOCUMENTED", "BETA" ], "sources": [ { "url": "https://platform.claude.com/docs/en/api/beta/memory_stores/memories/retrieve", "retrieved_at": "2026-09-18" }, { "url": "https://platform.claude.com/docs/en/managed-agents/memory", "retrieved_at": "2026-09-18" } ], "beta_header": "agent-memory-2026-07-22 (do not combine with managed-agents-2026-04-01 on memory store calls)", "_fragment": "generated/fragments/objects/anthropic-platform-objects.json" }, { "provider": "anthropic", "api_family": "managed-agents", "name": "MemoryListItem", "official_type_name": "BetaManagedAgentsMemoryListItem", "description": "One page of results. Each item is either a `memory` object or, when `depth` was set, a `memory_prefix` rollup marker. Items are returned in a stable, server-defined order.", "fields": [ { "name": "", "type": "BetaManagedAgentsMemory object", "required": false, "description": "A `memory` object: a single text document at a hierarchical path inside a memory store. The `content` field is populated when `view=full` and `null` when `view=basic`; the `content_size_bytes` and `content_sha256` fields are always populated so sync clients can diff without fetching content. Memories are addressed by their `mem_...` ID; the path is the create key and can be changed via update." }, { "name": ".type", "type": "\"memory\"", "required": true, "description": "" }, { "name": ".id", "type": "string", "required": true, "description": "Unique identifier for this memory (a `mem_...` value). Stable across renames; use this ID, not the path, to read, update, or delete the memory." }, { "name": ".content_sha256", "type": "string", "required": true, "description": "Lowercase hex SHA-256 digest of the UTF-8 `content` bytes (64 characters). The server applies no normalization, so clients can compute the same hash locally for staleness checks and as the value for a `content_sha256` precondition on update. Always populated, regardless of `view`." }, { "name": ".content_size_bytes", "type": "number", "required": true, "description": "Size of `content` in bytes (the UTF-8 plaintext length). Always populated, regardless of `view`.", "constraints": { "format": "int32" } }, { "name": ".created_at", "type": "string", "required": true, "description": "A timestamp in RFC 3339 format", "constraints": { "format": "date-time" } }, { "name": ".memory_store_id", "type": "string", "required": true, "description": "ID of the memory store this memory belongs to (a `memstore_...` value)." }, { "name": ".memory_version_id", "type": "string", "required": true, "description": "ID of the `memory_version` representing this memory's current content (a `memver_...` value). This is the authoritative head pointer; `memory_version` objects do not carry an `is_latest` flag, so compare against this field instead. Enumerate the history via [List memory versions](/docs/en/api/beta/memory_stores/memory_versions/list)." }, { "name": ".path", "type": "string", "required": true, "description": "Hierarchical path of the memory within the store, e.g. `/projects/foo/notes.md`. Always starts with `/`. Paths are case-sensitive and unique within a store. Maximum 1,024 bytes." }, { "name": ".updated_at", "type": "string", "required": true, "description": "A timestamp in RFC 3339 format", "constraints": { "format": "date-time" } }, { "name": ".content", "type": "string or null", "required": false, "description": "The memory's UTF-8 text content. Populated when `view=full`; `null` when `view=basic`. Maximum 100 kB (102,400 bytes)." }, { "name": "", "type": "BetaManagedAgentsMemoryPrefix object", "required": false, "description": "A rolled-up directory marker returned by [List memories](/docs/en/api/beta/memory_stores/memories/list) when `depth` is set. Indicates that one or more memories exist deeper than the requested depth under this prefix. This is a list-time rollup, not a stored resource; it has no ID and no lifecycle. Each prefix counts toward the page `limit` and interleaves with `memory` items in path order." }, { "name": ".type", "type": "\"memory_prefix\"", "required": true, "description": "" }, { "name": ".path", "type": "string", "required": true, "description": "The rolled-up path prefix, including a trailing `/` (e.g. `/projects/foo/`). Pass this value as `path_prefix` on a subsequent list call to drill into the directory." } ], "status": [ "DOCUMENTED", "BETA" ], "sources": [ { "url": "https://platform.claude.com/docs/en/api/beta/memory_stores/memories/list", "retrieved_at": "2026-09-18" }, { "url": "https://platform.claude.com/docs/en/managed-agents/memory", "retrieved_at": "2026-09-18" } ], "beta_header": "agent-memory-2026-07-22 (do not combine with managed-agents-2026-04-01 on memory store calls)", "_fragment": "generated/fragments/objects/anthropic-platform-objects.json" }, { "provider": "anthropic", "api_family": "managed-agents", "name": "MemoryVersion", "official_type_name": "BetaManagedAgentsMemoryVersion", "description": "A `memory_version` object: one immutable, attributed row in a memory's append-only history. Every non-no-op mutation to a memory produces a new version. Versions belong to the store (not the individual memory) and are not deleted with the memory; each version is retained for at least the version retention period after it was written, unless the store itself is deleted. Retrieving a redacted version returns 200 with `content`, `path`, `content_size_bytes`, and `content_sha256` set to `null`; branch on `redacted_at`, not HTTP status.", "fields": [ { "name": "type", "type": "\"memory_version\"", "required": true, "description": "" }, { "name": "id", "type": "string", "required": true, "description": "Unique identifier for this version (a `memver_...` value)." }, { "name": "created_at", "type": "string", "required": true, "description": "A timestamp in RFC 3339 format", "constraints": { "format": "date-time" } }, { "name": "memory_id", "type": "string", "required": true, "description": "ID of the memory this version snapshots (a `mem_...` value). Remains valid after the memory is deleted; pass it as `memory_id` to [List memory versions](/docs/en/api/beta/memory_stores/memory_versions/list) to retrieve the memory's retained versions, including the `deleted` row while the lineage is retained." }, { "name": "memory_store_id", "type": "string", "required": true, "description": "ID of the memory store this version belongs to (a `memstore_...` value)." }, { "name": "operation", "type": "BetaManagedAgentsMemoryVersionOperation", "required": true, "description": "The kind of mutation a `memory_version` records. Every non-no-op mutation to a memory appends exactly one version row with one of these values.", "enum": [ "created", "modified", "deleted" ] }, { "name": "content", "type": "string or null", "required": false, "description": "The memory's UTF-8 text content as of this version. `null` when `view=basic`, when `operation` is `deleted`, or when `redacted_at` is set." }, { "name": "content_sha256", "type": "string or null", "required": false, "description": "Lowercase hex SHA-256 digest of `content` as of this version (64 characters). `null` when `redacted_at` is set or `operation` is `deleted`. Populated regardless of `view` otherwise." }, { "name": "content_size_bytes", "type": "number or null", "required": false, "description": "Size of `content` in bytes as of this version. `null` when `redacted_at` is set or `operation` is `deleted`. Populated regardless of `view` otherwise.", "constraints": { "format": "int32" } }, { "name": "created_by", "type": "BetaManagedAgentsActor", "required": false, "description": "Identifies who performed a write or redact operation. Captured at write time on the `memory_version` row. The API key that created a session is not recorded on agent writes; attribution answers who made the write, not who is ultimately responsible. Look up session provenance separately via the [Sessions API](/docs/en/api/beta/sessions/retrieve)." }, { "name": "created_by", "type": "BetaManagedAgentsSessionActor object", "required": false, "description": "Attribution for a write made by an agent during a session, through the mounted filesystem at `/mnt/memory/`." }, { "name": "created_by.type", "type": "\"session_actor\"", "required": true, "description": "" }, { "name": "created_by.session_id", "type": "string", "required": true, "description": "ID of the session that performed the write (a `sesn_...` value). Look up the session via [Retrieve a session](/docs/en/api/beta/sessions/retrieve) for further provenance.", "constraints": { "minLength": "1" } }, { "name": "created_by", "type": "BetaManagedAgentsAPIActor object", "required": false, "description": "Attribution for a write made directly via the public API (outside of any session)." }, { "name": "created_by.type", "type": "\"api_actor\"", "required": true, "description": "" }, { "name": "created_by.api_key_id", "type": "string", "required": true, "description": "ID of the API key that performed the write. This identifies the key, not the secret.", "constraints": { "minLength": "1" } }, { "name": "created_by", "type": "BetaManagedAgentsUserActor object", "required": false, "description": "Attribution for a write made by a human user through the Anthropic Console." }, { "name": "created_by.type", "type": "\"user_actor\"", "required": true, "description": "" }, { "name": "created_by.user_id", "type": "string", "required": true, "description": "ID of the user who performed the write (a `user_...` value).", "constraints": { "minLength": "1" } }, { "name": "created_by", "type": "BetaManagedAgentsServiceAccountActor object", "required": false, "description": "Attribution for a write made by a workload authenticated as a service account, for example via Workload Identity Federation." }, { "name": "created_by.type", "type": "\"service_account_actor\"", "required": true, "description": "" }, { "name": "created_by.service_account_id", "type": "string", "required": true, "description": "ID of the service account that performed the write (a `svac_...` value).", "constraints": { "minLength": "1" } }, { "name": "path", "type": "string or null", "required": false, "description": "The memory's path at the time of this write. `null` if and only if `redacted_at` is set." }, { "name": "redacted_at", "type": "string or null", "required": false, "description": "A timestamp in RFC 3339 format", "constraints": { "format": "date-time" } }, { "name": "redacted_by", "type": "BetaManagedAgentsActor", "required": false, "description": "Identifies who performed a write or redact operation. Captured at write time on the `memory_version` row. The API key that created a session is not recorded on agent writes; attribution answers who made the write, not who is ultimately responsible. Look up session provenance separately via the [Sessions API](/docs/en/api/beta/sessions/retrieve)." } ], "status": [ "DOCUMENTED", "BETA" ], "sources": [ { "url": "https://platform.claude.com/docs/en/api/beta/memory_stores/memory_versions/retrieve", "retrieved_at": "2026-09-18" }, { "url": "https://platform.claude.com/docs/en/managed-agents/memory", "retrieved_at": "2026-09-18" } ], "beta_header": "agent-memory-2026-07-22 (do not combine with managed-agents-2026-04-01 on memory store calls)", "_fragment": "generated/fragments/objects/anthropic-platform-objects.json" }, { "provider": "anthropic", "api_family": "managed-agents", "name": "MemoryUpdateParams (request body, precondition)", "official_type_name": "BetaManagedAgentsMemoryUpdateParams", "description": "Update a memory", "fields": [ { "name": "content", "type": "string or null", "required": false, "description": "New UTF-8 text content for the memory. Maximum 100 kB (102,400 bytes). Omit to leave the content unchanged (e.g., for a rename-only update)." }, { "name": "path", "type": "string or null", "required": false, "description": "New path for the memory (a rename). Must start with `/`, contain at least one non-empty segment, and be at most 1,024 bytes. Must not contain empty segments, `.` or `..` segments, control or format characters, or the Unicode line and paragraph separators (U+2028, U+2029), and must be NFC-normalized. Paths are case-sensitive. The memory's `id` is preserved across renames. Omit to leave the path unchanged.", "constraints": { "minLength": "2", "maxLength": "1024" } }, { "name": "precondition", "type": "BetaManagedAgentsPrecondition", "required": false, "description": "Optimistic-concurrency precondition: the update applies only if the memory's stored `content_sha256` equals the supplied value. On mismatch, the request returns `memory_precondition_failed_error` (HTTP 409); re-read the memory and retry against the fresh state. If the precondition fails but the stored state already exactly matches the requested `content` and `path`, the server returns 200 instead of 409." }, { "name": "precondition.type", "type": "\"content_sha256\"", "required": true, "description": "" }, { "name": "precondition.content_sha256", "type": "string", "required": false, "description": "Expected `content_sha256` of the stored memory (64 lowercase hexadecimal characters). Typically the `content_sha256` returned by a prior read or list call. Because the server applies no content normalization, clients can also compute this locally as the SHA-256 of the UTF-8 content bytes." } ], "status": [ "DOCUMENTED", "BETA" ], "sources": [ { "url": "https://platform.claude.com/docs/en/api/beta/memory_stores/memories/update", "retrieved_at": "2026-09-18" }, { "url": "https://platform.claude.com/docs/en/managed-agents/memory", "retrieved_at": "2026-09-18" } ], "beta_header": "agent-memory-2026-07-22 (do not combine with managed-agents-2026-04-01 on memory store calls)", "_fragment": "generated/fragments/objects/anthropic-platform-objects.json" }, { "provider": "anthropic", "api_family": "managed-agents", "name": "Vault", "official_type_name": "BetaManagedAgentsVault", "description": "A vault that stores credentials for use by agents during sessions.", "fields": [ { "name": "type", "type": "\"vault\"", "required": true, "description": "" }, { "name": "id", "type": "string", "required": true, "description": "Unique identifier for the vault." }, { "name": "archived_at", "type": "string or null", "required": true, "description": "A timestamp in RFC 3339 format", "constraints": { "format": "date-time" } }, { "name": "created_at", "type": "string", "required": true, "description": "A timestamp in RFC 3339 format", "constraints": { "format": "date-time" } }, { "name": "display_name", "type": "string", "required": true, "description": "Human-readable name for the vault." }, { "name": "metadata", "type": "map[string]", "required": true, "description": "Arbitrary key-value metadata attached to the vault." }, { "name": "updated_at", "type": "string", "required": true, "description": "A timestamp in RFC 3339 format", "constraints": { "format": "date-time" } } ], "status": [ "DOCUMENTED", "BETA" ], "sources": [ { "url": "https://platform.claude.com/docs/en/api/beta/vaults/create", "retrieved_at": "2026-09-18" }, { "url": "https://platform.claude.com/docs/en/managed-agents/vaults", "retrieved_at": "2026-09-18" } ], "beta_header": "managed-agents-2026-04-01", "_fragment": "generated/fragments/objects/anthropic-platform-objects.json" }, { "provider": "anthropic", "api_family": "managed-agents", "name": "Credential (auth union: mcp_oauth | static_bearer | environment_variable)", "official_type_name": "BetaManagedAgentsCredential", "description": "A credential stored in a vault. Sensitive fields are never returned in responses.", "fields": [ { "name": "type", "type": "\"vault_credential\"", "required": true, "description": "" }, { "name": "id", "type": "string", "required": true, "description": "Unique identifier for the credential." }, { "name": "archived_at", "type": "string or null", "required": true, "description": "A timestamp in RFC 3339 format", "constraints": { "format": "date-time" } }, { "name": "auth", "type": "BetaManagedAgentsMCPOAuthAuthResponse or BetaManagedAgentsStaticBearerAuthResponse or BetaManagedAgentsEnvironmentVariableAuthResponse", "required": true, "description": "Authentication details for a credential." }, { "name": "auth", "type": "BetaManagedAgentsMCPOAuthAuthResponse object", "required": false, "description": "OAuth credential details for an MCP server." }, { "name": "auth.type", "type": "\"mcp_oauth\"", "required": true, "description": "" }, { "name": "auth.mcp_server_url", "type": "string", "required": true, "description": "URL of the MCP server this credential authenticates against." }, { "name": "auth.expires_at", "type": "string or null", "required": false, "description": "A timestamp in RFC 3339 format", "constraints": { "format": "date-time" } }, { "name": "auth.refresh", "type": "BetaManagedAgentsMCPOAuthRefreshResponse or null", "required": false, "description": "OAuth refresh token configuration returned in credential responses." }, { "name": "auth.refresh.client_id", "type": "string", "required": true, "description": "OAuth client ID." }, { "name": "auth.refresh.token_endpoint", "type": "string", "required": true, "description": "Token endpoint URL used to refresh the access token." }, { "name": "auth.refresh.token_endpoint_auth", "type": "BetaManagedAgentsTokenEndpointAuthNoneResponse or BetaManagedAgentsTokenEndpointAuthBasicResponse or BetaManagedAgentsTokenEndpointAuthPostResponse", "required": true, "description": "" }, { "name": "auth.refresh.token_endpoint_auth", "type": "BetaManagedAgentsTokenEndpointAuthNoneResponse object", "required": false, "description": "Token endpoint requires no client authentication." }, { "name": "auth.refresh.token_endpoint_auth.type", "type": "\"none\"", "required": true, "description": "" }, { "name": "auth.refresh.token_endpoint_auth", "type": "BetaManagedAgentsTokenEndpointAuthBasicResponse object", "required": false, "description": "Token endpoint uses HTTP Basic authentication with client credentials." }, { "name": "auth.refresh.token_endpoint_auth.type", "type": "\"client_secret_basic\"", "required": true, "description": "" }, { "name": "auth.refresh.token_endpoint_auth", "type": "BetaManagedAgentsTokenEndpointAuthPostResponse object", "required": false, "description": "Token endpoint uses POST body authentication with client credentials." }, { "name": "auth.refresh.token_endpoint_auth.type", "type": "\"client_secret_post\"", "required": true, "description": "" }, { "name": "auth.refresh.resource", "type": "string or null", "required": false, "description": "OAuth resource indicator." }, { "name": "auth.refresh.scope", "type": "string or null", "required": false, "description": "OAuth scope for the refresh request." }, { "name": "auth", "type": "BetaManagedAgentsStaticBearerAuthResponse object", "required": false, "description": "Static bearer token credential details for an MCP server." }, { "name": "auth.type", "type": "\"static_bearer\"", "required": true, "description": "" }, { "name": "auth.mcp_server_url", "type": "string", "required": true, "description": "URL of the MCP server this credential authenticates against." }, { "name": "auth", "type": "BetaManagedAgentsEnvironmentVariableAuthResponse object", "required": false, "description": "Environment variable credential details. The secret value is never returned." }, { "name": "auth.type", "type": "\"environment_variable\"", "required": true, "description": "" }, { "name": "auth.injection_location", "type": "BetaManagedAgentsInjectionLocationResponse", "required": true, "description": "Where in the outbound request the secret value is substituted." }, { "name": "auth.injection_location.body", "type": "boolean", "required": true, "description": "Whether the placeholder is substituted in the request body." }, { "name": "auth.injection_location.header", "type": "boolean", "required": true, "description": "Whether the placeholder is substituted in request header values." }, { "name": "auth.networking", "type": "BetaManagedAgentsUnrestrictedCredentialNetworkingResponse or BetaManagedAgentsLimitedCredentialNetworkingResponse", "required": true, "description": "Outbound hosts the secret value is substituted on." }, { "name": "auth.networking", "type": "BetaManagedAgentsUnrestrictedCredentialNetworkingResponse object", "required": false, "description": "The secret is substituted on any host the session's Environment network policy permits egress to." }, { "name": "auth.networking.type", "type": "\"unrestricted\"", "required": true, "description": "" }, { "name": "auth.networking", "type": "BetaManagedAgentsLimitedCredentialNetworkingResponse object", "required": false, "description": "The secret is substituted only on requests to the listed hosts." }, { "name": "auth.networking.type", "type": "\"limited\"", "required": true, "description": "" }, { "name": "auth.networking.allowed_hosts", "type": "array of string", "required": true, "description": "Hostnames on which the secret will be substituted. An entry matches the request host exactly; a `*.`-prefixed entry matches any subdomain of the named domain but not the domain itself." }, { "name": "auth.secret_name", "type": "string", "required": true, "description": "Name of the environment variable." }, { "name": "created_at", "type": "string", "required": true, "description": "A timestamp in RFC 3339 format", "constraints": { "format": "date-time" } }, { "name": "metadata", "type": "map[string]", "required": true, "description": "Arbitrary key-value metadata attached to the credential." }, { "name": "updated_at", "type": "string", "required": true, "description": "A timestamp in RFC 3339 format", "constraints": { "format": "date-time" } }, { "name": "vault_id", "type": "string", "required": true, "description": "Identifier of the vault this credential belongs to." }, { "name": "display_name", "type": "string or null", "required": false, "description": "Human-readable name for the credential." } ], "status": [ "DOCUMENTED", "BETA" ], "sources": [ { "url": "https://platform.claude.com/docs/en/api/beta/vaults/credentials/create", "retrieved_at": "2026-09-18" }, { "url": "https://platform.claude.com/docs/en/managed-agents/vaults", "retrieved_at": "2026-09-18" } ], "beta_header": "managed-agents-2026-04-01", "_fragment": "generated/fragments/objects/anthropic-platform-objects.json" }, { "provider": "anthropic", "api_family": "managed-agents", "name": "CredentialCreateParams (request body; secret fields write-only)", "official_type_name": "BetaManagedAgentsCredentialCreateParams", "description": "Create Credential", "fields": [ { "name": "auth", "type": "BetaManagedAgentsMCPOAuthCreateParams or BetaManagedAgentsStaticBearerCreateParams or BetaManagedAgentsEnvironmentVariableCreateParams", "required": true, "description": "Authentication details for creating a credential." }, { "name": "auth", "type": "BetaManagedAgentsMCPOAuthCreateParams object", "required": false, "description": "Parameters for creating an MCP OAuth credential." }, { "name": "auth.type", "type": "\"mcp_oauth\"", "required": true, "description": "" }, { "name": "auth.access_token", "type": "string", "required": true, "description": "OAuth access token.", "constraints": { "minLength": "1", "maxLength": "8192" } }, { "name": "auth.mcp_server_url", "type": "string", "required": true, "description": "URL of the MCP server this credential authenticates against.", "constraints": { "minLength": "1", "maxLength": "2047" } }, { "name": "auth.expires_at", "type": "string or null", "required": false, "description": "A timestamp in RFC 3339 format", "constraints": { "format": "date-time" } }, { "name": "auth.refresh", "type": "BetaManagedAgentsMCPOAuthRefreshParams or null", "required": false, "description": "OAuth refresh token parameters for creating a credential with refresh support." }, { "name": "auth.refresh.client_id", "type": "string", "required": true, "description": "OAuth client ID.", "constraints": { "minLength": "1", "maxLength": "1024" } }, { "name": "auth.refresh.refresh_token", "type": "string", "required": true, "description": "OAuth refresh token.", "constraints": { "minLength": "1", "maxLength": "8192" } }, { "name": "auth.refresh.token_endpoint", "type": "string", "required": true, "description": "Token endpoint URL used to refresh the access token.", "constraints": { "minLength": "1", "maxLength": "2047" } }, { "name": "auth.refresh.token_endpoint_auth", "type": "BetaManagedAgentsTokenEndpointAuthNoneParam or BetaManagedAgentsTokenEndpointAuthBasicParam or BetaManagedAgentsTokenEndpointAuthPostParam", "required": true, "description": "" }, { "name": "auth.refresh.token_endpoint_auth", "type": "BetaManagedAgentsTokenEndpointAuthNoneParam object", "required": false, "description": "Token endpoint requires no client authentication." }, { "name": "auth.refresh.token_endpoint_auth.type", "type": "\"none\"", "required": true, "description": "" }, { "name": "auth.refresh.token_endpoint_auth", "type": "BetaManagedAgentsTokenEndpointAuthBasicParam object", "required": false, "description": "Token endpoint uses HTTP Basic authentication with client credentials." }, { "name": "auth.refresh.token_endpoint_auth.type", "type": "\"client_secret_basic\"", "required": true, "description": "" }, { "name": "auth.refresh.token_endpoint_auth.client_secret", "type": "string", "required": true, "description": "OAuth client secret.", "constraints": { "minLength": "1", "maxLength": "512" } }, { "name": "auth.refresh.token_endpoint_auth", "type": "BetaManagedAgentsTokenEndpointAuthPostParam object", "required": false, "description": "Token endpoint uses POST body authentication with client credentials." }, { "name": "auth.refresh.token_endpoint_auth.type", "type": "\"client_secret_post\"", "required": true, "description": "" }, { "name": "auth.refresh.token_endpoint_auth.client_secret", "type": "string", "required": true, "description": "OAuth client secret.", "constraints": { "minLength": "1", "maxLength": "512" } }, { "name": "auth.refresh.resource", "type": "string or null", "required": false, "description": "OAuth resource indicator.", "constraints": { "minLength": "1", "maxLength": "2047" } }, { "name": "auth.refresh.scope", "type": "string or null", "required": false, "description": "OAuth scope for the refresh request.", "constraints": { "minLength": "1", "maxLength": "8192" } }, { "name": "auth", "type": "BetaManagedAgentsStaticBearerCreateParams object", "required": false, "description": "Parameters for creating a static bearer token credential." }, { "name": "auth.type", "type": "\"static_bearer\"", "required": true, "description": "" }, { "name": "auth.token", "type": "string", "required": true, "description": "Static bearer token value.", "constraints": { "minLength": "1", "maxLength": "8192" } }, { "name": "auth.mcp_server_url", "type": "string", "required": true, "description": "URL of the MCP server this credential authenticates against.", "constraints": { "minLength": "1", "maxLength": "2047" } }, { "name": "auth", "type": "BetaManagedAgentsEnvironmentVariableCreateParams object", "required": false, "description": "Parameters for creating an environment variable credential." }, { "name": "auth.type", "type": "\"environment_variable\"", "required": true, "description": "" }, { "name": "auth.networking", "type": "BetaManagedAgentsCredentialNetworkingParams", "required": true, "description": "Outbound hosts the secret value is substituted on." }, { "name": "auth.networking", "type": "BetaManagedAgentsUnrestrictedCredentialNetworkingParams object", "required": false, "description": "Substitute the secret on any host the session's Environment network policy permits egress to. The Environment's network policy is the only boundary on where the secret can reach." }, { "name": "auth.networking.type", "type": "\"unrestricted\"", "required": true, "description": "" }, { "name": "auth.networking", "type": "BetaManagedAgentsLimitedCredentialNetworkingParams object", "required": false, "description": "Substitute the secret only on requests to the listed hosts." }, { "name": "auth.networking.type", "type": "\"limited\"", "required": true, "description": "" }, { "name": "auth.networking.allowed_hosts", "type": "array of string", "required": true, "description": "Hostnames on which the secret will be substituted. Each entry is a bare hostname (`api.example.com`), an IPv4 address (`192.0.2.1`), or a `*.`-prefixed wildcard (`*.example.com`). URLs, ports, paths, and IPv6 addresses are not accepted. At most 16 entries." }, { "name": "auth.secret_name", "type": "string", "required": true, "description": "Name of the environment variable. Immutable after create.", "constraints": { "minLength": "1", "maxLength": "255" } }, { "name": "auth.secret_value", "type": "string", "required": true, "description": "Secret value. Write-only; never returned in responses.", "constraints": { "minLength": "1", "maxLength": "4096" } }, { "name": "auth.injection_location", "type": "BetaManagedAgentsInjectionLocationParams", "required": false, "description": "Where in the outbound request the secret value may be substituted." }, { "name": "auth.injection_location.body", "type": "boolean", "required": false, "description": "Substitute when the placeholder appears in the request body." }, { "name": "auth.injection_location.header", "type": "boolean", "required": false, "description": "Substitute when the placeholder appears in a request header value." }, { "name": "display_name", "type": "string or null", "required": false, "description": "Human-readable name for the credential. Up to 255 characters.", "constraints": { "maxLength": "255" } }, { "name": "metadata", "type": "map[string]", "required": false, "description": "Arbitrary key-value metadata to attach to the credential. Maximum 16 pairs, keys up to 64 chars, values up to 512 chars." } ], "status": [ "DOCUMENTED", "BETA" ], "sources": [ { "url": "https://platform.claude.com/docs/en/api/beta/vaults/credentials/create", "retrieved_at": "2026-09-18" }, { "url": "https://platform.claude.com/docs/en/managed-agents/vaults", "retrieved_at": "2026-09-18" } ], "beta_header": "managed-agents-2026-04-01", "_fragment": "generated/fragments/objects/anthropic-platform-objects.json" }, { "provider": "anthropic", "api_family": "managed-agents", "name": "CredentialValidation", "official_type_name": "BetaManagedAgentsCredentialValidation", "description": "Result of live-probing a credential against its configured MCP server.", "fields": [ { "name": "type", "type": "\"vault_credential_validation\"", "required": true, "description": "" }, { "name": "credential_id", "type": "string", "required": true, "description": "Unique identifier of the credential that was validated." }, { "name": "has_refresh_token", "type": "boolean", "required": true, "description": "Whether the credential has a refresh token configured." }, { "name": "mcp_probe", "type": "BetaManagedAgentsMCPProbe or null", "required": true, "description": "The failing step of an MCP validation probe." }, { "name": "mcp_probe.http_response", "type": "BetaManagedAgentsRefreshHTTPResponse or null", "required": true, "description": "An HTTP response captured during a credential validation probe." }, { "name": "mcp_probe.http_response.body", "type": "string", "required": true, "description": "Response body. May be truncated and has sensitive values scrubbed." }, { "name": "mcp_probe.http_response.body_truncated", "type": "boolean", "required": true, "description": "Whether `body` was truncated." }, { "name": "mcp_probe.http_response.content_type", "type": "string", "required": true, "description": "Value of the `Content-Type` response header." }, { "name": "mcp_probe.http_response.status_code", "type": "number", "required": true, "description": "HTTP status code.", "constraints": { "format": "int32" } }, { "name": "mcp_probe.method", "type": "string", "required": true, "description": "The MCP method that failed (for example `initialize` or `tools/list`)." }, { "name": "refresh", "type": "BetaManagedAgentsRefreshObject or null", "required": true, "description": "Outcome of a refresh-token exchange attempted during credential validation." }, { "name": "refresh.http_response", "type": "BetaManagedAgentsRefreshHTTPResponse or null", "required": true, "description": "An HTTP response captured during a credential validation probe." }, { "name": "refresh.status", "type": "\"succeeded\" or \"failed\" or \"connect_error\" or \"no_refresh_token\"", "required": true, "description": "Outcome of a refresh-token exchange attempted during credential validation.", "enum": [ "succeeded", "failed", "connect_error", "no_refresh_token" ] }, { "name": "status", "type": "BetaManagedAgentsCredentialValidationStatus", "required": true, "description": "Overall verdict of a credential validation probe.", "enum": [ "valid", "invalid", "unknown" ] }, { "name": "validated_at", "type": "string", "required": true, "description": "A timestamp in RFC 3339 format", "constraints": { "format": "date-time" } }, { "name": "vault_id", "type": "string", "required": true, "description": "Identifier of the vault containing the credential." } ], "status": [ "DOCUMENTED", "BETA" ], "sources": [ { "url": "https://platform.claude.com/docs/en/api/beta/vaults/credentials/mcp_oauth_validate", "retrieved_at": "2026-09-18" }, { "url": "https://platform.claude.com/docs/en/managed-agents/vaults", "retrieved_at": "2026-09-18" } ], "beta_header": "managed-agents-2026-04-01", "_fragment": "generated/fragments/objects/anthropic-platform-objects.json" }, { "provider": "anthropic", "api_family": "managed-agents", "name": "Tunnel (workspace Tunnels API, beta mcp-tunnels-2026-06-22)", "official_type_name": "BetaTunnel", "description": "An MCP tunnel.", "fields": [ { "name": "type", "type": "\"tunnel\"", "required": true, "description": "" }, { "name": "id", "type": "string", "required": true, "description": "Unique identifier for the tunnel, prefixed with `tnl_`." }, { "name": "archived_at", "type": "string or null", "required": true, "description": "A timestamp in RFC 3339 format", "constraints": { "format": "date-time" } }, { "name": "created_at", "type": "string", "required": true, "description": "A timestamp in RFC 3339 format", "constraints": { "format": "date-time" } }, { "name": "display_name", "type": "string or null", "required": true, "description": "Human-readable name for the tunnel (1-255 characters). Null if unset." }, { "name": "domain", "type": "string", "required": true, "description": "Anthropic-assigned hostname for the tunnel. MCP server URLs whose host is a subdomain of this value are routed through the tunnel. Globally unique and never reused, even after the tunnel is archived." } ], "status": [ "DOCUMENTED", "BETA", "PREVIEW" ], "sources": [ { "url": "https://platform.claude.com/docs/en/api/beta/tunnels/create", "retrieved_at": "2026-09-18" }, { "url": "https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/reference", "retrieved_at": "2026-09-18" } ], "beta_header": "mcp-tunnels-2026-06-22", "_fragment": "generated/fragments/objects/anthropic-platform-objects.json" }, { "provider": "anthropic", "api_family": "managed-agents", "name": "TunnelCertificate", "official_type_name": "BetaTunnelCertificate", "description": "A CA certificate attached to a tunnel.", "fields": [ { "name": "type", "type": "\"tunnel_certificate\"", "required": true, "description": "" }, { "name": "id", "type": "string", "required": true, "description": "Unique identifier for the certificate, prefixed with `tcrt_`." }, { "name": "archived_at", "type": "string or null", "required": true, "description": "A timestamp in RFC 3339 format", "constraints": { "format": "date-time" } }, { "name": "created_at", "type": "string", "required": true, "description": "A timestamp in RFC 3339 format", "constraints": { "format": "date-time" } }, { "name": "expires_at", "type": "string or null", "required": true, "description": "A timestamp in RFC 3339 format", "constraints": { "format": "date-time" } }, { "name": "fingerprint", "type": "string", "required": true, "description": "Lowercase hex SHA-256 fingerprint of the certificate's DER encoding." }, { "name": "tunnel_id", "type": "string", "required": true, "description": "ID of the tunnel the certificate is registered against." } ], "status": [ "DOCUMENTED", "BETA", "PREVIEW" ], "sources": [ { "url": "https://platform.claude.com/docs/en/api/beta/tunnels/certificates/create", "retrieved_at": "2026-09-18" }, { "url": "https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/reference", "retrieved_at": "2026-09-18" } ], "beta_header": "mcp-tunnels-2026-06-22", "_fragment": "generated/fragments/objects/anthropic-platform-objects.json" }, { "provider": "anthropic", "api_family": "managed-agents", "name": "TunnelToken", "official_type_name": "BetaTunnelToken", "description": "A tunnel's connector token.", "fields": [ { "name": "type", "type": "\"tunnel_token\"", "required": true, "description": "" }, { "name": "id", "type": "string", "required": true, "description": "Stable identifier for the current token value. Changes when the token is rotated." }, { "name": "tunnel_token", "type": "string", "required": true, "description": "The connector token used to run the tunnel. Treat as a credential." } ], "status": [ "DOCUMENTED", "BETA", "PREVIEW" ], "sources": [ { "url": "https://platform.claude.com/docs/en/api/beta/tunnels/reveal_token", "retrieved_at": "2026-09-18" } ], "beta_header": "mcp-tunnels-2026-06-22", "_fragment": "generated/fragments/objects/anthropic-platform-objects.json" }, { "provider": "anthropic", "api_family": "managed-agents", "name": "UserProfile (separate beta user-profiles-*; not a Managed Agents resource)", "official_type_name": "BetaUserProfile", "description": "Create User Profile", "fields": [ { "name": "type", "type": "\"user_profile\"", "required": true, "description": "Object type. Always `user_profile`." }, { "name": "id", "type": "string", "required": true, "description": "Unique identifier for this user profile, prefixed `uprof_`." }, { "name": "created_at", "type": "string", "required": true, "description": "A timestamp in RFC 3339 format", "constraints": { "format": "date-time" } }, { "name": "metadata", "type": "map[string]", "required": true, "description": "Arbitrary key-value metadata. Maximum 16 pairs, keys up to 64 chars, values up to 512 chars." }, { "name": "trust_grants", "type": "map[BetaUserProfileTrustGrant]", "required": true, "description": "Trust grants for this profile, keyed by grant name. Key omitted when no grant is active or in flight." }, { "name": "trust_grants.status", "type": "\"active\" or \"pending\" or \"rejected\"", "required": true, "description": "Status of the trust grant.", "enum": [ "active", "pending", "rejected" ] }, { "name": "updated_at", "type": "string", "required": true, "description": "A timestamp in RFC 3339 format", "constraints": { "format": "date-time" } }, { "name": "access_type", "type": "\"application\" or \"passthrough\"", "required": false, "description": "How the platform uses the API on behalf of the entity this profile represents. `application`: the platform sells a product that uses the API behind the scenes, and the profile represents an individual end-user of that product. `passthrough`: the platform resells raw inference, and the profile identifies the resold-to company.", "enum": [ "application", "passthrough" ] }, { "name": "external_id", "type": "string or null", "required": false, "description": "Platform's own identifier for this user. Not enforced unique. Present under the `user-profiles-2026-03-24` and `user-profiles-2026-08-18` beta headers; under `user-profiles-2026-09-04` the value is `external_user_details.reference_id`." }, { "name": "external_user_details", "type": "BetaUserProfileExternalUserDetails", "required": false, "description": "Details about the entity this profile represents, as the platform states them. Anthropic does not verify them. Every field is present, `null` until the platform supplies a value." }, { "name": "external_user_details.account_status", "type": "\"active\" or \"suspended\" or \"blocked\" or null", "required": true, "description": "The status of the entity's account on the platform, as the platform states it: `active`; `suspended`, when the platform has restricted the account and may restore it; or `blocked`, when the platform has barred it. It records the platform's decision only; the statuses in `trust_grants` are Anthropic's and do not follow it.", "enum": [ "active", "suspended", "blocked" ] }, { "name": "external_user_details.country", "type": "string or null", "required": true, "description": "The country the platform associates with the entity, as an ISO 3166-1 alpha-2 code. `null` until the platform supplies one." }, { "name": "external_user_details.email_hash", "type": "string or null", "required": true, "description": "The platform-computed hash of the entity's email address. `null` until the platform supplies one." }, { "name": "external_user_details.entity_type", "type": "\"individual\" or \"business\" or \"non_profit\" or \"government\" or null", "required": true, "description": "What kind of entity the profile represents, as the platform states it: `individual`, `business`, `non_profit` or `government`.", "enum": [ "individual", "business", "non_profit", "government" ] }, { "name": "external_user_details.name_hash", "type": "string or null", "required": true, "description": "The platform-computed hash of the entity's name. `null` until the platform supplies one." }, { "name": "external_user_details.onboarded_at", "type": "string or null", "required": true, "description": "A timestamp in RFC 3339 format", "constraints": { "format": "date-time" } }, { "name": "external_user_details.reference_id", "type": "string or null", "required": true, "description": "The platform's own reference for the entity. `null` until the platform supplies one." }, { "name": "external_user_onboarded_at", "type": "string or null", "required": false, "description": "A timestamp in RFC 3339 format", "constraints": { "format": "date-time" } }, { "name": "name", "type": "string or null", "required": false, "description": "Real-world name of the entity this profile represents (company or individual). For a company the platform resells Claude access to (`access_type` `passthrough`) this is that company's name." } ], "status": [ "DOCUMENTED", "BETA" ], "sources": [ { "url": "https://platform.claude.com/docs/en/api/beta/user_profiles/create", "retrieved_at": "2026-09-18" } ], "beta_header": "user-profiles-2026-09-04", "_fragment": "generated/fragments/objects/anthropic-platform-objects.json" }, { "provider": "anthropic", "api_family": "managed-agents", "name": "UserProfileEnrollmentURL", "official_type_name": "BetaUserProfileEnrollmentURL", "description": "Create Enrollment URL", "fields": [ { "name": "type", "type": "\"enrollment_url\"", "required": true, "description": "Object type. Always `enrollment_url`." }, { "name": "expires_at", "type": "string", "required": true, "description": "A timestamp in RFC 3339 format", "constraints": { "format": "date-time" } }, { "name": "url", "type": "string", "required": true, "description": "Enrollment URL to send to the end user. Valid until `expires_at`." } ], "status": [ "DOCUMENTED", "BETA" ], "sources": [ { "url": "https://platform.claude.com/docs/en/api/beta/user_profiles/create_enrollment_url", "retrieved_at": "2026-09-18" } ], "beta_header": "user-profiles-2026-09-04", "_fragment": "generated/fragments/objects/anthropic-platform-objects.json" }, { "provider": "anthropic", "api_family": "managed-agents", "name": "WebhookEvent (envelope)", "official_type_name": "BetaWebhookEvent", "description": "Envelope delivered to a registered webhook endpoint. `data.type` is the event type; `data.id` is the affected resource ID (fetch it with GET). Thread events add `session_thread_id`; credential events add `vault_id`.", "fields": [ { "name": "type", "type": "\"event\"", "required": true, "description": "" }, { "name": "id", "type": "string", "required": true, "description": "Unique per event (not per delivery); equals the webhook-id header. Deduplicate on it." }, { "name": "created_at", "type": "string", "required": true, "description": "RFC 3339 time the event occurred." }, { "name": "data", "type": "BetaWebhookEventData (union of 44 *EventData variants)", "required": true, "description": "" }, { "name": "data.type", "type": "string", "required": true, "description": "Event type string, e.g. session.status_idled." }, { "name": "data.id", "type": "string", "required": true, "description": "ID of the resource that triggered the event." }, { "name": "data.organization_id", "type": "string", "required": true, "description": "" }, { "name": "data.workspace_id", "type": "string", "required": true, "description": "" }, { "name": "data.session_thread_id", "type": "string", "required": false, "description": "Only on session.thread_created / session.thread_idled / session.thread_terminated." }, { "name": "data.vault_id", "type": "string", "required": false, "description": "Only on vault_credential.* events." } ], "status": [ "DOCUMENTED", "BETA" ], "sources": [ { "url": "https://platform.claude.com/docs/en/api/beta/webhooks", "retrieved_at": "2026-09-18" }, { "url": "https://platform.claude.com/docs/en/managed-agents/webhooks", "retrieved_at": "2026-09-18" } ], "beta_header": "managed-agents-2026-04-01", "_fragment": "generated/fragments/objects/anthropic-platform-objects.json" }, { "provider": "anthropic", "api_family": "compliance", "name": "Activity", "official_type_name": "Activity (discriminated union on `type`)", "description": "One Activity Feed event. Common fields id/created_at/organization_id/organization_uuid/actor/type; each `type` adds type-specific fields (e.g. claude_chat_id, filename).", "fields": [ { "name": "type", "type": "\"abuse_decision_received\"", "required": false, "constraints": { "default": "abuse_decision_received" } }, { "name": "actor", "type": "APIActor or UserActor or UnauthenticatedUserActor or 8 more", "required": true, "children": [ { "variant": "APIActor object", "fields": [ { "name": "type", "type": "\"api_actor\"", "required": false, "constraints": { "default": "api_actor" } }, { "name": "api_key_id", "type": "string", "required": true }, { "name": "ip_address", "type": "string", "required": true }, { "name": "user_agent", "type": "string", "required": true } ] }, { "variant": "UserActor object", "fields": [ { "name": "type", "type": "\"user_actor\"", "required": false, "constraints": { "default": "user_actor" } }, { "name": "email_address", "type": "string", "required": true, "constraints": { "format": "email" } }, { "name": "ip_address", "type": "string", "required": true }, { "name": "user_agent", "type": "string", "required": true }, { "name": "user_id", "type": "string", "required": true } ] }, { "variant": "UnauthenticatedUserActor object", "fields": [ { "name": "type", "type": "\"unauthenticated_user_actor\"", "required": false, "constraints": { "default": "unauthenticated_user_actor" } }, { "name": "ip_address", "type": "string", "required": true }, { "name": "user_agent", "type": "string", "required": true }, { "name": "unauthenticated_email_address", "type": "string or null", "required": false, "constraints": { "format": "email" } } ] }, { "variant": "AnthropicActor object", "fields": [ { "name": "type", "type": "\"anthropic_actor\"", "required": false, "constraints": { "default": "anthropic_actor" } }, { "name": "email_address", "type": "string or null", "required": false, "constraints": { "format": "email" } } ] }, { "variant": "SystemActor object", "fields": [ { "name": "type", "type": "\"system_actor\"", "required": false, "constraints": { "default": "system_actor" } }, { "name": "service", "type": "string or null", "required": false, "description": "Name of the automated process that performed the action, when known." } ] }, { "variant": "AdminAPIKeyActor object", "fields": [ { "name": "type", "type": "\"admin_api_key_actor\"", "required": false, "constraints": { "default": "admin_api_key_actor" } }, { "name": "admin_api_key_id", "type": "string", "required": true }, { "name": "ip_address", "type": "string", "required": true }, { "name": "user_agent", "type": "string", "required": true } ] }, { "variant": "ServiceAccountActor object", "fields": [ { "name": "type", "type": "\"service_account_actor\"", "required": false, "constraints": { "default": "service_account_actor" } }, { "name": "ip_address", "type": "string", "required": true }, { "name": "service_account_id", "type": "string", "required": true }, { "name": "user_agent", "type": "string", "required": true } ] }, { "variant": "ScimDirectorySyncActor object", "fields": [ { "name": "type", "type": "\"scim_directory_sync_actor\"", "required": false, "constraints": { "default": "scim_directory_sync_actor" } }, { "name": "directory_id", "type": "string", "required": true }, { "name": "workos_event_id", "type": "string", "required": true }, { "name": "idp_connection_type", "type": "string or null", "required": false } ] }, { "variant": "FederatedIdentityActor object", "fields": [ { "name": "type", "type": "\"federated_identity_actor\"", "required": false, "constraints": { "default": "federated_identity_actor" } }, { "name": "issuer", "type": "string", "required": true }, { "name": "subject", "type": "string", "required": true }, { "name": "audience", "type": "array of string", "required": false }, { "name": "ip_address", "type": "string or null", "required": false }, { "name": "user_agent", "type": "string or null", "required": false } ] }, { "variant": "FederatedActor object", "fields": [ { "name": "type", "type": "\"federated_actor\"", "required": false, "constraints": { "default": "federated_actor" } }, { "name": "provider", "type": "FederatedActorAwsProvider or FederatedActorAzureProvider or FederatedActorGcpProvider or FederatedActorOidcProvider", "required": true, "children": [ { "variant": "FederatedActorAwsProvider object", "fields": [ { "name": "type", "type": "\"aws\"", "required": false, "constraints": { "default": "aws" } }, { "name": "account_id", "type": "string", "required": true }, { "name": "signed_principal", "type": "string", "required": true, "description": "The AWS-signed ARN of the IAM principal that requested the token." } ] }, { "variant": "FederatedActorAzureProvider object", "fields": [ { "name": "type", "type": "\"azure\"", "required": false, "constraints": { "default": "azure" } }, { "name": "subscription_id", "type": "string", "required": true } ] }, { "variant": "FederatedActorGcpProvider object", "fields": [ { "name": "type", "type": "\"gcp\"", "required": false, "constraints": { "default": "gcp" } }, { "name": "project_number", "type": "string", "required": true } ] }, { "variant": "FederatedActorOidcProvider object", "fields": [ { "name": "type", "type": "\"oidc\"", "required": false, "constraints": { "default": "oidc" } }, { "name": "issuer", "type": "string or null", "required": false, "description": "The federation issuer's URL. Null when the presented credential failed verification." } ] } ] }, { "name": "ip_address", "type": "string or null", "required": false }, { "name": "subject", "type": "string or null", "required": false, "description": "The provider's verified identifier for the caller; its form depends on the provider." }, { "name": "user_agent", "type": "string or null", "required": false } ] }, { "variant": "AttestedDeviceActor object", "fields": [ { "name": "type", "type": "\"attested_device_actor\"", "required": false, "constraints": { "default": "attested_device_actor" } }, { "name": "external_client_id", "type": "string", "required": true }, { "name": "kid_hash", "type": "string", "required": true }, { "name": "ip_address", "type": "string or null", "required": false }, { "name": "user_agent", "type": "string or null", "required": false } ] } ] }, { "name": "id", "type": "string", "required": false, "description": "Unique identifier for the activity e.g. 'activity_abcd1234'" }, { "name": "created_at", "type": "string", "required": false, "description": "When this activity occurred.", "constraints": { "format": "date-time" } }, { "name": "organization_id", "type": "string or null", "required": false, "description": "Organization ID this activity is associated with" }, { "name": "organization_uuid", "type": "string or null", "required": false, "description": "Organization UUID where the activity occurred. Null when the activity is not tied to an organization (for example, login and logout events or calls to the Compliance API)." } ], "status": [ "DOCUMENTED", "ACCOUNT_RESTRICTED" ], "sources": [ { "url": "https://platform.claude.com/docs/en/api/compliance/activities/list", "retrieved_at": "2026-09-18" } ], "union_variants": [ "AbuseDecisionReceived", "AccountDeleted", "AdminAPIKeyCreated", "AdminAPIKeyDeleted", "AdminAPIKeyUpdated", "AdminConnectorRequestResolved", "AdminRequestCreated", "AdminSetupChecklistStepDelegated", "AdminSetupChecklistStepDelegationCancelled", "AgeVerified", "AnonymousMobileLoginAttempted", "APIKeyCreated", "ClaudeArtifactAccessFailed", "ClaudeArtifactCommented", "ClaudeArtifactCommentsViewed", "ClaudeArtifactCreated", "ClaudePublishedArtifactDeleted", "ClaudeArtifactPublished", "ClaudeArtifactSharingUpdated", "ClaudeArtifactViewed", "AuditLogExportAccessed", "AuditLogExportStarted", "BillingEmailsUpdated", "CcrAgentCreated", "CcrAgentDeleted", "CcrAgentProxyAnthropicOidcTokenExchanged", "CcrAgentProxyAnthropicOidcTokenMinted", "CcrAgentProxyCredentialCreated", "CcrAgentProxyCredentialDeleted", "CcrAgentProxyCredentialRotated", "CcrAgentProxyCredentialUpdated", "CcrAgentProxyDestinationDeleted", "CcrAgentProxyNetworkEventsListed", "CcrAgentProxyProfileBound", "CcrAgentProxyProfileCreated", "CcrAgentProxyProfileDeleted", "CcrAgentProxyProfileUnbound", "CcrAgentProxyProfileUpdated", "CcrAgentProxyProvisioningCredentialRejected", "CcrAgentProxyProvisioningLinkEnabled", "CcrAgentProxyProvisioningLinkGenerated", "CcrAgentProxyProvisioningLinkRevoked", "CcrAgentProxyProvisioningLinkSubmitted", "CcrAgentProxyRuleCreated", "CcrAgentProxyRuleDeleted", "CcrAgentProxyRuleUpdated", "CcrAgentSlackAccessScopeCreated", "CcrAgentSlackAccessScopeDeleted", "CcrAgentSlackBindingCreated", "CcrAgentSlackBindingDeleted", "CcrAgentUpdated", "CcrChannelManagerAdded", "CcrChannelManagerRemoved", "CcrRoleChannelAssignmentDeleted", "CcrRoleChannelAssignmentUpdated", "CcrSessionCreated", "CcrSessionDeleted", "CcrSessionUpdated", "CcrSlackChannelJoined", "ClaudeChatSettingsUpdated", "ClaudeChatSnapshotCreated", "ClaudeChatSnapshotDeleted", "ClaudeChatSnapshotViewed", "ClaudeArtifactDuplicated", "ClaudeArtifactExternalSharingPermissionUpdated", "ClaudeChatAccessFailed", "ClaudeChatCreated", "ClaudeChatDeleted", "ClaudeChatDeletionFailed", "ClaudeChatSyncSourceCreated", "ClaudeChatSyncSourceDeleted", "ClaudeChatSyncSourceUpdated", "ClaudeChatUpdated", "ClaudeChatViewed", "ClaudeCodeCredentialRevoked", "ClaudeCodeReviewConfigUpdated", "ClaudeCodeReviewRepositoryAdded", "ClaudeCodeReviewRepositoryRemoved", "ClaudeCodeReviewRepositoryUpdated", "ClaudeCodeRunnerDeleted", "ClaudeCodeRunnerPoolCreated", "ClaudeCodeRunnerPoolDeleted", "ClaudeCodeRunnerPoolSecretMinted", "ClaudeCodeRunnerPoolSessionQueueUpdated", "ClaudeCodeRunnerPoolUpdated", "ClaudeCodeSecurityCenterConfigUpdated", "ClaudeCodeSecurityScanCancelled", "ClaudeCodeSecurityScanCreated", "ClaudeCodeSecurityScanProjectMemberUpdated", "ClaudeCodeSecurityScanProjectUpdated", "ClaudeCodeSecurityScanProjectVisibilityUpdated", "ClaudeCodeSecurityScanRunUpdated", "ClaudeCodeSecurityScanScheduleDeleted", "ClaudeCodeSecurityScanScheduleUpdated", "ClaudeCodeSecurityVulnerabilityDeleted", "ClaudeCodeSecurityVulnerabilityFixSessionCreated", "ClaudeCodeSecurityVulnerabilityUpdated", "ClaudeCodeSecurityWebhookCreated", "ClaudeCodeSecurityWebhookDeleted", "ClaudeCodeSecurityWebhookSecretUpdated", "ClaudeCodeSecurityWebhookUpdated", "ClaudeCodeTeamMemoryACLUpdated", "ClaudeCodeTeamMemoryUpdated", "ClaudeCodeTeamOnboardingGuideUpdated", "ClaudeCodeUserMarketplacesUpdated", "ClaudeCodeUserMemoryUpdated", "ClaudeCodeUserPluginsUpdated", "ClaudeCodeUserSettingsUpdated", "ClaudeEnterpriseUpgradeCreditUpdated", "ClaudeFileAccessFailed", "ClaudeFileExported", "ClaudeFileViewed", "ClaudeProjectSyncSourceCreated", "ClaudeProjectSyncSourceDeleted", "ClaudeProjectSyncSourceUpdated", "ClaudeUserSeatTierUpdated", "CliPluginExecPolicyUpdated", "ClaudeCommandCreated", "ClaudeCommandDeleted", "ClaudeCommandReplaced", "ComplianceAPIAccessed", "CoworkSessionUpdated", "DesignProjectArtifactPublished", "DesignProjectCreated", "DesignProjectDeleted", "DesignProjectMemberAdded", "DesignProjectMemberRemoved", "DesignProjectMemberRoleUpdated", "DesignProjectPublished", "DesignProjectSharingUpdated", "DesignProjectUnpublished", "DesignProjectUpdated", "DesignProjectVersionRestored", "DesignProjectViewed", "DesktopExtensionAllowlisted", "DesktopExtensionBlocklisted", "DesktopExtensionDeleted", "DesktopExtensionRemovedFromAllowlist", "DesktopExtensionUnblocked", "DesktopExtensionUploaded", "DesktopExtensionVersionUploaded", "InferenceHooksConfigDeleted", "InferenceHooksConfigUpdated", "InferenceHooksSigningSecretGenerated", "DomainClaimInitiated", "EndUserInviteRequested", "ExtraUsageBillingEnabled", "ExtraUsageCreditGranted", "ExtraUsageSpendLimitCreated", "ExtraUsageSpendLimitDeleted", "ExtraUsageSpendLimitIncreaseRequestApproved", "ExtraUsageSpendLimitIncreaseRequestDenied", "ExtraUsageSpendLimitUpdated", "ClaudeFileDeleted", "ClaudeFileUploaded", "GheConfigurationCreated", "GheConfigurationDeleted", "GheConfigurationUpdated", "GheUserConnected", "GheUserDisconnected", "GheWebhookSignatureInvalid", "ClaudeGitHubIntegrationCreated", "ClaudeGitHubIntegrationDeleted", "ClaudeGitHubIntegrationUpdated", "GitHubAppInstallationLinked", "GitHubAppInstallationUnlinked", "GitHubTokenImport", "ClaudeGdriveIntegrationCreated", "ClaudeGdriveIntegrationDeleted", "ClaudeGdriveIntegrationUpdated", "GroupCreated", "GroupDeleted", "GroupListViewed", "GroupMemberAdded", "GroupMemberAdditionFailed", "GroupMemberListViewed", "GroupMemberRemovalFailed", "GroupMemberRemoved", "GroupProjectSharesRevoked", "GroupSkillSharesRevoked", "GroupUpdated", "GroupViewed", "GroupVisibilityUpdated", "InferenceHooksCircuitBreakerTripped", "InferenceHooksRequestDenied", "InferenceHooksRequestFailedOpen", "IntegrationUserConnected", "IntegrationUserDisconnected", "InvoiceCollectionMethodUpdated", "UserLoggedOut", "LtiLaunchInitiated", "LtiLaunchSuccess", "LtiPlatformCreated", "LtiPlatformUpdated", "MagicLinkLoginFailed", "MagicLinkLoginInitiated", "MagicLinkLoginSucceeded", "ManagedOrganizationSetupCompleted", "MarketplaceCreated", "MarketplaceDeleted", "MarketplaceUpdated", "MarketplaceWebhookDeleted", "MarketplaceWebhookProvisioned", "McpDirectoryServerPublished", "McpServerCreated", "McpServerDeleted", "McpServerManagedAuthTokenExchanged", "McpServerManagedAuthUpdated", "McpServerUpdated", "McpToolPolicyUpdated", "OrgAnalyticsAPICapabilityUpdated", "OrgBulkDeleteInitiated", "OrgCapabilityGrantAdded", "OrgCapabilityGrantRemoved", "OrgClaudeCodeDataSharingDisabled", "OrgClaudeCodeDataSharingEnabled", "OrgClaudeCodeDesktopDisabled", "OrgClaudeCodeDesktopEnabled", "OrgClaudeCodeZeroDataRetentionDisabled", "OrgComplianceAPISettingsUpdated", "OrgConnectorDomainGuardUpdated", "OrgCoworkActWithoutAskingModeDisabled", "OrgCoworkActWithoutAskingModeEnabled", "OrgCoworkAgentDisabled", "OrgCoworkAgentEnabled", "OrgCoworkAutoModeDisabled", "OrgCoworkAutoModeEnabled", "OrgCoworkBrowserPaneDisabled", "OrgCoworkBrowserPaneEnabled", "OrgCoworkDisabled", "OrgCoworkEnabled", "OrgCoworkMcpAlwaysAllowDisabled", "OrgCoworkMcpAlwaysAllowEnabled", "OrgCoworkOtlpSettingsUpdated", "OrgCoworkRemoteDisabled", "OrgCoworkRemoteEnabled", "OrgCreationBlocked", "OrgDataExportAccessed", "OrgDataExportCompleted", "OrgDataExportStarted", "OrgDataResidencyUpdated", "OrgDeletedViaBulk", "OrgDeletionRequested", "OrgDirectoryResyncCompleted", "OrgDirectoryResyncFailed", "OrgDirectoryResyncStarted", "OrgDirectorySyncActivated", "OrgDirectorySyncAddInitiated", "OrgDirectorySyncDeleted", "OrgDiscoverabilityDisabled", "OrgDiscoverabilityEnabled", "OrgDiscoverabilitySettingsUpdated", "OrgDomainAddInitiated", "OrgDomainRemoved", "OrgDomainVerified", "OrgExternalKeyCreated", "OrgExternalKeyDeleted", "OrgExternalKeyUpdated", "OrgExternalKeyValidated", "OrgHipaaSelfServeEnabled", "OrgIPRestrictionCreated", "OrgIPRestrictionDeleted", "OrgIPRestrictionUpdated", "OrgInviteLinkDisabled", "OrgInviteLinkGenerated", "OrgInviteLinkRegenerated", "OrgInviteViewed", "OrgInvitesListed", "OrgJoinProposalDecided", "OrgJoinRequestApproved", "OrgJoinRequestCreated", "OrgJoinRequestDismissed", "OrgJoinRequestInstantApproved", "OrgJoinRequestsBulkDismissed", "OrgMagicLinkSecondFactorToggled", "OrgMemberInvitesDisabled", "OrgMemberInvitesEnabled", "OrgMembersExported", "OrgModelDefaultUpdated", "OrgParentJoinProposalCreated", "OrgParentSearchPerformed", "OrgSSOAddInitiated", "OrgSSOConnectionActivated", "OrgSSOConnectionDeactivated", "OrgSSOConnectionDeleted", "OrgSSOGroupRoleMappingsUpdated", "OrgSSOProvisioningModeChanged", "OrgSSOScimWelcomeEmailToggled", "OrgSSOSeatTierAssignmentToggled", "OrgSSOSeatTierMappingsUpdated", "OrgSSOToggled", "OrgSyncDeletingSynchronizedFilesStarted", "OrgSyncSynchronizedFilesDeleted", "OrgTaintAdded", "OrgTaintRemoved", "OrgUserDeleted", "OrgUserInviteAccepted", "OrgUserInviteDeleted", "OrgUserInviteReSent", "OrgUserInviteRejected", "OrgUserInviteSent", "OrgUserLeft", "OrgUserSharesRetained", "OrgUserTrustedDevicesRevoked", "OrgUserViewed", "OrgUsersListed", "OrgWorkAcrossAppsDisabled", "OrgWorkAcrossAppsEnabled", "OrganizationAddressUpdated", "OrganizationIconDeleted", "OrganizationIconUpdated", "ClaudeOrganizationSettingsUpdated", "OwnedProjectsAccessRestored", "PaymentMethodUpdated", "PendingShareCreated", "PendingShareRevoked", "PhoneCodeSent", "PhoneCodeVerified", "PlatformAgentArchived", "PlatformAgentCreated", "PlatformAgentDeleted", "PlatformAgentDeploymentArchived", "PlatformAgentDeploymentCreated", "PlatformAgentDeploymentDeleted", "PlatformAgentDeploymentPaused", "PlatformAgentDeploymentRunTriggered", "PlatformAgentDeploymentUnpaused", "PlatformAgentDeploymentUpdated", "PlatformAgentSessionArchived", "PlatformAgentSessionCreated", "PlatformAgentSessionDeleted", "PlatformAgentSessionResourceAdded", "PlatformAgentSessionResourceDeleted", "PlatformAgentSessionResourceUpdated", "PlatformAgentSessionThreadArchived", "PlatformAgentSessionUpdated", "PlatformAgentUpdated", "PlatformAPIKeyCreated", "PlatformAPIKeyUpdated", "PlatformAppAttestAuthentication", "PlatformBillingUpgradedToPrepaid", "PlatformClearanceWorkspaceProgramRequestCleared", "PlatformClearanceWorkspaceProgramRequestSet", "PlatformCostReportViewed", "PlatformDreamArchived", "PlatformDreamCancelled", "PlatformDreamCreated", "PlatformFederatedAuthentication", "PlatformFederationIssuerArchived", "PlatformFederationIssuerCreated", "PlatformFederationIssuerUpdated", "PlatformFederationRuleArchived", "PlatformFederationRuleCreated", "PlatformFederationRuleUpdated", "PlatformFederationRuleWorkspaceAdded", "PlatformFederationRuleWorkspaceRemoved", "PlatformFileContentDownloaded", "PlatformFileDeleted", "PlatformFileUploaded", "PlatformMemoryCreated", "PlatformMemoryDeleted", "PlatformMemoryStoreArchived", "PlatformMemoryStoreCreated", "PlatformMemoryStoreDeleted", "PlatformMemoryStoreUpdated", "PlatformMemoryUpdated", "PlatformMemoryVersionRedacted", "PlatformOAuthAppCreated", "PlatformOAuthAppRevoked", "PlatformOAuthAppUpdated", "PlatformPluginDirectorySubmissionCreated", "PlatformPluginDirectorySubmissionDeleted", "PlatformPluginDirectorySubmissionUpdated", "PlatformServiceAccountArchived", "PlatformServiceAccountCreated", "PlatformServiceAccountUpdated", "PlatformServiceAccountWorkspaceMemberAdded", "PlatformServiceAccountWorkspaceMemberRemoved", "PlatformServiceAccountWorkspaceMemberUpdated", "PlatformSigningKeyCreated", "PlatformSigningKeyDeleted", "PlatformSigningKeyRotated", "PlatformSkillVersionContentDownloaded", "PlatformSkillVersionCreated", "PlatformSkillVersionDeleted", "PlatformSpendLimitAlertEmailsUpdated", "PlatformSpendLimitCreated", "PlatformSpendLimitDeleted", "PlatformSpendLimitUpdated", "PlatformUsageReportClaudeCodeViewed", "PlatformUsageReportMessagesViewed", "PlatformWorkspaceArchived", "PlatformWorkspaceCreated", "PlatformWorkspaceInferenceDataRetentionDisabled", "PlatformWorkspaceInferenceDataRetentionEnabled", "PlatformWorkspaceMemberAdded", "PlatformWorkspaceMemberRemoved", "PlatformWorkspaceMemberUpdated", "PlatformWorkspaceMemberViewed", "PlatformWorkspaceMembersListed", "PlatformWorkspaceRateLimitDeleted", "PlatformWorkspaceRateLimitUpdated", "PlatformWorkspaceUpdated", "ClaudePluginCreated", "ClaudePluginDeleted", "ClaudePluginDisabled", "ClaudePluginEnabled", "PluginInstallationPreferenceUpdated", "ClaudePluginReplaced", "ClaudePluginSecurityScanCompleted", "ClaudePluginUpdated", "PrepaidAutoRechargeDisabled", "PrepaidAutoRechargeUpdated", "PrepaidExtraUsageAutoReloadDisabled", "PrepaidExtraUsageAutoReloadEnabled", "PrepaidExtraUsageAutoReloadSettingsUpdated", "PrimaryOwnerTransferred", "ClaudeProjectArchived", "ClaudeProjectCreated", "ClaudeProjectDeleted", "ClaudeProjectDocumentAccessFailed", "ClaudeProjectDocumentBulkDeletionAuditTruncated", "ClaudeProjectDocumentDeleted", "ClaudeProjectDocumentDeletionFailed", "ClaudeProjectDocumentUpdated", "ClaudeProjectDocumentUploaded", "ClaudeProjectDocumentViewed", "ClaudeProjectFileAccessFailed", "ClaudeProjectFileBulkDeletionAuditTruncated", "ClaudeProjectFileDeleted", "ClaudeProjectFileDeletionFailed", "ClaudeProjectFileUploaded", "ClaudeProjectReported", "ClaudeProjectSharingUpdated", "ClaudeProjectViewed", "ClaudePubsecIdentityConfigured", "RbacRoleAssigned", "RbacRoleCreated", "RbacRoleDeleted", "RbacRoleGrantUpdated", "RbacRolePermissionAdded", "RbacRolePermissionRemoved", "RbacRoleUnassigned", "RbacRoleUpdated", "RoleAssignmentGranted", "RoleAssignmentRevoked", "SSOLoginFailed", "SSOLoginInitiated", "SSOLoginSucceeded", "SSOSecondFactorMagicLink", "ScimUserCreated", "ScimUserDeleted", "ScimUserUpdated", "ScopedAPIKeyDeleted", "ScopedAPIKeyUpdated", "SeatTierChangesCancelled", "SeatTiersPurchased", "ServiceCreated", "ServiceDeleted", "ServiceKeyCreated", "ServiceKeyRevoked", "SessionRevoked", "SessionShareAccessed", "SessionShareCreated", "SessionShareRevoked", "ClaudeSkillCreated", "ClaudeSkillDeleted", "ClaudeSkillDisabled", "ClaudeSkillEnabled", "ClaudeSkillReplaced", "ClaudeSkillSecurityScanCompleted", "SlackWorkspaceClaimRevoked", "SlackWorkspaceClaimed", "SocialLoginSucceeded", "StepUpAuthenticationFailed", "StepUpAuthenticationSucceeded", "StepUpCredentialEnrolled", "SubscriptionCancellationScheduled", "SubscriptionQuantityUpdated", "SubscriptionRenewed", "SubscriptionResumed", "SubscriptionStarted", "SubscriptionUpgraded", "TrustedDeviceCredentialRotated", "TrustedDeviceEnrolled", "TrustedDeviceRevoked", "TunnelArchived", "TunnelCertificateAdded", "TunnelCertificateRevoked", "TunnelCreated", "TunnelTokenMinted", "TunnelTokenRevealed", "TunnelTokenRevoked", "TunnelTokenRotated", "UserConsentRecorded", "UserConsentRevoked", "ClaudeUserRoleUpdated", "ClaudeUserSettingsUpdated", "VerificationEvidenceSubmitted", "VerificationProgramApplicationCreated", "WorkspaceMemberSpendLimitCreated", "WorkspaceMemberSpendLimitDeleted", "WorkspaceMemberSpendLimitUpdated", "WorkspaceSpendLimitAlertEmailsUpdated", "WorkspaceSpendLimitCreated", "WorkspaceSpendLimitDeleted" ], "_fragment": "generated/fragments/objects/anthropic-platform-objects.json" }, { "provider": "anthropic", "api_family": "compliance", "name": "Actor", "official_type_name": "APIActor | UserActor | UnauthenticatedUserActor | AnthropicActor | SystemActor | AdminAPIKeyActor | ServiceAccountActor | ScimDirectorySyncActor | FederatedIdentityActor | FederatedActor | AttestedDeviceActor", "description": "Who performed the activity; discriminated union on actor.type.", "fields": [ { "name": "actor", "type": "APIActor or UserActor or UnauthenticatedUserActor or 8 more", "required": true, "children": [ { "variant": "APIActor object", "fields": [ { "name": "type", "type": "\"api_actor\"", "required": false, "constraints": { "default": "api_actor" } }, { "name": "api_key_id", "type": "string", "required": true }, { "name": "ip_address", "type": "string", "required": true }, { "name": "user_agent", "type": "string", "required": true } ] }, { "variant": "UserActor object", "fields": [ { "name": "type", "type": "\"user_actor\"", "required": false, "constraints": { "default": "user_actor" } }, { "name": "email_address", "type": "string", "required": true, "constraints": { "format": "email" } }, { "name": "ip_address", "type": "string", "required": true }, { "name": "user_agent", "type": "string", "required": true }, { "name": "user_id", "type": "string", "required": true } ] }, { "variant": "UnauthenticatedUserActor object", "fields": [ { "name": "type", "type": "\"unauthenticated_user_actor\"", "required": false, "constraints": { "default": "unauthenticated_user_actor" } }, { "name": "ip_address", "type": "string", "required": true }, { "name": "user_agent", "type": "string", "required": true }, { "name": "unauthenticated_email_address", "type": "string or null", "required": false, "constraints": { "format": "email" } } ] }, { "variant": "AnthropicActor object", "fields": [ { "name": "type", "type": "\"anthropic_actor\"", "required": false, "constraints": { "default": "anthropic_actor" } }, { "name": "email_address", "type": "string or null", "required": false, "constraints": { "format": "email" } } ] }, { "variant": "SystemActor object", "fields": [ { "name": "type", "type": "\"system_actor\"", "required": false, "constraints": { "default": "system_actor" } }, { "name": "service", "type": "string or null", "required": false, "description": "Name of the automated process that performed the action, when known." } ] }, { "variant": "AdminAPIKeyActor object", "fields": [ { "name": "type", "type": "\"admin_api_key_actor\"", "required": false, "constraints": { "default": "admin_api_key_actor" } }, { "name": "admin_api_key_id", "type": "string", "required": true }, { "name": "ip_address", "type": "string", "required": true }, { "name": "user_agent", "type": "string", "required": true } ] }, { "variant": "ServiceAccountActor object", "fields": [ { "name": "type", "type": "\"service_account_actor\"", "required": false, "constraints": { "default": "service_account_actor" } }, { "name": "ip_address", "type": "string", "required": true }, { "name": "service_account_id", "type": "string", "required": true }, { "name": "user_agent", "type": "string", "required": true } ] }, { "variant": "ScimDirectorySyncActor object", "fields": [ { "name": "type", "type": "\"scim_directory_sync_actor\"", "required": false, "constraints": { "default": "scim_directory_sync_actor" } }, { "name": "directory_id", "type": "string", "required": true }, { "name": "workos_event_id", "type": "string", "required": true }, { "name": "idp_connection_type", "type": "string or null", "required": false } ] }, { "variant": "FederatedIdentityActor object", "fields": [ { "name": "type", "type": "\"federated_identity_actor\"", "required": false, "constraints": { "default": "federated_identity_actor" } }, { "name": "issuer", "type": "string", "required": true }, { "name": "subject", "type": "string", "required": true }, { "name": "audience", "type": "array of string", "required": false }, { "name": "ip_address", "type": "string or null", "required": false }, { "name": "user_agent", "type": "string or null", "required": false } ] }, { "variant": "FederatedActor object", "fields": [ { "name": "type", "type": "\"federated_actor\"", "required": false, "constraints": { "default": "federated_actor" } }, { "name": "provider", "type": "FederatedActorAwsProvider or FederatedActorAzureProvider or FederatedActorGcpProvider or FederatedActorOidcProvider", "required": true, "children": [ { "variant": "FederatedActorAwsProvider object", "fields": [ { "name": "type", "type": "\"aws\"", "required": false, "constraints": { "default": "aws" } }, { "name": "account_id", "type": "string", "required": true }, { "name": "signed_principal", "type": "string", "required": true, "description": "The AWS-signed ARN of the IAM principal that requested the token." } ] }, { "variant": "FederatedActorAzureProvider object", "fields": [ { "name": "type", "type": "\"azure\"", "required": false, "constraints": { "default": "azure" } }, { "name": "subscription_id", "type": "string", "required": true } ] }, { "variant": "FederatedActorGcpProvider object", "fields": [ { "name": "type", "type": "\"gcp\"", "required": false, "constraints": { "default": "gcp" } }, { "name": "project_number", "type": "string", "required": true } ] }, { "variant": "FederatedActorOidcProvider object", "fields": [ { "name": "type", "type": "\"oidc\"", "required": false, "constraints": { "default": "oidc" } }, { "name": "issuer", "type": "string or null", "required": false, "description": "The federation issuer's URL. Null when the presented credential failed verification." } ] } ] }, { "name": "ip_address", "type": "string or null", "required": false }, { "name": "subject", "type": "string or null", "required": false, "description": "The provider's verified identifier for the caller; its form depends on the provider." }, { "name": "user_agent", "type": "string or null", "required": false } ] }, { "variant": "AttestedDeviceActor object", "fields": [ { "name": "type", "type": "\"attested_device_actor\"", "required": false, "constraints": { "default": "attested_device_actor" } }, { "name": "external_client_id", "type": "string", "required": true }, { "name": "kid_hash", "type": "string", "required": true }, { "name": "ip_address", "type": "string or null", "required": false }, { "name": "user_agent", "type": "string or null", "required": false } ] } ] } ], "status": [ "DOCUMENTED", "ACCOUNT_RESTRICTED" ], "sources": [ { "url": "https://platform.claude.com/docs/en/api/compliance/activities/list", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/anthropic-platform-objects.json" }, { "provider": "anthropic", "api_family": "compliance", "name": "ActivityListResponse", "official_type_name": null, "description": "Envelope: data[] Activity, has_more, first_id, last_id.", "fields": [ { "name": "data", "type": "array of AbuseDecisionReceived or AccountDeleted or AdminAPIKeyCreated or 503 more", "required": false, "description": "List of activity records. Each element's `type` field identifies which activity it is and which additional fields are present." }, { "name": "first_id", "type": "string or null", "required": false }, { "name": "has_more", "type": "boolean", "required": false, "constraints": { "default": "false" } }, { "name": "last_id", "type": "string or null", "required": false } ], "status": [ "DOCUMENTED", "ACCOUNT_RESTRICTED" ], "sources": [ { "url": "https://platform.claude.com/docs/en/api/compliance/activities/list", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/anthropic-platform-objects.json" }, { "provider": "anthropic", "api_family": "compliance", "name": "ComplianceArtifactVersionMetadata", "official_type_name": "object", "description": "Returns metadata for an artifact version, without the content body. Use the sibling `/content` endpoint to fetch the artifact text. The `md5` and `size_bytes` fields here are computed over the UTF-8 encoding of that text, so a DLP consumer can dedupe or match hashes without downloading every artifact.", "fields": [ { "name": "id", "type": "string", "required": true, "description": "Artifact ID e.g. 'claude_artifact_abc123'" }, { "name": "artifact_type", "type": "string or null", "required": true, "description": "MIME-like artifact type e.g. 'application/vnd.ant.code'" }, { "name": "claude_chat_id", "type": "string", "required": true, "description": "The chat this artifact belongs to" }, { "name": "created_at", "type": "string", "required": true, "description": "Artifact version creation timestamp", "constraints": { "format": "date-time" } }, { "name": "md5", "type": "string", "required": true, "description": "Lowercase hex MD5 of the artifact content (UTF-8 encoded). Matches the `content` field returned by the sibling `/content` endpoint." }, { "name": "size_bytes", "type": "number", "required": true, "description": "Size in bytes of the artifact content (UTF-8 encoded)" }, { "name": "title", "type": "string or null", "required": true, "description": "Artifact title" }, { "name": "version_id", "type": "string", "required": true, "description": "Artifact version ID e.g. 'claude_artifact_version_abc123'" } ], "status": [ "DOCUMENTED", "ACCOUNT_RESTRICTED" ], "sources": [ { "url": "https://platform.claude.com/docs/en/api/compliance/apps/artifacts/retrieve", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/anthropic-platform-objects.json" }, { "provider": "anthropic", "api_family": "compliance", "name": "ComplianceChat", "official_type_name": "chat list item", "description": "Lists chat metadata with filtering capabilities for targeted compliance review. Results are sorted chronologically (time ascending) by the `order_by` key, with ties broken by id. filter is deprecated and will be rejected with HTTP 400 after 2026-09-22. For incremental polling by update time, omit `user_ids[]` and set `order_by=updated_at` with `after_id` cursor pagination — this returns the same chats across the whole organization in a single request stream. For per-user listing, use `created_at.*` filters (or no time filter) with the default `order_by`. `user_ids[]` with `order_by=updated_at`", "fields": [ { "name": "id", "type": "string", "required": true, "description": "Chat ID" }, { "name": "created_at", "type": "string", "required": true, "description": "Creation timestamp", "constraints": { "format": "date-time" } }, { "name": "deleted_at", "type": "string or null", "required": true, "description": "Deletion timestamp if deleted", "constraints": { "format": "date-time" } }, { "name": "href", "type": "string", "required": true, "description": "URL to view this chat in claude.ai" }, { "name": "model", "type": "string or null", "required": true, "description": "Model selected for this chat (e.g. 'claude-opus-5'). May be null for legacy chats that never had a model recorded." }, { "name": "name", "type": "string", "required": true, "description": "Chat name/title" }, { "name": "organization_uuid", "type": "string", "required": true, "description": "Organization UUID this chat belongs to" }, { "name": "project_id", "type": "string or null", "required": true, "description": "Project ID this chat belongs to" }, { "name": "updated_at", "type": "string", "required": true, "description": "Last update timestamp", "constraints": { "format": "date-time" } }, { "name": "user", "type": "object or null", "required": true, "description": "The user who created the chat. Null when the API key is restricted to one organization and the creator is no longer a member of it (for example, after they were removed from it). A key for the whole parent organization returns the creator's `id` and current `email_address` for every chat; on the lis", "children": [ { "name": "id", "type": "string", "required": true, "description": "User identifier" }, { "name": "email_address", "type": "string", "required": true, "description": "User's email address" } ] }, { "name": "organization_id", "type": "string", "required": true, "description": "**Deprecated** Organization ID this chat belongs to" } ], "status": [ "DOCUMENTED", "ACCOUNT_RESTRICTED" ], "sources": [ { "url": "https://platform.claude.com/docs/en/api/compliance/apps/chats/list", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/anthropic-platform-objects.json" }, { "provider": "anthropic", "api_family": "compliance", "name": "ComplianceChatMessages", "official_type_name": "chat with chat_messages[]", "description": "Retrieves message history and file metadata for a specific chat.", "fields": [ { "name": "id", "type": "string", "required": true, "description": "Chat ID" }, { "name": "chat_messages", "type": "array of object", "required": true, "description": "Array of chat messages in order of created_at", "children": [ { "name": "id", "type": "string", "required": true, "description": "Unique identifier for the message e.g. 'claude_chat_msg_abcd1234'" }, { "name": "artifacts", "type": "array of object or null", "required": true, "description": "Versioned documents generated or updated by the assistant in this message. Download via `GET /v1/compliance/apps/artifacts/{artifact_version_id}/content`.", "children": [ { "name": "id", "type": "string", "required": true, "description": "Artifact ID e.g. 'claude_artifact_abc123'" }, { "name": "artifact_type", "type": "string or null", "required": true, "description": "MIME-like artifact type e.g. 'application/vnd.ant.code'" }, { "name": "title", "type": "string or null", "required": true, "description": "Artifact title" }, { "name": "version_id", "type": "string", "required": true, "description": "Artifact version ID e.g. 'claude_artifact_version_abc123'" } ] }, { "name": "content", "type": "array of Text or ToolUse or ToolResult", "required": true, "description": "Content blocks within the message", "children": [ { "variant": "Text object", "fields": [ { "name": "type", "type": "\"text\"", "required": true, "constraints": { "default": "text" } }, { "name": "text", "type": "string", "required": true, "description": "Text content from human or assistant" }, { "name": "thinking_redacted", "type": "boolean", "required": true, "description": "True when content enclosed in the assistant's internal-reasoning tags (or the tag markup itself) was removed from `text` during export. Removal never occurs with this field false. Always false on human messages, whose text is exported verbatim.", "constraints": { "default": "false" } }, { "name": "truncated", "type": "boolean", "required": true, "description": "True when `text` was shortened by the server's fixed per-string bound (1 MiB). Always false on chat text blocks.", "constraints": { "default": "false" } } ] }, { "variant": "ToolUse object", "fields": [ { "name": "type", "type": "\"tool_use\"", "required": true, "constraints": { "default": "tool_use" } }, { "name": "id", "type": "string or null", "required": true, "description": "Tool-use ID, e.g. 'toolu_01AbC...'" }, { "name": "input", "type": "string", "required": true, "description": "Arguments passed to the tool, as a JSON-encoded string. May be shortened — see the `truncated` field" }, { "name": "integration_name", "type": "string or null", "required": true, "description": "Name of the integration that provides this tool, when applicable" }, { "name": "mcp_server_url", "type": "string or null", "required": true, "description": "Base URL (scheme, host, and path only) of the MCP server that provides this tool, when applicable" }, { "name": "name", "type": "string", "required": true, "description": "Name of the tool invoked" }, { "name": "truncated", "type": "boolean", "required": true, "description": "True when `input` was shortened. Pass the endpoint's tool-use input max parameter as -1 to request full content, subject to any server-side maximum the endpoint enforces.", "constraints": { "default": "false" } } ] }, { "variant": "ToolResult object", "fields": [ { "name": "type", "type": "\"tool_result\"", "required": true, "constraints": { "default": "tool_result" } }, { "name": "content", "type": "array of object", "required": true, "description": "Text content returned by the tool. Generated files are surfaced via the message's `generated_files` list; other non-text item types (including images and links) are omitted." }, { "name": "integration_name", "type": "string or null", "required": true, "description": "Name of the integration that provides this tool, when applicable" }, { "name": "is_error", "type": "boolean", "required": true, "description": "True when the tool reported an error" }, { "name": "mcp_server_url", "type": "string or null", "required": true, "description": "Base URL (scheme, host, and path only) of the MCP server that provides this tool, when applicable" }, { "name": "name", "type": "string", "required": true, "description": "Name of the tool that produced this result" }, { "name": "tool_use_id", "type": "string or null", "required": true, "description": "ID of the tool_use block this result responds to" }, { "name": "truncated", "type": "boolean", "required": true, "description": "True when one or more text items in `content` were shortened. Pass the endpoint's tool-result max parameter as -1 to request full content, subject to any server-side maximum the endpoint enforces.", "constraints": { "default": "false" } } ] } ] }, { "name": "created_at", "type": "string", "required": true, "description": "Message creation timestamp - For human: when they sent the message, For assistant: when it completed the last content block", "constraints": { "format": "date-time" } }, { "name": "files", "type": "array of object or null", "required": true, "description": "Binary file attachments uploaded by the user. Download via `GET /v1/compliance/apps/chats/files/{claude_file_id}/content`.", "children": [ { "name": "id", "type": "string", "required": true, "description": "File ID" }, { "name": "created_at", "type": "string", "required": true, "description": "File creation timestamp", "constraints": { "format": "date-time" } }, { "name": "filename", "type": "string", "required": true, "description": "Display name of the file" }, { "name": "md5", "type": "string or null", "required": true, "description": "Lowercase hex MD5 of the file's preferred downloadable variant, as recorded at upload time. Null when no stored hash is available." }, { "name": "mime_type", "type": "string or null", "required": true, "description": "MIME type of the file's preferred downloadable variant (e.g. 'application/pdf')" }, { "name": "size_bytes", "type": "number or null", "required": true, "description": "Size in bytes of the file's preferred downloadable variant, if known. Null for older files uploaded before size was recorded." } ] }, { "name": "generated_files", "type": "array of object or null", "required": true, "description": "Downloadable files the assistant created via tool use (e.g. PDF, spreadsheet, slide deck). Distinct from `files`, which are uploads attached to the message. Download via `GET /v1/compliance/apps/chats/generated-files/{claude_gen_file_id}/content`.", "children": [ { "name": "id", "type": "string", "required": true, "description": "Opaque generated-file id, e.g. 'claude_gen_file_abc123'. Treat as an opaque string; the encoding may change without notice." }, { "name": "filename", "type": "string", "required": true, "description": "Display name of the generated file" }, { "name": "md5", "type": "string or null", "required": true, "description": "Lowercase hex MD5 of the generated file, when available. Null when no stored hash is available." }, { "name": "mime_type", "type": "string or null", "required": true, "description": "MIME type reported by the tool that produced the file" }, { "name": "size_bytes", "type": "number or null", "required": true, "description": "Size in bytes of the generated file, when available. Null when the file has expired or size is not recorded." } ] }, { "name": "role", "type": "\"assistant\" or \"user\"", "required": true, "description": "Message sender (user or assistant)", "enum": [ "assistant", "user" ] } ] }, { "name": "created_at", "type": "string", "required": true, "description": "Creation timestamp", "constraints": { "format": "date-time" } }, { "name": "deleted_at", "type": "string or null", "required": true, "description": "Deletion timestamp if deleted", "constraints": { "format": "date-time" } }, { "name": "first_id", "type": "string or null", "required": true, "description": "Opaque pagination cursor for the first message in the current result set. Pass as `before_id` on the next request to page backwards. Clients should treat this value as an opaque string and not attempt to parse or interpret its contents, as the format may change without notice." }, { "name": "has_more", "type": "boolean", "required": true, "description": "Whether more chat messages exist beyond the current result set. Use `last_id` as `after_id` in a follow-up request to page forward.", "constraints": { "default": "false" } }, { "name": "href", "type": "string", "required": true, "description": "URL to view this chat in claude.ai" }, { "name": "last_id", "type": "string or null", "required": true, "description": "Opaque pagination cursor for the last message in the current result set. Pass as `after_id` on the next request to page forwards. Clients should treat this value as an opaque string and not attempt to parse or interpret its contents, as the format may change without notice." }, { "name": "model", "type": "string or null", "required": true, "description": "Model selected for this chat (e.g. 'claude-opus-5'). May be null for legacy chats that never had a model recorded." }, { "name": "name", "type": "string", "required": true, "description": "Chat name" }, { "name": "organization_uuid", "type": "string", "required": true, "description": "Organization UUID this chat belongs to" }, { "name": "project_id", "type": "string or null", "required": true, "description": "Project ID this chat belongs to" }, { "name": "updated_at", "type": "string", "required": true, "description": "Last update timestamp", "constraints": { "format": "date-time" } }, { "name": "user", "type": "object or null", "required": true, "description": "The user who created the chat. Null when the API key is restricted to one organization and the creator is no longer a member of it (for example, after they were removed from it). A key for the whole parent organization returns the creator's `id` and current `email_address` for every chat; on the lis", "children": [ { "name": "id", "type": "string", "required": true, "description": "User identifier" }, { "name": "email_address", "type": "string", "required": true, "description": "User's email address" } ] }, { "name": "organization_id", "type": "string", "required": true, "description": "**Deprecated** Organization ID this chat belongs to" } ], "status": [ "DOCUMENTED", "ACCOUNT_RESTRICTED" ], "sources": [ { "url": "https://platform.claude.com/docs/en/api/compliance/apps/chats/messages/list", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/anthropic-platform-objects.json" }, { "provider": "anthropic", "api_family": "compliance", "name": "ComplianceProjectAttachment", "official_type_name": "ComplianceProjectFileReference | ComplianceProjectDocReference", "description": "List files and documents attached to a project. List files and project documents attached to the project referenced by project_id. This includes the IDs of attached files, and attached project documents. The raw binary content of attached files can be downloaded using the GET /v1/compliance/apps/chats/files/{claude_file_id}/content endpoint. The text content of attached project documents can be fetched using the GET /v1/compliance/apps/projects/documents/{claude_proj_doc_id} endpoint.", "fields": [], "status": [ "DOCUMENTED", "ACCOUNT_RESTRICTED" ], "sources": [ { "url": "https://platform.claude.com/docs/en/api/compliance/apps/projects/attachments/list", "retrieved_at": "2026-09-18" } ], "union_variants": [ { "variant": "ComplianceProjectFileReference object", "fields": [ { "name": "type", "type": "\"project_file\"", "required": true, "description": "Discriminator marking this as a binary file", "constraints": { "default": "project_file" } }, { "name": "id", "type": "string", "required": true, "description": "File identifier (e.g., 'claude_file_abcd')" }, { "name": "created_at", "type": "string", "required": true, "description": "Creation timestamp (RFC 3339 format)", "constraints": { "format": "date-time" } }, { "name": "filename", "type": "string", "required": true, "description": "Display name of the file (e.g., 'document.pdf')" }, { "name": "md5", "type": "string or null", "required": true, "description": "Lowercase hex MD5 of the file's preferred downloadable variant, when recorded. Null otherwise. Use the per-file `/metadata` endpoint for the authoritative value." }, { "name": "mime_type", "type": "string", "required": true, "description": "MIME type of the file's preferred downloadable variant when one is recorded, else 'application/octet-stream'. Use the per-file `/metadata` endpoint for the authoritative value." }, { "name": "size_bytes", "type": "number or null", "required": true, "description": "Size in bytes of the file's preferred downloadable variant, when recorded. Null otherwise. Use the per-file `/metadata` endpoint for the authoritative value." } ] }, { "variant": "ComplianceProjectDocReference object", "fields": [ { "name": "type", "type": "\"project_doc\"", "required": true, "description": "Discriminator marking this as a plain text document", "constraints": { "default": "project_doc" } }, { "name": "id", "type": "string", "required": true, "description": "Project document identifier (e.g., 'claude_proj_doc_abcd')" }, { "name": "created_at", "type": "string", "required": true, "description": "Creation timestamp (RFC 3339 format)", "constraints": { "format": "date-time" } }, { "name": "filename", "type": "string", "required": true, "description": "Display name of the document (e.g., 'document.txt')" }, { "name": "mime_type", "type": "\"text/plain\"", "required": true, "description": "MIME type of the project document, always set to plain text", "constraints": { "default": "text/plain" } }, { "name": "updated_at", "type": "string or null", "required": true, "description": "Last-modified timestamp of the document. Reserved for future use — currently always null.", "constraints": { "format": "date-time" } } ] } ], "_fragment": "generated/fragments/objects/anthropic-platform-objects.json" }, { "provider": "anthropic", "api_family": "compliance", "name": "ComplianceProjectCollaborator", "official_type_name": "ComplianceProjectUserCollaborator | ComplianceProjectGroupCollaborator | ComplianceProjectOrganizationCollaborator | ComplianceProjectOrganizationRoleCollaborator", "description": "List the users, groups, and organization-wide grants on a project. Each entry represents one active role assignment on the project. Principals are returned as a discriminated union on `type` — an individual user, an RBAC group, the whole organization, or all holders of an organization-level role.", "fields": [], "status": [ "DOCUMENTED", "ACCOUNT_RESTRICTED" ], "sources": [ { "url": "https://platform.claude.com/docs/en/api/compliance/apps/projects/collaborators/list", "retrieved_at": "2026-09-18" } ], "union_variants": [ { "variant": "ComplianceProjectUserCollaborator object", "fields": [ { "name": "type", "type": "\"user\"", "required": true, "description": "Discriminator marking this as an individual user collaborator", "constraints": { "default": "user" } }, { "name": "granted_at", "type": "string", "required": true, "description": "When this collaborator was granted access (RFC 3339 format)", "constraints": { "format": "date-time" } }, { "name": "role", "type": "\"admin\" or \"editor\" or \"owner\" or \"viewer\"", "required": true, "description": "Role granted on the project", "enum": [ "admin", "editor", "owner", "viewer" ] }, { "name": "user_id", "type": "string or null", "required": true, "description": "Identifier of the user granted access (tagged ID), or null if their account has since been deleted" } ] }, { "variant": "ComplianceProjectGroupCollaborator object", "fields": [ { "name": "type", "type": "\"group\"", "required": true, "description": "Discriminator marking this as a group collaborator", "constraints": { "default": "group" } }, { "name": "granted_at", "type": "string", "required": true, "description": "When this collaborator was granted access (RFC 3339 format)", "constraints": { "format": "date-time" } }, { "name": "group_id", "type": "string", "required": true, "description": "Identifier of the group granted access (tagged ID)" }, { "name": "role", "type": "\"admin\" or \"editor\" or \"owner\" or \"viewer\"", "required": true, "description": "Role granted on the project", "enum": [ "admin", "editor", "owner", "viewer" ] } ] }, { "variant": "ComplianceProjectOrganizationCollaborator object", "fields": [ { "name": "type", "type": "\"organization\"", "required": true, "description": "Discriminator marking this as an organization-wide grant", "constraints": { "default": "organization" } }, { "name": "granted_at", "type": "string", "required": true, "description": "When this collaborator was granted access (RFC 3339 format)", "constraints": { "format": "date-time" } }, { "name": "organization_uuid", "type": "string", "required": true, "description": "UUID of the organization granted access" }, { "name": "role", "type": "\"admin\" or \"editor\" or \"owner\" or \"viewer\"", "required": true, "description": "Role granted on the project", "enum": [ "admin", "editor", "owner", "viewer" ] } ] }, { "variant": "ComplianceProjectOrganizationRoleCollaborator object", "fields": [ { "name": "type", "type": "\"organization_role\"", "required": true, "description": "Discriminator marking this as a grant to all organization members holding a specific org-level role", "constraints": { "default": "organization_role" } }, { "name": "granted_at", "type": "string", "required": true, "description": "When this collaborator was granted access (RFC 3339 format)", "constraints": { "format": "date-time" } }, { "name": "organization_role", "type": "string", "required": true, "description": "The organization-level role whose holders are granted access" }, { "name": "role", "type": "\"admin\" or \"editor\" or \"owner\" or \"viewer\"", "required": true, "description": "Role granted on the project", "enum": [ "admin", "editor", "owner", "viewer" ] } ] } ], "_fragment": "generated/fragments/objects/anthropic-platform-objects.json" }, { "provider": "anthropic", "api_family": "compliance", "name": "ComplianceLocalSession", "official_type_name": "compliance_local_session", "description": "List local sessions across the organizations the key may read. Results are ordered by `created_at` descending. Pagination is forward-only via `next_page`; there is no reverse cursor.", "fields": [ { "name": "type", "type": "\"compliance_local_session\"", "required": true, "constraints": { "default": "compliance_local_session" } }, { "name": "id", "type": "string", "required": true, "description": "Local session identifier, prefixed `clls_`. Unique within the parent organization. Treat as an opaque string; the format may change without notice." }, { "name": "created_at", "type": "string", "required": true, "description": "Timestamp of the session's first retained inference call (RFC 3339, UTC). When a session's activity spans the child organization's retention boundary, calls older than the boundary are no longer reflected, so this value is the timestamp of the earliest retained call: always strictly after the bounda", "constraints": { "format": "date-time" } }, { "name": "organization_uuid", "type": "string", "required": true, "description": "UUID of the child organization the session belongs to" }, { "name": "product_surface", "type": "string or null", "required": true, "description": "The product the session ran in: `cowork` (Cowork in Claude Desktop on the user's machine), `claude_code` (Claude Code), `claude_science` (Claude Science), or one of `office_agents/excel`, `office_agents/powerpoint`, `office_agents/word`, and `office_agents/outlook` (Claude for Microsoft 365, by app;" }, { "name": "truncated", "type": "boolean", "required": true, "description": "True when the session has more inference calls than the service can return for one session (100,000). The messages endpoint then returns only the session's earliest calls, up to that many, and ends before the session does; `updated_at` is a lower bound on the latest call and can differ between the l", "constraints": { "default": "false" } }, { "name": "updated_at", "type": "string", "required": true, "description": "Timestamp of the session's last retained inference call (RFC 3339, UTC). Always at or after `created_at`. When a session's activity spans the child organization's retention boundary, calls older than the boundary are no longer reflected — but because retention removes only the oldest calls, this val", "constraints": { "format": "date-time" } }, { "name": "user", "type": "object", "required": true, "description": "The authenticated user at the time of the session. Always set; `user.id` is always populated. `user.email_address` is null when the user's account has been deleted or the user is no longer a member of an organization the key may read.", "children": [ { "name": "id", "type": "string", "required": true, "description": "User identifier (tagged ID, prefixed `user_`). Always set, so attribution survives after the user's account is deleted or the user leaves the organizations the key may read." }, { "name": "email_address", "type": "string or null", "required": true, "description": "User's email address. Null when the user's account has been deleted or the user is no longer a member of an organization the key may read. The messages endpoint does not resolve email addresses; this field is always null there." } ] }, { "name": "workspace_id", "type": "string or null", "required": true, "description": "Workspace identifier (tagged ID, prefixed `wrkspc_`). Null for sessions not attributed to a workspace." } ], "status": [ "DOCUMENTED", "ACCOUNT_RESTRICTED" ], "sources": [ { "url": "https://platform.claude.com/docs/en/api/compliance/apps/sessions/local/list", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/anthropic-platform-objects.json" }, { "provider": "anthropic", "api_family": "compliance", "name": "EffectiveOrganizationSettings", "official_type_name": "effective_organization_settings", "description": "Retrieve the effective settings for an organization. Returns the settings currently in force for the given organization — the enforced state after all policies are applied, which may differ from what is configured in the admin console. Settings an organization's administrators cannot change (for example, ones controlled by Anthropic policy or not available to the organization) are omitted from the list. Settings that report a compliance arrangement with Anthropic are the exception: the HIPAA and Access Transparency settings are always included; the API zero data retention setting is reported f", "fields": [ { "name": "type", "type": "\"effective_organization_settings\"", "required": false, "constraints": { "default": "effective_organization_settings" } }, { "name": "api_keys", "type": "array of object", "required": true, "description": "Compliance API keys configured for the organization hierarchy, ordered by creation time ascending. Key secret values are never included.", "children": [ { "name": "type", "type": "\"compliance_api_key\"", "required": false, "constraints": { "default": "compliance_api_key" } }, { "name": "id", "type": "string", "required": true, "description": "Unique identifier for the API key." }, { "name": "created_at", "type": "string", "required": true, "description": "When the key was created.", "constraints": { "format": "date-time" } }, { "name": "created_by_id", "type": "string or null", "required": true, "description": "Identifier of the user who created the key, or null when the key was created by automation or its creator's account no longer exists." }, { "name": "is_active", "type": "boolean", "required": true, "description": "Whether the key is currently active. A deactivated key is listed for audit visibility but cannot authenticate requests." }, { "name": "name", "type": "string", "required": true, "description": "The name given to the API key when it was created." }, { "name": "scopes", "type": "array of string", "required": true, "description": "The permission scopes granted to the key." }, { "name": "expires_at", "type": "string or null", "required": false, "description": "When the key will stop authenticating, or null when the key does not expire.", "constraints": { "format": "date-time" } } ] }, { "name": "organization_id", "type": "string", "required": true }, { "name": "settings", "type": "array of Boolean or Integer or String or 3 more", "required": true, "children": [ { "variant": "Boolean object", "fields": [ { "name": "type", "type": "\"boolean\"", "required": false, "constraints": { "default": "boolean" } }, { "name": "name", "type": "\"access_transparency_enabled\" or \"ai_powered_artifacts_enabled\" or \"api_workbench_feedback_collection_enabled\" or 57 more", "required": true, "enum": [ "access_transparency_enabled", "ai_powered_artifacts_enabled", "api_workbench_feedback_collection_enabled", "api_zero_data_retention_enabled", "artifact_connectors_enabled", "ask_your_org_enabled", "chat_enabled", "claude_ai_chat_sharing_enabled", "claude_ai_feedback_collection_enabled", "claude_ai_integration_sharing_enabled", "claude_ai_skill_plugins_scanning_enabled", "claude_code_desktop_bypass_permissions_enabled", "claude_code_desktop_enabled", "claude_code_fast_mode_enabled", "claude_code_metrics_logging_enabled", "claude_code_remote_control_enabled", "claude_code_review_enabled", "claude_code_routines_enabled", "claude_code_security_enabled", "claude_code_trusted_devices_required", "claude_code_web_enabled", "claude_code_workflows_enabled", "claude_design_enabled", "claude_enterprise_claude_code_zero_data_retention_enabled", "claude_in_slack_enabled", "claude_science_custom_connectors_enabled", "claude_science_custom_skills_enabled", "claude_science_enabled", "claude_science_managed_network_allowlist_enabled", "claude_science_memory_enabled", "claude_science_modal_enabled", "claude_science_scientific_model_endpoints_enabled", "claude_science_ssh_hosts_enabled", "cmek_enabled", "code_execution_enabled", "code_execution_network_egress_enabled", "connector_tools_default_always_allow", "content_redaction_enabled", "cowork_trusted_devices_required", "desktop_extension_allowlist_enabled", "… 60 total" ] }, { "name": "value", "type": "boolean", "required": true } ] }, { "variant": "Integer object", "fields": [ { "name": "type", "type": "\"integer\"", "required": false, "constraints": { "default": "integer" } }, { "name": "name", "type": "\"account_session_duration_seconds\"", "required": true }, { "name": "value", "type": "number or null", "required": true } ] }, { "variant": "String object", "fields": [ { "name": "type", "type": "\"string\"", "required": false, "constraints": { "default": "string" } }, { "name": "name", "type": "\"claude_code_default_worker_environment_id\" or \"claude_code_default_worker_pool_id\"", "required": true, "enum": [ "claude_code_default_worker_environment_id", "claude_code_default_worker_pool_id" ] }, { "name": "value", "type": "string or null", "required": true } ] }, { "variant": "StringList object", "fields": [ { "name": "type", "type": "\"string_list\"", "required": false, "constraints": { "default": "string_list" } }, { "name": "name", "type": "\"allowed_invite_domains\" or \"disabled_admin_request_types\" or \"ip_allowlist_ip_ranges\"", "required": true, "enum": [ "allowed_invite_domains", "disabled_admin_request_types", "ip_allowlist_ip_ranges" ] }, { "name": "value", "type": "array of string", "required": true } ] }, { "variant": "ProvisioningMode object", "fields": [ { "name": "type", "type": "\"provisioning_mode\"", "required": false, "constraints": { "default": "provisioning_mode" } }, { "name": "value", "type": "\"jit_advanced\" or \"jit_permissive\" or \"login_only\" or 2 more", "required": true, "description": "How organization members are provisioned under SSO.", "enum": [ "jit_advanced", "jit_permissive", "login_only", "scim_advanced", "scim_permissive" ] }, { "name": "name", "type": "\"sso_provisioning_mode\"", "required": false, "constraints": { "default": "sso_provisioning_mode" } } ] }, { "variant": "DataRetention object", "fields": [ { "name": "type", "type": "\"data_retention\"", "required": false, "constraints": { "default": "data_retention" } }, { "name": "value", "type": "map[Fixed or Indefinite]", "required": true, "children": [ { "variant": "Fixed object", "fields": [ { "name": "type", "type": "\"fixed\"", "required": false, "constraints": { "default": "fixed" } }, { "name": "duration", "type": "number", "required": true }, { "name": "timescale", "type": "\"day\" or \"month\"", "required": true, "enum": [ "day", "month" ] } ] }, { "variant": "Indefinite object", "fields": [ { "name": "type", "type": "\"indefinite\"", "required": false, "constraints": { "default": "indefinite" } } ] } ] }, { "name": "name", "type": "\"data_retention_periods\"", "required": false, "constraints": { "default": "data_retention_periods" } } ] } ] } ], "status": [ "DOCUMENTED", "ACCOUNT_RESTRICTED" ], "sources": [ { "url": "https://platform.claude.com/docs/en/api/compliance/organizations/settings/retrieve", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/anthropic-platform-objects.json" }, { "provider": "anthropic", "api_family": "messages", "name": "Tool use block (assistant)", "object": "tool_use", "schema_name": null, "description": "Claude's request to run a client tool.", "fields": { "type": "tool_use", "id": "toolu_…", "name": "string", "input": "object", "caller": "{type: direct} | {type: code_execution_20260120, tool_id: srvtoolu_…}", "toolset_name": "computer|browser (toolset members only)", "cache_control": "optional" }, "status": [ "DOCUMENTED", "LIVE_VERIFIED" ], "example": { "type": "tool_use", "id": "toolu_01DSKX54Pm98m42E64kMCrww", "name": "get_weather", "input": { "location": "Paris" }, "caller": { "type": "direct" } }, "example_source": "live a1 2026-09-18", "sources": [ { "url": "https://platform.claude.com/docs/en/agents-and-tools/tool-use/handle-tool-calls", "retrieved_at": "2026-09-18" }, { "url": "https://platform.claude.com/docs/en/agents-and-tools/tool-use/programmatic-tool-calling", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/anthropic-tool-blocks.json" }, { "provider": "anthropic", "api_family": "messages", "name": "Tool result block (user)", "object": "tool_result", "schema_name": null, "description": "Your answer to a tool_use block.", "fields": { "type": "tool_result", "tool_use_id": "toolu_…", "content": "string | [text|image|document|search_result|tool_reference|browser_state]", "is_error": "bool", "toolset_name": "computer|browser", "cache_control": "optional" }, "status": [ "DOCUMENTED", "LIVE_VERIFIED" ], "example": { "type": "tool_result", "tool_use_id": "toolu_01", "content": [ { "type": "text", "text": "15 degrees" } ] }, "example_source": "docs", "sources": [ { "url": "https://platform.claude.com/docs/en/agents-and-tools/tool-use/handle-tool-calls", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/anthropic-tool-blocks.json" }, { "provider": "anthropic", "api_family": "messages", "name": "Caller (direct)", "object": "direct", "schema_name": null, "description": "caller variant for model-initiated calls.", "fields": { "type": "direct" }, "status": [ "DOCUMENTED", "LIVE_VERIFIED" ], "example": { "type": "direct" }, "example_source": "live", "sources": [ { "url": "https://platform.claude.com/docs/en/agents-and-tools/tool-use/programmatic-tool-calling", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/anthropic-tool-blocks.json" }, { "provider": "anthropic", "api_family": "messages", "name": "Caller (code execution)", "object": "code_execution_20260120", "schema_name": null, "description": "caller variant for programmatic calls; tool_id = the code_execution server_tool_use id. Always tagged 20260120 even if 20260521 was declared.", "fields": { "type": "code_execution_20260120", "tool_id": "srvtoolu_…" }, "status": [ "DOCUMENTED", "LIVE_VERIFIED" ], "example": { "type": "code_execution_20260120", "tool_id": "srvtoolu_01XRkMSA5mTTPpoGGMHeLMyb" }, "example_source": "live g1", "sources": [ { "url": "https://platform.claude.com/docs/en/agents-and-tools/tool-use/programmatic-tool-calling", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/anthropic-tool-blocks.json" }, { "provider": "anthropic", "api_family": "messages", "name": "Server tool use block", "object": "server_tool_use", "schema_name": null, "description": "Anthropic-executed tool call (id prefix srvtoolu_). Names: web_search, web_fetch, bash_code_execution, text_editor_code_execution, code_execution, tool_search_tool_regex, tool_search_tool_bm25, advisor.", "fields": { "type": "server_tool_use", "id": "srvtoolu_…", "name": "string", "input": "object", "caller": "optional (nested dynamic-filtering calls)" }, "status": [ "DOCUMENTED", "LIVE_VERIFIED" ], "example": { "type": "server_tool_use", "id": "srvtoolu_01WafKETTQ3UTdLCrTvD3nMs", "name": "web_search", "input": { "query": "Bank of Canada policy interest rate current" } }, "example_source": "live c4", "sources": [ { "url": "https://platform.claude.com/docs/en/agents-and-tools/tool-use/server-tools", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/anthropic-tool-blocks.json" }, { "provider": "anthropic", "api_family": "messages", "name": "Web search tool result", "object": "web_search_tool_result", "schema_name": null, "description": "Search results or error, paired by tool_use_id.", "fields": { "type": "web_search_tool_result", "tool_use_id": "srvtoolu_…", "content": "[web_search_result] | web_search_tool_result_error" }, "status": [ "DOCUMENTED", "LIVE_VERIFIED" ], "example": { "type": "web_search_tool_result", "tool_use_id": "srvtoolu_01WafKETTQ3UTdLCrTvD3nMs", "content": [ { "type": "web_search_result", "title": "Bank of Canada interest rate decisions - The Globe and Mail", "url": "https://www.theglobeandmail.com/topics/bank-of-canada/", "encrypted_content": "EuAQ…", "page_age": "2 weeks ago" } ] }, "example_source": "live c4 (truncated)", "sources": [ { "url": "https://platform.claude.com/docs/en/agents-and-tools/tool-use/web-search-tool", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/anthropic-tool-blocks.json" }, { "provider": "anthropic", "api_family": "messages", "name": "Web search result item", "object": "web_search_result", "schema_name": null, "description": "One search hit.", "fields": { "type": "web_search_result", "url": "string", "title": "string", "encrypted_content": "opaque, must be round-tripped", "page_age": "string|null" }, "status": [ "DOCUMENTED", "LIVE_VERIFIED" ], "example": { "type": "web_search_result", "url": "https://en.wikipedia.org/wiki/Claude_Shannon", "title": "Claude Shannon - Wikipedia", "encrypted_content": "…", "page_age": "April 30, 2025" }, "example_source": "docs", "sources": [ { "url": "https://platform.claude.com/docs/en/agents-and-tools/tool-use/web-search-tool", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/anthropic-tool-blocks.json" }, { "provider": "anthropic", "api_family": "messages", "name": "Web search tool result error", "object": "web_search_tool_result_error", "schema_name": null, "description": "Error variant of web_search_tool_result.content.", "fields": { "type": "web_search_tool_result_error", "error_code": "too_many_requests|invalid_tool_input|max_uses_exceeded|query_too_long|request_too_large|unavailable" }, "status": [ "DOCUMENTED" ], "example": { "type": "web_search_tool_result_error", "error_code": "max_uses_exceeded" }, "example_source": "docs", "sources": [ { "url": "https://platform.claude.com/docs/en/agents-and-tools/tool-use/web-search-tool", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/anthropic-tool-blocks.json" }, { "provider": "anthropic", "api_family": "messages", "name": "Web search citation", "object": "web_search_result_location", "schema_name": null, "description": "Citation attached to a text block after web search.", "fields": { "type": "web_search_result_location", "url": "string", "title": "string", "encrypted_index": "opaque", "cited_text": "<=150 chars" }, "status": [ "DOCUMENTED", "LIVE_VERIFIED" ], "example": { "type": "web_search_result_location", "cited_text": "The Bank of Canada’s benchmark interest rate, known as the policy rate, is at 2.25 per cent. ", "url": "https://www.theglobeandmail.com/topics/bank-of-canada/", "title": "Bank of Canada interest rate decisions - The Globe and Mail", "encrypted_index": "Eo8B…" }, "example_source": "live c4", "sources": [ { "url": "https://platform.claude.com/docs/en/agents-and-tools/tool-use/web-search-tool", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/anthropic-tool-blocks.json" }, { "provider": "anthropic", "api_family": "messages", "name": "Web fetch tool result", "object": "web_fetch_tool_result", "schema_name": null, "description": "Fetched document or error.", "fields": { "type": "web_fetch_tool_result", "tool_use_id": "srvtoolu_…", "content": "web_fetch_result | web_fetch_tool_result_error", "caller": "{type: direct} (seen live)" }, "status": [ "DOCUMENTED", "LIVE_VERIFIED" ], "example": { "type": "web_fetch_tool_result", "tool_use_id": "srvtoolu_01Wyo96U86ZBHpoxvWHigCfL", "content": { "type": "web_fetch_result", "url": "https://example.com", "retrieved_at": "2026-09-18T21:31:53.465000+00:00", "content": { "type": "document", "source": { "type": "text", "media_type": "text/plain", "data": "…" }, "title": "Example Domain", "citations": { "enabled": true } } }, "caller": { "type": "direct" } }, "example_source": "live d1", "sources": [ { "url": "https://platform.claude.com/docs/en/agents-and-tools/tool-use/web-fetch-tool", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/anthropic-tool-blocks.json" }, { "provider": "anthropic", "api_family": "messages", "name": "Web fetch result", "object": "web_fetch_result", "schema_name": null, "description": "Successful fetch payload.", "fields": { "type": "web_fetch_result", "url": "string", "retrieved_at": "ISO-8601", "content": "document block (source text/plain or base64 application/pdf, title?, citations?)" }, "status": [ "DOCUMENTED" ], "example": { "type": "web_fetch_result", "url": "https://example.com/paper.pdf", "content": { "type": "document", "source": { "type": "base64", "media_type": "application/pdf", "data": "JVBERi0…" }, "citations": { "enabled": true } }, "retrieved_at": "2025-08-25T10:30:02Z" }, "example_source": "docs", "sources": [ { "url": "https://platform.claude.com/docs/en/agents-and-tools/tool-use/web-fetch-tool", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/anthropic-tool-blocks.json" }, { "provider": "anthropic", "api_family": "messages", "name": "Web fetch tool result error", "object": "web_fetch_tool_result_error", "schema_name": null, "description": "Error variant.", "fields": { "type": "web_fetch_tool_result_error", "error_code": "invalid_tool_input|url_too_long|url_not_allowed|url_not_in_prior_context|url_not_accessible|too_many_requests|unsupported_content_type|max_uses_exceeded|unavailable" }, "status": [ "DOCUMENTED", "LIVE_VERIFIED" ], "example": { "type": "web_fetch_tool_result_error", "error_code": "url_not_in_prior_context" }, "example_source": "live k21", "sources": [ { "url": "https://platform.claude.com/docs/en/agents-and-tools/tool-use/web-fetch-tool", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/anthropic-tool-blocks.json" }, { "provider": "anthropic", "api_family": "messages", "name": "Bash code execution tool result", "object": "bash_code_execution_tool_result", "schema_name": null, "description": "Result of the code_execution bash sub-tool.", "fields": { "type": "bash_code_execution_tool_result", "tool_use_id": "srvtoolu_…", "content": "bash_code_execution_result | bash_code_execution_tool_result_error" }, "status": [ "DOCUMENTED", "LIVE_VERIFIED" ], "example": { "type": "bash_code_execution_tool_result", "tool_use_id": "srvtoolu_017wgbCMpCoaqP1rGX7nhccu", "content": { "type": "bash_code_execution_result", "stdout": "4\n", "stderr": "", "return_code": 0, "content": [] } }, "example_source": "live e1", "sources": [ { "url": "https://platform.claude.com/docs/en/agents-and-tools/tool-use/code-execution-tool", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/anthropic-tool-blocks.json" }, { "provider": "anthropic", "api_family": "messages", "name": "Bash code execution result", "object": "bash_code_execution_result", "schema_name": null, "description": "stdout/stderr/return_code + captured $OUTPUT_DIR files.", "fields": { "type": "bash_code_execution_result", "stdout": "string", "stderr": "string", "return_code": "int", "content": "[{type: code_execution_output, file_id}]" }, "status": [ "DOCUMENTED", "LIVE_VERIFIED" ], "example": { "type": "bash_code_execution_result", "stdout": "hi\n", "stderr": "", "return_code": 0, "content": [] }, "example_source": "live e2", "sources": [ { "url": "https://platform.claude.com/docs/en/agents-and-tools/tool-use/code-execution-tool", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/anthropic-tool-blocks.json" }, { "provider": "anthropic", "api_family": "messages", "name": "Text editor code execution tool result", "object": "text_editor_code_execution_tool_result", "schema_name": null, "description": "Result of the code_execution file sub-tool.", "fields": { "type": "text_editor_code_execution_tool_result", "tool_use_id": "srvtoolu_…", "content": "text_editor_code_execution_view_result{file_type,content,num_lines,start_line,total_lines} | …_create_result{is_file_update} | …_str_replace_result{old_start,old_lines,new_start,new_lines,lines[]} | text_editor_code_execution_tool_result_error{error_code}" }, "status": [ "DOCUMENTED" ], "example": { "type": "text_editor_code_execution_tool_result", "tool_use_id": "srvtoolu_01C4D5E6F7G8H9I0J1K2L3M4", "content": { "type": "text_editor_code_execution_view_result", "file_type": "text", "content": "{\n \"setting\": \"value\"\n}", "num_lines": 3, "start_line": 1, "total_lines": 3 } }, "example_source": "docs", "sources": [ { "url": "https://platform.claude.com/docs/en/agents-and-tools/tool-use/code-execution-tool", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/anthropic-tool-blocks.json" }, { "provider": "anthropic", "api_family": "messages", "name": "Code execution tool result (Python cell / legacy)", "object": "code_execution_tool_result", "schema_name": null, "description": "Result of a code_execution Python cell (PTC, 20260120+) or of the legacy 20250522 tool.", "fields": { "type": "code_execution_tool_result", "tool_use_id": "srvtoolu_…", "content": "code_execution_result{stdout,stderr,return_code,content[],abort_reason?} | code_execution_tool_result_error{error_code}" }, "status": [ "DOCUMENTED", "LIVE_VERIFIED", "LIVE_DISCOVERED" ], "example": { "type": "code_execution_tool_result", "tool_use_id": "srvtoolu_01XRkMSA5mTTPpoGGMHeLMyb", "content": { "type": "code_execution_result", "stdout": "[{'one': 1}]\n", "stderr": "", "return_code": 0, "content": [], "abort_reason": null } }, "example_source": "live g2 (abort_reason undocumented)", "sources": [ { "url": "https://platform.claude.com/docs/en/agents-and-tools/tool-use/programmatic-tool-calling", "retrieved_at": "2026-09-18" }, { "url": "https://platform.claude.com/docs/en/agents-and-tools/tool-use/code-execution-tool", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/anthropic-tool-blocks.json" }, { "provider": "anthropic", "api_family": "messages", "name": "Code execution tool result error", "object": "code_execution_tool_result_error", "schema_name": null, "description": "Error variant (also bash_/text_editor_ prefixed).", "fields": { "type": "code_execution_tool_result_error", "error_code": "unavailable|execution_time_exceeded|invalid_tool_input|too_many_requests|output_file_too_large|file_not_found" }, "status": [ "DOCUMENTED" ], "example": { "type": "bash_code_execution_tool_result_error", "error_code": "unavailable" }, "example_source": "docs", "sources": [ { "url": "https://platform.claude.com/docs/en/agents-and-tools/tool-use/code-execution-tool", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/anthropic-tool-blocks.json" }, { "provider": "anthropic", "api_family": "messages", "name": "Container (response)", "object": "container", "schema_name": null, "description": "Top-level response field when code execution ran.", "fields": { "id": "container_…", "expires_at": "ISO-8601 rolling (~5 h ahead live); 30-day hard limit not reported", "skills": "[{type, skill_id, version}]|null" }, "status": [ "DOCUMENTED", "LIVE_VERIFIED" ], "example": { "id": "container_01YXRh6bhAJd4WeWsdo29Bgg", "expires_at": "2026-09-19T02:49:11.949149Z" }, "example_source": "live e1", "sources": [ { "url": "https://platform.claude.com/docs/en/agents-and-tools/tool-use/code-execution-tool", "retrieved_at": "2026-09-18" }, { "url": "https://platform.claude.com/docs/en/api/messages/create", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/anthropic-tool-blocks.json" }, { "provider": "anthropic", "api_family": "messages", "name": "Container upload block (user)", "object": "container_upload", "schema_name": null, "description": "Preload a Files API file into the container.", "fields": { "type": "container_upload", "file_id": "file_…" }, "status": [ "DOCUMENTED" ], "example": { "type": "container_upload", "file_id": "file_011CNha8iCJcU1wXNR6q4V8w" }, "example_source": "docs", "sources": [ { "url": "https://platform.claude.com/docs/en/agents-and-tools/tool-use/code-execution-tool", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/anthropic-tool-blocks.json" }, { "provider": "anthropic", "api_family": "messages", "name": "Tool search tool result", "object": "tool_search_tool_result", "schema_name": null, "description": "Discovered tool references (server-side format).", "fields": { "type": "tool_search_tool_result", "tool_use_id": "srvtoolu_…", "content": "tool_search_tool_search_result{tool_references[]} | tool_search_tool_result_error{error_code,error_message}" }, "status": [ "DOCUMENTED", "LIVE_VERIFIED" ], "example": { "type": "tool_search_tool_result", "tool_use_id": "srvtoolu_0174JggKYYgM6KLN5X3WkG8N", "content": { "type": "tool_search_tool_search_result", "tool_references": [ { "type": "tool_reference", "tool_name": "get_weather" } ] } }, "example_source": "live f1", "sources": [ { "url": "https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-search-tool", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/anthropic-tool-blocks.json" }, { "provider": "anthropic", "api_family": "messages", "name": "Tool reference block", "object": "tool_reference", "schema_name": null, "description": "Pointer to a deferred tool; the API expands it into the full definition. Also valid inside a custom tool_result for client-side tool search.", "fields": { "type": "tool_reference", "tool_name": "string" }, "status": [ "DOCUMENTED", "LIVE_VERIFIED" ], "example": { "type": "tool_reference", "tool_name": "get_weather" }, "example_source": "docs", "sources": [ { "url": "https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-search-tool", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/anthropic-tool-blocks.json" }, { "provider": "anthropic", "api_family": "messages", "name": "Tool search tool result error", "object": "tool_search_tool_result_error", "schema_name": null, "description": "Error variant (200 response).", "fields": { "type": "tool_search_tool_result_error", "error_code": "invalid_tool_input|unavailable|too_many_requests|execution_time_exceeded", "error_message": "string" }, "status": [ "DOCUMENTED" ], "example": { "type": "tool_search_tool_result_error", "error_code": "invalid_tool_input", "error_message": "Invalid regular expression pattern: missing ) at position 1" }, "example_source": "docs", "sources": [ { "url": "https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-search-tool", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/anthropic-tool-blocks.json" }, { "provider": "anthropic", "api_family": "messages", "name": "MCP tool use block", "object": "mcp_tool_use", "schema_name": null, "description": "Claude calling a remote MCP tool via the connector (id prefix mcptoolu_).", "fields": { "type": "mcp_tool_use", "id": "mcptoolu_…", "name": "string", "server_name": "string", "input": "object" }, "status": [ "DOCUMENTED", "BETA", "LIVE_VERIFIED" ], "example": { "type": "mcp_tool_use", "id": "mcptoolu_01SvS54EZae5f3nhQCKNuBu5", "name": "read_wiki_structure", "input": { "repoName": "anthropics/anthropic-sdk-python" }, "server_name": "deepwiki" }, "example_source": "live i1", "sources": [ { "url": "https://platform.claude.com/docs/en/agents-and-tools/mcp-connector", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/anthropic-tool-blocks.json" }, { "provider": "anthropic", "api_family": "messages", "name": "MCP tool result block", "object": "mcp_tool_result", "schema_name": null, "description": "Result returned by the MCP server (executed by Anthropic).", "fields": { "type": "mcp_tool_result", "tool_use_id": "mcptoolu_…", "is_error": "bool", "content": "string | [text …]" }, "status": [ "DOCUMENTED", "BETA", "LIVE_VERIFIED" ], "example": { "type": "mcp_tool_result", "tool_use_id": "mcptoolu_01SvS54EZae5f3nhQCKNuBu5", "is_error": false, "content": [ { "type": "text", "text": "Available pages for anthropics/anthropic-sdk-python:\n\n- 1 Overview\n- 2 Installation and Setup\n…" } ] }, "example_source": "live i1 (truncated)", "sources": [ { "url": "https://platform.claude.com/docs/en/agents-and-tools/mcp-connector", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/anthropic-tool-blocks.json" }, { "provider": "anthropic", "api_family": "messages", "name": "Advisor tool result", "object": "advisor_tool_result", "schema_name": null, "description": "Advisor guidance block.", "fields": { "type": "advisor_tool_result", "tool_use_id": "srvtoolu_…", "content": "advisor_result{text,stop_reason?} | advisor_redacted_result{encrypted_content,stop_reason?} | advisor_tool_result_error{error_code}" }, "status": [ "DOCUMENTED", "BETA" ], "example": { "type": "advisor_tool_result", "tool_use_id": "srvtoolu_abc123", "content": { "type": "advisor_result", "text": "Use a channel-based coordination pattern…" } }, "example_source": "docs", "sources": [ { "url": "https://platform.claude.com/docs/en/agents-and-tools/tool-use/advisor-tool", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/anthropic-tool-blocks.json" }, { "provider": "anthropic", "api_family": "messages", "name": "Usage server_tool_use", "object": "usage.server_tool_use", "schema_name": null, "description": "Server tool counters in usage.", "fields": { "web_search_requests": "int", "web_fetch_requests": "int", "code_execution_requests": "int (documented; NOT present live 2026-09-18)" }, "status": [ "DOCUMENTED", "LIVE_VERIFIED" ], "example": { "server_tool_use": { "web_search_requests": 0, "web_fetch_requests": 1 } }, "example_source": "live d1", "sources": [ { "url": "https://platform.claude.com/docs/en/agents-and-tools/tool-use/web-search-tool", "retrieved_at": "2026-09-18" }, { "url": "https://platform.claude.com/docs/en/agents-and-tools/tool-use/web-fetch-tool", "retrieved_at": "2026-09-18" }, { "url": "https://platform.claude.com/docs/en/agents-and-tools/tool-use/code-execution-tool", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/anthropic-tool-blocks.json" }, { "provider": "anthropic", "api_family": "messages", "name": "Usage iterations (advisor)", "object": "usage.iterations[]", "schema_name": null, "description": "Per-iteration token breakdown when the advisor tool is present.", "fields": { "type": "message|advisor_message", "model": "advisor model (advisor_message only)", "input_tokens": "int", "output_tokens": "int", "cache_read_input_tokens": "int", "cache_creation_input_tokens": "int" }, "status": [ "DOCUMENTED", "BETA", "LIVE_VERIFIED" ], "example": { "iterations": [ { "type": "message", "input_tokens": 990, "output_tokens": 5, "cache_read_input_tokens": 0, "cache_creation_input_tokens": 0 } ] }, "example_source": "live k18", "sources": [ { "url": "https://platform.claude.com/docs/en/agents-and-tools/tool-use/advisor-tool", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/anthropic-tool-blocks.json" }, { "provider": "anthropic", "api_family": "messages", "name": "Browser state block (user)", "object": "browser_state", "schema_name": null, "description": "Tab inventory returned with browser toolset results.", "fields": { "type": "browser_state", "tabs": "[{tab_id, title, url, active?}] (<=100)", "state_changes": "[{type: tab_opened, tab_id} | {type: download_started|download_completed|download_failed, …}] (<=200, omit when empty)" }, "status": [ "DOCUMENTED" ], "example": { "type": "browser_state", "tabs": [ { "tab_id": "tab-1", "title": "Documentation", "url": "https://example.com/docs", "active": true } ] }, "example_source": "docs", "sources": [ { "url": "https://platform.claude.com/docs/en/agents-and-tools/tool-use/browser-use-tool", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/anthropic-tool-blocks.json" }, { "provider": "anthropic", "api_family": "messages", "name": "Computer use action schemas", "object": "computer.actions", "schema_name": null, "description": "Per-version action/member inputs.", "fields": { "computer_20250124": { "input.action": [ "key", "hold_key", "type", "cursor_position", "mouse_move", "left_mouse_down", "left_mouse_up", "left_click", "left_click_drag", "right_click", "middle_click", "double_click", "triple_click", "scroll", "wait", "screenshot" ], "params": { "screenshot": {}, "zoom": { "region": "[x0,y0,x1,y1]" }, "left_click": { "coordinate?": "[x,y]", "text?": "modifier keys shift|ctrl|alt|super joined with +" }, "right_click|middle_click|double_click|triple_click": "same as left_click", "left_click_drag": { "start_coordinate": "[x,y]", "coordinate": "[x,y]", "text?": "modifiers" }, "mouse_move": { "coordinate": "[x,y]" }, "left_mouse_down|left_mouse_up": {}, "cursor_position": {}, "scroll": { "scroll_direction": "up|down|left|right", "scroll_amount": "int clicks", "coordinate?": "[x,y]", "text?": "modifiers" }, "type": { "text": "string" }, "key": { "text": "key or chord e.g. Return, ctrl+s", "repeat?": "1-100 (toolset only)" }, "hold_key": { "text": "key", "duration": "seconds <=300" }, "wait": { "duration": "seconds <=300" } } }, "computer_20251124": { "input.action": [ "key", "hold_key", "type", "cursor_position", "mouse_move", "left_mouse_down", "left_mouse_up", "left_click", "left_click_drag", "right_click", "middle_click", "double_click", "triple_click", "scroll", "wait", "screenshot", "zoom (when enable_zoom:true)" ], "params": { "screenshot": {}, "zoom": { "region": "[x0,y0,x1,y1]" }, "left_click": { "coordinate?": "[x,y]", "text?": "modifier keys shift|ctrl|alt|super joined with +" }, "right_click|middle_click|double_click|triple_click": "same as left_click", "left_click_drag": { "start_coordinate": "[x,y]", "coordinate": "[x,y]", "text?": "modifiers" }, "mouse_move": { "coordinate": "[x,y]" }, "left_mouse_down|left_mouse_up": {}, "cursor_position": {}, "scroll": { "scroll_direction": "up|down|left|right", "scroll_amount": "int clicks", "coordinate?": "[x,y]", "text?": "modifiers" }, "type": { "text": "string" }, "key": { "text": "key or chord e.g. Return, ctrl+s", "repeat?": "1-100 (toolset only)" }, "hold_key": { "text": "key", "duration": "seconds <=300" }, "wait": { "duration": "seconds <=300" } } }, "computer_toolset_20260801": { "member tool names": [ "screenshot", "zoom", "left_click", "right_click", "middle_click", "double_click", "triple_click", "left_click_drag", "mouse_move", "left_mouse_down", "left_mouse_up", "cursor_position", "scroll", "type", "key", "hold_key", "wait" ], "params": { "screenshot": {}, "zoom": { "region": "[x0,y0,x1,y1]" }, "left_click": { "coordinate?": "[x,y]", "text?": "modifier keys shift|ctrl|alt|super joined with +" }, "right_click|middle_click|double_click|triple_click": "same as left_click", "left_click_drag": { "start_coordinate": "[x,y]", "coordinate": "[x,y]", "text?": "modifiers" }, "mouse_move": { "coordinate": "[x,y]" }, "left_mouse_down|left_mouse_up": {}, "cursor_position": {}, "scroll": { "scroll_direction": "up|down|left|right", "scroll_amount": "int clicks", "coordinate?": "[x,y]", "text?": "modifiers" }, "type": { "text": "string" }, "key": { "text": "key or chord e.g. Return, ctrl+s", "repeat?": "1-100 (toolset only)" }, "hold_key": { "text": "key", "duration": "seconds <=300" }, "wait": { "duration": "seconds <=300" } }, "key.repeat": "1-100" } }, "status": [ "DOCUMENTED", "LIVE_VERIFIED" ], "example": { "type": "tool_use", "id": "toolu_01Ppr3sZ3TnE9m6VUu4RyH2K", "name": "type", "toolset_name": "computer", "input": { "text": "pictures of cats" } }, "example_source": "docs", "sources": [ { "url": "https://platform.claude.com/docs/en/agents-and-tools/tool-use/computer-use-tool", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/anthropic-tool-blocks.json" }, { "provider": "anthropic", "api_family": "messages", "name": "Streaming: input_json_delta", "object": "input_json_delta", "schema_name": null, "description": "content_block_delta payload carrying partial JSON of tool_use/server_tool_use/mcp_tool_use input.", "fields": { "type": "input_json_delta", "partial_json": "string fragment (first is often \"\")" }, "status": [ "DOCUMENTED", "LIVE_VERIFIED" ], "example": { "type": "content_block_delta", "index": 0, "delta": { "type": "input_json_delta", "partial_json": "{\"locat" } }, "example_source": "live b1", "sources": [ { "url": "https://platform.claude.com/docs/en/build-with-claude/streaming", "retrieved_at": "2026-09-18" }, { "url": "https://platform.claude.com/docs/en/agents-and-tools/tool-use/fine-grained-tool-streaming", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/anthropic-tool-blocks.json" }, { "provider": "gemini", "object": "GenerateContentResponse", "kind": "response", "description": "Response of generateContent (and each stream chunk).", "fields": { "candidates": "Candidate[] (absent when the prompt is blocked)", "promptFeedback": "PromptFeedback (only when the prompt was filtered)", "usageMetadata": "UsageMetadata", "modelVersion": "string (resolved model id, e.g. gemini-3.5-flash-lite — note models.get.version is '3.5-flash-lite-07-2026')", "responseId": "string (opaque, e.g. ZgWuapkcpuD-4w_B5sz4CQ)", "modelStatus": "ModelStatus {modelStage, retirementTime, message} (output only; not observed)" }, "status": [ "DOCUMENTED", "LIVE_VERIFIED" ], "example": { "candidates": [ { "content": { "parts": [ { "text": "OK", "thoughtSignature": "El4KXAFpFH0Tz0tl…" } ], "role": "model" }, "finishReason": "STOP", "index": 0 } ], "usageMetadata": { "promptTokenCount": 5, "candidatesTokenCount": 1, "totalTokenCount": 6, "promptTokensDetails": [ { "modality": "TEXT", "tokenCount": 5 } ], "serviceTier": "standard" }, "modelVersion": "gemini-3.5-flash-lite", "responseId": "ZgWuapkcpuD-4w_B5sz4CQ" }, "source": "https://ai.google.dev/api/generate-content", "_fragment": "generated/fragments/objects/gemini-core-objects.json" }, { "provider": "gemini", "object": "Candidate", "kind": "response", "description": "One generated answer.", "fields": { "content": "Content (role 'model')", "finishReason": "FinishReason enum — see FinishReason", "finishMessage": "string (details, only with finishReason)", "index": "integer", "safetyRatings": "SafetyRating[] (only when safetySettings were sent or content was flagged)", "citationMetadata": "CitationMetadata (recitation of training data)", "groundingMetadata": "GroundingMetadata (tools domain)", "urlContextMetadata": "UrlContextMetadata {urlMetadata[{retrievedUrl, urlRetrievalStatus}]} (tools domain)", "logprobsResult": "LogprobsResult (responseLogprobs=true)", "avgLogprobs": "number", "tokenCount": "integer (output only)", "groundingAttributions": "GroundingAttribution[] (generateAnswer only)" }, "status": [ "DOCUMENTED", "LIVE_VERIFIED" ], "example": { "content": { "parts": [ { "text": "OK.", "thoughtSignature": "…" } ], "role": "model" }, "finishReason": "STOP", "index": 0, "safetyRatings": [ { "category": "HARM_CATEGORY_HARASSMENT", "probability": "NEGLIGIBLE" }, { "category": "HARM_CATEGORY_HATE_SPEECH", "probability": "NEGLIGIBLE" }, { "category": "HARM_CATEGORY_SEXUALLY_EXPLICIT", "probability": "NEGLIGIBLE" }, { "category": "HARM_CATEGORY_DANGEROUS_CONTENT", "probability": "NEGLIGIBLE" } ] }, "source": "https://ai.google.dev/api/generate-content", "_fragment": "generated/fragments/objects/gemini-core-objects.json" }, { "provider": "gemini", "object": "FinishReason", "kind": "enum", "description": "Why generation stopped (discovery rev. 20260918).", "fields": { "STOP": "natural stop or stop sequence (observed)", "MAX_TOKENS": "maxOutputTokens reached incl. thinking (observed)", "SAFETY": "candidate flagged; inspect safetyRatings", "RECITATION": "recitation of copyrighted material", "LANGUAGE": "unsupported language", "OTHER": "unknown", "BLOCKLIST": "forbidden terms", "PROHIBITED_CONTENT": "prohibited content", "SPII": "sensitive PII", "MALFORMED_FUNCTION_CALL": "invalid function call", "IMAGE_SAFETY": "generated image unsafe", "IMAGE_PROHIBITED_CONTENT": "generated image prohibited", "IMAGE_OTHER": "image generation misc", "NO_IMAGE": "image expected but none generated", "IMAGE_RECITATION": "image recitation", "UNEXPECTED_TOOL_CALL": "tool call without tools enabled", "TOO_MANY_TOOL_CALLS": "consecutive tool-call limit", "MISSING_THOUGHT_SIGNATURE": "a required thought signature is missing", "MALFORMED_RESPONSE": "malformed response", "ESCALATION": "filtered by an escalation rule", "PUP_LIMITED_DISABLED": "account limited/disabled for Prohibited Use Policy violations" }, "status": [ "DOCUMENTED", "LIVE_VERIFIED" ], "example": "STOP", "source": "https://generativelanguage.googleapis.com/$discovery/rest?version=v1beta", "_fragment": "generated/fragments/objects/gemini-core-objects.json" }, { "provider": "gemini", "object": "Content", "kind": "request+response", "description": "A turn: role + ordered parts.", "fields": { "role": "'user' | 'model' (optional on single-turn input)", "parts": "Part[]" }, "status": [ "DOCUMENTED", "LIVE_VERIFIED" ], "example": { "role": "user", "parts": [ { "text": "Reply with OK." } ] }, "source": "https://ai.google.dev/api/generate-content", "_fragment": "generated/fragments/objects/gemini-core-objects.json" }, { "provider": "gemini", "object": "Part", "kind": "request+response", "description": "Union of exactly one data field plus metadata.", "fields": { "text": "string", "inlineData": "Blob {mimeType, data(base64), displayName}", "fileData": "FileData {fileUri, mimeType, displayName}", "functionCall": "{name, args{}, id}", "functionResponse": "{name, response{}, id, parts[], scheduling, willContinue}", "executableCode": "{language: PYTHON, code, id}", "codeExecutionResult": "{outcome, output, id}", "toolCall / toolResponse": "server-side tool invocation echo (discovery)", "thought": "boolean (thought summary part)", "thoughtSignature": "string base64 (output; echo back)", "videoMetadata": "{startOffset, endOffset, fps}", "mediaResolution": "{level: MEDIA_RESOLUTION_*}", "mediaProcessing": "STATIC | AGENTIC (video)", "partMetadata": "Struct", "audioTranscription": "{text, speakerLabel, words[]} (output, transcription models)" }, "status": [ "DOCUMENTED", "LIVE_VERIFIED" ], "example": [ { "text": "**My Calculation of a Multiplication Problem**\n\nOkay, so I'm looking at the multiplication 17 × 23 …", "thought": true }, { "text": "391", "thoughtSignature": "EvACCu0CAWkUfRPh1YMU…" } ], "source": "https://ai.google.dev/api/generate-content", "_fragment": "generated/fragments/objects/gemini-core-objects.json" }, { "provider": "gemini", "object": "Blob", "kind": "request", "description": "Inline media bytes.", "fields": { "mimeType": "string (IANA)", "data": "string base64", "displayName": "string" }, "status": [ "DOCUMENTED", "LIVE_VERIFIED" ], "example": { "mimeType": "image/png", "data": "iVBORw0KGgo…" }, "source": "https://ai.google.dev/gemini-api/docs/generate-content/file-input-methods", "_fragment": "generated/fragments/objects/gemini-core-objects.json" }, { "provider": "gemini", "object": "FileData", "kind": "request", "description": "URI-based media reference.", "fields": { "fileUri": "File.uri | YouTube URL | public https URL", "mimeType": "string (optional)", "displayName": "string" }, "status": [ "DOCUMENTED", "LIVE_VERIFIED" ], "example": { "fileUri": "https://generativelanguage.googleapis.com/v1beta/files/w7x6n2hlpxrq", "mimeType": "text/plain" }, "source": "https://ai.google.dev/gemini-api/docs/generate-content/file-input-methods", "_fragment": "generated/fragments/objects/gemini-core-objects.json" }, { "provider": "gemini", "object": "VideoMetadata", "kind": "request", "description": "Clipping / sampling for a video part (static mode).", "fields": { "startOffset": "Duration '40s'", "endOffset": "Duration '80s'", "fps": "number (0,24], default 1" }, "status": [ "DOCUMENTED", "LIVE_VERIFIED" ], "example": { "startOffset": "0s", "endOffset": "10s", "fps": 1 }, "source": "https://ai.google.dev/gemini-api/docs/generate-content/video-understanding", "_fragment": "generated/fragments/objects/gemini-core-objects.json" }, { "provider": "gemini", "object": "UsageMetadata", "kind": "response", "description": "Token accounting for the request (present in every stream chunk).", "fields": { "promptTokenCount": "int — includes cached tokens", "cachedContentTokenCount": "int — cached prefix (explicit or implicit cache hit)", "candidatesTokenCount": "int — output tokens (absent when only thoughts were produced)", "thoughtsTokenCount": "int — billed thinking tokens (thinking models)", "toolUsePromptTokenCount": "int — tokens of server-side tool prompts (search, agentic video loads)", "totalTokenCount": "int = prompt + thoughts + candidates (+ toolUse)", "promptTokensDetails": "ModalityTokenCount[] (TEXT, IMAGE, VIDEO, AUDIO, DOCUMENT)", "cacheTokensDetails": "ModalityTokenCount[]", "candidatesTokensDetails": "ModalityTokenCount[]", "toolUsePromptTokensDetails": "ModalityTokenCount[]", "serviceTier": "'standard' | 'flex' | 'priority' (observed 'standard' on every 200)", "trafficType": "SDK-only (Vertex)" }, "status": [ "DOCUMENTED", "LIVE_VERIFIED" ], "example": { "promptTokenCount": 16, "candidatesTokenCount": 3, "totalTokenCount": 136, "promptTokensDetails": [ { "modality": "TEXT", "tokenCount": 16 } ], "thoughtsTokenCount": 117, "serviceTier": "standard" }, "source": "https://ai.google.dev/api/generate-content", "_fragment": "generated/fragments/objects/gemini-core-objects.json" }, { "provider": "gemini", "object": "ModalityTokenCount", "kind": "response", "description": "Per-modality token count.", "fields": { "modality": "MODALITY_UNSPECIFIED | TEXT | IMAGE | VIDEO | AUDIO | DOCUMENT", "tokenCount": "int" }, "status": [ "DOCUMENTED", "LIVE_VERIFIED" ], "example": [ { "modality": "TEXT", "tokenCount": 4 }, { "modality": "VIDEO", "tokenCount": 10650 }, { "modality": "AUDIO", "tokenCount": 4777 } ], "source": "https://ai.google.dev/api/tokens", "_fragment": "generated/fragments/objects/gemini-core-objects.json" }, { "provider": "gemini", "object": "PromptFeedback", "kind": "response", "description": "Prompt-level filtering result (only when set).", "fields": { "blockReason": "SAFETY | OTHER | BLOCKLIST | PROHIBITED_CONTENT | IMAGE_SAFETY", "safetyRatings": "SafetyRating[]" }, "status": [ "DOCUMENTED", "UNVERIFIED" ], "example": { "blockReason": "SAFETY", "safetyRatings": [ { "category": "HARM_CATEGORY_DANGEROUS_CONTENT", "probability": "HIGH", "blocked": true } ] }, "source": "https://ai.google.dev/gemini-api/docs/safety-settings", "_fragment": "generated/fragments/objects/gemini-core-objects.json" }, { "provider": "gemini", "object": "SafetyRating", "kind": "response", "description": "Probability of harm per category.", "fields": { "category": "HarmCategory", "probability": "NEGLIGIBLE | LOW | MEDIUM | HIGH", "blocked": "boolean (only when true)" }, "status": [ "DOCUMENTED", "LIVE_VERIFIED" ], "example": { "category": "HARM_CATEGORY_HARASSMENT", "probability": "NEGLIGIBLE" }, "source": "https://ai.google.dev/gemini-api/docs/safety-settings", "_fragment": "generated/fragments/objects/gemini-core-objects.json" }, { "provider": "gemini", "object": "SafetySetting", "kind": "request", "description": "Threshold per category.", "fields": { "category": "HarmCategory (6 accepted values)", "threshold": "HarmBlockThreshold", "method": "SDK-only (Vertex: SEVERITY|PROBABILITY)" }, "status": [ "DOCUMENTED", "LIVE_VERIFIED" ], "example": { "category": "HARM_CATEGORY_HATE_SPEECH", "threshold": "BLOCK_LOW_AND_ABOVE" }, "source": "https://ai.google.dev/gemini-api/docs/safety-settings", "_fragment": "generated/fragments/objects/gemini-core-objects.json" }, { "provider": "gemini", "object": "CitationMetadata", "kind": "response", "description": "Recitation sources for candidate text.", "fields": { "citationSources": "[{startIndex (bytes), endIndex (exclusive), uri, license}]" }, "status": [ "DOCUMENTED", "UNVERIFIED" ], "example": { "citationSources": [ { "startIndex": 0, "endIndex": 120, "uri": "https://example.com", "license": "" } ] }, "source": "https://ai.google.dev/api/generate-content", "_fragment": "generated/fragments/objects/gemini-core-objects.json" }, { "provider": "gemini", "object": "GroundingMetadata", "kind": "response", "description": "Grounding info when search/maps/url tools ran (shape only — tools domain).", "fields": { "webSearchQueries": "string[]", "imageSearchQueries": "string[]", "groundingChunks": "[{web{uri,title} | retrievedContext | maps | image}]", "groundingSupports": "[{segment, groundingChunkIndices[], confidenceScores[], renderedParts[]}]", "searchEntryPoint": "{renderedContent, sdkBlob}", "retrievalMetadata": "{googleSearchDynamicRetrievalScore}", "googleMapsWidgetContextToken": "string" }, "status": [ "DOCUMENTED" ], "example": null, "source": "https://ai.google.dev/gemini-api/docs/google-search", "_fragment": "generated/fragments/objects/gemini-core-objects.json" }, { "provider": "gemini", "object": "LogprobsResult", "kind": "response", "description": "Log-probabilities (responseLogprobs=true).", "fields": { "chosenCandidates": "[{token, tokenId, logProbability}] per step", "topCandidates": "[{candidates:[{token, tokenId, logProbability}]}] per step (logprobs N)", "logProbabilitySum": "number" }, "status": [ "DOCUMENTED", "FAILED_VERIFICATION" ], "example": null, "source": "https://ai.google.dev/api/generate-content", "_fragment": "generated/fragments/objects/gemini-core-objects.json" }, { "provider": "gemini", "object": "CachedContent", "kind": "resource", "description": "Explicit context cache (beta).", "fields": { "name": "cachedContents/{id} (output)", "model": "models/{id}", "displayName": "string ≤128", "contents / systemInstruction / tools / toolConfig": "input-only, never returned", "createTime / updateTime": "RFC 3339", "expireTime": "RFC 3339 (always on output)", "ttl": "Duration (input only)", "usageMetadata": "{totalTokenCount}" }, "status": [ "DOCUMENTED", "BETA", "ACCOUNT_RESTRICTED" ], "example": null, "source": "https://ai.google.dev/api/caching", "_fragment": "generated/fragments/objects/gemini-core-objects.json" }, { "provider": "gemini", "object": "File", "kind": "resource", "description": "Uploaded, registered or generated file.", "fields": { "name": "files/{id}", "displayName": "string", "mimeType": "string", "sizeBytes": "int64 as string", "createTime / updateTime": "RFC 3339", "expirationTime": "RFC 3339 (= createTime + 48 h for uploads; absent for REGISTERED)", "sha256Hash": "base64 of the hex SHA-256 string", "uri": "https://generativelanguage.googleapis.com/v1beta/files/{id} (use in fileData.fileUri)", "downloadUri": "only for generated files", "state": "PROCESSING | ACTIVE | FAILED", "source": "UPLOADED | GENERATED | REGISTERED", "error": "Status (when FAILED)", "videoMetadata": "{videoDuration}" }, "status": [ "DOCUMENTED", "LIVE_VERIFIED" ], "example": { "name": "files/w7x6n2hlpxrq", "displayName": "atlas-probe.txt", "mimeType": "text/plain", "sizeBytes": "174", "createTime": "2026-09-19T03:46:49Z", "updateTime": "2026-09-19T03:46:49Z", "expirationTime": "2026-09-21T03:46:49.478571266Z", "sha256Hash": "ZmVhNTIx…", "uri": "https://generativelanguage.googleapis.com/v1beta/files/w7x6n2hlpxrq", "state": "ACTIVE", "source": "UPLOADED" }, "source": "https://ai.google.dev/api/files", "_fragment": "generated/fragments/objects/gemini-core-objects.json" }, { "provider": "gemini", "object": "EmbedContentResponse", "kind": "response", "description": "Single embedding.", "fields": { "embedding": "ContentEmbedding {values: float[]}", "usageMetadata": "EmbeddingUsageMetadata {promptTokenCount, promptTokenDetails[]} — returned by gemini-embedding-2 only (absent on gemini-embedding-001)" }, "status": [ "DOCUMENTED", "LIVE_VERIFIED" ], "example": { "embedding": { "values": [ "… 64 floats …" ] }, "usageMetadata": { "promptTokenCount": 8, "promptTokenDetails": [ { "modality": "TEXT", "tokenCount": 8 } ] } }, "source": "https://ai.google.dev/api/embeddings", "_fragment": "generated/fragments/objects/gemini-core-objects.json" }, { "provider": "gemini", "object": "BatchEmbedContentsResponse", "kind": "response", "description": "Ordered embeddings for batchEmbedContents.", "fields": { "embeddings": "ContentEmbedding[]", "usageMetadata": "EmbeddingUsageMetadata (embedding-2)" }, "status": [ "DOCUMENTED", "LIVE_VERIFIED" ], "example": { "embeddings": [ { "values": [ "… 64 floats …" ] }, { "values": [ "… 64 floats …" ] } ] }, "source": "https://ai.google.dev/api/embeddings", "_fragment": "generated/fragments/objects/gemini-core-objects.json" }, { "provider": "gemini", "object": "EmbedContentBatch", "kind": "resource", "description": "Async embedding batch (asyncBatchEmbedContent → Operation.response).", "fields": { "name": "batches/{id}", "displayName": "string", "model": "models/{id}", "state": "BATCH_STATE_PENDING|RUNNING|SUCCEEDED|FAILED|CANCELLED|EXPIRED", "inputConfig": "{requests{requests[]} | fileName}", "output": "{responsesFile | inlinedResponses{inlinedResponses[{response, metadata, error}]}}", "batchStats": "{requestCount, successfulRequestCount, failedRequestCount, pendingRequestCount}", "priority": "int64", "createTime/updateTime/endTime": "RFC 3339" }, "status": [ "DOCUMENTED", "ACCOUNT_RESTRICTED" ], "example": null, "source": "https://ai.google.dev/api/embeddings", "_fragment": "generated/fragments/objects/gemini-core-objects.json" }, { "provider": "gemini", "object": "CountTokensResponse", "kind": "response", "description": "Token count of the input only.", "fields": { "totalTokens": "int", "promptTokensDetails": "ModalityTokenCount[]", "cachedContentTokenCount": "int (with cachedContent)", "cacheTokensDetails": "ModalityTokenCount[]" }, "status": [ "DOCUMENTED", "LIVE_VERIFIED" ], "example": { "totalTokens": 1092, "promptTokensDetails": [ { "modality": "TEXT", "tokenCount": 3 }, { "modality": "IMAGE", "tokenCount": 1089 } ] }, "source": "https://ai.google.dev/api/tokens", "_fragment": "generated/fragments/objects/gemini-core-objects.json" }, { "provider": "gemini", "object": "GeneratedFile", "kind": "resource", "description": "Model-generated file.", "fields": { "name": "generatedFiles/{id}", "mimeType": "string", "state": "GENERATING | GENERATED | FAILED", "error": "Status" }, "status": [ "DOCUMENTED", "UNVERIFIED" ], "example": null, "source": "https://generativelanguage.googleapis.com/$discovery/rest?version=v1beta", "_fragment": "generated/fragments/objects/gemini-core-objects.json" }, { "provider": "gemini", "object": "Operation", "api_family": "operations", "description": "google.longrunning.Operation returned by predictLongRunning, batchGenerateContent, asyncBatchEmbedContent, tunedModels.create. done=false while running; when done exactly one of error/response is set.", "fields": { "name": "string (models/{m}/operations/{id} | batches/{id} | tunedModels/{id}/operations/{id})", "metadata": "object with @type (Veo: none/progress; batch: GenerateContentBatch|EmbedContentBatch; tuning: CreateTunedModelMetadata)", "done": "boolean", "error": "Status {code, message, details[]}", "response": "object with @type (GenerateVideoResponse | batch output | TunedModel)" }, "status": [ "DOCUMENTED", "ACCOUNT_RESTRICTED" ], "example": { "error": { "code": 400, "message": "Precondition check failed.", "status": "FAILED_PRECONDITION" } }, "notes": "Live example: Operation returned by batchGenerateContent (metadata = GenerateContentBatch).", "sources": [ { "url": "https://ai.google.dev/api/batch-api", "retrieved_at": "2026-09-18" }, { "url": "https://generativelanguage.googleapis.com/$discovery/rest?version=v1beta", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/gemini-media-objects.json" }, { "provider": "gemini", "object": "Model", "kind": "resource", "description": "models.get result — source of per-model defaults used by generationConfig.", "fields": { "name": "models/{id}", "version": "string", "displayName / description": "string", "inputTokenLimit / outputTokenLimit": "int", "supportedGenerationMethods": "string[]", "temperature / maxTemperature / topP / topK": "defaults (topK absent ⇒ topK not allowed)", "thinking": "boolean" }, "status": [ "DOCUMENTED", "LIVE_VERIFIED" ], "example": { "name": "models/gemini-3.5-flash-lite", "version": "3.5-flash-lite-07-2026", "displayName": "Gemini 3.5 Flash Lite", "inputTokenLimit": 1048576, "outputTokenLimit": 65536, "supportedGenerationMethods": [ "generateContent", "countTokens", "createCachedContent", "batchGenerateContent" ], "temperature": 1, "topP": 0.95, "topK": 64, "maxTemperature": 2, "thinking": true }, "source": "https://ai.google.dev/api/models", "_fragment": "generated/fragments/objects/gemini-core-objects.json" }, { "provider": "gemini", "object": "ErrorEnvelope", "kind": "error", "description": "All errors: HTTP status + {error:{code, message, status, details[]}}. `status` is the google.rpc.Code name; details may include google.rpc.BadRequest fieldViolations, google.rpc.Help links, google.rpc.QuotaFailure violations and google.rpc.RetryInfo retryDelay.", "fields": { "error.code": "int = HTTP status", "error.message": "string (often starts with '* GenerateContentRequest.: …' for validation errors)", "error.status": "INVALID_ARGUMENT | NOT_FOUND | PERMISSION_DENIED | RESOURCE_EXHAUSTED | FAILED_PRECONDITION | UNIMPLEMENTED | …", "error.details": "[{@type, …}]" }, "status": [ "DOCUMENTED", "LIVE_VERIFIED" ], "example": { "error": { "code": 429, "message": "You exceeded your current quota, please check your plan and billing details. … * Quota exceeded for metric: generativelanguage.googleapis.com/generate_content_free_tier_requests, limit: 15, model: gemini-3.5-flash-lite Please retry in 4.953207913s.", "status": "RESOURCE_EXHAUSTED", "details": [ { "@type": "type.googleapis.com/google.rpc.Help", "links": [ { "description": "Learn more about Gemini API quotas", "url": "https://ai.google.dev/gemini-api/docs/rate-limits" } ] }, { "@type": "type.googleapis.com/google.rpc.QuotaFailure", "violations": [ { "quotaMetric": "generativelanguage.googleapis.com/generate_content_free_tier_requests", "quotaId": "GenerateRequestsPerMinutePerProjectPerModel-FreeTier", "quotaDimensions": { "location": "global", "model": "gemini-3.5-flash-lite" }, "quotaValue": "15" } ] }, { "@type": "type.googleapis.com/google.rpc.RetryInfo", "retryDelay": "4s" } ] } }, "source": "https://ai.google.dev/gemini-api/docs/troubleshooting", "_fragment": "generated/fragments/objects/gemini-core-objects.json" }, { "provider": "gemini", "object": "GenerateAnswerResponse", "kind": "response", "description": "AQA (models/aqa:generateAnswer) result.", "fields": { "answer": "Candidate (+ groundingAttributions[{content, sourceId:{groundingPassage:{passageId}}}])", "answerableProbability": "float 0–1", "inputFeedback": "{safetyRatings[], blockReason}" }, "status": [ "LEGACY", "DOCUMENTED", "LIVE_VERIFIED" ], "example": { "answer": { "content": { "parts": [ { "text": "The sky is blue on a clear day." } ] }, "finishReason": "STOP", "groundingAttributions": [ { "sourceId": { "groundingPassage": { "passageId": "p1" } } } ] }, "answerableProbability": 0.999992 }, "source": "https://ai.google.dev/api/all-methods", "_fragment": "generated/fragments/objects/gemini-core-objects.json" }, { "provider": "gemini", "object": "GenerateContentResponse (image part)", "api_family": "image-generation", "description": "Response of a native image generation call: candidates[0].content.parts[] mixes text parts and inlineData image parts; usageMetadata reports image output tokens (1120 for 1K on 3.1 models, 1290 on 2.5-flash-image, 2000 for 4K on 3-pro).", "fields": { "candidates[].content.parts[].text": "string (optional narration)", "candidates[].content.parts[].inlineData.mimeType": "image/png (observed) | image/jpeg", "candidates[].content.parts[].inlineData.data": "base64", "candidates[].content.parts[].thought": "bool (thought images on Gemini 3, not charged)", "candidates[].finishReason": "STOP | IMAGE_SAFETY | …", "usageMetadata.promptTokenCount": "int", "usageMetadata.candidatesTokenCount": "int (image tokens)", "usageMetadata.candidatesTokensDetails[]": "{modality: IMAGE|TEXT, tokenCount}", "usageMetadata.thoughtsTokenCount": "int" }, "status": [ "DOCUMENTED", "ACCOUNT_RESTRICTED" ], "example": { "error": { "code": 429, "message": "You exceeded your current quota, please check your plan and billing details. For more information on this error, head to: https://ai.google.dev/gemini-api/docs/rate-limits. To monitor your current usage, head to: https://ai.dev/rate-limit. \n* Quota exceeded for metric: generativelanguage.googleapis.com/generate_content_free_tier_input_token_count, limit: 0, model: gemini-3.1-flash-lite-image\n* Quota exceeded for metric: generativelanguage.googleapis.com/generate_content_free_tier_requests, limit: 0, model: gemini-3.1-flash-lite-image\n* Quota exceeded for metric: generativelanguage.googleapis.com/generate_content_free_tier_requests, limit: 0, model: gemini-3.1-flash-lite-image\nPlease retry in 40.808490523s.", "status": "RESOURCE_EXHAUSTED", "details": [ { "@type": "type.googleapis.com/google.rpc.Help", "links": [ { "description": "Learn more about Gemini API quotas", "url": "https://ai.google.dev/gemini-api/docs/rate-limits" } ] }, { "@type": "type.googleapis.com/google.rpc.QuotaFailure", "violations": [ { "quotaMetric": "generativelanguage.googleapis.com/generate_content_free_tier_input_token_count", "quotaId": "GenerateContentInputTokensPerModelPerMinute-FreeTier", "quotaDimensions": { "location": "global", "model": "gemini-3.1-flash-lite-image" } }, { "quotaMetric": "generativelanguage.googleapis.com/generate_content_free_tier_requests", "quotaId": "GenerateRequestsPerMinutePerProjectPerModel-FreeTier", "quotaDimensions": { "location": "global", "model": "gemini-3.1-flash-lite-image" } }, { "quotaMetric": "generativelanguage.googleapis.com/generate_content_free_tier_requests", "quotaId": "GenerateRequestsPerDayPerProjectPerModel-FreeTier", "quotaDimensions": { "location": "global", "model": "gemini-3.1-flash-lite-image" } } ] }, { "@type": "type.googleapis.com/google.rpc.RetryInfo", "retryDelay": "40s" } ] } }, "notes": "Not obtainable with this key: HTTP 429 RESOURCE_EXHAUSTED: You exceeded your current quota, please check your plan and billing details. For more information on this error, head to: https://ai.google.dev/gemini-api/docs/rate-limits. To monitor your current usage, head to: https://ai.dev/rate-limit. \n* Quota exceeded for metric: generativelanguage.googleapis. (also gemini-2.5-flash-image -> HTTP 429). Field list from the image-generation guide and GenerateContentResponse reference; token counts from the guide's aspect-ratio tables.", "sources": [ { "url": "https://ai.google.dev/gemini-api/docs/image-generation", "retrieved_at": "2026-09-18" }, { "url": "https://ai.google.dev/api/generate-content", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/gemini-media-objects.json" }, { "provider": "gemini", "object": "PredictRequest / PredictResponse", "api_family": "image-generation", "description": "Generic prediction envelope used by Imagen (retired) and predictLongRunning (Veo).", "fields": { "instances[]": "any[] (required)", "parameters": "any", "labels": "map", "predictions[] (response)": "any[]" }, "status": [ "DOCUMENTED", "LEGACY" ], "example": null, "notes": null, "sources": [ { "url": "https://generativelanguage.googleapis.com/$discovery/rest?version=v1beta", "retrieved_at": "2026-09-18" }, { "url": "https://ai.google.dev/api/models", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/gemini-media-objects.json" }, { "provider": "gemini", "object": "Status (google.rpc.Status)", "api_family": "operations", "description": "Error model used in Operation.error, InlinedResponse.error, GeneratedFile.error and HTTP error bodies ({error:{code,message,status,details[]}}).", "fields": { "code": "int (google.rpc.Code; 1 = CANCELLED)", "message": "string", "details[]": "object[] with @type" }, "status": [ "DOCUMENTED", "LIVE_VERIFIED" ], "example": { "error": { "code": 403, "message": "You do not have permission to access the Operation with ID bogus-op or it may not exist.", "status": "PERMISSION_DENIED" } }, "notes": "Live example: GET bogus models/…/operations/… error body.", "sources": [ { "url": "https://ai.google.dev/api/files", "retrieved_at": "2026-09-18" }, { "url": "https://generativelanguage.googleapis.com/$discovery/rest?version=v1beta", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/gemini-media-objects.json" }, { "provider": "gemini", "object": "GenerateVideoResponse / GeneratedVideo (Veo operation response)", "api_family": "video-generation", "description": "Operation.response for Veo. REST shape: response.generateVideoResponse.generatedSamples[].video.uri; SDK GenerateVideosResponse: generated_videos[].video.{uri, video_bytes, mime_type}, rai_media_filtered_count, rai_media_filtered_reasons[].", "fields": { "response.@type": "type.googleapis.com/google.ai.generativelanguage.v1beta.PredictLongRunningResponse", "response.generateVideoResponse.generatedSamples[].video.uri": "https://generativelanguage.googleapis.com/v1beta/files/{id}:download?alt=media", "response.generateVideoResponse.raiMediaFilteredCount": "int", "response.generateVideoResponse.raiMediaFilteredReasons[]": "string[]", "video.mimeType": "video/mp4", "video (SDK)": "{uri, video_bytes, mime_type} — reusable as instances[].video for extension" }, "status": [ "DOCUMENTED", "UNVERIFIED" ], "example": { "name": "models/veo-3.1-generate-preview/operations/abc123", "done": true, "response": { "@type": "type.googleapis.com/google.ai.generativelanguage.v1beta.PredictLongRunningResponse", "generateVideoResponse": { "generatedSamples": [ { "video": { "uri": "https://generativelanguage.googleapis.com/v1beta/files/xyz:download?alt=media" } } ] } } }, "notes": "Example assembled from the Veo guide (jq path) and SDK types; not generated live (cost).", "sources": [ { "url": "https://ai.google.dev/gemini-api/docs/veo", "retrieved_at": "2026-09-18" }, { "url": "https://github.com/googleapis/python-genai/blob/main/google/genai/types.py", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/gemini-media-objects.json" }, { "provider": "gemini", "object": "VideoGenerationReferenceImage / Image / Video (Veo inputs)", "api_family": "video-generation", "description": "Input objects for predictLongRunning instances.", "fields": { "Image": "{inlineData:{mimeType,data}} (docs) | SDK Image {image_bytes, mime_type, gcs_uri}", "Video": "{inlineData:{mimeType:'video/mp4',data}} | {uri} from a previous generation", "VideoGenerationReferenceImage": "{image: Image, referenceType: 'asset'|'style'}" }, "status": [ "DOCUMENTED" ], "example": null, "notes": null, "sources": [ { "url": "https://ai.google.dev/gemini-api/docs/veo", "retrieved_at": "2026-09-18" }, { "url": "https://github.com/googleapis/python-genai/blob/main/google/genai/types.py", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/gemini-media-objects.json" }, { "provider": "gemini", "object": "GeneratedFile / ListGeneratedFilesResponse", "api_family": "files", "description": "Files generated on behalf of the project (e.g. Veo outputs).", "fields": { "name": "generatedFiles/{id}", "state": "STATE_UNSPECIFIED | GENERATING | GENERATED | FAILED", "mimeType": "string", "error": "Status", "generatedFiles[] / nextPageToken (list)": "" }, "status": [ "DOCUMENTED", "LIVE_VERIFIED" ], "example": {}, "notes": "Live list result recorded (empty list expected when no videos were generated).", "sources": [ { "url": "https://generativelanguage.googleapis.com/$discovery/rest?version=v1beta", "retrieved_at": "2026-09-18" }, { "url": "https://ai.google.dev/api/all-methods", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/gemini-media-objects.json" }, { "provider": "gemini", "object": "GenerateContentResponse (music, Lyria 3)", "api_family": "music-generation", "description": "Lyria via generateContent: parts with text (lyrics / JSON song structure) and an audio inlineData part.", "fields": { "candidates[].content.parts[].text": "lyrics / structure", "candidates[].content.parts[].inlineData.mimeType": "audio/mpeg (MP3) — documented, not observed", "candidates[].content.parts[].inlineData.data": "base64 MP3 44.1 kHz stereo (30 s clip)", "usageMetadata": "token counts" }, "status": [ "DOCUMENTED", "PREVIEW", "ACCOUNT_RESTRICTED" ], "example": { "error": { "code": 429, "message": "You exceeded your current quota, please check your plan and billing details. For more information on this error, head to: https://ai.google.dev/gemini-api/docs/rate-limits. To monitor your current usage, head to: https://ai.dev/rate-limit. \n* Quota exceeded for metric: generativelanguage.googleapis.com/generate_content_free_tier_requests, limit: 0, model: lyria-3-clip\n* Quota exceeded for metric: generativelanguage.googleapis.com/generate_content_free_tier_requests, limit: 0, model: lyria-3-clip\n* Quota exceeded for metric: generativelanguage.googleapis.com/generate_content_free_tier_input_token_count, limit: 0, model: lyria-3-clip\nPlease retry in 34.145529939s.", "status": "RESOURCE_EXHAUSTED", "details": [ { "@type": "type.googleapis.com/google.rpc.Help", "links": [ { "description": "Learn more about Gemini API quotas", "url": "https://ai.google.dev/gemini-api/docs/rate-limits" } ] }, { "@type": "type.googleapis.com/google.rpc.QuotaFailure", "violations": [ { "quotaMetric": "generativelanguage.googleapis.com/generate_content_free_tier_requests", "quotaId": "GenerateRequestsPerDayPerProjectPerModel-FreeTier", "quotaDimensions": { "location": "global", "model": "lyria-3-clip" } }, { "quotaMetric": "generativelanguage.googleapis.com/generate_content_free_tier_requests", "quotaId": "GenerateRequestsPerMinutePerProjectPerModel-FreeTier", "quotaDimensions": { "model": "lyria-3-clip", "location": "global" } }, { "quotaMetric": "generativelanguage.googleapis.com/generate_content_free_tier_input_token_count", "quotaId": "GenerateContentInputTokensPerModelPerMinute-FreeTier", "quotaDimensions": { "location": "global", "model": "lyria-3-clip" } } ] }, { "@type": "type.googleapis.com/google.rpc.RetryInfo", "retryDelay": "34s" } ] } }, "notes": "Not obtainable with this key: lyria-3-clip-preview -> HTTP 429 RESOURCE_EXHAUSTED: You exceeded your current quota, please check your plan and billing details. For more information on this error, head to: https://ai.google.dev/gemini-api/docs/rate-limits. To monitor your current usage, head to: https:/; lyria-3.5 -> HTTP 429 (no free tier for Lyria 3). Shape from the music-generation guide.", "sources": [ { "url": "https://ai.google.dev/gemini-api/docs/music-generation", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/gemini-media-objects.json" }, { "provider": "gemini", "object": "LiveMusicClientMessage", "api_family": "music-generation", "description": "Client frame of the BidiGenerateMusic WebSocket (one of setup | clientContent | musicGenerationConfig | playbackControl).", "fields": { "setup.model": "string", "clientContent.weightedPrompts[]": "{text, weight}", "musicGenerationConfig": "LiveMusicGenerationConfig", "playbackControl": "PLAY|PAUSE|STOP|RESET_CONTEXT" }, "status": [ "DOCUMENTED", "BETA" ], "example": null, "notes": null, "sources": [ { "url": "https://ai.google.dev/gemini-api/docs/realtime-music-generation", "retrieved_at": "2026-09-18" }, { "url": "https://github.com/googleapis/python-genai/blob/main/google/genai/types.py", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/gemini-media-objects.json" }, { "provider": "gemini", "object": "LiveMusicServerMessage", "api_family": "music-generation", "description": "Server frame: setupComplete | serverContent.audioChunks[] | filteredPrompt.", "fields": { "setupComplete": "{}", "serverContent.audioChunks[].data": "base64 raw PCM 16-bit 48 kHz stereo", "serverContent.audioChunks[].mimeType": "audio/l16;rate=48000;channels=2", "serverContent.audioChunks[].sourceMetadata": "{clientContent, musicGenerationConfig}", "filteredPrompt": "{text, filteredReason}" }, "status": [ "DOCUMENTED", "BETA", "LIVE_VERIFIED" ], "example": { "events": [ { "dir": "server", "keys": [ "setupComplete" ] }, { "dir": "server", "keys": [ "serverContent" ], "audioChunk": { "mimeType": "audio/l16;rate=48000;channels=2", "bytes": 384000, "sourceMetadata": { "clientContent": { "weightedPrompts": [ { "text": "minimal techno", "weight": 1 } ] }, "musicGenerationConfig": { "temperature": 1, "seed": 603898271, "bpm": 120 } }, "n_chunks_in_msg": 1 } }, { "dir": "server", "keys": [ "serverContent" ], "audioChunk": { "mimeType": "audio/l16;rate=48000;channels=2", "bytes": 384000, "sourceMetadata": { "clientContent": { "weightedPrompts": [ { "text": "minimal techno", "weight": 1 } ] }, "musicGenerationConfig": { "temperature": 1, "seed": 603898272, "bpm": 120 } }, "n_chunks_in_msg": 1 } } ] }, "notes": "Live event sequence recorded 2026-09-18 (2 audio chunks).", "sources": [ { "url": "https://ai.google.dev/gemini-api/docs/realtime-music-generation", "retrieved_at": "2026-09-18" }, { "url": "https://github.com/googleapis/python-genai/blob/main/google/genai/types.py", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/gemini-media-objects.json" }, { "provider": "gemini", "object": "GenerateContentResponse (TTS audio part)", "api_family": "speech-generation", "description": "TTS output: single inlineData part with raw PCM (16-bit LE mono 24 kHz; no WAV header — wrap it yourself). Streaming (3.1) delivers many small inlineData chunks (first 1920 bytes = 40 ms) then a final event with finishReason STOP and usage.", "fields": { "candidates[].content.parts[].inlineData.mimeType": "2.5 models: 'audio/L16;codec=pcm;rate=24000' | 3.1: 'audio/l16; rate=24000; channels=1'", "candidates[].content.parts[].inlineData.data": "base64 PCM", "candidates[].finishReason": "STOP | OTHER (observed once with no content for multi-speaker)", "usageMetadata.candidatesTokensDetails[]": "{modality: AUDIO, tokenCount} — ~25-32 tokens per second observed" }, "status": [ "DOCUMENTED", "PREVIEW", "LIVE_VERIFIED" ], "example": { "gemini-3.1-flash-tts-preview": { "candidates": [ { "content": { "parts": [ { "inlineData": { "mimeType": "audio/l16; rate=24000; channels=1", "data": "<46080 bytes>" } } ], "role": "model" }, "finishReason": "STOP", "index": 0 } ], "usageMetadata": { "promptTokenCount": 3, "candidatesTokenCount": 31, "totalTokenCount": 34, "promptTokensDetails": [ { "modality": "TEXT", "tokenCount": 3 } ], "candidatesTokensDetails": [ { "modality": "AUDIO", "tokenCount": 31 } ], "serviceTier": "standard" }, "modelVersion": "gemini-3.1-flash-tts-preview", "responseId": "nQeuapDTGrGZ_uMP7a_PwAo" }, "gemini-2.5-flash-preview-tts": { "candidates": [ { "content": { "parts": [ { "inlineData": { "mimeType": "audio/L16;codec=pcm;rate=24000", "data": "<38926 bytes, base64 len 51904>" } } ], "role": "model" }, "finishReason": "STOP", "index": 0 } ], "usageMetadata": { "promptTokenCount": 3, "candidatesTokenCount": 20, "totalTokenCount": 23, "promptTokensDetails": [ { "modality": "TEXT", "tokenCount": 3 } ], "candidatesTokensDetails": [ { "modality": "AUDIO", "tokenCount": 20 } ], "serviceTier": "standard" }, "modelVersion": "gemini-2.5-flash-preview-tts", "responseId": "jQWuauOMMvS11MkP9_Sx0Ak" }, "multi_speaker_empty_first_attempt": { "candidates": [ { "finishReason": "OTHER", "index": 0 } ], "usageMetadata": { "promptTokenCount": 19, "totalTokenCount": 19, "promptTokensDetails": [ { "modality": "TEXT", "tokenCount": 19 } ], "serviceTier": "standard" }, "modelVersion": "gemini-2.5-flash-preview-tts", "responseId": "ngeuaoDWO4TV_uMP5sD90AY" }, "sse_stream_summary": { "n_events": 26, "first": { "n_parts": 1, "mime": [ "audio/l16; rate=24000; channels=1" ], "bytes": [ 1920 ], "finishReason": null, "usage": { "promptTokenCount": 3, "candidatesTokenCount": 2, "totalTokenCount": 5, "promptTokensDetails": [ { "modality": "TEXT", "tokenCount": 3 } ], "candidatesTokensDetails": [ { "modality": "AUDIO", "tokenCount": 2 } ], "serviceTier": "standard" } }, "last": { "n_parts": 1, "mime": [ null ], "bytes": [], "finishReason": "STOP", "usage": { "promptTokenCount": 3, "candidatesTokenCount": 50, "totalTokenCount": 53, "promptTokensDetails": [ { "modality": "TEXT", "tokenCount": 3 } ], "candidatesTokensDetails": [ { "modality": "AUDIO", "tokenCount": 50 } ], "serviceTier": "standard" } } } }, "notes": "Live examples 2026-09-18 'Say: OK' (base64 replaced by byte counts).", "sources": [ { "url": "https://ai.google.dev/gemini-api/docs/speech-generation", "retrieved_at": "2026-09-18" }, { "url": "https://ai.google.dev/api/generate-content", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/gemini-media-objects.json" }, { "provider": "gemini", "object": "SpeechConfig", "api_family": "speech-generation", "description": "generationConfig.speechConfig.", "fields": { "voiceConfig.prebuiltVoiceConfig.voiceName": "one of 30 voices", "multiSpeakerVoiceConfig.speakerVoiceConfigs[]": "{speaker, voiceConfig} (<= 2)", "languageCode": "BCP-47 (optional)" }, "status": [ "DOCUMENTED" ], "example": null, "notes": null, "sources": [ { "url": "https://ai.google.dev/api/generate-content", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/gemini-media-objects.json" }, { "provider": "gemini", "object": "ImageConfig", "api_family": "image-generation", "description": "generationConfig.imageConfig.", "fields": { "aspectRatio": "string (14 ratios)", "imageSize": "512 | 1K | 2K | 4K" }, "status": [ "DOCUMENTED" ], "example": null, "notes": null, "sources": [ { "url": "https://ai.google.dev/api/generate-content", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/gemini-media-objects.json" }, { "provider": "gemini", "object": "AudioTranscriptionConfig", "api_family": "transcription", "description": "generationConfig.audioTranscriptionConfig (discovery 20260918).", "fields": { "languageCodes[]": "BCP-47", "languageHints / languageAuto": "alternative language selection objects", "customVocabulary[] / adaptationPhrases[]": "bias terms", "mode": "VERBATIM | SMART", "diarization": "bool", "wordTimestamp": "bool" }, "status": [ "DOCUMENTED", "LIVE_DISCOVERED" ], "example": null, "notes": null, "sources": [ { "url": "https://generativelanguage.googleapis.com/$discovery/rest?version=v1beta", "retrieved_at": "2026-09-18" }, { "url": "https://ai.google.dev/api/generate-content", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/gemini-media-objects.json" }, { "provider": "gemini", "object": "GenerateContentResponse (transcription)", "api_family": "transcription", "description": "gemini-3.5-transcribe output via generateContent. LIVE_DISCOVERED: the transcript comes in a part field `audioTranscription` {text, speakerLabel, words[]} (not in the generate-content reference); with diarization/timestamps a plain `text` part field is also present. The Interactions API instead returns word_info annotations {text, speaker, start_offset, end_offset}.", "fields": { "candidates[].content.parts[].audioTranscription.text": "transcript string", "candidates[].content.parts[].audioTranscription.speakerLabel": "'spk:0' … (diarization on)", "candidates[].content.parts[].audioTranscription.words[]": "{word, startOffset '0.200s', endOffset '0.500s'} (wordTimestamp on)", "candidates[].content.parts[].text": "transcript (present when diarization/timestamps on)", "candidates[].content": "{} (empty) when the audio contains no speech", "usageMetadata.promptTokensDetails[]": "{modality: AUDIO, tokenCount} — ~25 tokens/s (0.8 s -> 21, 0.5 s -> 13)" }, "status": [ "DOCUMENTED", "LIVE_DISCOVERED", "LIVE_VERIFIED" ], "example": { "speech": { "candidates": [ { "content": { "parts": [ { "audioTranscription": { "text": "Okay." } } ], "role": "model" }, "finishReason": "STOP", "index": 0 } ], "usageMetadata": { "promptTokenCount": 21, "totalTokenCount": 21, "promptTokensDetails": [ { "modality": "AUDIO", "tokenCount": 21 } ], "serviceTier": "standard" }, "modelVersion": "gemini-3.5-transcribe", "responseId": "tweuatuLCdWb9MoP4f3G4Ao" }, "diarization_timestamps": { "candidates": [ { "content": { "parts": [ { "text": "Okay.", "audioTranscription": { "text": "Okay.", "speakerLabel": "spk:0", "words": [ { "word": "Okay.", "startOffset": "0.200s", "endOffset": "0.500s" } ] } } ], "role": "model" }, "finishReason": "STOP", "index": 0 } ], "usageMetadata": { "promptTokenCount": 21, "totalTokenCount": 21, "promptTokensDetails": [ { "modality": "AUDIO", "tokenCount": 21 } ], "serviceTier": "standard" }, "modelVersion": "gemini-3.5-transcribe", "responseId": "uQeuauDKBNSo9MoPguPVuQI" }, "silence": { "candidates": [ { "content": {}, "finishReason": "STOP", "index": 0 } ], "usageMetadata": { "promptTokenCount": 13, "totalTokenCount": 13, "promptTokensDetails": [ { "modality": "AUDIO", "tokenCount": 13 } ], "serviceTier": "standard" }, "modelVersion": "gemini-3.5-transcribe", "responseId": "jwWuarWgFe2c_uMPnpfUyAk" } }, "notes": "Live examples 2026-09-18 (input = 0.8 s TTS 'OK' WAV and 0.5 s silence).", "sources": [ { "url": "https://ai.google.dev/gemini-api/docs/transcribe", "retrieved_at": "2026-09-18" }, { "url": "https://ai.google.dev/api/generate-content", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/gemini-media-objects.json" }, { "provider": "gemini", "object": "GenerateContentBatch", "api_family": "batch", "description": "Batch resource (Operation.metadata / update body).", "fields": { "model": "models/{m}", "name": "batches/{id} [RO]", "displayName": "string (required)", "inputConfig": "{fileName} | {requests:{requests:[InlinedRequest]}}", "output": "GenerateContentBatchOutput [RO]", "createTime/updateTime/endTime": "RFC 3339 [RO]", "batchStats": "BatchStats [RO]", "state": "BatchState [RO]", "priority": "int64 string", "webhookConfig.uris[]": "string[]" }, "status": [ "DOCUMENTED", "ACCOUNT_RESTRICTED" ], "example": null, "notes": null, "sources": [ { "url": "https://ai.google.dev/api/batch-api", "retrieved_at": "2026-09-18" }, { "url": "https://generativelanguage.googleapis.com/$discovery/rest?version=v1beta", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/gemini-media-objects.json" }, { "provider": "gemini", "object": "BatchStats", "api_family": "batch", "description": "Counters on the batch.", "fields": { "requestCount": "int64 string", "successfulRequestCount": "int64 string", "failedRequestCount": "int64 string", "pendingRequestCount": "int64 string" }, "status": [ "DOCUMENTED" ], "example": null, "notes": null, "sources": [ { "url": "https://ai.google.dev/api/batch-api", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/gemini-media-objects.json" }, { "provider": "gemini", "object": "GenerateContentBatchOutput / InlinedResponse", "api_family": "batch", "description": "Operation.response when done: inlinedResponses (inline input) or responsesFile (file input).", "fields": { "@type": "type.googleapis.com/google.ai.generativelanguage.v1beta.GenerateContentBatchOutput", "inlinedResponses.inlinedResponses[].metadata": "echo of request metadata (key)", "inlinedResponses.inlinedResponses[].response": "GenerateContentResponse", "inlinedResponses.inlinedResponses[].error": "Status", "responsesFile": "files/{id} (JSONL, one GenerateContentResponse or status object per line, same order as input; download /download/v1beta/{file}:download?alt=media)" }, "status": [ "DOCUMENTED" ], "example": null, "notes": "Live final Operation of the 2-request inline batch (if it completed within 5 min).", "sources": [ { "url": "https://ai.google.dev/gemini-api/docs/batch-api", "retrieved_at": "2026-09-18" }, { "url": "https://ai.google.dev/api/batch-api", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/gemini-media-objects.json" }, { "provider": "gemini", "object": "EmbedContentBatch / EmbedContentBatchOutput", "api_family": "batch", "description": "Embedding batch resource and output (inlinedResponses[].response = EmbedContentResponse {embedding:{values[]}} or responsesFile).", "fields": { "inputConfig.requests.requests[].request": "EmbedContentRequest", "output.inlinedResponses.inlinedResponses[].response.embedding.values[]": "float[]", "batchStats": "EmbedContentBatchStats", "state": "BatchState" }, "status": [ "DOCUMENTED", "ACCOUNT_RESTRICTED" ], "example": { "error": { "code": 400, "message": "Precondition check failed.", "status": "FAILED_PRECONDITION" } }, "notes": null, "sources": [ { "url": "https://ai.google.dev/api/batch-api", "retrieved_at": "2026-09-18" }, { "url": "https://generativelanguage.googleapis.com/$discovery/rest?version=v1beta", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/gemini-media-objects.json" }, { "provider": "gemini", "object": "TunedModel", "api_family": "tuning", "description": "Tuned model resource.", "fields": { "name": "tunedModels/{id} [RO]", "displayName": "<= 40 chars", "description": "string", "state": "CREATING | ACTIVE | FAILED [RO]", "createTime/updateTime": "[RO]", "tuningTask": "TuningTask", "readerProjectNumbers[]": "int64[]", "baseModel | tunedModelSource": "source model (oneof)", "temperature/topP/topK": "defaults for generation" }, "status": [ "DOCUMENTED", "LEGACY" ], "example": null, "notes": null, "sources": [ { "url": "https://ai.google.dev/api/tuning", "retrieved_at": "2026-09-18" }, { "url": "https://generativelanguage.googleapis.com/$discovery/rest?version=v1beta", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/gemini-media-objects.json" }, { "provider": "gemini", "object": "TuningTask / TuningSnapshot / Dataset / Hyperparameters", "api_family": "tuning", "description": "Tuning job description and metrics.", "fields": { "tuningTask.startTime/completeTime": "[RO]", "tuningTask.snapshots[]": "{step, epoch, meanLoss, computeTime}", "tuningTask.trainingData.examples.examples[]": "{textInput, output}", "tuningTask.hyperparameters": "{learningRate | learningRateMultiplier, epochCount, batchSize}" }, "status": [ "DOCUMENTED", "LEGACY" ], "example": null, "notes": null, "sources": [ { "url": "https://ai.google.dev/api/tuning", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/gemini-media-objects.json" }, { "provider": "gemini", "object": "CreateTunedModelMetadata", "api_family": "tuning", "description": "Operation.metadata while tuning.", "fields": { "tunedModel": "tunedModels/{id}", "totalSteps": "int", "completedSteps": "int", "completedPercent": "float", "snapshots[]": "TuningSnapshot" }, "status": [ "DOCUMENTED", "LEGACY" ], "example": null, "notes": null, "sources": [ { "url": "https://ai.google.dev/api/tuning", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/gemini-media-objects.json" }, { "provider": "gemini", "object": "Permission", "api_family": "tuning", "description": "ACL entry on a tuned model (or corpus).", "fields": { "name": "tunedModels/{m}/permissions/{p} [RO]", "granteeType": "USER | GROUP | EVERYONE", "emailAddress": "string (not for EVERYONE)", "role": "OWNER | WRITER | READER" }, "status": [ "DOCUMENTED", "LEGACY" ], "example": null, "notes": null, "sources": [ { "url": "https://generativelanguage.googleapis.com/$discovery/rest?version=v1beta", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/gemini-media-objects.json" }, { "provider": "gemini", "api_family": "generate-content", "name": "Tool (tools[] item)", "object": "Tool", "schema_name": "Tool", "description": "One entry of `tools[]`. Each field enables one tool type; several may be set on one Tool or spread across the array. Exact keys (discovery rev. 20260918): functionDeclarations, googleSearchRetrieval, fileSearch, mcpServers, codeExecution, computerUse, googleMaps, urlContext, googleSearch.", "fields": [ { "name": "functionDeclarations", "type": "array", "required": false, "description": "Optional. A list of `FunctionDeclarations` available to the model that can be used for function calling. The model or system does not execute the function. Instead the defined function may be returned as a FunctionCall with arguments to the client side for execution. The model may decide to call a subset of these functions by populating FunctionCall in the response. The next conversation turn may contain a FunctionResponse with the Content.role \"function\" generation context for the next model turn." }, { "name": "googleSearchRetrieval", "type": "GoogleSearchRetrieval", "required": false, "description": "Optional. Retrieval tool that is powered by Google search. LEGACY (1.5/2.0 models)." }, { "name": "fileSearch", "type": "FileSearch", "required": false, "description": "Optional. FileSearch tool type. Tool to retrieve knowledge from Semantic Retrieval corpora." }, { "name": "mcpServers", "type": "array", "required": false, "description": "Optional. MCP Servers to connect to. Not covered by generateContent guides; UNVERIFIED on the Gemini Developer API." }, { "name": "codeExecution", "type": "CodeExecution", "required": false, "description": "Optional. Enables the model to execute code as part of generation." }, { "name": "computerUse", "type": "ComputerUse", "required": false, "description": "Optional. Tool to support the model interacting directly with the computer. If enabled, it automatically populates computer-use specific Function Declarations." }, { "name": "googleMaps", "type": "GoogleMaps", "required": false, "description": "Optional. Tool that allows grounding the model's response with geospatial context related to the user's query." }, { "name": "urlContext", "type": "UrlContext", "required": false, "description": "Optional. Tool to support URL context retrieval." }, { "name": "googleSearch", "type": "GoogleSearch", "required": false, "description": "Optional. GoogleSearch tool type. Tool to support Google Search in Model. Powered by Google." } ], "status": [ "DOCUMENTED" ], "example": { "functionDeclarations": [ { "name": "get_weather", "description": "...", "parameters": { "type": "object", "properties": { "city": { "type": "string" } }, "required": [ "city" ] } } ] }, "sources": [ { "url": "https://ai.google.dev/api/generate-content#Tool", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/gemini-tools-agents-objects.json" }, { "provider": "gemini", "api_family": "generate-content", "name": "FunctionDeclaration", "object": "FunctionDeclaration", "schema_name": "FunctionDeclaration", "description": "Structured representation of a function declaration as defined by the [OpenAPI 3.03 specification](https://spec.openapis.org/oas/v3.0.3). Included in this declaration are the function name and parameters. This FunctionDeclaration is a representation of a block of code that can be used as a `Tool` by the model and executed by the client.", "fields": [ { "name": "name", "type": "string", "required": true, "description": "Required. The name of the function. Must be a-z, A-Z, 0-9, or contain underscores, colons, dots, and dashes, with a maximum length of 128." }, { "name": "behavior", "type": "string", "required": false, "description": "Optional. Specifies the function Behavior. Currently only supported by the BidiGenerateContent method. Live API only; REST reference: defaults to BLOCKING.", "enum": [ "UNSPECIFIED", "BLOCKING", "NON_BLOCKING" ] }, { "name": "parameters", "type": "Schema", "required": false, "description": "Optional. Describes the parameters to this function. Reflects the Open API 3.03 Parameter Object string Key: the name of the parameter. Parameter names are case sensitive. Schema Value: the Schema defining the type used for the parameter." }, { "name": "responseJsonSchema", "type": "any", "required": false, "description": "Optional. Describes the output from this function in JSON Schema format. The value specified by the schema is the response value of the function. This field is mutually exclusive with `response`." }, { "name": "parametersJsonSchema", "type": "any", "required": false, "description": "Optional. Describes the parameters to the function in JSON Schema format. The schema must describe an object where the properties are the parameters to the function. For example: ``` { \"type\": \"object\", \"properties\": { \"name\": { \"type\": \"string\" }, \"age\": { \"type\": \"integer\" } }, \"additionalProperties\": false, \"required\": [\"name\", \"age\"], \"propertyOrdering\": [\"name\", \"age\"] } ``` This field is mutually exclusive with `parameters`." }, { "name": "response", "type": "Schema", "required": false, "description": "Optional. Describes the output from this function in JSON Schema format. Reflects the Open API 3.03 Response Object. The Schema defines the type used for the response value of the function." }, { "name": "description", "type": "string", "required": true, "description": "Required. A brief description of the function." } ], "status": [ "DOCUMENTED" ], "example": { "name": "get_weather", "description": "Gets the weather for a city.", "parametersJsonSchema": { "type": "object", "properties": { "city": { "type": "string" } }, "required": [ "city" ] } }, "sources": [ { "url": "https://ai.google.dev/api/generate-content#FunctionDeclaration", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/gemini-tools-agents-objects.json" }, { "provider": "gemini", "api_family": "generate-content", "name": "FunctionCallingConfig", "object": "FunctionCallingConfig", "schema_name": "FunctionCallingConfig", "description": "Configuration for specifying function calling behavior.", "fields": [ { "name": "allowedFunctionNames", "type": "array", "required": false, "description": "Optional. A set of function names that, when provided, limits the functions the model will call. This should only be set when the Mode is ANY or VALIDATED. Function names should match [FunctionDeclaration.name]. When set, model will predict a function call from only allowed function names." }, { "name": "mode", "type": "string", "required": false, "description": "Optional. Specifies the mode in which function calling should execute. If unspecified, the default value will be set to AUTO.", "enum": [ "MODE_UNSPECIFIED", "AUTO", "ANY", "NONE", "VALIDATED" ] } ], "status": [ "DOCUMENTED" ], "example": { "mode": "ANY", "allowedFunctionNames": [ "get_weather" ] }, "sources": [ { "url": "https://ai.google.dev/api/generate-content#FunctionCallingConfig", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/gemini-tools-agents-objects.json" }, { "provider": "gemini", "api_family": "generate-content", "name": "ToolConfig", "object": "ToolConfig", "schema_name": "ToolConfig", "description": "Request-level `toolConfig` shared by all tools: functionCallingConfig, retrievalConfig, includeServerSideToolInvocations (Gemini 3 tool context circulation).", "fields": [ { "name": "retrievalConfig", "type": "RetrievalConfig", "required": false, "description": "Optional. Retrieval config." }, { "name": "includeServerSideToolInvocations", "type": "boolean", "required": false, "description": "Optional. If true, the API response will include the server-side tool calls and responses within the `Content` message. This allows clients to observe the server's tool interactions." }, { "name": "functionCallingConfig", "type": "FunctionCallingConfig", "required": false, "description": "Optional. Function calling config." } ], "status": [ "DOCUMENTED" ], "example": { "functionCallingConfig": { "mode": "VALIDATED" }, "retrievalConfig": { "latLng": { "latitude": 45.5, "longitude": -73.56 }, "languageCode": "fr-CA" }, "includeServerSideToolInvocations": true }, "sources": [ { "url": "https://ai.google.dev/api/generate-content#ToolConfig", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/gemini-tools-agents-objects.json" }, { "provider": "gemini", "api_family": "generate-content", "name": "RetrievalConfig", "object": "RetrievalConfig", "schema_name": "RetrievalConfig", "description": "Retrieval config.", "fields": [ { "name": "languageCode", "type": "string", "required": false, "description": "Optional. The language code of the user. Language code for content. Use language tags defined by [BCP47](https://www.rfc-editor.org/rfc/bcp/bcp47.txt)." }, { "name": "latLng", "type": "LatLng", "required": false, "description": "Optional. The location of the user." } ], "status": [ "DOCUMENTED" ], "example": { "latLng": { "latitude": 40.758896, "longitude": -73.98513 }, "languageCode": "en-US" }, "sources": [ { "url": "https://ai.google.dev/api/generate-content#RetrievalConfig", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/gemini-tools-agents-objects.json" }, { "provider": "gemini", "api_family": "generate-content", "name": "LatLng", "object": "LatLng", "schema_name": "LatLng", "description": "An object that represents a latitude/longitude pair. This is expressed as a pair of doubles to represent degrees latitude and degrees longitude. Unless specified otherwise, this object must conform to the WGS84 standard. Values must be within normalized ranges.", "fields": [ { "name": "longitude", "type": "number", "required": false, "description": "The longitude in degrees. It must be in the range [-180.0, +180.0]." }, { "name": "latitude", "type": "number", "required": false, "description": "The latitude in degrees. It must be in the range [-90.0, +90.0]." } ], "status": [ "DOCUMENTED" ], "example": { "latitude": 40.758896, "longitude": -73.98513 }, "sources": [ { "url": "https://ai.google.dev/api/generate-content#LatLng", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/gemini-tools-agents-objects.json" }, { "provider": "gemini", "api_family": "generate-content", "name": "GoogleSearch", "object": "GoogleSearch", "schema_name": "GoogleSearch", "description": "GoogleSearch tool type. Tool to support Google Search in Model. Powered by Google.", "fields": [ { "name": "timeRangeFilter", "type": "Interval", "required": false, "description": "Optional. Filter search results to a specific time range. If customers set a start time, they must set an end time (and vice versa)." }, { "name": "searchTypes", "type": "SearchTypes", "required": false, "description": "Optional. The set of search types to enable. If not set, web search is enabled by default." } ], "status": [ "DOCUMENTED" ], "example": { "timeRangeFilter": { "startTime": "2026-01-01T00:00:00Z", "endTime": "2026-09-18T00:00:00Z" }, "searchTypes": { "webSearch": {}, "imageSearch": {} } }, "sources": [ { "url": "https://ai.google.dev/api/generate-content#GoogleSearch", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/gemini-tools-agents-objects.json" }, { "provider": "gemini", "api_family": "generate-content", "name": "Interval", "object": "Interval", "schema_name": "Interval", "description": "Represents a time interval, encoded as a Timestamp start (inclusive) and a Timestamp end (exclusive). The start must be less than or equal to the end. When the start equals the end, the interval is empty (matches no time). When both start and end are unspecified, the interval matches any time.", "fields": [ { "name": "startTime", "type": "string", "required": false, "description": "Optional. Inclusive start of the interval. If specified, a Timestamp matching this interval will have to be the same or after the start." }, { "name": "endTime", "type": "string", "required": false, "description": "Optional. Exclusive end of the interval. If specified, a Timestamp matching this interval will have to be before the end." } ], "status": [ "DOCUMENTED" ], "example": { "startTime": "2026-01-01T00:00:00Z", "endTime": "2026-09-18T00:00:00Z" }, "sources": [ { "url": "https://ai.google.dev/api/generate-content#Interval", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/gemini-tools-agents-objects.json" }, { "provider": "gemini", "api_family": "generate-content", "name": "SearchTypes", "object": "SearchTypes", "schema_name": "SearchTypes", "description": "Different types of search that can be enabled on the GoogleSearch tool.", "fields": [ { "name": "webSearch", "type": "WebSearch", "required": false, "description": "Optional. Enables web search. Only text results are returned." }, { "name": "imageSearch", "type": "ImageSearch", "required": false, "description": "Optional. Enables image search. Image bytes are returned." } ], "status": [ "DOCUMENTED" ], "example": { "webSearch": {}, "imageSearch": {} }, "sources": [ { "url": "https://ai.google.dev/api/generate-content#SearchTypes", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/gemini-tools-agents-objects.json" }, { "provider": "gemini", "api_family": "generate-content", "name": "WebSearch", "object": "WebSearch", "schema_name": "WebSearch", "description": "Empty marker object enabling text web search inside GoogleSearch.searchTypes.", "fields": [], "status": [ "DOCUMENTED" ], "example": {}, "sources": [ { "url": "https://ai.google.dev/api/generate-content#WebSearch", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/gemini-tools-agents-objects.json" }, { "provider": "gemini", "api_family": "generate-content", "name": "ImageSearch", "object": "ImageSearch", "schema_name": "ImageSearch", "description": "Empty marker object enabling image search inside GoogleSearch.searchTypes (image bytes returned; Nano Banana 2 image generation grounding). Real schema; not a top-level Tool key.", "fields": [], "status": [ "DOCUMENTED" ], "example": {}, "sources": [ { "url": "https://ai.google.dev/api/generate-content#ImageSearch", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/gemini-tools-agents-objects.json" }, { "provider": "gemini", "api_family": "generate-content", "name": "GoogleSearchRetrieval (legacy)", "object": "GoogleSearchRetrieval", "schema_name": "GoogleSearchRetrieval", "description": "Tool to retrieve public web data for grounding, powered by Google.", "fields": [ { "name": "dynamicRetrievalConfig", "type": "DynamicRetrievalConfig", "required": false, "description": "Specifies the dynamic retrieval configuration for the given source." } ], "status": [ "DOCUMENTED", "LEGACY", "DEPRECATED" ], "example": { "dynamicRetrievalConfig": { "mode": "MODE_DYNAMIC", "dynamicThreshold": 0.7 } }, "sources": [ { "url": "https://ai.google.dev/api/generate-content#GoogleSearchRetrieval", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/gemini-tools-agents-objects.json" }, { "provider": "gemini", "api_family": "generate-content", "name": "DynamicRetrievalConfig (legacy)", "object": "DynamicRetrievalConfig", "schema_name": "DynamicRetrievalConfig", "description": "Describes the options to customize dynamic retrieval.", "fields": [ { "name": "dynamicThreshold", "type": "number", "required": false, "description": "The threshold to be used in dynamic retrieval. If not set, a system default value is used." }, { "name": "mode", "type": "string", "required": false, "description": "The mode of the predictor to be used in dynamic retrieval.", "enum": [ "MODE_UNSPECIFIED", "MODE_DYNAMIC" ] } ], "status": [ "DOCUMENTED", "LEGACY", "DEPRECATED" ], "example": { "mode": "MODE_DYNAMIC", "dynamicThreshold": 0.7 }, "sources": [ { "url": "https://ai.google.dev/api/generate-content#DynamicRetrievalConfig", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/gemini-tools-agents-objects.json" }, { "provider": "gemini", "api_family": "generate-content", "name": "GoogleMaps", "object": "GoogleMaps", "schema_name": "GoogleMaps", "description": "The GoogleMaps Tool that provides geospatial context for the user's query.", "fields": [ { "name": "enableWidget", "type": "boolean", "required": false, "description": "Optional. Whether to return a widget context token in the GroundingMetadata of the response. Developers can use the widget context token to render a Google Maps widget with geospatial context related to the places that the model references in the response." } ], "status": [ "DOCUMENTED" ], "example": { "enableWidget": true }, "sources": [ { "url": "https://ai.google.dev/api/generate-content#GoogleMaps", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/gemini-tools-agents-objects.json" }, { "provider": "gemini", "api_family": "generate-content", "name": "UrlContext", "object": "UrlContext", "schema_name": "UrlContext", "description": "Empty object enabling URL context retrieval (up to 20 URLs from the prompt).", "fields": [], "status": [ "DOCUMENTED" ], "example": {}, "sources": [ { "url": "https://ai.google.dev/api/generate-content#UrlContext", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/gemini-tools-agents-objects.json" }, { "provider": "gemini", "api_family": "generate-content", "name": "CodeExecution", "object": "CodeExecution", "schema_name": "CodeExecution", "description": "Tool that executes code generated by the model, and automatically returns the result to the model. See also `ExecutableCode` and `CodeExecutionResult` which are only generated when using this tool.", "fields": [], "status": [ "DOCUMENTED" ], "example": {}, "sources": [ { "url": "https://ai.google.dev/api/generate-content#CodeExecution", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/gemini-tools-agents-objects.json" }, { "provider": "gemini", "api_family": "generate-content", "name": "ComputerUse", "object": "ComputerUse", "schema_name": "ComputerUse", "description": "Computer Use tool type.", "fields": [ { "name": "enablePromptInjectionDetection", "type": "boolean", "required": false, "description": "Optional. Whether enable the prompt injection detection check on computer-use request." }, { "name": "environment", "type": "string", "required": true, "description": "Required. The environment being operated.", "enum": [ "ENVIRONMENT_UNSPECIFIED", "ENVIRONMENT_BROWSER", "ENVIRONMENT_MOBILE", "ENVIRONMENT_DESKTOP" ] }, { "name": "disabledSafetyPolicies", "type": "array", "required": false, "description": "Optional. Disabled safety policies for computer use. Enum SafetyPolicy: FINANCIAL_TRANSACTIONS, SENSITIVE_DATA_MODIFICATION, COMMUNICATION_TOOL, ACCOUNT_CREATION, DATA_MODIFICATION, USER_CONSENT_MANAGEMENT, LEGAL_TERMS_AND_AGREEMENTS." }, { "name": "excludedPredefinedFunctions", "type": "array", "required": false, "description": "Optional. By default, predefined functions are included in the final model call. Some of them can be explicitly excluded from being automatically included. This can serve two purposes: 1. Using a more restricted / different action space. 2. Improving the definitions / instructions of predefined functions." } ], "status": [ "DOCUMENTED", "PREVIEW" ], "example": { "environment": "ENVIRONMENT_BROWSER", "excludedPredefinedFunctions": [ "drag_and_drop" ], "enablePromptInjectionDetection": true, "disabledSafetyPolicies": [ "DATA_MODIFICATION" ] }, "sources": [ { "url": "https://ai.google.dev/api/generate-content#ComputerUse", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/gemini-tools-agents-objects.json" }, { "provider": "gemini", "api_family": "generate-content", "name": "FileSearch", "object": "FileSearch", "schema_name": "FileSearch", "description": "The FileSearch tool that retrieves knowledge from Semantic Retrieval corpora. Files are imported to Semantic Retrieval corpora using the ImportFile API.", "fields": [ { "name": "fileSearchStoreNames", "type": "array", "required": true, "description": "Required. The names of the file_search_stores to retrieve from. Example: `fileSearchStores/my-file-search-store-123`" }, { "name": "topK", "type": "integer", "required": false, "description": "Optional. The number of semantic retrieval chunks to retrieve." }, { "name": "metadataFilter", "type": "string", "required": false, "description": "Optional. Metadata filter to apply to the semantic retrieval documents and chunks." } ], "status": [ "DOCUMENTED", "PREVIEW" ], "example": { "fileSearchStoreNames": [ "fileSearchStores/my-store-123a456b789c" ], "metadataFilter": "author = \"Robert Graves\"", "topK": 5 }, "sources": [ { "url": "https://ai.google.dev/api/generate-content#FileSearch", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/gemini-tools-agents-objects.json" }, { "provider": "gemini", "api_family": "generate-content", "name": "McpServer (server-side MCP, schema only)", "object": "McpServer", "schema_name": "McpServer", "description": "A MCPServer is a server that can be called by the model to perform actions. It is a server that implements the MCP protocol. Next ID: 7", "fields": [ { "name": "streamableHttpTransport", "type": "StreamableHttpTransport", "required": false, "description": "A transport that can stream HTTP requests and responses." }, { "name": "name", "type": "string", "required": false, "description": "The name of the MCPServer." } ], "status": [ "DOCUMENTED", "DOCUMENTATION_INCOMPLETE", "UNVERIFIED" ], "example": { "name": "weather", "streamableHttpTransport": { "url": "https://example.com/mcp", "headers": { "Authorization": "Bearer ..." }, "timeout": "30s" } }, "sources": [ { "url": "https://ai.google.dev/api/generate-content#McpServer", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/gemini-tools-agents-objects.json" }, { "provider": "gemini", "api_family": "generate-content", "name": "StreamableHttpTransport", "object": "StreamableHttpTransport", "schema_name": "StreamableHttpTransport", "description": "A transport that can stream HTTP requests and responses. Next ID: 6", "fields": [ { "name": "terminateOnClose", "type": "boolean", "required": false, "description": "Whether to close the client session when the transport closes." }, { "name": "sseReadTimeout", "type": "string", "required": false, "description": "Timeout for SSE read operations." }, { "name": "headers", "type": "object", "required": false, "description": "Optional: Fields for authentication headers, timeouts, etc., if needed." }, { "name": "timeout", "type": "string", "required": false, "description": "HTTP timeout for regular operations." }, { "name": "url", "type": "string", "required": false, "description": "The full URL for the MCPServer endpoint. Example: \"https://api.example.com/mcp\"" } ], "status": [ "DOCUMENTED", "UNVERIFIED" ], "example": { "url": "https://example.com/mcp", "headers": {}, "timeout": "30s", "sseReadTimeout": "300s", "terminateOnClose": true }, "sources": [ { "url": "https://ai.google.dev/api/generate-content#StreamableHttpTransport", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/gemini-tools-agents-objects.json" }, { "provider": "gemini", "api_family": "generate-content", "name": "FunctionCall (Part.functionCall)", "object": "FunctionCall", "schema_name": "FunctionCall", "description": "A predicted `FunctionCall` returned from the model that contains a string representing the `FunctionDeclaration.name` with the arguments and their values.", "fields": [ { "name": "args", "type": "object", "required": false, "description": "Optional. The function parameters and values in JSON object format." }, { "name": "name", "type": "string", "required": true, "description": "Required. The name of the function to call. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 128." }, { "name": "id", "type": "string", "required": false, "description": "Optional. Unique identifier of the function call. If populated, the client to execute the `function_call` and return the response with the matching `id`." } ], "status": [ "DOCUMENTED", "LIVE_VERIFIED" ], "example": { "id": "m4q8z1v6", "name": "get_weather", "args": { "city": "Paris" } }, "sources": [ { "url": "https://ai.google.dev/api/generate-content#FunctionCall", "retrieved_at": "2026-09-18" } ], "companion_part_fields": { "thoughtSignature": "base64 string on the same Part — Gemini 3: mandatory on the first functionCall of each step" }, "live_observation_2026_09_18": "live: {name, args, id: call_…} + sibling part field thoughtSignature (first call of a parallel turn only); Live API toolCall ids look like function-call-", "_fragment": "generated/fragments/objects/gemini-tools-agents-objects.json" }, { "provider": "gemini", "api_family": "generate-content", "name": "FunctionResponse (Part.functionResponse)", "object": "FunctionResponse", "schema_name": "FunctionResponse", "description": "The result output from a `FunctionCall` that contains a string representing the `FunctionDeclaration.name` and a structured JSON object containing any output from the function is used as context to the model. This should contain the result of a`FunctionCall` made based on model prediction.", "fields": [ { "name": "id", "type": "string", "required": false, "description": "Optional. The identifier of the function call this response is for. Populated by the client to match the corresponding function call `id`." }, { "name": "name", "type": "string", "required": true, "description": "Required. The name of the function to call. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 128." }, { "name": "scheduling", "type": "string", "required": false, "description": "Optional. Specifies how the response should be scheduled in the conversation. Only applicable to NON_BLOCKING function calls, is ignored otherwise. Defaults to WHEN_IDLE. Live NON_BLOCKING only.", "enum": [ "SCHEDULING_UNSPECIFIED", "SILENT", "WHEN_IDLE", "INTERRUPT" ] }, { "name": "willContinue", "type": "boolean", "required": false, "description": "Optional. Signals that function call continues, and more responses will be returned, turning the function call into a generator. Is only applicable to NON_BLOCKING function calls, is ignored otherwise. If set to false, future responses will not be considered. It is allowed to return empty `response` with `will_continue=False` to signal that the function call is finished. This may still trigger the model generation. To avoid triggering the generation and finish the function call, additionally set `scheduling` to `SILENT`. Live NON_BLOCKING only." }, { "name": "response", "type": "object", "required": true, "description": "Required. The function response in JSON object format. Callers can use any keys of their choice that fit the function's syntax to return the function output, e.g. \"output\", \"result\", etc. In particular, if the function call failed to execute, the response can have an \"error\" key to return error details to the model. Multimedia can be included by using a subobject containing a single \"$ref\" key whose value is the `inline_data.display_name` of a `FunctionResponsePart` holding the multimedia. See https://ai.google.dev/gemini-api/docs/function-calling#multimodal." }, { "name": "parts", "type": "array", "required": false, "description": "Optional. Ordered `Parts` that constitute a function response. Parts may have different IANA MIME types." } ], "status": [ "DOCUMENTED" ], "example": { "id": "m4q8z1v6", "name": "get_weather", "response": { "temperature": 18, "unit": "C", "image": { "$ref": "photo.png" } }, "parts": [ { "inlineData": { "mimeType": "image/png", "data": "", "displayName": "photo.png" } } ] }, "sources": [ { "url": "https://ai.google.dev/api/generate-content#FunctionResponse", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/gemini-tools-agents-objects.json" }, { "provider": "gemini", "api_family": "generate-content", "name": "FunctionResponsePart", "object": "FunctionResponsePart", "schema_name": "FunctionResponsePart", "description": "A datatype containing media that is part of a `FunctionResponse` message. A `FunctionResponsePart` consists of data which has an associated datatype. A `FunctionResponsePart` can only contain one of the accepted types in `FunctionResponsePart.data`. A `FunctionResponsePart` must have a fixed IANA MIME type identifying the type and subtype of the media if the `inline_data` field is filled with raw bytes.", "fields": [ { "name": "inlineData", "type": "FunctionResponseBlob", "required": false, "description": "Inline media bytes." } ], "status": [ "DOCUMENTED" ], "example": { "inlineData": { "mimeType": "image/png", "data": "" } }, "sources": [ { "url": "https://ai.google.dev/api/generate-content#FunctionResponsePart", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/gemini-tools-agents-objects.json" }, { "provider": "gemini", "api_family": "generate-content", "name": "FunctionResponseBlob", "object": "FunctionResponseBlob", "schema_name": "FunctionResponseBlob", "description": "Raw media bytes for function response. Text should not be sent as raw bytes, use the 'FunctionResponse.response' field.", "fields": [ { "name": "data", "type": "string", "required": false, "description": "Raw bytes for media formats." }, { "name": "mimeType", "type": "string", "required": false, "description": "The IANA standard MIME type of the source data. Examples: - image/png - image/jpeg If an unsupported MIME type is provided, an error will be returned. For a complete list of supported types, see [Supported file formats](https://ai.google.dev/gemini-api/docs/prompting_with_media#supported_file_formats)." } ], "status": [ "DOCUMENTED" ], "example": { "mimeType": "image/jpeg", "data": "" }, "sources": [ { "url": "https://ai.google.dev/api/generate-content#FunctionResponseBlob", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/gemini-tools-agents-objects.json" }, { "provider": "gemini", "api_family": "generate-content", "name": "ExecutableCode (Part.executableCode)", "object": "ExecutableCode", "schema_name": "ExecutableCode", "description": "Code generated by the model that is meant to be executed, and the result returned to the model. Only generated when using the `CodeExecution` tool, in which the code will be automatically executed, and a corresponding `CodeExecutionResult` will also be generated.", "fields": [ { "name": "code", "type": "string", "required": true, "description": "Required. The code to be executed." }, { "name": "id", "type": "string", "required": false, "description": "Optional. Unique identifier of the `ExecutableCode` part. The server returns the `CodeExecutionResult` with the matching `id`." }, { "name": "language", "type": "string", "required": true, "description": "Required. Programming language of the `code`.", "enum": [ "LANGUAGE_UNSPECIFIED", "PYTHON" ] } ], "status": [ "DOCUMENTED", "LIVE_VERIFIED" ], "example": { "language": "PYTHON", "code": "print(sum(range(1, 51)))", "id": "c1" }, "sources": [ { "url": "https://ai.google.dev/api/generate-content#ExecutableCode", "retrieved_at": "2026-09-18" } ], "live_observation_2026_09_18": "live: {language: PYTHON, code, id: call_…}", "_fragment": "generated/fragments/objects/gemini-tools-agents-objects.json" }, { "provider": "gemini", "api_family": "generate-content", "name": "CodeExecutionResult (Part.codeExecutionResult)", "object": "CodeExecutionResult", "schema_name": "CodeExecutionResult", "description": "Result of executing the `ExecutableCode`. Generated only when the `CodeExecution` tool is used.", "fields": [ { "name": "outcome", "type": "string", "required": true, "description": "Required. Outcome of the code execution.", "enum": [ "OUTCOME_UNSPECIFIED", "OUTCOME_OK", "OUTCOME_FAILED", "OUTCOME_DEADLINE_EXCEEDED" ] }, { "name": "id", "type": "string", "required": false, "description": "Optional. The identifier of the `ExecutableCode` part this result is for. Only populated if the corresponding `ExecutableCode` has an id." }, { "name": "output", "type": "string", "required": false, "description": "Optional. Contains stdout when code execution is successful, stderr or other description otherwise." } ], "status": [ "DOCUMENTED", "LIVE_VERIFIED" ], "example": { "outcome": "OUTCOME_OK", "output": "1275\n", "id": "c1" }, "sources": [ { "url": "https://ai.google.dev/api/generate-content#CodeExecutionResult", "retrieved_at": "2026-09-18" } ], "live_observation_2026_09_18": "live: {outcome: OUTCOME_OK, output: '4\\n', id: call_…}", "_fragment": "generated/fragments/objects/gemini-tools-agents-objects.json" }, { "provider": "gemini", "api_family": "generate-content", "name": "ToolCall (Part.toolCall, server-side)", "object": "ToolCall", "schema_name": "ToolCall", "description": "A predicted server-side `ToolCall` returned from the model. This message contains information about a tool that the model wants to invoke. The client is NOT expected to execute this `ToolCall`. Instead, the client should pass this `ToolCall` back to the API in a subsequent turn within a `Content` message, along with the corresponding `ToolResponse`.", "fields": [ { "name": "toolType", "type": "string", "required": true, "description": "Required. The type of tool that was called.", "enum": [ "TOOL_TYPE_UNSPECIFIED", "GOOGLE_SEARCH_WEB", "GOOGLE_SEARCH_IMAGE", "URL_CONTEXT", "GOOGLE_MAPS", "FILE_SEARCH" ] }, { "name": "args", "type": "object", "required": false, "description": "Optional. The tool call arguments. Example: {\"arg1\" : \"value1\", \"arg2\" : \"value2\" , ...}" }, { "name": "id", "type": "string", "required": false, "description": "Optional. Unique identifier of the tool call. The server returns the tool response with the matching `id`." }, { "name": "toolName", "type": "string", "required": false, "description": "Optional. The name of the tool that was called." } ], "status": [ "DOCUMENTED", "PREVIEW" ], "example": { "toolType": "GOOGLE_SEARCH_WEB", "args": { "queries": [ "northernmost city in the United States" ] }, "id": "a7b3k9p2" }, "sources": [ { "url": "https://ai.google.dev/api/generate-content#ToolCall", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/gemini-tools-agents-objects.json" }, { "provider": "gemini", "api_family": "generate-content", "name": "ToolResponse (Part.toolResponse, server-side)", "object": "ToolResponse", "schema_name": "ToolResponse", "description": "The output from a server-side `ToolCall` execution. This message contains the results of a tool invocation that was initiated by a `ToolCall` from the model. The client should pass this `ToolResponse` back to the API in a subsequent turn within a `Content` message, along with the corresponding `ToolCall`.", "fields": [ { "name": "toolType", "type": "string", "required": true, "description": "Required. The type of tool that was called, matching the `tool_type` in the corresponding `ToolCall`.", "enum": [ "TOOL_TYPE_UNSPECIFIED", "GOOGLE_SEARCH_WEB", "GOOGLE_SEARCH_IMAGE", "URL_CONTEXT", "GOOGLE_MAPS", "FILE_SEARCH" ] }, { "name": "response", "type": "object", "required": false, "description": "Optional. The tool response." }, { "name": "id", "type": "string", "required": false, "description": "Optional. The identifier of the tool call this response is for." } ], "status": [ "DOCUMENTED", "PREVIEW" ], "example": { "toolType": "URL_CONTEXT", "response": { "urls_metadata": [ { "retrieved_url": "https://...", "url_retrieval_status": "URL_RETRIEVAL_STATUS_SUCCESS" } ] }, "id": "a7b3k9p2" }, "sources": [ { "url": "https://ai.google.dev/api/generate-content#ToolResponse", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/gemini-tools-agents-objects.json" }, { "provider": "gemini", "api_family": "generate-content", "name": "GroundingMetadata (candidates[].groundingMetadata)", "object": "GroundingMetadata", "schema_name": "GroundingMetadata", "description": "Metadata returned to client when grounding is enabled.", "fields": [ { "name": "googleMapsWidgetContextToken", "type": "string", "required": false, "description": "Optional. Resource name of the Google Maps widget context token that can be used with the PlacesContextElement widget in order to render contextual data. Only populated in the case that grounding with Google Maps is enabled." }, { "name": "retrievalMetadata", "type": "RetrievalMetadata", "required": false, "description": "Metadata related to retrieval in the grounding flow." }, { "name": "imageSearchQueries", "type": "array", "required": false, "description": "Image search queries used for grounding." }, { "name": "webSearchQueries", "type": "array", "required": false, "description": "Web search queries for the following-up web search." }, { "name": "groundingChunks", "type": "array", "required": false, "description": "List of supporting references retrieved from specified grounding source. When streaming, this only contains the grounding chunks that have not been included in the grounding metadata of previous responses." }, { "name": "groundingSupports", "type": "array", "required": false, "description": "List of grounding support." }, { "name": "searchEntryPoint", "type": "SearchEntryPoint", "required": false, "description": "Optional. Google search entry for the following-up web searches." } ], "status": [ "DOCUMENTED", "LIVE_VERIFIED" ], "example": { "webSearchQueries": [ "UEFA Euro 2024 winner" ], "searchEntryPoint": { "renderedContent": "
...
" }, "groundingChunks": [ { "web": { "uri": "https://vertexaisearch.cloud.google.com/grounding-api-redirect/...", "title": "uefa.com" } } ], "groundingSupports": [ { "segment": { "startIndex": 0, "endIndex": 85, "text": "Spain won Euro 2024..." }, "groundingChunkIndices": [ 0 ], "confidenceScores": [ 0.98 ] } ] }, "sources": [ { "url": "https://ai.google.dev/api/generate-content#GroundingMetadata", "retrieved_at": "2026-09-18" } ], "live_observation_2026_09_18": "maps run: {webSearchQueries, groundingChunks[{maps}], groundingSupports}; fileSearch run: groundingChunks[{retrievedContext{title,text,fileSearchStore(,customMetadata)}}] + groundingSupports (absent once)", "_fragment": "generated/fragments/objects/gemini-tools-agents-objects.json" }, { "provider": "gemini", "api_family": "generate-content", "name": "GroundingChunk", "object": "GroundingChunk", "schema_name": "GroundingChunk", "description": "Union: exactly one of web | image | retrievedContext | maps.", "fields": [ { "name": "image", "type": "Image", "required": false, "description": "Optional. Grounding chunk from image search." }, { "name": "retrievedContext", "type": "RetrievedContext", "required": false, "description": "Optional. Grounding chunk from context retrieved by the file search tool." }, { "name": "maps", "type": "Maps", "required": false, "description": "Optional. Grounding chunk from Google Maps." }, { "name": "web", "type": "Web", "required": false, "description": "Grounding chunk from the web." } ], "status": [ "DOCUMENTED", "LIVE_VERIFIED" ], "example": { "web": { "uri": "https://...", "title": "example.com" } }, "sources": [ { "url": "https://ai.google.dev/api/generate-content#GroundingChunk", "retrieved_at": "2026-09-18" } ], "live_observation_2026_09_18": "live shapes: {maps:{uri,title,text,placeId}}, {retrievedContext:{title,text,fileSearchStore}}", "_fragment": "generated/fragments/objects/gemini-tools-agents-objects.json" }, { "provider": "gemini", "api_family": "generate-content", "name": "Web (GroundingChunk.web)", "object": "Web", "schema_name": "Web", "description": "Chunk from the web.", "fields": [ { "name": "title", "type": "string (output only)", "required": false, "description": "Output only. Title of the chunk." }, { "name": "uri", "type": "string (output only)", "required": false, "description": "Output only. URI reference of the chunk." } ], "status": [ "DOCUMENTED" ], "example": { "uri": "https://vertexaisearch.cloud.google.com/grounding-api-redirect/...", "title": "aljazeera.com" }, "sources": [ { "url": "https://ai.google.dev/api/generate-content#Web", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/gemini-tools-agents-objects.json" }, { "provider": "gemini", "api_family": "generate-content", "name": "Image (GroundingChunk.image)", "object": "Image", "schema_name": "Image", "description": "Chunk from image search.", "fields": [ { "name": "imageUri", "type": "string", "required": false, "description": "The image asset URL." }, { "name": "title", "type": "string", "required": false, "description": "The title of the web page that the image is from." }, { "name": "sourceUri", "type": "string", "required": false, "description": "The web page URI for attribution." }, { "name": "domain", "type": "string", "required": false, "description": "The root domain of the web page that the image is from, e.g. \"example.com\"." } ], "status": [ "DOCUMENTED" ], "example": { "imageUri": "https://...jpg", "sourceUri": "https://example.com/page", "title": "Page title", "domain": "example.com" }, "sources": [ { "url": "https://ai.google.dev/api/generate-content#Image", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/gemini-tools-agents-objects.json" }, { "provider": "gemini", "api_family": "generate-content", "name": "Maps (GroundingChunk.maps)", "object": "Maps", "schema_name": "Maps", "description": "A grounding chunk from Google Maps. A Maps chunk corresponds to a single place.", "fields": [ { "name": "placeId", "type": "string", "required": false, "description": "The ID of the place, in `places/{place_id}` format. A user can use this ID to look up that place." }, { "name": "title", "type": "string", "required": false, "description": "Title of the place." }, { "name": "uri", "type": "string", "required": false, "description": "URI reference of the place." }, { "name": "placeAnswerSources", "type": "PlaceAnswerSources", "required": false, "description": "Sources that provide answers about the features of a given place in Google Maps." }, { "name": "text", "type": "string", "required": false, "description": "Text description of the place answer." } ], "status": [ "DOCUMENTED" ], "example": { "uri": "https://maps.google.com/?cid=13100894621228039586", "title": "Heaven on 7th Marketplace", "placeId": "places/ChIJ0-zA1vBZwokRon0fGj-6z7U", "placeAnswerSources": { "reviewSnippets": [ { "reviewId": "...", "googleMapsUri": "https://maps.google.com/...", "title": "..." } ] } }, "sources": [ { "url": "https://ai.google.dev/api/generate-content#Maps", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/gemini-tools-agents-objects.json" }, { "provider": "gemini", "api_family": "generate-content", "name": "PlaceAnswerSources", "object": "PlaceAnswerSources", "schema_name": "PlaceAnswerSources", "description": "Collection of sources that provide answers about the features of a given place in Google Maps. Each PlaceAnswerSources message corresponds to a specific place in Google Maps. The Google Maps tool used these sources in order to answer questions about features of the place (e.g: \"does Bar Foo have Wifi\" or \"is Foo Bar wheelchair accessible?\"). Currently we only support review snippets as sources.", "fields": [ { "name": "reviewSnippets", "type": "array", "required": false, "description": "Snippets of reviews that are used to generate answers about the features of a given place in Google Maps." } ], "status": [ "DOCUMENTED" ], "example": { "reviewSnippets": [ { "reviewId": "r1", "googleMapsUri": "https://maps.google.com/...", "title": "Great wifi" } ] }, "sources": [ { "url": "https://ai.google.dev/api/generate-content#PlaceAnswerSources", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/gemini-tools-agents-objects.json" }, { "provider": "gemini", "api_family": "generate-content", "name": "ReviewSnippet", "object": "ReviewSnippet", "schema_name": "ReviewSnippet", "description": "Encapsulates a snippet of a user review that answers a question about the features of a specific place in Google Maps.", "fields": [ { "name": "title", "type": "string", "required": false, "description": "Title of the review." }, { "name": "googleMapsUri", "type": "string", "required": false, "description": "A link that corresponds to the user review on Google Maps." }, { "name": "reviewId", "type": "string", "required": false, "description": "The ID of the review snippet." } ], "status": [ "DOCUMENTED" ], "example": { "reviewId": "r1", "googleMapsUri": "https://maps.google.com/...", "title": "Great wifi" }, "sources": [ { "url": "https://ai.google.dev/api/generate-content#ReviewSnippet", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/gemini-tools-agents-objects.json" }, { "provider": "gemini", "api_family": "generate-content", "name": "RetrievedContext (GroundingChunk.retrievedContext, File Search)", "object": "RetrievedContext", "schema_name": "RetrievedContext", "description": "Chunk from context retrieved by the file search tool.", "fields": [ { "name": "title", "type": "string", "required": false, "description": "Optional. Title of the document." }, { "name": "uri", "type": "string", "required": false, "description": "Optional. URI reference of the semantic retrieval document." }, { "name": "pageNumber", "type": "integer", "required": false, "description": "Optional. Page number of the retrieved context, if applicable." }, { "name": "customMetadata", "type": "array", "required": false, "description": "Optional. User-provided metadata about the retrieved context." }, { "name": "mediaId", "type": "string", "required": false, "description": "Optional. The media blob resource name for multimodal file search results. Format: fileSearchStores/{file_search_store_id}/media/{blob_id}" }, { "name": "text", "type": "string", "required": false, "description": "Optional. Text of the chunk." }, { "name": "fileSearchStore", "type": "string", "required": false, "description": "Optional. Name of the `FileSearchStore` containing the document. Example: `fileSearchStores/123`" } ], "status": [ "DOCUMENTED", "PREVIEW" ], "example": { "title": "sample.txt", "uri": "...", "text": "chunk text", "fileSearchStore": "fileSearchStores/my-store-123", "pageNumber": 3, "mediaId": "fileSearchStores/my-store-123/media/BlobId-456", "customMetadata": [ { "key": "author", "stringValue": "Robert Graves" } ] }, "sources": [ { "url": "https://ai.google.dev/api/generate-content#RetrievedContext", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/gemini-tools-agents-objects.json" }, { "provider": "gemini", "api_family": "generate-content", "name": "GroundingChunkCustomMetadata (retrievedContext.customMetadata[])", "object": "GroundingChunkCustomMetadata", "schema_name": "GroundingChunkCustomMetadata", "description": "User provided metadata about the GroundingFact.", "fields": [ { "name": "numericValue", "type": "number", "required": false, "description": "Optional. The numeric value of the metadata. The expected range for this value depends on the specific `key` used." }, { "name": "stringListValue", "type": "GroundingChunkStringList", "required": false, "description": "Optional. A list of string values for the metadata." }, { "name": "stringValue", "type": "string", "required": false, "description": "Optional. The string value of the metadata." }, { "name": "key", "type": "string", "required": false, "description": "The key of the metadata." } ], "status": [ "DOCUMENTED", "PREVIEW" ], "example": { "key": "year", "numericValue": 1934 }, "sources": [ { "url": "https://ai.google.dev/api/generate-content#GroundingChunkCustomMetadata", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/gemini-tools-agents-objects.json" }, { "provider": "gemini", "api_family": "generate-content", "name": "GroundingSupport", "object": "GroundingSupport", "schema_name": "GoogleAiGenerativelanguageV1betaGroundingSupport", "description": "Links a text segment of the answer to grounding chunks (citations).", "fields": [ { "name": "confidenceScores", "type": "array", "required": false, "description": "Optional. Confidence score of the support references. Ranges from 0 to 1. 1 is the most confident. This list must have the same size as the grounding_chunk_indices." }, { "name": "renderedParts", "type": "array (output only)", "required": false, "description": "Output only. Indices into the `parts` field of the candidate's content. These indices specify which rendered parts are associated with this support source." }, { "name": "groundingChunkIndices", "type": "array", "required": false, "description": "Optional. A list of indices (into 'grounding_chunk' in `response.candidate.grounding_metadata`) specifying the citations associated with the claim. For instance [1,3,4] means that grounding_chunk[1], grounding_chunk[3], grounding_chunk[4] are the retrieved content attributed to the claim. If the response is streaming, the grounding_chunk_indices refer to the indices across all responses. It is the client's responsibility to accumulate the grounding chunks from all responses (while maintaining the same order)." }, { "name": "segment", "type": "GoogleAiGenerativelanguageV1betaSegment", "required": false, "description": "Segment of the content this support belongs to." } ], "status": [ "DOCUMENTED" ], "example": { "segment": { "partIndex": 0, "startIndex": 86, "endIndex": 210, "text": "This victory marks..." }, "groundingChunkIndices": [ 0, 1 ], "confidenceScores": [ 0.9, 0.7 ] }, "sources": [ { "url": "https://ai.google.dev/api/generate-content#GoogleAiGenerativelanguageV1betaGroundingSupport", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/gemini-tools-agents-objects.json" }, { "provider": "gemini", "api_family": "generate-content", "name": "Segment", "object": "Segment", "schema_name": "GoogleAiGenerativelanguageV1betaSegment", "description": "Byte-offset span within a Part (startIndex inclusive, endIndex exclusive).", "fields": [ { "name": "endIndex", "type": "integer", "required": false, "description": "End index in the given Part, measured in bytes. Offset from the start of the Part, exclusive, starting at zero." }, { "name": "startIndex", "type": "integer", "required": false, "description": "Start index in the given Part, measured in bytes. Offset from the start of the Part, inclusive, starting at zero." }, { "name": "text", "type": "string", "required": false, "description": "The text corresponding to the segment from the response." }, { "name": "partIndex", "type": "integer", "required": false, "description": "The index of a Part object within its parent Content object." } ], "status": [ "DOCUMENTED" ], "example": { "partIndex": 0, "startIndex": 0, "endIndex": 85, "text": "Spain won Euro 2024..." }, "sources": [ { "url": "https://ai.google.dev/api/generate-content#GoogleAiGenerativelanguageV1betaSegment", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/gemini-tools-agents-objects.json" }, { "provider": "gemini", "api_family": "generate-content", "name": "SearchEntryPoint", "object": "SearchEntryPoint", "schema_name": "SearchEntryPoint", "description": "Google Search Suggestions widget that MUST be displayed with grounded answers (Terms of Service).", "fields": [ { "name": "renderedContent", "type": "string", "required": false, "description": "Optional. Web content snippet that can be embedded in a web page or an app webview." }, { "name": "sdkBlob", "type": "string", "required": false, "description": "Optional. Base64 encoded JSON representing array of tuple." } ], "status": [ "DOCUMENTED" ], "example": { "renderedContent": "
...
", "sdkBlob": "" }, "sources": [ { "url": "https://ai.google.dev/api/generate-content#SearchEntryPoint", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/gemini-tools-agents-objects.json" }, { "provider": "gemini", "api_family": "generate-content", "name": "RetrievalMetadata", "object": "RetrievalMetadata", "schema_name": "RetrievalMetadata", "description": "Metadata related to retrieval in the grounding flow.", "fields": [ { "name": "googleSearchDynamicRetrievalScore", "type": "number", "required": false, "description": "Optional. Score indicating how likely information from google search could help answer the prompt. The score is in the range [0, 1], where 0 is the least likely and 1 is the most likely. This score is only populated when google search grounding and dynamic retrieval is enabled. It will be compared to the threshold to determine whether to trigger google search." } ], "status": [ "DOCUMENTED" ], "example": { "googleSearchDynamicRetrievalScore": 0.73 }, "sources": [ { "url": "https://ai.google.dev/api/generate-content#RetrievalMetadata", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/gemini-tools-agents-objects.json" }, { "provider": "gemini", "api_family": "generate-content", "name": "UrlContextMetadata (candidates[].urlContextMetadata)", "object": "UrlContextMetadata", "schema_name": "UrlContextMetadata", "description": "Metadata related to url context retrieval tool.", "fields": [ { "name": "urlMetadata", "type": "array", "required": false, "description": "List of url context." } ], "status": [ "DOCUMENTED", "LIVE_VERIFIED" ], "example": { "urlMetadata": [ { "retrievedUrl": "https://www.foodnetwork.com/...", "urlRetrievalStatus": "URL_RETRIEVAL_STATUS_SUCCESS" } ] }, "sources": [ { "url": "https://ai.google.dev/api/generate-content#UrlContextMetadata", "retrieved_at": "2026-09-18" } ], "live_observation_2026_09_18": "live: {urlMetadata:[{retrievedUrl, urlRetrievalStatus: URL_RETRIEVAL_STATUS_ERROR}]}", "_fragment": "generated/fragments/objects/gemini-tools-agents-objects.json" }, { "provider": "gemini", "api_family": "generate-content", "name": "UrlMetadata", "object": "UrlMetadata", "schema_name": "UrlMetadata", "description": "Context of the a single url retrieval.", "fields": [ { "name": "retrievedUrl", "type": "string", "required": false, "description": "Retrieved url by the tool." }, { "name": "urlRetrievalStatus", "type": "string", "required": false, "description": "Status of the url retrieval.", "enum": [ "URL_RETRIEVAL_STATUS_UNSPECIFIED", "URL_RETRIEVAL_STATUS_SUCCESS", "URL_RETRIEVAL_STATUS_ERROR", "URL_RETRIEVAL_STATUS_PAYWALL", "URL_RETRIEVAL_STATUS_UNSAFE" ] } ], "status": [ "DOCUMENTED" ], "example": { "retrievedUrl": "https://...", "urlRetrievalStatus": "URL_RETRIEVAL_STATUS_PAYWALL" }, "sources": [ { "url": "https://ai.google.dev/api/generate-content#UrlMetadata", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/gemini-tools-agents-objects.json" }, { "provider": "gemini", "api_family": "file-search", "name": "FileSearchStore", "object": "FileSearchStore", "schema_name": "FileSearchStore", "description": "A `FileSearchStore` is a collection of `Document`s.", "fields": [ { "name": "displayName", "type": "string", "required": false, "description": "Optional. The human-readable display name for the `FileSearchStore`. The display name must be no more than 512 characters in length, including spaces. Example: \"Docs on Semantic Retriever\"" }, { "name": "updateTime", "type": "string (output only)", "required": false, "description": "Output only. The Timestamp of when the `FileSearchStore` was last updated." }, { "name": "sizeBytes", "type": "string (output only)", "required": false, "description": "Output only. The size of raw bytes ingested into the `FileSearchStore`. This is the total size of all the documents in the `FileSearchStore`." }, { "name": "embeddingModel", "type": "string", "required": false, "description": "Optional. The embedding model to use for the `FileSearchStore`. The model's resource name. This serves as an ID for the Model to use. Format: `models/{model}`. If not specified, the default embedding model will be used." }, { "name": "activeDocumentsCount", "type": "string (output only)", "required": false, "description": "Output only. The number of documents in the `FileSearchStore` that are active and ready for retrieval." }, { "name": "failedDocumentsCount", "type": "string (output only)", "required": false, "description": "Output only. The number of documents in the `FileSearchStore` that have failed processing." }, { "name": "createTime", "type": "string (output only)", "required": false, "description": "Output only. The Timestamp of when the `FileSearchStore` was created." }, { "name": "name", "type": "string (output only)", "required": false, "description": "Output only. Immutable. Identifier. The `FileSearchStore` resource name. It is an ID (name excluding the \"fileSearchStores/\" prefix) that can contain up to 40 characters that are lowercase alphanumeric or dashes (-). It is output only. The unique name will be derived from `display_name` along with a 12 character random suffix. Example: `fileSearchStores/my-awesome-file-search-store-123a456b789c` If `display_name` is not provided, the name will be randomly generated." }, { "name": "pendingDocumentsCount", "type": "string (output only)", "required": false, "description": "Output only. The number of documents in the `FileSearchStore` that are being processed." } ], "status": [ "DOCUMENTED", "PREVIEW", "LIVE_VERIFIED" ], "example": { "name": "fileSearchStores/my-awesome-file-search-store-123a456b789c", "displayName": "My Store", "embeddingModel": "models/gemini-embedding-2", "createTime": "2026-09-18T12:00:00Z", "updateTime": "2026-09-18T12:00:00Z", "activeDocumentsCount": "3", "pendingDocumentsCount": "0", "failedDocumentsCount": "0", "sizeBytes": "12345" }, "sources": [ { "url": "https://ai.google.dev/api/file-search/file-search-stores#FileSearchStore", "retrieved_at": "2026-09-18" } ], "live_observation_2026_09_18": "live: {name, displayName, createTime, updateTime, embeddingModel: models/gemini-embedding-001, activeDocumentsCount, sizeBytes}", "_fragment": "generated/fragments/objects/gemini-tools-agents-objects.json" }, { "provider": "gemini", "api_family": "file-search", "name": "Document", "object": "Document", "schema_name": "Document", "description": "A `Document` is a collection of `Chunk`s.", "fields": [ { "name": "sizeBytes", "type": "string (output only)", "required": false, "description": "Output only. The size of raw bytes ingested into the Document." }, { "name": "displayName", "type": "string", "required": false, "description": "Optional. The human-readable display name for the `Document`. The display name must be no more than 512 characters in length, including spaces. Example: \"Semantic Retriever Documentation\"" }, { "name": "createTime", "type": "string (output only)", "required": false, "description": "Output only. The Timestamp of when the `Document` was created." }, { "name": "customMetadata", "type": "array", "required": false, "description": "Optional. User provided custom metadata stored as key-value pairs used for querying. A `Document` can have a maximum of 20 `CustomMetadata`." }, { "name": "state", "type": "string (output only)", "required": false, "description": "Output only. Current state of the `Document`.", "enum": [ "STATE_UNSPECIFIED", "STATE_PENDING", "STATE_ACTIVE", "STATE_FAILED" ] }, { "name": "updateTime", "type": "string (output only)", "required": false, "description": "Output only. The Timestamp of when the `Document` was last updated." }, { "name": "name", "type": "string", "required": false, "description": "Immutable. Identifier. The `Document` resource name. The ID (name excluding the \"fileSearchStores/*/documents/\" prefix) can contain up to 40 characters that are lowercase alphanumeric or dashes (-). The ID cannot start or end with a dash. If the name is empty on create, a unique name will be derived from `display_name` along with a 12 character random suffix. Example: `fileSearchStores/{file_search_store_id}/documents/my-awesome-doc-123a456b789c`" }, { "name": "mimeType", "type": "string (output only)", "required": false, "description": "Output only. The mime type of the Document." } ], "status": [ "DOCUMENTED", "PREVIEW", "LIVE_VERIFIED" ], "example": { "name": "fileSearchStores/my-store-123/documents/sample-txt-1a2b3c4d5e6f", "displayName": "sample.txt", "state": "STATE_ACTIVE", "mimeType": "text/plain", "sizeBytes": "2048", "customMetadata": [ { "key": "author", "stringValue": "Robert Graves" }, { "key": "year", "numericValue": 1934 } ], "createTime": "...", "updateTime": "..." }, "sources": [ { "url": "https://ai.google.dev/api/file-search/documents#Document", "retrieved_at": "2026-09-18" } ], "live_observation_2026_09_18": "live: {name, displayName, mimeType, sizeBytes, state: STATE_ACTIVE, customMetadata, createTime, updateTime}", "_fragment": "generated/fragments/objects/gemini-tools-agents-objects.json" }, { "provider": "gemini", "api_family": "file-search", "name": "CustomMetadata (request)", "object": "CustomMetadata", "schema_name": "CustomMetadata", "description": "User provided metadata stored as key-value pairs.", "fields": [ { "name": "stringListValue", "type": "StringList", "required": false, "description": "The StringList value of the metadata to store." }, { "name": "numericValue", "type": "number", "required": false, "description": "The numeric value of the metadata to store." }, { "name": "stringValue", "type": "string", "required": false, "description": "The string value of the metadata to store." }, { "name": "key", "type": "string", "required": true, "description": "Required. The key of the metadata to store." } ], "status": [ "DOCUMENTED", "PREVIEW" ], "example": { "key": "tags", "stringListValue": { "values": [ "history", "novel" ] } }, "sources": [ { "url": "https://ai.google.dev/api/file-search/documents#CustomMetadata", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/gemini-tools-agents-objects.json" }, { "provider": "gemini", "api_family": "file-search", "name": "StringList", "object": "StringList", "schema_name": "StringList", "description": "User provided string values assigned to a single metadata key.", "fields": [ { "name": "values", "type": "array", "required": false, "description": "The string values of the metadata to store." } ], "status": [ "DOCUMENTED", "PREVIEW" ], "example": { "values": [ "a", "b" ] }, "sources": [ { "url": "https://ai.google.dev/api/file-search/documents#StringList", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/gemini-tools-agents-objects.json" }, { "provider": "gemini", "api_family": "file-search", "name": "ChunkingConfig", "object": "ChunkingConfig", "schema_name": "ChunkingConfig", "description": "Parameters for telling the service how to chunk the file. inspired by google3/cloud/ai/platform/extension/lib/retrieval/config/chunker_config.proto", "fields": [ { "name": "whiteSpaceConfig", "type": "WhiteSpaceConfig", "required": false, "description": "White space chunking configuration." } ], "status": [ "DOCUMENTED", "PREVIEW" ], "example": { "whiteSpaceConfig": { "maxTokensPerChunk": 200, "maxOverlapTokens": 20 } }, "sources": [ { "url": "https://ai.google.dev/api/file-search/file-search-stores", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/gemini-tools-agents-objects.json" }, { "provider": "gemini", "api_family": "file-search", "name": "WhiteSpaceConfig", "object": "WhiteSpaceConfig", "schema_name": "WhiteSpaceConfig", "description": "Configuration for a white space chunking algorithm [white space delimited].", "fields": [ { "name": "maxTokensPerChunk", "type": "integer", "required": false, "description": "Maximum number of tokens per chunk. Tokens are defined as words for this chunking algorithm. Note: we are defining tokens as words split by whitespace as opposed to the output of a tokenizer. The context window of the latest gemini embedding model as of 2025-04-17 is currently 8192 tokens. We assume that the average word is 5 characters. Therefore, we set the upper limit to 2**9, which is 512 words, or 2560 tokens, assuming worst case a character per token. This is a conservative estimate meant to prevent context window overflow." }, { "name": "maxOverlapTokens", "type": "integer", "required": false, "description": "Maximum number of overlapping tokens between two adjacent chunks." } ], "status": [ "DOCUMENTED", "PREVIEW" ], "example": { "maxTokensPerChunk": 200, "maxOverlapTokens": 20 }, "sources": [ { "url": "https://ai.google.dev/api/file-search/file-search-stores", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/gemini-tools-agents-objects.json" }, { "provider": "gemini", "api_family": "file-search", "name": "MetadataFilter (discovery schema; the generateContent tool takes a string)", "object": "MetadataFilter", "schema_name": "MetadataFilter", "description": "Structured filter schema present in discovery (key + OR-joined conditions). generateContent's tools[].fileSearch.metadataFilter is a STRING in AIP-160 syntax; this object documents the operators available.", "fields": [ { "name": "conditions", "type": "array", "required": true, "description": "Required. The `Condition`s for the given key that will trigger this filter. Multiple `Condition`s are joined by logical ORs." }, { "name": "key", "type": "string", "required": true, "description": "Required. The key of the metadata to filter on." } ], "status": [ "DOCUMENTED", "PREVIEW" ], "example": { "key": "document.custom_metadata.genre", "conditions": [ { "stringValue": "drama", "operation": "EQUAL" }, { "stringValue": "action", "operation": "EQUAL" } ] }, "sources": [ { "url": "https://ai.google.dev/api/file-search/file-search-stores", "retrieved_at": "2026-09-18" }, { "url": "https://ai.google.dev/api/generate-content#FileSearch", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/gemini-tools-agents-objects.json" }, { "provider": "gemini", "api_family": "file-search", "name": "Condition", "object": "Condition", "schema_name": "Condition", "description": "Filter condition applicable to a single key.", "fields": [ { "name": "operation", "type": "string", "required": true, "description": "Required. Operator applied to the given key-value pair to trigger the condition.", "enum": [ "OPERATOR_UNSPECIFIED", "LESS", "LESS_EQUAL", "EQUAL", "GREATER_EQUAL", "GREATER", "NOT_EQUAL", "INCLUDES", "EXCLUDES" ] }, { "name": "numericValue", "type": "number", "required": false, "description": "The numeric value to filter the metadata on." }, { "name": "stringValue", "type": "string", "required": false, "description": "The string value to filter the metadata on." } ], "status": [ "DOCUMENTED", "PREVIEW" ], "example": { "operation": "GREATER", "numericValue": 1930 }, "sources": [ { "url": "https://ai.google.dev/api/file-search/file-search-stores", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/gemini-tools-agents-objects.json" }, { "provider": "gemini", "api_family": "file-search", "name": "UploadToFileSearchStoreRequest", "object": "UploadToFileSearchStoreRequest", "schema_name": "UploadToFileSearchStoreRequest", "description": "Request for `UploadToFileSearchStore`.", "fields": [ { "name": "chunkingConfig", "type": "ChunkingConfig", "required": false, "description": "Optional. Config for telling the service how to chunk the data. If not provided, the service will use default parameters." }, { "name": "displayName", "type": "string", "required": false, "description": "Optional. Display name of the created document." }, { "name": "mimeType", "type": "string", "required": false, "description": "Optional. MIME type of the data. If not provided, it will be inferred from the uploaded content." }, { "name": "customMetadata", "type": "array", "required": false, "description": "Custom metadata to be associated with the data." } ], "status": [ "DOCUMENTED", "PREVIEW" ], "example": { "displayName": "sample.txt", "mimeType": "text/plain", "customMetadata": [ { "key": "author", "stringValue": "X" } ], "chunkingConfig": { "whiteSpaceConfig": { "maxTokensPerChunk": 200, "maxOverlapTokens": 20 } } }, "sources": [ { "url": "https://ai.google.dev/api/file-search/file-search-stores#method:-media.uploadtofilesearchstore", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/gemini-tools-agents-objects.json" }, { "provider": "gemini", "api_family": "file-search", "name": "ImportFileRequest", "object": "ImportFileRequest", "schema_name": "ImportFileRequest", "description": "Request for `ImportFile` to import a File API file with a `FileSearchStore`.", "fields": [ { "name": "customMetadata", "type": "array", "required": false, "description": "Custom metadata to be associated with the file." }, { "name": "fileName", "type": "string", "required": true, "description": "Required. The name of the `File` to import. Example: `files/abc-123`" }, { "name": "chunkingConfig", "type": "ChunkingConfig", "required": false, "description": "Optional. Config for telling the service how to chunk the file. If not provided, the service will use default parameters." } ], "status": [ "DOCUMENTED", "PREVIEW" ], "example": { "fileName": "files/abc-123", "customMetadata": [ { "key": "year", "numericValue": 1934 } ] }, "sources": [ { "url": "https://ai.google.dev/api/file-search/file-search-stores#method:-filesearchstores.importfile", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/gemini-tools-agents-objects.json" }, { "provider": "gemini", "api_family": "file-search", "name": "ListFileSearchStoresResponse", "object": "ListFileSearchStoresResponse", "schema_name": "ListFileSearchStoresResponse", "description": "Response from `ListFileSearchStores` containing a paginated list of `FileSearchStores`. The results are sorted by ascending `file_search_store.create_time`.", "fields": [ { "name": "fileSearchStores", "type": "array", "required": false, "description": "The returned rag_stores." }, { "name": "nextPageToken", "type": "string", "required": false, "description": "A token, which can be sent as `page_token` to retrieve the next page. If this field is omitted, there are no more pages." } ], "status": [ "DOCUMENTED", "PREVIEW" ], "example": { "fileSearchStores": [ { "name": "fileSearchStores/..." } ], "nextPageToken": "..." }, "sources": [ { "url": "https://ai.google.dev/api/file-search/file-search-stores", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/gemini-tools-agents-objects.json" }, { "provider": "gemini", "api_family": "file-search", "name": "ListDocumentsResponse", "object": "ListDocumentsResponse", "schema_name": "ListDocumentsResponse", "description": "Response from `ListDocuments` containing a paginated list of `Document`s. The `Document`s are sorted by ascending `document.create_time`.", "fields": [ { "name": "nextPageToken", "type": "string", "required": false, "description": "A token, which can be sent as `page_token` to retrieve the next page. If this field is omitted, there are no more pages." }, { "name": "documents", "type": "array", "required": false, "description": "The returned `Document`s." } ], "status": [ "DOCUMENTED", "PREVIEW" ], "example": { "documents": [ { "name": "fileSearchStores/.../documents/..." } ], "nextPageToken": "..." }, "sources": [ { "url": "https://ai.google.dev/api/file-search/documents", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/gemini-tools-agents-objects.json" }, { "provider": "gemini", "api_family": "file-search", "name": "Operation (long-running operation)", "object": "Operation", "schema_name": "Operation", "description": "google.longrunning.Operation returned by importFile / uploadToFileSearchStore; poll GET on `name` until done=true, then read response or error. Upload operations live under fileSearchStores/{id}/upload/operations/{op}; import operations under fileSearchStores/{id}/operations/{op}.", "fields": [ { "name": "error", "type": "Status", "required": false, "description": "The error result of the operation in case of failure or cancellation." }, { "name": "response", "type": "object", "required": false, "description": "The normal, successful response of the operation. If the original method returns no data on success, such as `Delete`, the response is `google.protobuf.Empty`. If the original method is standard `Get`/`Create`/`Update`, the response should be the resource. For other methods, the response should have the type `XxxResponse`, where `Xxx` is the original method name. For example, if the original method name is `TakeSnapshot()`, the inferred response type is `TakeSnapshotResponse`." }, { "name": "done", "type": "boolean", "required": false, "description": "If the value is `false`, it means the operation is still in progress. If `true`, the operation is completed, and either `error` or `response` is available." }, { "name": "name", "type": "string", "required": false, "description": "The server-assigned name, which is only unique within the same service that originally returns it. If you use the default HTTP mapping, the `name` should be a resource name ending with `operations/{unique_id}`." }, { "name": "metadata", "type": "object", "required": false, "description": "Service-specific metadata associated with the operation. It typically contains progress information and common metadata such as create time. Some services might not provide such metadata. Any method that returns a long-running operation should document the metadata type, if any." } ], "status": [ "DOCUMENTED", "PREVIEW", "LIVE_VERIFIED" ], "example": { "name": "fileSearchStores/my-store-123/upload/operations/abc123", "done": false, "metadata": { "@type": "..." } }, "sources": [ { "url": "https://ai.google.dev/api/file-search/file-search-stores#Operation", "retrieved_at": "2026-09-18" } ], "live_observation_2026_09_18": "live upload operation: {name: …/upload/operations/…, response:{@type, documentName, mimeType, parent, sizeBytes}, done:true}", "_fragment": "generated/fragments/objects/gemini-tools-agents-objects.json" }, { "provider": "gemini", "api_family": "file-search", "name": "Status (Operation.error)", "object": "Status", "schema_name": "Status", "description": "The `Status` type defines a logical error model that is suitable for different programming environments, including REST APIs and RPC APIs. It is used by [gRPC](https://github.com/grpc). Each `Status` message contains three pieces of data: error code, error message, and error details. You can find out more about this error model and how to work with it in the [API Design Guide](https://cloud.google.com/apis/design/errors).", "fields": [ { "name": "message", "type": "string", "required": false, "description": "A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the google.rpc.Status.details field, or localized by the client." }, { "name": "code", "type": "integer", "required": false, "description": "The status code, which should be an enum value of google.rpc.Code." }, { "name": "details", "type": "array", "required": false, "description": "A list of messages that carry the error details. There is a common set of message types for APIs to use." } ], "status": [ "DOCUMENTED" ], "example": { "code": 9, "message": "FAILED_PRECONDITION: ...", "details": [] }, "sources": [ { "url": "https://ai.google.dev/api/files#v1beta.Status", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/gemini-tools-agents-objects.json" }, { "provider": "gemini", "api_family": "generate-content", "name": "ComputerUse predefined actions (functionCall catalogue)", "object": "computerUse predefined functions", "schema_name": null, "description": "Function names the model emits as functionCall parts when tools[].computerUse is enabled (auto-populated declarations; remove any with excludedPredefinedFunctions[]). Gemini 3.x: every call carries an `intent` string; coordinates normalized 0-999 (client scales to viewport). Legacy gemini-2.5-computer-use-preview-10-2025 uses the older browser-only set. Safety: args may include `safety_decision {decision: 'require_confirmation'|..., explanation}`; after user approval reply with functionResponse.response.safety_acknowledgement=true (or terminate). Client returns after each action a functionResponse with {url, ...result} and the new screenshot (inlineData image/png).", "fields": [ { "name": "browser (ENVIRONMENT_BROWSER, Gemini 3.x)", "type": "actions", "required": false, "description": "[{\"name\": \"click\", \"description\": \"Left click\", \"args\": \"x: int 0-999, y: int 0-999, intent: str\"}, {\"name\": \"double_click\", \"description\": \"Double click\", \"args\": \"x: int 0-999, y: int 0-999, intent\"}, {\"name\": \"triple_click\", \"description\": \"Triple click\", \"args\": \"x: int 0-999, y: int 0-999, intent\"}, {\"name\": \"middle_click\", \"description\": \"Middle click\", \"args\": \"x: int 0-999, y: int 0-999, intent\"}, {\"name\": \"right_click\", \"description\": \"Right click\", \"args\": \"x: int 0-999, y: int 0-999, intent\"}, {\"name\": \"mouse_down\", \"description\": \"Press and hold mouse button\", \"args\": \"x: int 0-999, y: int 0-999, intent\"}, {\"name\": \"mouse_up\", \"description\": \"Release mouse button\", \"args\": \"x: int 0-999, y: int 0-999, intent\"}, {\"name\": \"move\", \"description\": \"Move cursor\", \"args\": \"x: int 0-999, y: int 0-999, intent\"}, {\"name\": \"type\", \"description\": \"Type text\", \"args\": \"text: str, press_enter: bool (default false), intent\"}, {\"name\": \"drag_and_drop\", \"description\": \"Drag from start to end\", \"args\": \"start_x, start_y, end_x, end_y: int 0-999, intent\"}, {\"name\": \"wait\", \"description\": \"Pause\", \"args\": \"seconds: int (default 1), intent\"}, {\"name\": \"press_key\", \"description\": \"Press and release key\", \"args\": \"key: str, intent\"}, {\"name\": \"key_down\", \"description\": \"Hold key\", \"args\": \"key: str, intent\"}, {\"name\": \"key_up\", \"description\": \"Release key\", \"args\": \"key: str, intent\"}, {\"name\": \"hotkey\", \"description\": \"Key combination\", \"args\": \"keys: list[str], intent\"}, {\"name\": \"take_screenshot\", \"description\": \"Return screenshot\", \"args\": \"intent\"}, {\"name\": \"scroll\", \"description\": \"Scroll at coordinate\", \"args\": \"x: int 0-999, y: int 0-999, direction: up|down|left|right, magnitude_in_pixels: int 0-999 (default 300), intent\"}, {\"name\": \"go_back\", \"description\": \"Browser back\", \"args\": \"intent\"}, {\"name\": \"navigate\", \"description\": \"Go to URL\", \"args\": \"url: str, intent\"}, {\"name\": \"go_forward\", \"description\": \"Browser forward\", \"args\": \"intent\"}]" }, { "name": "mobile (ENVIRONMENT_MOBILE, Gemini 3.x)", "type": "actions", "required": false, "description": "[{\"name\": \"open_app\", \"description\": \"Open app by name\", \"args\": \"app_name: str, intent\"}, {\"name\": \"click\", \"description\": \"Left click\", \"args\": \"x: int 0-999, y: int 0-999, intent\"}, {\"name\": \"list_apps\", \"description\": \"List apps (names + package names)\", \"args\": \"intent\"}, {\"name\": \"wait\", \"description\": \"Pause\", \"args\": \"seconds: int (default 1), intent\"}, {\"name\": \"go_back\", \"description\": \"Back\", \"args\": \"intent\"}, {\"name\": \"type\", \"description\": \"Type text\", \"args\": \"text: str, press_enter: bool (default false), intent\"}, {\"name\": \"drag_and_drop\", \"description\": \"Drag\", \"args\": \"start_x, start_y, end_x, end_y, intent\"}, {\"name\": \"long_press\", \"description\": \"Long press\", \"args\": \"x: int 0-999, y: int 0-999, seconds: int (default 2), intent\"}, {\"name\": \"press_key\", \"description\": \"Press key\", \"args\": \"key: str, intent\"}, {\"name\": \"take_screenshot\", \"description\": \"Screenshot\", \"args\": \"intent\"}]" }, { "name": "desktop (ENVIRONMENT_DESKTOP, Gemini 3.x)", "type": "actions", "required": false, "description": "[{\"name\": \"click\", \"description\": \"Left click\", \"args\": \"x: int 0-999, y: int 0-999, intent: str\"}, {\"name\": \"double_click\", \"description\": \"Double click\", \"args\": \"x: int 0-999, y: int 0-999, intent\"}, {\"name\": \"triple_click\", \"description\": \"Triple click\", \"args\": \"x: int 0-999, y: int 0-999, intent\"}, {\"name\": \"middle_click\", \"description\": \"Middle click\", \"args\": \"x: int 0-999, y: int 0-999, intent\"}, {\"name\": \"right_click\", \"description\": \"Right click\", \"args\": \"x: int 0-999, y: int 0-999, intent\"}, {\"name\": \"mouse_down\", \"description\": \"Press and hold mouse button\", \"args\": \"x: int 0-999, y: int 0-999, intent\"}, {\"name\": \"mouse_up\", \"description\": \"Release mouse button\", \"args\": \"x: int 0-999, y: int 0-999, intent\"}, {\"name\": \"move\", \"description\": \"Move cursor\", \"args\": \"x: int 0-999, y: int 0-999, intent\"}, {\"name\": \"type\", \"description\": \"Type text\", \"args\": \"text: str, press_enter: bool (default false), intent\"}, {\"name\": \"drag_and_drop\", \"description\": \"Drag from start to end\", \"args\": \"start_x, start_y, end_x, end_y: int 0-999, intent\"}, {\"name\": \"wait\", \"description\": \"Pause\", \"args\": \"seconds: int (default 1), intent\"}, {\"name\": \"press_key\", \"description\": \"Press and release key\", \"args\": \"key: str, intent\"}, {\"name\": \"key_down\", \"description\": \"Hold key\", \"args\": \"key: str, intent\"}, {\"name\": \"key_up\", \"description\": \"Release key\", \"args\": \"key: str, intent\"}, {\"name\": \"hotkey\", \"description\": \"Key combination\", \"args\": \"keys: list[str], intent\"}, {\"name\": \"take_screenshot\", \"description\": \"Return screenshot\", \"args\": \"intent\"}, {\"name\": \"scroll\", \"description\": \"Scroll at coordinate\", \"args\": \"x: int 0-999, y: int 0-999, direction: up|down|left|right, magnitude_in_pixels: int 0-999 (default 300), intent\"}]" }, { "name": "legacy browser (gemini-2.5-computer-use-preview-10-2025)", "type": "actions", "required": false, "description": "[{\"name\": \"open_web_browser\", \"description\": \"Opens the web browser\", \"args\": \"none\"}, {\"name\": \"wait_5_seconds\", \"description\": \"Pause 5 s\", \"args\": \"none\"}, {\"name\": \"go_back\", \"description\": \"Back\", \"args\": \"none\"}, {\"name\": \"go_forward\", \"description\": \"Forward\", \"args\": \"none\"}, {\"name\": \"search\", \"description\": \"Go to default search engine\", \"args\": \"none\"}, {\"name\": \"navigate\", \"description\": \"Go to URL\", \"args\": \"url: str\"}, {\"name\": \"click_at\", \"description\": \"Click at coordinate\", \"args\": \"x, y: int 0-999\"}, {\"name\": \"hover_at\", \"description\": \"Hover\", \"args\": \"x, y\"}, {\"name\": \"type_text_at\", \"description\": \"Type at coordinate\", \"args\": \"x, y, text: str, press_enter: bool (default true), clear_before_typing: bool (default true)\"}, {\"name\": \"key_combination\", \"description\": \"Press keys\", \"args\": \"keys: str e.g. 'Control+A'\"}, {\"name\": \"scroll_document\", \"description\": \"Scroll page\", \"args\": \"direction: str\"}, {\"name\": \"scroll_at\", \"description\": \"Scroll at coordinate\", \"args\": \"x, y, direction, magnitude: int (default 800)\"}, {\"name\": \"drag_and_drop\", \"description\": \"Drag\", \"args\": \"x, y, destination_x, destination_y\"}]" }, { "name": "safety_decision (in functionCall.args)", "type": "object", "required": false, "description": "{decision: 'require_confirmation' | (allowed/blocked), explanation: str}" }, { "name": "safety_acknowledgement (in functionResponse.response)", "type": "boolean", "required": false, "description": "Set true after the end user confirms a require_confirmation action." } ], "status": [ "DOCUMENTED", "PREVIEW" ], "example": { "model": { "functionCall": { "name": "click", "args": { "x": 450, "y": 120, "intent": "Click the search box to type the destination." } } }, "client": { "functionResponse": { "name": "click", "id": "", "response": { "url": "https://www.google.com/", "safety_acknowledgement": true }, "parts": [ { "inlineData": { "mimeType": "image/png", "data": "" } } ] } } }, "sources": [ { "url": "https://ai.google.dev/gemini-api/docs/computer-use", "retrieved_at": "2026-09-18" }, { "url": "https://ai.google.dev/gemini-api/docs/generate-content/computer-use", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/gemini-tools-agents-objects.json" }, { "provider": "gemini", "api_family": "interactions", "name": "Interaction", "object": "interaction", "schema_name": "Interaction", "description": "Core resource: one turn/task with its chronological `steps` (thoughts, tool calls/results, model_output; `user_input` only in GET). `object` = 'interaction'.", "fields": [ { "name": "id", "type": "string", "required": true, "description": "Unique id, e.g. `v1_Chd...`." }, { "name": "object", "type": "string", "required": false, "description": "Always `interaction`." }, { "name": "status", "type": "string", "required": true, "description": "Lifecycle status. `budget_exceeded` is deprecated (now `incomplete`).", "enum": [ "queued", "in_progress", "requires_action", "completed", "failed", "cancelled", "incomplete", "budget_exceeded" ] }, { "name": "model", "type": "string (ModelOption)", "required": false, "description": "Model used (mutually exclusive with agent)." }, { "name": "agent", "type": "string (AgentOption)", "required": false, "description": "Agent used." }, { "name": "agent_config", "type": "AntigravityAgentConfig | DeepResearchAgentConfig | DynamicAgentConfig | CodeMenderAgentConfig", "required": false, "description": "Agent configuration." }, { "name": "generation_config", "type": "GenerationConfig", "required": false, "description": "Input only. Model configuration." }, { "name": "input", "type": "string | Content | Content[] | Step[]", "required": false, "description": "Echo of the input." }, { "name": "system_instruction", "type": "string", "required": false, "description": "" }, { "name": "tools", "type": "Tool[]", "required": false, "description": "" }, { "name": "response_format", "type": "ResponseFormat | ResponseFormat[]", "required": false, "description": "" }, { "name": "environment", "type": "EnvironmentConfig | string", "required": false, "description": "Requested environment." }, { "name": "environment_id", "type": "string", "required": false, "description": "Output only. Sandbox id; only when environment set." }, { "name": "previous_interaction_id", "type": "string", "required": false, "description": "" }, { "name": "labels", "type": "object", "required": false, "description": "" }, { "name": "safety_settings", "type": "SafetySetting[]", "required": false, "description": "" }, { "name": "service_tier", "type": "string", "required": false, "description": "", "enum": [ "flex", "standard", "priority" ] }, { "name": "webhook_config", "type": "WebhookConfig", "required": false, "description": "" }, { "name": "steps", "type": "Step[]", "required": false, "description": "Output only. Execution steps." }, { "name": "usage", "type": "Usage", "required": false, "description": "Output only. Token statistics." }, { "name": "errors", "type": "Error[]", "required": false, "description": "Output only. Diagnostic faults {code, message}." }, { "name": "created", "type": "string (ISO 8601)", "required": false, "description": "Output only." }, { "name": "updated", "type": "string (ISO 8601)", "required": false, "description": "Output only." }, { "name": "output_text", "type": "string (SDK convenience)", "required": false, "description": "google-genai / @google/genai only: concatenated text of the last model_output step (not in the JSON)." } ], "status": [ "DOCUMENTED", "BETA", "LIVE_VERIFIED" ], "example": { "created": "2025-12-04T15:01:45Z", "id": "v1_ChdXS0l4YWZXTk9xbk0xZThQczhEcmlROBIXV0tJeGFmV05PcW5NMWU4UHM4RHJpUTg", "model": "gemini-3.6-flash", "object": "interaction", "status": "completed", "steps": [ { "type": "model_output", "content": [ { "type": "text", "text": "Hello! I'm doing well..." } ] } ], "updated": "2025-12-04T15:01:45Z", "usage": { "input_tokens_by_modality": [ { "modality": "text", "tokens": 7 } ], "total_cached_tokens": 0, "total_input_tokens": 7, "total_output_tokens": 23, "total_thought_tokens": 49, "total_tokens": 79, "total_tool_use_tokens": 0 } }, "sources": [ { "url": "https://ai.google.dev/api/interactions", "retrieved_at": "2026-09-18" } ], "live_observation_2026_09_18": "live: {id, object: interaction, status, model|agent, created, updated, service_tier, steps[], usage{total_tokens,total_input_tokens,input_tokens_by_modality,total_cached_tokens,total_output_tokens,total_tool_use_tokens,total_thought_tokens,raw_prompt_token,model_invocation_token_counts}, generation_config (GET echo)}; store:false → no id", "_fragment": "generated/fragments/objects/gemini-tools-agents-objects.json" }, { "provider": "gemini", "api_family": "interactions", "name": "Usage", "object": null, "schema_name": "Usage", "description": "Token statistics of an interaction (also `step_usage`/`usage` on step.stop, `metadata.total_usage` on step.delta).", "fields": [ { "name": "total_input_tokens", "type": "integer", "required": false, "description": "Prompt tokens." }, { "name": "total_output_tokens", "type": "integer", "required": false, "description": "" }, { "name": "total_thought_tokens", "type": "integer", "required": false, "description": "Thinking tokens." }, { "name": "total_cached_tokens", "type": "integer", "required": false, "description": "Cached prompt tokens." }, { "name": "total_tool_use_tokens", "type": "integer", "required": false, "description": "Tool-use prompt tokens." }, { "name": "total_tokens", "type": "integer", "required": false, "description": "prompt + responses + internal." }, { "name": "input_tokens_by_modality", "type": "ModalityTokens[]", "required": false, "description": "{modality: text|image|audio|video|document, tokens}" }, { "name": "output_tokens_by_modality", "type": "ModalityTokens[]", "required": false, "description": "" }, { "name": "cached_tokens_by_modality", "type": "ModalityTokens[]", "required": false, "description": "" }, { "name": "tool_use_tokens_by_modality", "type": "ModalityTokens[]", "required": false, "description": "" }, { "name": "grounding_tool_count", "type": "GroundingToolCount[]", "required": false, "description": "{type: google_search|google_maps, count}" } ], "status": [ "DOCUMENTED", "BETA" ], "example": null, "sources": [ { "url": "https://ai.google.dev/api/interactions", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/gemini-tools-agents-objects.json" }, { "provider": "gemini", "api_family": "interactions", "name": "Error", "object": null, "schema_name": "Error", "description": "Error object (Interaction.errors[], SSE error event, HTTP error bodies `{error:{message, code}}`). Known codes: invalid_request (400), not_found (404), aborted (409), gateway_timeout.", "fields": [ { "name": "code", "type": "string", "required": false, "description": "A URI/short code identifying the error type." }, { "name": "message", "type": "string", "required": false, "description": "Human-readable message." } ], "status": [ "DOCUMENTED", "BETA" ], "example": { "error": { "message": "Result not found.; GetCredential call failed", "code": "not_found" } }, "sources": [ { "url": "https://ai.google.dev/api/interactions", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/gemini-tools-agents-objects.json" }, { "provider": "gemini", "api_family": "interactions", "name": "InteractionSseEventInteraction", "object": null, "schema_name": "InteractionSseEventInteraction", "description": "Partial Interaction carried by interaction.created / interaction.completed (may omit fields available only on full responses; no steps).", "fields": [ { "name": "id", "type": "string", "required": true, "description": "" }, { "name": "object", "type": "string", "required": false, "description": "" }, { "name": "model", "type": "string", "required": false, "description": "" }, { "name": "agent", "type": "string", "required": false, "description": "" }, { "name": "status", "type": "string", "required": true, "description": "", "enum": [ "in_progress", "requires_action", "completed", "failed", "cancelled", "incomplete" ] }, { "name": "service_tier", "type": "string", "required": false, "description": "" }, { "name": "steps", "type": "Step[]", "required": false, "description": "if included" }, { "name": "usage", "type": "Usage", "required": false, "description": "" }, { "name": "created", "type": "string", "required": false, "description": "" }, { "name": "updated", "type": "string", "required": false, "description": "" } ], "status": [ "DOCUMENTED", "BETA" ], "example": null, "sources": [ { "url": "https://ai.google.dev/api/interactions", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/gemini-tools-agents-objects.json" }, { "provider": "gemini", "api_family": "interactions", "name": "Content (union)", "object": null, "schema_name": "Content", "description": "Polymorphic content block (discriminator `type`). Used in `input`, `user_input.content`, `model_output.content`, function results, thought summaries.", "fields": [ { "name": "type", "type": "string", "required": true, "description": "", "enum": [ "text", "image", "audio", "document", "video" ] } ], "status": [ "DOCUMENTED", "BETA" ], "example": null, "sources": [ { "url": "https://ai.google.dev/api/interactions", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/gemini-tools-agents-objects.json" }, { "provider": "gemini", "api_family": "interactions", "name": "TextContent", "object": null, "schema_name": "TextContent", "description": "A text block, optionally with citation annotations.", "fields": [ { "name": "type", "type": "string", "required": true, "description": "`text`", "enum": [ "text" ] }, { "name": "text", "type": "string", "required": true, "description": "" }, { "name": "annotations", "type": "Annotation[]", "required": false, "description": "file_citation | place_citation | url_citation | word_info" } ], "status": [ "DOCUMENTED", "BETA" ], "example": { "type": "text", "text": "Hello, how are you?" }, "sources": [ { "url": "https://ai.google.dev/api/interactions", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/gemini-tools-agents-objects.json" }, { "provider": "gemini", "api_family": "interactions", "name": "ImageContent", "object": null, "schema_name": "ImageContent", "description": "Image block (inline base64 or uri).", "fields": [ { "name": "type", "type": "string", "required": true, "description": "", "enum": [ "image" ] }, { "name": "data", "type": "string (base64)", "required": false, "description": "" }, { "name": "uri", "type": "string", "required": false, "description": "" }, { "name": "mime_type", "type": "string", "required": false, "description": "", "enum": [ "image/png", "image/jpeg", "image/webp", "image/heic", "image/heif", "image/gif", "image/bmp", "image/tiff" ] }, { "name": "resolution", "type": "string", "required": false, "description": "", "enum": [ "low", "medium", "high", "ultra_high" ] } ], "status": [ "DOCUMENTED", "BETA" ], "example": { "type": "image", "data": "BASE64_ENCODED_IMAGE", "mime_type": "image/png" }, "sources": [ { "url": "https://ai.google.dev/api/interactions", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/gemini-tools-agents-objects.json" }, { "provider": "gemini", "api_family": "interactions", "name": "AudioContent", "object": null, "schema_name": "AudioContent", "description": "Audio block.", "fields": [ { "name": "type", "type": "string", "required": true, "description": "", "enum": [ "audio" ] }, { "name": "data", "type": "string", "required": false, "description": "" }, { "name": "uri", "type": "string", "required": false, "description": "" }, { "name": "mime_type", "type": "string", "required": false, "description": "", "enum": [ "audio/wav", "audio/mp3", "audio/aiff", "audio/aac", "audio/ogg", "audio/flac", "audio/mpeg", "audio/m4a", "audio/l16", "audio/opus", "audio/alaw", "audio/mulaw", "audio/webm" ] }, { "name": "channels", "type": "integer", "required": false, "description": "" }, { "name": "sample_rate", "type": "integer", "required": false, "description": "" } ], "status": [ "DOCUMENTED", "BETA" ], "example": { "type": "audio", "data": "BASE64_ENCODED_AUDIO", "mime_type": "audio/wav" }, "sources": [ { "url": "https://ai.google.dev/api/interactions", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/gemini-tools-agents-objects.json" }, { "provider": "gemini", "api_family": "interactions", "name": "DocumentContent", "object": null, "schema_name": "DocumentContent", "description": "Document block (PDF/CSV).", "fields": [ { "name": "type", "type": "string", "required": true, "description": "", "enum": [ "document" ] }, { "name": "data", "type": "string", "required": false, "description": "" }, { "name": "uri", "type": "string", "required": false, "description": "" }, { "name": "mime_type", "type": "string", "required": false, "description": "", "enum": [ "application/pdf", "text/csv" ] } ], "status": [ "DOCUMENTED", "BETA" ], "example": { "type": "document", "data": "BASE64_ENCODED_DOCUMENT", "mime_type": "application/pdf" }, "sources": [ { "url": "https://ai.google.dev/api/interactions", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/gemini-tools-agents-objects.json" }, { "provider": "gemini", "api_family": "interactions", "name": "VideoContent", "object": null, "schema_name": "VideoContent", "description": "Video block; `processing` selects static frame sampling vs agentic navigation.", "fields": [ { "name": "type", "type": "string", "required": true, "description": "", "enum": [ "video" ] }, { "name": "data", "type": "string", "required": false, "description": "" }, { "name": "uri", "type": "string", "required": false, "description": "Files URI or YouTube URL" }, { "name": "mime_type", "type": "string", "required": false, "description": "", "enum": [ "video/mp4", "video/mpeg", "video/mpg", "video/mov", "video/avi", "video/x-flv", "video/webm", "video/wmv", "video/3gpp" ] }, { "name": "name", "type": "string", "required": false, "description": "user-defined reference name" }, { "name": "processing", "type": "'static' | 'agentic' | StaticMediaProcessing{type:'static', fps, start_offset, end_offset}", "required": false, "description": "" }, { "name": "resolution", "type": "string", "required": false, "description": "", "enum": [ "low", "medium", "high", "ultra_high" ] } ], "status": [ "DOCUMENTED", "BETA" ], "example": { "type": "video", "uri": "https://www.youtube.com/watch?v=9hE5-98ZeCg" }, "sources": [ { "url": "https://ai.google.dev/api/interactions", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/gemini-tools-agents-objects.json" }, { "provider": "gemini", "api_family": "interactions", "name": "Annotation (union)", "object": null, "schema_name": "Annotation", "description": "Citation annotation on TextContent / TextAnnotationDelta.", "fields": [ { "name": "type", "type": "string", "required": true, "description": "", "enum": [ "file_citation", "place_citation", "url_citation", "word_info" ] }, { "name": "start_index", "type": "integer", "required": false, "description": "byte offset start" }, { "name": "end_index", "type": "integer", "required": false, "description": "exclusive end" }, { "name": "url / title", "type": "string", "required": false, "description": "url_citation" }, { "name": "document_uri / file_name / page_number / media_id / source / custom_metadata", "type": "mixed", "required": false, "description": "file_citation" }, { "name": "place_id / name / url / review_snippets[]{review_id,title,url}", "type": "mixed", "required": false, "description": "place_citation" }, { "name": "text / start_offset / end_offset / speaker", "type": "mixed", "required": false, "description": "word_info (ASR word timing & diarization)" } ], "status": [ "DOCUMENTED", "BETA" ], "example": null, "sources": [ { "url": "https://ai.google.dev/api/interactions", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/gemini-tools-agents-objects.json" }, { "provider": "gemini", "api_family": "interactions", "name": "Tool (union)", "object": null, "schema_name": "Tool", "description": "Tool declaration (discriminator `type`).", "fields": [ { "name": "type", "type": "string", "required": true, "description": "", "enum": [ "function", "google_search", "google_maps", "code_execution", "url_context", "file_search", "mcp_server", "computer_use" ] } ], "status": [ "DOCUMENTED", "BETA" ], "example": null, "sources": [ { "url": "https://ai.google.dev/api/interactions", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/gemini-tools-agents-objects.json" }, { "provider": "gemini", "api_family": "interactions", "name": "Function tool", "object": null, "schema_name": "Function", "description": "Client-side function declaration; model emits `function_call` steps (status requires_action), client answers with `function_result`.", "fields": [ { "name": "type", "type": "string", "required": true, "description": "", "enum": [ "function" ] }, { "name": "name", "type": "string", "required": false, "description": "" }, { "name": "description", "type": "string", "required": false, "description": "" }, { "name": "parameters", "type": "object (JSON Schema)", "required": false, "description": "" } ], "status": [ "DOCUMENTED", "BETA" ], "example": { "type": "function", "name": "get_weather", "description": "Get the current weather in a given location", "parameters": { "type": "object", "properties": { "location": { "type": "string" } }, "required": [ "location" ] } }, "sources": [ { "url": "https://ai.google.dev/api/interactions", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/gemini-tools-agents-objects.json" }, { "provider": "gemini", "api_family": "interactions", "name": "GoogleSearch tool", "object": null, "schema_name": "GoogleSearch", "description": "Server-side Google Search grounding (web and/or image search).", "fields": [ { "name": "type", "type": "string", "required": true, "description": "", "enum": [ "google_search" ] }, { "name": "search_types", "type": "string[]", "required": false, "description": "", "enum": [ "web_search", "image_search" ] } ], "status": [ "DOCUMENTED", "BETA" ], "example": { "type": "google_search" }, "sources": [ { "url": "https://ai.google.dev/api/interactions", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/gemini-tools-agents-objects.json" }, { "provider": "gemini", "api_family": "interactions", "name": "GoogleMaps tool", "object": null, "schema_name": "GoogleMaps", "description": "Server-side Google Maps grounding.", "fields": [ { "name": "type", "type": "string", "required": true, "description": "", "enum": [ "google_maps" ] }, { "name": "latitude", "type": "number", "required": false, "description": "" }, { "name": "longitude", "type": "number", "required": false, "description": "" }, { "name": "enable_widget", "type": "boolean", "required": false, "description": "return widget context token" } ], "status": [ "DOCUMENTED", "BETA" ], "example": { "type": "google_maps", "latitude": 37.7749, "longitude": -122.4194 }, "sources": [ { "url": "https://ai.google.dev/api/interactions", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/gemini-tools-agents-objects.json" }, { "provider": "gemini", "api_family": "interactions", "name": "CodeExecution tool", "object": null, "schema_name": "CodeExecution", "description": "Server-side Python sandbox (>= 3.10, numpy, simpy) → code_execution_call/result steps.", "fields": [ { "name": "type", "type": "string", "required": true, "description": "", "enum": [ "code_execution" ] } ], "status": [ "DOCUMENTED", "BETA" ], "example": { "type": "code_execution" }, "sources": [ { "url": "https://ai.google.dev/api/interactions", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/gemini-tools-agents-objects.json" }, { "provider": "gemini", "api_family": "interactions", "name": "UrlContext tool", "object": null, "schema_name": "UrlContext", "description": "Server-side URL fetching → url_context_call/result steps.", "fields": [ { "name": "type", "type": "string", "required": true, "description": "", "enum": [ "url_context" ] } ], "status": [ "DOCUMENTED", "BETA" ], "example": { "type": "url_context" }, "sources": [ { "url": "https://ai.google.dev/api/interactions", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/gemini-tools-agents-objects.json" }, { "provider": "gemini", "api_family": "interactions", "name": "FileSearch tool", "object": null, "schema_name": "FileSearch", "description": "Retrieval over File Search stores → file_search_call/result steps + file_citation annotations.", "fields": [ { "name": "type", "type": "string", "required": true, "description": "", "enum": [ "file_search" ] }, { "name": "file_search_store_names", "type": "string[]", "required": false, "description": "fileSearchStores/..." }, { "name": "metadata_filter", "type": "string", "required": false, "description": "" }, { "name": "top_k", "type": "integer", "required": false, "description": "" } ], "status": [ "DOCUMENTED", "BETA" ], "example": { "type": "file_search", "file_search_store_names": [ "fileSearchStores/m64d1sevsr4y-xfyawui3fxqg" ] }, "sources": [ { "url": "https://ai.google.dev/api/interactions", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/gemini-tools-agents-objects.json" }, { "provider": "gemini", "api_family": "interactions", "name": "McpServer tool", "object": null, "schema_name": "McpServer", "description": "Remote MCP server (streamable HTTP) called server-side → mcp_server_tool_call/result steps. Not supported by Gemini 3 models yet ('coming soon'); supported by Deep Research and Antigravity.", "fields": [ { "name": "type", "type": "string", "required": true, "description": "", "enum": [ "mcp_server" ] }, { "name": "name", "type": "string", "required": false, "description": "Antigravity: required, ^[a-z0-9_-]+$" }, { "name": "url", "type": "string", "required": false, "description": "" }, { "name": "headers", "type": "object", "required": false, "description": "" }, { "name": "credential", "type": "string", "required": false, "description": "stored credential id (guides)" }, { "name": "allowed_tools", "type": "AllowedTools[] {mode, tools[]} | string[]", "required": false, "description": "" } ], "status": [ "DOCUMENTED", "BETA" ], "example": { "type": "mcp_server", "name": "weather_service", "url": "https://gemini-api-demos.uc.r.appspot.com/mcp" }, "sources": [ { "url": "https://ai.google.dev/api/interactions", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/gemini-tools-agents-objects.json" }, { "provider": "gemini", "api_family": "interactions", "name": "ComputerUse tool", "object": null, "schema_name": "ComputerUse", "description": "Computer-use tool (model gemini-2.5-computer-use-preview-10-2025).", "fields": [ { "name": "type", "type": "string", "required": true, "description": "", "enum": [ "computer_use" ] }, { "name": "environment", "type": "string", "required": false, "description": "", "enum": [ "browser", "mobile", "desktop" ] }, { "name": "disabled_safety_policies", "type": "string[]", "required": false, "description": "", "enum": [ "financial_transactions", "sensitive_data_modification", "communication_tool", "account_creation", "data_modification", "user_consent_management", "legal_terms_and_agreements" ] }, { "name": "enable_prompt_injection_detection", "type": "boolean", "required": false, "description": "" }, { "name": "excluded_predefined_functions", "type": "string[]", "required": false, "description": "" } ], "status": [ "DOCUMENTED", "BETA" ], "example": { "type": "computer_use" }, "sources": [ { "url": "https://ai.google.dev/api/interactions", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/gemini-tools-agents-objects.json" }, { "provider": "gemini", "api_family": "interactions", "name": "ToolChoiceConfig", "object": null, "schema_name": "ToolChoiceConfig", "description": "Object form of generation_config.tool_choice.", "fields": [ { "name": "allowed_tools", "type": "AllowedTools", "required": false, "description": "" }, { "name": "allowed_tools.mode", "type": "string", "required": false, "description": "", "enum": [ "auto", "any", "none", "validated" ] }, { "name": "allowed_tools.tools", "type": "string[]", "required": false, "description": "" } ], "status": [ "DOCUMENTED", "BETA" ], "example": { "allowed_tools": { "mode": "any", "tools": [ "my_tool" ] } }, "sources": [ { "url": "https://ai.google.dev/api/interactions", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/gemini-tools-agents-objects.json" }, { "provider": "gemini", "api_family": "interactions", "name": "GenerationConfig", "object": null, "schema_name": "GenerationConfig", "description": "Model configuration (model interactions only).", "fields": [ { "name": "max_output_tokens", "type": "integer", "required": false, "description": "" }, { "name": "seed", "type": "integer", "required": false, "description": "" }, { "name": "stop_sequences", "type": "string[]", "required": false, "description": "" }, { "name": "temperature", "type": "number", "required": false, "description": "guide only (UNVERIFIED in reference)" }, { "name": "thinking_level", "type": "string", "required": false, "description": "", "enum": [ "minimal", "low", "medium", "high" ] }, { "name": "thinking_summaries", "type": "string", "required": false, "description": "", "enum": [ "auto", "none" ] }, { "name": "tool_choice", "type": "string | ToolChoiceConfig", "required": false, "description": "" }, { "name": "speech_config", "type": "SpeakerConfig | SpeechConfig[]", "required": false, "description": "{speakers[]{speaker, voice, language}}" }, { "name": "transcription_config", "type": "TranscriptionConfig", "required": false, "description": "{custom_vocabulary[], language_codes[], mode}" }, { "name": "video_config", "type": "VideoConfig", "required": false, "description": "{task}" } ], "status": [ "DOCUMENTED", "BETA" ], "example": null, "sources": [ { "url": "https://ai.google.dev/api/interactions", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/gemini-tools-agents-objects.json" }, { "provider": "gemini", "api_family": "interactions", "name": "TranscriptionConfig", "object": null, "schema_name": "TranscriptionConfig", "description": "ASR configuration inside generation_config.", "fields": [ { "name": "custom_vocabulary", "type": "string[]", "required": false, "description": "" }, { "name": "language_codes", "type": "string[]", "required": false, "description": "BCP-47" }, { "name": "mode", "type": "'verbatim' | 'smart' | {type:'smart'} | {type:'verbatim', diarization_mode:'speaker', timestamp_granularities:['word']}", "required": false, "description": "" } ], "status": [ "DOCUMENTED", "BETA" ], "example": null, "sources": [ { "url": "https://ai.google.dev/api/interactions", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/gemini-tools-agents-objects.json" }, { "provider": "gemini", "api_family": "interactions", "name": "ResponseFormat (union)", "object": null, "schema_name": "ResponseFormat", "description": "Output format entry (discriminator `type`); array for multi-modal output.", "fields": [ { "name": "type", "type": "string", "required": true, "description": "", "enum": [ "text", "image", "audio", "video" ] } ], "status": [ "DOCUMENTED", "BETA" ], "example": null, "sources": [ { "url": "https://ai.google.dev/api/interactions", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/gemini-tools-agents-objects.json" }, { "provider": "gemini", "api_family": "interactions", "name": "TextResponseFormat", "object": null, "schema_name": "TextResponseFormat", "description": "Text / structured JSON output.", "fields": [ { "name": "type", "type": "string", "required": true, "description": "", "enum": [ "text" ] }, { "name": "mime_type", "type": "string", "required": false, "description": "", "enum": [ "application/json", "text/plain" ] }, { "name": "schema", "type": "object (JSON Schema)", "required": false, "description": "only with application/json" } ], "status": [ "DOCUMENTED", "BETA" ], "example": { "type": "text", "mime_type": "application/json", "schema": { "type": "object", "properties": { "recipe_name": { "type": "string" } }, "required": [ "recipe_name" ] } }, "sources": [ { "url": "https://ai.google.dev/api/interactions", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/gemini-tools-agents-objects.json" }, { "provider": "gemini", "api_family": "interactions", "name": "ImageResponseFormat", "object": null, "schema_name": "ImageResponseFormat", "description": "Image output settings (replaces generation_config.image_config).", "fields": [ { "name": "type", "type": "string", "required": true, "description": "", "enum": [ "image" ] }, { "name": "aspect_ratio", "type": "string", "required": false, "description": "", "enum": [ "1:1", "2:3", "3:2", "3:4", "4:3", "4:5", "5:4", "9:16", "16:9", "21:9", "1:8", "8:1", "1:4", "4:1" ] }, { "name": "image_size", "type": "string", "required": false, "description": "", "enum": [ "512", "1K", "2K", "4K" ] }, { "name": "mime_type", "type": "string", "required": false, "description": "", "enum": [ "image/jpeg" ] }, { "name": "delivery", "type": "string", "required": false, "description": "", "enum": [ "inline", "uri" ] } ], "status": [ "DOCUMENTED", "BETA" ], "example": { "type": "image", "aspect_ratio": "16:9", "image_size": "1K", "mime_type": "image/jpeg" }, "sources": [ { "url": "https://ai.google.dev/api/interactions", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/gemini-tools-agents-objects.json" }, { "provider": "gemini", "api_family": "interactions", "name": "AudioResponseFormat", "object": null, "schema_name": "AudioResponseFormat", "description": "Audio output settings.", "fields": [ { "name": "type", "type": "string", "required": true, "description": "", "enum": [ "audio" ] }, { "name": "mime_type", "type": "string", "required": false, "description": "", "enum": [ "audio/mp3", "audio/ogg_opus", "audio/l16", "audio/wav", "audio/alaw", "audio/mulaw" ] }, { "name": "sample_rate", "type": "integer", "required": false, "description": "Hz" }, { "name": "bit_rate", "type": "integer", "required": false, "description": "bps, compressed only" }, { "name": "delivery", "type": "string", "required": false, "description": "", "enum": [ "inline", "uri" ] } ], "status": [ "DOCUMENTED", "BETA" ], "example": { "type": "audio", "sample_rate": 24000 }, "sources": [ { "url": "https://ai.google.dev/api/interactions", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/gemini-tools-agents-objects.json" }, { "provider": "gemini", "api_family": "interactions", "name": "VideoResponseFormat", "object": null, "schema_name": "VideoResponseFormat", "description": "Video output settings.", "fields": [ { "name": "type", "type": "string", "required": true, "description": "", "enum": [ "video" ] }, { "name": "aspect_ratio", "type": "string", "required": false, "description": "", "enum": [ "16:9", "9:16" ] }, { "name": "resolution", "type": "string", "required": false, "description": "default 720p", "enum": [ "360p", "720p", "1080p", "4k" ] }, { "name": "duration", "type": "string", "required": false, "description": "" }, { "name": "delivery", "type": "string", "required": false, "description": "", "enum": [ "inline", "uri" ] } ], "status": [ "DOCUMENTED", "BETA" ], "example": { "type": "video", "aspect_ratio": "16:9", "delivery": "inline" }, "sources": [ { "url": "https://ai.google.dev/api/interactions", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/gemini-tools-agents-objects.json" }, { "provider": "gemini", "api_family": "interactions", "name": "Step (union)", "object": null, "schema_name": "Step", "description": "One entry of the interaction timeline (discriminator `type`). POST returns model-generated steps; GET adds `user_input`. Steps can be replayed in `input` for stateless history.", "fields": [ { "name": "type", "type": "string", "required": true, "description": "", "enum": [ "user_input", "model_output", "thought", "function_call", "function_result", "code_execution_call", "code_execution_result", "google_search_call", "google_search_result", "google_maps_call", "google_maps_result", "url_context_call", "url_context_result", "file_search_call", "file_search_result", "mcp_server_tool_call", "mcp_server_tool_result", "processing_call", "processing_result" ] } ], "status": [ "DOCUMENTED", "BETA" ], "example": null, "sources": [ { "url": "https://ai.google.dev/api/interactions", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/gemini-tools-agents-objects.json" }, { "provider": "gemini", "api_family": "interactions", "name": "UserInputStep", "object": null, "schema_name": "UserInputStep", "description": "User turn.", "fields": [ { "name": "type", "type": "string", "required": true, "description": "", "enum": [ "user_input" ] }, { "name": "content", "type": "Content[]", "required": false, "description": "" } ], "status": [ "DOCUMENTED", "BETA" ], "example": { "type": "user_input", "content": [ { "type": "text", "text": "What is the capital of France?" } ] }, "sources": [ { "url": "https://ai.google.dev/api/interactions", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/gemini-tools-agents-objects.json" }, { "provider": "gemini", "api_family": "interactions", "name": "ModelOutputStep", "object": null, "schema_name": "ModelOutputStep", "description": "Final model content.", "fields": [ { "name": "type", "type": "string", "required": true, "description": "", "enum": [ "model_output" ] }, { "name": "content", "type": "Content[]", "required": false, "description": "" } ], "status": [ "DOCUMENTED", "BETA" ], "example": { "type": "model_output", "content": [ { "type": "text", "text": "The capital of France is Paris." } ] }, "sources": [ { "url": "https://ai.google.dev/api/interactions", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/gemini-tools-agents-objects.json" }, { "provider": "gemini", "api_family": "interactions", "name": "ThoughtStep", "object": null, "schema_name": "ThoughtStep", "description": "Reasoning step; `signature` for stateless replay, `summary` when thinking_summaries=auto.", "fields": [ { "name": "type", "type": "string", "required": true, "description": "", "enum": [ "thought" ] }, { "name": "signature", "type": "string", "required": false, "description": "" }, { "name": "summary", "type": "(TextContent|ImageContent)[]", "required": false, "description": "" } ], "status": [ "DOCUMENTED", "BETA" ], "example": { "type": "thought", "signature": "thought_sig_abcd1234", "summary": [ { "type": "text", "text": "The model is searching Google..." } ] }, "sources": [ { "url": "https://ai.google.dev/api/interactions", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/gemini-tools-agents-objects.json" }, { "provider": "gemini", "api_family": "interactions", "name": "FunctionCallStep", "object": null, "schema_name": "FunctionCallStep", "description": "Model requests a client function; interaction status becomes requires_action.", "fields": [ { "name": "type", "type": "string", "required": true, "description": "", "enum": [ "function_call" ] }, { "name": "id", "type": "string", "required": true, "description": "call id" }, { "name": "name", "type": "string", "required": true, "description": "" }, { "name": "arguments", "type": "object", "required": true, "description": "" } ], "status": [ "DOCUMENTED", "BETA" ], "example": { "name": "get_weather", "type": "function_call", "arguments": { "location": "Boston, MA" }, "id": "call_98231" }, "sources": [ { "url": "https://ai.google.dev/api/interactions", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/gemini-tools-agents-objects.json" }, { "provider": "gemini", "api_family": "interactions", "name": "FunctionResultStep", "object": null, "schema_name": "FunctionResultStep", "description": "Client-provided function result (in `input`).", "fields": [ { "name": "type", "type": "string", "required": true, "description": "", "enum": [ "function_result" ] }, { "name": "call_id", "type": "string", "required": true, "description": "matches FunctionCallStep.id" }, { "name": "name", "type": "string", "required": false, "description": "" }, { "name": "result", "type": "string | object | (TextContent|ImageContent)[]", "required": true, "description": "" }, { "name": "is_error", "type": "boolean", "required": false, "description": "" } ], "status": [ "DOCUMENTED", "BETA" ], "example": { "name": "get_weather", "type": "function_result", "call_id": "call_98231", "result": [ { "type": "text", "text": "{\"weather\":\"sunny\"}" } ] }, "sources": [ { "url": "https://ai.google.dev/api/interactions", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/gemini-tools-agents-objects.json" }, { "provider": "gemini", "api_family": "interactions", "name": "CodeExecutionCallStep / CodeExecutionResultStep", "object": null, "schema_name": "CodeExecutionCallStep|CodeExecutionResultStep", "description": "Server-side code execution pair.", "fields": [ { "name": "type", "type": "string", "required": true, "description": "", "enum": [ "code_execution_call", "code_execution_result" ] }, { "name": "id", "type": "string", "required": true, "description": "call step" }, { "name": "arguments", "type": "{code, language: python}", "required": true, "description": "call step" }, { "name": "call_id", "type": "string", "required": true, "description": "result step" }, { "name": "result", "type": "string", "required": true, "description": "result step (stdout)" }, { "name": "is_error", "type": "boolean", "required": false, "description": "" }, { "name": "signature", "type": "string", "required": false, "description": "" } ], "status": [ "DOCUMENTED", "BETA" ], "example": { "type": "code_execution_result", "call_id": "code_call_71021", "result": "55\n" }, "sources": [ { "url": "https://ai.google.dev/api/interactions", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/gemini-tools-agents-objects.json" }, { "provider": "gemini", "api_family": "interactions", "name": "GoogleSearchCallStep / GoogleSearchResultStep", "object": null, "schema_name": "GoogleSearchCallStep|GoogleSearchResultStep", "description": "Server-side search pair.", "fields": [ { "name": "type", "type": "string", "required": true, "description": "", "enum": [ "google_search_call", "google_search_result" ] }, { "name": "id", "type": "string", "required": true, "description": "" }, { "name": "arguments", "type": "{queries: string[]}", "required": true, "description": "call" }, { "name": "search_type", "type": "string", "required": false, "description": "call", "enum": [ "web_search", "image_search" ] }, { "name": "call_id", "type": "string", "required": true, "description": "result" }, { "name": "result", "type": "GoogleSearchResultItem[] {search_suggestions}", "required": true, "description": "result" }, { "name": "is_error", "type": "boolean", "required": false, "description": "" }, { "name": "signature", "type": "string", "required": false, "description": "" } ], "status": [ "DOCUMENTED", "BETA" ], "example": null, "sources": [ { "url": "https://ai.google.dev/api/interactions", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/gemini-tools-agents-objects.json" }, { "provider": "gemini", "api_family": "interactions", "name": "GoogleMapsCallStep / GoogleMapsResultStep", "object": null, "schema_name": "GoogleMapsCallStep|GoogleMapsResultStep", "description": "Server-side Maps pair.", "fields": [ { "name": "type", "type": "string", "required": true, "description": "", "enum": [ "google_maps_call", "google_maps_result" ] }, { "name": "id", "type": "string", "required": true, "description": "" }, { "name": "arguments", "type": "{queries: string[]}", "required": false, "description": "call" }, { "name": "call_id", "type": "string", "required": true, "description": "result" }, { "name": "result", "type": "GoogleMapsResultItem[] {places[]{name, place_id, url, review_snippets[]}, widget_context_token}", "required": true, "description": "result" }, { "name": "signature", "type": "string", "required": false, "description": "" } ], "status": [ "DOCUMENTED", "BETA" ], "example": null, "sources": [ { "url": "https://ai.google.dev/api/interactions", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/gemini-tools-agents-objects.json" }, { "provider": "gemini", "api_family": "interactions", "name": "UrlContextCallStep / UrlContextResultStep", "object": null, "schema_name": "UrlContextCallStep|UrlContextResultStep", "description": "Server-side URL fetch pair.", "fields": [ { "name": "type", "type": "string", "required": true, "description": "", "enum": [ "url_context_call", "url_context_result" ] }, { "name": "id", "type": "string", "required": true, "description": "" }, { "name": "arguments", "type": "{urls: string[]}", "required": true, "description": "call" }, { "name": "call_id", "type": "string", "required": true, "description": "result" }, { "name": "result", "type": "UrlContextResult[] {url, status: success|error|paywall|unsafe}", "required": true, "description": "result" }, { "name": "is_error", "type": "boolean", "required": false, "description": "" }, { "name": "signature", "type": "string", "required": false, "description": "" } ], "status": [ "DOCUMENTED", "BETA" ], "example": { "type": "url_context_call", "arguments": { "urls": [ "https://www.example.com" ] }, "id": "url_call_10219" }, "sources": [ { "url": "https://ai.google.dev/api/interactions", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/gemini-tools-agents-objects.json" }, { "provider": "gemini", "api_family": "interactions", "name": "FileSearchCallStep / FileSearchResultStep", "object": null, "schema_name": "FileSearchCallStep|FileSearchResultStep", "description": "Server-side File Search pair.", "fields": [ { "name": "type", "type": "string", "required": true, "description": "", "enum": [ "file_search_call", "file_search_result" ] }, { "name": "id", "type": "string", "required": true, "description": "call" }, { "name": "call_id", "type": "string", "required": true, "description": "result" }, { "name": "signature", "type": "string", "required": false, "description": "" } ], "status": [ "DOCUMENTED", "BETA" ], "example": { "type": "file_search_call", "id": "file_call_88192" }, "sources": [ { "url": "https://ai.google.dev/api/interactions", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/gemini-tools-agents-objects.json" }, { "provider": "gemini", "api_family": "interactions", "name": "McpServerToolCallStep / McpServerToolResultStep", "object": null, "schema_name": "McpServerToolCallStep|McpServerToolResultStep", "description": "Remote MCP tool pair.", "fields": [ { "name": "type", "type": "string", "required": true, "description": "", "enum": [ "mcp_server_tool_call", "mcp_server_tool_result" ] }, { "name": "id", "type": "string", "required": true, "description": "call" }, { "name": "name", "type": "string", "required": true, "description": "tool name" }, { "name": "server_name", "type": "string", "required": true, "description": "" }, { "name": "arguments", "type": "object", "required": true, "description": "call" }, { "name": "call_id", "type": "string", "required": true, "description": "result" }, { "name": "result", "type": "string | object | (TextContent|ImageContent)[]", "required": true, "description": "result" } ], "status": [ "DOCUMENTED", "BETA" ], "example": { "name": "calculate_tax", "type": "mcp_server_tool_call", "arguments": { "income": 120000, "state": "CA" }, "id": "mcp_call_29012", "server_name": "financial_mcp_server" }, "sources": [ { "url": "https://ai.google.dev/api/interactions", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/gemini-tools-agents-objects.json" }, { "provider": "gemini", "api_family": "interactions", "name": "ProcessingCallStep / ProcessingResultStep", "object": null, "schema_name": "ProcessingCallStep|ProcessingResultStep", "description": "Server-initiated media processing (e.g. agentic video understanding).", "fields": [ { "name": "type", "type": "string", "required": true, "description": "", "enum": [ "processing_call", "processing_result" ] }, { "name": "id", "type": "string", "required": true, "description": "call" }, { "name": "call_id", "type": "string", "required": true, "description": "result" }, { "name": "signature", "type": "string", "required": false, "description": "" } ], "status": [ "DOCUMENTED", "BETA" ], "example": null, "sources": [ { "url": "https://ai.google.dev/api/interactions", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/gemini-tools-agents-objects.json" }, { "provider": "gemini", "api_family": "agents", "name": "AntigravityAgentConfig", "object": null, "schema_name": "AntigravityAgentConfig", "description": "agent_config for antigravity-* agents.", "fields": [ { "name": "type", "type": "string", "required": true, "description": "", "enum": [ "antigravity" ] }, { "name": "model", "type": "string", "required": false, "description": "default gemini-3.8-flash", "enum": [ "gemini-3.8-flash", "gemini-3.7-flash", "gemini-3.6-flash", "gemini-3.5-flash", "gemini-3.5-flash-lite" ] }, { "name": "max_total_tokens", "type": "string|integer", "required": false, "description": "token budget → status incomplete" } ], "status": [ "DOCUMENTED", "PREVIEW" ], "example": { "type": "antigravity", "model": "gemini-3.8-flash", "max_total_tokens": 50000 }, "sources": [ { "url": "https://ai.google.dev/api/interactions", "retrieved_at": "2026-09-18" }, { "url": "https://ai.google.dev/gemini-api/docs/antigravity-agent", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/gemini-tools-agents-objects.json" }, { "provider": "gemini", "api_family": "agents", "name": "DeepResearchAgentConfig", "object": null, "schema_name": "DeepResearchAgentConfig", "description": "agent_config for deep-research-* agents.", "fields": [ { "name": "type", "type": "string", "required": true, "description": "", "enum": [ "deep-research" ] }, { "name": "collaborative_planning", "type": "boolean", "required": false, "description": "" }, { "name": "thinking_summaries", "type": "string", "required": false, "description": "", "enum": [ "auto", "none" ] }, { "name": "visualization", "type": "string", "required": false, "description": "", "enum": [ "off", "auto" ] } ], "status": [ "DOCUMENTED", "PREVIEW" ], "example": { "type": "deep-research", "thinking_summaries": "auto", "collaborative_planning": true }, "sources": [ { "url": "https://ai.google.dev/api/interactions", "retrieved_at": "2026-09-18" }, { "url": "https://ai.google.dev/gemini-api/docs/deep-research", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/gemini-tools-agents-objects.json" }, { "provider": "gemini", "api_family": "agents", "name": "DynamicAgentConfig", "object": null, "schema_name": "DynamicAgentConfig", "description": "agent_config `{type: dynamic}` — only config type in the v1 surface; no other fields documented (v1 page also lists a top-level `max_total_tokens`). Relation to `dynamic/*:generateContent` unknown.", "fields": [ { "name": "type", "type": "string", "required": true, "description": "", "enum": [ "dynamic" ] } ], "status": [ "DOCUMENTED", "UNVERIFIED", "DOCUMENTATION_INCOMPLETE" ], "example": null, "sources": [ { "url": "https://ai.google.dev/api/interactions", "retrieved_at": "2026-09-18" }, { "url": "https://ai.google.dev/api/interactions-api-v1", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/gemini-tools-agents-objects.json" }, { "provider": "gemini", "api_family": "agents", "name": "CodeMenderAgentConfig", "object": null, "schema_name": "CodeMenderAgentConfig", "description": "Named in the agent_config union on the reference page; no fields, no agent id documented.", "fields": [], "status": [ "DOCUMENTED", "DOCUMENTATION_INCOMPLETE" ], "example": null, "sources": [ { "url": "https://ai.google.dev/api/interactions", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/gemini-tools-agents-objects.json" }, { "provider": "gemini", "api_family": "agents", "name": "Agent (custom managed agent)", "object": "agent", "schema_name": "Agent", "description": "Saved agent definition (POST/GET /v1beta/agents). Fields from the guide's definition reference + SDK type.", "fields": [ { "name": "id", "type": "string", "required": true, "description": "unique; reserved prefixes forbidden" }, { "name": "description", "type": "string", "required": false, "description": "" }, { "name": "base_agent", "type": "string", "required": true, "description": "antigravity-preview-09-2026" }, { "name": "agent_config", "type": "AntigravityAgentConfig", "required": false, "description": "model locked at creation" }, { "name": "system_instruction", "type": "string", "required": false, "description": "" }, { "name": "tools", "type": "Tool[]", "required": false, "description": "code_execution, google_search, url_context, mcp_server, function" }, { "name": "base_environment", "type": "string | EnvironmentConfig", "required": false, "description": "'remote' | env id | config" } ], "status": [ "DOCUMENTED", "PREVIEW" ], "example": { "id": "data-analyst", "base_agent": "antigravity-preview-09-2026", "agent_config": { "type": "antigravity", "model": "gemini-3.8-flash" }, "system_instruction": "You are a data analyst.", "base_environment": { "type": "remote", "sources": [ { "type": "inline", "target": ".agents/AGENTS.md", "content": "Always use matplotlib." } ] } }, "sources": [ { "url": "https://ai.google.dev/gemini-api/docs/custom-agents", "retrieved_at": "2026-09-18" }, { "url": "https://ai.google.dev/api/interactions", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/gemini-tools-agents-objects.json" }, { "provider": "gemini", "api_family": "agents", "name": "Trigger", "object": null, "schema_name": "Trigger", "description": "Cron-scheduled agent run (POST /v1beta/triggers). Fields from the guide + SDK type.", "fields": [ { "name": "id", "type": "string", "required": true, "description": "" }, { "name": "schedule", "type": "string (cron)", "required": true, "description": "" }, { "name": "time_zone", "type": "string", "required": true, "description": "" }, { "name": "interaction", "type": "CreateInteractionRequest", "required": true, "description": "" }, { "name": "display_name", "type": "string", "required": false, "description": "" }, { "name": "status", "type": "string", "required": false, "description": "", "enum": [ "active", "paused", "disabled" ] }, { "name": "max_consecutive_failures", "type": "integer", "required": false, "description": "default 5" }, { "name": "execution_timeout_seconds", "type": "integer", "required": false, "description": "default 600" }, { "name": "consecutive_failure_count", "type": "integer", "required": false, "description": "" }, { "name": "next_run_time", "type": "string", "required": false, "description": "" }, { "name": "last_run_time", "type": "string", "required": false, "description": "" }, { "name": "last_pause_time / last_resume_time", "type": "string", "required": false, "description": "" }, { "name": "environment_id", "type": "string", "required": false, "description": "shared sandbox" }, { "name": "previous_interaction_id", "type": "string", "required": false, "description": "" }, { "name": "create_time / update_time", "type": "string", "required": false, "description": "" } ], "status": [ "DOCUMENTED", "PREVIEW" ], "example": null, "sources": [ { "url": "https://ai.google.dev/gemini-api/docs/antigravity-agent", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/gemini-tools-agents-objects.json" }, { "provider": "gemini", "api_family": "agents", "name": "TriggerExecution", "object": null, "schema_name": "TriggerExecution", "description": "One run of a trigger (GET/POST /v1beta/triggers/{id}/executions).", "fields": [ { "name": "status", "type": "string", "required": false, "description": "" }, { "name": "interaction_id", "type": "string", "required": false, "description": "fetch output via GET /interactions/{id}" }, { "name": "environment_id", "type": "string", "required": false, "description": "" }, { "name": "timestamps", "type": "string", "required": false, "description": "start/end (names not documented)" } ], "status": [ "DOCUMENTED", "PREVIEW", "DOCUMENTATION_INCOMPLETE" ], "example": null, "sources": [ { "url": "https://ai.google.dev/gemini-api/docs/antigravity-agent", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/gemini-tools-agents-objects.json" }, { "provider": "gemini", "api_family": "agents", "name": "hooks.json (HooksConfig)", "object": null, "schema_name": "HooksConfig", "description": "File `.agents/hooks.json` mounted in the sandbox: map of group name → {enabled?, pre_tool_execution[] | post_tool_execution[]: [{matcher (RE2 regex on container tool name), hooks: [{type: command, command, timeout=30} | {type: http, url, headers?, timeout=30}]}]}. pre hooks read the tool_call JSON on stdin and answer {decision: allow|deny, reason}. Failures/timeouts = allow.", "fields": [ { "name": ".enabled", "type": "boolean", "required": false, "description": "default true" }, { "name": ".pre_tool_execution[].matcher", "type": "string (RE2)", "required": false, "description": "code_execution | view_file | write_to_file | replace_file_content | list_dir | delete_file | .*" }, { "name": ".pre_tool_execution[].hooks[]", "type": "CommandHook | HttpHook", "required": false, "description": "" }, { "name": ".post_tool_execution[]", "type": "same shape", "required": false, "description": "cannot block" } ], "status": [ "DOCUMENTED", "PREVIEW" ], "example": { "security-gate": { "pre_tool_execution": [ { "matcher": "code_execution", "hooks": [ { "type": "command", "command": "python3 /.agents/hooks-scripts/gate.py", "timeout": 10 } ] } ] } }, "sources": [ { "url": "https://ai.google.dev/gemini-api/docs/agent-hooks", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/gemini-tools-agents-objects.json" }, { "provider": "gemini", "api_family": "environments", "name": "EnvironmentConfig (interaction `environment` object)", "object": null, "schema_name": "EnvironmentConfig", "description": "Sandbox configuration passed as `environment` on POST /v1beta/interactions (or `base_environment` on agents).", "fields": [ { "name": "type", "type": "string", "required": true, "description": "", "enum": [ "remote" ] }, { "name": "environment_id", "type": "string", "required": false, "description": "update existing env instead of creating" }, { "name": "sources", "type": "Source[]", "required": false, "description": "" }, { "name": "network", "type": "'disabled' | EnvironmentNetworkEgressAllowlist", "required": false, "description": "" }, { "name": "env", "type": "map", "required": false, "description": "" } ], "status": [ "DOCUMENTED", "BETA" ], "example": { "type": "remote", "sources": [ { "type": "repository", "source": "https://github.com/my-org/my-skills.git", "target": ".agents/skills" }, { "type": "gcs", "source": "gs://my-bucket/my-folder", "target": "/workspace/data" } ], "network": { "allowlist": [ { "domain": "pypi.org" }, { "domain": "*.github.com" } ] } }, "sources": [ { "url": "https://ai.google.dev/api/interactions", "retrieved_at": "2026-09-18" }, { "url": "https://ai.google.dev/gemini-api/docs/agent-environment", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/gemini-tools-agents-objects.json" }, { "provider": "gemini", "api_family": "environments", "name": "Source", "object": null, "schema_name": "Source", "description": "Mounted source (inline ≤1 MB/file, 2 MB total; repository ≤500 MB; gcs ≤2 GB; target ≠ `/`).", "fields": [ { "name": "type", "type": "string", "required": false, "description": "", "enum": [ "gcs", "inline", "repository" ] }, { "name": "source", "type": "string", "required": false, "description": "gs:// path or repo URL" }, { "name": "target", "type": "string", "required": false, "description": "" }, { "name": "content", "type": "string", "required": false, "description": "inline" }, { "name": "encoding", "type": "string", "required": false, "description": "e.g. base64" } ], "status": [ "DOCUMENTED", "BETA" ], "example": { "type": "inline", "content": "print('Hello, World!')", "target": "main.py" }, "sources": [ { "url": "https://ai.google.dev/api/environments", "retrieved_at": "2026-09-18" }, { "url": "https://ai.google.dev/gemini-api/docs/agent-environment", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/gemini-tools-agents-objects.json" }, { "provider": "gemini", "api_family": "environments", "name": "EnvironmentNetworkEgressAllowlist", "object": null, "schema_name": "EnvironmentNetworkEgressAllowlist", "description": "Outbound allowlist {allowlist: AllowlistEntry[]}; or the string 'disabled'; omit = unrestricted. Discovery doc: items are `EgressRule`.", "fields": [ { "name": "allowlist", "type": "AllowlistEntry[]", "required": false, "description": "" } ], "status": [ "DOCUMENTED", "BETA" ], "example": { "allowlist": [ { "domain": "github.com", "transform": [ { "Authorization": "Bearer your-token" } ] }, { "domain": "*.googleapis.com" } ] }, "sources": [ { "url": "https://ai.google.dev/api/interactions", "retrieved_at": "2026-09-18" }, { "url": "https://ai.google.dev/api/environments", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/gemini-tools-agents-objects.json" }, { "provider": "gemini", "api_family": "environments", "name": "AllowlistEntry (EgressRule)", "object": null, "schema_name": "AllowlistEntry", "description": "One egress rule.", "fields": [ { "name": "domain", "type": "string", "required": false, "description": "exact host, `*.sub` wildcard, or `*`" }, { "name": "credential", "type": "string", "required": false, "description": "stored credential id" }, { "name": "transform", "type": "object | object[]", "required": false, "description": "headers to inject; merged over credential" } ], "status": [ "DOCUMENTED", "BETA" ], "example": { "domain": "api.atlassian.com", "credential": "jira-oauth", "transform": { "X-Atlassian-Workspace": "my-workspace-id" } }, "sources": [ { "url": "https://ai.google.dev/api/environments", "retrieved_at": "2026-09-18" }, { "url": "https://ai.google.dev/gemini-api/docs/agent-credentials", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/gemini-tools-agents-objects.json" }, { "provider": "gemini", "api_family": "environments", "name": "EnvVar", "object": null, "schema_name": "EnvVar", "description": "Value of an `environment.env` entry.", "fields": [ { "name": "credential", "type": "string", "required": false, "description": "credential id → placeholder __GEMINI_CRED___" }, { "name": "value", "type": "string", "required": false, "description": "plaintext literal" } ], "status": [ "DOCUMENTED", "BETA" ], "example": null, "sources": [ { "url": "https://ai.google.dev/api/interactions", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/gemini-tools-agents-objects.json" }, { "provider": "gemini", "api_family": "environments", "name": "Environment", "object": null, "schema_name": "Environment", "description": "Sandbox resource (REST page snake_case shown; discovery doc uses camelCase fileCount/lastAccessed/sizeBytes/networkMode/networkAllowlist and enum STATUS ACTIVE|EXPIRED).", "fields": [ { "name": "id", "type": "string", "required": true, "description": "Output only" }, { "name": "status", "type": "string", "required": false, "description": "Output only", "enum": [ "active", "expired" ] }, { "name": "created", "type": "string", "required": false, "description": "" }, { "name": "updated", "type": "string", "required": false, "description": "" }, { "name": "last_accessed", "type": "string", "required": false, "description": "" }, { "name": "file_count", "type": "string (int64)", "required": false, "description": "" }, { "name": "size_bytes", "type": "string (int64)", "required": false, "description": "" }, { "name": "sources", "type": "Source[]", "required": false, "description": "" }, { "name": "network", "type": "'disabled' | EnvironmentNetworkEgressAllowlist", "required": false, "description": "" } ], "status": [ "DOCUMENTED", "BETA", "PREVIEW", "LIVE_VERIFIED" ], "example": { "created": "2026-08-19T00:00:00Z", "id": "env_abc123", "last_accessed": "2026-08-19T00:00:00Z", "sources": [ { "type": "inline", "content": "print('Hello, World!')", "target": "main.py" } ], "status": "active", "updated": "2026-08-19T00:00:00Z" }, "sources": [ { "url": "https://ai.google.dev/api/environments", "retrieved_at": "2026-09-18" }, { "url": "https://generativelanguage.googleapis.com/$discovery/rest?version=v1beta", "retrieved_at": "2026-09-18" } ], "live_observation_2026_09_18": "live: {id, status: active, storage{tier, project_used_bytes, project_limit_bytes}, file_count, size_bytes, created, updated}", "_fragment": "generated/fragments/objects/gemini-tools-agents-objects.json" }, { "provider": "gemini", "api_family": "environments", "name": "CreateEnvironmentRequest", "object": null, "schema_name": "CreateEnvironmentRequest", "description": "Body of POST /v1beta/environments.", "fields": [ { "name": "sources", "type": "Source[]", "required": false, "description": "" }, { "name": "network", "type": "'disabled' | EnvironmentNetworkEgressAllowlist", "required": false, "description": "REST page" }, { "name": "from_environment", "type": "string", "required": false, "description": "fork; sources/env must be empty" }, { "name": "networkMode", "type": "string", "required": false, "description": "discovery", "enum": [ "NETWORK_MODE_UNSPECIFIED", "DISABLED" ] }, { "name": "networkAllowlist", "type": "EnvironmentNetworkEgressAllowlist", "required": false, "description": "discovery" }, { "name": "fromEnvironment", "type": "string", "required": false, "description": "discovery" } ], "status": [ "DOCUMENTED", "BETA", "PREVIEW" ], "example": null, "sources": [ { "url": "https://ai.google.dev/api/environments", "retrieved_at": "2026-09-18" }, { "url": "https://generativelanguage.googleapis.com/$discovery/rest?version=v1beta", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/gemini-tools-agents-objects.json" }, { "provider": "gemini", "api_family": "environments", "name": "EnvironmentFile", "object": null, "schema_name": "EnvironmentFile", "description": "File/directory metadata in GetEnvironmentFilesResponse / UploadEnvironmentFileResponse. Guide shows `type` as FILE|DIRECTORY (uppercase), REST page as file|directory.", "fields": [ { "name": "name", "type": "string", "required": false, "description": "" }, { "name": "path", "type": "string", "required": false, "description": "relative to workspace" }, { "name": "type", "type": "string", "required": false, "description": "", "enum": [ "FILE", "DIRECTORY", "file", "directory" ] }, { "name": "size_bytes", "type": "string (int64)", "required": false, "description": "files only" }, { "name": "mime_type", "type": "string", "required": false, "description": "files only" }, { "name": "created", "type": "string", "required": false, "description": "" }, { "name": "modified", "type": "string", "required": false, "description": "" } ], "status": [ "DOCUMENTED", "BETA", "PREVIEW" ], "example": { "name": "main.py", "path": "src/main.py", "type": "FILE", "size_bytes": "15", "mime_type": "text/x-python; charset=utf-8", "created": "2026-08-12T07:44:20Z", "modified": "2026-08-12T07:44:20Z" }, "sources": [ { "url": "https://ai.google.dev/api/environments", "retrieved_at": "2026-09-18" }, { "url": "https://ai.google.dev/gemini-api/docs/agent-environment", "retrieved_at": "2026-09-18" }, { "url": "https://generativelanguage.googleapis.com/$discovery/rest?version=v1beta", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/gemini-tools-agents-objects.json" }, { "provider": "gemini", "api_family": "environments", "name": "GetEnvironmentFilesResponse", "object": null, "schema_name": "GetEnvironmentFilesResponse", "description": "JSON response of GET .../files/{path} without alt=media.", "fields": [ { "name": "files", "type": "EnvironmentFile[]", "required": false, "description": "directory contents or single file entry; empty when alt=media" }, { "name": "next_page_token", "type": "string", "required": false, "description": "" } ], "status": [ "DOCUMENTED", "BETA", "PREVIEW" ], "example": null, "sources": [ { "url": "https://ai.google.dev/api/environments", "retrieved_at": "2026-09-18" }, { "url": "https://generativelanguage.googleapis.com/$discovery/rest?version=v1beta", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/gemini-tools-agents-objects.json" }, { "provider": "gemini", "api_family": "environments", "name": "UploadEnvironmentFileRequest / Response", "object": null, "schema_name": "UploadEnvironmentFileRequest|UploadEnvironmentFileResponse", "description": "PUT upload options and result.", "fields": [ { "name": "extract", "type": "boolean", "required": false, "description": "request: unpack tar/tar.gz" }, { "name": "overwrite", "type": "boolean", "required": false, "description": "request" }, { "name": "files", "type": "EnvironmentFile[]", "required": false, "description": "response: files created/extracted" } ], "status": [ "DOCUMENTED", "BETA", "PREVIEW" ], "example": null, "sources": [ { "url": "https://generativelanguage.googleapis.com/$discovery/rest?version=v1beta", "retrieved_at": "2026-09-18" }, { "url": "https://ai.google.dev/gemini-api/docs/agent-environment", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/gemini-tools-agents-objects.json" }, { "provider": "gemini", "api_family": "environments", "name": "ListEnvironmentsResponse", "object": null, "schema_name": "ListEnvironmentsResponse", "description": "GET /v1beta/environments response.", "fields": [ { "name": "environments", "type": "Environment[]", "required": false, "description": "" }, { "name": "next_page_token", "type": "string", "required": false, "description": "discovery: nextPageToken" } ], "status": [ "DOCUMENTED", "BETA", "PREVIEW" ], "example": null, "sources": [ { "url": "https://ai.google.dev/api/environments", "retrieved_at": "2026-09-18" }, { "url": "https://generativelanguage.googleapis.com/$discovery/rest?version=v1beta", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/gemini-tools-agents-objects.json" }, { "provider": "gemini", "api_family": "credentials", "name": "Credential", "object": null, "schema_name": "Credential", "description": "Server-managed secret metadata (secrets never returned).", "fields": [ { "name": "id", "type": "string", "required": true, "description": "" }, { "name": "type", "type": "string", "required": true, "description": "", "enum": [ "bearer_token", "oauth2", "environment_variable" ] }, { "name": "status", "type": "string", "required": false, "description": "", "enum": [ "active", "revoked" ] }, { "name": "create_time", "type": "string", "required": false, "description": "" }, { "name": "update_time", "type": "string", "required": false, "description": "" } ], "status": [ "DOCUMENTED", "BETA", "PREVIEW" ], "example": { "id": "github-production", "type": "bearer_token", "status": "active", "create_time": "2026-07-15T10:00:00.000000000Z", "update_time": "2026-07-15T10:00:00.000000000Z" }, "sources": [ { "url": "https://ai.google.dev/api/interactions", "retrieved_at": "2026-09-18" }, { "url": "https://ai.google.dev/gemini-api/docs/agent-credentials", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/gemini-tools-agents-objects.json" }, { "provider": "gemini", "api_family": "credentials", "name": "HttpBearerConfig (create)", "object": null, "schema_name": "HttpBearerConfig", "description": "Create body for type bearer_token.", "fields": [ { "name": "type", "type": "string", "required": true, "description": "", "enum": [ "bearer_token" ] }, { "name": "id", "type": "string", "required": false, "description": "reference says required; guide says optional (UUID)" }, { "name": "token", "type": "string", "required": true, "description": "write-only" }, { "name": "header_name", "type": "string", "required": false, "description": "default Authorization" }, { "name": "prefix", "type": "string", "required": false, "description": "default Bearer" } ], "status": [ "DOCUMENTED", "BETA", "PREVIEW" ], "example": { "id": "my-api-key", "type": "bearer_token", "token": "key_xxx", "header_name": "x-goog-api-key", "prefix": "" }, "sources": [ { "url": "https://ai.google.dev/api/interactions", "retrieved_at": "2026-09-18" }, { "url": "https://ai.google.dev/gemini-api/docs/agent-credentials", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/gemini-tools-agents-objects.json" }, { "provider": "gemini", "api_family": "credentials", "name": "OAuth2Config (create)", "object": null, "schema_name": "OAuth2Config", "description": "Create body for type oauth2 (live token exchange at creation; auto-refresh).", "fields": [ { "name": "type", "type": "string", "required": true, "description": "", "enum": [ "oauth2" ] }, { "name": "id", "type": "string", "required": false, "description": "" }, { "name": "client_id", "type": "string", "required": true, "description": "" }, { "name": "client_secret", "type": "string", "required": true, "description": "write-only" }, { "name": "refresh_token", "type": "string", "required": true, "description": "write-only" }, { "name": "token_url", "type": "string", "required": true, "description": "" }, { "name": "scopes", "type": "string[]", "required": false, "description": "" } ], "status": [ "DOCUMENTED", "BETA", "PREVIEW" ], "example": null, "sources": [ { "url": "https://ai.google.dev/api/interactions", "retrieved_at": "2026-09-18" }, { "url": "https://ai.google.dev/gemini-api/docs/agent-credentials", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/gemini-tools-agents-objects.json" }, { "provider": "gemini", "api_family": "credentials", "name": "EnvironmentVariableConfig (create)", "object": null, "schema_name": "EnvironmentVariableConfig", "description": "Create body for type environment_variable (placeholder substituted by the egress proxy).", "fields": [ { "name": "type", "type": "string", "required": true, "description": "", "enum": [ "environment_variable" ] }, { "name": "id", "type": "string", "required": false, "description": "" }, { "name": "value", "type": "string", "required": true, "description": "write-only" }, { "name": "injection_location", "type": "string | string[]", "required": true, "description": "", "enum": [ "header", "query", "body" ] }, { "name": "trusted_domains", "type": "string[]", "required": false, "description": "" } ], "status": [ "DOCUMENTED", "BETA", "PREVIEW" ], "example": { "id": "slack-bot-token", "type": "environment_variable", "value": "xoxb-...", "trusted_domains": [ "*.slack.com", "slack.com" ], "injection_location": "header" }, "sources": [ { "url": "https://ai.google.dev/api/interactions", "retrieved_at": "2026-09-18" }, { "url": "https://ai.google.dev/gemini-api/docs/agent-credentials", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/gemini-tools-agents-objects.json" }, { "provider": "gemini", "api_family": "credentials", "name": "ListCredentialsResponse", "object": null, "schema_name": "ListCredentialsResponse", "description": "GET /v1beta/credentials response.", "fields": [ { "name": "credentials", "type": "Credential[]", "required": false, "description": "" }, { "name": "next_page_token", "type": "string", "required": false, "description": "" } ], "status": [ "DOCUMENTED", "BETA", "PREVIEW" ], "example": null, "sources": [ { "url": "https://ai.google.dev/api/interactions", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/gemini-tools-agents-objects.json" }, { "provider": "gemini", "api_family": "interactions", "name": "WebhookConfig (dynamic webhook)", "object": null, "schema_name": "WebhookConfig", "description": "Per-request webhook on POST /v1beta/interactions.", "fields": [ { "name": "uris", "type": "string[]", "required": false, "description": "" }, { "name": "user_metadata", "type": "object", "required": false, "description": "returned on each event" } ], "status": [ "DOCUMENTED", "BETA" ], "example": { "uris": [ "https://my-api.com/gemini-webhook-dynamic" ], "user_metadata": { "job_group": "nightly-eval" } }, "sources": [ { "url": "https://ai.google.dev/api/interactions", "retrieved_at": "2026-09-18" }, { "url": "https://ai.google.dev/gemini-api/docs/webhooks", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/gemini-tools-agents-objects.json" }, { "provider": "gemini", "api_family": "webhooks", "name": "Webhook event envelope", "object": null, "schema_name": "WebhookEnvelope", "description": "Thin payload POSTed to webhook listeners (headers webhook-id, webhook-timestamp, signature). Interaction events: interaction.requires_action {id}, interaction.completed {id}, interaction.failed {id, error_code, error_message}, interaction.cancelled {id}.", "fields": [ { "name": "type", "type": "string", "required": true, "description": "", "enum": [ "interaction.requires_action", "interaction.completed", "interaction.failed", "interaction.cancelled", "batch.succeeded", "batch.cancelled", "batch.expired", "batch.failed", "video.generated" ] }, { "name": "version", "type": "string", "required": false, "description": "v1" }, { "name": "timestamp", "type": "string", "required": false, "description": "" }, { "name": "data", "type": "object", "required": false, "description": "id (+ error_code/error_message, output_file_uri...)" } ], "status": [ "DOCUMENTED", "BETA" ], "example": { "type": "interaction.completed", "version": "v1", "timestamp": "2026-01-22T12:00:00Z", "data": { "id": "v1_..." } }, "sources": [ { "url": "https://ai.google.dev/gemini-api/docs/webhooks", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/gemini-tools-agents-objects.json" }, { "provider": "gemini", "api_family": "live", "name": "Live setup message", "object": "BidiGenerateContentSetup", "schema_name": "BidiGenerateContentSetup", "description": "First client message; configuration for the whole streaming session.", "fields": [ { "name": "model", "type": "string", "required": true, "description": "Required. `models/{model}` resource name (e.g. models/gemini-3.8-live)." }, { "name": "generationConfig", "type": "GenerationConfig (subset)", "required": false, "description": "Not supported in Live: responseLogprobs, responseMimeType, logprobs, responseSchema, responseJsonSchema, stopSequence, skipResponseCache, routingConfig, audioTimestamp.", "fields": [ { "name": "responseModalities[]", "type": "enum[]", "required": false, "description": "Requested output modalities. Native audio models support only [\"AUDIO\"] (use outputAudioTranscription for text); gemini-3.5-transcribe-live uses [\"TEXT\"]. SDK default: AUDIO.", "enum": [ "TEXT", "AUDIO" ] }, { "name": "speechConfig", "type": "SpeechConfig", "required": false, "description": "Voice / language configuration.", "fields": [ { "name": "voiceConfig", "type": "VoiceConfig", "required": false, "description": "Single-voice output configuration.", "fields": [ { "name": "prebuiltVoiceConfig", "type": "PrebuiltVoiceConfig", "required": false, "description": "The prebuilt voice to use.", "fields": [ { "name": "voiceName", "type": "string", "required": false, "description": "Optional. Name of the preset voice (any Gemini TTS voice: Zephyr, Puck, Charon, Kore, Fenrir, Leda, Orus, Aoede, Callirrhoe, Autonoe, Enceladus, Iapetus, Umbriel, Algieba, Despina, Erinome, Algenib, Rasalgethi, Laomedeia, Achernar, Alnilam, Schedar, Gacrux, Pulcherrima, Achird, Zubenelgenubi, Vindemiatrix, Sadachbia, Sadaltager, Sulafat)." } ] } ] }, { "name": "multiSpeakerVoiceConfig", "type": "MultiSpeakerVoiceConfig", "required": false, "description": "Multi-speaker setup; mutually exclusive with voiceConfig (TTS feature; not documented for Live — UNVERIFIED in Live).", "status": [ "UNVERIFIED" ], "fields": [ { "name": "speakerVoiceConfigs[]", "type": "SpeakerVoiceConfig[]", "required": true, "description": "Required. All enabled speaker voices (SDK doc: exactly two).", "fields": [ { "name": "speaker", "type": "string", "required": true, "description": "Required. Speaker name as used in the prompt." }, { "name": "voiceConfig", "type": "VoiceConfig", "required": true, "description": "Required. Voice for this speaker.", "fields": [ { "name": "prebuiltVoiceConfig", "type": "PrebuiltVoiceConfig", "required": false, "description": "The prebuilt voice to use.", "fields": [ { "name": "voiceName", "type": "string", "required": false, "description": "Optional. Name of the preset voice (any Gemini TTS voice: Zephyr, Puck, Charon, Kore, Fenrir, Leda, Orus, Aoede, Callirrhoe, Autonoe, Enceladus, Iapetus, Umbriel, Algieba, Despina, Erinome, Algenib, Rasalgethi, Laomedeia, Achernar, Alnilam, Schedar, Gacrux, Pulcherrima, Achird, Zubenelgenubi, Vindemiatrix, Sadachbia, Sadaltager, Sulafat)." } ] } ] } ] } ] }, { "name": "languageCode", "type": "string", "required": false, "description": "Optional. BCP-47 language code for speech recognition and synthesis (de-DE, en-AU, en-GB, en-IN, en-US, es-US, fr-FR, hi-IN, pt-BR, ar-XA, es-ES, fr-CA, id-ID, it-IT, ja-JP, tr-TR, vi-VN, bn-IN, gu-IN, kn-IN, ml-IN, mr-IN, ta-IN, te-IN, nl-NL, ko-KR, cmn-CN, pl-PL, ru-RU, th-TH). Native audio output models choose the language automatically and do NOT support setting it explicitly." } ] }, { "name": "mediaResolution", "type": "enum", "required": false, "description": "Token allocation per visual input frame (LOW=64 tokens, MEDIUM=256, HIGH=zoomed reframing 256). Audio tokenization is fixed per second regardless.", "enum": [ "MEDIA_RESOLUTION_UNSPECIFIED", "MEDIA_RESOLUTION_LOW", "MEDIA_RESOLUTION_MEDIUM", "MEDIA_RESOLUTION_HIGH" ] }, { "name": "thinkingConfig", "type": "ThinkingConfig", "required": false, "description": "Thinking configuration (model-dependent, see thinkingLevel).", "fields": [ { "name": "thinkingLevel", "type": "enum", "required": false, "description": "Reasoning depth. gemini-3.1-flash-live-preview: MINIMAL (default), LOW, MEDIUM, HIGH. gemini-3.8-live-extended-thinking: LOW, MEDIUM, HIGH (MINIMAL not supported). gemini-3.8-live: NOT supported — omit thinkingConfig.", "enum": [ "THINKING_LEVEL_UNSPECIFIED", "MINIMAL", "LOW", "MEDIUM", "HIGH" ] }, { "name": "thinkingBudget", "type": "integer", "required": false, "description": "Thoughts token budget (0 disabled, -1 automatic). Gemini 2.5 native-audio models; replaced by thinkingLevel from Gemini 3.1 onward." }, { "name": "includeThoughts", "type": "boolean", "required": false, "description": "Return thought summaries in modelTurn parts (part.thought=true) when available." } ] }, { "name": "translationConfig", "type": "TranslationConfig", "required": false, "description": "Live translation (gemini-3.5-live-translate-preview only).", "fields": [ { "name": "targetLanguageCode", "type": "string", "required": true, "description": "Required. BCP-47 target language (e.g. \"en\", \"es\", \"pl\"). Guide: defaults to \"en\"." }, { "name": "echoTargetLanguage", "type": "boolean", "required": false, "description": "If true, input already in the target language is echoed (parroted) as audio; if false (default) the model stays silent for it." } ] }, { "name": "enableAffectiveDialog", "type": "boolean", "required": false, "description": "Detect emotions and adapt responses (Gemini 2.5 native audio only; not supported on 3.1; removed on 3.8 — remove from code)." }, { "name": "temperature", "type": "number", "required": false, "description": "Sampling temperature." }, { "name": "topP", "type": "number", "required": false, "description": "Nucleus sampling." }, { "name": "topK", "type": "integer", "required": false, "description": "Top-k sampling." }, { "name": "maxOutputTokens", "type": "integer", "required": false, "description": "Max output tokens." }, { "name": "candidateCount", "type": "integer", "required": false, "description": "Number of candidates." }, { "name": "presencePenalty", "type": "number", "required": false, "description": "Presence penalty." }, { "name": "frequencyPenalty", "type": "number", "required": false, "description": "Frequency penalty." }, { "name": "seed", "type": "integer", "required": false, "description": "Best-effort deterministic seed (SDK LiveConnectConfig)." } ] }, { "name": "systemInstruction", "type": "Content", "required": false, "description": "Text-only parts; each part becomes a separate paragraph.", "fields": [ { "name": "role", "type": "string", "required": false, "description": "\"user\" or \"model\".", "enum": [ "user", "model" ] }, { "name": "parts[]", "type": "Part[]", "required": false, "description": "Parts: text, inlineData{mimeType,data}, functionCall, functionResponse, thought ... (systemInstruction: text parts only, each part a separate paragraph)." } ] }, { "name": "tools[]", "type": "Tool[]", "required": false, "description": "Tools the model may use.", "fields": [ { "name": "functionDeclarations[]", "type": "FunctionDeclaration[]", "required": false, "description": "Client-executed functions.", "fields": [ { "name": "name", "type": "string", "required": true, "description": "Required. Function name (a-z, A-Z, 0-9, _ - : . ; max 128)." }, { "name": "description", "type": "string", "required": true, "description": "Required. Function description." }, { "name": "parameters", "type": "Schema", "required": false, "description": "OpenAPI-style parameter schema." }, { "name": "parametersJsonSchema", "type": "object", "required": false, "description": "JSON Schema alternative to parameters." }, { "name": "behavior", "type": "enum", "required": false, "description": "Live-only. BLOCKING = model waits for the response; NON_BLOCKING = asynchronous (conversation continues). Default: gemini-3.8-live NON_BLOCKING; gemini-3.8-live-extended-thinking NON_BLOCKING only (BLOCKING = hard error); gemini-3.1-flash-live-preview synchronous only (NON_BLOCKING not supported); Gemini 2.5 supports both.", "enum": [ "UNSPECIFIED", "BLOCKING", "NON_BLOCKING" ] }, { "name": "response", "type": "Schema", "required": false, "description": "Response schema." }, { "name": "responseJsonSchema", "type": "object", "required": false, "description": "JSON Schema for the response." } ] }, { "name": "googleSearch", "type": "object {}", "required": false, "description": "Grounding with Google Search (supported on Live agent models; not on translate/transcribe)." }, { "name": "codeExecution", "type": "object {}", "required": false, "description": "Not supported on current Live models (tools table)." }, { "name": "urlContext", "type": "object {}", "required": false, "description": "Not supported on current Live models (tools table); serverContent.urlContextMetadata exists in the schema nonetheless." }, { "name": "googleMaps", "type": "object", "required": false, "description": "Not supported on Live models." } ] }, { "name": "realtimeInputConfig", "type": "RealtimeInputConfig", "required": false, "description": "VAD / activity handling / turn coverage.", "fields": [ { "name": "automaticActivityDetection", "type": "AutomaticActivityDetection", "required": false, "description": "Server-side VAD; enabled by default if not set.", "fields": [ { "name": "disabled", "type": "boolean", "required": false, "description": "Default false (automatic VAD on: detected voice and text count as activity). true = client must send activityStart/activityEnd." }, { "name": "startOfSpeechSensitivity", "type": "enum", "required": false, "description": "How readily speech start is detected. Default START_SENSITIVITY_HIGH.", "enum": [ "START_SENSITIVITY_UNSPECIFIED", "START_SENSITIVITY_HIGH", "START_SENSITIVITY_LOW" ] }, { "name": "prefixPaddingMs", "type": "integer (int32)", "required": false, "description": "Speech duration required before start-of-speech is committed (look-back padding). Lower = more sensitive, more false positives; 0 may clip first syllables." }, { "name": "endOfSpeechSensitivity", "type": "enum", "required": false, "description": "How readily end of speech is detected. Default END_SENSITIVITY_HIGH.", "enum": [ "END_SENSITIVITY_UNSPECIFIED", "END_SENSITIVITY_HIGH", "END_SENSITIVITY_LOW" ] }, { "name": "silenceDurationMs", "type": "integer (int32)", "required": false, "description": "Non-speech duration before end-of-speech is committed. Server default ~800 ms; recommended 500-800 ms." } ] }, { "name": "activityHandling", "type": "enum", "required": false, "description": "Effect of user activity on model output. Default START_OF_ACTIVITY_INTERRUPTS (barge-in).", "enum": [ "ACTIVITY_HANDLING_UNSPECIFIED", "START_OF_ACTIVITY_INTERRUPTS", "NO_INTERRUPTION" ] }, { "name": "turnCoverage", "type": "enum", "required": false, "description": "Which realtime input is part of the user turn. Default: Gemini 2.5 TURN_INCLUDES_ONLY_ACTIVITY; Gemini 3.1+ TURN_INCLUDES_AUDIO_ACTIVITY_AND_ALL_VIDEO.", "enum": [ "TURN_COVERAGE_UNSPECIFIED", "TURN_INCLUDES_ONLY_ACTIVITY", "TURN_INCLUDES_ALL_INPUT", "TURN_INCLUDES_AUDIO_ACTIVITY_AND_ALL_VIDEO" ] } ] }, { "name": "sessionResumption", "type": "SessionResumptionConfig", "required": false, "description": "If present the server sends sessionResumptionUpdate messages.", "fields": [ { "name": "handle", "type": "string", "required": false, "description": "Handle from a previous SessionResumptionUpdate.newHandle. Absent = new session. Valid 2 h after the last session termination." }, { "name": "transparent", "type": "boolean", "required": false, "description": "SDK-only: server includes lastConsumedClientMessageIndex in sessionResumptionUpdate for transparent reconnects. Not in the REST reference.", "status": [ "UNVERIFIED" ] } ] }, { "name": "contextWindowCompression", "type": "ContextWindowCompressionConfig", "required": false, "description": "Automatic context reduction beyond a length; enables unlimited session duration.", "fields": [ { "name": "slidingWindow", "type": "SlidingWindow", "required": false, "description": "Sliding-window mechanism (union compressionMechanism); discards from the start, always cutting at a USER turn; system instructions kept.", "fields": [ { "name": "targetTokens", "type": "integer (int64, JSON string)", "required": false, "description": "Tokens to keep after compression. Default triggerTokens/2. Must be < triggerTokens." } ] }, { "name": "triggerTokens", "type": "integer (int64, JSON string)", "required": false, "description": "Token count (before a turn) that triggers compression. Default 80% of the model context window." } ] }, { "name": "inputAudioTranscription", "type": "AudioTranscriptionConfig", "required": false, "description": "Enable transcription of user audio ({} = defaults).", "fields": [ { "name": "languageCodes[]", "type": "string[]", "required": false, "description": "BCP-47 hints for languages present in the audio; omitted/empty = automatic detection." }, { "name": "customVocabulary[]", "type": "string[]", "required": false, "description": "Up to 1,000 phrases to bias recognition (best results <= 100)." }, { "name": "mode", "type": "enum", "required": false, "description": "VERBATIM (default) or SMART (disfluency removal, cleanup, formatting). Incompatible with timestamps/diarization.", "enum": [ "MODE_UNSPECIFIED", "VERBATIM", "SMART" ] }, { "name": "wordTimestamp", "type": "boolean", "required": false, "description": "Word-level timestamps (NOT supported over the Live API per live-transcribe limitations)." }, { "name": "diarization", "type": "boolean", "required": false, "description": "Speaker diarization (NOT supported over the Live API per live-transcribe limitations)." } ] }, { "name": "outputAudioTranscription", "type": "AudioTranscriptionConfig", "required": false, "description": "Enable transcription of model audio ({} = defaults).", "fields": [ { "name": "languageCodes[]", "type": "string[]", "required": false, "description": "BCP-47 hints for languages present in the audio; omitted/empty = automatic detection." }, { "name": "customVocabulary[]", "type": "string[]", "required": false, "description": "Up to 1,000 phrases to bias recognition (best results <= 100)." }, { "name": "mode", "type": "enum", "required": false, "description": "VERBATIM (default) or SMART (disfluency removal, cleanup, formatting). Incompatible with timestamps/diarization.", "enum": [ "MODE_UNSPECIFIED", "VERBATIM", "SMART" ] }, { "name": "wordTimestamp", "type": "boolean", "required": false, "description": "Word-level timestamps (NOT supported over the Live API per live-transcribe limitations)." }, { "name": "diarization", "type": "boolean", "required": false, "description": "Speaker diarization (NOT supported over the Live API per live-transcribe limitations)." } ] }, { "name": "proactivity", "type": "ProactivityConfig", "required": false, "description": "Proactive audio.", "fields": [ { "name": "proactiveAudio", "type": "boolean", "required": false, "description": "Model may decline to answer irrelevant/incomplete input. Gemini 2.5: opt-in; gemini-3.8-live*: permanently enabled (false returns an error); gemini-3.1-flash-live-preview: not supported." } ] }, { "name": "historyConfig", "type": "HistoryConfig", "required": false, "description": "Initial-history handshake.", "fields": [ { "name": "initialHistoryInClientContent", "type": "boolean", "required": false, "description": "If true, after setupComplete the server first ingests clientContent until turnComplete=true (history may end with role model) without a model call; then realtimeInput starts the conversation." } ] }, { "name": "labels", "type": "object", "required": false, "description": "Discovery-only: user metadata labels (e.g. {\"safety_identifier\": ...}); not in the public Live reference page.", "status": [ "UNVERIFIED" ] } ], "status": [ "DOCUMENTED" ], "example": { "model": "models/gemini-3.8-live", "generationConfig": { "responseModalities": [ "AUDIO" ], "speechConfig": { "voiceConfig": { "prebuiltVoiceConfig": { "voiceName": "Puck" } } } }, "systemInstruction": { "parts": [ { "text": "You are a helpful assistant." } ] }, "tools": [ { "functionDeclarations": [ { "name": "searchFlights", "description": "Searches for flights between cities.", "behavior": "NON_BLOCKING", "parameters": { "type": "OBJECT", "properties": { "destination": { "type": "STRING" } }, "required": [ "destination" ] } } ] }, { "googleSearch": {} } ], "realtimeInputConfig": { "automaticActivityDetection": { "disabled": false, "startOfSpeechSensitivity": "START_SENSITIVITY_LOW", "endOfSpeechSensitivity": "END_SENSITIVITY_LOW", "prefixPaddingMs": 20, "silenceDurationMs": 100 } }, "inputAudioTranscription": {}, "outputAudioTranscription": {}, "sessionResumption": {}, "contextWindowCompression": { "triggerTokens": "25600", "slidingWindow": { "targetTokens": "12800" } } }, "sources": [ { "url": "https://ai.google.dev/api/live", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/gemini-tools-agents-objects.json" }, { "provider": "gemini", "api_family": "live", "name": "Client content update", "object": "BidiGenerateContentClientContent", "schema_name": "BidiGenerateContentClientContent", "description": "Incremental conversation history/prompt update from the client; interrupts generation.", "fields": [ { "name": "turns[]", "type": "Content[]", "required": false, "description": "Content appended to the conversation (history and/or latest request), roles user/model.", "fields": [ { "name": "role", "type": "string", "required": false, "description": "\"user\" or \"model\".", "enum": [ "user", "model" ] }, { "name": "parts[]", "type": "Part[]", "required": false, "description": "Parts: text, inlineData{mimeType,data}, functionCall, functionResponse, thought ... (systemInstruction: text parts only, each part a separate paragraph)." } ] }, { "name": "turnComplete", "type": "boolean", "required": false, "description": "true = start generation with accumulated prompt (unconditionally interrupts active generation); otherwise the server waits for more messages." } ], "status": [ "DOCUMENTED" ], "example": { "turns": [ { "role": "user", "parts": [ { "text": "Hello world!" } ] } ], "turnComplete": true }, "sources": [ { "url": "https://ai.google.dev/api/live", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/gemini-tools-agents-objects.json" }, { "provider": "gemini", "api_family": "live", "name": "Realtime input", "object": "BidiGenerateContentRealtimeInput", "schema_name": "BidiGenerateContentRealtimeInput", "description": "Realtime audio/video/text streams and activity signals.", "fields": [ { "name": "audio", "type": "Blob", "required": false, "description": "Realtime audio chunk: raw 16-bit little-endian PCM, natively 16 kHz mono (any rate accepted, declare it in mimeType).", "fields": [ { "name": "mimeType", "type": "string", "required": true, "description": "IANA MIME type, e.g. audio/pcm;rate=16000, image/jpeg, image/png." }, { "name": "data", "type": "string (base64)", "required": true, "description": "Raw bytes, base64-encoded in JSON." } ] }, { "name": "video", "type": "Blob", "required": false, "description": "Realtime video frame as an individual image (JPEG/PNG), max 1 frame/s.", "fields": [ { "name": "mimeType", "type": "string", "required": true, "description": "IANA MIME type, e.g. audio/pcm;rate=16000, image/jpeg, image/png." }, { "name": "data", "type": "string (base64)", "required": true, "description": "Raw bytes, base64-encoded in JSON." } ] }, { "name": "text", "type": "string", "required": false, "description": "Realtime text input stream." }, { "name": "activityStart", "type": "ActivityStart {}", "required": false, "description": "Marks start of user activity; only when automatic VAD is disabled." }, { "name": "activityEnd", "type": "ActivityEnd {}", "required": false, "description": "Marks end of user activity; only when automatic VAD is disabled." }, { "name": "audioStreamEnd", "type": "boolean", "required": false, "description": "Audio stream ended (mic off / hybrid VAD end-of-speech). Only with automatic VAD enabled; flushes cached audio; reopened by sending audio again." }, { "name": "mediaResolution", "type": "enum", "required": false, "description": "Per-message override of setup.generationConfig.mediaResolution.", "enum": [ "MEDIA_RESOLUTION_UNSPECIFIED", "MEDIA_RESOLUTION_LOW", "MEDIA_RESOLUTION_MEDIUM", "MEDIA_RESOLUTION_HIGH" ] }, { "name": "mediaChunks[]", "type": "Blob[]", "required": false, "description": "DEPRECATED — use audio/video/text. Only the first chunk is honoured.", "status": [ "DOCUMENTED", "DEPRECATED" ], "fields": [ { "name": "mimeType", "type": "string", "required": true, "description": "IANA MIME type, e.g. audio/pcm;rate=16000, image/jpeg, image/png." }, { "name": "data", "type": "string (base64)", "required": true, "description": "Raw bytes, base64-encoded in JSON." } ] } ], "status": [ "DOCUMENTED" ], "example": { "audio": { "data": "UklGRiQAAABXQVZF...", "mimeType": "audio/pcm;rate=16000" } }, "sources": [ { "url": "https://ai.google.dev/api/live", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/gemini-tools-agents-objects.json" }, { "provider": "gemini", "api_family": "live", "name": "Tool response", "object": "BidiGenerateContentToolResponse", "schema_name": "BidiGenerateContentToolResponse", "description": "Client's function results for a toolCall.", "fields": [ { "name": "functionResponses[]", "type": "FunctionResponse[]", "required": false, "description": "Responses matched to toolCall.functionCalls by id.", "fields": [ { "name": "id", "type": "string", "required": false, "description": "Must match FunctionCall.id." }, { "name": "name", "type": "string", "required": true, "description": "Required. Function name." }, { "name": "response", "type": "object", "required": true, "description": "Required. JSON result; keys of your choice (\"output\", \"result\", \"error\" ...)." }, { "name": "scheduling", "type": "enum", "required": false, "description": "NON_BLOCKING calls only: INTERRUPT (interrupt and speak now), WHEN_IDLE (default; after current output), SILENT (add to context only).", "enum": [ "SCHEDULING_UNSPECIFIED", "SILENT", "WHEN_IDLE", "INTERRUPT" ] }, { "name": "willContinue", "type": "boolean", "required": false, "description": "NON_BLOCKING calls only: more responses follow (generator). false + empty response finishes the call (still may trigger generation unless scheduling=SILENT)." }, { "name": "parts[]", "type": "FunctionResponsePart[]", "required": false, "description": "Multimodal parts (inlineData/fileData) of the response." } ] } ], "status": [ "DOCUMENTED" ], "example": { "functionResponses": [ { "id": "call_123", "name": "searchFlights", "response": { "output": { "flight": "DL 145", "price": "$145" }, "scheduling": "INTERRUPT" } } ] }, "sources": [ { "url": "https://ai.google.dev/api/live", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/gemini-tools-agents-objects.json" }, { "provider": "gemini", "api_family": "live", "name": "Client message (union)", "object": "BidiGenerateContentClientMessage", "schema_name": "BidiGenerateContentClientMessage", "description": "Exactly one of setup | clientContent | realtimeInput | toolResponse.", "fields": [ { "name": "setup", "type": "BidiGenerateContentSetup", "required": false, "description": "" }, { "name": "clientContent", "type": "BidiGenerateContentClientContent", "required": false, "description": "" }, { "name": "realtimeInput", "type": "BidiGenerateContentRealtimeInput", "required": false, "description": "" }, { "name": "toolResponse", "type": "BidiGenerateContentToolResponse", "required": false, "description": "" } ], "status": [ "DOCUMENTED" ], "example": { "clientContent": { "turns": [ { "role": "user", "parts": [ { "text": "Hello world!" } ] } ], "turnComplete": true } }, "sources": [ { "url": "https://ai.google.dev/api/live", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/gemini-tools-agents-objects.json" }, { "provider": "gemini", "api_family": "live", "name": "Server message (union)", "object": "BidiGenerateContentServerMessage", "schema_name": "BidiGenerateContentServerMessage", "description": "usageMetadata (optional) + exactly one of the messageType union fields, which appear at the top level of the JSON.", "fields": [ { "name": "usageMetadata", "type": "UsageMetadata", "required": false, "description": "Optional companion." }, { "name": "setupComplete", "type": "BidiGenerateContentSetupComplete", "required": false, "description": "" }, { "name": "serverContent", "type": "BidiGenerateContentServerContent", "required": false, "description": "" }, { "name": "toolCall", "type": "BidiGenerateContentToolCall", "required": false, "description": "" }, { "name": "toolCallCancellation", "type": "BidiGenerateContentToolCallCancellation", "required": false, "description": "" }, { "name": "goAway", "type": "GoAway", "required": false, "description": "" }, { "name": "sessionResumptionUpdate", "type": "SessionResumptionUpdate", "required": false, "description": "" }, { "name": "voiceActivity", "type": "VoiceActivity", "required": false, "description": "SDK types only.", "status": [ "UNVERIFIED" ] }, { "name": "voiceActivityDetectionSignal", "type": "VoiceActivityDetectionSignal", "required": false, "description": "SDK types only; allowlisted.", "status": [ "UNVERIFIED" ] } ], "status": [ "DOCUMENTED" ], "example": { "serverContent": { "turnComplete": true, "interactionStatus": "IDLE" } }, "sources": [ { "url": "https://ai.google.dev/api/live", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/gemini-tools-agents-objects.json" }, { "provider": "gemini", "api_family": "live", "name": "Setup complete", "object": "BidiGenerateContentSetupComplete", "schema_name": "BidiGenerateContentSetupComplete", "description": "Empty acknowledgement of setup.", "fields": [], "status": [ "DOCUMENTED", "LIVE_VERIFIED" ], "example": {}, "sources": [ { "url": "https://ai.google.dev/api/live", "retrieved_at": "2026-09-18" } ], "live_observation_2026_09_18": "live: {} (empty object)", "_fragment": "generated/fragments/objects/gemini-tools-agents-objects.json" }, { "provider": "gemini", "api_family": "live", "name": "Server content", "object": "BidiGenerateContentServerContent", "schema_name": "BidiGenerateContentServerContent", "description": "Model output and turn-state flags.", "fields": [ { "name": "modelTurn", "type": "Content", "required": false, "description": "Generated content: parts with inlineData {mimeType:'audio/pcm;rate=24000', data} for audio, text for TEXT modality, thought summaries. One message can hold several parts.", "fields": [ { "name": "role", "type": "string", "required": false, "description": "\"user\" or \"model\".", "enum": [ "user", "model" ] }, { "name": "parts[]", "type": "Part[]", "required": false, "description": "Parts: text, inlineData{mimeType,data}, functionCall, functionResponse, thought ... (systemInstruction: text parts only, each part a separate paragraph)." } ] }, { "name": "generationComplete", "type": "boolean", "required": false, "description": "Model finished generating. Absent in interrupted turns (interrupted -> turnComplete). With realtime playback there is a gap before turnComplete." }, { "name": "turnComplete", "type": "boolean", "required": false, "description": "Model turn complete; generation resumes only on new client messages. On extended-thinking, check interactionStatus (IDLE vs IN_PROGRESS)." }, { "name": "interrupted", "type": "boolean", "required": false, "description": "A client message/VAD barge-in interrupted generation: stop playback and flush queue." }, { "name": "groundingMetadata", "type": "GroundingMetadata", "required": false, "description": "Search grounding metadata (webSearchQueries, groundingChunks, groundingSupports, searchEntryPoint)." }, { "name": "inputTranscription", "type": "BidiGenerateContentTranscription", "required": false, "description": "Finalized user-audio transcript (independent stream, no ordering guarantee).", "fields": [ { "name": "text", "type": "string", "required": false, "description": "Transcription text." }, { "name": "languageCode", "type": "string", "required": false, "description": "BCP-47 code of the transcript (translate model reports it)." }, { "name": "finished", "type": "boolean", "required": false, "description": "SDK-only: end of transcription.", "status": [ "UNVERIFIED" ] } ] }, { "name": "interimInputTranscription", "type": "BidiGenerateContentTranscription", "required": false, "description": "Low-latency partial hypothesis, updated frequently while the user speaks.", "fields": [ { "name": "text", "type": "string", "required": false, "description": "Transcription text." }, { "name": "languageCode", "type": "string", "required": false, "description": "BCP-47 code of the transcript (translate model reports it)." }, { "name": "finished", "type": "boolean", "required": false, "description": "SDK-only: end of transcription.", "status": [ "UNVERIFIED" ] } ] }, { "name": "outputTranscription", "type": "BidiGenerateContentTranscription", "required": false, "description": "Model-audio transcript; last one of a turn precedes generationComplete/interrupted.", "fields": [ { "name": "text", "type": "string", "required": false, "description": "Transcription text." }, { "name": "languageCode", "type": "string", "required": false, "description": "BCP-47 code of the transcript (translate model reports it)." }, { "name": "finished", "type": "boolean", "required": false, "description": "SDK-only: end of transcription.", "status": [ "UNVERIFIED" ] } ] }, { "name": "urlContextMetadata", "type": "UrlContextMetadata", "required": false, "description": "urlMetadata[] from the URL context tool." }, { "name": "waitingForInput", "type": "boolean", "required": false, "description": "Model idle because it expects the user to continue." }, { "name": "interactionStatus", "type": "enum", "required": false, "description": "Always sent alongside turnComplete. IN_PROGRESS = background reasoning / async tool calls pending; IDLE = fully done; REQUIRES_ACTION deprecated.", "enum": [ "INTERACTION_STATUS_UNSPECIFIED", "IN_PROGRESS", "REQUIRES_ACTION", "IDLE" ] }, { "name": "speechState", "type": "enum (deprecated)", "required": false, "description": "DEPRECATED: use VoiceActivity. Speech detection state on realtimeInput.audio.", "status": [ "DOCUMENTED", "DEPRECATED" ] }, { "name": "turnCompleteReason", "type": "enum", "required": false, "description": "SDK-only: TURN_COMPLETE_REASON_UNSPECIFIED, MALFORMED_FUNCTION_CALL, RESPONSE_REJECTED, NEED_MORE_INPUT, PROHIBITED_INPUT_CONTENT, ... Not in the REST reference.", "status": [ "UNVERIFIED" ] } ], "status": [ "DOCUMENTED", "LIVE_VERIFIED" ], "example": { "modelTurn": { "parts": [ { "inlineData": { "mimeType": "audio/pcm;rate=24000", "data": "..." } } ] } }, "sources": [ { "url": "https://ai.google.dev/api/live", "retrieved_at": "2026-09-18" } ], "live_observation_2026_09_18": "live fields seen: modelTurn (parts text+thought:true, then inlineData audio/pcm;rate=24000), outputTranscription{text}, generationComplete, turnComplete", "_fragment": "generated/fragments/objects/gemini-tools-agents-objects.json" }, { "provider": "gemini", "api_family": "live", "name": "Tool call", "object": "BidiGenerateContentToolCall", "schema_name": "BidiGenerateContentToolCall", "description": "Function calls to execute.", "fields": [ { "name": "functionCalls[]", "type": "FunctionCall[]", "required": false, "description": "Calls to execute; reply with toolResponse using matching ids.", "fields": [ { "name": "id", "type": "string", "required": false, "description": "Unique id to echo in FunctionResponse.id." }, { "name": "name", "type": "string", "required": true, "description": "Function name." }, { "name": "args", "type": "object", "required": false, "description": "Arguments." } ] } ], "status": [ "DOCUMENTED", "LIVE_VERIFIED" ], "example": { "functionCalls": [ { "id": "call_123", "name": "searchFlights", "args": { "destination": "Seattle" } } ] }, "sources": [ { "url": "https://ai.google.dev/api/live", "retrieved_at": "2026-09-18" } ], "live_observation_2026_09_18": "live: {functionCalls:[{name, args, id: function-call-…}]}", "_fragment": "generated/fragments/objects/gemini-tools-agents-objects.json" }, { "provider": "gemini", "api_family": "live", "name": "Tool call cancellation", "object": "BidiGenerateContentToolCallCancellation", "schema_name": "BidiGenerateContentToolCallCancellation", "description": "Ids of tool calls to cancel after an interruption.", "fields": [ { "name": "ids[]", "type": "string[]", "required": true, "description": "Ids of tool calls to cancel/undo." } ], "status": [ "DOCUMENTED" ], "example": { "ids": [ "call_123" ] }, "sources": [ { "url": "https://ai.google.dev/api/live", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/gemini-tools-agents-objects.json" }, { "provider": "gemini", "api_family": "live", "name": "GoAway", "object": "GoAway", "schema_name": "GoAway", "description": "Imminent connection termination notice.", "fields": [ { "name": "timeLeft", "type": "string (google.protobuf.Duration, e.g. \"30s\")", "required": true, "description": "Remaining time before the connection is terminated as ABORTED; never below a model-specific minimum (documented with rate limits — value not published)." } ], "status": [ "DOCUMENTED" ], "example": { "timeLeft": "30s" }, "sources": [ { "url": "https://ai.google.dev/api/live", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/gemini-tools-agents-objects.json" }, { "provider": "gemini", "api_family": "live", "name": "Session resumption update", "object": "SessionResumptionUpdate", "schema_name": "SessionResumptionUpdate", "description": "Resumable state handle.", "fields": [ { "name": "newHandle", "type": "string", "required": false, "description": "New resumable handle; empty when resumable=false." }, { "name": "resumable", "type": "boolean", "required": false, "description": "False while the model is generating / executing function calls (resuming then loses data)." }, { "name": "lastConsumedClientMessageIndex", "type": "integer", "required": false, "description": "SDK-only, when SessionResumptionConfig.transparent is set: index of the last client message included in the state.", "status": [ "UNVERIFIED" ] } ], "status": [ "DOCUMENTED", "LIVE_VERIFIED" ], "example": { "newHandle": "", "resumable": true }, "sources": [ { "url": "https://ai.google.dev/api/live", "retrieved_at": "2026-09-18" } ], "live_observation_2026_09_18": "live: {newHandle: , resumable: true} right after setupComplete and again after turnComplete", "_fragment": "generated/fragments/objects/gemini-tools-agents-objects.json" }, { "provider": "gemini", "api_family": "live", "name": "Usage metadata (Live)", "object": "UsageMetadata", "schema_name": "UsageMetadata", "description": "Token usage with per-modality details; sent alongside server messages.", "fields": [ { "name": "promptTokenCount", "type": "integer", "required": false, "description": "Prompt tokens (includes cached content)." }, { "name": "cachedContentTokenCount", "type": "integer", "required": false, "description": "Cached prompt tokens." }, { "name": "responseTokenCount", "type": "integer", "required": false, "description": "Tokens across generated candidates." }, { "name": "toolUsePromptTokenCount", "type": "integer", "required": false, "description": "Tool-use prompt tokens." }, { "name": "thoughtsTokenCount", "type": "integer", "required": false, "description": "Thinking tokens." }, { "name": "totalTokenCount", "type": "integer", "required": false, "description": "prompt + response (+ thoughts + tool-use)." }, { "name": "promptTokensDetails[]", "type": "ModalityTokenCount[]", "required": false, "description": "Per-modality prompt breakdown (TEXT/AUDIO/IMAGE/VIDEO...).", "fields": [ { "name": "modality", "type": "enum", "required": false, "description": "Modality of the count.", "enum": [ "MODALITY_UNSPECIFIED", "TEXT", "IMAGE", "VIDEO", "AUDIO", "DOCUMENT" ] }, { "name": "tokenCount", "type": "integer", "required": false, "description": "Tokens." } ] }, { "name": "cacheTokensDetails[]", "type": "ModalityTokenCount[]", "required": false, "description": "Per-modality cached breakdown.", "fields": [ { "name": "modality", "type": "enum", "required": false, "description": "Modality of the count.", "enum": [ "MODALITY_UNSPECIFIED", "TEXT", "IMAGE", "VIDEO", "AUDIO", "DOCUMENT" ] }, { "name": "tokenCount", "type": "integer", "required": false, "description": "Tokens." } ] }, { "name": "responseTokensDetails[]", "type": "ModalityTokenCount[]", "required": false, "description": "Per-modality response breakdown.", "fields": [ { "name": "modality", "type": "enum", "required": false, "description": "Modality of the count.", "enum": [ "MODALITY_UNSPECIFIED", "TEXT", "IMAGE", "VIDEO", "AUDIO", "DOCUMENT" ] }, { "name": "tokenCount", "type": "integer", "required": false, "description": "Tokens." } ] }, { "name": "toolUsePromptTokensDetails[]", "type": "ModalityTokenCount[]", "required": false, "description": "Per-modality tool-use prompt breakdown.", "fields": [ { "name": "modality", "type": "enum", "required": false, "description": "Modality of the count.", "enum": [ "MODALITY_UNSPECIFIED", "TEXT", "IMAGE", "VIDEO", "AUDIO", "DOCUMENT" ] }, { "name": "tokenCount", "type": "integer", "required": false, "description": "Tokens." } ] } ], "status": [ "DOCUMENTED", "LIVE_VERIFIED" ], "example": { "promptTokenCount": 1250, "responseTokenCount": 420, "totalTokenCount": 1670, "promptTokensDetails": [ { "modality": "AUDIO", "tokenCount": 1200 }, { "modality": "TEXT", "tokenCount": 50 } ], "responseTokensDetails": [ { "modality": "AUDIO", "tokenCount": 420 } ] }, "sources": [ { "url": "https://ai.google.dev/api/live", "retrieved_at": "2026-09-18" } ], "live_observation_2026_09_18": "live (Live API): {promptTokenCount, responseTokenCount, totalTokenCount, promptTokensDetails[{modality:TEXT}], responseTokensDetails[{modality:AUDIO}], thoughtsTokenCount} attached to the turnComplete message", "_fragment": "generated/fragments/objects/gemini-tools-agents-objects.json" }, { "provider": "gemini", "api_family": "live", "name": "Modality token count", "object": "ModalityTokenCount", "schema_name": "ModalityTokenCount", "description": "Per-modality token count entry.", "fields": [ { "name": "modality", "type": "enum", "required": false, "description": "Modality of the count.", "enum": [ "MODALITY_UNSPECIFIED", "TEXT", "IMAGE", "VIDEO", "AUDIO", "DOCUMENT" ] }, { "name": "tokenCount", "type": "integer", "required": false, "description": "Tokens." } ], "status": [ "DOCUMENTED" ], "example": { "modality": "AUDIO", "tokenCount": 1200 }, "sources": [ { "url": "https://ai.google.dev/api/live", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/gemini-tools-agents-objects.json" }, { "provider": "gemini", "api_family": "live", "name": "Realtime input config", "object": "RealtimeInputConfig", "schema_name": "RealtimeInputConfig", "description": "VAD / activity handling / turn coverage.", "fields": [ { "name": "automaticActivityDetection", "type": "AutomaticActivityDetection", "required": false, "description": "Server-side VAD; enabled by default if not set.", "fields": [ { "name": "disabled", "type": "boolean", "required": false, "description": "Default false (automatic VAD on: detected voice and text count as activity). true = client must send activityStart/activityEnd." }, { "name": "startOfSpeechSensitivity", "type": "enum", "required": false, "description": "How readily speech start is detected. Default START_SENSITIVITY_HIGH.", "enum": [ "START_SENSITIVITY_UNSPECIFIED", "START_SENSITIVITY_HIGH", "START_SENSITIVITY_LOW" ] }, { "name": "prefixPaddingMs", "type": "integer (int32)", "required": false, "description": "Speech duration required before start-of-speech is committed (look-back padding). Lower = more sensitive, more false positives; 0 may clip first syllables." }, { "name": "endOfSpeechSensitivity", "type": "enum", "required": false, "description": "How readily end of speech is detected. Default END_SENSITIVITY_HIGH.", "enum": [ "END_SENSITIVITY_UNSPECIFIED", "END_SENSITIVITY_HIGH", "END_SENSITIVITY_LOW" ] }, { "name": "silenceDurationMs", "type": "integer (int32)", "required": false, "description": "Non-speech duration before end-of-speech is committed. Server default ~800 ms; recommended 500-800 ms." } ] }, { "name": "activityHandling", "type": "enum", "required": false, "description": "Effect of user activity on model output. Default START_OF_ACTIVITY_INTERRUPTS (barge-in).", "enum": [ "ACTIVITY_HANDLING_UNSPECIFIED", "START_OF_ACTIVITY_INTERRUPTS", "NO_INTERRUPTION" ] }, { "name": "turnCoverage", "type": "enum", "required": false, "description": "Which realtime input is part of the user turn. Default: Gemini 2.5 TURN_INCLUDES_ONLY_ACTIVITY; Gemini 3.1+ TURN_INCLUDES_AUDIO_ACTIVITY_AND_ALL_VIDEO.", "enum": [ "TURN_COVERAGE_UNSPECIFIED", "TURN_INCLUDES_ONLY_ACTIVITY", "TURN_INCLUDES_ALL_INPUT", "TURN_INCLUDES_AUDIO_ACTIVITY_AND_ALL_VIDEO" ] } ], "status": [ "DOCUMENTED" ], "example": { "automaticActivityDetection": { "disabled": false, "startOfSpeechSensitivity": "START_SENSITIVITY_LOW", "endOfSpeechSensitivity": "END_SENSITIVITY_LOW", "prefixPaddingMs": 20, "silenceDurationMs": 100 } }, "sources": [ { "url": "https://ai.google.dev/api/live", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/gemini-tools-agents-objects.json" }, { "provider": "gemini", "api_family": "live", "name": "Automatic activity detection", "object": "AutomaticActivityDetection", "schema_name": "AutomaticActivityDetection", "description": "Server-side VAD parameters.", "fields": [ { "name": "disabled", "type": "boolean", "required": false, "description": "Default false (automatic VAD on: detected voice and text count as activity). true = client must send activityStart/activityEnd." }, { "name": "startOfSpeechSensitivity", "type": "enum", "required": false, "description": "How readily speech start is detected. Default START_SENSITIVITY_HIGH.", "enum": [ "START_SENSITIVITY_UNSPECIFIED", "START_SENSITIVITY_HIGH", "START_SENSITIVITY_LOW" ] }, { "name": "prefixPaddingMs", "type": "integer (int32)", "required": false, "description": "Speech duration required before start-of-speech is committed (look-back padding). Lower = more sensitive, more false positives; 0 may clip first syllables." }, { "name": "endOfSpeechSensitivity", "type": "enum", "required": false, "description": "How readily end of speech is detected. Default END_SENSITIVITY_HIGH.", "enum": [ "END_SENSITIVITY_UNSPECIFIED", "END_SENSITIVITY_HIGH", "END_SENSITIVITY_LOW" ] }, { "name": "silenceDurationMs", "type": "integer (int32)", "required": false, "description": "Non-speech duration before end-of-speech is committed. Server default ~800 ms; recommended 500-800 ms." } ], "status": [ "DOCUMENTED" ], "example": { "disabled": false, "startOfSpeechSensitivity": "START_SENSITIVITY_LOW", "endOfSpeechSensitivity": "END_SENSITIVITY_LOW", "prefixPaddingMs": 20, "silenceDurationMs": 100 }, "sources": [ { "url": "https://ai.google.dev/api/live", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/gemini-tools-agents-objects.json" }, { "provider": "gemini", "api_family": "live", "name": "Audio transcription config", "object": "AudioTranscriptionConfig", "schema_name": "AudioTranscriptionConfig", "description": "Input/output transcription settings.", "fields": [ { "name": "languageCodes[]", "type": "string[]", "required": false, "description": "BCP-47 hints for languages present in the audio; omitted/empty = automatic detection." }, { "name": "customVocabulary[]", "type": "string[]", "required": false, "description": "Up to 1,000 phrases to bias recognition (best results <= 100)." }, { "name": "mode", "type": "enum", "required": false, "description": "VERBATIM (default) or SMART (disfluency removal, cleanup, formatting). Incompatible with timestamps/diarization.", "enum": [ "MODE_UNSPECIFIED", "VERBATIM", "SMART" ] }, { "name": "wordTimestamp", "type": "boolean", "required": false, "description": "Word-level timestamps (NOT supported over the Live API per live-transcribe limitations)." }, { "name": "diarization", "type": "boolean", "required": false, "description": "Speaker diarization (NOT supported over the Live API per live-transcribe limitations)." } ], "status": [ "DOCUMENTED" ], "example": { "languageCodes": [ "en-US" ], "customVocabulary": [ "Gemini", "MacLustr" ], "mode": "SMART" }, "sources": [ { "url": "https://ai.google.dev/api/live", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/gemini-tools-agents-objects.json" }, { "provider": "gemini", "api_family": "live", "name": "Context window compression config", "object": "ContextWindowCompressionConfig", "schema_name": "ContextWindowCompressionConfig", "description": "Sliding-window compression trigger/target.", "fields": [ { "name": "slidingWindow", "type": "SlidingWindow", "required": false, "description": "Sliding-window mechanism (union compressionMechanism); discards from the start, always cutting at a USER turn; system instructions kept.", "fields": [ { "name": "targetTokens", "type": "integer (int64, JSON string)", "required": false, "description": "Tokens to keep after compression. Default triggerTokens/2. Must be < triggerTokens." } ] }, { "name": "triggerTokens", "type": "integer (int64, JSON string)", "required": false, "description": "Token count (before a turn) that triggers compression. Default 80% of the model context window." } ], "status": [ "DOCUMENTED" ], "example": { "triggerTokens": "25600", "slidingWindow": { "targetTokens": "12800" } }, "sources": [ { "url": "https://ai.google.dev/api/live", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/gemini-tools-agents-objects.json" }, { "provider": "gemini", "api_family": "live", "name": "Sliding window", "object": "SlidingWindow", "schema_name": "SlidingWindow", "description": "Keep-suffix compression.", "fields": [ { "name": "targetTokens", "type": "integer (int64, JSON string)", "required": false, "description": "Tokens to keep after compression. Default triggerTokens/2. Must be < triggerTokens." } ], "status": [ "DOCUMENTED" ], "example": { "targetTokens": "12800" }, "sources": [ { "url": "https://ai.google.dev/api/live", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/gemini-tools-agents-objects.json" }, { "provider": "gemini", "api_family": "live", "name": "Session resumption config", "object": "SessionResumptionConfig", "schema_name": "SessionResumptionConfig", "description": "Resume a previous session by handle.", "fields": [ { "name": "handle", "type": "string", "required": false, "description": "Handle from a previous SessionResumptionUpdate.newHandle. Absent = new session. Valid 2 h after the last session termination." }, { "name": "transparent", "type": "boolean", "required": false, "description": "SDK-only: server includes lastConsumedClientMessageIndex in sessionResumptionUpdate for transparent reconnects. Not in the REST reference.", "status": [ "UNVERIFIED" ] } ], "status": [ "DOCUMENTED" ], "example": { "handle": "" }, "sources": [ { "url": "https://ai.google.dev/api/live", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/gemini-tools-agents-objects.json" }, { "provider": "gemini", "api_family": "live", "name": "Proactivity config", "object": "ProactivityConfig", "schema_name": "ProactivityConfig", "description": "Proactive audio toggle.", "fields": [ { "name": "proactiveAudio", "type": "boolean", "required": false, "description": "Model may decline to answer irrelevant/incomplete input. Gemini 2.5: opt-in; gemini-3.8-live*: permanently enabled (false returns an error); gemini-3.1-flash-live-preview: not supported." } ], "status": [ "DOCUMENTED" ], "example": { "proactiveAudio": true }, "sources": [ { "url": "https://ai.google.dev/api/live", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/gemini-tools-agents-objects.json" }, { "provider": "gemini", "api_family": "live", "name": "History config", "object": "HistoryConfig", "schema_name": "HistoryConfig", "description": "Initial history handshake.", "fields": [ { "name": "initialHistoryInClientContent", "type": "boolean", "required": false, "description": "If true, after setupComplete the server first ingests clientContent until turnComplete=true (history may end with role model) without a model call; then realtimeInput starts the conversation." } ], "status": [ "DOCUMENTED" ], "example": { "initialHistoryInClientContent": true }, "sources": [ { "url": "https://ai.google.dev/api/live", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/gemini-tools-agents-objects.json" }, { "provider": "gemini", "api_family": "live", "name": "Speech config", "object": "SpeechConfig", "schema_name": "SpeechConfig", "description": "Voice and language.", "fields": [ { "name": "voiceConfig", "type": "VoiceConfig", "required": false, "description": "Single-voice output configuration.", "fields": [ { "name": "prebuiltVoiceConfig", "type": "PrebuiltVoiceConfig", "required": false, "description": "The prebuilt voice to use.", "fields": [ { "name": "voiceName", "type": "string", "required": false, "description": "Optional. Name of the preset voice (any Gemini TTS voice: Zephyr, Puck, Charon, Kore, Fenrir, Leda, Orus, Aoede, Callirrhoe, Autonoe, Enceladus, Iapetus, Umbriel, Algieba, Despina, Erinome, Algenib, Rasalgethi, Laomedeia, Achernar, Alnilam, Schedar, Gacrux, Pulcherrima, Achird, Zubenelgenubi, Vindemiatrix, Sadachbia, Sadaltager, Sulafat)." } ] } ] }, { "name": "multiSpeakerVoiceConfig", "type": "MultiSpeakerVoiceConfig", "required": false, "description": "Multi-speaker setup; mutually exclusive with voiceConfig (TTS feature; not documented for Live — UNVERIFIED in Live).", "status": [ "UNVERIFIED" ], "fields": [ { "name": "speakerVoiceConfigs[]", "type": "SpeakerVoiceConfig[]", "required": true, "description": "Required. All enabled speaker voices (SDK doc: exactly two).", "fields": [ { "name": "speaker", "type": "string", "required": true, "description": "Required. Speaker name as used in the prompt." }, { "name": "voiceConfig", "type": "VoiceConfig", "required": true, "description": "Required. Voice for this speaker.", "fields": [ { "name": "prebuiltVoiceConfig", "type": "PrebuiltVoiceConfig", "required": false, "description": "The prebuilt voice to use.", "fields": [ { "name": "voiceName", "type": "string", "required": false, "description": "Optional. Name of the preset voice (any Gemini TTS voice: Zephyr, Puck, Charon, Kore, Fenrir, Leda, Orus, Aoede, Callirrhoe, Autonoe, Enceladus, Iapetus, Umbriel, Algieba, Despina, Erinome, Algenib, Rasalgethi, Laomedeia, Achernar, Alnilam, Schedar, Gacrux, Pulcherrima, Achird, Zubenelgenubi, Vindemiatrix, Sadachbia, Sadaltager, Sulafat)." } ] } ] } ] } ] }, { "name": "languageCode", "type": "string", "required": false, "description": "Optional. BCP-47 language code for speech recognition and synthesis (de-DE, en-AU, en-GB, en-IN, en-US, es-US, fr-FR, hi-IN, pt-BR, ar-XA, es-ES, fr-CA, id-ID, it-IT, ja-JP, tr-TR, vi-VN, bn-IN, gu-IN, kn-IN, ml-IN, mr-IN, ta-IN, te-IN, nl-NL, ko-KR, cmn-CN, pl-PL, ru-RU, th-TH). Native audio output models choose the language automatically and do NOT support setting it explicitly." } ], "status": [ "DOCUMENTED" ], "example": { "voiceConfig": { "prebuiltVoiceConfig": { "voiceName": "Kore" } } }, "sources": [ { "url": "https://ai.google.dev/api/live", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/gemini-tools-agents-objects.json" }, { "provider": "gemini", "api_family": "live", "name": "Voice config", "object": "VoiceConfig", "schema_name": "VoiceConfig", "description": "Voice selection wrapper.", "fields": [ { "name": "prebuiltVoiceConfig", "type": "PrebuiltVoiceConfig", "required": false, "description": "The prebuilt voice to use.", "fields": [ { "name": "voiceName", "type": "string", "required": false, "description": "Optional. Name of the preset voice (any Gemini TTS voice: Zephyr, Puck, Charon, Kore, Fenrir, Leda, Orus, Aoede, Callirrhoe, Autonoe, Enceladus, Iapetus, Umbriel, Algieba, Despina, Erinome, Algenib, Rasalgethi, Laomedeia, Achernar, Alnilam, Schedar, Gacrux, Pulcherrima, Achird, Zubenelgenubi, Vindemiatrix, Sadachbia, Sadaltager, Sulafat)." } ] } ], "status": [ "DOCUMENTED" ], "example": { "prebuiltVoiceConfig": { "voiceName": "Kore" } }, "sources": [ { "url": "https://ai.google.dev/api/live", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/gemini-tools-agents-objects.json" }, { "provider": "gemini", "api_family": "live", "name": "Prebuilt voice config", "object": "PrebuiltVoiceConfig", "schema_name": "PrebuiltVoiceConfig", "description": "Named preset voice.", "fields": [ { "name": "voiceName", "type": "string", "required": false, "description": "Optional. Name of the preset voice (any Gemini TTS voice: Zephyr, Puck, Charon, Kore, Fenrir, Leda, Orus, Aoede, Callirrhoe, Autonoe, Enceladus, Iapetus, Umbriel, Algieba, Despina, Erinome, Algenib, Rasalgethi, Laomedeia, Achernar, Alnilam, Schedar, Gacrux, Pulcherrima, Achird, Zubenelgenubi, Vindemiatrix, Sadachbia, Sadaltager, Sulafat)." } ], "status": [ "DOCUMENTED" ], "example": { "voiceName": "Kore" }, "sources": [ { "url": "https://ai.google.dev/api/live", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/gemini-tools-agents-objects.json" }, { "provider": "gemini", "api_family": "live", "name": "Multi-speaker voice config", "object": "MultiSpeakerVoiceConfig", "schema_name": "MultiSpeakerVoiceConfig", "description": "Two-speaker TTS voices (Live support undocumented).", "fields": [ { "name": "speakerVoiceConfigs[]", "type": "SpeakerVoiceConfig[]", "required": true, "description": "Required. All enabled speaker voices (SDK doc: exactly two).", "fields": [ { "name": "speaker", "type": "string", "required": true, "description": "Required. Speaker name as used in the prompt." }, { "name": "voiceConfig", "type": "VoiceConfig", "required": true, "description": "Required. Voice for this speaker.", "fields": [ { "name": "prebuiltVoiceConfig", "type": "PrebuiltVoiceConfig", "required": false, "description": "The prebuilt voice to use.", "fields": [ { "name": "voiceName", "type": "string", "required": false, "description": "Optional. Name of the preset voice (any Gemini TTS voice: Zephyr, Puck, Charon, Kore, Fenrir, Leda, Orus, Aoede, Callirrhoe, Autonoe, Enceladus, Iapetus, Umbriel, Algieba, Despina, Erinome, Algenib, Rasalgethi, Laomedeia, Achernar, Alnilam, Schedar, Gacrux, Pulcherrima, Achird, Zubenelgenubi, Vindemiatrix, Sadachbia, Sadaltager, Sulafat)." } ] } ] } ] } ], "status": [ "UNVERIFIED" ], "example": { "speakerVoiceConfigs": [ { "speaker": "Joe", "voiceConfig": { "prebuiltVoiceConfig": { "voiceName": "Kore" } } }, { "speaker": "Jane", "voiceConfig": { "prebuiltVoiceConfig": { "voiceName": "Puck" } } } ] }, "sources": [ { "url": "https://ai.google.dev/api/live", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/gemini-tools-agents-objects.json" }, { "provider": "gemini", "api_family": "live", "name": "Thinking config", "object": "ThinkingConfig", "schema_name": "ThinkingConfig", "description": "Reasoning depth / thought summaries.", "fields": [ { "name": "thinkingLevel", "type": "enum", "required": false, "description": "Reasoning depth. gemini-3.1-flash-live-preview: MINIMAL (default), LOW, MEDIUM, HIGH. gemini-3.8-live-extended-thinking: LOW, MEDIUM, HIGH (MINIMAL not supported). gemini-3.8-live: NOT supported — omit thinkingConfig.", "enum": [ "THINKING_LEVEL_UNSPECIFIED", "MINIMAL", "LOW", "MEDIUM", "HIGH" ] }, { "name": "thinkingBudget", "type": "integer", "required": false, "description": "Thoughts token budget (0 disabled, -1 automatic). Gemini 2.5 native-audio models; replaced by thinkingLevel from Gemini 3.1 onward." }, { "name": "includeThoughts", "type": "boolean", "required": false, "description": "Return thought summaries in modelTurn parts (part.thought=true) when available." } ], "status": [ "DOCUMENTED" ], "example": { "thinkingLevel": "LOW", "includeThoughts": true }, "sources": [ { "url": "https://ai.google.dev/api/live", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/gemini-tools-agents-objects.json" }, { "provider": "gemini", "api_family": "live", "name": "Translation config", "object": "TranslationConfig", "schema_name": "TranslationConfig", "description": "Live translation target/echo.", "fields": [ { "name": "targetLanguageCode", "type": "string", "required": true, "description": "Required. BCP-47 target language (e.g. \"en\", \"es\", \"pl\"). Guide: defaults to \"en\"." }, { "name": "echoTargetLanguage", "type": "boolean", "required": false, "description": "If true, input already in the target language is echoed (parroted) as audio; if false (default) the model stays silent for it." } ], "status": [ "DOCUMENTED" ], "example": { "targetLanguageCode": "pl", "echoTargetLanguage": true }, "sources": [ { "url": "https://ai.google.dev/api/live", "retrieved_at": "2026-09-18" }, { "url": "https://ai.google.dev/gemini-api/docs/live-api/live-translate", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/gemini-tools-agents-objects.json" }, { "provider": "gemini", "api_family": "live", "name": "Transcription", "object": "BidiGenerateContentTranscription", "schema_name": "BidiGenerateContentTranscription", "description": "Transcript chunk (input/interim/output).", "fields": [ { "name": "text", "type": "string", "required": false, "description": "Transcription text." }, { "name": "languageCode", "type": "string", "required": false, "description": "BCP-47 code of the transcript (translate model reports it)." }, { "name": "finished", "type": "boolean", "required": false, "description": "SDK-only: end of transcription.", "status": [ "UNVERIFIED" ] } ], "status": [ "DOCUMENTED" ], "example": { "text": "Hello", "languageCode": "en" }, "sources": [ { "url": "https://ai.google.dev/api/live", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/gemini-tools-agents-objects.json" }, { "provider": "gemini", "api_family": "live", "name": "Activity start", "object": "BidiGenerateContentRealtimeInput.ActivityStart", "schema_name": "BidiGenerateContentRealtimeInput.ActivityStart", "description": "Empty marker: user activity begins (manual VAD).", "fields": [], "status": [ "DOCUMENTED" ], "example": {}, "sources": [ { "url": "https://ai.google.dev/api/live", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/gemini-tools-agents-objects.json" }, { "provider": "gemini", "api_family": "live", "name": "Activity end", "object": "BidiGenerateContentRealtimeInput.ActivityEnd", "schema_name": "BidiGenerateContentRealtimeInput.ActivityEnd", "description": "Empty marker: user activity ends (manual VAD).", "fields": [], "status": [ "DOCUMENTED" ], "example": {}, "sources": [ { "url": "https://ai.google.dev/api/live", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/gemini-tools-agents-objects.json" }, { "provider": "gemini", "api_family": "live", "name": "Blob (realtime media)", "object": "Blob", "schema_name": "Blob", "description": "Base64 media chunk with MIME type.", "fields": [ { "name": "mimeType", "type": "string", "required": true, "description": "IANA MIME type, e.g. audio/pcm;rate=16000, image/jpeg, image/png." }, { "name": "data", "type": "string (base64)", "required": true, "description": "Raw bytes, base64-encoded in JSON." } ], "status": [ "DOCUMENTED" ], "example": { "mimeType": "audio/pcm;rate=16000", "data": "" }, "sources": [ { "url": "https://ai.google.dev/api/live", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/gemini-tools-agents-objects.json" }, { "provider": "gemini", "api_family": "live", "name": "Function call", "object": "FunctionCall", "schema_name": "FunctionCall", "description": "Model-requested call (Live: always carries id).", "fields": [ { "name": "id", "type": "string", "required": false, "description": "Unique id to echo in FunctionResponse.id." }, { "name": "name", "type": "string", "required": true, "description": "Function name." }, { "name": "args", "type": "object", "required": false, "description": "Arguments." } ], "status": [ "DOCUMENTED", "LIVE_VERIFIED" ], "example": { "id": "call_123", "name": "searchFlights", "args": { "destination": "Seattle" } }, "sources": [ { "url": "https://ai.google.dev/api/live", "retrieved_at": "2026-09-18" } ], "live_observation_2026_09_18": "live: {name, args, id: call_…} + sibling part field thoughtSignature (first call of a parallel turn only); Live API toolCall ids look like function-call-", "_fragment": "generated/fragments/objects/gemini-tools-agents-objects.json" }, { "provider": "gemini", "api_family": "live", "name": "Function response (Live extras)", "object": "FunctionResponse", "schema_name": "FunctionResponse", "description": "Function result; Live-only scheduling and willContinue for NON_BLOCKING calls.", "fields": [ { "name": "id", "type": "string", "required": false, "description": "Must match FunctionCall.id." }, { "name": "name", "type": "string", "required": true, "description": "Required. Function name." }, { "name": "response", "type": "object", "required": true, "description": "Required. JSON result; keys of your choice (\"output\", \"result\", \"error\" ...)." }, { "name": "scheduling", "type": "enum", "required": false, "description": "NON_BLOCKING calls only: INTERRUPT (interrupt and speak now), WHEN_IDLE (default; after current output), SILENT (add to context only).", "enum": [ "SCHEDULING_UNSPECIFIED", "SILENT", "WHEN_IDLE", "INTERRUPT" ] }, { "name": "willContinue", "type": "boolean", "required": false, "description": "NON_BLOCKING calls only: more responses follow (generator). false + empty response finishes the call (still may trigger generation unless scheduling=SILENT)." }, { "name": "parts[]", "type": "FunctionResponsePart[]", "required": false, "description": "Multimodal parts (inlineData/fileData) of the response." } ], "status": [ "DOCUMENTED" ], "example": { "id": "call_123", "name": "searchFlights", "response": { "output": { "flight": "DL 145", "price": "$145" }, "scheduling": "INTERRUPT" } }, "sources": [ { "url": "https://ai.google.dev/api/live", "retrieved_at": "2026-09-18" }, { "url": "https://ai.google.dev/gemini-api/docs/live-api/tools", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/gemini-tools-agents-objects.json" }, { "provider": "gemini", "api_family": "live", "name": "Function declaration (Live behavior)", "object": "FunctionDeclaration", "schema_name": "FunctionDeclaration", "description": "Function declaration with Live-only `behavior` (BLOCKING | NON_BLOCKING).", "fields": [ { "name": "name", "type": "string", "required": true, "description": "Required. Function name (a-z, A-Z, 0-9, _ - : . ; max 128)." }, { "name": "description", "type": "string", "required": true, "description": "Required. Function description." }, { "name": "parameters", "type": "Schema", "required": false, "description": "OpenAPI-style parameter schema." }, { "name": "parametersJsonSchema", "type": "object", "required": false, "description": "JSON Schema alternative to parameters." }, { "name": "behavior", "type": "enum", "required": false, "description": "Live-only. BLOCKING = model waits for the response; NON_BLOCKING = asynchronous (conversation continues). Default: gemini-3.8-live NON_BLOCKING; gemini-3.8-live-extended-thinking NON_BLOCKING only (BLOCKING = hard error); gemini-3.1-flash-live-preview synchronous only (NON_BLOCKING not supported); Gemini 2.5 supports both.", "enum": [ "UNSPECIFIED", "BLOCKING", "NON_BLOCKING" ] }, { "name": "response", "type": "Schema", "required": false, "description": "Response schema." }, { "name": "responseJsonSchema", "type": "object", "required": false, "description": "JSON Schema for the response." } ], "status": [ "DOCUMENTED" ], "example": { "name": "searchFlights", "description": "Searches for flights between cities.", "behavior": "NON_BLOCKING", "parameters": { "type": "OBJECT", "properties": { "destination": { "type": "STRING" } }, "required": [ "destination" ] } }, "sources": [ { "url": "https://ai.google.dev/gemini-api/docs/live-api/tools", "retrieved_at": "2026-09-18" }, { "url": "https://ai.google.dev/api/caching#FunctionDeclaration", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/gemini-tools-agents-objects.json" }, { "provider": "gemini", "api_family": "live", "name": "Voice activity (SDK)", "object": "VoiceActivity", "schema_name": "VoiceActivity", "description": "SDK-only server message: VAD start/end with audio offset.", "fields": [ { "name": "voiceActivityType", "type": "enum", "required": false, "description": "", "enum": [ "TYPE_UNSPECIFIED", "ACTIVITY_START", "ACTIVITY_END" ] }, { "name": "audioOffset", "type": "string (Duration)", "required": false, "description": "" } ], "status": [ "UNVERIFIED" ], "example": { "voiceActivityType": "ACTIVITY_START", "audioOffset": "1.250s" }, "sources": [ { "url": "https://github.com/googleapis/python-genai/blob/main/google/genai/types.py", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/gemini-tools-agents-objects.json" }, { "provider": "gemini", "api_family": "auth-tokens", "name": "Ephemeral auth token", "object": "AuthToken", "schema_name": "AuthToken", "description": "Request/response body of POST /v1beta/auth_tokens.", "fields": [ { "name": "name", "type": "string", "required": false, "description": "Output only. The token itself (pass it to the client)." }, { "name": "uses", "type": "integer (int32)", "required": false, "description": "Times the token can start a session; 0 = unlimited; default 1. Resuming a session does not count." }, { "name": "expireTime", "type": "string (RFC 3339 Timestamp)", "required": false, "description": "After this, messages in sessions using the token are rejected (session may be closed). Default now+30 min; must be < 20 h ahead." }, { "name": "newSessionExpireTime", "type": "string (RFC 3339 Timestamp)", "required": false, "description": "After this, NEW sessions with the token are rejected. Default now+60 s; must be < 20 h ahead." }, { "name": "fieldMask", "type": "string (FieldMask)", "required": false, "description": "Empty + no bidiGenerateContentSetup: setup taken from the WebSocket. Empty + setup present: setup taken entirely from the token (client setup ignored). Non-empty: listed fields overwrite the client's setup." }, { "name": "bidiGenerateContentSetup", "type": "BidiGenerateContentSetup", "required": false, "description": "Union `config`: locked Live setup for sessions using this token.", "fields": [ { "name": "model", "type": "string", "required": true, "description": "Required. `models/{model}` resource name (e.g. models/gemini-3.8-live)." }, { "name": "generationConfig", "type": "GenerationConfig (subset)", "required": false, "description": "Not supported in Live: responseLogprobs, responseMimeType, logprobs, responseSchema, responseJsonSchema, stopSequence, skipResponseCache, routingConfig, audioTimestamp.", "fields": [ { "name": "responseModalities[]", "type": "enum[]", "required": false, "description": "Requested output modalities. Native audio models support only [\"AUDIO\"] (use outputAudioTranscription for text); gemini-3.5-transcribe-live uses [\"TEXT\"]. SDK default: AUDIO.", "enum": [ "TEXT", "AUDIO" ] }, { "name": "speechConfig", "type": "SpeechConfig", "required": false, "description": "Voice / language configuration.", "fields": [ { "name": "voiceConfig", "type": "VoiceConfig", "required": false, "description": "Single-voice output configuration.", "fields": [ { "name": "prebuiltVoiceConfig", "type": "PrebuiltVoiceConfig", "required": false, "description": "The prebuilt voice to use.", "fields": [ { "name": "voiceName", "type": "string", "required": false, "description": "Optional. Name of the preset voice (any Gemini TTS voice: Zephyr, Puck, Charon, Kore, Fenrir, Leda, Orus, Aoede, Callirrhoe, Autonoe, Enceladus, Iapetus, Umbriel, Algieba, Despina, Erinome, Algenib, Rasalgethi, Laomedeia, Achernar, Alnilam, Schedar, Gacrux, Pulcherrima, Achird, Zubenelgenubi, Vindemiatrix, Sadachbia, Sadaltager, Sulafat)." } ] } ] }, { "name": "multiSpeakerVoiceConfig", "type": "MultiSpeakerVoiceConfig", "required": false, "description": "Multi-speaker setup; mutually exclusive with voiceConfig (TTS feature; not documented for Live — UNVERIFIED in Live).", "status": [ "UNVERIFIED" ], "fields": [ { "name": "speakerVoiceConfigs[]", "type": "SpeakerVoiceConfig[]", "required": true, "description": "Required. All enabled speaker voices (SDK doc: exactly two).", "fields": [ { "name": "speaker", "type": "string", "required": true, "description": "Required. Speaker name as used in the prompt." }, { "name": "voiceConfig", "type": "VoiceConfig", "required": true, "description": "Required. Voice for this speaker.", "fields": [ { "name": "prebuiltVoiceConfig", "type": "PrebuiltVoiceConfig", "required": false, "description": "The prebuilt voice to use.", "fields": [ { "name": "voiceName", "type": "string", "required": false, "description": "Optional. Name of the preset voice (any Gemini TTS voice: Zephyr, Puck, Charon, Kore, Fenrir, Leda, Orus, Aoede, Callirrhoe, Autonoe, Enceladus, Iapetus, Umbriel, Algieba, Despina, Erinome, Algenib, Rasalgethi, Laomedeia, Achernar, Alnilam, Schedar, Gacrux, Pulcherrima, Achird, Zubenelgenubi, Vindemiatrix, Sadachbia, Sadaltager, Sulafat)." } ] } ] } ] } ] }, { "name": "languageCode", "type": "string", "required": false, "description": "Optional. BCP-47 language code for speech recognition and synthesis (de-DE, en-AU, en-GB, en-IN, en-US, es-US, fr-FR, hi-IN, pt-BR, ar-XA, es-ES, fr-CA, id-ID, it-IT, ja-JP, tr-TR, vi-VN, bn-IN, gu-IN, kn-IN, ml-IN, mr-IN, ta-IN, te-IN, nl-NL, ko-KR, cmn-CN, pl-PL, ru-RU, th-TH). Native audio output models choose the language automatically and do NOT support setting it explicitly." } ] }, { "name": "mediaResolution", "type": "enum", "required": false, "description": "Token allocation per visual input frame (LOW=64 tokens, MEDIUM=256, HIGH=zoomed reframing 256). Audio tokenization is fixed per second regardless.", "enum": [ "MEDIA_RESOLUTION_UNSPECIFIED", "MEDIA_RESOLUTION_LOW", "MEDIA_RESOLUTION_MEDIUM", "MEDIA_RESOLUTION_HIGH" ] }, { "name": "thinkingConfig", "type": "ThinkingConfig", "required": false, "description": "Thinking configuration (model-dependent, see thinkingLevel).", "fields": [ { "name": "thinkingLevel", "type": "enum", "required": false, "description": "Reasoning depth. gemini-3.1-flash-live-preview: MINIMAL (default), LOW, MEDIUM, HIGH. gemini-3.8-live-extended-thinking: LOW, MEDIUM, HIGH (MINIMAL not supported). gemini-3.8-live: NOT supported — omit thinkingConfig.", "enum": [ "THINKING_LEVEL_UNSPECIFIED", "MINIMAL", "LOW", "MEDIUM", "HIGH" ] }, { "name": "thinkingBudget", "type": "integer", "required": false, "description": "Thoughts token budget (0 disabled, -1 automatic). Gemini 2.5 native-audio models; replaced by thinkingLevel from Gemini 3.1 onward." }, { "name": "includeThoughts", "type": "boolean", "required": false, "description": "Return thought summaries in modelTurn parts (part.thought=true) when available." } ] }, { "name": "translationConfig", "type": "TranslationConfig", "required": false, "description": "Live translation (gemini-3.5-live-translate-preview only).", "fields": [ { "name": "targetLanguageCode", "type": "string", "required": true, "description": "Required. BCP-47 target language (e.g. \"en\", \"es\", \"pl\"). Guide: defaults to \"en\"." }, { "name": "echoTargetLanguage", "type": "boolean", "required": false, "description": "If true, input already in the target language is echoed (parroted) as audio; if false (default) the model stays silent for it." } ] }, { "name": "enableAffectiveDialog", "type": "boolean", "required": false, "description": "Detect emotions and adapt responses (Gemini 2.5 native audio only; not supported on 3.1; removed on 3.8 — remove from code)." }, { "name": "temperature", "type": "number", "required": false, "description": "Sampling temperature." }, { "name": "topP", "type": "number", "required": false, "description": "Nucleus sampling." }, { "name": "topK", "type": "integer", "required": false, "description": "Top-k sampling." }, { "name": "maxOutputTokens", "type": "integer", "required": false, "description": "Max output tokens." }, { "name": "candidateCount", "type": "integer", "required": false, "description": "Number of candidates." }, { "name": "presencePenalty", "type": "number", "required": false, "description": "Presence penalty." }, { "name": "frequencyPenalty", "type": "number", "required": false, "description": "Frequency penalty." }, { "name": "seed", "type": "integer", "required": false, "description": "Best-effort deterministic seed (SDK LiveConnectConfig)." } ] }, { "name": "systemInstruction", "type": "Content", "required": false, "description": "Text-only parts; each part becomes a separate paragraph.", "fields": [ { "name": "role", "type": "string", "required": false, "description": "\"user\" or \"model\".", "enum": [ "user", "model" ] }, { "name": "parts[]", "type": "Part[]", "required": false, "description": "Parts: text, inlineData{mimeType,data}, functionCall, functionResponse, thought ... (systemInstruction: text parts only, each part a separate paragraph)." } ] }, { "name": "tools[]", "type": "Tool[]", "required": false, "description": "Tools the model may use.", "fields": [ { "name": "functionDeclarations[]", "type": "FunctionDeclaration[]", "required": false, "description": "Client-executed functions.", "fields": [ { "name": "name", "type": "string", "required": true, "description": "Required. Function name (a-z, A-Z, 0-9, _ - : . ; max 128)." }, { "name": "description", "type": "string", "required": true, "description": "Required. Function description." }, { "name": "parameters", "type": "Schema", "required": false, "description": "OpenAPI-style parameter schema." }, { "name": "parametersJsonSchema", "type": "object", "required": false, "description": "JSON Schema alternative to parameters." }, { "name": "behavior", "type": "enum", "required": false, "description": "Live-only. BLOCKING = model waits for the response; NON_BLOCKING = asynchronous (conversation continues). Default: gemini-3.8-live NON_BLOCKING; gemini-3.8-live-extended-thinking NON_BLOCKING only (BLOCKING = hard error); gemini-3.1-flash-live-preview synchronous only (NON_BLOCKING not supported); Gemini 2.5 supports both.", "enum": [ "UNSPECIFIED", "BLOCKING", "NON_BLOCKING" ] }, { "name": "response", "type": "Schema", "required": false, "description": "Response schema." }, { "name": "responseJsonSchema", "type": "object", "required": false, "description": "JSON Schema for the response." } ] }, { "name": "googleSearch", "type": "object {}", "required": false, "description": "Grounding with Google Search (supported on Live agent models; not on translate/transcribe)." }, { "name": "codeExecution", "type": "object {}", "required": false, "description": "Not supported on current Live models (tools table)." }, { "name": "urlContext", "type": "object {}", "required": false, "description": "Not supported on current Live models (tools table); serverContent.urlContextMetadata exists in the schema nonetheless." }, { "name": "googleMaps", "type": "object", "required": false, "description": "Not supported on Live models." } ] }, { "name": "realtimeInputConfig", "type": "RealtimeInputConfig", "required": false, "description": "VAD / activity handling / turn coverage.", "fields": [ { "name": "automaticActivityDetection", "type": "AutomaticActivityDetection", "required": false, "description": "Server-side VAD; enabled by default if not set.", "fields": [ { "name": "disabled", "type": "boolean", "required": false, "description": "Default false (automatic VAD on: detected voice and text count as activity). true = client must send activityStart/activityEnd." }, { "name": "startOfSpeechSensitivity", "type": "enum", "required": false, "description": "How readily speech start is detected. Default START_SENSITIVITY_HIGH.", "enum": [ "START_SENSITIVITY_UNSPECIFIED", "START_SENSITIVITY_HIGH", "START_SENSITIVITY_LOW" ] }, { "name": "prefixPaddingMs", "type": "integer (int32)", "required": false, "description": "Speech duration required before start-of-speech is committed (look-back padding). Lower = more sensitive, more false positives; 0 may clip first syllables." }, { "name": "endOfSpeechSensitivity", "type": "enum", "required": false, "description": "How readily end of speech is detected. Default END_SENSITIVITY_HIGH.", "enum": [ "END_SENSITIVITY_UNSPECIFIED", "END_SENSITIVITY_HIGH", "END_SENSITIVITY_LOW" ] }, { "name": "silenceDurationMs", "type": "integer (int32)", "required": false, "description": "Non-speech duration before end-of-speech is committed. Server default ~800 ms; recommended 500-800 ms." } ] }, { "name": "activityHandling", "type": "enum", "required": false, "description": "Effect of user activity on model output. Default START_OF_ACTIVITY_INTERRUPTS (barge-in).", "enum": [ "ACTIVITY_HANDLING_UNSPECIFIED", "START_OF_ACTIVITY_INTERRUPTS", "NO_INTERRUPTION" ] }, { "name": "turnCoverage", "type": "enum", "required": false, "description": "Which realtime input is part of the user turn. Default: Gemini 2.5 TURN_INCLUDES_ONLY_ACTIVITY; Gemini 3.1+ TURN_INCLUDES_AUDIO_ACTIVITY_AND_ALL_VIDEO.", "enum": [ "TURN_COVERAGE_UNSPECIFIED", "TURN_INCLUDES_ONLY_ACTIVITY", "TURN_INCLUDES_ALL_INPUT", "TURN_INCLUDES_AUDIO_ACTIVITY_AND_ALL_VIDEO" ] } ] }, { "name": "sessionResumption", "type": "SessionResumptionConfig", "required": false, "description": "If present the server sends sessionResumptionUpdate messages.", "fields": [ { "name": "handle", "type": "string", "required": false, "description": "Handle from a previous SessionResumptionUpdate.newHandle. Absent = new session. Valid 2 h after the last session termination." }, { "name": "transparent", "type": "boolean", "required": false, "description": "SDK-only: server includes lastConsumedClientMessageIndex in sessionResumptionUpdate for transparent reconnects. Not in the REST reference.", "status": [ "UNVERIFIED" ] } ] }, { "name": "contextWindowCompression", "type": "ContextWindowCompressionConfig", "required": false, "description": "Automatic context reduction beyond a length; enables unlimited session duration.", "fields": [ { "name": "slidingWindow", "type": "SlidingWindow", "required": false, "description": "Sliding-window mechanism (union compressionMechanism); discards from the start, always cutting at a USER turn; system instructions kept.", "fields": [ { "name": "targetTokens", "type": "integer (int64, JSON string)", "required": false, "description": "Tokens to keep after compression. Default triggerTokens/2. Must be < triggerTokens." } ] }, { "name": "triggerTokens", "type": "integer (int64, JSON string)", "required": false, "description": "Token count (before a turn) that triggers compression. Default 80% of the model context window." } ] }, { "name": "inputAudioTranscription", "type": "AudioTranscriptionConfig", "required": false, "description": "Enable transcription of user audio ({} = defaults).", "fields": [ { "name": "languageCodes[]", "type": "string[]", "required": false, "description": "BCP-47 hints for languages present in the audio; omitted/empty = automatic detection." }, { "name": "customVocabulary[]", "type": "string[]", "required": false, "description": "Up to 1,000 phrases to bias recognition (best results <= 100)." }, { "name": "mode", "type": "enum", "required": false, "description": "VERBATIM (default) or SMART (disfluency removal, cleanup, formatting). Incompatible with timestamps/diarization.", "enum": [ "MODE_UNSPECIFIED", "VERBATIM", "SMART" ] }, { "name": "wordTimestamp", "type": "boolean", "required": false, "description": "Word-level timestamps (NOT supported over the Live API per live-transcribe limitations)." }, { "name": "diarization", "type": "boolean", "required": false, "description": "Speaker diarization (NOT supported over the Live API per live-transcribe limitations)." } ] }, { "name": "outputAudioTranscription", "type": "AudioTranscriptionConfig", "required": false, "description": "Enable transcription of model audio ({} = defaults).", "fields": [ { "name": "languageCodes[]", "type": "string[]", "required": false, "description": "BCP-47 hints for languages present in the audio; omitted/empty = automatic detection." }, { "name": "customVocabulary[]", "type": "string[]", "required": false, "description": "Up to 1,000 phrases to bias recognition (best results <= 100)." }, { "name": "mode", "type": "enum", "required": false, "description": "VERBATIM (default) or SMART (disfluency removal, cleanup, formatting). Incompatible with timestamps/diarization.", "enum": [ "MODE_UNSPECIFIED", "VERBATIM", "SMART" ] }, { "name": "wordTimestamp", "type": "boolean", "required": false, "description": "Word-level timestamps (NOT supported over the Live API per live-transcribe limitations)." }, { "name": "diarization", "type": "boolean", "required": false, "description": "Speaker diarization (NOT supported over the Live API per live-transcribe limitations)." } ] }, { "name": "proactivity", "type": "ProactivityConfig", "required": false, "description": "Proactive audio.", "fields": [ { "name": "proactiveAudio", "type": "boolean", "required": false, "description": "Model may decline to answer irrelevant/incomplete input. Gemini 2.5: opt-in; gemini-3.8-live*: permanently enabled (false returns an error); gemini-3.1-flash-live-preview: not supported." } ] }, { "name": "historyConfig", "type": "HistoryConfig", "required": false, "description": "Initial-history handshake.", "fields": [ { "name": "initialHistoryInClientContent", "type": "boolean", "required": false, "description": "If true, after setupComplete the server first ingests clientContent until turnComplete=true (history may end with role model) without a model call; then realtimeInput starts the conversation." } ] }, { "name": "labels", "type": "object", "required": false, "description": "Discovery-only: user metadata labels (e.g. {\"safety_identifier\": ...}); not in the public Live reference page.", "status": [ "UNVERIFIED" ] } ] }, { "name": "liveConnectConstraints", "type": "LiveConnectConstraints {model, config}", "required": false, "description": "Shape used by the official REST curl examples and SDKs (model + LiveConnectConfig); not present in the discovery schema for AuthToken — REST acceptance UNVERIFIED (SDK translates it to bidiGenerateContentSetup + fieldMask).", "status": [ "UNVERIFIED" ] } ], "status": [ "DOCUMENTED", "PREVIEW", "LIVE_VERIFIED" ], "example": { "uses": 1, "expireTime": "2026-09-18T20:30:00Z", "newSessionExpireTime": "2026-09-18T20:01:00Z", "bidiGenerateContentSetup": { "model": "models/gemini-3.8-live", "generationConfig": { "responseModalities": [ "AUDIO" ] }, "sessionResumption": {} } }, "sources": [ { "url": "https://ai.google.dev/api/live", "retrieved_at": "2026-09-18" }, { "url": "https://ai.google.dev/gemini-api/docs/live-api/ephemeral-tokens", "retrieved_at": "2026-09-18" }, { "url": "https://generativelanguage.googleapis.com/$discovery/rest?version=v1beta", "retrieved_at": "2026-09-18" } ], "live_observation_2026_09_18": "live: response is exactly {name: 'auth_tokens/…'}", "_fragment": "generated/fragments/objects/gemini-tools-agents-objects.json" }, { "provider": "gemini", "api_family": "auth-tokens", "name": "Create auth token request", "object": "CreateAuthTokenRequest", "schema_name": "CreateAuthTokenRequest", "description": "RPC wrapper {authToken}; REST body is the AuthToken itself.", "fields": [ { "name": "authToken", "type": "AuthToken", "required": true, "description": "Required." } ], "status": [ "DOCUMENTED", "PREVIEW" ], "example": { "authToken": { "uses": 1 } }, "sources": [ { "url": "https://ai.google.dev/api/live", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/gemini-tools-agents-objects.json" }, { "provider": "gemini", "api_family": "auth-tokens", "name": "Live connect constraints (SDK / REST examples)", "object": "LiveConnectConstraints", "schema_name": "LiveConnectConstraints", "description": "Model + config to lock into an ephemeral token.", "fields": [ { "name": "model", "type": "string", "required": false, "description": "Model id/resource to lock (e.g. gemini-3.8-live or models/gemini-3.8-live)." }, { "name": "config", "type": "LiveConnectConfig", "required": false, "description": "SDK-style live config to lock (responseModalities, sessionResumption, systemInstruction, tools, translationConfig ...)." } ], "status": [ "DOCUMENTED", "PREVIEW", "UNVERIFIED" ], "example": { "model": "models/gemini-3.8-live", "config": { "sessionResumption": {}, "responseModalities": [ "AUDIO" ] } }, "sources": [ { "url": "https://ai.google.dev/gemini-api/docs/live-api/ephemeral-tokens", "retrieved_at": "2026-09-18" }, { "url": "https://github.com/googleapis/python-genai/blob/main/google/genai/types.py", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/gemini-tools-agents-objects.json" }, { "provider": "openai", "api_family": "agents-platform/agents", "name": "Agent (saved, reusable agent definition)", "object": "agent", "schema_name": "AgentResource", "description": "A reusable agent scoped to the caller's project.", "fields": [ { "name": "id", "type": "string", "required": true, "description": "The ID of the reusable agent." }, { "name": "object", "type": "string", "required": true, "description": "The object type. Always `agent`." }, { "name": "created_at", "type": "integer", "required": true, "description": "The Unix timestamp, in seconds, when the agent was created." }, { "name": "updated_at", "type": "integer", "required": true, "description": "The Unix timestamp, in seconds, when the agent was last updated." }, { "name": "name", "type": "string | null", "required": true, "description": "A human-readable name for the agent, or null if it is unnamed." }, { "name": "metadata", "type": "object", "required": true, "description": "Custom string key-value pairs attached to the agent." }, { "name": "model", "type": "string", "required": true, "description": "The requested model name used for inference." }, { "name": "reasoning", "type": "ReasoningResource", "required": true, "description": "The resolved reasoning configuration, including the model default for an omitted effort." }, { "name": "text", "type": "TextResource", "required": true, "description": "The resolved configuration for text generated by the agent." }, { "name": "service_tier", "type": "ServiceTierResource", "required": true, "description": "The resolved service-tier policy used for model requests.", "enum": [ "auto", "default", "flex", "priority", "fast" ] }, { "name": "instructions", "type": "string | null", "required": true, "description": "Custom instructions appended to the agent's default base instructions." }, { "name": "tools", "type": "array", "required": true, "description": "Tools available to the agent." }, { "name": "multi_agent", "type": "MultiAgentConfigResource", "required": true, "description": "The resolved configuration for creating and coordinating subagents." } ], "status": [ "DOCUMENTED", "BETA", "LIVE_VERIFIED" ], "example": { "id": "agent_f0363c606b6e418287a352178f20c141750d483e3399419c99", "object": "agent", "created_at": 1789782093, "updated_at": 1789782093, "name": "atlas-probe", "metadata": { "atlas": "probe" }, "model": "gpt-5.6-luna", "reasoning": { "effort": "medium", "summary": null }, "text": { "format": { "type": "text" }, "verbosity": "medium" }, "service_tier": "auto", "instructions": "Reply with OK.", "tools": [], "multi_agent": { "enabled": false, "max_concurrent_subagents": null } }, "example_source": "live 2026-09-18", "sources": [ { "url": "https://developers.openai.com/api/reference/resources/beta/subresources/agents", "retrieved_at": "2026-09-18T00:00:00Z" }, { "url": "https://github.com/openai/openai-openapi (openapi-master.yaml)", "retrieved_at": "2026-09-18T00:00:00Z" } ], "_fragment": "generated/fragments/objects/openai-agents-objects.json" }, { "provider": "openai", "api_family": "agents-platform/agents", "name": "DeletedAgentResource", "object": "agent.deleted", "schema_name": "DeletedAgentResource", "description": "A deleted reusable agent.", "fields": [ { "name": "id", "type": "string", "required": true, "description": "The ID of the deleted agent." }, { "name": "object", "type": "string", "required": true, "description": "The object type. Always `agent.deleted`." }, { "name": "deleted", "type": "boolean", "required": true, "description": "Whether the agent was deleted. Always `true`." } ], "status": [ "DOCUMENTED", "BETA", "LIVE_VERIFIED" ], "example": { "id": "agent_f0363c606b6e418287a352178f20c141750d483e3399419c99", "object": "agent.deleted", "deleted": true }, "example_source": "live 2026-09-18", "sources": [ { "url": "https://developers.openai.com/api/reference/resources/beta/subresources/agents", "retrieved_at": "2026-09-18T00:00:00Z" }, { "url": "https://github.com/openai/openai-openapi (openapi-master.yaml)", "retrieved_at": "2026-09-18T00:00:00Z" } ], "_fragment": "generated/fragments/objects/openai-agents-objects.json" }, { "provider": "openai", "api_family": "agents-platform/agents", "name": "Session", "object": "agent.session", "schema_name": "SessionResource", "description": "A Managed Agents session.", "fields": [ { "name": "metadata", "type": "object", "required": true, "description": "Custom string key-value pairs attached to the session." }, { "name": "id", "type": "string", "required": true, "description": "The ID of the session." }, { "name": "object", "type": "string", "required": true, "description": "The object type. Always `agent.session`." }, { "name": "created_at", "type": "integer", "required": true, "description": "The Unix timestamp, in seconds, when the session was created." }, { "name": "last_active_at", "type": "integer", "required": true, "description": "The Unix timestamp, in seconds, when the session was last active." }, { "name": "status", "type": "SessionStatusResource", "required": true, "description": "The current status of the session.", "enum": [ "idle", "in_progress", "requires_action", "failed" ] }, { "name": "required_actions", "type": "array", "required": true, "description": "Actions that must be completed before the session can continue." }, { "name": "error", "type": "string | null", "required": true, "description": "The error that caused the session to fail, if any." }, { "name": "agent", "type": "SessionAgentResource", "required": true, "description": "The agent running in the session." }, { "name": "environment", "type": "EnvironmentResource", "required": true, "description": "The execution environment for the session." }, { "name": "vault_ids", "type": "array", "required": true, "description": "The IDs of vaults made available to the session." }, { "name": "usage", "type": "TokenUsageResource | null", "required": true, "description": "Best-effort token usage for the session, or null if unknown. Recorded usage may change." } ], "status": [ "DOCUMENTED", "BETA", "LIVE_VERIFIED" ], "example": { "metadata": { "atlas": "probe" }, "id": "sess_0b52151131840c7d006aade89b61c88195a75804fb31b33990", "object": "agent.session", "created_at": 1789782171, "last_active_at": 1789782171, "status": "idle", "required_actions": [], "error": null, "agent": { "id": "agent_f0363c606b6e418287a352178f20c141750d483e3399419c99", "name": "atlas-probe", "model": "gpt-5.6-luna", "reasoning": { "effort": "medium", "summary": null }, "text": { "format": { "type": "text" }, "verbosity": "medium" }, "service_tier": "auto", "instructions": "Reply with OK.", "tools": [], "multi_agent": { "enabled": false, "max_concurrent_subagents": null } }, "environment": { "type": "none" }, "vault_ids": [], "usage": null }, "example_source": "live 2026-09-18", "sources": [ { "url": "https://developers.openai.com/api/reference/resources/beta/subresources/agents", "retrieved_at": "2026-09-18T00:00:00Z" }, { "url": "https://github.com/openai/openai-openapi (openapi-master.yaml)", "retrieved_at": "2026-09-18T00:00:00Z" } ], "_fragment": "generated/fragments/objects/openai-agents-objects.json" }, { "provider": "openai", "api_family": "agents-platform/agents", "name": "DeletedSessionResource", "object": "agent.session.deleted", "schema_name": "DeletedSessionResource", "description": "A Managed Agents session removed from the public API. Physical cleanup may continue asynchronously.", "fields": [ { "name": "id", "type": "string", "required": true, "description": "The ID of the deleted session." }, { "name": "object", "type": "string", "required": true, "description": "The object type. Always `agent.session.deleted`." }, { "name": "deleted", "type": "boolean", "required": true, "description": "Whether the session has been removed from the public API. Always `true`. Physical cleanup may still be in progress." } ], "status": [ "DOCUMENTED", "BETA", "LIVE_VERIFIED" ], "example": { "id": "sess_0b52151131840c7d006aade89b61c88195a75804fb31b33990", "object": "agent.session.deleted", "deleted": true }, "example_source": "live 2026-09-18", "sources": [ { "url": "https://developers.openai.com/api/reference/resources/beta/subresources/agents", "retrieved_at": "2026-09-18T00:00:00Z" }, { "url": "https://github.com/openai/openai-openapi (openapi-master.yaml)", "retrieved_at": "2026-09-18T00:00:00Z" } ], "_fragment": "generated/fragments/objects/openai-agents-objects.json" }, { "provider": "openai", "api_family": "agents-platform/agents", "name": "Turn", "object": "agent.session.turn", "schema_name": "TurnResource", "description": "The canonical public representation of a session turn.", "fields": [ { "name": "id", "type": "string", "required": true, "description": "The ID of the turn." }, { "name": "object", "type": "TurnObjectResource", "required": true, "description": "The object type. Always `agent.session.turn`." }, { "name": "session_id", "type": "string", "required": true, "description": "The ID of the session that owns the turn." }, { "name": "agent_id", "type": "string", "required": true, "description": "The ID of the agent that ran the turn." }, { "name": "subagent_id", "type": "string | null", "required": true, "description": "The ID of the subagent that ran the turn, if applicable." }, { "name": "status", "type": "TurnStatusResource", "required": true, "description": "The current status of the turn.", "enum": [ "queued", "in_progress", "waiting", "completed", "failed", "cancelled" ] }, { "name": "created_at", "type": "integer", "required": true, "description": "The Unix timestamp, in seconds, used to order the turn by creation time. Subagent turns use their start time, falling back to completion time or the subagent opening time when the preceding timestamps are unavailable." }, { "name": "started_at", "type": "integer | null", "required": true, "description": "The Unix timestamp, in seconds, when the turn started." }, { "name": "completed_at", "type": "integer | null", "required": true, "description": "The Unix timestamp, in seconds, when the turn reached a terminal state." }, { "name": "error", "type": "SessionTurnErrorResource | null", "required": true, "description": "A customer-safe error. Non-null only for a failed turn." }, { "name": "usage", "type": "TokenUsageResource | null", "required": true, "description": "Best-effort token usage for the turn, or null if unknown. Recorded usage may change." } ], "status": [ "DOCUMENTED", "BETA", "LIVE_VERIFIED" ], "example": { "id": "turn_0b52151131840c7d006aade8a3114c8195b6286aaca0730297", "object": "agent.session.turn", "session_id": "sess_0b52151131840c7d006aade89b61c88195a75804fb31b33990", "agent_id": "agent_f0363c606b6e418287a352178f20c141750d483e3399419c99", "subagent_id": null, "status": "completed", "created_at": 1789782177, "started_at": 1789782177, "completed_at": 1789782179, "error": null, "usage": { "input_tokens": 6087, "input_tokens_details": { "cached_tokens": 0 }, "output_tokens": 6, "output_tokens_details": { "reasoning_tokens": 0 }, "total_tokens": 6093 } }, "example_source": "live 2026-09-18", "sources": [ { "url": "https://developers.openai.com/api/reference/resources/beta/subresources/agents", "retrieved_at": "2026-09-18T00:00:00Z" }, { "url": "https://github.com/openai/openai-openapi (openapi-master.yaml)", "retrieved_at": "2026-09-18T00:00:00Z" } ], "_fragment": "generated/fragments/objects/openai-agents-objects.json" }, { "provider": "openai", "api_family": "agents-platform/agents", "name": "Subagent", "object": "agent.session.subagent", "schema_name": "SubagentResource", "description": "A subagent created within a session.", "fields": [ { "name": "id", "type": "string", "required": true, "description": "The ID of the subagent." }, { "name": "object", "type": "SubagentObjectResource", "required": true, "description": "The object type. Always `agent.session.subagent`." }, { "name": "session_id", "type": "string", "required": true, "description": "The ID of the session that owns the subagent." }, { "name": "name", "type": "string | null", "required": true, "description": "The runner-assigned nickname, or null when unavailable." }, { "name": "instructions", "type": "array | null", "required": true, "description": "Initial task content, or null when unavailable. Text may contain placeholders for images or audio when only a preview is available." }, { "name": "parent_agent_id", "type": "string", "required": true, "description": "The ID of the agent that created this subagent." }, { "name": "status", "type": "SubagentStatusResource", "required": true, "description": "The current status of the subagent.", "enum": [ "active", "closed" ] }, { "name": "opened_at", "type": "integer", "required": true, "description": "The Unix timestamp, in seconds, when the subagent was first opened. Resuming does not change it." }, { "name": "closed_at", "type": "integer | null", "required": true, "description": "The Unix timestamp, in seconds, when the subagent was closed. Null while active, including after resume." } ], "status": [ "DOCUMENTED", "BETA" ], "example": null, "example_source": null, "sources": [ { "url": "https://developers.openai.com/api/reference/resources/beta/subresources/agents", "retrieved_at": "2026-09-18T00:00:00Z" }, { "url": "https://github.com/openai/openai-openapi (openapi-master.yaml)", "retrieved_at": "2026-09-18T00:00:00Z" } ], "_fragment": "generated/fragments/objects/openai-agents-objects.json" }, { "provider": "openai", "api_family": "agents-platform/agents", "name": "Artifact", "object": "agent.session.artifact", "schema_name": "SessionArtifactResource", "description": "An immutable file published by a completed hosted session turn.", "fields": [ { "name": "id", "type": "string", "required": true, "description": "The immutable artifact ID." }, { "name": "object", "type": "string", "required": true, "description": "The object type. Always `agent.session.artifact`." }, { "name": "session_id", "type": "string", "required": true, "description": "The ID of the session that owns the artifact." }, { "name": "environment_id", "type": "string", "required": true, "description": "The ID of the environment that produced the artifact." }, { "name": "turn_id", "type": "string", "required": true, "description": "The ID of the completed turn that published the artifact." }, { "name": "path", "type": "string", "required": true, "description": "The original absolute file path in the execution environment." }, { "name": "size_bytes", "type": "integer", "required": true, "description": "The immutable artifact size in bytes." }, { "name": "created_at", "type": "integer", "required": true, "description": "The Unix timestamp, in seconds, when the artifact was published." } ], "status": [ "DOCUMENTED", "BETA" ], "example": null, "example_source": null, "sources": [ { "url": "https://developers.openai.com/api/reference/resources/beta/subresources/agents", "retrieved_at": "2026-09-18T00:00:00Z" }, { "url": "https://github.com/openai/openai-openapi (openapi-master.yaml)", "retrieved_at": "2026-09-18T00:00:00Z" } ], "_fragment": "generated/fragments/objects/openai-agents-objects.json" }, { "provider": "openai", "api_family": "agents-platform/agents", "name": "DeletedSessionArtifactResource", "object": "agent.session.artifact.deleted", "schema_name": "DeletedSessionArtifactResource", "description": "Confirmation that an immutable session artifact was deleted.", "fields": [ { "name": "id", "type": "string", "required": true, "description": "The ID of the deleted session artifact." }, { "name": "object", "type": "string", "required": true, "description": "The object type. Always `agent.session.artifact.deleted`." }, { "name": "deleted", "type": "boolean", "required": true, "description": "Whether the session artifact was deleted. Always `true`." } ], "status": [ "DOCUMENTED", "BETA" ], "example": null, "example_source": null, "sources": [ { "url": "https://developers.openai.com/api/reference/resources/beta/subresources/agents", "retrieved_at": "2026-09-18T00:00:00Z" }, { "url": "https://github.com/openai/openai-openapi (openapi-master.yaml)", "retrieved_at": "2026-09-18T00:00:00Z" } ], "_fragment": "generated/fragments/objects/openai-agents-objects.json" }, { "provider": "openai", "api_family": "agents-platform/agents", "name": "Environment (live execution environment)", "object": "agent.environment", "schema_name": "PublicEnvironmentResource", "description": "Safe metadata for a first-class execution environment.", "fields": [ { "name": "id", "type": "string", "required": true, "description": "The ID of the environment." }, { "name": "object", "type": "string", "required": true, "description": "The object type. Always `agent.environment`." }, { "name": "type", "type": "EnvironmentTypeResource", "required": true, "description": "Whether the environment is hosted by OpenAI or by the application.", "enum": [ "openai_hosted", "self_hosted" ], "const": "openai_hosted" }, { "name": "status", "type": "EnvironmentStatusResource", "required": true, "description": "The current environment connection status.", "enum": [ "pending", "connected", "disconnected", "expired", "failed" ] }, { "name": "files", "type": "array", "required": true, "description": "Files installed in the environment, without their contents." }, { "name": "skills", "type": "array", "required": true, "description": "Skills installed in the environment, without their archive contents." }, { "name": "plugins", "type": "array", "required": true, "description": "Plugins installed in the environment, without their archive contents." } ], "status": [ "DOCUMENTED", "BETA" ], "example": null, "example_source": null, "sources": [ { "url": "https://developers.openai.com/api/reference/resources/beta/subresources/agents", "retrieved_at": "2026-09-18T00:00:00Z" }, { "url": "https://github.com/openai/openai-openapi (openapi-master.yaml)", "retrieved_at": "2026-09-18T00:00:00Z" } ], "_fragment": "generated/fragments/objects/openai-agents-objects.json" }, { "provider": "openai", "api_family": "agents-platform/agents", "name": "Environment file", "object": "agent.environment.file", "schema_name": "EnvironmentFileResource", "description": "A live file in an execution environment.", "fields": [ { "name": "object", "type": "string", "required": true, "description": "The object type. Always `agent.environment.file`." }, { "name": "environment_id", "type": "string", "required": true, "description": "The ID of the environment containing this file." }, { "name": "path", "type": "string", "required": true, "description": "The absolute file path inside the environment's workspace." }, { "name": "size_bytes", "type": "integer", "required": true, "description": "The file size in bytes." } ], "status": [ "DOCUMENTED", "BETA" ], "example": null, "example_source": null, "sources": [ { "url": "https://developers.openai.com/api/reference/resources/beta/subresources/agents", "retrieved_at": "2026-09-18T00:00:00Z" }, { "url": "https://github.com/openai/openai-openapi (openapi-master.yaml)", "retrieved_at": "2026-09-18T00:00:00Z" } ], "_fragment": "generated/fragments/objects/openai-agents-objects.json" }, { "provider": "openai", "api_family": "agents-platform/agents", "name": "Environment template", "object": "agent.environment.template", "schema_name": "EnvironmentTemplateResource", "description": "Reusable configuration that provisions a fresh OpenAI-hosted environment for each session.", "fields": [ { "name": "id", "type": "string", "required": true, "description": "The ID of the reusable environment template." }, { "name": "name", "type": "string | null", "required": true, "description": "An optional human-readable display name for the template." }, { "name": "object", "type": "string", "required": true, "description": "The object type. Always `agent.environment.template`." }, { "name": "created_at", "type": "integer", "required": true, "description": "The Unix timestamp, in seconds, when the template was created." }, { "name": "updated_at", "type": "integer", "required": true, "description": "The Unix timestamp, in seconds, when the template was last updated." }, { "name": "packages", "type": "EnvironmentPackagesResource", "required": true, "description": "Packages installed in each fresh OpenAI-hosted environment." }, { "name": "network", "type": "NetworkPolicyResource", "required": true, "description": "Runtime network access for each OpenAI-hosted environment." }, { "name": "capability_directories", "type": "array", "required": true, "description": "Directories that expose capabilities to the agent." }, { "name": "skills", "type": "array", "required": true, "description": "Safe skill metadata, preserving unresolved version selectors." }, { "name": "plugins", "type": "array", "required": true, "description": "Safe plugin metadata, excluding inline archive contents." }, { "name": "files", "type": "array", "required": true, "description": "Safe file metadata, excluding contents and session-scoped file IDs." } ], "status": [ "DOCUMENTED", "BETA" ], "example": null, "example_source": null, "sources": [ { "url": "https://developers.openai.com/api/reference/resources/beta/subresources/agents", "retrieved_at": "2026-09-18T00:00:00Z" }, { "url": "https://github.com/openai/openai-openapi (openapi-master.yaml)", "retrieved_at": "2026-09-18T00:00:00Z" } ], "_fragment": "generated/fragments/objects/openai-agents-objects.json" }, { "provider": "openai", "api_family": "agents-platform/agents", "name": "DeletedEnvironmentTemplateResource", "object": "agent.environment.template.deleted", "schema_name": "DeletedEnvironmentTemplateResource", "description": "A deleted reusable environment template.", "fields": [ { "name": "id", "type": "string", "required": true, "description": "The ID of the deleted environment template." }, { "name": "object", "type": "string", "required": true, "description": "The object type. Always `agent.environment.template.deleted`." }, { "name": "deleted", "type": "boolean", "required": true, "description": "Whether the environment template was deleted. Always `true`." } ], "status": [ "DOCUMENTED", "BETA" ], "example": null, "example_source": null, "sources": [ { "url": "https://developers.openai.com/api/reference/resources/beta/subresources/agents", "retrieved_at": "2026-09-18T00:00:00Z" }, { "url": "https://github.com/openai/openai-openapi (openapi-master.yaml)", "retrieved_at": "2026-09-18T00:00:00Z" } ], "_fragment": "generated/fragments/objects/openai-agents-objects.json" }, { "provider": "openai", "api_family": "agents-platform/vaults", "name": "Vault", "object": "vault", "schema_name": "VaultResource", "description": "A collection of credentials for MCP servers and OpenAI-hosted environments.", "fields": [ { "name": "id", "type": "string", "required": true, "description": "The ID of the vault." }, { "name": "object", "type": "string", "required": true, "description": "The object type. Always `vault`." }, { "name": "name", "type": "string | null", "required": true, "description": "The human-readable name of the vault, if set." }, { "name": "metadata", "type": "object", "required": true, "description": "Key-value pairs associated with the vault, such as an application or team identifier." }, { "name": "created_at", "type": "integer", "required": true, "description": "The Unix timestamp, in seconds, when the vault was created." } ], "status": [ "DOCUMENTED", "BETA" ], "example": null, "example_source": null, "sources": [ { "url": "https://developers.openai.com/api/reference/resources/beta/subresources/agents", "retrieved_at": "2026-09-18T00:00:00Z" }, { "url": "https://github.com/openai/openai-openapi (openapi-master.yaml)", "retrieved_at": "2026-09-18T00:00:00Z" } ], "_fragment": "generated/fragments/objects/openai-agents-objects.json" }, { "provider": "openai", "api_family": "agents-platform/vaults", "name": "DeletedVaultResource", "object": "vault.deleted", "schema_name": "DeletedVaultResource", "description": "Confirmation that a vault was deleted.", "fields": [ { "name": "id", "type": "string", "required": true, "description": "The ID of the deleted vault." }, { "name": "object", "type": "string", "required": true, "description": "The object type. Always `vault.deleted`." }, { "name": "deleted", "type": "boolean", "required": true, "description": "Whether the resource was deleted. Always `true`." } ], "status": [ "DOCUMENTED", "BETA" ], "example": null, "example_source": null, "sources": [ { "url": "https://developers.openai.com/api/reference/resources/beta/subresources/agents", "retrieved_at": "2026-09-18T00:00:00Z" }, { "url": "https://github.com/openai/openai-openapi (openapi-master.yaml)", "retrieved_at": "2026-09-18T00:00:00Z" } ], "_fragment": "generated/fragments/objects/openai-agents-objects.json" }, { "provider": "openai", "api_family": "agents-platform/vaults", "name": "Credential (secrets write-only)", "object": "vault.credential", "schema_name": "VaultCredentialResource", "description": "Metadata for a stored credential. Secret values are never returned.", "fields": [ { "name": "id", "type": "string", "required": true, "description": "The ID of the credential." }, { "name": "object", "type": "string", "required": true, "description": "The object type. Always `vault.credential`." }, { "name": "vault_id", "type": "string", "required": true, "description": "The ID of the vault containing this credential." }, { "name": "name", "type": "string", "required": true, "description": "The human-readable name of the credential." }, { "name": "auth", "type": "VaultCredentialAuthResource", "required": true, "description": "The authentication method and non-secret configuration of the credential." }, { "name": "created_at", "type": "integer", "required": true, "description": "The Unix timestamp, in seconds, when the credential was created." }, { "name": "updated_at", "type": "integer", "required": true, "description": "The Unix timestamp, in seconds, when the credential was last updated." } ], "status": [ "DOCUMENTED", "BETA" ], "example": null, "example_source": null, "sources": [ { "url": "https://developers.openai.com/api/reference/resources/beta/subresources/agents", "retrieved_at": "2026-09-18T00:00:00Z" }, { "url": "https://github.com/openai/openai-openapi (openapi-master.yaml)", "retrieved_at": "2026-09-18T00:00:00Z" } ], "_fragment": "generated/fragments/objects/openai-agents-objects.json" }, { "provider": "openai", "api_family": "agents-platform/vaults", "name": "DeletedVaultCredentialResource", "object": "vault.credential.deleted", "schema_name": "DeletedVaultCredentialResource", "description": "Confirmation that a vault credential was deleted.", "fields": [ { "name": "id", "type": "string", "required": true, "description": "The ID of the deleted credential." }, { "name": "object", "type": "string", "required": true, "description": "The object type. Always `vault.credential.deleted`." }, { "name": "deleted", "type": "boolean", "required": true, "description": "Whether the resource was deleted. Always `true`." } ], "status": [ "DOCUMENTED", "BETA" ], "example": null, "example_source": null, "sources": [ { "url": "https://developers.openai.com/api/reference/resources/beta/subresources/agents", "retrieved_at": "2026-09-18T00:00:00Z" }, { "url": "https://github.com/openai/openai-openapi (openapi-master.yaml)", "retrieved_at": "2026-09-18T00:00:00Z" } ], "_fragment": "generated/fragments/objects/openai-agents-objects.json" }, { "provider": "openai", "api_family": "agents-platform/chatkit", "name": "ChatKit session", "object": "chatkit.session", "schema_name": "ChatSessionResource", "description": "Represents a ChatKit session and its resolved configuration.", "fields": [ { "name": "id", "type": "string", "required": true, "description": "Identifier for the ChatKit session." }, { "name": "object", "type": "string", "required": true, "description": "Type discriminator that is always `chatkit.session`." }, { "name": "expires_at", "type": "integer", "required": true, "description": "Unix timestamp (in seconds) for when the session expires." }, { "name": "client_secret", "type": "string", "required": true, "description": "Ephemeral client secret that authenticates session requests." }, { "name": "workflow", "type": "ChatkitWorkflow", "required": true, "description": "Workflow metadata for the session." }, { "name": "user", "type": "string", "required": true, "description": "User identifier associated with the session." }, { "name": "rate_limits", "type": "ChatSessionRateLimits", "required": true, "description": "Resolved rate limit values." }, { "name": "max_requests_per_1_minute", "type": "integer", "required": true, "description": "Convenience copy of the per-minute request limit." }, { "name": "status", "type": "ChatSessionStatus", "required": true, "description": "Current lifecycle state of the session.", "enum": [ "active", "expired", "cancelled" ] }, { "name": "chatkit_configuration", "type": "ChatSessionChatkitConfiguration", "required": true, "description": "Resolved ChatKit feature configuration for the session." } ], "status": [ "DOCUMENTED", "BETA" ], "example": null, "example_source": null, "sources": [ { "url": "https://developers.openai.com/api/reference/resources/beta/subresources/chatkit", "retrieved_at": "2026-09-18T00:00:00Z" }, { "url": "https://github.com/openai/openai-openapi (openapi-master.yaml)", "retrieved_at": "2026-09-18T00:00:00Z" } ], "_fragment": "generated/fragments/objects/openai-agents-objects.json" }, { "provider": "openai", "api_family": "agents-platform/chatkit", "name": "ChatKit thread", "object": "chatkit.thread", "schema_name": "ThreadResource", "description": "Represents a ChatKit thread and its current status.", "fields": [ { "name": "id", "type": "string", "required": true, "description": "Identifier of the thread." }, { "name": "object", "type": "string", "required": true, "description": "Type discriminator that is always `chatkit.thread`." }, { "name": "created_at", "type": "integer", "required": true, "description": "Unix timestamp (in seconds) for when the thread was created." }, { "name": "title", "type": "string | null", "required": true, "description": "" }, { "name": "status", "type": "ActiveStatus | LockedStatus | ClosedStatus", "required": true, "description": "Current status for the thread. Defaults to `active` for newly created threads." }, { "name": "user", "type": "string", "required": true, "description": "Free-form string that identifies your end user who owns the thread." } ], "status": [ "DOCUMENTED", "BETA" ], "example": null, "example_source": null, "sources": [ { "url": "https://developers.openai.com/api/reference/resources/beta/subresources/chatkit", "retrieved_at": "2026-09-18T00:00:00Z" }, { "url": "https://github.com/openai/openai-openapi (openapi-master.yaml)", "retrieved_at": "2026-09-18T00:00:00Z" } ], "_fragment": "generated/fragments/objects/openai-agents-objects.json" }, { "provider": "openai", "api_family": "agents-platform/chatkit", "name": "DeletedThreadResource", "object": "chatkit.thread.deleted", "schema_name": "DeletedThreadResource", "description": "Confirmation payload returned after deleting a thread.", "fields": [ { "name": "id", "type": "string", "required": true, "description": "Identifier of the deleted thread." }, { "name": "object", "type": "string", "required": true, "description": "Type discriminator that is always `chatkit.thread.deleted`." }, { "name": "deleted", "type": "boolean", "required": true, "description": "Indicates that the thread has been deleted." } ], "status": [ "DOCUMENTED", "BETA" ], "example": null, "example_source": null, "sources": [ { "url": "https://developers.openai.com/api/reference/resources/beta/subresources/chatkit", "retrieved_at": "2026-09-18T00:00:00Z" }, { "url": "https://github.com/openai/openai-openapi (openapi-master.yaml)", "retrieved_at": "2026-09-18T00:00:00Z" } ], "_fragment": "generated/fragments/objects/openai-agents-objects.json" }, { "provider": "openai", "api_family": "agents-platform/agents", "name": "Session item: message", "object": "agent.session.item[type=message]", "schema_name": "MessageItemResource", "description": "A user or assistant message recorded in a session.", "fields": [ { "name": "type", "type": "string", "required": true, "description": "The item type. Always `message`.", "enum": [ "message" ], "const": "message" }, { "name": "id", "type": "string | null", "required": true, "description": "The ID of this item, or null for legacy user messages whose ID was not recorded." }, { "name": "turn_id", "type": "string", "required": true, "description": "The ID of the turn that contains this item." }, { "name": "role", "type": "SessionMessageRoleResource", "required": true, "description": "The role of the message author.", "enum": [ "user", "assistant" ] }, { "name": "content", "type": "array", "required": true, "description": "The content of the message. User messages contain input text or images; assistant messages contain output text." }, { "name": "status", "type": "OutputItemStatusResource", "required": true, "description": "The status of the message. User messages are always `completed`.", "enum": [ "in_progress", "completed", "incomplete" ] }, { "name": "phase", "type": "MessagePhaseResource | null", "required": true, "description": "The phase of an assistant message. Null for user messages." } ], "status": [ "DOCUMENTED", "BETA", "LIVE_VERIFIED" ], "example": [ { "type": "message", "id": "msg_a168d37c50fe59f871f0243a74cefcab58523253681a5ad41b", "turn_id": "turn_0b52151131840c7d006aade8a3114c8195b6286aaca0730297", "role": "user", "content": [ { "type": "input_text", "text": "Reply with OK." } ], "status": "completed", "phase": null }, { "type": "message", "id": "msg_04be7b73944e7645016aade8a1919087d1aa6bf202ab47a6f4", "turn_id": "turn_0b52151131840c7d006aade8a3114c8195b6286aaca0730297", "role": "assistant", "content": [ { "type": "output_text", "text": "OK." } ], "status": "completed", "phase": "final_answer" } ], "example_source": "live 2026-09-18 (user + assistant message, phase final_answer)", "union": "SessionTurnItemResource (GET /items, /subagents/{id}/items, event item.added); AgentOutputItemResource subset for item.done", "sources": [ { "url": "https://developers.openai.com/api/reference/resources/beta/subresources/agents", "retrieved_at": "2026-09-18T00:00:00Z" }, { "url": "https://github.com/openai/openai-openapi (openapi-master.yaml)", "retrieved_at": "2026-09-18T00:00:00Z" } ], "_fragment": "generated/fragments/objects/openai-agents-objects.json" }, { "provider": "openai", "api_family": "agents-platform/agents", "name": "Session item: reasoning", "object": "agent.session.item[type=reasoning]", "schema_name": "ReasoningItemResource", "description": "A reasoning item produced by the agent.", "fields": [ { "name": "type", "type": "string", "required": true, "description": "The item type. Always `reasoning`.", "enum": [ "reasoning" ], "const": "reasoning" }, { "name": "id", "type": "string", "required": true, "description": "The ID of the reasoning item." }, { "name": "turn_id", "type": "string", "required": true, "description": "The ID of the turn that contains this item." }, { "name": "summary", "type": "array", "required": true, "description": "The reasoning summaries produced by the agent." }, { "name": "status", "type": "OutputItemStatusResource | null", "required": true, "description": "The status of the reasoning item." } ], "status": [ "DOCUMENTED", "BETA" ], "example": null, "example_source": null, "union": "SessionTurnItemResource (GET /items, /subagents/{id}/items, event item.added); AgentOutputItemResource subset for item.done", "sources": [ { "url": "https://developers.openai.com/api/reference/resources/beta/subresources/agents", "retrieved_at": "2026-09-18T00:00:00Z" }, { "url": "https://github.com/openai/openai-openapi (openapi-master.yaml)", "retrieved_at": "2026-09-18T00:00:00Z" } ], "_fragment": "generated/fragments/objects/openai-agents-objects.json" }, { "provider": "openai", "api_family": "agents-platform/agents", "name": "Session item: function_call", "object": "agent.session.item[type=function_call]", "schema_name": "FunctionCallItemResource", "description": "A function call produced by the agent.", "fields": [ { "name": "type", "type": "string", "required": true, "description": "The item type. Always `function_call`.", "enum": [ "function_call" ], "const": "function_call" }, { "name": "id", "type": "string", "required": true, "description": "The ID of the function call item." }, { "name": "turn_id", "type": "string", "required": true, "description": "The ID of the turn that contains this item." }, { "name": "call_id", "type": "string", "required": true, "description": "The ID used to submit the function result." }, { "name": "name", "type": "string", "required": true, "description": "The name of the function to call." }, { "name": "arguments", "type": "any", "required": true, "description": "The arguments to pass to the function." }, { "name": "status", "type": "FunctionCallStatusResource", "required": true, "description": "The status of the function call.", "enum": [ "in_progress", "completed", "failed", "incomplete" ] } ], "status": [ "DOCUMENTED", "BETA" ], "example": null, "example_source": null, "union": "SessionTurnItemResource (GET /items, /subagents/{id}/items, event item.added); AgentOutputItemResource subset for item.done", "sources": [ { "url": "https://developers.openai.com/api/reference/resources/beta/subresources/agents", "retrieved_at": "2026-09-18T00:00:00Z" }, { "url": "https://github.com/openai/openai-openapi (openapi-master.yaml)", "retrieved_at": "2026-09-18T00:00:00Z" } ], "_fragment": "generated/fragments/objects/openai-agents-objects.json" }, { "provider": "openai", "api_family": "agents-platform/agents", "name": "Session item: function_call_output", "object": "agent.session.item[type=function_call_output]", "schema_name": "FunctionCallOutputItemResource", "description": "The result supplied for a function call.", "fields": [ { "name": "id", "type": "string", "required": true, "description": "The ID of the function call output item." }, { "name": "turn_id", "type": "string", "required": true, "description": "The ID of the turn that contains this item." }, { "name": "type", "type": "string", "required": true, "description": "The item type. Always `function_call_output`.", "enum": [ "function_call_output" ], "const": "function_call_output" }, { "name": "call_id", "type": "string", "required": true, "description": "The ID of the function call that produced this output." }, { "name": "status", "type": "FunctionCallStatusResource", "required": true, "description": "The status of the function call.", "enum": [ "in_progress", "completed", "failed", "incomplete" ] }, { "name": "output", "type": "FunctionCallOutputResource | null", "required": true, "description": "The function result, if the call succeeded." }, { "name": "error", "type": "string | null", "required": true, "description": "The error message, if the call failed." } ], "status": [ "DOCUMENTED", "BETA" ], "example": null, "example_source": null, "union": "SessionTurnItemResource (GET /items, /subagents/{id}/items, event item.added); AgentOutputItemResource subset for item.done", "sources": [ { "url": "https://developers.openai.com/api/reference/resources/beta/subresources/agents", "retrieved_at": "2026-09-18T00:00:00Z" }, { "url": "https://github.com/openai/openai-openapi (openapi-master.yaml)", "retrieved_at": "2026-09-18T00:00:00Z" } ], "_fragment": "generated/fragments/objects/openai-agents-objects.json" }, { "provider": "openai", "api_family": "agents-platform/agents", "name": "Session item: agent_message", "object": "agent.session.item[type=agent_message]", "schema_name": "AgentMessageItemResource", "description": "A message exchanged between agent threads.", "fields": [ { "name": "id", "type": "string", "required": true, "description": "The ID of the message." }, { "name": "turn_id", "type": "string", "required": true, "description": "The ID of the turn that contains this item." }, { "name": "type", "type": "string", "required": true, "description": "The item type. Always `agent_message`.", "enum": [ "agent_message" ], "const": "agent_message" }, { "name": "sender_agent_id", "type": "string", "required": true, "description": "The ID or name of the sending agent." }, { "name": "recipient_agent_id", "type": "string", "required": true, "description": "The ID or name of the receiving agent." }, { "name": "content", "type": "array", "required": true, "description": "The content exchanged between the agents." } ], "status": [ "DOCUMENTED", "BETA" ], "example": null, "example_source": null, "union": "SessionTurnItemResource (GET /items, /subagents/{id}/items, event item.added); AgentOutputItemResource subset for item.done", "sources": [ { "url": "https://developers.openai.com/api/reference/resources/beta/subresources/agents", "retrieved_at": "2026-09-18T00:00:00Z" }, { "url": "https://github.com/openai/openai-openapi (openapi-master.yaml)", "retrieved_at": "2026-09-18T00:00:00Z" } ], "_fragment": "generated/fragments/objects/openai-agents-objects.json" }, { "provider": "openai", "api_family": "agents-platform/agents", "name": "Session item: mcp_call", "object": "agent.session.item[type=mcp_call]", "schema_name": "McpCallItemResource", "description": "A call to a tool on an MCP server.", "fields": [ { "name": "type", "type": "string", "required": true, "description": "The item type. Always `mcp_call`.", "enum": [ "mcp_call" ], "const": "mcp_call" }, { "name": "id", "type": "string", "required": true, "description": "The ID of the MCP call item." }, { "name": "turn_id", "type": "string", "required": true, "description": "The ID of the turn that contains this item." }, { "name": "server_label", "type": "string", "required": true, "description": "The label of the MCP server." }, { "name": "name", "type": "string", "required": true, "description": "The name of the MCP tool." }, { "name": "arguments", "type": "any", "required": true, "description": "The arguments passed to the MCP tool." }, { "name": "status", "type": "FunctionCallStatusResource", "required": true, "description": "The status of the MCP tool call.", "enum": [ "in_progress", "completed", "failed", "incomplete" ] }, { "name": "output", "type": "any | null", "required": true, "description": "The output returned by the MCP tool, if any." }, { "name": "error", "type": "any | null", "required": true, "description": "The error returned by the MCP tool, if any." } ], "status": [ "DOCUMENTED", "BETA" ], "example": null, "example_source": null, "union": "SessionTurnItemResource (GET /items, /subagents/{id}/items, event item.added); AgentOutputItemResource subset for item.done", "sources": [ { "url": "https://developers.openai.com/api/reference/resources/beta/subresources/agents", "retrieved_at": "2026-09-18T00:00:00Z" }, { "url": "https://github.com/openai/openai-openapi (openapi-master.yaml)", "retrieved_at": "2026-09-18T00:00:00Z" } ], "_fragment": "generated/fragments/objects/openai-agents-objects.json" }, { "provider": "openai", "api_family": "agents-platform/agents", "name": "Session item: web_search_call", "object": "agent.session.item[type=web_search_call]", "schema_name": "WebSearchCallItemResource", "description": "A web search call produced by the agent.", "fields": [ { "name": "type", "type": "string", "required": true, "description": "The item type. Always `web_search_call`.", "enum": [ "web_search_call" ], "const": "web_search_call" }, { "name": "id", "type": "string", "required": true, "description": "The ID of the web search call." }, { "name": "turn_id", "type": "string", "required": true, "description": "The ID of the turn that contains this item." }, { "name": "status", "type": "OutputItemStatusResource", "required": true, "description": "The status of the web search call.", "enum": [ "in_progress", "completed", "incomplete" ] }, { "name": "action", "type": "WebSearchActionResource | null", "required": true, "description": "The action performed by the web search tool." } ], "status": [ "DOCUMENTED", "BETA" ], "example": null, "example_source": null, "union": "SessionTurnItemResource (GET /items, /subagents/{id}/items, event item.added); AgentOutputItemResource subset for item.done", "sources": [ { "url": "https://developers.openai.com/api/reference/resources/beta/subresources/agents", "retrieved_at": "2026-09-18T00:00:00Z" }, { "url": "https://github.com/openai/openai-openapi (openapi-master.yaml)", "retrieved_at": "2026-09-18T00:00:00Z" } ], "_fragment": "generated/fragments/objects/openai-agents-objects.json" }, { "provider": "openai", "api_family": "agents-platform/agents", "name": "Session item: command_execution", "object": "agent.session.item[type=command_execution]", "schema_name": "CommandExecutionItemResource", "description": "A command execution produced by the agent.", "fields": [ { "name": "type", "type": "string", "required": true, "description": "The item type. Always `command_execution`.", "enum": [ "command_execution" ], "const": "command_execution" }, { "name": "id", "type": "string", "required": true, "description": "The ID of the command execution item." }, { "name": "turn_id", "type": "string", "required": true, "description": "The ID of the turn that contains this item." }, { "name": "command", "type": "string", "required": true, "description": "The command that was executed." }, { "name": "cwd", "type": "string | null", "required": true, "description": "The working directory used to execute the command." }, { "name": "status", "type": "FunctionCallStatusResource", "required": true, "description": "The status of the command execution.", "enum": [ "in_progress", "completed", "failed", "incomplete" ] }, { "name": "output", "type": "string | null", "required": true, "description": "The command output, if available." }, { "name": "exit_code", "type": "integer | null", "required": true, "description": "The process exit code, if the command completed." }, { "name": "duration_ms", "type": "integer | null", "required": true, "description": "The command duration in milliseconds." } ], "status": [ "DOCUMENTED", "BETA" ], "example": null, "example_source": null, "union": "SessionTurnItemResource (GET /items, /subagents/{id}/items, event item.added); AgentOutputItemResource subset for item.done", "sources": [ { "url": "https://developers.openai.com/api/reference/resources/beta/subresources/agents", "retrieved_at": "2026-09-18T00:00:00Z" }, { "url": "https://github.com/openai/openai-openapi (openapi-master.yaml)", "retrieved_at": "2026-09-18T00:00:00Z" } ], "_fragment": "generated/fragments/objects/openai-agents-objects.json" }, { "provider": "openai", "api_family": "agents-platform/agents", "name": "Session item: create_subagent_call", "object": "agent.session.item[type=create_subagent_call]", "schema_name": "CreateSubagentCallItemResource", "description": "A request to spawn a subagent.", "fields": [ { "name": "type", "type": "string", "required": true, "description": "The item type. Always `create_subagent_call`.", "enum": [ "create_subagent_call" ], "const": "create_subagent_call" }, { "name": "id", "type": "string", "required": true, "description": "The ID of the tool call item." }, { "name": "turn_id", "type": "string", "required": true, "description": "The ID of the turn that contains this item." }, { "name": "status", "type": "FunctionCallStatusResource", "required": true, "description": "The status of the tool call.", "enum": [ "in_progress", "completed", "failed", "incomplete" ] }, { "name": "agent_id", "type": "string", "required": true, "description": "The ID of the agent that requested the subagent." }, { "name": "content", "type": "array", "required": true, "description": "The task given to the spawned agent." }, { "name": "model", "type": "string | null", "required": true, "description": "The model requested for the spawned agent." }, { "name": "reasoning_effort", "type": "string | null", "required": true, "description": "The reasoning effort requested for the spawned agent." } ], "status": [ "DOCUMENTED", "BETA" ], "example": null, "example_source": null, "union": "SessionTurnItemResource (GET /items, /subagents/{id}/items, event item.added); AgentOutputItemResource subset for item.done", "sources": [ { "url": "https://developers.openai.com/api/reference/resources/beta/subresources/agents", "retrieved_at": "2026-09-18T00:00:00Z" }, { "url": "https://github.com/openai/openai-openapi (openapi-master.yaml)", "retrieved_at": "2026-09-18T00:00:00Z" } ], "_fragment": "generated/fragments/objects/openai-agents-objects.json" }, { "provider": "openai", "api_family": "agents-platform/agents", "name": "Session item: send_subagent_input_call", "object": "agent.session.item[type=send_subagent_input_call]", "schema_name": "SendSubagentInputCallItemResource", "description": "A request to send input to another agent.", "fields": [ { "name": "type", "type": "string", "required": true, "description": "The item type. Always `send_subagent_input_call`.", "enum": [ "send_subagent_input_call" ], "const": "send_subagent_input_call" }, { "name": "id", "type": "string", "required": true, "description": "The ID of the tool call item." }, { "name": "turn_id", "type": "string", "required": true, "description": "The ID of the turn that contains this item." }, { "name": "status", "type": "FunctionCallStatusResource", "required": true, "description": "The status of the tool call.", "enum": [ "in_progress", "completed", "failed", "incomplete" ] }, { "name": "sender_agent_id", "type": "string", "required": true, "description": "The ID of the agent sending the input." }, { "name": "recipient_agent_id", "type": "string", "required": true, "description": "The ID of the agent receiving the input." }, { "name": "content", "type": "array", "required": true, "description": "The input sent to the receiving agent." } ], "status": [ "DOCUMENTED", "BETA" ], "example": null, "example_source": null, "union": "SessionTurnItemResource (GET /items, /subagents/{id}/items, event item.added); AgentOutputItemResource subset for item.done", "sources": [ { "url": "https://developers.openai.com/api/reference/resources/beta/subresources/agents", "retrieved_at": "2026-09-18T00:00:00Z" }, { "url": "https://github.com/openai/openai-openapi (openapi-master.yaml)", "retrieved_at": "2026-09-18T00:00:00Z" } ], "_fragment": "generated/fragments/objects/openai-agents-objects.json" }, { "provider": "openai", "api_family": "agents-platform/agents", "name": "Session item: resume_subagent_call", "object": "agent.session.item[type=resume_subagent_call]", "schema_name": "ResumeSubagentCallItemResource", "description": "A request to resume a subagent.", "fields": [ { "name": "type", "type": "string", "required": true, "description": "The item type. Always `resume_subagent_call`.", "enum": [ "resume_subagent_call" ], "const": "resume_subagent_call" }, { "name": "id", "type": "string", "required": true, "description": "The ID of the tool call item." }, { "name": "turn_id", "type": "string", "required": true, "description": "The ID of the turn that contains this item." }, { "name": "status", "type": "FunctionCallStatusResource", "required": true, "description": "The status of the tool call.", "enum": [ "in_progress", "completed", "failed", "incomplete" ] }, { "name": "sender_agent_id", "type": "string", "required": true, "description": "The ID of the agent requesting the resume." }, { "name": "recipient_agent_id", "type": "string", "required": true, "description": "The ID of the agent to resume." } ], "status": [ "DOCUMENTED", "BETA" ], "example": null, "example_source": null, "union": "SessionTurnItemResource (GET /items, /subagents/{id}/items, event item.added); AgentOutputItemResource subset for item.done", "sources": [ { "url": "https://developers.openai.com/api/reference/resources/beta/subresources/agents", "retrieved_at": "2026-09-18T00:00:00Z" }, { "url": "https://github.com/openai/openai-openapi (openapi-master.yaml)", "retrieved_at": "2026-09-18T00:00:00Z" } ], "_fragment": "generated/fragments/objects/openai-agents-objects.json" }, { "provider": "openai", "api_family": "agents-platform/agents", "name": "Session item: wait_for_subagents_call", "object": "agent.session.item[type=wait_for_subagents_call]", "schema_name": "WaitForSubagentsCallItemResource", "description": "A request to wait for one or more subagents.", "fields": [ { "name": "type", "type": "string", "required": true, "description": "The item type. Always `wait_for_subagents_call`.", "enum": [ "wait_for_subagents_call" ], "const": "wait_for_subagents_call" }, { "name": "id", "type": "string", "required": true, "description": "The ID of the tool call item." }, { "name": "turn_id", "type": "string", "required": true, "description": "The ID of the turn that contains this item." }, { "name": "status", "type": "FunctionCallStatusResource", "required": true, "description": "The status of the tool call.", "enum": [ "in_progress", "completed", "failed", "incomplete" ] }, { "name": "sender_agent_id", "type": "string", "required": true, "description": "The ID of the agent waiting for results." }, { "name": "recipient_agent_ids", "type": "array", "required": true, "description": "The IDs of the agents to wait for." } ], "status": [ "DOCUMENTED", "BETA" ], "example": null, "example_source": null, "union": "SessionTurnItemResource (GET /items, /subagents/{id}/items, event item.added); AgentOutputItemResource subset for item.done", "sources": [ { "url": "https://developers.openai.com/api/reference/resources/beta/subresources/agents", "retrieved_at": "2026-09-18T00:00:00Z" }, { "url": "https://github.com/openai/openai-openapi (openapi-master.yaml)", "retrieved_at": "2026-09-18T00:00:00Z" } ], "_fragment": "generated/fragments/objects/openai-agents-objects.json" }, { "provider": "openai", "api_family": "agents-platform/agents", "name": "Session item: interrupt_subagent_call", "object": "agent.session.item[type=interrupt_subagent_call]", "schema_name": "InterruptSubagentCallItemResource", "description": "A request to interrupt a subagent's current turn. The subagent remains available.", "fields": [ { "name": "type", "type": "string", "required": true, "description": "The item type. Always `interrupt_subagent_call`.", "enum": [ "interrupt_subagent_call" ], "const": "interrupt_subagent_call" }, { "name": "id", "type": "string", "required": true, "description": "The ID of the tool call item." }, { "name": "turn_id", "type": "string", "required": true, "description": "The ID of the turn that contains this item." }, { "name": "status", "type": "FunctionCallStatusResource", "required": true, "description": "The status of the tool call.", "enum": [ "in_progress", "completed", "failed", "incomplete" ] }, { "name": "sender_agent_id", "type": "string", "required": true, "description": "The ID of the agent requesting the interrupt." }, { "name": "recipient_agent_id", "type": "string", "required": true, "description": "The ID of the agent to interrupt." } ], "status": [ "DOCUMENTED", "BETA" ], "example": null, "example_source": null, "union": "SessionTurnItemResource (GET /items, /subagents/{id}/items, event item.added); AgentOutputItemResource subset for item.done", "sources": [ { "url": "https://developers.openai.com/api/reference/resources/beta/subresources/agents", "retrieved_at": "2026-09-18T00:00:00Z" }, { "url": "https://github.com/openai/openai-openapi (openapi-master.yaml)", "retrieved_at": "2026-09-18T00:00:00Z" } ], "_fragment": "generated/fragments/objects/openai-agents-objects.json" }, { "provider": "openai", "api_family": "agents-platform/agents", "name": "Session item: close_subagent_call", "object": "agent.session.item[type=close_subagent_call]", "schema_name": "CloseSubagentCallItemResource", "description": "A request to close a subagent.", "fields": [ { "name": "type", "type": "string", "required": true, "description": "The item type. Always `close_subagent_call`.", "enum": [ "close_subagent_call" ], "const": "close_subagent_call" }, { "name": "id", "type": "string", "required": true, "description": "The ID of the tool call item." }, { "name": "turn_id", "type": "string", "required": true, "description": "The ID of the turn that contains this item." }, { "name": "status", "type": "FunctionCallStatusResource", "required": true, "description": "The status of the tool call.", "enum": [ "in_progress", "completed", "failed", "incomplete" ] }, { "name": "sender_agent_id", "type": "string", "required": true, "description": "The ID of the agent requesting the close." }, { "name": "recipient_agent_id", "type": "string", "required": true, "description": "The ID of the agent to close." } ], "status": [ "DOCUMENTED", "BETA" ], "example": null, "example_source": null, "union": "SessionTurnItemResource (GET /items, /subagents/{id}/items, event item.added); AgentOutputItemResource subset for item.done", "sources": [ { "url": "https://developers.openai.com/api/reference/resources/beta/subresources/agents", "retrieved_at": "2026-09-18T00:00:00Z" }, { "url": "https://github.com/openai/openai-openapi (openapi-master.yaml)", "retrieved_at": "2026-09-18T00:00:00Z" } ], "_fragment": "generated/fragments/objects/openai-agents-objects.json" }, { "provider": "openai", "api_family": "agents-platform/agents", "name": "Message content part: MessageContentResourceInputText", "object": "agent.session.item[type=message].content[]", "schema_name": "MessageContentResourceInputText", "description": "Text supplied by the user.", "fields": [ { "name": "type", "type": "string", "required": true, "description": "The type of the object. Always `input_text`.", "enum": [ "input_text" ], "const": "input_text" }, { "name": "text", "type": "string", "required": true, "description": "The text supplied by the user." } ], "status": [ "DOCUMENTED", "BETA", "LIVE_VERIFIED" ], "example": null, "sources": [ { "url": "https://github.com/openai/openai-openapi (openapi-master.yaml)", "retrieved_at": "2026-09-18T00:00:00Z" } ], "_fragment": "generated/fragments/objects/openai-agents-objects.json" }, { "provider": "openai", "api_family": "agents-platform/agents", "name": "Message content part: MessageContentResourceInputImage", "object": "agent.session.item[type=message].content[]", "schema_name": "MessageContentResourceInputImage", "description": "An image supplied by the user.", "fields": [ { "name": "type", "type": "string", "required": true, "description": "The type of the object. Always `input_image`.", "enum": [ "input_image" ], "const": "input_image" }, { "name": "image_url", "type": "string", "required": true, "description": "The URL of the image supplied by the user, which may be a base64-encoded data URL." } ], "status": [ "DOCUMENTED", "BETA", "LIVE_VERIFIED" ], "example": null, "sources": [ { "url": "https://github.com/openai/openai-openapi (openapi-master.yaml)", "retrieved_at": "2026-09-18T00:00:00Z" } ], "_fragment": "generated/fragments/objects/openai-agents-objects.json" }, { "provider": "openai", "api_family": "agents-platform/agents", "name": "Message content part: MessageContentResourceOutputText", "object": "agent.session.item[type=message].content[]", "schema_name": "MessageContentResourceOutputText", "description": "Text produced by the assistant.", "fields": [ { "name": "type", "type": "string", "required": true, "description": "The type of the object. Always `output_text`.", "enum": [ "output_text" ], "const": "output_text" }, { "name": "text", "type": "string", "required": true, "description": "The text produced by the assistant." } ], "status": [ "DOCUMENTED", "BETA", "LIVE_VERIFIED" ], "example": null, "sources": [ { "url": "https://github.com/openai/openai-openapi (openapi-master.yaml)", "retrieved_at": "2026-09-18T00:00:00Z" } ], "_fragment": "generated/fragments/objects/openai-agents-objects.json" }, { "provider": "openai", "api_family": "agents-platform/agents", "name": "SessionAgentResource", "object": null, "schema_name": "SessionAgentResource", "description": "The effective agent configuration for a session.", "fields": [ { "name": "id", "type": "string", "required": true, "description": "The ID of the agent." }, { "name": "name", "type": "string | null", "required": true, "description": "The reusable agent's name when the session was created, or null if no name was saved. Later changes to the agent's name do not affect this value." }, { "name": "model", "type": "string", "required": true, "description": "The model used by the agent." }, { "name": "reasoning", "type": "ReasoningResource", "required": true, "description": "The agent's reasoning configuration." }, { "name": "text", "type": "TextResource", "required": true, "description": "Configuration for text generated by the agent." }, { "name": "service_tier", "type": "ServiceTierResource", "required": true, "description": "The effective service-tier policy for model requests. Defaults to `auto`.", "enum": [ "auto", "default", "flex", "priority", "fast" ] }, { "name": "instructions", "type": "string | null", "required": true, "description": "Custom instructions appended to the agent's default base instructions." }, { "name": "tools", "type": "array", "required": true, "description": "Tools available to the agent." }, { "name": "multi_agent", "type": "MultiAgentConfigResource", "required": true, "description": "Configuration for creating and coordinating subagents." } ], "status": [ "DOCUMENTED", "BETA" ], "example": null, "sources": [ { "url": "https://github.com/openai/openai-openapi (openapi-master.yaml)", "retrieved_at": "2026-09-18T00:00:00Z" } ], "_fragment": "generated/fragments/objects/openai-agents-objects.json" }, { "provider": "openai", "api_family": "agents-platform/agents", "name": "EnvironmentResourceNone", "object": null, "schema_name": "EnvironmentResourceNone", "description": "The session talks to CCA without selecting or provisioning an execution environment.", "fields": [ { "name": "type", "type": "string", "required": true, "description": "The type of the object. Always `none`.", "enum": [ "none" ], "const": "none" } ], "status": [ "DOCUMENTED", "BETA" ], "example": null, "sources": [ { "url": "https://github.com/openai/openai-openapi (openapi-master.yaml)", "retrieved_at": "2026-09-18T00:00:00Z" } ], "_fragment": "generated/fragments/objects/openai-agents-objects.json" }, { "provider": "openai", "api_family": "agents-platform/agents", "name": "EnvironmentResourceOpenaiHosted", "object": null, "schema_name": "EnvironmentResourceOpenaiHosted", "description": "An environment hosted by OpenAI.", "fields": [ { "name": "type", "type": "string", "required": true, "description": "The type of the object. Always `openai_hosted`.", "enum": [ "openai_hosted" ], "const": "openai_hosted" }, { "name": "id", "type": "string", "required": true, "description": "The public ID of the environment." }, { "name": "packages", "type": "EnvironmentPackagesResource", "required": true, "description": "Packages installed in the environment." }, { "name": "network", "type": "NetworkPolicyResource", "required": true, "description": "The effective network access policy for the environment." }, { "name": "capability_directories", "type": "array", "required": true, "description": "Directories that contain capabilities exposed to the agent." }, { "name": "skills", "type": "array", "required": true, "description": "Skills installed in the environment, excluding their archive contents." }, { "name": "plugins", "type": "array", "required": true, "description": "Plugins installed in the environment, excluding their archive contents." }, { "name": "files", "type": "array", "required": true, "description": "Files available in the environment, excluding their contents." } ], "status": [ "DOCUMENTED", "BETA" ], "example": null, "sources": [ { "url": "https://github.com/openai/openai-openapi (openapi-master.yaml)", "retrieved_at": "2026-09-18T00:00:00Z" } ], "_fragment": "generated/fragments/objects/openai-agents-objects.json" }, { "provider": "openai", "api_family": "agents-platform/agents", "name": "EnvironmentResourceSelfHosted", "object": null, "schema_name": "EnvironmentResourceSelfHosted", "description": "An environment hosted by the application.", "fields": [ { "name": "type", "type": "string", "required": true, "description": "The type of the object. Always `self_hosted`.", "enum": [ "self_hosted" ], "const": "self_hosted" }, { "name": "remote_url", "type": "string", "required": true, "description": "Pass this URL unchanged to `codex exec-server --remote` when connecting this environment." }, { "name": "id", "type": "string", "required": true, "description": "The public ID of the environment." }, { "name": "workspace_directory", "type": "string", "required": true, "description": "The absolute project directory inside the environment. Defaults to `/workspace`." }, { "name": "capability_directories", "type": "array", "required": true, "description": "Directories that contain capabilities exposed to the agent." } ], "status": [ "DOCUMENTED", "BETA" ], "example": null, "sources": [ { "url": "https://github.com/openai/openai-openapi (openapi-master.yaml)", "retrieved_at": "2026-09-18T00:00:00Z" } ], "_fragment": "generated/fragments/objects/openai-agents-objects.json" }, { "provider": "openai", "api_family": "agents-platform/agents", "name": "SessionRequiredActionResourceFunctionCall", "object": null, "schema_name": "SessionRequiredActionResourceFunctionCall", "description": "Run a function tool and submit its result.", "fields": [ { "name": "type", "type": "string", "required": true, "description": "The type of the object. Always `function_call`.", "enum": [ "function_call" ], "const": "function_call" }, { "name": "turn_id", "type": "string", "required": true, "description": "The ID of the turn that requested the function call." }, { "name": "call_id", "type": "string", "required": true, "description": "The ID to include when submitting the function result." }, { "name": "name", "type": "string", "required": true, "description": "The function name." }, { "name": "arguments", "type": "any", "required": true, "description": "The arguments supplied by the model." } ], "status": [ "DOCUMENTED", "BETA" ], "example": null, "sources": [ { "url": "https://github.com/openai/openai-openapi (openapi-master.yaml)", "retrieved_at": "2026-09-18T00:00:00Z" } ], "_fragment": "generated/fragments/objects/openai-agents-objects.json" }, { "provider": "openai", "api_family": "agents-platform/agents", "name": "SessionRequiredActionResourceEnvironmentConnection", "object": null, "schema_name": "SessionRequiredActionResourceEnvironmentConnection", "description": "Reconnect a session environment.", "fields": [ { "name": "type", "type": "string", "required": true, "description": "The type of the object. Always `environment_connection`.", "enum": [ "environment_connection" ], "const": "environment_connection" }, { "name": "environment_id", "type": "string", "required": true, "description": "The ID of the environment to reconnect." } ], "status": [ "DOCUMENTED", "BETA" ], "example": null, "sources": [ { "url": "https://github.com/openai/openai-openapi (openapi-master.yaml)", "retrieved_at": "2026-09-18T00:00:00Z" } ], "_fragment": "generated/fragments/objects/openai-agents-objects.json" }, { "provider": "openai", "api_family": "agents-platform/agents", "name": "TokenUsageResource", "object": null, "schema_name": "TokenUsageResource", "description": "Recorded token usage for a session or turn. Usage is best effort and may change.", "fields": [ { "name": "input_tokens", "type": "integer", "required": true, "description": "The number of input tokens used by the agent." }, { "name": "input_tokens_details", "type": "InputTokensDetailsResource", "required": true, "description": "A breakdown of the agent's input token usage." }, { "name": "output_tokens", "type": "integer", "required": true, "description": "The number of output tokens generated by the agent." }, { "name": "output_tokens_details", "type": "OutputTokensDetailsResource", "required": true, "description": "A breakdown of the agent's output token usage." }, { "name": "total_tokens", "type": "integer", "required": true, "description": "The total number of input and output tokens used by the agent." } ], "status": [ "DOCUMENTED", "BETA" ], "example": null, "sources": [ { "url": "https://github.com/openai/openai-openapi (openapi-master.yaml)", "retrieved_at": "2026-09-18T00:00:00Z" } ], "_fragment": "generated/fragments/objects/openai-agents-objects.json" }, { "provider": "openai", "api_family": "agents-platform/agents", "name": "SessionTurnErrorResource", "object": null, "schema_name": "SessionTurnErrorResource", "description": "A customer-safe error describing why a session request failed.", "fields": [ { "name": "code", "type": "SessionTurnErrorCodeResource", "required": true, "description": "A stable, machine-readable failure category.", "enum": [ "context_length_exceeded", "session_budget_exceeded", "usage_limit_exceeded", "credit_balance_exhausted", "rate_limit_exceeded", "server_overloaded", "cyber_policy", "connection_failed", "server_error", "authentication_error", "invalid_request", "resource_not_found", "sandbox_error", "executor_version_incompatible", "active_turn_not_steerable", "request_timeout", "internal_error" ] }, { "name": "message", "type": "string", "required": true, "description": "A customer-safe explanation of the failure." } ], "status": [ "DOCUMENTED", "BETA" ], "example": null, "sources": [ { "url": "https://github.com/openai/openai-openapi (openapi-master.yaml)", "retrieved_at": "2026-09-18T00:00:00Z" } ], "_fragment": "generated/fragments/objects/openai-agents-objects.json" }, { "provider": "openai", "api_family": "agents-platform/agents", "name": "ReasoningResource", "object": null, "schema_name": "ReasoningResource", "description": "The reasoning configuration used by an agent.", "fields": [ { "name": "effort", "type": "ReasoningEffortResource | null", "required": true, "description": "The requested reasoning effort, or `null` when the model selects its own default." }, { "name": "summary", "type": "ReasoningSummaryResource | null", "required": true, "description": "The requested reasoning summary format, or `null` when summaries are disabled." } ], "status": [ "DOCUMENTED", "BETA" ], "example": null, "sources": [ { "url": "https://github.com/openai/openai-openapi (openapi-master.yaml)", "retrieved_at": "2026-09-18T00:00:00Z" } ], "_fragment": "generated/fragments/objects/openai-agents-objects.json" }, { "provider": "openai", "api_family": "agents-platform/agents", "name": "TextResource", "object": null, "schema_name": "TextResource", "description": "The text configuration used by an agent.", "fields": [ { "name": "format", "type": "TextFormatResource", "required": true, "description": "The effective output format. Defaults to ordinary text." }, { "name": "verbosity", "type": "VerbosityResource", "required": true, "description": "The amount of text produced by the agent. Defaults to `medium`.", "enum": [ "low", "medium", "high" ] } ], "status": [ "DOCUMENTED", "BETA" ], "example": null, "sources": [ { "url": "https://github.com/openai/openai-openapi (openapi-master.yaml)", "retrieved_at": "2026-09-18T00:00:00Z" } ], "_fragment": "generated/fragments/objects/openai-agents-objects.json" }, { "provider": "openai", "api_family": "agents-platform/agents", "name": "MultiAgentConfigResource", "object": null, "schema_name": "MultiAgentConfigResource", "description": "The resolved configuration for creating and coordinating subagents.", "fields": [ { "name": "enabled", "type": "boolean", "required": true, "description": "Whether subagent tools are enabled. Defaults to false." }, { "name": "max_concurrent_subagents", "type": "integer | null", "required": true, "description": "Maximum number of subagents that may run concurrently, or null when disabled. Defaults to 6 when enabled." } ], "status": [ "DOCUMENTED", "BETA" ], "example": null, "sources": [ { "url": "https://github.com/openai/openai-openapi (openapi-master.yaml)", "retrieved_at": "2026-09-18T00:00:00Z" } ], "_fragment": "generated/fragments/objects/openai-agents-objects.json" }, { "provider": "openai", "api_family": "agents-platform/agents", "name": "NetworkPolicyResource", "object": null, "schema_name": "NetworkPolicyResource", "description": "Network access for an OpenAI-hosted environment.", "fields": [ { "name": "access", "type": "NetworkAccessResource", "required": true, "description": "The environment's network access mode.", "enum": [ "enabled", "disabled", "restricted" ] }, { "name": "allowed_domains", "type": "array", "required": true, "description": "Domains the environment may access when network access is restricted." } ], "status": [ "DOCUMENTED", "BETA" ], "example": null, "sources": [ { "url": "https://github.com/openai/openai-openapi (openapi-master.yaml)", "retrieved_at": "2026-09-18T00:00:00Z" } ], "_fragment": "generated/fragments/objects/openai-agents-objects.json" }, { "provider": "openai", "api_family": "agents-platform/agents", "name": "EnvironmentPackagesResource", "object": null, "schema_name": "EnvironmentPackagesResource", "description": "Packages installed in an OpenAI-hosted environment.", "fields": [ { "name": "python", "type": "array", "required": true, "description": "Python packages installed in the environment." }, { "name": "system", "type": "array", "required": true, "description": "System packages installed in the environment." }, { "name": "npm", "type": "array", "required": true, "description": "npm packages installed globally in the environment." } ], "status": [ "DOCUMENTED", "BETA" ], "example": null, "sources": [ { "url": "https://github.com/openai/openai-openapi (openapi-master.yaml)", "retrieved_at": "2026-09-18T00:00:00Z" } ], "_fragment": "generated/fragments/objects/openai-agents-objects.json" }, { "provider": "openai", "api_family": "agents-platform/vaults", "name": "VaultCredentialAuthResourceStaticBearer", "object": null, "schema_name": "VaultCredentialAuthResourceStaticBearer", "description": "Metadata for a bearer-token credential, without automatic OAuth refresh.", "fields": [ { "name": "type", "type": "string", "required": true, "description": "The type of the object. Always `static_bearer`.", "enum": [ "static_bearer" ], "const": "static_bearer" }, { "name": "mcp_server_url", "type": "string", "required": true, "description": "The HTTPS MCP server URL authorized by this credential." } ], "status": [ "DOCUMENTED", "BETA" ], "example": null, "sources": [ { "url": "https://github.com/openai/openai-openapi (openapi-master.yaml)", "retrieved_at": "2026-09-18T00:00:00Z" } ], "_fragment": "generated/fragments/objects/openai-agents-objects.json" }, { "provider": "openai", "api_family": "agents-platform/vaults", "name": "VaultCredentialAuthResourceMcpOauth", "object": null, "schema_name": "VaultCredentialAuthResourceMcpOauth", "description": "Public metadata for an OAuth credential; tokens and client secrets are never returned.", "fields": [ { "name": "type", "type": "string", "required": true, "description": "The type of the object. Always `mcp_oauth`.", "enum": [ "mcp_oauth" ], "const": "mcp_oauth" }, { "name": "mcp_server_url", "type": "string", "required": true, "description": "The HTTPS MCP server URL authorized by this credential." }, { "name": "expires_at", "type": "string | null", "required": true, "description": "When the OAuth access token expires, as an RFC 3339 timestamp, if known." }, { "name": "refresh", "type": "McpOauthRefreshResource | null", "required": true, "description": "Public refresh metadata without refresh tokens or OAuth client secrets." } ], "status": [ "DOCUMENTED", "BETA" ], "example": null, "sources": [ { "url": "https://github.com/openai/openai-openapi (openapi-master.yaml)", "retrieved_at": "2026-09-18T00:00:00Z" } ], "_fragment": "generated/fragments/objects/openai-agents-objects.json" }, { "provider": "openai", "api_family": "agents-platform/vaults", "name": "VaultCredentialAuthResourceEnvironmentVariable", "object": null, "schema_name": "VaultCredentialAuthResourceEnvironmentVariable", "description": "Metadata for an HTTP credential used only in OpenAI-hosted environments. Sandbox code receives a placeholder. The proxy substitutes the secret for allowed HTTPS destinations on ports 443 and 8443. The real secret is not available to sandbox code for local computation and is never returned in this resource.", "fields": [ { "name": "type", "type": "string", "required": true, "description": "The type of the object. Always `environment_variable`.", "enum": [ "environment_variable" ], "const": "environment_variable" }, { "name": "secret_name", "type": "string", "required": true, "description": "The environment variable name that receives the placeholder in the sandbox." }, { "name": "networking", "type": "VaultCredentialNetworkingResource", "required": true, "description": "The destinations where the proxy can substitute the secret, subject to the environment network policy." } ], "status": [ "DOCUMENTED", "BETA" ], "example": null, "sources": [ { "url": "https://github.com/openai/openai-openapi (openapi-master.yaml)", "retrieved_at": "2026-09-18T00:00:00Z" } ], "_fragment": "generated/fragments/objects/openai-agents-objects.json" }, { "provider": "openai", "api_family": "agents-platform/agents", "name": "SessionEnvironmentStateResource", "object": null, "schema_name": "SessionEnvironmentStateResource", "description": "The current state of a session environment.", "fields": [ { "name": "id", "type": "string", "required": true, "description": "The public ID of the environment." }, { "name": "type", "type": "string", "required": true, "description": "The environment type." }, { "name": "status", "type": "SessionEnvironmentStatusResource", "required": true, "description": "The environment's connection status.", "enum": [ "pending", "ready", "connected", "disconnected", "failed" ] }, { "name": "error", "type": "SessionEnvironmentErrorResource | null", "required": true, "description": "The error reported while preparing the environment, if any." } ], "status": [ "DOCUMENTED", "BETA" ], "example": null, "sources": [ { "url": "https://github.com/openai/openai-openapi (openapi-master.yaml)", "retrieved_at": "2026-09-18T00:00:00Z" } ], "_fragment": "generated/fragments/objects/openai-agents-objects.json" }, { "provider": "openai", "api_family": "agents-platform/chatkit", "name": "ChatKit thread item: chatkit.user_message", "object": "chatkit.thread_item", "schema_name": "UserMessageItem", "description": "User-authored messages within a thread.", "fields": [ { "name": "id", "type": "string", "required": true, "description": "Identifier of the thread item." }, { "name": "object", "type": "string", "required": true, "description": "Type discriminator that is always `chatkit.thread_item`." }, { "name": "created_at", "type": "integer", "required": true, "description": "Unix timestamp (in seconds) for when the item was created." }, { "name": "thread_id", "type": "string", "required": true, "description": "Identifier of the parent thread." }, { "name": "type", "type": "string", "required": true, "description": "", "enum": [ "chatkit.user_message" ], "const": "chatkit.user_message" }, { "name": "content", "type": "array", "required": true, "description": "Ordered content elements supplied by the user." }, { "name": "attachments", "type": "array", "required": true, "description": "Attachments associated with the user message. Defaults to an empty list." }, { "name": "inference_options", "type": "InferenceOptions | null", "required": true, "description": "" } ], "status": [ "DOCUMENTED", "BETA" ], "example": null, "sources": [ { "url": "https://developers.openai.com/api/reference/resources/beta/subresources/chatkit/subresources/threads", "retrieved_at": "2026-09-18T00:00:00Z" }, { "url": "https://github.com/openai/openai-openapi (openapi-master.yaml)", "retrieved_at": "2026-09-18T00:00:00Z" } ], "_fragment": "generated/fragments/objects/openai-agents-objects.json" }, { "provider": "openai", "api_family": "agents-platform/chatkit", "name": "ChatKit thread item: chatkit.assistant_message", "object": "chatkit.thread_item", "schema_name": "AssistantMessageItem", "description": "Assistant-authored message within a thread.", "fields": [ { "name": "id", "type": "string", "required": true, "description": "Identifier of the thread item." }, { "name": "object", "type": "string", "required": true, "description": "Type discriminator that is always `chatkit.thread_item`." }, { "name": "created_at", "type": "integer", "required": true, "description": "Unix timestamp (in seconds) for when the item was created." }, { "name": "thread_id", "type": "string", "required": true, "description": "Identifier of the parent thread." }, { "name": "type", "type": "string", "required": true, "description": "Type discriminator that is always `chatkit.assistant_message`.", "enum": [ "chatkit.assistant_message" ], "const": "chatkit.assistant_message" }, { "name": "content", "type": "array", "required": true, "description": "Ordered assistant response segments." } ], "status": [ "DOCUMENTED", "BETA" ], "example": null, "sources": [ { "url": "https://developers.openai.com/api/reference/resources/beta/subresources/chatkit/subresources/threads", "retrieved_at": "2026-09-18T00:00:00Z" }, { "url": "https://github.com/openai/openai-openapi (openapi-master.yaml)", "retrieved_at": "2026-09-18T00:00:00Z" } ], "_fragment": "generated/fragments/objects/openai-agents-objects.json" }, { "provider": "openai", "api_family": "agents-platform/chatkit", "name": "ChatKit thread item: chatkit.widget", "object": "chatkit.thread_item", "schema_name": "WidgetMessageItem", "description": "Thread item that renders a widget payload.", "fields": [ { "name": "id", "type": "string", "required": true, "description": "Identifier of the thread item." }, { "name": "object", "type": "string", "required": true, "description": "Type discriminator that is always `chatkit.thread_item`." }, { "name": "created_at", "type": "integer", "required": true, "description": "Unix timestamp (in seconds) for when the item was created." }, { "name": "thread_id", "type": "string", "required": true, "description": "Identifier of the parent thread." }, { "name": "type", "type": "string", "required": true, "description": "Type discriminator that is always `chatkit.widget`.", "enum": [ "chatkit.widget" ], "const": "chatkit.widget" }, { "name": "widget", "type": "string", "required": true, "description": "Serialized widget payload rendered in the UI." } ], "status": [ "DOCUMENTED", "BETA" ], "example": null, "sources": [ { "url": "https://developers.openai.com/api/reference/resources/beta/subresources/chatkit/subresources/threads", "retrieved_at": "2026-09-18T00:00:00Z" }, { "url": "https://github.com/openai/openai-openapi (openapi-master.yaml)", "retrieved_at": "2026-09-18T00:00:00Z" } ], "_fragment": "generated/fragments/objects/openai-agents-objects.json" }, { "provider": "openai", "api_family": "agents-platform/chatkit", "name": "ChatKit thread item: chatkit.client_tool_call", "object": "chatkit.thread_item", "schema_name": "ClientToolCallItem", "description": "Record of a client side tool invocation initiated by the assistant.", "fields": [ { "name": "id", "type": "string", "required": true, "description": "Identifier of the thread item." }, { "name": "object", "type": "string", "required": true, "description": "Type discriminator that is always `chatkit.thread_item`." }, { "name": "created_at", "type": "integer", "required": true, "description": "Unix timestamp (in seconds) for when the item was created." }, { "name": "thread_id", "type": "string", "required": true, "description": "Identifier of the parent thread." }, { "name": "type", "type": "string", "required": true, "description": "Type discriminator that is always `chatkit.client_tool_call`.", "enum": [ "chatkit.client_tool_call" ], "const": "chatkit.client_tool_call" }, { "name": "status", "type": "ClientToolCallStatus", "required": true, "description": "Execution status for the tool call.", "enum": [ "in_progress", "completed" ] }, { "name": "call_id", "type": "string", "required": true, "description": "Identifier for the client tool call." }, { "name": "name", "type": "string", "required": true, "description": "Tool name that was invoked." }, { "name": "arguments", "type": "string", "required": true, "description": "JSON-encoded arguments that were sent to the tool." }, { "name": "output", "type": "string | null", "required": true, "description": "" } ], "status": [ "DOCUMENTED", "BETA" ], "example": null, "sources": [ { "url": "https://developers.openai.com/api/reference/resources/beta/subresources/chatkit/subresources/threads", "retrieved_at": "2026-09-18T00:00:00Z" }, { "url": "https://github.com/openai/openai-openapi (openapi-master.yaml)", "retrieved_at": "2026-09-18T00:00:00Z" } ], "_fragment": "generated/fragments/objects/openai-agents-objects.json" }, { "provider": "openai", "api_family": "agents-platform/chatkit", "name": "ChatKit thread item: chatkit.task", "object": "chatkit.thread_item", "schema_name": "TaskItem", "description": "Task emitted by the workflow to show progress and status updates.", "fields": [ { "name": "id", "type": "string", "required": true, "description": "Identifier of the thread item." }, { "name": "object", "type": "string", "required": true, "description": "Type discriminator that is always `chatkit.thread_item`." }, { "name": "created_at", "type": "integer", "required": true, "description": "Unix timestamp (in seconds) for when the item was created." }, { "name": "thread_id", "type": "string", "required": true, "description": "Identifier of the parent thread." }, { "name": "type", "type": "string", "required": true, "description": "Type discriminator that is always `chatkit.task`.", "enum": [ "chatkit.task" ], "const": "chatkit.task" }, { "name": "task_type", "type": "TaskType", "required": true, "description": "Subtype for the task.", "enum": [ "custom", "thought" ] }, { "name": "heading", "type": "string | null", "required": true, "description": "" }, { "name": "summary", "type": "string | null", "required": true, "description": "" } ], "status": [ "DOCUMENTED", "BETA" ], "example": null, "sources": [ { "url": "https://developers.openai.com/api/reference/resources/beta/subresources/chatkit/subresources/threads", "retrieved_at": "2026-09-18T00:00:00Z" }, { "url": "https://github.com/openai/openai-openapi (openapi-master.yaml)", "retrieved_at": "2026-09-18T00:00:00Z" } ], "_fragment": "generated/fragments/objects/openai-agents-objects.json" }, { "provider": "openai", "api_family": "agents-platform/chatkit", "name": "ChatKit thread item: chatkit.task_group", "object": "chatkit.thread_item", "schema_name": "TaskGroupItem", "description": "Collection of workflow tasks grouped together in the thread.", "fields": [ { "name": "id", "type": "string", "required": true, "description": "Identifier of the thread item." }, { "name": "object", "type": "string", "required": true, "description": "Type discriminator that is always `chatkit.thread_item`." }, { "name": "created_at", "type": "integer", "required": true, "description": "Unix timestamp (in seconds) for when the item was created." }, { "name": "thread_id", "type": "string", "required": true, "description": "Identifier of the parent thread." }, { "name": "type", "type": "string", "required": true, "description": "Type discriminator that is always `chatkit.task_group`.", "enum": [ "chatkit.task_group" ], "const": "chatkit.task_group" }, { "name": "tasks", "type": "array", "required": true, "description": "Tasks included in the group." } ], "status": [ "DOCUMENTED", "BETA" ], "example": null, "sources": [ { "url": "https://developers.openai.com/api/reference/resources/beta/subresources/chatkit/subresources/threads", "retrieved_at": "2026-09-18T00:00:00Z" }, { "url": "https://github.com/openai/openai-openapi (openapi-master.yaml)", "retrieved_at": "2026-09-18T00:00:00Z" } ], "_fragment": "generated/fragments/objects/openai-agents-objects.json" }, { "provider": "openai", "api_family": "agents-platform", "name": "enum SessionStatusResource", "object": null, "schema_name": "SessionStatusResource", "description": "The current status of a session.", "enum": [ "idle", "in_progress", "requires_action", "failed" ], "fields": [], "status": [ "DOCUMENTED", "BETA" ], "sources": [ { "url": "https://github.com/openai/openai-openapi (openapi-master.yaml)", "retrieved_at": "2026-09-18T00:00:00Z" } ], "_fragment": "generated/fragments/objects/openai-agents-objects.json" }, { "provider": "openai", "api_family": "agents-platform", "name": "enum TurnStatusResource", "object": null, "schema_name": "TurnStatusResource", "description": "The current status of a turn.", "enum": [ "queued", "in_progress", "waiting", "completed", "failed", "cancelled" ], "fields": [], "status": [ "DOCUMENTED", "BETA" ], "sources": [ { "url": "https://github.com/openai/openai-openapi (openapi-master.yaml)", "retrieved_at": "2026-09-18T00:00:00Z" } ], "_fragment": "generated/fragments/objects/openai-agents-objects.json" }, { "provider": "openai", "api_family": "agents-platform", "name": "enum SubagentStatusResource", "object": null, "schema_name": "SubagentStatusResource", "description": "The current status of a subagent.", "enum": [ "active", "closed" ], "fields": [], "status": [ "DOCUMENTED", "BETA" ], "sources": [ { "url": "https://github.com/openai/openai-openapi (openapi-master.yaml)", "retrieved_at": "2026-09-18T00:00:00Z" } ], "_fragment": "generated/fragments/objects/openai-agents-objects.json" }, { "provider": "openai", "api_family": "agents-platform", "name": "enum EnvironmentStatusResource", "object": null, "schema_name": "EnvironmentStatusResource", "description": "The public lifecycle status of an execution environment.", "enum": [ "pending", "connected", "disconnected", "expired", "failed" ], "fields": [], "status": [ "DOCUMENTED", "BETA" ], "sources": [ { "url": "https://github.com/openai/openai-openapi (openapi-master.yaml)", "retrieved_at": "2026-09-18T00:00:00Z" } ], "_fragment": "generated/fragments/objects/openai-agents-objects.json" }, { "provider": "openai", "api_family": "agents-platform", "name": "enum SessionEnvironmentStatusResource", "object": null, "schema_name": "SessionEnvironmentStatusResource", "description": "The connection status of a session environment.", "enum": [ "pending", "ready", "connected", "disconnected", "failed" ], "fields": [], "status": [ "DOCUMENTED", "BETA" ], "sources": [ { "url": "https://github.com/openai/openai-openapi (openapi-master.yaml)", "retrieved_at": "2026-09-18T00:00:00Z" } ], "_fragment": "generated/fragments/objects/openai-agents-objects.json" }, { "provider": "openai", "api_family": "agents-platform", "name": "enum SessionTurnErrorCodeResource", "object": null, "schema_name": "SessionTurnErrorCodeResource", "description": "Stable public categories for session request failures.", "enum": [ "context_length_exceeded", "session_budget_exceeded", "usage_limit_exceeded", "credit_balance_exhausted", "rate_limit_exceeded", "server_overloaded", "cyber_policy", "connection_failed", "server_error", "authentication_error", "invalid_request", "resource_not_found", "sandbox_error", "executor_version_incompatible", "active_turn_not_steerable", "request_timeout", "internal_error" ], "fields": [], "status": [ "DOCUMENTED", "BETA" ], "sources": [ { "url": "https://github.com/openai/openai-openapi (openapi-master.yaml)", "retrieved_at": "2026-09-18T00:00:00Z" } ], "_fragment": "generated/fragments/objects/openai-agents-objects.json" }, { "provider": "openai", "api_family": "agents-platform", "name": "enum FunctionCallStatusResource", "object": null, "schema_name": "FunctionCallStatusResource", "description": "The status of a tool call.", "enum": [ "in_progress", "completed", "failed", "incomplete" ], "fields": [], "status": [ "DOCUMENTED", "BETA" ], "sources": [ { "url": "https://github.com/openai/openai-openapi (openapi-master.yaml)", "retrieved_at": "2026-09-18T00:00:00Z" } ], "_fragment": "generated/fragments/objects/openai-agents-objects.json" }, { "provider": "openai", "api_family": "agents-platform", "name": "enum OutputItemStatusResource", "object": null, "schema_name": "OutputItemStatusResource", "description": "The status of an agent output item.", "enum": [ "in_progress", "completed", "incomplete" ], "fields": [], "status": [ "DOCUMENTED", "BETA" ], "sources": [ { "url": "https://github.com/openai/openai-openapi (openapi-master.yaml)", "retrieved_at": "2026-09-18T00:00:00Z" } ], "_fragment": "generated/fragments/objects/openai-agents-objects.json" }, { "provider": "openai", "api_family": "agents-platform", "name": "enum MessagePhaseResource", "object": null, "schema_name": "MessagePhaseResource", "description": "The phase of an assistant message.", "enum": [ "commentary", "final_answer" ], "fields": [], "status": [ "DOCUMENTED", "BETA" ], "sources": [ { "url": "https://github.com/openai/openai-openapi (openapi-master.yaml)", "retrieved_at": "2026-09-18T00:00:00Z" } ], "_fragment": "generated/fragments/objects/openai-agents-objects.json" }, { "provider": "openai", "api_family": "agents-platform", "name": "enum ReasoningEffortParam", "object": null, "schema_name": "ReasoningEffortParam", "description": "The amount of reasoning effort the model should use.", "enum": [ "none", "minimal", "low", "medium", "high", "xhigh", "max" ], "fields": [], "status": [ "DOCUMENTED", "BETA" ], "sources": [ { "url": "https://github.com/openai/openai-openapi (openapi-master.yaml)", "retrieved_at": "2026-09-18T00:00:00Z" } ], "_fragment": "generated/fragments/objects/openai-agents-objects.json" }, { "provider": "openai", "api_family": "agents-platform", "name": "enum ServiceTierParam", "object": null, "schema_name": "ServiceTierParam", "description": "The service tier used for model requests.", "enum": [ "auto", "default", "flex", "priority", "fast" ], "fields": [], "status": [ "DOCUMENTED", "BETA" ], "sources": [ { "url": "https://github.com/openai/openai-openapi (openapi-master.yaml)", "retrieved_at": "2026-09-18T00:00:00Z" } ], "_fragment": "generated/fragments/objects/openai-agents-objects.json" }, { "provider": "openai", "api_family": "agents-platform", "name": "enum NetworkAccessParam", "object": null, "schema_name": "NetworkAccessParam", "description": "The network access mode for an OpenAI-hosted environment.", "enum": [ "enabled", "disabled", "restricted" ], "fields": [], "status": [ "DOCUMENTED", "BETA" ], "sources": [ { "url": "https://github.com/openai/openai-openapi (openapi-master.yaml)", "retrieved_at": "2026-09-18T00:00:00Z" } ], "_fragment": "generated/fragments/objects/openai-agents-objects.json" }, { "provider": "openai", "api_family": "agents-platform", "name": "enum McpConnectionOriginParam", "object": null, "schema_name": "McpConnectionOriginParam", "description": "Where outbound MCP HTTP connections originate.", "enum": [ "service", "environment" ], "fields": [], "status": [ "DOCUMENTED", "BETA" ], "sources": [ { "url": "https://github.com/openai/openai-openapi (openapi-master.yaml)", "retrieved_at": "2026-09-18T00:00:00Z" } ], "_fragment": "generated/fragments/objects/openai-agents-objects.json" }, { "provider": "openai", "api_family": "agents-platform", "name": "enum WebSearchModeParam", "object": null, "schema_name": "WebSearchModeParam", "description": "The source used for web search results.", "enum": [ "disabled", "cached", "live" ], "fields": [], "status": [ "DOCUMENTED", "BETA" ], "sources": [ { "url": "https://github.com/openai/openai-openapi (openapi-master.yaml)", "retrieved_at": "2026-09-18T00:00:00Z" } ], "_fragment": "generated/fragments/objects/openai-agents-objects.json" }, { "provider": "openai", "api_family": "agents-platform", "name": "enum VaultStatusParam", "object": null, "schema_name": "VaultStatusParam", "description": "Whether a vault or credential is active or archived.", "enum": [ "active", "archived" ], "fields": [], "status": [ "DOCUMENTED", "BETA" ], "sources": [ { "url": "https://github.com/openai/openai-openapi (openapi-master.yaml)", "retrieved_at": "2026-09-18T00:00:00Z" } ], "_fragment": "generated/fragments/objects/openai-agents-objects.json" }, { "provider": "openai", "api_family": "agents-platform", "name": "enum ChatSessionStatus", "object": null, "schema_name": "ChatSessionStatus", "description": "", "enum": [ "active", "expired", "cancelled" ], "fields": [], "status": [ "DOCUMENTED", "BETA" ], "sources": [ { "url": "https://github.com/openai/openai-openapi (openapi-master.yaml)", "retrieved_at": "2026-09-18T00:00:00Z" } ], "_fragment": "generated/fragments/objects/openai-agents-objects.json" }, { "provider": "openai", "api_family": "agents-platform/workspace-agents", "name": "Workspace agent trigger run", "object": "workspace_agent.trigger_run", "schema_name": null, "description": "Status of a trigger run on api.chatgpt.com (beta; requires OpenAI-Beta: workspace_agent_runs=v1).", "fields": [ { "name": "object", "type": "\"workspace_agent.trigger_run\"", "required": true, "description": "" }, { "name": "id", "type": "string (apirun_…)", "required": true, "description": "" }, { "name": "status", "type": "queued|in_progress|suspended|completed|failed", "required": true, "description": "completed/failed terminal" }, { "name": "created_at", "type": "integer", "required": true, "description": "" }, { "name": "agent_id", "type": "string (agt_…)", "required": true, "description": "" }, { "name": "api_trigger_id", "type": "string (agtch_…)", "required": true, "description": "" }, { "name": "conversation_url", "type": "string", "required": true, "description": "https://chatgpt.com/c/…" }, { "name": "error", "type": "null | {code: dispatch_failed|run_failed}", "required": true, "description": "" } ], "status": [ "DOCUMENTED", "BETA", "UNVERIFIED" ], "example": { "object": "workspace_agent.trigger_run", "id": "apirun_123", "status": "in_progress", "created_at": 1784763880, "agent_id": "agt_123", "api_trigger_id": "agtch_123", "conversation_url": "https://chatgpt.com/c/123", "error": null }, "sources": [ { "url": "https://developers.openai.com/workspace-agents/trigger-runs", "retrieved_at": "2026-09-18T00:00:00Z" } ], "_fragment": "generated/fragments/objects/openai-agents-objects.json" }, { "provider": "openai", "api_family": "agents-platform/assistants", "name": "assistant (RETIRED 2026-08-26)", "object": "assistant", "schema_name": "AssistantObject", "description": "Represents an `assistant` that can call the model and use tools.", "fields": [ { "name": "id" }, { "name": "object" }, { "name": "created_at" }, { "name": "name" }, { "name": "description" }, { "name": "model" }, { "name": "instructions" }, { "name": "tools" }, { "name": "tool_resources" }, { "name": "metadata" }, { "name": "temperature" }, { "name": "top_p" }, { "name": "response_format" } ], "status": [ "RETIRED", "DOCUMENTED" ], "replacement": "Prompt (dashboard) / Agent", "sources": [ { "url": "https://developers.openai.com/api/docs/assistants/migration", "retrieved_at": "2026-09-18T00:00:00Z" }, { "url": "https://github.com/openai/openai-openapi (openapi-master.yaml)", "retrieved_at": "2026-09-18T00:00:00Z" } ], "_fragment": "generated/fragments/objects/openai-agents-objects.json" }, { "provider": "openai", "api_family": "agents-platform/assistants", "name": "thread (RETIRED 2026-08-26)", "object": "thread", "schema_name": "ThreadObject", "description": "Represents a thread that contains [messages](https://developers.openai.com/api/docs/assistants/migration).", "fields": [ { "name": "id" }, { "name": "object" }, { "name": "created_at" }, { "name": "tool_resources" }, { "name": "metadata" } ], "status": [ "RETIRED", "DOCUMENTED" ], "replacement": "Conversation", "sources": [ { "url": "https://developers.openai.com/api/docs/assistants/migration", "retrieved_at": "2026-09-18T00:00:00Z" }, { "url": "https://github.com/openai/openai-openapi (openapi-master.yaml)", "retrieved_at": "2026-09-18T00:00:00Z" } ], "_fragment": "generated/fragments/objects/openai-agents-objects.json" }, { "provider": "openai", "api_family": "agents-platform/assistants", "name": "thread.message (RETIRED 2026-08-26)", "object": "thread.message", "schema_name": "MessageObject", "description": "Represents a message within a [thread](https://developers.openai.com/api/docs/assistants/migration).", "fields": [ { "name": "id" }, { "name": "object" }, { "name": "created_at" }, { "name": "thread_id" }, { "name": "status" }, { "name": "incomplete_details" }, { "name": "completed_at" }, { "name": "incomplete_at" }, { "name": "role" }, { "name": "content" }, { "name": "assistant_id" }, { "name": "run_id" }, { "name": "attachments" }, { "name": "metadata" } ], "status": [ "RETIRED", "DOCUMENTED" ], "replacement": "Conversation item", "sources": [ { "url": "https://developers.openai.com/api/docs/assistants/migration", "retrieved_at": "2026-09-18T00:00:00Z" }, { "url": "https://github.com/openai/openai-openapi (openapi-master.yaml)", "retrieved_at": "2026-09-18T00:00:00Z" } ], "_fragment": "generated/fragments/objects/openai-agents-objects.json" }, { "provider": "openai", "api_family": "agents-platform/assistants", "name": "thread.run (RETIRED 2026-08-26)", "object": "thread.run", "schema_name": "RunObject", "description": "Represents an execution run on a [thread](https://developers.openai.com/api/docs/assistants/migration).", "fields": [ { "name": "id" }, { "name": "object" }, { "name": "created_at" }, { "name": "thread_id" }, { "name": "assistant_id" }, { "name": "status" }, { "name": "required_action" }, { "name": "last_error" }, { "name": "expires_at" }, { "name": "started_at" }, { "name": "cancelled_at" }, { "name": "failed_at" }, { "name": "completed_at" }, { "name": "incomplete_details" }, { "name": "model" }, { "name": "instructions" }, { "name": "tools" }, { "name": "metadata" }, { "name": "usage" }, { "name": "temperature" }, { "name": "top_p" }, { "name": "max_prompt_tokens" }, { "name": "max_completion_tokens" }, { "name": "truncation_strategy" }, { "name": "tool_choice" }, { "name": "parallel_tool_calls" }, { "name": "response_format" } ], "status": [ "RETIRED", "DOCUMENTED" ], "replacement": "Response", "sources": [ { "url": "https://developers.openai.com/api/docs/assistants/migration", "retrieved_at": "2026-09-18T00:00:00Z" }, { "url": "https://github.com/openai/openai-openapi (openapi-master.yaml)", "retrieved_at": "2026-09-18T00:00:00Z" } ], "_fragment": "generated/fragments/objects/openai-agents-objects.json" }, { "provider": "openai", "api_family": "agents-platform/assistants", "name": "thread.run.step (RETIRED 2026-08-26)", "object": "thread.run.step", "schema_name": "RunStepObject", "description": "Represents a step in execution of a run.", "fields": [ { "name": "id" }, { "name": "object" }, { "name": "created_at" }, { "name": "assistant_id" }, { "name": "thread_id" }, { "name": "run_id" }, { "name": "type" }, { "name": "status" }, { "name": "step_details" }, { "name": "last_error" }, { "name": "expired_at" }, { "name": "cancelled_at" }, { "name": "failed_at" }, { "name": "completed_at" }, { "name": "metadata" }, { "name": "usage" } ], "status": [ "RETIRED", "DOCUMENTED" ], "replacement": "Response output item", "sources": [ { "url": "https://developers.openai.com/api/docs/assistants/migration", "retrieved_at": "2026-09-18T00:00:00Z" }, { "url": "https://github.com/openai/openai-openapi (openapi-master.yaml)", "retrieved_at": "2026-09-18T00:00:00Z" } ], "_fragment": "generated/fragments/objects/openai-agents-objects.json" }, { "provider": "openai", "object": "ImagesResponse", "api_family": "images", "description": "Response of generations/edits/variations.", "fields": { "created": "integer unix s", "data": "Image[]", "background": "transparent|opaque (GPT image)", "output_format": "png|webp|jpeg", "quality": "low|medium|high|xhigh|max", "size": "string", "usage": "ImageUsage (GPT image models)" }, "status": [ "DOCUMENTED", "LIVE_VERIFIED" ], "example": { "created": 1789782224, "background": "opaque", "output_format": "jpeg", "quality": "low", "size": "1024x1024", "data": [ { "b64_json": "<39383 bytes of JPEG, base64>", "generation_id": "" } ], "usage": { "input_tokens": 10, "input_tokens_details": { "image_tokens": 0, "text_tokens": 10 }, "output_tokens": 272, "output_tokens_details": { "image_tokens": 272, "text_tokens": 0 }, "total_tokens": 282 } }, "notes": "Live example (gpt-image-1-mini, low, 1024x1024). `created` present; no `revised_prompt`/`url` for GPT image models.", "sources": [ { "url": "https://developers.openai.com/api/reference/resources/images", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/openai-media-objects.json" }, { "provider": "openai", "object": "Image", "api_family": "images", "description": "One generated image.", "fields": { "b64_json": "string (default for GPT image; dall-e only with response_format=b64_json)", "url": "string (dall-e only, 60-min validity; unsupported for GPT image)", "revised_prompt": "string (dall-e-3 only)", "generation_id": "string — LIVE_DISCOVERED, undocumented (observed on gpt-image-1-mini generations)" }, "status": [ "DOCUMENTED", "LIVE_VERIFIED", "LIVE_DISCOVERED" ], "example": null, "notes": null, "sources": [ { "url": "https://developers.openai.com/api/reference/resources/images", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/openai-media-objects.json" }, { "provider": "openai", "object": "ImageUsage", "api_family": "images", "description": "Token usage for GPT image models (docs text still says 'gpt-image-1 only' but present for all GPT image models).", "fields": { "input_tokens": "int", "input_tokens_details": { "image_tokens": "int", "text_tokens": "int" }, "output_tokens": "int", "output_tokens_details": { "image_tokens": "int", "text_tokens": "int" }, "total_tokens": "int" }, "status": [ "DOCUMENTED", "LIVE_VERIFIED" ], "example": null, "notes": null, "sources": [ { "url": "https://developers.openai.com/api/reference/resources/images", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/openai-media-objects.json" }, { "provider": "openai", "object": "Video", "api_family": "videos", "description": "Video generation job.", "fields": { "id": "string (video_...)", "object": "'video'", "model": "VideoModel", "status": "queued|in_progress|completed|failed", "progress": "integer 0-100", "created_at": "unix s", "completed_at": "unix s|null", "expires_at": "unix s|null (asset expiry, ~48 h after completion observed)", "prompt": "string|null", "size": "VideoSize", "seconds": "string (stitched total for extensions)", "remixed_from_video_id": "string|null", "error": "VideoCreateError|null", "edited_from_video_id": "string|null — LIVE_DISCOVERED (not in docs/spec)", "extended_from_video_id": "string|null — LIVE_DISCOVERED (not in docs/spec)", "quality": "'standard' — appears in a doc example only" }, "status": [ "DOCUMENTED", "DEPRECATED", "LIVE_VERIFIED", "LIVE_DISCOVERED" ], "example": { "id": "video_6a5e...a57a", "object": "video", "created_at": 1784590069, "status": "completed", "completed_at": 1784590117, "edited_from_video_id": null, "error": null, "expires_at": 1784762917, "extended_from_video_id": null, "model": "sora-2", "progress": 100, "prompt": "A simple blue geometric cube rotating on a white background.", "remixed_from_video_id": null, "seconds": "4", "size": "720x1280" }, "notes": "Live example from GET /v1/videos (2026-09-18). expires_at - completed_at = 172,800 s = 48 h.", "sources": [ { "url": "https://developers.openai.com/api/reference/resources/videos", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/openai-media-objects.json" }, { "provider": "openai", "object": "VideoCreateError", "api_family": "videos", "description": "Why a job failed.", "fields": { "code": "string", "message": "string", "misalignment": { "error_type": "potentially_unintended_data_transfer|potentially_unintended_data_access|potentially_unintended_destructive_activity|other|", "detailed_explanation": "string", "steer": { "message": "string" } } }, "status": [ "DOCUMENTED", "DEPRECATED" ], "example": null, "notes": null, "sources": [ { "url": "https://developers.openai.com/api/reference/resources/videos", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/openai-media-objects.json" }, { "provider": "openai", "object": "VideoList", "api_family": "videos", "description": "Paginated list.", "fields": { "object": "'list'", "data": "Video[]", "first_id": "string|null", "last_id": "string|null", "has_more": "boolean" }, "status": [ "DOCUMENTED", "DEPRECATED", "LIVE_VERIFIED" ], "example": null, "notes": null, "sources": [ { "url": "https://developers.openai.com/api/reference/resources/videos", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/openai-media-objects.json" }, { "provider": "openai", "object": "VideoDeleteResponse", "api_family": "videos", "description": "Deletion confirmation.", "fields": { "id": "string", "deleted": "boolean", "object": "'video.deleted'" }, "status": [ "DOCUMENTED", "DEPRECATED" ], "example": null, "notes": null, "sources": [ { "url": "https://developers.openai.com/api/reference/resources/videos", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/openai-media-objects.json" }, { "provider": "openai", "object": "VideoCharacterResource", "api_family": "videos", "description": "Character (cameo) created from an uploaded clip.", "fields": { "id": "string|null", "name": "string|null", "created_at": "unix s" }, "status": [ "DOCUMENTED", "DEPRECATED" ], "example": null, "notes": null, "sources": [ { "url": "https://developers.openai.com/api/reference/resources/videos", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/openai-media-objects.json" }, { "provider": "openai", "object": "WebhookEvent video.completed / video.failed", "api_family": "videos", "description": "Webhook events emitted when a video job reaches a terminal state; payload carries only the job id (fetch details with GET /v1/videos/{id}).", "fields": { "id": "evt_...", "object": "'event'", "created_at": "unix s", "type": "video.completed|video.failed", "data": { "id": "video_..." } }, "status": [ "DOCUMENTED", "DEPRECATED" ], "example": { "id": "evt_abc123", "object": "event", "created_at": 1758941485, "type": "video.completed", "data": { "id": "video_abc123" } }, "notes": null, "sources": [ { "url": "https://developers.openai.com/api/docs/guides/video-generation", "retrieved_at": "2026-09-18" }, { "url": "https://developers.openai.com/api/reference/resources/webhooks", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/openai-media-objects.json" }, { "provider": "openai", "object": "CreateEmbeddingResponse", "api_family": "embeddings", "description": "Embeddings list.", "fields": { "object": "'list'", "data": "Embedding[] (same order as input; index field)", "model": "string (e.g. text-embedding-ada-002-v2)", "usage": { "prompt_tokens": "int", "total_tokens": "int" } }, "status": [ "DOCUMENTED", "LIVE_VERIFIED" ], "example": { "object": "list", "data": [ { "object": "embedding", "index": 0, "embedding": [ "<1536 floats>" ] } ], "model": "text-embedding-3-small", "usage": { "prompt_tokens": 1, "total_tokens": 1 } }, "notes": null, "sources": [ { "url": "https://developers.openai.com/api/reference/resources/embeddings", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/openai-media-objects.json" }, { "provider": "openai", "object": "Embedding", "api_family": "embeddings", "description": "One vector.", "fields": { "object": "'embedding'", "index": "int", "embedding": "float[] (encoding_format=float) | base64 string of little-endian float32 (encoding_format=base64)" }, "status": [ "DOCUMENTED", "LIVE_VERIFIED" ], "example": null, "notes": "Live lengths: 1536 (3-small, ada-002), 3072 (3-large); L2 norm 1.000±0.0003 (also after dimensions=16).", "sources": [ { "url": "https://developers.openai.com/api/reference/resources/embeddings", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/openai-media-objects.json" }, { "provider": "openai", "object": "CreateModerationResponse", "api_family": "moderations", "description": "Moderation response.", "fields": { "id": "string (modr-...)", "model": "string", "results": "Moderation[] (one per input item; multimodal array = one result)" }, "status": [ "DOCUMENTED", "LIVE_VERIFIED" ], "example": null, "notes": null, "sources": [ { "url": "https://developers.openai.com/api/reference/resources/moderations", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/openai-media-objects.json" }, { "provider": "openai", "object": "Moderation", "api_family": "moderations", "description": "Per-input classification.", "fields": { "flagged": "boolean (any category flagged)", "categories": "object — 13 keys: harassment, harassment/threatening, hate, hate/threatening, illicit, illicit/violent, self-harm, self-harm/instructions, self-harm/intent, sexual, sexual/minors, violence, violence/graphic (illicit* nullable for legacy models)", "category_scores": "object model confidence; thresholds may be recalibrated over time", "category_applied_input_types": "object — image supported only for self-harm*, sexual, violence, violence/graphic" }, "status": [ "DOCUMENTED", "LIVE_VERIFIED" ], "example": { "flagged": false, "categories": { "violence": false, "...": "..." }, "category_scores": { "violence": 0.00054, "...": "..." }, "category_applied_input_types": { "violence": [ "text", "image" ], "harassment": [ "text" ] } }, "notes": "Live: with image present, image-capable categories list ['text','image']; text-only input lists ['text'] for all 13.", "sources": [ { "url": "https://developers.openai.com/api/reference/resources/moderations", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/openai-media-objects.json" }, { "provider": "openai", "object": "SafetyAlertResource (safety.alert)", "api_family": "safety", "description": "Misalignment-monitoring alert for one request.", "fields": { "id": "string", "object": "'safety.alert'", "created_at": "unix s", "request_id": "string", "response_id": "string", "model": "string", "request_paused": "boolean — block registration succeeded (does not confirm execution stopped)", "error_type": "potentially_unintended_data_transfer|potentially_unintended_data_access|potentially_unintended_destructive_activity|other", "reason": "string|null (null for ZDR requests)" }, "status": [ "DOCUMENTED", "LIVE_VERIFIED" ], "example": null, "notes": "Endpoint reachable (404 safety_alert_not_found for unknown id).", "sources": [ { "url": "https://raw.githubusercontent.com/openai/openai-openapi/master/openapi.yaml", "retrieved_at": "2026-09-18" }, { "url": "https://developers.openai.com/api/docs/guides/safety-checks/misalignment-monitoring", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/openai-media-objects.json" }, { "provider": "openai", "object": "SafetyCaseResource (safety.case)", "api_family": "safety", "description": "Warning or deactivation issued for a safety identifier.", "fields": { "id": "string", "object": "'safety.case'", "created_at": "unix s", "entity_identifier": "string (the safety identifier)", "reason": "string|null", "notice": { "type": "warning|deactivation" } }, "status": [ "LIVE_DISCOVERED", "ACCOUNT_RESTRICTED" ], "example": null, "notes": "Requires api.safety.read scope (403 for our key).", "sources": [ { "url": "https://raw.githubusercontent.com/openai/openai-openapi/master/openapi.yaml", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/openai-media-objects.json" }, { "provider": "openai", "object": "Safety webhook events", "api_family": "safety", "description": "safety.alert.created (project) / safety.org_alert.created (enterprise workspace) carry an alert id for GET /v1/safety/alerts/{id}; safety.warning_issued / safety.deactivation_issued carry a case id for GET /v1/safety/cases/{id}.", "fields": { "id": "evt_...", "object": "'event'", "created_at": "unix s", "type": "safety.alert.created|safety.org_alert.created|safety.warning_issued|safety.deactivation_issued", "data": { "id": "alert_<32 hex> | C-..." } }, "status": [ "DOCUMENTED" ], "example": { "object": "event", "id": "evt_123", "type": "safety.alert.created", "created_at": 1787659200, "data": { "id": "alert_0123456789abcdef0123456789abcdef" } }, "notes": null, "sources": [ { "url": "https://raw.githubusercontent.com/openai/openai-openapi/master/openapi.yaml", "retrieved_at": "2026-09-18" }, { "url": "https://developers.openai.com/api/docs/guides/safety-checks/misalignment-monitoring", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/openai-media-objects.json" }, { "provider": "openai", "object": "ProvenanceResource (content_provenance_check)", "api_family": "content_provenance", "description": "Synchronous provenance verdicts.", "fields": { "object": "'content_provenance_check'", "created_at": "unix s", "results": "(C2PAProvenanceResult | SynthIDProvenanceResult)[] — images: c2pa + synthid; audio: synthid only; inapplicable checks are omitted" }, "status": [ "DOCUMENTED", "LIVE_VERIFIED" ], "example": { "object": "content_provenance_check", "created_at": 1789782225, "results": [ { "type": "c2pa", "outcome": "detected", "validation_state": "trusted", "issuer": "OpenAI OpCo, LLC", "model": "API / gpt-image", "generated_at": "2026-09-19T01:43:43.564995Z" }, { "type": "synthid", "outcome": "not_detected", "model": null, "generated_at": null } ] }, "notes": "Live on a fresh gpt-image-1-mini JPEG. Note model string 'API / gpt-image' (docs example: 'gpt-image').", "sources": [ { "url": "https://developers.openai.com/api/docs/guides/content-provenance", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/openai-media-objects.json" }, { "provider": "openai", "object": "C2PAProvenanceResult", "api_family": "content_provenance", "description": "C2PA Content Credentials verdict (images).", "fields": { "type": "'c2pa'", "outcome": "detected|not_detected (detected only if trusted/valid manifest issued by OpenAI with an AI-generation action)", "validation_state": "trusted|valid|invalid|not_present", "issuer": "string|null", "model": "string|null", "generated_at": "RFC3339|null" }, "status": [ "DOCUMENTED", "LIVE_VERIFIED" ], "example": null, "notes": null, "sources": [ { "url": "https://developers.openai.com/api/docs/guides/content-provenance", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/openai-media-objects.json" }, { "provider": "openai", "object": "SynthIDProvenanceResult", "api_family": "content_provenance", "description": "SynthID watermark verdict (images + audio).", "fields": { "type": "'synthid'", "outcome": "detected|not_detected", "model": "string|null", "generated_at": "RFC3339|null" }, "status": [ "DOCUMENTED", "LIVE_VERIFIED" ], "example": null, "notes": null, "sources": [ { "url": "https://developers.openai.com/api/docs/guides/content-provenance", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/openai-media-objects.json" }, { "provider": "openai", "api_family": "files", "name": "File", "spec_schema": "OpenAIFile", "object_type": "file", "description": "The `File` object represents a document that has been uploaded to OpenAI.", "required": [ "id", "object", "bytes", "created_at", "filename", "purpose", "status" ], "fields": [ { "parameter": "id", "type": "string", "required": true, "description": "The file identifier, which can be referenced in the API endpoints." }, { "parameter": "bytes", "type": "integer", "required": true, "description": "The size of the file, in bytes." }, { "parameter": "created_at", "type": "integer", "required": true, "description": "The Unix timestamp (in seconds) for when the file was created." }, { "parameter": "expires_at", "type": "integer", "description": "The Unix timestamp (in seconds) for when the file will expire." }, { "parameter": "filename", "type": "string", "required": true, "description": "The name of the file." }, { "parameter": "object", "type": "string", "required": true, "enum": [ "file" ], "description": "The object type, which is always `file`." }, { "parameter": "purpose", "type": "string", "required": true, "enum": [ "assistants", "assistants_output", "batch", "batch_output", "fine-tune", "fine-tune-results", "vision", "user_data" ], "description": "The intended purpose of the file. Supported values are `assistants`, `assistants_output`, `batch`, `batch_output`, `fine-tune`, `fine-tune-results`, `vision`, and `user_data`." }, { "parameter": "status", "type": "string", "required": true, "enum": [ "uploaded", "processed", "error" ], "description": "Deprecated. The current status of the file, which can be either `uploaded`, `processed`, or `error`." }, { "parameter": "status_details", "type": "string", "description": "Deprecated. For details on why a fine-tuning training file failed validation, see the `error` field on `fine_tuning.job`." } ], "status": [ "DOCUMENTED" ], "verification": { "method": "docs_only" }, "sources": [ { "url": "https://developers.openai.com/api/reference/resources/files", "retrieved_at": "2026-09-18" }, { "url": "https://developers.openai.com/api/openapi (openapi-master.yaml)", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/openai-platform-objects.json" }, { "provider": "openai", "api_family": "uploads", "name": "Upload", "spec_schema": "Upload", "object_type": "upload", "description": "The Upload object can accept byte chunks in the form of Parts.", "required": [ "bytes", "created_at", "expires_at", "filename", "id", "purpose", "status" ], "fields": [ { "parameter": "id", "type": "string", "required": true, "description": "The Upload unique identifier, which can be referenced in API endpoints." }, { "parameter": "created_at", "type": "integer", "required": true, "description": "The Unix timestamp (in seconds) for when the Upload was created." }, { "parameter": "filename", "type": "string", "required": true, "description": "The name of the file to be uploaded." }, { "parameter": "bytes", "type": "integer", "required": true, "description": "The intended number of bytes to be uploaded." }, { "parameter": "purpose", "type": "string", "required": true, "description": "The intended purpose of the file. [Please refer here](https://developers.openai.com/api/reference/resources/files#%28resource%29%20files%20%3E%20%28model%29%20file_object%20%3E%20%28schema%29%20%3E%20%28property%29%20purpose) for acceptable values." }, { "parameter": "status", "type": "string", "required": true, "enum": [ "pending", "completed", "cancelled", "expired" ], "description": "The status of the Upload." }, { "parameter": "expires_at", "type": "integer", "required": true, "description": "The Unix timestamp (in seconds) for when the Upload will expire." }, { "parameter": "object", "type": "string", "enum": [ "upload" ], "description": "The object type, which is always \"upload\"." }, { "parameter": "file", "type": "object", "description": "" }, { "parameter": "file.id", "type": "string", "required": true, "description": "The file identifier, which can be referenced in the API endpoints." }, { "parameter": "file.bytes", "type": "integer", "required": true, "description": "The size of the file, in bytes." }, { "parameter": "file.created_at", "type": "integer", "required": true, "description": "The Unix timestamp (in seconds) for when the file was created." }, { "parameter": "file.expires_at", "type": "integer", "description": "The Unix timestamp (in seconds) for when the file will expire." }, { "parameter": "file.filename", "type": "string", "required": true, "description": "The name of the file." }, { "parameter": "file.object", "type": "string", "required": true, "enum": [ "file" ], "description": "The object type, which is always `file`." }, { "parameter": "file.purpose", "type": "string", "required": true, "enum": [ "assistants", "assistants_output", "batch", "batch_output", "fine-tune", "fine-tune-results", "vision", "user_data" ], "description": "The intended purpose of the file. Supported values are `assistants`, `assistants_output`, `batch`, `batch_output`, `fine-tune`, `fine-tune-results`, `vision`, and `user_data`." }, { "parameter": "file.status", "type": "string", "required": true, "enum": [ "uploaded", "processed", "error" ], "description": "Deprecated. The current status of the file, which can be either `uploaded`, `processed`, or `error`." }, { "parameter": "file.status_details", "type": "string", "description": "Deprecated. For details on why a fine-tuning training file failed validation, see the `error` field on `fine_tuning.job`." } ], "status": [ "DOCUMENTED" ], "verification": { "method": "docs_only" }, "sources": [ { "url": "https://developers.openai.com/api/reference/resources/uploads", "retrieved_at": "2026-09-18" }, { "url": "https://developers.openai.com/api/openapi (openapi-master.yaml)", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/openai-platform-objects.json" }, { "provider": "openai", "api_family": "uploads", "name": "UploadPart", "spec_schema": "UploadPart", "object_type": "upload.part", "description": "The upload Part represents a chunk of bytes we can add to an Upload object.", "required": [ "created_at", "id", "object", "upload_id" ], "fields": [ { "parameter": "id", "type": "string", "required": true, "description": "The upload Part unique identifier, which can be referenced in API endpoints." }, { "parameter": "created_at", "type": "integer", "required": true, "description": "The Unix timestamp (in seconds) for when the Part was created." }, { "parameter": "upload_id", "type": "string", "required": true, "description": "The ID of the Upload object that this Part was added to." }, { "parameter": "object", "type": "string", "required": true, "enum": [ "upload.part" ], "description": "The object type, which is always `upload.part`." } ], "status": [ "DOCUMENTED" ], "verification": { "method": "docs_only" }, "sources": [ { "url": "https://developers.openai.com/api/reference/resources/uploads", "retrieved_at": "2026-09-18" }, { "url": "https://developers.openai.com/api/openapi (openapi-master.yaml)", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/openai-platform-objects.json" }, { "provider": "openai", "api_family": "vector_stores", "name": "VectorStore", "spec_schema": "VectorStoreObject", "object_type": "vector_store", "description": "A vector store is a collection of processed files can be used by the `file_search` tool.", "required": [ "id", "object", "usage_bytes", "created_at", "status", "last_active_at", "name", "file_counts", "metadata" ], "fields": [ { "parameter": "id", "type": "string", "required": true, "description": "The identifier, which can be referenced in API endpoints." }, { "parameter": "object", "type": "string", "required": true, "enum": [ "vector_store" ], "description": "The object type, which is always `vector_store`." }, { "parameter": "created_at", "type": "integer", "required": true, "description": "The Unix timestamp (in seconds) for when the vector store was created." }, { "parameter": "name", "type": "string", "required": true, "description": "The name of the vector store." }, { "parameter": "usage_bytes", "type": "integer", "required": true, "description": "The total number of bytes used by the files in the vector store." }, { "parameter": "file_counts", "type": "object", "required": true, "description": "" }, { "parameter": "file_counts.in_progress", "type": "integer", "required": true, "description": "The number of files that are currently being processed." }, { "parameter": "file_counts.completed", "type": "integer", "required": true, "description": "The number of files that have been successfully processed." }, { "parameter": "file_counts.failed", "type": "integer", "required": true, "description": "The number of files that have failed to process." }, { "parameter": "file_counts.cancelled", "type": "integer", "required": true, "description": "The number of files that were cancelled." }, { "parameter": "file_counts.total", "type": "integer", "required": true, "description": "The total number of files." }, { "parameter": "status", "type": "string", "required": true, "enum": [ "expired", "in_progress", "completed" ], "description": "The status of the vector store, which can be either `expired`, `in_progress`, or `completed`. A status of `completed` indicates that the vector store is ready for use." }, { "parameter": "expires_after", "type": "object", "description": "The expiration policy for a vector store." }, { "parameter": "expires_after.anchor", "type": "string", "required": true, "enum": [ "last_active_at" ], "description": "Anchor timestamp after which the expiration policy applies. Supported anchors: `last_active_at`." }, { "parameter": "expires_after.days", "type": "integer", "required": true, "minimum": 1, "maximum": 365, "description": "The number of days after the anchor time that the vector store will expire." }, { "parameter": "expires_at", "type": "integer | null", "description": "" }, { "parameter": "last_active_at", "type": "integer | null", "required": true, "description": "" }, { "parameter": "metadata", "type": "object | null", "required": true, "description": "" } ], "status": [ "DOCUMENTED" ], "verification": { "method": "docs_only" }, "sources": [ { "url": "https://developers.openai.com/api/reference/resources/vector_stores", "retrieved_at": "2026-09-18" }, { "url": "https://developers.openai.com/api/openapi (openapi-master.yaml)", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/openai-platform-objects.json" }, { "provider": "openai", "api_family": "vector_stores", "name": "VectorStoreFile", "spec_schema": "VectorStoreFileObject", "object_type": "vector_store.file", "description": "A list of files attached to a vector store.", "required": [ "id", "object", "usage_bytes", "created_at", "vector_store_id", "status", "last_error" ], "fields": [ { "parameter": "id", "type": "string", "required": true, "description": "The identifier, which can be referenced in API endpoints." }, { "parameter": "object", "type": "string", "required": true, "enum": [ "vector_store.file" ], "description": "The object type, which is always `vector_store.file`." }, { "parameter": "usage_bytes", "type": "integer", "required": true, "description": "The total vector store usage in bytes. Note that this may be different from the original file size." }, { "parameter": "created_at", "type": "integer", "required": true, "description": "The Unix timestamp (in seconds) for when the vector store file was created." }, { "parameter": "vector_store_id", "type": "string", "required": true, "description": "The ID of the [vector store](https://developers.openai.com/api/reference/resources/vector_stores) that the [File](https://developers.openai.com/api/reference/resources/files) is attached to." }, { "parameter": "status", "type": "string", "required": true, "enum": [ "in_progress", "completed", "cancelled", "failed" ], "description": "The status of the vector store file, which can be either `in_progress`, `completed`, `cancelled`, or `failed`. The status `completed` indicates that the vector store file is ready for use." }, { "parameter": "last_error", "type": "object | null", "required": true, "description": "" }, { "parameter": "last_error.code", "type": "string", "required": true, "enum": [ "server_error", "unsupported_file", "invalid_file" ], "description": "One of `server_error`, `unsupported_file`, or `invalid_file`." }, { "parameter": "last_error.message", "type": "string", "required": true, "description": "A human-readable description of the error." }, { "parameter": "chunking_strategy", "type": "object", "description": "The strategy used to chunk the file." }, { "parameter": "chunking_strategy.type", "type": "string", "required": true, "enum": [ "static" ], "description": "Always `static`." }, { "parameter": "chunking_strategy.static", "type": "object", "required": true, "description": "" }, { "parameter": "chunking_strategy.static.max_chunk_size_tokens", "type": "integer", "required": true, "minimum": 100, "maximum": 4096, "description": "The maximum number of tokens in each chunk. The default value is `800`. The minimum value is `100` and the maximum value is `4096`." }, { "parameter": "chunking_strategy.static.chunk_overlap_tokens", "type": "integer", "required": true, "description": "The number of tokens that overlap between chunks. The default value is `400`.\n\nNote that the overlap must not exceed half of `max_chunk_size_tokens`." }, { "parameter": "chunking_strategy.type", "type": "string", "required": true, "enum": [ "other" ], "description": "Always `other`." }, { "parameter": "attributes", "type": "object | null", "description": "" } ], "status": [ "DOCUMENTED" ], "verification": { "method": "docs_only" }, "sources": [ { "url": "https://developers.openai.com/api/reference/resources/vector_stores", "retrieved_at": "2026-09-18" }, { "url": "https://developers.openai.com/api/openapi (openapi-master.yaml)", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/openai-platform-objects.json" }, { "provider": "openai", "api_family": "vector_stores", "name": "VectorStoreFileBatch", "spec_schema": "VectorStoreFileBatchObject", "object_type": "vector_store.files_batch", "description": "A batch of files attached to a vector store.", "required": [ "id", "object", "created_at", "vector_store_id", "status", "file_counts" ], "fields": [ { "parameter": "id", "type": "string", "required": true, "description": "The identifier, which can be referenced in API endpoints." }, { "parameter": "object", "type": "string", "required": true, "enum": [ "vector_store.files_batch" ], "description": "The object type, which is always `vector_store.file_batch`." }, { "parameter": "created_at", "type": "integer", "required": true, "description": "The Unix timestamp (in seconds) for when the vector store files batch was created." }, { "parameter": "vector_store_id", "type": "string", "required": true, "description": "The ID of the [vector store](https://developers.openai.com/api/reference/resources/vector_stores) that the [File](https://developers.openai.com/api/reference/resources/files) is attached to." }, { "parameter": "status", "type": "string", "required": true, "enum": [ "in_progress", "completed", "cancelled", "failed" ], "description": "The status of the vector store files batch, which can be either `in_progress`, `completed`, `cancelled` or `failed`." }, { "parameter": "file_counts", "type": "object", "required": true, "description": "" }, { "parameter": "file_counts.in_progress", "type": "integer", "required": true, "description": "The number of files that are currently being processed." }, { "parameter": "file_counts.completed", "type": "integer", "required": true, "description": "The number of files that have been processed." }, { "parameter": "file_counts.failed", "type": "integer", "required": true, "description": "The number of files that have failed to process." }, { "parameter": "file_counts.cancelled", "type": "integer", "required": true, "description": "The number of files that where cancelled." }, { "parameter": "file_counts.total", "type": "integer", "required": true, "description": "The total number of files." } ], "status": [ "DOCUMENTED" ], "verification": { "method": "docs_only" }, "sources": [ { "url": "https://developers.openai.com/api/reference/resources/vector_stores", "retrieved_at": "2026-09-18" }, { "url": "https://developers.openai.com/api/openapi (openapi-master.yaml)", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/openai-platform-objects.json" }, { "provider": "openai", "api_family": "vector_stores", "name": "VectorStoreSearchResultsPage", "spec_schema": "VectorStoreSearchResultsPage", "object_type": "vector_store.search_results.page", "description": "", "required": [ "object", "search_query", "data", "has_more", "next_page" ], "fields": [ { "parameter": "object", "type": "string", "required": true, "enum": [ "vector_store.search_results.page" ], "description": "The object type, which is always `vector_store.search_results.page`" }, { "parameter": "search_query", "type": "array", "required": true, "description": "" }, { "parameter": "data", "type": "array", "required": true, "description": "The list of search result items." }, { "parameter": "data[].file_id", "type": "string", "required": true, "description": "The ID of the vector store file." }, { "parameter": "data[].filename", "type": "string", "required": true, "description": "The name of the vector store file." }, { "parameter": "data[].score", "type": "number", "required": true, "maximum": 1, "description": "The similarity score for the result." }, { "parameter": "data[].attributes", "type": "object | null", "required": true, "description": "" }, { "parameter": "data[].content", "type": "array", "required": true, "description": "Content chunks from the file." }, { "parameter": "data[].content[].type", "type": "string", "required": true, "enum": [ "text" ], "description": "The type of content." }, { "parameter": "data[].content[].text", "type": "string", "required": true, "description": "The text content returned from search." }, { "parameter": "has_more", "type": "boolean", "required": true, "description": "Indicates if there are more results to fetch." }, { "parameter": "next_page", "type": "string | null", "required": true, "description": "" } ], "status": [ "DOCUMENTED" ], "verification": { "method": "docs_only" }, "sources": [ { "url": "https://developers.openai.com/api/reference/resources/vector_stores", "retrieved_at": "2026-09-18" }, { "url": "https://developers.openai.com/api/openapi (openapi-master.yaml)", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/openai-platform-objects.json" }, { "provider": "openai", "api_family": "vector_stores", "name": "VectorStoreFileContentPage", "spec_schema": "VectorStoreFileContentResponse", "object_type": "vector_store.file_content.page", "description": "Represents the parsed content of a vector store file.", "required": [ "object", "data", "has_more", "next_page" ], "fields": [ { "parameter": "object", "type": "string", "required": true, "enum": [ "vector_store.file_content.page" ], "description": "The object type, which is always `vector_store.file_content.page`" }, { "parameter": "data", "type": "array", "required": true, "description": "Parsed content of the file." }, { "parameter": "data[].type", "type": "string", "description": "The content type (currently only `\"text\"`)" }, { "parameter": "data[].text", "type": "string", "description": "The text content" }, { "parameter": "has_more", "type": "boolean", "required": true, "description": "Indicates if there are more content pages to fetch." }, { "parameter": "next_page", "type": "string | null", "required": true, "description": "" } ], "status": [ "DOCUMENTED" ], "verification": { "method": "docs_only" }, "sources": [ { "url": "https://developers.openai.com/api/reference/resources/vector_stores", "retrieved_at": "2026-09-18" }, { "url": "https://developers.openai.com/api/openapi (openapi-master.yaml)", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/openai-platform-objects.json" }, { "provider": "openai", "api_family": "batches", "name": "Batch", "spec_schema": "Batch", "object_type": "batch", "description": "", "required": [ "id", "object", "endpoint", "input_file_id", "completion_window", "status", "created_at" ], "fields": [ { "parameter": "id", "type": "string", "required": true, "description": "" }, { "parameter": "object", "type": "string", "required": true, "enum": [ "batch" ], "description": "The object type, which is always `batch`." }, { "parameter": "endpoint", "type": "string", "required": true, "description": "The OpenAI API endpoint used by the batch." }, { "parameter": "model", "type": "string", "description": "Model ID used to process the batch, like `gpt-6-astra`. OpenAI\noffers a wide range of models with different capabilities, performance\ncharacteristics, and price points. Refer to the [model\nguide](https://developers.openai.com/api/docs/models) to browse and compare available models." }, { "parameter": "errors", "type": "object", "description": "" }, { "parameter": "errors.object", "type": "string", "description": "The object type, which is always `list`." }, { "parameter": "errors.data", "type": "array", "description": "" }, { "parameter": "errors.data[].code", "type": "string", "description": "An error code identifying the error type." }, { "parameter": "errors.data[].message", "type": "string", "description": "A human-readable message providing more details about the error." }, { "parameter": "errors.data[].param", "type": "string | null", "description": "" }, { "parameter": "errors.data[].line", "type": "integer | null", "description": "" }, { "parameter": "input_file_id", "type": "string", "required": true, "description": "The ID of the input file for the batch." }, { "parameter": "completion_window", "type": "string", "required": true, "description": "The time frame within which the batch should be processed." }, { "parameter": "status", "type": "string", "required": true, "enum": [ "validating", "failed", "in_progress", "finalizing", "completed", "expired", "cancelling", "cancelled" ], "description": "The current status of the batch." }, { "parameter": "output_file_id", "type": "string", "description": "The ID of the file containing the outputs of successfully executed requests." }, { "parameter": "error_file_id", "type": "string", "description": "The ID of the file containing the outputs of requests with errors." }, { "parameter": "created_at", "type": "integer", "required": true, "description": "The Unix timestamp (in seconds) for when the batch was created." }, { "parameter": "in_progress_at", "type": "integer", "description": "The Unix timestamp (in seconds) for when the batch started processing." }, { "parameter": "expires_at", "type": "integer", "description": "The Unix timestamp (in seconds) for when the batch will expire." }, { "parameter": "finalizing_at", "type": "integer", "description": "The Unix timestamp (in seconds) for when the batch started finalizing." }, { "parameter": "completed_at", "type": "integer", "description": "The Unix timestamp (in seconds) for when the batch was completed." }, { "parameter": "failed_at", "type": "integer", "description": "The Unix timestamp (in seconds) for when the batch failed." }, { "parameter": "expired_at", "type": "integer", "description": "The Unix timestamp (in seconds) for when the batch expired." }, { "parameter": "cancelling_at", "type": "integer", "description": "The Unix timestamp (in seconds) for when the batch started cancelling." }, { "parameter": "cancelled_at", "type": "integer", "description": "The Unix timestamp (in seconds) for when the batch was cancelled." }, { "parameter": "request_counts", "type": "object", "description": "The request counts for different statuses within the batch." }, { "parameter": "request_counts.total", "type": "integer", "required": true, "description": "Total number of requests in the batch." }, { "parameter": "request_counts.completed", "type": "integer", "required": true, "description": "Number of requests that have been completed successfully." }, { "parameter": "request_counts.failed", "type": "integer", "required": true, "description": "Number of requests that have failed." }, { "parameter": "usage", "type": "object", "description": "Represents token usage details including input tokens, output tokens, a\nbreakdown of output tokens, and the total tokens used. Only populated on\nbatches created after September 7, 2025." }, { "parameter": "usage.input_tokens", "type": "integer", "required": true, "description": "The number of input tokens." }, { "parameter": "usage.input_tokens_details", "type": "object", "required": true, "description": "A detailed breakdown of the input tokens." }, { "parameter": "usage.input_tokens_details.cached_tokens", "type": "integer", "required": true, "description": "The number of tokens that were retrieved from the cache. [More on\nprompt caching](https://developers.openai.com/api/docs/guides/prompt-caching)." }, { "parameter": "usage.output_tokens", "type": "integer", "required": true, "description": "The number of output tokens." }, { "parameter": "usage.output_tokens_details", "type": "object", "required": true, "description": "A detailed breakdown of the output tokens." }, { "parameter": "usage.output_tokens_details.reasoning_tokens", "type": "integer", "required": true, "description": "The number of reasoning tokens." }, { "parameter": "usage.total_tokens", "type": "integer", "required": true, "description": "The total number of tokens used." }, { "parameter": "metadata", "type": "object | null", "description": "" } ], "status": [ "DOCUMENTED" ], "verification": { "method": "docs_only" }, "sources": [ { "url": "https://developers.openai.com/api/reference/resources/batches", "retrieved_at": "2026-09-18" }, { "url": "https://developers.openai.com/api/openapi (openapi-master.yaml)", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/openai-platform-objects.json" }, { "provider": "openai", "api_family": "batches", "name": "BatchRequestCounts", "spec_schema": "BatchRequestCounts", "object_type": null, "description": "The request counts for different statuses within the batch.", "required": [ "total", "completed", "failed" ], "fields": [ { "parameter": "total", "type": "integer", "required": true, "description": "Total number of requests in the batch." }, { "parameter": "completed", "type": "integer", "required": true, "description": "Number of requests that have been completed successfully." }, { "parameter": "failed", "type": "integer", "required": true, "description": "Number of requests that have failed." } ], "status": [ "DOCUMENTED" ], "verification": { "method": "docs_only" }, "sources": [ { "url": "https://developers.openai.com/api/reference/resources/batches", "retrieved_at": "2026-09-18" }, { "url": "https://developers.openai.com/api/openapi (openapi-master.yaml)", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/openai-platform-objects.json" }, { "provider": "openai", "api_family": "batches", "name": "BatchError", "spec_schema": "BatchError", "object_type": null, "description": "", "required": [], "fields": [ { "parameter": "code", "type": "string", "description": "An error code identifying the error type." }, { "parameter": "message", "type": "string", "description": "A human-readable message providing more details about the error." }, { "parameter": "param", "type": "string | null", "description": "" }, { "parameter": "line", "type": "integer | null", "description": "" } ], "status": [ "DOCUMENTED" ], "verification": { "method": "docs_only" }, "sources": [ { "url": "https://developers.openai.com/api/reference/resources/batches", "retrieved_at": "2026-09-18" }, { "url": "https://developers.openai.com/api/openapi (openapi-master.yaml)", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/openai-platform-objects.json" }, { "provider": "openai", "api_family": "fine_tuning", "name": "FineTuningJob", "spec_schema": "FineTuningJob", "object_type": "fine_tuning.job", "description": "The `fine_tuning.job` object represents a fine-tuning job that has been created through the API.", "required": [ "created_at", "error", "finished_at", "fine_tuned_model", "hyperparameters", "id", "model", "object", "organization_id", "result_files", "status", "trained_tokens", "training_file", "validation_file", "seed" ], "fields": [ { "parameter": "id", "type": "string", "required": true, "description": "The object identifier, which can be referenced in the API endpoints." }, { "parameter": "created_at", "type": "integer", "required": true, "description": "The Unix timestamp (in seconds) for when the fine-tuning job was created." }, { "parameter": "error", "type": "object | null", "required": true, "description": "" }, { "parameter": "error.code", "type": "string", "required": true, "description": "A machine-readable error code." }, { "parameter": "error.message", "type": "string", "required": true, "description": "A human-readable error message." }, { "parameter": "error.param", "type": "string | null", "required": true, "description": "" }, { "parameter": "fine_tuned_model", "type": "string | null", "required": true, "description": "" }, { "parameter": "finished_at", "type": "integer | null", "required": true, "description": "" }, { "parameter": "hyperparameters", "type": "object", "required": true, "description": "The hyperparameters used for the fine-tuning job. This value will only be returned when running `supervised` jobs." }, { "parameter": "hyperparameters.batch_size", "type": "object | null", "description": "" }, { "parameter": "hyperparameters.learning_rate_multiplier", "type": "string | number", "default": "auto", "description": "Scaling factor for the learning rate. A smaller learning rate may be useful to avoid\noverfitting." }, { "parameter": "hyperparameters.n_epochs", "type": "string | integer", "default": "auto", "description": "The number of epochs to train the model for. An epoch refers to one full cycle\nthrough the training dataset." }, { "parameter": "model", "type": "string", "required": true, "description": "The base model that is being fine-tuned." }, { "parameter": "object", "type": "string", "required": true, "enum": [ "fine_tuning.job" ], "description": "The object type, which is always \"fine_tuning.job\"." }, { "parameter": "organization_id", "type": "string", "required": true, "description": "The organization that owns the fine-tuning job." }, { "parameter": "result_files", "type": "array", "required": true, "description": "The compiled results file ID(s) for the fine-tuning job. You can retrieve the results with the [Files API](https://developers.openai.com/api/reference/resources/files/methods/content)." }, { "parameter": "status", "type": "string", "required": true, "enum": [ "validating_files", "queued", "running", "succeeded", "failed", "cancelled" ], "description": "The current status of the fine-tuning job, which can be either `validating_files`, `queued`, `running`, `succeeded`, `failed`, or `cancelled`." }, { "parameter": "trained_tokens", "type": "integer | null", "required": true, "description": "" }, { "parameter": "training_file", "type": "string", "required": true, "description": "The file ID used for training. You can retrieve the training data with the [Files API](https://developers.openai.com/api/reference/resources/files/methods/content)." }, { "parameter": "validation_file", "type": "string | null", "required": true, "description": "" }, { "parameter": "integrations", "type": "array | null", "description": "" }, { "parameter": "seed", "type": "integer", "required": true, "description": "The seed used for the fine-tuning job." }, { "parameter": "estimated_finish", "type": "integer | null", "description": "" }, { "parameter": "method", "type": "object", "description": "The method used for fine-tuning." }, { "parameter": "method.type", "type": "string", "required": true, "enum": [ "supervised", "dpo", "reinforcement" ], "description": "The type of method. Is either `supervised`, `dpo`, or `reinforcement`." }, { "parameter": "method.supervised", "type": "object", "description": "Configuration for the supervised fine-tuning method." }, { "parameter": "method.supervised.hyperparameters", "type": "object", "description": "The hyperparameters used for the fine-tuning job." }, { "parameter": "method.supervised.hyperparameters.batch_size", "type": "string | integer", "default": "auto", "description": "Number of examples in each batch. A larger batch size means that model parameters are updated less frequently, but with lower variance." }, { "parameter": "method.supervised.hyperparameters.learning_rate_multiplier", "type": "string | number", "default": "auto", "description": "Scaling factor for the learning rate. A smaller learning rate may be useful to avoid overfitting." }, { "parameter": "method.supervised.hyperparameters.n_epochs", "type": "string | integer", "default": "auto", "description": "The number of epochs to train the model for. An epoch refers to one full cycle through the training dataset." }, { "parameter": "method.dpo", "type": "object", "description": "Configuration for the DPO fine-tuning method." }, { "parameter": "method.dpo.hyperparameters", "type": "object", "description": "The hyperparameters used for the DPO fine-tuning job." }, { "parameter": "method.dpo.hyperparameters.beta", "type": "string | number", "default": "auto", "description": "The beta value for the DPO method. A higher beta value will increase the weight of the penalty between the policy and reference model." }, { "parameter": "method.dpo.hyperparameters.batch_size", "type": "string | integer", "default": "auto", "description": "Number of examples in each batch. A larger batch size means that model parameters are updated less frequently, but with lower variance." }, { "parameter": "method.dpo.hyperparameters.learning_rate_multiplier", "type": "string | number", "default": "auto", "description": "Scaling factor for the learning rate. A smaller learning rate may be useful to avoid overfitting." }, { "parameter": "method.dpo.hyperparameters.n_epochs", "type": "string | integer", "default": "auto", "description": "The number of epochs to train the model for. An epoch refers to one full cycle through the training dataset." }, { "parameter": "method.reinforcement", "type": "object", "description": "Configuration for the reinforcement fine-tuning method." }, { "parameter": "method.reinforcement.grader", "type": "object", "required": true, "description": "The grader used for the fine-tuning job." }, { "parameter": "method.reinforcement.grader.type", "type": "string", "required": true, "enum": [ "string_check" ], "description": "The object type, which is always `string_check`." }, { "parameter": "method.reinforcement.grader.name", "type": "string", "required": true, "description": "The name of the grader." }, { "parameter": "method.reinforcement.grader.input", "type": "string", "required": true, "description": "The input text. This may include template strings." }, { "parameter": "method.reinforcement.grader.reference", "type": "string", "required": true, "description": "The reference text. This may include template strings." }, { "parameter": "method.reinforcement.grader.operation", "type": "string", "required": true, "enum": [ "eq", "ne", "like", "ilike" ], "description": "The string check operation to perform. One of `eq`, `ne`, `like`, or `ilike`." }, { "parameter": "method.reinforcement.grader.type", "type": "string", "required": true, "enum": [ "text_similarity" ], "default": "text_similarity", "description": "The type of grader." }, { "parameter": "method.reinforcement.grader.name", "type": "string", "required": true, "description": "The name of the grader." }, { "parameter": "method.reinforcement.grader.input", "type": "string", "required": true, "description": "The text being graded." }, { "parameter": "method.reinforcement.grader.reference", "type": "string", "required": true, "description": "The text being graded against." }, { "parameter": "method.reinforcement.grader.evaluation_metric", "type": "string", "required": true, "enum": [ "cosine", "fuzzy_match", "bleu", "gleu", "meteor", "rouge_1", "rouge_2", "rouge_3", "rouge_4", "rouge_5", "rouge_l" ], "description": "The evaluation metric to use. One of `cosine`, `fuzzy_match`, `bleu`, \n`gleu`, `meteor`, `rouge_1`, `rouge_2`, `rouge_3`, `rouge_4`, `rouge_5`, \nor `rouge_l`." }, { "parameter": "method.reinforcement.grader.type", "type": "string", "required": true, "enum": [ "python" ], "description": "The object type, which is always `python`." }, { "parameter": "method.reinforcement.grader.name", "type": "string", "required": true, "description": "The name of the grader." }, { "parameter": "method.reinforcement.grader.source", "type": "string", "required": true, "description": "The source code of the python script." }, { "parameter": "method.reinforcement.grader.image_tag", "type": "string", "description": "The image tag to use for the python script." }, { "parameter": "method.reinforcement.grader.type", "type": "string", "required": true, "enum": [ "score_model" ], "description": "The object type, which is always `score_model`." }, { "parameter": "method.reinforcement.grader.name", "type": "string", "required": true, "description": "The name of the grader." }, { "parameter": "method.reinforcement.grader.model", "type": "string", "required": true, "description": "The model to use for the evaluation." }, { "parameter": "method.reinforcement.grader.sampling_params", "type": "object", "description": "The sampling parameters for the model." }, { "parameter": "method.reinforcement.grader.input", "type": "array", "required": true, "description": "The input messages evaluated by the grader. Supports text, output text, input image, and input audio content blocks, and may include template strings." }, { "parameter": "method.reinforcement.grader.range", "type": "array", "description": "The range of the score. Defaults to `[0, 1]`." }, { "parameter": "method.reinforcement.grader.type", "type": "string", "required": true, "enum": [ "multi" ], "default": "multi", "description": "The object type, which is always `multi`." }, { "parameter": "method.reinforcement.grader.name", "type": "string", "required": true, "description": "The name of the grader." }, { "parameter": "method.reinforcement.grader.graders", "type": "GraderStringCheck | GraderTextSimilarity | GraderPython | GraderScoreModel | GraderLabelModel", "required": true, "description": "" }, { "parameter": "method.reinforcement.grader.calculate_output", "type": "string", "required": true, "description": "A formula to calculate the output based on grader results." }, { "parameter": "method.reinforcement.hyperparameters", "type": "object", "description": "The hyperparameters used for the reinforcement fine-tuning job." }, { "parameter": "method.reinforcement.hyperparameters.batch_size", "type": "string | integer", "default": "auto", "description": "Number of examples in each batch. A larger batch size means that model parameters are updated less frequently, but with lower variance." }, { "parameter": "method.reinforcement.hyperparameters.learning_rate_multiplier", "type": "string | number", "default": "auto", "description": "Scaling factor for the learning rate. A smaller learning rate may be useful to avoid overfitting." }, { "parameter": "method.reinforcement.hyperparameters.n_epochs", "type": "string | integer", "default": "auto", "description": "The number of epochs to train the model for. An epoch refers to one full cycle through the training dataset." }, { "parameter": "method.reinforcement.hyperparameters.reasoning_effort", "type": "string", "enum": [ "default", "low", "medium", "high" ], "default": "default", "description": "Level of reasoning effort." }, { "parameter": "method.reinforcement.hyperparameters.compute_multiplier", "type": "string | number", "default": "auto", "description": "Multiplier on amount of compute used for exploring search space during training." }, { "parameter": "method.reinforcement.hyperparameters.eval_interval", "type": "string | integer", "default": "auto", "description": "The number of training steps between evaluation runs." }, { "parameter": "method.reinforcement.hyperparameters.eval_samples", "type": "string | integer", "default": "auto", "description": "Number of evaluation samples to generate per training step." }, { "parameter": "metadata", "type": "object | null", "description": "" } ], "status": [ "DOCUMENTED", "DEPRECATED" ], "verification": { "method": "docs_only" }, "sources": [ { "url": "https://developers.openai.com/api/reference/resources/fine_tuning", "retrieved_at": "2026-09-18" }, { "url": "https://developers.openai.com/api/openapi (openapi-master.yaml)", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/openai-platform-objects.json" }, { "provider": "openai", "api_family": "fine_tuning", "name": "FineTuningJobEvent", "spec_schema": "FineTuningJobEvent", "object_type": "fine_tuning.job.event", "description": "Fine-tuning job event object", "required": [ "id", "object", "created_at", "level", "message" ], "fields": [ { "parameter": "object", "type": "string", "required": true, "enum": [ "fine_tuning.job.event" ], "description": "The object type, which is always \"fine_tuning.job.event\"." }, { "parameter": "id", "type": "string", "required": true, "description": "The object identifier." }, { "parameter": "created_at", "type": "integer", "required": true, "description": "The Unix timestamp (in seconds) for when the fine-tuning job was created." }, { "parameter": "level", "type": "string", "required": true, "enum": [ "info", "warn", "error" ], "description": "The log level of the event." }, { "parameter": "message", "type": "string", "required": true, "description": "The message of the event." }, { "parameter": "type", "type": "string", "enum": [ "message", "metrics" ], "description": "The type of event." }, { "parameter": "data", "type": "object", "description": "The data associated with the event." } ], "status": [ "DOCUMENTED", "DEPRECATED" ], "verification": { "method": "docs_only" }, "sources": [ { "url": "https://developers.openai.com/api/reference/resources/fine_tuning", "retrieved_at": "2026-09-18" }, { "url": "https://developers.openai.com/api/openapi (openapi-master.yaml)", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/openai-platform-objects.json" }, { "provider": "openai", "api_family": "fine_tuning", "name": "FineTuningJobCheckpoint", "spec_schema": "FineTuningJobCheckpoint", "object_type": "fine_tuning.job.checkpoint", "description": "The `fine_tuning.job.checkpoint` object represents a model checkpoint for a fine-tuning job that is ready to use.", "required": [ "created_at", "fine_tuning_job_id", "fine_tuned_model_checkpoint", "id", "metrics", "object", "step_number" ], "fields": [ { "parameter": "id", "type": "string", "required": true, "description": "The checkpoint identifier, which can be referenced in the API endpoints." }, { "parameter": "created_at", "type": "integer", "required": true, "description": "The Unix timestamp (in seconds) for when the checkpoint was created." }, { "parameter": "fine_tuned_model_checkpoint", "type": "string", "required": true, "description": "The name of the fine-tuned checkpoint model that is created." }, { "parameter": "step_number", "type": "integer", "required": true, "description": "The step number that the checkpoint was created at." }, { "parameter": "metrics", "type": "object", "required": true, "description": "Metrics at the step number during the fine-tuning job." }, { "parameter": "metrics.step", "type": "number", "description": "" }, { "parameter": "metrics.train_loss", "type": "number", "description": "" }, { "parameter": "metrics.train_mean_token_accuracy", "type": "number", "description": "" }, { "parameter": "metrics.valid_loss", "type": "number", "description": "" }, { "parameter": "metrics.valid_mean_token_accuracy", "type": "number", "description": "" }, { "parameter": "metrics.full_valid_loss", "type": "number", "description": "" }, { "parameter": "metrics.full_valid_mean_token_accuracy", "type": "number", "description": "" }, { "parameter": "fine_tuning_job_id", "type": "string", "required": true, "description": "The name of the fine-tuning job that this checkpoint was created from." }, { "parameter": "object", "type": "string", "required": true, "enum": [ "fine_tuning.job.checkpoint" ], "description": "The object type, which is always \"fine_tuning.job.checkpoint\"." } ], "status": [ "DOCUMENTED", "DEPRECATED" ], "verification": { "method": "docs_only" }, "sources": [ { "url": "https://developers.openai.com/api/reference/resources/fine_tuning", "retrieved_at": "2026-09-18" }, { "url": "https://developers.openai.com/api/openapi (openapi-master.yaml)", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/openai-platform-objects.json" }, { "provider": "openai", "api_family": "fine_tuning", "name": "CheckpointPermission", "spec_schema": "FineTuningCheckpointPermission", "object_type": "checkpoint.permission", "description": "The `checkpoint.permission` object represents a permission for a fine-tuned model checkpoint.", "required": [ "created_at", "id", "object", "project_id" ], "fields": [ { "parameter": "id", "type": "string", "required": true, "description": "The permission identifier, which can be referenced in the API endpoints." }, { "parameter": "created_at", "type": "integer", "required": true, "description": "The Unix timestamp (in seconds) for when the permission was created." }, { "parameter": "project_id", "type": "string", "required": true, "description": "The project identifier that the permission is for." }, { "parameter": "object", "type": "string", "required": true, "enum": [ "checkpoint.permission" ], "description": "The object type, which is always \"checkpoint.permission\"." } ], "status": [ "DOCUMENTED", "DEPRECATED" ], "verification": { "method": "docs_only" }, "sources": [ { "url": "https://developers.openai.com/api/reference/resources/fine_tuning", "retrieved_at": "2026-09-18" }, { "url": "https://developers.openai.com/api/openapi (openapi-master.yaml)", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/openai-platform-objects.json" }, { "provider": "openai", "api_family": "graders", "name": "GraderStringCheck", "spec_schema": "GraderStringCheck", "object_type": null, "description": "A StringCheckGrader object that performs a string comparison between input and reference using a specified operation.", "required": [ "type", "name", "input", "reference", "operation" ], "fields": [ { "parameter": "type", "type": "string", "required": true, "enum": [ "string_check" ], "description": "The object type, which is always `string_check`." }, { "parameter": "name", "type": "string", "required": true, "description": "The name of the grader." }, { "parameter": "input", "type": "string", "required": true, "description": "The input text. This may include template strings." }, { "parameter": "reference", "type": "string", "required": true, "description": "The reference text. This may include template strings." }, { "parameter": "operation", "type": "string", "required": true, "enum": [ "eq", "ne", "like", "ilike" ], "description": "The string check operation to perform. One of `eq`, `ne`, `like`, or `ilike`." } ], "status": [ "DOCUMENTED", "DEPRECATED" ], "verification": { "method": "docs_only" }, "sources": [ { "url": "https://developers.openai.com/api/reference/resources/graders", "retrieved_at": "2026-09-18" }, { "url": "https://developers.openai.com/api/openapi (openapi-master.yaml)", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/openai-platform-objects.json" }, { "provider": "openai", "api_family": "graders", "name": "GraderTextSimilarity", "spec_schema": "GraderTextSimilarity", "object_type": null, "description": "A TextSimilarityGrader object which grades text based on similarity metrics.", "required": [ "type", "name", "input", "reference", "evaluation_metric" ], "fields": [ { "parameter": "type", "type": "string", "required": true, "enum": [ "text_similarity" ], "default": "text_similarity", "description": "The type of grader." }, { "parameter": "name", "type": "string", "required": true, "description": "The name of the grader." }, { "parameter": "input", "type": "string", "required": true, "description": "The text being graded." }, { "parameter": "reference", "type": "string", "required": true, "description": "The text being graded against." }, { "parameter": "evaluation_metric", "type": "string", "required": true, "enum": [ "cosine", "fuzzy_match", "bleu", "gleu", "meteor", "rouge_1", "rouge_2", "rouge_3", "rouge_4", "rouge_5", "rouge_l" ], "description": "The evaluation metric to use. One of `cosine`, `fuzzy_match`, `bleu`, \n`gleu`, `meteor`, `rouge_1`, `rouge_2`, `rouge_3`, `rouge_4`, `rouge_5`, \nor `rouge_l`." } ], "status": [ "DOCUMENTED", "DEPRECATED" ], "verification": { "method": "docs_only" }, "sources": [ { "url": "https://developers.openai.com/api/reference/resources/graders", "retrieved_at": "2026-09-18" }, { "url": "https://developers.openai.com/api/openapi (openapi-master.yaml)", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/openai-platform-objects.json" }, { "provider": "openai", "api_family": "graders", "name": "GraderScoreModel", "spec_schema": "GraderScoreModel", "object_type": null, "description": "A ScoreModelGrader object that uses a model to assign a score to the input.", "required": [ "type", "name", "input", "model" ], "fields": [ { "parameter": "type", "type": "string", "required": true, "enum": [ "score_model" ], "description": "The object type, which is always `score_model`." }, { "parameter": "name", "type": "string", "required": true, "description": "The name of the grader." }, { "parameter": "model", "type": "string", "required": true, "description": "The model to use for the evaluation." }, { "parameter": "sampling_params", "type": "object", "description": "The sampling parameters for the model." }, { "parameter": "sampling_params.seed", "type": "integer | null", "description": "" }, { "parameter": "sampling_params.top_p", "type": "number | null", "description": "" }, { "parameter": "sampling_params.temperature", "type": "number | null", "description": "" }, { "parameter": "sampling_params.max_completions_tokens", "type": "integer | null", "description": "" }, { "parameter": "sampling_params.reasoning_effort", "type": "string | null", "description": "" }, { "parameter": "input", "type": "array", "required": true, "description": "The input messages evaluated by the grader. Supports text, output text, input image, and input audio content blocks, and may include template strings." }, { "parameter": "input[].role", "type": "string", "required": true, "enum": [ "user", "assistant", "system", "developer" ], "description": "The role of the message input. One of `user`, `assistant`, `system`, or\n`developer`." }, { "parameter": "input[].content", "type": "EvalItemContentItem | array", "required": true, "description": "Inputs to the model - can contain template strings. Supports text, output text, input images, and input audio, either as a single item or an array of items." }, { "parameter": "input[].content.type", "type": "string", "required": true, "enum": [ "input_text" ], "default": "input_text", "description": "The type of the input item. Always `input_text`." }, { "parameter": "input[].content.text", "type": "string", "required": true, "description": "The text input to the model." }, { "parameter": "input[].content.prompt_cache_breakpoint", "type": "object", "description": "" }, { "parameter": "input[].content.type", "type": "string", "required": true, "enum": [ "output_text" ], "description": "The type of the output text. Always `output_text`." }, { "parameter": "input[].content.text", "type": "string", "required": true, "description": "The text output from the model." }, { "parameter": "input[].content.type", "type": "string", "required": true, "enum": [ "input_image" ], "description": "The type of the image input. Always `input_image`." }, { "parameter": "input[].content.image_url", "type": "string", "required": true, "description": "The URL of the image input." }, { "parameter": "input[].content.detail", "type": "string", "description": "The detail level of the image to be sent to the model. One of `high`, `low`, or `auto`. Defaults to `auto`." }, { "parameter": "input[].content.type", "type": "string", "required": true, "enum": [ "input_audio" ], "description": "The type of the input item. Always `input_audio`." }, { "parameter": "input[].content.input_audio", "type": "object", "required": true, "description": "" }, { "parameter": "input[].content.input_audio.data", "type": "string", "required": true, "description": "Base64-encoded audio data." }, { "parameter": "input[].content.input_audio.format", "type": "string", "required": true, "enum": [ "mp3", "wav" ], "description": "The format of the audio data. Currently supported formats are `mp3` and\n`wav`." }, { "parameter": "input[].type", "type": "string", "enum": [ "message" ], "description": "The type of the message input. Always `message`." }, { "parameter": "range", "type": "array", "description": "The range of the score. Defaults to `[0, 1]`." } ], "status": [ "DOCUMENTED", "DEPRECATED" ], "verification": { "method": "docs_only" }, "sources": [ { "url": "https://developers.openai.com/api/reference/resources/graders", "retrieved_at": "2026-09-18" }, { "url": "https://developers.openai.com/api/openapi (openapi-master.yaml)", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/openai-platform-objects.json" }, { "provider": "openai", "api_family": "graders", "name": "GraderLabelModel", "spec_schema": "GraderLabelModel", "object_type": null, "description": "A LabelModelGrader object which uses a model to assign labels to each item\nin the evaluation.", "required": [ "type", "model", "input", "passing_labels", "labels", "name" ], "fields": [ { "parameter": "type", "type": "string", "required": true, "enum": [ "label_model" ], "description": "The object type, which is always `label_model`." }, { "parameter": "name", "type": "string", "required": true, "description": "The name of the grader." }, { "parameter": "model", "type": "string", "required": true, "description": "The model to use for the evaluation. Must support structured outputs." }, { "parameter": "input", "type": "array", "required": true, "description": "" }, { "parameter": "input[].role", "type": "string", "required": true, "enum": [ "user", "assistant", "system", "developer" ], "description": "The role of the message input. One of `user`, `assistant`, `system`, or\n`developer`." }, { "parameter": "input[].content", "type": "EvalItemContentItem | array", "required": true, "description": "Inputs to the model - can contain template strings. Supports text, output text, input images, and input audio, either as a single item or an array of items." }, { "parameter": "input[].content.type", "type": "string", "required": true, "enum": [ "input_text" ], "default": "input_text", "description": "The type of the input item. Always `input_text`." }, { "parameter": "input[].content.text", "type": "string", "required": true, "description": "The text input to the model." }, { "parameter": "input[].content.prompt_cache_breakpoint", "type": "object", "description": "" }, { "parameter": "input[].content.type", "type": "string", "required": true, "enum": [ "output_text" ], "description": "The type of the output text. Always `output_text`." }, { "parameter": "input[].content.text", "type": "string", "required": true, "description": "The text output from the model." }, { "parameter": "input[].content.type", "type": "string", "required": true, "enum": [ "input_image" ], "description": "The type of the image input. Always `input_image`." }, { "parameter": "input[].content.image_url", "type": "string", "required": true, "description": "The URL of the image input." }, { "parameter": "input[].content.detail", "type": "string", "description": "The detail level of the image to be sent to the model. One of `high`, `low`, or `auto`. Defaults to `auto`." }, { "parameter": "input[].content.type", "type": "string", "required": true, "enum": [ "input_audio" ], "description": "The type of the input item. Always `input_audio`." }, { "parameter": "input[].content.input_audio", "type": "object", "required": true, "description": "" }, { "parameter": "input[].content.input_audio.data", "type": "string", "required": true, "description": "Base64-encoded audio data." }, { "parameter": "input[].content.input_audio.format", "type": "string", "required": true, "enum": [ "mp3", "wav" ], "description": "The format of the audio data. Currently supported formats are `mp3` and\n`wav`." }, { "parameter": "input[].type", "type": "string", "enum": [ "message" ], "description": "The type of the message input. Always `message`." }, { "parameter": "labels", "type": "array", "required": true, "description": "The labels to assign to each item in the evaluation." }, { "parameter": "passing_labels", "type": "array", "required": true, "description": "The labels that indicate a passing result. Must be a subset of labels." } ], "status": [ "DOCUMENTED", "DEPRECATED" ], "verification": { "method": "docs_only" }, "sources": [ { "url": "https://developers.openai.com/api/reference/resources/graders", "retrieved_at": "2026-09-18" }, { "url": "https://developers.openai.com/api/openapi (openapi-master.yaml)", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/openai-platform-objects.json" }, { "provider": "openai", "api_family": "graders", "name": "GraderPython", "spec_schema": "GraderPython", "object_type": null, "description": "A PythonGrader object that runs a python script on the input.", "required": [ "type", "name", "source" ], "fields": [ { "parameter": "type", "type": "string", "required": true, "enum": [ "python" ], "description": "The object type, which is always `python`." }, { "parameter": "name", "type": "string", "required": true, "description": "The name of the grader." }, { "parameter": "source", "type": "string", "required": true, "description": "The source code of the python script." }, { "parameter": "image_tag", "type": "string", "description": "The image tag to use for the python script." } ], "status": [ "DOCUMENTED", "DEPRECATED" ], "verification": { "method": "docs_only" }, "sources": [ { "url": "https://developers.openai.com/api/reference/resources/graders", "retrieved_at": "2026-09-18" }, { "url": "https://developers.openai.com/api/openapi (openapi-master.yaml)", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/openai-platform-objects.json" }, { "provider": "openai", "api_family": "graders", "name": "GraderMulti", "spec_schema": "GraderMulti", "object_type": null, "description": "A MultiGrader object combines the output of multiple graders to produce a single score.", "required": [ "name", "type", "graders", "calculate_output" ], "fields": [ { "parameter": "type", "type": "string", "required": true, "enum": [ "multi" ], "default": "multi", "description": "The object type, which is always `multi`." }, { "parameter": "name", "type": "string", "required": true, "description": "The name of the grader." }, { "parameter": "graders", "type": "object | object | object | object | object", "required": true, "description": "" }, { "parameter": "graders.type", "type": "string", "required": true, "enum": [ "string_check" ], "description": "The object type, which is always `string_check`." }, { "parameter": "graders.name", "type": "string", "required": true, "description": "The name of the grader." }, { "parameter": "graders.input", "type": "string", "required": true, "description": "The input text. This may include template strings." }, { "parameter": "graders.reference", "type": "string", "required": true, "description": "The reference text. This may include template strings." }, { "parameter": "graders.operation", "type": "string", "required": true, "enum": [ "eq", "ne", "like", "ilike" ], "description": "The string check operation to perform. One of `eq`, `ne`, `like`, or `ilike`." }, { "parameter": "graders.type", "type": "string", "required": true, "enum": [ "text_similarity" ], "default": "text_similarity", "description": "The type of grader." }, { "parameter": "graders.name", "type": "string", "required": true, "description": "The name of the grader." }, { "parameter": "graders.input", "type": "string", "required": true, "description": "The text being graded." }, { "parameter": "graders.reference", "type": "string", "required": true, "description": "The text being graded against." }, { "parameter": "graders.evaluation_metric", "type": "string", "required": true, "enum": [ "cosine", "fuzzy_match", "bleu", "gleu", "meteor", "rouge_1", "rouge_2", "rouge_3", "rouge_4", "rouge_5", "rouge_l" ], "description": "The evaluation metric to use. One of `cosine`, `fuzzy_match`, `bleu`, \n`gleu`, `meteor`, `rouge_1`, `rouge_2`, `rouge_3`, `rouge_4`, `rouge_5`, \nor `rouge_l`." }, { "parameter": "graders.type", "type": "string", "required": true, "enum": [ "python" ], "description": "The object type, which is always `python`." }, { "parameter": "graders.name", "type": "string", "required": true, "description": "The name of the grader." }, { "parameter": "graders.source", "type": "string", "required": true, "description": "The source code of the python script." }, { "parameter": "graders.image_tag", "type": "string", "description": "The image tag to use for the python script." }, { "parameter": "graders.type", "type": "string", "required": true, "enum": [ "score_model" ], "description": "The object type, which is always `score_model`." }, { "parameter": "graders.name", "type": "string", "required": true, "description": "The name of the grader." }, { "parameter": "graders.model", "type": "string", "required": true, "description": "The model to use for the evaluation." }, { "parameter": "graders.sampling_params", "type": "object", "description": "The sampling parameters for the model." }, { "parameter": "graders.sampling_params.seed", "type": "integer | null", "description": "" }, { "parameter": "graders.sampling_params.top_p", "type": "number | null", "description": "" }, { "parameter": "graders.sampling_params.temperature", "type": "number | null", "description": "" }, { "parameter": "graders.sampling_params.max_completions_tokens", "type": "integer | null", "description": "" }, { "parameter": "graders.sampling_params.reasoning_effort", "type": "string | null", "description": "" }, { "parameter": "graders.input", "type": "array", "required": true, "description": "The input messages evaluated by the grader. Supports text, output text, input image, and input audio content blocks, and may include template strings." }, { "parameter": "graders.input[].role", "type": "string", "required": true, "enum": [ "user", "assistant", "system", "developer" ], "description": "The role of the message input. One of `user`, `assistant`, `system`, or\n`developer`." }, { "parameter": "graders.input[].content", "type": "EvalItemContentItem | EvalItemContentArray", "required": true, "description": "Inputs to the model - can contain template strings. Supports text, output text, input images, and input audio, either as a single item or an array of items." }, { "parameter": "graders.input[].type", "type": "string", "enum": [ "message" ], "description": "The type of the message input. Always `message`." }, { "parameter": "graders.range", "type": "array", "description": "The range of the score. Defaults to `[0, 1]`." }, { "parameter": "graders.type", "type": "string", "required": true, "enum": [ "label_model" ], "description": "The object type, which is always `label_model`." }, { "parameter": "graders.name", "type": "string", "required": true, "description": "The name of the grader." }, { "parameter": "graders.model", "type": "string", "required": true, "description": "The model to use for the evaluation. Must support structured outputs." }, { "parameter": "graders.input", "type": "array", "required": true, "description": "" }, { "parameter": "graders.input[].role", "type": "string", "required": true, "enum": [ "user", "assistant", "system", "developer" ], "description": "The role of the message input. One of `user`, `assistant`, `system`, or\n`developer`." }, { "parameter": "graders.input[].content", "type": "EvalItemContentItem | EvalItemContentArray", "required": true, "description": "Inputs to the model - can contain template strings. Supports text, output text, input images, and input audio, either as a single item or an array of items." }, { "parameter": "graders.input[].type", "type": "string", "enum": [ "message" ], "description": "The type of the message input. Always `message`." }, { "parameter": "graders.labels", "type": "array", "required": true, "description": "The labels to assign to each item in the evaluation." }, { "parameter": "graders.passing_labels", "type": "array", "required": true, "description": "The labels that indicate a passing result. Must be a subset of labels." }, { "parameter": "calculate_output", "type": "string", "required": true, "description": "A formula to calculate the output based on grader results." } ], "status": [ "DOCUMENTED", "DEPRECATED" ], "verification": { "method": "docs_only" }, "sources": [ { "url": "https://developers.openai.com/api/reference/resources/graders", "retrieved_at": "2026-09-18" }, { "url": "https://developers.openai.com/api/openapi (openapi-master.yaml)", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/openai-platform-objects.json" }, { "provider": "openai", "api_family": "graders", "name": "RunGraderResponse", "spec_schema": "RunGraderResponse", "object_type": null, "description": "", "required": [ "reward", "metadata", "sub_rewards", "model_grader_token_usage_per_model" ], "fields": [ { "parameter": "reward", "type": "number", "required": true, "description": "" }, { "parameter": "metadata", "type": "object", "required": true, "description": "" }, { "parameter": "metadata.name", "type": "string", "required": true, "description": "" }, { "parameter": "metadata.type", "type": "string", "required": true, "description": "" }, { "parameter": "metadata.errors", "type": "object", "required": true, "description": "" }, { "parameter": "metadata.errors.formula_parse_error", "type": "boolean", "required": true, "description": "" }, { "parameter": "metadata.errors.sample_parse_error", "type": "boolean", "required": true, "description": "" }, { "parameter": "metadata.errors.truncated_observation_error", "type": "boolean", "required": true, "description": "" }, { "parameter": "metadata.errors.unresponsive_reward_error", "type": "boolean", "required": true, "description": "" }, { "parameter": "metadata.errors.invalid_variable_error", "type": "boolean", "required": true, "description": "" }, { "parameter": "metadata.errors.other_error", "type": "boolean", "required": true, "description": "" }, { "parameter": "metadata.errors.python_grader_server_error", "type": "boolean", "required": true, "description": "" }, { "parameter": "metadata.errors.python_grader_server_error_type", "type": "string | null", "required": true, "description": "" }, { "parameter": "metadata.errors.python_grader_runtime_error", "type": "boolean", "required": true, "description": "" }, { "parameter": "metadata.errors.python_grader_runtime_error_details", "type": "string | null", "required": true, "description": "" }, { "parameter": "metadata.errors.model_grader_server_error", "type": "boolean", "required": true, "description": "" }, { "parameter": "metadata.errors.model_grader_refusal_error", "type": "boolean", "required": true, "description": "" }, { "parameter": "metadata.errors.model_grader_parse_error", "type": "boolean", "required": true, "description": "" }, { "parameter": "metadata.errors.model_grader_server_error_details", "type": "string | null", "required": true, "description": "" }, { "parameter": "metadata.execution_time", "type": "number", "required": true, "description": "" }, { "parameter": "metadata.scores", "type": "object", "required": true, "description": "" }, { "parameter": "metadata.token_usage", "type": "integer | null", "required": true, "description": "" }, { "parameter": "metadata.sampled_model_name", "type": "string | null", "required": true, "description": "" }, { "parameter": "sub_rewards", "type": "object", "required": true, "description": "" }, { "parameter": "model_grader_token_usage_per_model", "type": "object", "required": true, "description": "" } ], "status": [ "DOCUMENTED", "DEPRECATED" ], "verification": { "method": "docs_only" }, "sources": [ { "url": "https://developers.openai.com/api/reference/resources/graders", "retrieved_at": "2026-09-18" }, { "url": "https://developers.openai.com/api/openapi (openapi-master.yaml)", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/openai-platform-objects.json" }, { "provider": "openai", "api_family": "graders", "name": "ValidateGraderResponse", "spec_schema": "ValidateGraderResponse", "object_type": null, "description": "", "required": [], "fields": [ { "parameter": "grader", "type": "object", "description": "The grader used for the fine-tuning job." }, { "parameter": "grader.type", "type": "string", "required": true, "enum": [ "string_check" ], "description": "The object type, which is always `string_check`." }, { "parameter": "grader.name", "type": "string", "required": true, "description": "The name of the grader." }, { "parameter": "grader.input", "type": "string", "required": true, "description": "The input text. This may include template strings." }, { "parameter": "grader.reference", "type": "string", "required": true, "description": "The reference text. This may include template strings." }, { "parameter": "grader.operation", "type": "string", "required": true, "enum": [ "eq", "ne", "like", "ilike" ], "description": "The string check operation to perform. One of `eq`, `ne`, `like`, or `ilike`." }, { "parameter": "grader.type", "type": "string", "required": true, "enum": [ "text_similarity" ], "default": "text_similarity", "description": "The type of grader." }, { "parameter": "grader.name", "type": "string", "required": true, "description": "The name of the grader." }, { "parameter": "grader.input", "type": "string", "required": true, "description": "The text being graded." }, { "parameter": "grader.reference", "type": "string", "required": true, "description": "The text being graded against." }, { "parameter": "grader.evaluation_metric", "type": "string", "required": true, "enum": [ "cosine", "fuzzy_match", "bleu", "gleu", "meteor", "rouge_1", "rouge_2", "rouge_3", "rouge_4", "rouge_5", "rouge_l" ], "description": "The evaluation metric to use. One of `cosine`, `fuzzy_match`, `bleu`, \n`gleu`, `meteor`, `rouge_1`, `rouge_2`, `rouge_3`, `rouge_4`, `rouge_5`, \nor `rouge_l`." }, { "parameter": "grader.type", "type": "string", "required": true, "enum": [ "python" ], "description": "The object type, which is always `python`." }, { "parameter": "grader.name", "type": "string", "required": true, "description": "The name of the grader." }, { "parameter": "grader.source", "type": "string", "required": true, "description": "The source code of the python script." }, { "parameter": "grader.image_tag", "type": "string", "description": "The image tag to use for the python script." }, { "parameter": "grader.type", "type": "string", "required": true, "enum": [ "score_model" ], "description": "The object type, which is always `score_model`." }, { "parameter": "grader.name", "type": "string", "required": true, "description": "The name of the grader." }, { "parameter": "grader.model", "type": "string", "required": true, "description": "The model to use for the evaluation." }, { "parameter": "grader.sampling_params", "type": "object", "description": "The sampling parameters for the model." }, { "parameter": "grader.sampling_params.seed", "type": "integer | null", "description": "" }, { "parameter": "grader.sampling_params.top_p", "type": "number | null", "description": "" }, { "parameter": "grader.sampling_params.temperature", "type": "number | null", "description": "" }, { "parameter": "grader.sampling_params.max_completions_tokens", "type": "integer | null", "description": "" }, { "parameter": "grader.sampling_params.reasoning_effort", "type": "string | null", "description": "" }, { "parameter": "grader.input", "type": "array", "required": true, "description": "The input messages evaluated by the grader. Supports text, output text, input image, and input audio content blocks, and may include template strings." }, { "parameter": "grader.input[].role", "type": "string", "required": true, "enum": [ "user", "assistant", "system", "developer" ], "description": "The role of the message input. One of `user`, `assistant`, `system`, or\n`developer`." }, { "parameter": "grader.input[].content", "type": "EvalItemContentItem | EvalItemContentArray", "required": true, "description": "Inputs to the model - can contain template strings. Supports text, output text, input images, and input audio, either as a single item or an array of items." }, { "parameter": "grader.input[].type", "type": "string", "enum": [ "message" ], "description": "The type of the message input. Always `message`." }, { "parameter": "grader.range", "type": "array", "description": "The range of the score. Defaults to `[0, 1]`." }, { "parameter": "grader.type", "type": "string", "required": true, "enum": [ "multi" ], "default": "multi", "description": "The object type, which is always `multi`." }, { "parameter": "grader.name", "type": "string", "required": true, "description": "The name of the grader." }, { "parameter": "grader.graders", "type": "object | object | object | object | object", "required": true, "description": "" }, { "parameter": "grader.graders.type", "type": "string", "required": true, "enum": [ "string_check" ], "description": "The object type, which is always `string_check`." }, { "parameter": "grader.graders.name", "type": "string", "required": true, "description": "The name of the grader." }, { "parameter": "grader.graders.input", "type": "string", "required": true, "description": "The input text. This may include template strings." }, { "parameter": "grader.graders.reference", "type": "string", "required": true, "description": "The reference text. This may include template strings." }, { "parameter": "grader.graders.operation", "type": "string", "required": true, "enum": [ "eq", "ne", "like", "ilike" ], "description": "The string check operation to perform. One of `eq`, `ne`, `like`, or `ilike`." }, { "parameter": "grader.graders.type", "type": "string", "required": true, "enum": [ "text_similarity" ], "default": "text_similarity", "description": "The type of grader." }, { "parameter": "grader.graders.name", "type": "string", "required": true, "description": "The name of the grader." }, { "parameter": "grader.graders.input", "type": "string", "required": true, "description": "The text being graded." }, { "parameter": "grader.graders.reference", "type": "string", "required": true, "description": "The text being graded against." }, { "parameter": "grader.graders.evaluation_metric", "type": "string", "required": true, "enum": [ "cosine", "fuzzy_match", "bleu", "gleu", "meteor", "rouge_1", "rouge_2", "rouge_3", "rouge_4", "rouge_5", "rouge_l" ], "description": "The evaluation metric to use. One of `cosine`, `fuzzy_match`, `bleu`, \n`gleu`, `meteor`, `rouge_1`, `rouge_2`, `rouge_3`, `rouge_4`, `rouge_5`, \nor `rouge_l`." }, { "parameter": "grader.graders.type", "type": "string", "required": true, "enum": [ "python" ], "description": "The object type, which is always `python`." }, { "parameter": "grader.graders.name", "type": "string", "required": true, "description": "The name of the grader." }, { "parameter": "grader.graders.source", "type": "string", "required": true, "description": "The source code of the python script." }, { "parameter": "grader.graders.image_tag", "type": "string", "description": "The image tag to use for the python script." }, { "parameter": "grader.graders.type", "type": "string", "required": true, "enum": [ "score_model" ], "description": "The object type, which is always `score_model`." }, { "parameter": "grader.graders.name", "type": "string", "required": true, "description": "The name of the grader." }, { "parameter": "grader.graders.model", "type": "string", "required": true, "description": "The model to use for the evaluation." }, { "parameter": "grader.graders.sampling_params", "type": "object", "description": "The sampling parameters for the model." }, { "parameter": "grader.graders.sampling_params.seed", "type": "integer | null", "description": "" }, { "parameter": "grader.graders.sampling_params.top_p", "type": "number | null", "description": "" }, { "parameter": "grader.graders.sampling_params.temperature", "type": "number | null", "description": "" }, { "parameter": "grader.graders.sampling_params.max_completions_tokens", "type": "integer | null", "description": "" }, { "parameter": "grader.graders.sampling_params.reasoning_effort", "type": "object", "description": "" }, { "parameter": "grader.graders.input", "type": "array", "required": true, "description": "The input messages evaluated by the grader. Supports text, output text, input image, and input audio content blocks, and may include template strings." }, { "parameter": "grader.graders.range", "type": "array", "description": "The range of the score. Defaults to `[0, 1]`." }, { "parameter": "grader.graders.type", "type": "string", "required": true, "enum": [ "label_model" ], "description": "The object type, which is always `label_model`." }, { "parameter": "grader.graders.name", "type": "string", "required": true, "description": "The name of the grader." }, { "parameter": "grader.graders.model", "type": "string", "required": true, "description": "The model to use for the evaluation. Must support structured outputs." }, { "parameter": "grader.graders.input", "type": "array", "required": true, "description": "" }, { "parameter": "grader.graders.labels", "type": "array", "required": true, "description": "The labels to assign to each item in the evaluation." }, { "parameter": "grader.graders.passing_labels", "type": "array", "required": true, "description": "The labels that indicate a passing result. Must be a subset of labels." }, { "parameter": "grader.calculate_output", "type": "string", "required": true, "description": "A formula to calculate the output based on grader results." } ], "status": [ "DOCUMENTED", "DEPRECATED" ], "verification": { "method": "docs_only" }, "sources": [ { "url": "https://developers.openai.com/api/reference/resources/graders", "retrieved_at": "2026-09-18" }, { "url": "https://developers.openai.com/api/openapi (openapi-master.yaml)", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/openai-platform-objects.json" }, { "provider": "openai", "api_family": "evals", "name": "Eval", "spec_schema": "Eval", "object_type": "eval", "description": "An Eval object with a data source config and testing criteria.\nAn Eval represents a task to be done for your LLM integration.\nLike:\n - Improve the quality of my chatbot\n - See how well my chatbot handles customer support\n - Check if o4-mini is better at my usecase than gpt-6-astra", "required": [ "id", "data_source_config", "object", "testing_criteria", "name", "created_at", "metadata" ], "fields": [ { "parameter": "object", "type": "string", "required": true, "enum": [ "eval" ], "default": "eval", "description": "The object type." }, { "parameter": "id", "type": "string", "required": true, "description": "Unique identifier for the evaluation." }, { "parameter": "name", "type": "string", "required": true, "description": "The name of the evaluation." }, { "parameter": "data_source_config", "type": "object", "required": true, "description": "Configuration of data sources used in runs of the evaluation." }, { "parameter": "data_source_config.type", "type": "string", "required": true, "enum": [ "custom" ], "default": "custom", "description": "The type of data source. Always `custom`." }, { "parameter": "data_source_config.schema", "type": "object", "required": true, "description": "The json schema for the run data source items.\nLearn how to build JSON schemas [here](https://json-schema.org/)." }, { "parameter": "data_source_config.type", "type": "string", "required": true, "enum": [ "logs" ], "default": "logs", "description": "The type of data source. Always `logs`." }, { "parameter": "data_source_config.metadata", "type": "object | null", "description": "" }, { "parameter": "data_source_config.schema", "type": "object", "required": true, "description": "The json schema for the run data source items.\nLearn how to build JSON schemas [here](https://json-schema.org/)." }, { "parameter": "data_source_config.type", "type": "string", "required": true, "enum": [ "stored_completions" ], "default": "stored_completions", "description": "The type of data source. Always `stored_completions`." }, { "parameter": "data_source_config.metadata", "type": "object | null", "description": "" }, { "parameter": "data_source_config.schema", "type": "object", "required": true, "description": "The json schema for the run data source items.\nLearn how to build JSON schemas [here](https://json-schema.org/)." }, { "parameter": "testing_criteria", "type": "array", "required": true, "description": "A list of testing criteria." }, { "parameter": "testing_criteria[].type", "type": "string", "required": true, "enum": [ "label_model" ], "description": "The object type, which is always `label_model`." }, { "parameter": "testing_criteria[].name", "type": "string", "required": true, "description": "The name of the grader." }, { "parameter": "testing_criteria[].model", "type": "string", "required": true, "description": "The model to use for the evaluation. Must support structured outputs." }, { "parameter": "testing_criteria[].input", "type": "array", "required": true, "description": "" }, { "parameter": "testing_criteria[].input[].role", "type": "string", "required": true, "enum": [ "user", "assistant", "system", "developer" ], "description": "The role of the message input. One of `user`, `assistant`, `system`, or\n`developer`." }, { "parameter": "testing_criteria[].input[].content", "required": true, "type": "object", "description": "" }, { "parameter": "testing_criteria[].input[].type", "type": "string", "enum": [ "message" ], "description": "The type of the message input. Always `message`." }, { "parameter": "testing_criteria[].labels", "type": "array", "required": true, "description": "The labels to assign to each item in the evaluation." }, { "parameter": "testing_criteria[].passing_labels", "type": "array", "required": true, "description": "The labels that indicate a passing result. Must be a subset of labels." }, { "parameter": "testing_criteria[].type", "type": "string", "required": true, "enum": [ "string_check" ], "description": "The object type, which is always `string_check`." }, { "parameter": "testing_criteria[].name", "type": "string", "required": true, "description": "The name of the grader." }, { "parameter": "testing_criteria[].input", "type": "string", "required": true, "description": "The input text. This may include template strings." }, { "parameter": "testing_criteria[].reference", "type": "string", "required": true, "description": "The reference text. This may include template strings." }, { "parameter": "testing_criteria[].operation", "type": "string", "required": true, "enum": [ "eq", "ne", "like", "ilike" ], "description": "The string check operation to perform. One of `eq`, `ne`, `like`, or `ilike`." }, { "parameter": "testing_criteria[].type", "type": "string", "required": true, "enum": [ "text_similarity" ], "default": "text_similarity", "description": "The type of grader." }, { "parameter": "testing_criteria[].name", "type": "string", "required": true, "description": "The name of the grader." }, { "parameter": "testing_criteria[].input", "type": "string", "required": true, "description": "The text being graded." }, { "parameter": "testing_criteria[].reference", "type": "string", "required": true, "description": "The text being graded against." }, { "parameter": "testing_criteria[].evaluation_metric", "type": "string", "required": true, "enum": [ "cosine", "fuzzy_match", "bleu", "gleu", "meteor", "rouge_1", "rouge_2", "rouge_3", "rouge_4", "rouge_5", "rouge_l" ], "description": "The evaluation metric to use. One of `cosine`, `fuzzy_match`, `bleu`, \n`gleu`, `meteor`, `rouge_1`, `rouge_2`, `rouge_3`, `rouge_4`, `rouge_5`, \nor `rouge_l`." }, { "parameter": "testing_criteria[].pass_threshold", "type": "number", "required": true, "description": "The threshold for the score." }, { "parameter": "testing_criteria[].type", "type": "string", "required": true, "enum": [ "python" ], "description": "The object type, which is always `python`." }, { "parameter": "testing_criteria[].name", "type": "string", "required": true, "description": "The name of the grader." }, { "parameter": "testing_criteria[].source", "type": "string", "required": true, "description": "The source code of the python script." }, { "parameter": "testing_criteria[].image_tag", "type": "string", "description": "The image tag to use for the python script." }, { "parameter": "testing_criteria[].pass_threshold", "type": "number", "description": "The threshold for the score." }, { "parameter": "testing_criteria[].type", "type": "string", "required": true, "enum": [ "score_model" ], "description": "The object type, which is always `score_model`." }, { "parameter": "testing_criteria[].name", "type": "string", "required": true, "description": "The name of the grader." }, { "parameter": "testing_criteria[].model", "type": "string", "required": true, "description": "The model to use for the evaluation." }, { "parameter": "testing_criteria[].sampling_params", "type": "object", "description": "The sampling parameters for the model." }, { "parameter": "testing_criteria[].sampling_params.seed", "type": "integer | null", "description": "" }, { "parameter": "testing_criteria[].sampling_params.top_p", "type": "number | null", "description": "" }, { "parameter": "testing_criteria[].sampling_params.temperature", "type": "number | null", "description": "" }, { "parameter": "testing_criteria[].sampling_params.max_completions_tokens", "type": "integer | null", "description": "" }, { "parameter": "testing_criteria[].sampling_params.reasoning_effort", "type": "object", "description": "" }, { "parameter": "testing_criteria[].input", "type": "array", "required": true, "description": "The input messages evaluated by the grader. Supports text, output text, input image, and input audio content blocks, and may include template strings." }, { "parameter": "testing_criteria[].input[].role", "type": "string", "required": true, "enum": [ "user", "assistant", "system", "developer" ], "description": "The role of the message input. One of `user`, `assistant`, `system`, or\n`developer`." }, { "parameter": "testing_criteria[].input[].content", "required": true, "type": "object", "description": "" }, { "parameter": "testing_criteria[].input[].type", "type": "string", "enum": [ "message" ], "description": "The type of the message input. Always `message`." }, { "parameter": "testing_criteria[].range", "type": "array", "description": "The range of the score. Defaults to `[0, 1]`." }, { "parameter": "testing_criteria[].pass_threshold", "type": "number", "description": "The threshold for the score." }, { "parameter": "created_at", "type": "integer", "required": true, "description": "The Unix timestamp (in seconds) for when the eval was created." }, { "parameter": "metadata", "type": "object | null", "required": true, "description": "" } ], "status": [ "DOCUMENTED", "DEPRECATED" ], "verification": { "method": "docs_only" }, "sources": [ { "url": "https://developers.openai.com/api/reference/resources/evals", "retrieved_at": "2026-09-18" }, { "url": "https://developers.openai.com/api/openapi (openapi-master.yaml)", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/openai-platform-objects.json" }, { "provider": "openai", "api_family": "evals", "name": "EvalRun", "spec_schema": "EvalRun", "object_type": "eval.run", "description": "A schema representing an evaluation run.", "required": [ "object", "id", "eval_id", "status", "model", "name", "created_at", "report_url", "result_counts", "per_model_usage", "per_testing_criteria_results", "data_source", "metadata", "error" ], "fields": [ { "parameter": "object", "type": "string", "required": true, "enum": [ "eval.run" ], "default": "eval.run", "description": "The type of the object. Always \"eval.run\"." }, { "parameter": "id", "type": "string", "required": true, "description": "Unique identifier for the evaluation run." }, { "parameter": "eval_id", "type": "string", "required": true, "description": "The identifier of the associated evaluation." }, { "parameter": "status", "type": "string", "required": true, "description": "The status of the evaluation run." }, { "parameter": "model", "type": "string", "required": true, "description": "The model that is evaluated, if applicable." }, { "parameter": "name", "type": "string", "required": true, "description": "The name of the evaluation run." }, { "parameter": "created_at", "type": "integer", "required": true, "description": "Unix timestamp (in seconds) when the evaluation run was created." }, { "parameter": "report_url", "type": "string", "required": true, "description": "The URL to the rendered evaluation run report on the UI dashboard." }, { "parameter": "result_counts", "type": "object", "required": true, "description": "Counters summarizing the outcomes of the evaluation run." }, { "parameter": "result_counts.total", "type": "integer", "required": true, "description": "Total number of executed output items." }, { "parameter": "result_counts.errored", "type": "integer", "required": true, "description": "Number of output items that resulted in an error." }, { "parameter": "result_counts.failed", "type": "integer", "required": true, "description": "Number of output items that failed to pass the evaluation." }, { "parameter": "result_counts.passed", "type": "integer", "required": true, "description": "Number of output items that passed the evaluation." }, { "parameter": "per_model_usage", "type": "array", "required": true, "description": "Usage statistics for each model during the evaluation run." }, { "parameter": "per_model_usage[].model_name", "type": "string", "required": true, "description": "The name of the model." }, { "parameter": "per_model_usage[].invocation_count", "type": "integer", "required": true, "description": "The number of invocations." }, { "parameter": "per_model_usage[].prompt_tokens", "type": "integer", "required": true, "description": "The number of prompt tokens used." }, { "parameter": "per_model_usage[].completion_tokens", "type": "integer", "required": true, "description": "The number of completion tokens generated." }, { "parameter": "per_model_usage[].total_tokens", "type": "integer", "required": true, "description": "The total number of tokens used." }, { "parameter": "per_model_usage[].cached_tokens", "type": "integer", "required": true, "description": "The number of tokens retrieved from cache." }, { "parameter": "per_testing_criteria_results", "type": "array", "required": true, "description": "Results per testing criteria applied during the evaluation run." }, { "parameter": "per_testing_criteria_results[].testing_criteria", "type": "string", "required": true, "description": "A description of the testing criteria." }, { "parameter": "per_testing_criteria_results[].passed", "type": "integer", "required": true, "description": "Number of tests passed for this criteria." }, { "parameter": "per_testing_criteria_results[].failed", "type": "integer", "required": true, "description": "Number of tests failed for this criteria." }, { "parameter": "data_source", "type": "object", "required": true, "description": "Information about the run's data source." }, { "parameter": "data_source.type", "type": "string", "required": true, "enum": [ "jsonl" ], "default": "jsonl", "description": "The type of data source. Always `jsonl`." }, { "parameter": "data_source.source", "type": "object | object", "required": true, "description": "Determines what populates the `item` namespace in the data source." }, { "parameter": "data_source.source.type", "type": "string", "required": true, "enum": [ "file_content" ], "default": "file_content", "description": "The type of jsonl source. Always `file_content`." }, { "parameter": "data_source.source.content", "type": "array", "required": true, "description": "The content of the jsonl file." }, { "parameter": "data_source.source.content[].item", "type": "object", "required": true, "description": "" }, { "parameter": "data_source.source.content[].sample", "type": "object", "description": "" }, { "parameter": "data_source.source.type", "type": "string", "required": true, "enum": [ "file_id" ], "default": "file_id", "description": "The type of jsonl source. Always `file_id`." }, { "parameter": "data_source.source.id", "type": "string", "required": true, "description": "The identifier of the file." }, { "parameter": "data_source.type", "type": "string", "required": true, "enum": [ "completions" ], "default": "completions", "description": "The type of run data source. Always `completions`." }, { "parameter": "data_source.input_messages", "type": "object | object", "description": "Used when sampling from a model. Dictates the structure of the messages passed into the model. Can either be a reference to a prebuilt trajectory (ie, `item.input_trajectory`), or a template with variable references to the `item` namespace." }, { "parameter": "data_source.input_messages.type", "type": "string", "required": true, "enum": [ "template" ], "description": "The type of input messages. Always `template`." }, { "parameter": "data_source.input_messages.template", "type": "array", "required": true, "description": "A list of chat messages forming the prompt or context. May include variable references to the `item` namespace, ie {{item.name}}." }, { "parameter": "data_source.input_messages.type", "type": "string", "required": true, "enum": [ "item_reference" ], "description": "The type of input messages. Always `item_reference`." }, { "parameter": "data_source.input_messages.item_reference", "type": "string", "required": true, "description": "A reference to a variable in the `item` namespace. Ie, \"item.input_trajectory\"" }, { "parameter": "data_source.sampling_params", "type": "object", "description": "" }, { "parameter": "data_source.sampling_params.reasoning_effort", "type": "string | null", "description": "" }, { "parameter": "data_source.sampling_params.temperature", "type": "number", "default": 1, "description": "A higher temperature increases randomness in the outputs." }, { "parameter": "data_source.sampling_params.max_completion_tokens", "type": "integer", "description": "The maximum number of tokens in the generated output." }, { "parameter": "data_source.sampling_params.top_p", "type": "number", "default": 1, "description": "An alternative to temperature for nucleus sampling; 1.0 includes all tokens." }, { "parameter": "data_source.sampling_params.seed", "type": "integer", "default": 42, "description": "A seed value to initialize the randomness, during sampling." }, { "parameter": "data_source.sampling_params.response_format", "type": "object | object | object", "description": "An object specifying the format that the model must output.\n\nSetting to `{ \"type\": \"json_schema\", \"json_schema\": {...} }` enables\nStructured Outputs which ensures the model will match your supplied JSON\nschema. Learn more in the [Structured Outputs\nguide](https://developers.openai.com/api/docs/guide" }, { "parameter": "data_source.sampling_params.response_format.type", "type": "string", "required": true, "enum": [ "text" ], "description": "The type of response format being defined. Always `text`." }, { "parameter": "data_source.sampling_params.response_format.type", "type": "string", "required": true, "enum": [ "json_schema" ], "description": "The type of response format being defined. Always `json_schema`." }, { "parameter": "data_source.sampling_params.response_format.json_schema", "type": "object", "required": true, "description": "Structured Outputs configuration options, including a JSON Schema." }, { "parameter": "data_source.sampling_params.response_format.type", "type": "string", "required": true, "enum": [ "json_object" ], "description": "The type of response format being defined. Always `json_object`." }, { "parameter": "data_source.sampling_params.tools", "type": "array", "description": "A list of tools the model may call. Currently, only functions are supported as a tool. Use this to provide a list of functions the model may generate JSON inputs for. A max of 128 functions are supported." }, { "parameter": "data_source.sampling_params.tools[].type", "type": "string", "required": true, "enum": [ "function" ], "description": "The type of the tool. Currently, only `function` is supported." }, { "parameter": "data_source.sampling_params.tools[].function", "required": true, "type": "object", "description": "" }, { "parameter": "data_source.model", "type": "string", "description": "The name of the model to use for generating completions (e.g. \"o3-mini\")." }, { "parameter": "data_source.source", "type": "object | object | object", "required": true, "description": "Determines what populates the `item` namespace in this run's data source." }, { "parameter": "data_source.source.type", "type": "string", "required": true, "enum": [ "file_content" ], "default": "file_content", "description": "The type of jsonl source. Always `file_content`." }, { "parameter": "data_source.source.content", "type": "array", "required": true, "description": "The content of the jsonl file." }, { "parameter": "data_source.source.content[].item", "type": "object", "required": true, "description": "" }, { "parameter": "data_source.source.content[].sample", "type": "object", "description": "" }, { "parameter": "data_source.source.type", "type": "string", "required": true, "enum": [ "file_id" ], "default": "file_id", "description": "The type of jsonl source. Always `file_id`." }, { "parameter": "data_source.source.id", "type": "string", "required": true, "description": "The identifier of the file." }, { "parameter": "data_source.source.type", "type": "string", "required": true, "enum": [ "stored_completions" ], "default": "stored_completions", "description": "The type of source. Always `stored_completions`." }, { "parameter": "data_source.source.metadata", "type": "object | null", "description": "" }, { "parameter": "data_source.source.model", "type": "string | null", "description": "" }, { "parameter": "data_source.source.created_after", "type": "integer | null", "description": "" }, { "parameter": "data_source.source.created_before", "type": "integer | null", "description": "" }, { "parameter": "data_source.source.limit", "type": "integer | null", "description": "" }, { "parameter": "data_source.type", "type": "string", "required": true, "enum": [ "responses" ], "default": "responses", "description": "The type of run data source. Always `responses`." }, { "parameter": "data_source.input_messages", "type": "object | object", "description": "Used when sampling from a model. Dictates the structure of the messages passed into the model. Can either be a reference to a prebuilt trajectory (ie, `item.input_trajectory`), or a template with variable references to the `item` namespace." }, { "parameter": "data_source.input_messages.type", "type": "string", "required": true, "enum": [ "template" ], "description": "The type of input messages. Always `template`." }, { "parameter": "data_source.input_messages.template", "type": "array", "required": true, "description": "A list of chat messages forming the prompt or context. May include variable references to the `item` namespace, ie {{item.name}}." }, { "parameter": "data_source.input_messages.template[].role", "type": "string", "required": true, "description": "The role of the message (e.g. \"system\", \"assistant\", \"user\")." }, { "parameter": "data_source.input_messages.template[].content", "type": "string", "required": true, "description": "The content of the message." }, { "parameter": "data_source.input_messages.type", "type": "string", "required": true, "enum": [ "item_reference" ], "description": "The type of input messages. Always `item_reference`." }, { "parameter": "data_source.input_messages.item_reference", "type": "string", "required": true, "description": "A reference to a variable in the `item` namespace. Ie, \"item.name\"" }, { "parameter": "data_source.sampling_params", "type": "object", "description": "" }, { "parameter": "data_source.sampling_params.reasoning_effort", "type": "string | null", "description": "" }, { "parameter": "data_source.sampling_params.temperature", "type": "number", "default": 1, "description": "A higher temperature increases randomness in the outputs." }, { "parameter": "data_source.sampling_params.max_completion_tokens", "type": "integer", "description": "The maximum number of tokens in the generated output." }, { "parameter": "data_source.sampling_params.top_p", "type": "number", "default": 1, "description": "An alternative to temperature for nucleus sampling; 1.0 includes all tokens." }, { "parameter": "data_source.sampling_params.seed", "type": "integer", "default": 42, "description": "A seed value to initialize the randomness, during sampling." }, { "parameter": "data_source.sampling_params.tools", "type": "array", "description": "An array of tools the model may call while generating a response. You\ncan specify which tool to use by setting the `tool_choice` parameter.\n\nThe two categories of tools you can provide the model are:\n\n- **Built-in tools**: Tools that are provided by OpenAI that extend the\n model's capabilities, lik" }, { "parameter": "data_source.sampling_params.text", "type": "object", "description": "Configuration options for a text response from the model. Can be plain\ntext or structured JSON data. Learn more:\n- [Text inputs and outputs](https://developers.openai.com/api/docs/guides/text)\n- [Structured Outputs](https://developers.openai.com/api/docs/guides/structured-outputs)" }, { "parameter": "data_source.sampling_params.text.format", "type": "ResponseFormatText | TextResponseFormatJsonSchema | ResponseFormatJsonObject", "description": "An object specifying the format that the model must output.\n\nConfiguring `{ \"type\": \"json_schema\" }` enables Structured Outputs,\nwhich ensures the model will match your supplied JSON schema. Learn more in the\n[Structured Outputs guide](https://developers.openai.com/api/docs/guides/structured-outputs" }, { "parameter": "data_source.model", "type": "string", "description": "The name of the model to use for generating completions (e.g. \"o3-mini\")." }, { "parameter": "data_source.source", "type": "object | object | object", "required": true, "description": "Determines what populates the `item` namespace in this run's data source." }, { "parameter": "data_source.source.type", "type": "string", "required": true, "enum": [ "file_content" ], "default": "file_content", "description": "The type of jsonl source. Always `file_content`." }, { "parameter": "data_source.source.content", "type": "array", "required": true, "description": "The content of the jsonl file." }, { "parameter": "data_source.source.content[].item", "type": "object", "required": true, "description": "" }, { "parameter": "data_source.source.content[].sample", "type": "object", "description": "" }, { "parameter": "data_source.source.type", "type": "string", "required": true, "enum": [ "file_id" ], "default": "file_id", "description": "The type of jsonl source. Always `file_id`." }, { "parameter": "data_source.source.id", "type": "string", "required": true, "description": "The identifier of the file." }, { "parameter": "data_source.source.type", "type": "string", "required": true, "enum": [ "responses" ], "description": "The type of run data source. Always `responses`." }, { "parameter": "data_source.source.metadata", "type": "object | null", "description": "" }, { "parameter": "data_source.source.model", "type": "string | null", "description": "" }, { "parameter": "data_source.source.instructions_search", "type": "string | null", "description": "" }, { "parameter": "data_source.source.created_after", "type": "integer | null", "description": "" }, { "parameter": "data_source.source.created_before", "type": "integer | null", "description": "" }, { "parameter": "data_source.source.reasoning_effort", "type": "ReasoningEffort | null", "description": "" }, { "parameter": "data_source.source.temperature", "type": "number | null", "description": "" }, { "parameter": "data_source.source.top_p", "type": "number | null", "description": "" }, { "parameter": "data_source.source.users", "type": "array | null", "description": "" }, { "parameter": "data_source.source.tools", "type": "array | null", "description": "" }, { "parameter": "metadata", "type": "object | null", "required": true, "description": "" }, { "parameter": "error", "type": "object", "required": true, "description": "An object representing an error response from the Eval API." }, { "parameter": "error.code", "type": "string", "required": true, "description": "The error code." }, { "parameter": "error.message", "type": "string", "required": true, "description": "The error message." } ], "status": [ "DOCUMENTED", "DEPRECATED" ], "verification": { "method": "docs_only" }, "sources": [ { "url": "https://developers.openai.com/api/reference/resources/evals", "retrieved_at": "2026-09-18" }, { "url": "https://developers.openai.com/api/openapi (openapi-master.yaml)", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/openai-platform-objects.json" }, { "provider": "openai", "api_family": "evals", "name": "EvalRunOutputItem", "spec_schema": "EvalRunOutputItem", "object_type": "eval.run.output_item", "description": "A schema representing an evaluation run output item.", "required": [ "object", "id", "run_id", "eval_id", "created_at", "status", "datasource_item_id", "datasource_item", "results", "sample" ], "fields": [ { "parameter": "object", "type": "string", "required": true, "enum": [ "eval.run.output_item" ], "default": "eval.run.output_item", "description": "The type of the object. Always \"eval.run.output_item\"." }, { "parameter": "id", "type": "string", "required": true, "description": "Unique identifier for the evaluation run output item." }, { "parameter": "run_id", "type": "string", "required": true, "description": "The identifier of the evaluation run associated with this output item." }, { "parameter": "eval_id", "type": "string", "required": true, "description": "The identifier of the evaluation group." }, { "parameter": "created_at", "type": "integer", "required": true, "description": "Unix timestamp (in seconds) when the evaluation run was created." }, { "parameter": "status", "type": "string", "required": true, "description": "The status of the evaluation run." }, { "parameter": "datasource_item_id", "type": "integer", "required": true, "description": "The identifier for the data source item." }, { "parameter": "datasource_item", "type": "object", "required": true, "description": "Details of the input data source item." }, { "parameter": "results", "type": "array", "required": true, "description": "A list of grader results for this output item." }, { "parameter": "results[].name", "type": "string", "required": true, "description": "The name of the grader." }, { "parameter": "results[].type", "type": "string", "description": "The grader type (for example, \"string-check-grader\")." }, { "parameter": "results[].score", "type": "number", "required": true, "description": "The numeric score produced by the grader." }, { "parameter": "results[].passed", "type": "boolean", "required": true, "description": "Whether the grader considered the output a pass." }, { "parameter": "results[].sample", "type": "object | null", "description": "Optional sample or intermediate data produced by the grader." }, { "parameter": "sample", "type": "object", "required": true, "description": "A sample containing the input and output of the evaluation run." }, { "parameter": "sample.input", "type": "array", "required": true, "description": "An array of input messages." }, { "parameter": "sample.input[].role", "type": "string", "required": true, "description": "The role of the message sender (e.g., system, user, developer)." }, { "parameter": "sample.input[].content", "type": "string", "required": true, "description": "The content of the message." }, { "parameter": "sample.output", "type": "array", "required": true, "description": "An array of output messages." }, { "parameter": "sample.output[].role", "type": "string", "description": "The role of the message (e.g. \"system\", \"assistant\", \"user\")." }, { "parameter": "sample.output[].content", "type": "string", "description": "The content of the message." }, { "parameter": "sample.finish_reason", "type": "string", "required": true, "description": "The reason why the sample generation was finished." }, { "parameter": "sample.model", "type": "string", "required": true, "description": "The model used for generating the sample." }, { "parameter": "sample.usage", "type": "object", "required": true, "description": "Token usage details for the sample." }, { "parameter": "sample.usage.total_tokens", "type": "integer", "required": true, "description": "The total number of tokens used." }, { "parameter": "sample.usage.completion_tokens", "type": "integer", "required": true, "description": "The number of completion tokens generated." }, { "parameter": "sample.usage.prompt_tokens", "type": "integer", "required": true, "description": "The number of prompt tokens used." }, { "parameter": "sample.usage.cached_tokens", "type": "integer", "required": true, "description": "The number of tokens retrieved from cache." }, { "parameter": "sample.error", "type": "object", "required": true, "description": "An object representing an error response from the Eval API." }, { "parameter": "sample.error.code", "type": "string", "required": true, "description": "The error code." }, { "parameter": "sample.error.message", "type": "string", "required": true, "description": "The error message." }, { "parameter": "sample.temperature", "type": "number", "required": true, "description": "The sampling temperature used." }, { "parameter": "sample.max_completion_tokens", "type": "integer", "required": true, "description": "The maximum number of tokens allowed for completion." }, { "parameter": "sample.top_p", "type": "number", "required": true, "description": "The top_p value used for sampling." }, { "parameter": "sample.seed", "type": "integer", "required": true, "description": "The seed used for generating the sample." } ], "status": [ "DOCUMENTED", "DEPRECATED" ], "verification": { "method": "docs_only" }, "sources": [ { "url": "https://developers.openai.com/api/reference/resources/evals", "retrieved_at": "2026-09-18" }, { "url": "https://developers.openai.com/api/openapi (openapi-master.yaml)", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/openai-platform-objects.json" }, { "provider": "openai", "api_family": "evals", "name": "EvalRunOutputItemResult", "spec_schema": "EvalRunOutputItemResult", "object_type": null, "description": "A single grader result for an evaluation run output item.", "required": [ "name", "score", "passed" ], "fields": [ { "parameter": "name", "type": "string", "required": true, "description": "The name of the grader." }, { "parameter": "type", "type": "string", "description": "The grader type (for example, \"string-check-grader\")." }, { "parameter": "score", "type": "number", "required": true, "description": "The numeric score produced by the grader." }, { "parameter": "passed", "type": "boolean", "required": true, "description": "Whether the grader considered the output a pass." }, { "parameter": "sample", "type": "object | null", "description": "Optional sample or intermediate data produced by the grader." } ], "status": [ "DOCUMENTED", "DEPRECATED" ], "verification": { "method": "docs_only" }, "sources": [ { "url": "https://developers.openai.com/api/reference/resources/evals", "retrieved_at": "2026-09-18" }, { "url": "https://developers.openai.com/api/openapi (openapi-master.yaml)", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/openai-platform-objects.json" }, { "provider": "openai", "api_family": "evals", "name": "EvalApiError", "spec_schema": "EvalApiError", "object_type": null, "description": "An object representing an error response from the Eval API.", "required": [ "code", "message" ], "fields": [ { "parameter": "code", "type": "string", "required": true, "description": "The error code." }, { "parameter": "message", "type": "string", "required": true, "description": "The error message." } ], "status": [ "DOCUMENTED", "DEPRECATED" ], "verification": { "method": "docs_only" }, "sources": [ { "url": "https://developers.openai.com/api/reference/resources/evals", "retrieved_at": "2026-09-18" }, { "url": "https://developers.openai.com/api/openapi (openapi-master.yaml)", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/openai-platform-objects.json" }, { "provider": "openai", "api_family": "files", "name": "ListFilesResponse", "spec_schema": "ListFilesResponse", "object_type": "list", "description": "", "required": [ "object", "data", "first_id", "last_id", "has_more" ], "fields": [ { "parameter": "object", "type": "string", "required": true, "description": "" }, { "parameter": "data", "type": "array", "required": true, "description": "" }, { "parameter": "data[].id", "type": "string", "required": true, "description": "The file identifier, which can be referenced in the API endpoints." }, { "parameter": "data[].bytes", "type": "integer", "required": true, "description": "The size of the file, in bytes." }, { "parameter": "data[].created_at", "type": "integer", "required": true, "description": "The Unix timestamp (in seconds) for when the file was created." }, { "parameter": "data[].expires_at", "type": "integer", "description": "The Unix timestamp (in seconds) for when the file will expire." }, { "parameter": "data[].filename", "type": "string", "required": true, "description": "The name of the file." }, { "parameter": "data[].object", "type": "string", "required": true, "enum": [ "file" ], "description": "The object type, which is always `file`." }, { "parameter": "data[].purpose", "type": "string", "required": true, "enum": [ "assistants", "assistants_output", "batch", "batch_output", "fine-tune", "fine-tune-results", "vision", "user_data" ], "description": "The intended purpose of the file. Supported values are `assistants`, `assistants_output`, `batch`, `batch_output`, `fine-tune`, `fine-tune-results`, `vision`, and `user_data`." }, { "parameter": "data[].status", "type": "string", "required": true, "enum": [ "uploaded", "processed", "error" ], "description": "Deprecated. The current status of the file, which can be either `uploaded`, `processed`, or `error`." }, { "parameter": "data[].status_details", "type": "string", "description": "Deprecated. For details on why a fine-tuning training file failed validation, see the `error` field on `fine_tuning.job`." }, { "parameter": "first_id", "type": "string", "required": true, "description": "" }, { "parameter": "last_id", "type": "string", "required": true, "description": "" }, { "parameter": "has_more", "type": "boolean", "required": true, "description": "" } ], "status": [ "DOCUMENTED" ], "verification": { "method": "docs_only" }, "sources": [ { "url": "https://developers.openai.com/api/reference/resources/files", "retrieved_at": "2026-09-18" }, { "url": "https://developers.openai.com/api/openapi (openapi-master.yaml)", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/openai-platform-objects.json" }, { "provider": "openai", "api_family": "batches", "name": "ListBatchesResponse", "spec_schema": "ListBatchesResponse", "object_type": "list", "description": "", "required": [ "object", "data", "has_more" ], "fields": [ { "parameter": "data", "type": "array", "required": true, "description": "" }, { "parameter": "data[].id", "type": "string", "required": true, "description": "" }, { "parameter": "data[].object", "type": "string", "required": true, "enum": [ "batch" ], "description": "The object type, which is always `batch`." }, { "parameter": "data[].endpoint", "type": "string", "required": true, "description": "The OpenAI API endpoint used by the batch." }, { "parameter": "data[].model", "type": "string", "description": "Model ID used to process the batch, like `gpt-6-astra`. OpenAI\noffers a wide range of models with different capabilities, performance\ncharacteristics, and price points. Refer to the [model\nguide](https://developers.openai.com/api/docs/models) to browse and compare available models." }, { "parameter": "data[].errors", "type": "object", "description": "" }, { "parameter": "data[].errors.object", "type": "string", "description": "The object type, which is always `list`." }, { "parameter": "data[].errors.data", "type": "array", "description": "" }, { "parameter": "data[].errors.data[].code", "type": "string", "description": "An error code identifying the error type." }, { "parameter": "data[].errors.data[].message", "type": "string", "description": "A human-readable message providing more details about the error." }, { "parameter": "data[].errors.data[].param", "type": "string | null", "description": "" }, { "parameter": "data[].errors.data[].line", "type": "integer | null", "description": "" }, { "parameter": "data[].input_file_id", "type": "string", "required": true, "description": "The ID of the input file for the batch." }, { "parameter": "data[].completion_window", "type": "string", "required": true, "description": "The time frame within which the batch should be processed." }, { "parameter": "data[].status", "type": "string", "required": true, "enum": [ "validating", "failed", "in_progress", "finalizing", "completed", "expired", "cancelling", "cancelled" ], "description": "The current status of the batch." }, { "parameter": "data[].output_file_id", "type": "string", "description": "The ID of the file containing the outputs of successfully executed requests." }, { "parameter": "data[].error_file_id", "type": "string", "description": "The ID of the file containing the outputs of requests with errors." }, { "parameter": "data[].created_at", "type": "integer", "required": true, "description": "The Unix timestamp (in seconds) for when the batch was created." }, { "parameter": "data[].in_progress_at", "type": "integer", "description": "The Unix timestamp (in seconds) for when the batch started processing." }, { "parameter": "data[].expires_at", "type": "integer", "description": "The Unix timestamp (in seconds) for when the batch will expire." }, { "parameter": "data[].finalizing_at", "type": "integer", "description": "The Unix timestamp (in seconds) for when the batch started finalizing." }, { "parameter": "data[].completed_at", "type": "integer", "description": "The Unix timestamp (in seconds) for when the batch was completed." }, { "parameter": "data[].failed_at", "type": "integer", "description": "The Unix timestamp (in seconds) for when the batch failed." }, { "parameter": "data[].expired_at", "type": "integer", "description": "The Unix timestamp (in seconds) for when the batch expired." }, { "parameter": "data[].cancelling_at", "type": "integer", "description": "The Unix timestamp (in seconds) for when the batch started cancelling." }, { "parameter": "data[].cancelled_at", "type": "integer", "description": "The Unix timestamp (in seconds) for when the batch was cancelled." }, { "parameter": "data[].request_counts", "type": "object", "description": "The request counts for different statuses within the batch." }, { "parameter": "data[].request_counts.total", "type": "integer", "required": true, "description": "Total number of requests in the batch." }, { "parameter": "data[].request_counts.completed", "type": "integer", "required": true, "description": "Number of requests that have been completed successfully." }, { "parameter": "data[].request_counts.failed", "type": "integer", "required": true, "description": "Number of requests that have failed." }, { "parameter": "data[].usage", "type": "object", "description": "Represents token usage details including input tokens, output tokens, a\nbreakdown of output tokens, and the total tokens used. Only populated on\nbatches created after September 7, 2025." }, { "parameter": "data[].usage.input_tokens", "type": "integer", "required": true, "description": "The number of input tokens." }, { "parameter": "data[].usage.input_tokens_details", "type": "object", "required": true, "description": "A detailed breakdown of the input tokens." }, { "parameter": "data[].usage.input_tokens_details.cached_tokens", "type": "integer", "required": true, "description": "The number of tokens that were retrieved from the cache. [More on\nprompt caching](https://developers.openai.com/api/docs/guides/prompt-caching)." }, { "parameter": "data[].usage.output_tokens", "type": "integer", "required": true, "description": "The number of output tokens." }, { "parameter": "data[].usage.output_tokens_details", "type": "object", "required": true, "description": "A detailed breakdown of the output tokens." }, { "parameter": "data[].usage.output_tokens_details.reasoning_tokens", "type": "integer", "required": true, "description": "The number of reasoning tokens." }, { "parameter": "data[].usage.total_tokens", "type": "integer", "required": true, "description": "The total number of tokens used." }, { "parameter": "data[].metadata", "type": "object | null", "description": "" }, { "parameter": "first_id", "type": "string", "description": "" }, { "parameter": "last_id", "type": "string", "description": "" }, { "parameter": "has_more", "type": "boolean", "required": true, "description": "" }, { "parameter": "object", "type": "string", "required": true, "enum": [ "list" ], "description": "" } ], "status": [ "DOCUMENTED" ], "verification": { "method": "docs_only" }, "sources": [ { "url": "https://developers.openai.com/api/reference/resources/batches", "retrieved_at": "2026-09-18" }, { "url": "https://developers.openai.com/api/openapi (openapi-master.yaml)", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/openai-platform-objects.json" }, { "provider": "openai", "api_family": "evals", "name": "EvalList", "spec_schema": "EvalList", "object_type": "list", "description": "An object representing a list of evals.", "required": [ "object", "data", "first_id", "last_id", "has_more" ], "fields": [ { "parameter": "object", "type": "string", "required": true, "enum": [ "list" ], "default": "list", "description": "The type of this object. It is always set to \"list\"." }, { "parameter": "data", "type": "array", "required": true, "description": "An array of eval objects." }, { "parameter": "data[].object", "type": "string", "required": true, "enum": [ "eval" ], "default": "eval", "description": "The object type." }, { "parameter": "data[].id", "type": "string", "required": true, "description": "Unique identifier for the evaluation." }, { "parameter": "data[].name", "type": "string", "required": true, "description": "The name of the evaluation." }, { "parameter": "data[].data_source_config", "type": "object", "required": true, "description": "Configuration of data sources used in runs of the evaluation." }, { "parameter": "data[].data_source_config.type", "type": "string", "required": true, "enum": [ "custom" ], "default": "custom", "description": "The type of data source. Always `custom`." }, { "parameter": "data[].data_source_config.schema", "type": "object", "required": true, "description": "The json schema for the run data source items.\nLearn how to build JSON schemas [here](https://json-schema.org/)." }, { "parameter": "data[].data_source_config.type", "type": "string", "required": true, "enum": [ "logs" ], "default": "logs", "description": "The type of data source. Always `logs`." }, { "parameter": "data[].data_source_config.metadata", "type": "object | null", "description": "" }, { "parameter": "data[].data_source_config.schema", "type": "object", "required": true, "description": "The json schema for the run data source items.\nLearn how to build JSON schemas [here](https://json-schema.org/)." }, { "parameter": "data[].data_source_config.type", "type": "string", "required": true, "enum": [ "stored_completions" ], "default": "stored_completions", "description": "The type of data source. Always `stored_completions`." }, { "parameter": "data[].data_source_config.metadata", "type": "object | null", "description": "" }, { "parameter": "data[].data_source_config.schema", "type": "object", "required": true, "description": "The json schema for the run data source items.\nLearn how to build JSON schemas [here](https://json-schema.org/)." }, { "parameter": "data[].testing_criteria", "type": "array", "required": true, "description": "A list of testing criteria." }, { "parameter": "data[].testing_criteria[].type", "type": "string", "required": true, "enum": [ "label_model" ], "description": "The object type, which is always `label_model`." }, { "parameter": "data[].testing_criteria[].name", "type": "string", "required": true, "description": "The name of the grader." }, { "parameter": "data[].testing_criteria[].model", "type": "string", "required": true, "description": "The model to use for the evaluation. Must support structured outputs." }, { "parameter": "data[].testing_criteria[].input", "type": "array", "required": true, "description": "" }, { "parameter": "data[].testing_criteria[].labels", "type": "array", "required": true, "description": "The labels to assign to each item in the evaluation." }, { "parameter": "data[].testing_criteria[].passing_labels", "type": "array", "required": true, "description": "The labels that indicate a passing result. Must be a subset of labels." }, { "parameter": "data[].testing_criteria[].type", "type": "string", "required": true, "enum": [ "string_check" ], "description": "The object type, which is always `string_check`." }, { "parameter": "data[].testing_criteria[].name", "type": "string", "required": true, "description": "The name of the grader." }, { "parameter": "data[].testing_criteria[].input", "type": "string", "required": true, "description": "The input text. This may include template strings." }, { "parameter": "data[].testing_criteria[].reference", "type": "string", "required": true, "description": "The reference text. This may include template strings." }, { "parameter": "data[].testing_criteria[].operation", "type": "string", "required": true, "enum": [ "eq", "ne", "like", "ilike" ], "description": "The string check operation to perform. One of `eq`, `ne`, `like`, or `ilike`." }, { "parameter": "data[].testing_criteria[].type", "type": "string", "required": true, "enum": [ "text_similarity" ], "default": "text_similarity", "description": "The type of grader." }, { "parameter": "data[].testing_criteria[].name", "type": "string", "required": true, "description": "The name of the grader." }, { "parameter": "data[].testing_criteria[].input", "type": "string", "required": true, "description": "The text being graded." }, { "parameter": "data[].testing_criteria[].reference", "type": "string", "required": true, "description": "The text being graded against." }, { "parameter": "data[].testing_criteria[].evaluation_metric", "type": "string", "required": true, "enum": [ "cosine", "fuzzy_match", "bleu", "gleu", "meteor", "rouge_1", "rouge_2", "rouge_3", "rouge_4", "rouge_5", "rouge_l" ], "description": "The evaluation metric to use. One of `cosine`, `fuzzy_match`, `bleu`, \n`gleu`, `meteor`, `rouge_1`, `rouge_2`, `rouge_3`, `rouge_4`, `rouge_5`, \nor `rouge_l`." }, { "parameter": "data[].testing_criteria[].pass_threshold", "type": "number", "required": true, "description": "The threshold for the score." }, { "parameter": "data[].testing_criteria[].type", "type": "string", "required": true, "enum": [ "python" ], "description": "The object type, which is always `python`." }, { "parameter": "data[].testing_criteria[].name", "type": "string", "required": true, "description": "The name of the grader." }, { "parameter": "data[].testing_criteria[].source", "type": "string", "required": true, "description": "The source code of the python script." }, { "parameter": "data[].testing_criteria[].image_tag", "type": "string", "description": "The image tag to use for the python script." }, { "parameter": "data[].testing_criteria[].pass_threshold", "type": "number", "description": "The threshold for the score." }, { "parameter": "data[].testing_criteria[].type", "type": "string", "required": true, "enum": [ "score_model" ], "description": "The object type, which is always `score_model`." }, { "parameter": "data[].testing_criteria[].name", "type": "string", "required": true, "description": "The name of the grader." }, { "parameter": "data[].testing_criteria[].model", "type": "string", "required": true, "description": "The model to use for the evaluation." }, { "parameter": "data[].testing_criteria[].sampling_params", "type": "object", "description": "The sampling parameters for the model." }, { "parameter": "data[].testing_criteria[].sampling_params.seed", "type": "integer | null", "description": "" }, { "parameter": "data[].testing_criteria[].sampling_params.top_p", "type": "number | null", "description": "" }, { "parameter": "data[].testing_criteria[].sampling_params.temperature", "type": "number | null", "description": "" }, { "parameter": "data[].testing_criteria[].sampling_params.max_completions_tokens", "type": "integer | null", "description": "" }, { "parameter": "data[].testing_criteria[].sampling_params.reasoning_effort", "type": "object", "description": "" }, { "parameter": "data[].testing_criteria[].input", "type": "array", "required": true, "description": "The input messages evaluated by the grader. Supports text, output text, input image, and input audio content blocks, and may include template strings." }, { "parameter": "data[].testing_criteria[].range", "type": "array", "description": "The range of the score. Defaults to `[0, 1]`." }, { "parameter": "data[].testing_criteria[].pass_threshold", "type": "number", "description": "The threshold for the score." }, { "parameter": "data[].created_at", "type": "integer", "required": true, "description": "The Unix timestamp (in seconds) for when the eval was created." }, { "parameter": "data[].metadata", "type": "object | null", "required": true, "description": "" }, { "parameter": "first_id", "type": "string", "required": true, "description": "The identifier of the first eval in the data array." }, { "parameter": "last_id", "type": "string", "required": true, "description": "The identifier of the last eval in the data array." }, { "parameter": "has_more", "type": "boolean", "required": true, "description": "Indicates whether there are more evals available." } ], "status": [ "DOCUMENTED", "DEPRECATED" ], "verification": { "method": "docs_only" }, "sources": [ { "url": "https://developers.openai.com/api/reference/resources/evals", "retrieved_at": "2026-09-18" }, { "url": "https://developers.openai.com/api/openapi (openapi-master.yaml)", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/openai-platform-objects.json" }, { "provider": "openai", "api_family": "evals", "name": "EvalRunList", "spec_schema": "EvalRunList", "object_type": "list", "description": "An object representing a list of runs for an evaluation.", "required": [ "object", "data", "first_id", "last_id", "has_more" ], "fields": [ { "parameter": "object", "type": "string", "required": true, "enum": [ "list" ], "default": "list", "description": "The type of this object. It is always set to \"list\"." }, { "parameter": "data", "type": "array", "required": true, "description": "An array of eval run objects." }, { "parameter": "data[].object", "type": "string", "required": true, "enum": [ "eval.run" ], "default": "eval.run", "description": "The type of the object. Always \"eval.run\"." }, { "parameter": "data[].id", "type": "string", "required": true, "description": "Unique identifier for the evaluation run." }, { "parameter": "data[].eval_id", "type": "string", "required": true, "description": "The identifier of the associated evaluation." }, { "parameter": "data[].status", "type": "string", "required": true, "description": "The status of the evaluation run." }, { "parameter": "data[].model", "type": "string", "required": true, "description": "The model that is evaluated, if applicable." }, { "parameter": "data[].name", "type": "string", "required": true, "description": "The name of the evaluation run." }, { "parameter": "data[].created_at", "type": "integer", "required": true, "description": "Unix timestamp (in seconds) when the evaluation run was created." }, { "parameter": "data[].report_url", "type": "string", "required": true, "description": "The URL to the rendered evaluation run report on the UI dashboard." }, { "parameter": "data[].result_counts", "type": "object", "required": true, "description": "Counters summarizing the outcomes of the evaluation run." }, { "parameter": "data[].result_counts.total", "type": "integer", "required": true, "description": "Total number of executed output items." }, { "parameter": "data[].result_counts.errored", "type": "integer", "required": true, "description": "Number of output items that resulted in an error." }, { "parameter": "data[].result_counts.failed", "type": "integer", "required": true, "description": "Number of output items that failed to pass the evaluation." }, { "parameter": "data[].result_counts.passed", "type": "integer", "required": true, "description": "Number of output items that passed the evaluation." }, { "parameter": "data[].per_model_usage", "type": "array", "required": true, "description": "Usage statistics for each model during the evaluation run." }, { "parameter": "data[].per_model_usage[].model_name", "type": "string", "required": true, "description": "The name of the model." }, { "parameter": "data[].per_model_usage[].invocation_count", "type": "integer", "required": true, "description": "The number of invocations." }, { "parameter": "data[].per_model_usage[].prompt_tokens", "type": "integer", "required": true, "description": "The number of prompt tokens used." }, { "parameter": "data[].per_model_usage[].completion_tokens", "type": "integer", "required": true, "description": "The number of completion tokens generated." }, { "parameter": "data[].per_model_usage[].total_tokens", "type": "integer", "required": true, "description": "The total number of tokens used." }, { "parameter": "data[].per_model_usage[].cached_tokens", "type": "integer", "required": true, "description": "The number of tokens retrieved from cache." }, { "parameter": "data[].per_testing_criteria_results", "type": "array", "required": true, "description": "Results per testing criteria applied during the evaluation run." }, { "parameter": "data[].per_testing_criteria_results[].testing_criteria", "type": "string", "required": true, "description": "A description of the testing criteria." }, { "parameter": "data[].per_testing_criteria_results[].passed", "type": "integer", "required": true, "description": "Number of tests passed for this criteria." }, { "parameter": "data[].per_testing_criteria_results[].failed", "type": "integer", "required": true, "description": "Number of tests failed for this criteria." }, { "parameter": "data[].data_source", "type": "object", "required": true, "description": "Information about the run's data source." }, { "parameter": "data[].data_source.type", "type": "string", "required": true, "enum": [ "jsonl" ], "default": "jsonl", "description": "The type of data source. Always `jsonl`." }, { "parameter": "data[].data_source.source", "type": "EvalJsonlFileContentSource | EvalJsonlFileIdSource", "required": true, "description": "Determines what populates the `item` namespace in the data source." }, { "parameter": "data[].data_source.type", "type": "string", "required": true, "enum": [ "completions" ], "default": "completions", "description": "The type of run data source. Always `completions`." }, { "parameter": "data[].data_source.input_messages", "type": "object | object", "description": "Used when sampling from a model. Dictates the structure of the messages passed into the model. Can either be a reference to a prebuilt trajectory (ie, `item.input_trajectory`), or a template with variable references to the `item` namespace." }, { "parameter": "data[].data_source.input_messages.type", "type": "string", "required": true, "enum": [ "template" ], "description": "The type of input messages. Always `template`." }, { "parameter": "data[].data_source.input_messages.template", "type": "array", "required": true, "description": "A list of chat messages forming the prompt or context. May include variable references to the `item` namespace, ie {{item.name}}." }, { "parameter": "data[].data_source.input_messages.type", "type": "string", "required": true, "enum": [ "item_reference" ], "description": "The type of input messages. Always `item_reference`." }, { "parameter": "data[].data_source.input_messages.item_reference", "type": "string", "required": true, "description": "A reference to a variable in the `item` namespace. Ie, \"item.input_trajectory\"" }, { "parameter": "data[].data_source.sampling_params", "type": "object", "description": "" }, { "parameter": "data[].data_source.sampling_params.reasoning_effort", "type": "object", "description": "" }, { "parameter": "data[].data_source.sampling_params.temperature", "type": "number", "default": 1, "description": "A higher temperature increases randomness in the outputs." }, { "parameter": "data[].data_source.sampling_params.max_completion_tokens", "type": "integer", "description": "The maximum number of tokens in the generated output." }, { "parameter": "data[].data_source.sampling_params.top_p", "type": "number", "default": 1, "description": "An alternative to temperature for nucleus sampling; 1.0 includes all tokens." }, { "parameter": "data[].data_source.sampling_params.seed", "type": "integer", "default": 42, "description": "A seed value to initialize the randomness, during sampling." }, { "parameter": "data[].data_source.sampling_params.response_format", "type": "ResponseFormatText | ResponseFormatJsonSchema | ResponseFormatJsonObject", "description": "An object specifying the format that the model must output.\n\nSetting to `{ \"type\": \"json_schema\", \"json_schema\": {...} }` enables\nStructured Outputs which ensures the model will match your supplied JSON\nschema. Learn more in the [Structured Outputs\nguide](https://developers.openai.com/api/docs/guide" }, { "parameter": "data[].data_source.sampling_params.tools", "type": "array", "description": "A list of tools the model may call. Currently, only functions are supported as a tool. Use this to provide a list of functions the model may generate JSON inputs for. A max of 128 functions are supported." }, { "parameter": "data[].data_source.model", "type": "string", "description": "The name of the model to use for generating completions (e.g. \"o3-mini\")." }, { "parameter": "data[].data_source.source", "type": "EvalJsonlFileContentSource | EvalJsonlFileIdSource | EvalStoredCompletionsSource", "required": true, "description": "Determines what populates the `item` namespace in this run's data source." }, { "parameter": "data[].data_source.type", "type": "string", "required": true, "enum": [ "responses" ], "default": "responses", "description": "The type of run data source. Always `responses`." }, { "parameter": "data[].data_source.input_messages", "type": "object | object", "description": "Used when sampling from a model. Dictates the structure of the messages passed into the model. Can either be a reference to a prebuilt trajectory (ie, `item.input_trajectory`), or a template with variable references to the `item` namespace." }, { "parameter": "data[].data_source.input_messages.type", "type": "string", "required": true, "enum": [ "template" ], "description": "The type of input messages. Always `template`." }, { "parameter": "data[].data_source.input_messages.template", "type": "array", "required": true, "description": "A list of chat messages forming the prompt or context. May include variable references to the `item` namespace, ie {{item.name}}." }, { "parameter": "data[].data_source.input_messages.type", "type": "string", "required": true, "enum": [ "item_reference" ], "description": "The type of input messages. Always `item_reference`." }, { "parameter": "data[].data_source.input_messages.item_reference", "type": "string", "required": true, "description": "A reference to a variable in the `item` namespace. Ie, \"item.name\"" }, { "parameter": "data[].data_source.sampling_params", "type": "object", "description": "" }, { "parameter": "data[].data_source.sampling_params.reasoning_effort", "type": "object", "description": "" }, { "parameter": "data[].data_source.sampling_params.temperature", "type": "number", "default": 1, "description": "A higher temperature increases randomness in the outputs." }, { "parameter": "data[].data_source.sampling_params.max_completion_tokens", "type": "integer", "description": "The maximum number of tokens in the generated output." }, { "parameter": "data[].data_source.sampling_params.top_p", "type": "number", "default": 1, "description": "An alternative to temperature for nucleus sampling; 1.0 includes all tokens." }, { "parameter": "data[].data_source.sampling_params.seed", "type": "integer", "default": 42, "description": "A seed value to initialize the randomness, during sampling." }, { "parameter": "data[].data_source.sampling_params.tools", "type": "array", "description": "An array of tools the model may call while generating a response. You\ncan specify which tool to use by setting the `tool_choice` parameter.\n\nThe two categories of tools you can provide the model are:\n\n- **Built-in tools**: Tools that are provided by OpenAI that extend the\n model's capabilities, lik" }, { "parameter": "data[].data_source.sampling_params.text", "type": "object", "description": "Configuration options for a text response from the model. Can be plain\ntext or structured JSON data. Learn more:\n- [Text inputs and outputs](https://developers.openai.com/api/docs/guides/text)\n- [Structured Outputs](https://developers.openai.com/api/docs/guides/structured-outputs)" }, { "parameter": "data[].data_source.model", "type": "string", "description": "The name of the model to use for generating completions (e.g. \"o3-mini\")." }, { "parameter": "data[].data_source.source", "type": "EvalJsonlFileContentSource | EvalJsonlFileIdSource | EvalResponsesSource", "required": true, "description": "Determines what populates the `item` namespace in this run's data source." }, { "parameter": "data[].metadata", "type": "object | null", "required": true, "description": "" }, { "parameter": "data[].error", "type": "object", "required": true, "description": "An object representing an error response from the Eval API." }, { "parameter": "data[].error.code", "type": "string", "required": true, "description": "The error code." }, { "parameter": "data[].error.message", "type": "string", "required": true, "description": "The error message." }, { "parameter": "first_id", "type": "string", "required": true, "description": "The identifier of the first eval run in the data array." }, { "parameter": "last_id", "type": "string", "required": true, "description": "The identifier of the last eval run in the data array." }, { "parameter": "has_more", "type": "boolean", "required": true, "description": "Indicates whether there are more evals available." } ], "status": [ "DOCUMENTED", "DEPRECATED" ], "verification": { "method": "docs_only" }, "sources": [ { "url": "https://developers.openai.com/api/reference/resources/evals", "retrieved_at": "2026-09-18" }, { "url": "https://developers.openai.com/api/openapi (openapi-master.yaml)", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/openai-platform-objects.json" }, { "provider": "openai", "api_family": "evals", "name": "EvalRunOutputItemList", "spec_schema": "EvalRunOutputItemList", "object_type": "list", "description": "An object representing a list of output items for an evaluation run.", "required": [ "object", "data", "first_id", "last_id", "has_more" ], "fields": [ { "parameter": "object", "type": "string", "required": true, "enum": [ "list" ], "default": "list", "description": "The type of this object. It is always set to \"list\"." }, { "parameter": "data", "type": "array", "required": true, "description": "An array of eval run output item objects." }, { "parameter": "data[].object", "type": "string", "required": true, "enum": [ "eval.run.output_item" ], "default": "eval.run.output_item", "description": "The type of the object. Always \"eval.run.output_item\"." }, { "parameter": "data[].id", "type": "string", "required": true, "description": "Unique identifier for the evaluation run output item." }, { "parameter": "data[].run_id", "type": "string", "required": true, "description": "The identifier of the evaluation run associated with this output item." }, { "parameter": "data[].eval_id", "type": "string", "required": true, "description": "The identifier of the evaluation group." }, { "parameter": "data[].created_at", "type": "integer", "required": true, "description": "Unix timestamp (in seconds) when the evaluation run was created." }, { "parameter": "data[].status", "type": "string", "required": true, "description": "The status of the evaluation run." }, { "parameter": "data[].datasource_item_id", "type": "integer", "required": true, "description": "The identifier for the data source item." }, { "parameter": "data[].datasource_item", "type": "object", "required": true, "description": "Details of the input data source item." }, { "parameter": "data[].results", "type": "array", "required": true, "description": "A list of grader results for this output item." }, { "parameter": "data[].results[].name", "type": "string", "required": true, "description": "The name of the grader." }, { "parameter": "data[].results[].type", "type": "string", "description": "The grader type (for example, \"string-check-grader\")." }, { "parameter": "data[].results[].score", "type": "number", "required": true, "description": "The numeric score produced by the grader." }, { "parameter": "data[].results[].passed", "type": "boolean", "required": true, "description": "Whether the grader considered the output a pass." }, { "parameter": "data[].results[].sample", "type": "object | null", "description": "Optional sample or intermediate data produced by the grader." }, { "parameter": "data[].sample", "type": "object", "required": true, "description": "A sample containing the input and output of the evaluation run." }, { "parameter": "data[].sample.input", "type": "array", "required": true, "description": "An array of input messages." }, { "parameter": "data[].sample.input[].role", "type": "string", "required": true, "description": "The role of the message sender (e.g., system, user, developer)." }, { "parameter": "data[].sample.input[].content", "type": "string", "required": true, "description": "The content of the message." }, { "parameter": "data[].sample.output", "type": "array", "required": true, "description": "An array of output messages." }, { "parameter": "data[].sample.output[].role", "type": "string", "description": "The role of the message (e.g. \"system\", \"assistant\", \"user\")." }, { "parameter": "data[].sample.output[].content", "type": "string", "description": "The content of the message." }, { "parameter": "data[].sample.finish_reason", "type": "string", "required": true, "description": "The reason why the sample generation was finished." }, { "parameter": "data[].sample.model", "type": "string", "required": true, "description": "The model used for generating the sample." }, { "parameter": "data[].sample.usage", "type": "object", "required": true, "description": "Token usage details for the sample." }, { "parameter": "data[].sample.usage.total_tokens", "type": "integer", "required": true, "description": "The total number of tokens used." }, { "parameter": "data[].sample.usage.completion_tokens", "type": "integer", "required": true, "description": "The number of completion tokens generated." }, { "parameter": "data[].sample.usage.prompt_tokens", "type": "integer", "required": true, "description": "The number of prompt tokens used." }, { "parameter": "data[].sample.usage.cached_tokens", "type": "integer", "required": true, "description": "The number of tokens retrieved from cache." }, { "parameter": "data[].sample.error", "type": "object", "required": true, "description": "An object representing an error response from the Eval API." }, { "parameter": "data[].sample.error.code", "type": "string", "required": true, "description": "The error code." }, { "parameter": "data[].sample.error.message", "type": "string", "required": true, "description": "The error message." }, { "parameter": "data[].sample.temperature", "type": "number", "required": true, "description": "The sampling temperature used." }, { "parameter": "data[].sample.max_completion_tokens", "type": "integer", "required": true, "description": "The maximum number of tokens allowed for completion." }, { "parameter": "data[].sample.top_p", "type": "number", "required": true, "description": "The top_p value used for sampling." }, { "parameter": "data[].sample.seed", "type": "integer", "required": true, "description": "The seed used for generating the sample." }, { "parameter": "first_id", "type": "string", "required": true, "description": "The identifier of the first eval run output item in the data array." }, { "parameter": "last_id", "type": "string", "required": true, "description": "The identifier of the last eval run output item in the data array." }, { "parameter": "has_more", "type": "boolean", "required": true, "description": "Indicates whether there are more eval run output items available." } ], "status": [ "DOCUMENTED", "DEPRECATED" ], "verification": { "method": "docs_only" }, "sources": [ { "url": "https://developers.openai.com/api/reference/resources/evals", "retrieved_at": "2026-09-18" }, { "url": "https://developers.openai.com/api/openapi (openapi-master.yaml)", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/openai-platform-objects.json" }, { "provider": "openai", "api_family": "vector_stores", "name": "ComparisonFilter", "spec_schema": "ComparisonFilter", "object_type": null, "description": "A filter used to compare a specified attribute key to a given value using a defined comparison operation.", "required": [ "type", "key", "value" ], "fields": [ { "parameter": "type", "type": "string", "required": true, "enum": [ "eq", "ne", "gt", "gte", "lt", "lte", "in", "nin" ], "default": "eq", "description": "Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`.\n- `eq`: equals\n- `ne`: not equal\n- `gt`: greater than\n- `gte`: greater than or equal\n- `lt`: less than\n- `lte`: less than or equal\n- `in`: in\n- `nin`: not in" }, { "parameter": "key", "type": "string", "required": true, "description": "The key to compare against the value." }, { "parameter": "value", "type": "string | number | boolean | array", "required": true, "description": "The value to compare against the attribute key; supports string, number, or boolean types." } ], "status": [ "DOCUMENTED" ], "verification": { "method": "docs_only" }, "sources": [ { "url": "https://developers.openai.com/api/reference/resources/vector_stores", "retrieved_at": "2026-09-18" }, { "url": "https://developers.openai.com/api/openapi (openapi-master.yaml)", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/openai-platform-objects.json" }, { "provider": "openai", "api_family": "vector_stores", "name": "CompoundFilter", "spec_schema": "CompoundFilter", "object_type": null, "description": "Combine multiple filters using `and` or `or`.", "required": [ "type", "filters" ], "fields": [ { "parameter": "type", "type": "string", "required": true, "enum": [ "and", "or" ], "description": "Type of operation: `and` or `or`." }, { "parameter": "filters", "type": "array", "required": true, "description": "Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`." }, { "parameter": "filters[].type", "type": "string", "required": true, "enum": [ "eq", "ne", "gt", "gte", "lt", "lte", "in", "nin" ], "default": "eq", "description": "Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`.\n- `eq`: equals\n- `ne`: not equal\n- `gt`: greater than\n- `gte`: greater than or equal\n- `lt`: less than\n- `lte`: less than or equal\n- `in`: in\n- `nin`: not in" }, { "parameter": "filters[].key", "type": "string", "required": true, "description": "The key to compare against the value." }, { "parameter": "filters[].value", "type": "string | number | boolean | array", "required": true, "description": "The value to compare against the attribute key; supports string, number, or boolean types." } ], "status": [ "DOCUMENTED" ], "verification": { "method": "docs_only" }, "sources": [ { "url": "https://developers.openai.com/api/reference/resources/vector_stores", "retrieved_at": "2026-09-18" }, { "url": "https://developers.openai.com/api/openapi (openapi-master.yaml)", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/openai-platform-objects.json" }, { "provider": "openai", "api_family": "vector_stores", "name": "StaticChunkingStrategy", "spec_schema": "StaticChunkingStrategy", "object_type": null, "description": "", "required": [ "max_chunk_size_tokens", "chunk_overlap_tokens" ], "fields": [ { "parameter": "max_chunk_size_tokens", "type": "integer", "required": true, "minimum": 100, "maximum": 4096, "description": "The maximum number of tokens in each chunk. The default value is `800`. The minimum value is `100` and the maximum value is `4096`." }, { "parameter": "chunk_overlap_tokens", "type": "integer", "required": true, "description": "The number of tokens that overlap between chunks. The default value is `400`.\n\nNote that the overlap must not exceed half of `max_chunk_size_tokens`." } ], "status": [ "DOCUMENTED" ], "verification": { "method": "docs_only" }, "sources": [ { "url": "https://developers.openai.com/api/reference/resources/vector_stores", "retrieved_at": "2026-09-18" }, { "url": "https://developers.openai.com/api/openapi (openapi-master.yaml)", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/openai-platform-objects.json" }, { "provider": "openai", "api_family": "vector_stores", "name": "VectorStoreExpirationAfter", "spec_schema": "VectorStoreExpirationAfter", "object_type": null, "description": "The expiration policy for a vector store.", "required": [ "anchor", "days" ], "fields": [ { "parameter": "anchor", "type": "string", "required": true, "enum": [ "last_active_at" ], "description": "Anchor timestamp after which the expiration policy applies. Supported anchors: `last_active_at`." }, { "parameter": "days", "type": "integer", "required": true, "minimum": 1, "maximum": 365, "description": "The number of days after the anchor time that the vector store will expire." } ], "status": [ "DOCUMENTED" ], "verification": { "method": "docs_only" }, "sources": [ { "url": "https://developers.openai.com/api/reference/resources/vector_stores", "retrieved_at": "2026-09-18" }, { "url": "https://developers.openai.com/api/openapi (openapi-master.yaml)", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/openai-platform-objects.json" }, { "provider": "openai", "api_family": "files", "name": "FileExpirationAfter", "spec_schema": "FileExpirationAfter", "object_type": null, "description": "The expiration policy for a file. By default, files with `purpose=batch` expire after 30 days and all other files are persisted until they are manually deleted.", "required": [ "anchor", "seconds" ], "fields": [ { "parameter": "anchor", "type": "string", "required": true, "enum": [ "created_at" ], "description": "Anchor timestamp after which the expiration policy applies. Supported anchors: `created_at`." }, { "parameter": "seconds", "type": "integer", "required": true, "minimum": 3600, "maximum": 2592000, "description": "The number of seconds after the anchor time that the file will expire. Must be between 3600 (1 hour) and 2592000 (30 days)." } ], "status": [ "DOCUMENTED" ], "verification": { "method": "docs_only" }, "sources": [ { "url": "https://developers.openai.com/api/reference/resources/files", "retrieved_at": "2026-09-18" }, { "url": "https://developers.openai.com/api/openapi (openapi-master.yaml)", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/openai-platform-objects.json" }, { "provider": "openai", "api_family": "batches", "name": "BatchFileExpirationAfter", "spec_schema": "BatchFileExpirationAfter", "object_type": null, "description": "The expiration policy for the output and/or error file that are generated for a batch.", "required": [ "anchor", "seconds" ], "fields": [ { "parameter": "anchor", "type": "string", "required": true, "enum": [ "created_at" ], "description": "Anchor timestamp after which the expiration policy applies. Supported anchors: `created_at`. Note that the anchor is the file creation time, not the time the batch is created." }, { "parameter": "seconds", "type": "integer", "required": true, "minimum": 3600, "maximum": 2592000, "description": "The number of seconds after the anchor time that the file will expire. Must be between 3600 (1 hour) and 2592000 (30 days)." } ], "status": [ "DOCUMENTED" ], "verification": { "method": "docs_only" }, "sources": [ { "url": "https://developers.openai.com/api/reference/resources/batches", "retrieved_at": "2026-09-18" }, { "url": "https://developers.openai.com/api/openapi (openapi-master.yaml)", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/openai-platform-objects.json" }, { "provider": "openai", "api_family": "fine_tuning", "name": "FineTuneMethod", "spec_schema": "FineTuneMethod", "object_type": null, "description": "The method used for fine-tuning.", "required": [ "type" ], "fields": [ { "parameter": "type", "type": "string", "required": true, "enum": [ "supervised", "dpo", "reinforcement" ], "description": "The type of method. Is either `supervised`, `dpo`, or `reinforcement`." }, { "parameter": "supervised", "type": "object", "description": "Configuration for the supervised fine-tuning method." }, { "parameter": "supervised.hyperparameters", "type": "object", "description": "The hyperparameters used for the fine-tuning job." }, { "parameter": "supervised.hyperparameters.batch_size", "type": "string | integer", "default": "auto", "description": "Number of examples in each batch. A larger batch size means that model parameters are updated less frequently, but with lower variance." }, { "parameter": "supervised.hyperparameters.learning_rate_multiplier", "type": "string | number", "default": "auto", "description": "Scaling factor for the learning rate. A smaller learning rate may be useful to avoid overfitting." }, { "parameter": "supervised.hyperparameters.n_epochs", "type": "string | integer", "default": "auto", "description": "The number of epochs to train the model for. An epoch refers to one full cycle through the training dataset." }, { "parameter": "dpo", "type": "object", "description": "Configuration for the DPO fine-tuning method." }, { "parameter": "dpo.hyperparameters", "type": "object", "description": "The hyperparameters used for the DPO fine-tuning job." }, { "parameter": "dpo.hyperparameters.beta", "type": "string | number", "default": "auto", "description": "The beta value for the DPO method. A higher beta value will increase the weight of the penalty between the policy and reference model." }, { "parameter": "dpo.hyperparameters.batch_size", "type": "string | integer", "default": "auto", "description": "Number of examples in each batch. A larger batch size means that model parameters are updated less frequently, but with lower variance." }, { "parameter": "dpo.hyperparameters.learning_rate_multiplier", "type": "string | number", "default": "auto", "description": "Scaling factor for the learning rate. A smaller learning rate may be useful to avoid overfitting." }, { "parameter": "dpo.hyperparameters.n_epochs", "type": "string | integer", "default": "auto", "description": "The number of epochs to train the model for. An epoch refers to one full cycle through the training dataset." }, { "parameter": "reinforcement", "type": "object", "description": "Configuration for the reinforcement fine-tuning method." }, { "parameter": "reinforcement.grader", "type": "object", "required": true, "description": "The grader used for the fine-tuning job." }, { "parameter": "reinforcement.grader.type", "type": "string", "required": true, "enum": [ "string_check" ], "description": "The object type, which is always `string_check`." }, { "parameter": "reinforcement.grader.name", "type": "string", "required": true, "description": "The name of the grader." }, { "parameter": "reinforcement.grader.input", "type": "string", "required": true, "description": "The input text. This may include template strings." }, { "parameter": "reinforcement.grader.reference", "type": "string", "required": true, "description": "The reference text. This may include template strings." }, { "parameter": "reinforcement.grader.operation", "type": "string", "required": true, "enum": [ "eq", "ne", "like", "ilike" ], "description": "The string check operation to perform. One of `eq`, `ne`, `like`, or `ilike`." }, { "parameter": "reinforcement.grader.type", "type": "string", "required": true, "enum": [ "text_similarity" ], "default": "text_similarity", "description": "The type of grader." }, { "parameter": "reinforcement.grader.name", "type": "string", "required": true, "description": "The name of the grader." }, { "parameter": "reinforcement.grader.input", "type": "string", "required": true, "description": "The text being graded." }, { "parameter": "reinforcement.grader.reference", "type": "string", "required": true, "description": "The text being graded against." }, { "parameter": "reinforcement.grader.evaluation_metric", "type": "string", "required": true, "enum": [ "cosine", "fuzzy_match", "bleu", "gleu", "meteor", "rouge_1", "rouge_2", "rouge_3", "rouge_4", "rouge_5", "rouge_l" ], "description": "The evaluation metric to use. One of `cosine`, `fuzzy_match`, `bleu`, \n`gleu`, `meteor`, `rouge_1`, `rouge_2`, `rouge_3`, `rouge_4`, `rouge_5`, \nor `rouge_l`." }, { "parameter": "reinforcement.grader.type", "type": "string", "required": true, "enum": [ "python" ], "description": "The object type, which is always `python`." }, { "parameter": "reinforcement.grader.name", "type": "string", "required": true, "description": "The name of the grader." }, { "parameter": "reinforcement.grader.source", "type": "string", "required": true, "description": "The source code of the python script." }, { "parameter": "reinforcement.grader.image_tag", "type": "string", "description": "The image tag to use for the python script." }, { "parameter": "reinforcement.grader.type", "type": "string", "required": true, "enum": [ "score_model" ], "description": "The object type, which is always `score_model`." }, { "parameter": "reinforcement.grader.name", "type": "string", "required": true, "description": "The name of the grader." }, { "parameter": "reinforcement.grader.model", "type": "string", "required": true, "description": "The model to use for the evaluation." }, { "parameter": "reinforcement.grader.sampling_params", "type": "object", "description": "The sampling parameters for the model." }, { "parameter": "reinforcement.grader.sampling_params.seed", "type": "integer | null", "description": "" }, { "parameter": "reinforcement.grader.sampling_params.top_p", "type": "number | null", "description": "" }, { "parameter": "reinforcement.grader.sampling_params.temperature", "type": "number | null", "description": "" }, { "parameter": "reinforcement.grader.sampling_params.max_completions_tokens", "type": "integer | null", "description": "" }, { "parameter": "reinforcement.grader.sampling_params.reasoning_effort", "type": "string | null", "description": "" }, { "parameter": "reinforcement.grader.input", "type": "array", "required": true, "description": "The input messages evaluated by the grader. Supports text, output text, input image, and input audio content blocks, and may include template strings." }, { "parameter": "reinforcement.grader.input[].role", "type": "string", "required": true, "enum": [ "user", "assistant", "system", "developer" ], "description": "The role of the message input. One of `user`, `assistant`, `system`, or\n`developer`." }, { "parameter": "reinforcement.grader.input[].content", "required": true, "type": "object", "description": "" }, { "parameter": "reinforcement.grader.input[].type", "type": "string", "enum": [ "message" ], "description": "The type of the message input. Always `message`." }, { "parameter": "reinforcement.grader.range", "type": "array", "description": "The range of the score. Defaults to `[0, 1]`." }, { "parameter": "reinforcement.grader.type", "type": "string", "required": true, "enum": [ "multi" ], "default": "multi", "description": "The object type, which is always `multi`." }, { "parameter": "reinforcement.grader.name", "type": "string", "required": true, "description": "The name of the grader." }, { "parameter": "reinforcement.grader.graders", "type": "object | object | object | object | object", "required": true, "description": "" }, { "parameter": "reinforcement.grader.graders.type", "type": "string", "required": true, "enum": [ "string_check" ], "description": "The object type, which is always `string_check`." }, { "parameter": "reinforcement.grader.graders.name", "type": "string", "required": true, "description": "The name of the grader." }, { "parameter": "reinforcement.grader.graders.input", "type": "string", "required": true, "description": "The input text. This may include template strings." }, { "parameter": "reinforcement.grader.graders.reference", "type": "string", "required": true, "description": "The reference text. This may include template strings." }, { "parameter": "reinforcement.grader.graders.operation", "type": "string", "required": true, "enum": [ "eq", "ne", "like", "ilike" ], "description": "The string check operation to perform. One of `eq`, `ne`, `like`, or `ilike`." }, { "parameter": "reinforcement.grader.graders.type", "type": "string", "required": true, "enum": [ "text_similarity" ], "default": "text_similarity", "description": "The type of grader." }, { "parameter": "reinforcement.grader.graders.name", "type": "string", "required": true, "description": "The name of the grader." }, { "parameter": "reinforcement.grader.graders.input", "type": "string", "required": true, "description": "The text being graded." }, { "parameter": "reinforcement.grader.graders.reference", "type": "string", "required": true, "description": "The text being graded against." }, { "parameter": "reinforcement.grader.graders.evaluation_metric", "type": "string", "required": true, "enum": [ "cosine", "fuzzy_match", "bleu", "gleu", "meteor", "rouge_1", "rouge_2", "rouge_3", "rouge_4", "rouge_5", "rouge_l" ], "description": "The evaluation metric to use. One of `cosine`, `fuzzy_match`, `bleu`, \n`gleu`, `meteor`, `rouge_1`, `rouge_2`, `rouge_3`, `rouge_4`, `rouge_5`, \nor `rouge_l`." }, { "parameter": "reinforcement.grader.graders.type", "type": "string", "required": true, "enum": [ "python" ], "description": "The object type, which is always `python`." }, { "parameter": "reinforcement.grader.graders.name", "type": "string", "required": true, "description": "The name of the grader." }, { "parameter": "reinforcement.grader.graders.source", "type": "string", "required": true, "description": "The source code of the python script." }, { "parameter": "reinforcement.grader.graders.image_tag", "type": "string", "description": "The image tag to use for the python script." }, { "parameter": "reinforcement.grader.graders.type", "type": "string", "required": true, "enum": [ "score_model" ], "description": "The object type, which is always `score_model`." }, { "parameter": "reinforcement.grader.graders.name", "type": "string", "required": true, "description": "The name of the grader." }, { "parameter": "reinforcement.grader.graders.model", "type": "string", "required": true, "description": "The model to use for the evaluation." }, { "parameter": "reinforcement.grader.graders.sampling_params", "type": "object", "description": "The sampling parameters for the model." }, { "parameter": "reinforcement.grader.graders.input", "type": "array", "required": true, "description": "The input messages evaluated by the grader. Supports text, output text, input image, and input audio content blocks, and may include template strings." }, { "parameter": "reinforcement.grader.graders.range", "type": "array", "description": "The range of the score. Defaults to `[0, 1]`." }, { "parameter": "reinforcement.grader.graders.type", "type": "string", "required": true, "enum": [ "label_model" ], "description": "The object type, which is always `label_model`." }, { "parameter": "reinforcement.grader.graders.name", "type": "string", "required": true, "description": "The name of the grader." }, { "parameter": "reinforcement.grader.graders.model", "type": "string", "required": true, "description": "The model to use for the evaluation. Must support structured outputs." }, { "parameter": "reinforcement.grader.graders.input", "type": "array", "required": true, "description": "" }, { "parameter": "reinforcement.grader.graders.labels", "type": "array", "required": true, "description": "The labels to assign to each item in the evaluation." }, { "parameter": "reinforcement.grader.graders.passing_labels", "type": "array", "required": true, "description": "The labels that indicate a passing result. Must be a subset of labels." }, { "parameter": "reinforcement.grader.calculate_output", "type": "string", "required": true, "description": "A formula to calculate the output based on grader results." }, { "parameter": "reinforcement.hyperparameters", "type": "object", "description": "The hyperparameters used for the reinforcement fine-tuning job." }, { "parameter": "reinforcement.hyperparameters.batch_size", "type": "string | integer", "default": "auto", "description": "Number of examples in each batch. A larger batch size means that model parameters are updated less frequently, but with lower variance." }, { "parameter": "reinforcement.hyperparameters.learning_rate_multiplier", "type": "string | number", "default": "auto", "description": "Scaling factor for the learning rate. A smaller learning rate may be useful to avoid overfitting." }, { "parameter": "reinforcement.hyperparameters.n_epochs", "type": "string | integer", "default": "auto", "description": "The number of epochs to train the model for. An epoch refers to one full cycle through the training dataset." }, { "parameter": "reinforcement.hyperparameters.reasoning_effort", "type": "string", "enum": [ "default", "low", "medium", "high" ], "default": "default", "description": "Level of reasoning effort." }, { "parameter": "reinforcement.hyperparameters.compute_multiplier", "type": "string | number", "default": "auto", "description": "Multiplier on amount of compute used for exploring search space during training." }, { "parameter": "reinforcement.hyperparameters.eval_interval", "type": "string | integer", "default": "auto", "description": "The number of training steps between evaluation runs." }, { "parameter": "reinforcement.hyperparameters.eval_samples", "type": "string | integer", "default": "auto", "description": "Number of evaluation samples to generate per training step." } ], "status": [ "DOCUMENTED", "DEPRECATED" ], "verification": { "method": "docs_only" }, "sources": [ { "url": "https://developers.openai.com/api/reference/resources/fine_tuning", "retrieved_at": "2026-09-18" }, { "url": "https://developers.openai.com/api/openapi (openapi-master.yaml)", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/openai-platform-objects.json" }, { "provider": "openai", "api_family": "fine_tuning", "name": "FineTuneSupervisedHyperparameters", "spec_schema": "FineTuneSupervisedHyperparameters", "object_type": null, "description": "The hyperparameters used for the fine-tuning job.", "required": [], "fields": [ { "parameter": "batch_size", "type": "string | integer", "default": "auto", "description": "Number of examples in each batch. A larger batch size means that model parameters are updated less frequently, but with lower variance." }, { "parameter": "learning_rate_multiplier", "type": "string | number", "default": "auto", "description": "Scaling factor for the learning rate. A smaller learning rate may be useful to avoid overfitting." }, { "parameter": "n_epochs", "type": "string | integer", "default": "auto", "description": "The number of epochs to train the model for. An epoch refers to one full cycle through the training dataset." } ], "status": [ "DOCUMENTED", "DEPRECATED" ], "verification": { "method": "docs_only" }, "sources": [ { "url": "https://developers.openai.com/api/reference/resources/fine_tuning", "retrieved_at": "2026-09-18" }, { "url": "https://developers.openai.com/api/openapi (openapi-master.yaml)", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/openai-platform-objects.json" }, { "provider": "openai", "api_family": "fine_tuning", "name": "FineTuneDPOHyperparameters", "spec_schema": "FineTuneDPOHyperparameters", "object_type": null, "description": "The hyperparameters used for the DPO fine-tuning job.", "required": [], "fields": [ { "parameter": "beta", "type": "string | number", "default": "auto", "description": "The beta value for the DPO method. A higher beta value will increase the weight of the penalty between the policy and reference model." }, { "parameter": "batch_size", "type": "string | integer", "default": "auto", "description": "Number of examples in each batch. A larger batch size means that model parameters are updated less frequently, but with lower variance." }, { "parameter": "learning_rate_multiplier", "type": "string | number", "default": "auto", "description": "Scaling factor for the learning rate. A smaller learning rate may be useful to avoid overfitting." }, { "parameter": "n_epochs", "type": "string | integer", "default": "auto", "description": "The number of epochs to train the model for. An epoch refers to one full cycle through the training dataset." } ], "status": [ "DOCUMENTED", "DEPRECATED" ], "verification": { "method": "docs_only" }, "sources": [ { "url": "https://developers.openai.com/api/reference/resources/fine_tuning", "retrieved_at": "2026-09-18" }, { "url": "https://developers.openai.com/api/openapi (openapi-master.yaml)", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/openai-platform-objects.json" }, { "provider": "openai", "api_family": "fine_tuning", "name": "FineTuneReinforcementHyperparameters", "spec_schema": "FineTuneReinforcementHyperparameters", "object_type": null, "description": "The hyperparameters used for the reinforcement fine-tuning job.", "required": [], "fields": [ { "parameter": "batch_size", "type": "string | integer", "default": "auto", "description": "Number of examples in each batch. A larger batch size means that model parameters are updated less frequently, but with lower variance." }, { "parameter": "learning_rate_multiplier", "type": "string | number", "default": "auto", "description": "Scaling factor for the learning rate. A smaller learning rate may be useful to avoid overfitting." }, { "parameter": "n_epochs", "type": "string | integer", "default": "auto", "description": "The number of epochs to train the model for. An epoch refers to one full cycle through the training dataset." }, { "parameter": "reasoning_effort", "type": "string", "enum": [ "default", "low", "medium", "high" ], "default": "default", "description": "Level of reasoning effort." }, { "parameter": "compute_multiplier", "type": "string | number", "default": "auto", "description": "Multiplier on amount of compute used for exploring search space during training." }, { "parameter": "eval_interval", "type": "string | integer", "default": "auto", "description": "The number of training steps between evaluation runs." }, { "parameter": "eval_samples", "type": "string | integer", "default": "auto", "description": "Number of evaluation samples to generate per training step." } ], "status": [ "DOCUMENTED", "DEPRECATED" ], "verification": { "method": "docs_only" }, "sources": [ { "url": "https://developers.openai.com/api/reference/resources/fine_tuning", "retrieved_at": "2026-09-18" }, { "url": "https://developers.openai.com/api/openapi (openapi-master.yaml)", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/openai-platform-objects.json" }, { "provider": "openai", "api_family": "fine_tuning", "name": "FineTuneChatCompletionRequestAssistantMessage", "spec_schema": "FineTuneChatCompletionRequestAssistantMessage", "object_type": null, "description": "", "required": [ "role" ], "fields": [ { "parameter": "weight", "type": "integer", "enum": [ 0, 1 ], "description": "Controls whether the assistant message is trained against (0 or 1)" }, { "parameter": "content", "type": "object | null", "description": "" }, { "parameter": "refusal", "type": "string | null", "description": "" }, { "parameter": "role", "type": "string", "required": true, "enum": [ "assistant" ], "description": "The role of the messages author, in this case `assistant`." }, { "parameter": "name", "type": "string", "description": "An optional name for the participant. Provides the model information to differentiate between participants of the same role." }, { "parameter": "audio", "type": "object | null", "description": "" }, { "parameter": "audio.id", "type": "string", "required": true, "description": "Unique identifier for a previous audio response from the model." }, { "parameter": "tool_calls", "type": "array", "description": "The tool calls generated by the model, such as function calls." }, { "parameter": "tool_calls[].id", "type": "string", "required": true, "description": "The ID of the tool call." }, { "parameter": "tool_calls[].type", "type": "string", "required": true, "enum": [ "function" ], "description": "The type of the tool. Currently, only `function` is supported." }, { "parameter": "tool_calls[].function", "type": "object", "required": true, "description": "The function that the model called." }, { "parameter": "tool_calls[].function.name", "type": "string", "required": true, "description": "The name of the function to call." }, { "parameter": "tool_calls[].function.arguments", "type": "string", "required": true, "description": "The arguments to call the function with, as generated by the model in JSON format. Note that the model does not always generate valid JSON, and may hallucinate parameters not defined by your function schema. Validate the arguments in your code before calling your function." }, { "parameter": "tool_calls[].id", "type": "string", "required": true, "description": "The ID of the tool call." }, { "parameter": "tool_calls[].type", "type": "string", "required": true, "enum": [ "custom" ], "description": "The type of the tool. Always `custom`." }, { "parameter": "tool_calls[].custom", "type": "object", "required": true, "description": "The custom tool that the model called." }, { "parameter": "tool_calls[].custom.name", "type": "string", "required": true, "description": "The name of the custom tool to call." }, { "parameter": "tool_calls[].custom.input", "type": "string", "required": true, "description": "The input for the custom tool call generated by the model." }, { "parameter": "function_call", "type": "object | null", "description": "" }, { "parameter": "function_call.arguments", "type": "string", "required": true, "description": "The arguments to call the function with, as generated by the model in JSON format. Note that the model does not always generate valid JSON, and may hallucinate parameters not defined by your function schema. Validate the arguments in your code before calling your function." }, { "parameter": "function_call.name", "type": "string", "required": true, "description": "The name of the function to call." } ], "status": [ "DOCUMENTED", "DEPRECATED" ], "verification": { "method": "docs_only" }, "sources": [ { "url": "https://developers.openai.com/api/reference/resources/fine_tuning", "retrieved_at": "2026-09-18" }, { "url": "https://developers.openai.com/api/openapi (openapi-master.yaml)", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/openai-platform-objects.json" }, { "provider": "openai", "api_family": "evals", "name": "EvalCustomDataSourceConfig", "spec_schema": "EvalCustomDataSourceConfig", "object_type": null, "description": "A CustomDataSourceConfig which specifies the schema of your `item` and optionally `sample` namespaces.\nThe response schema defines the shape of the data that will be:\n- Used to define your testing criteria and\n- What data is required when creating a run", "required": [ "type", "schema" ], "fields": [ { "parameter": "type", "type": "string", "required": true, "enum": [ "custom" ], "default": "custom", "description": "The type of data source. Always `custom`." }, { "parameter": "schema", "type": "object", "required": true, "description": "The json schema for the run data source items.\nLearn how to build JSON schemas [here](https://json-schema.org/)." } ], "status": [ "DOCUMENTED", "DEPRECATED" ], "verification": { "method": "docs_only" }, "sources": [ { "url": "https://developers.openai.com/api/reference/resources/evals", "retrieved_at": "2026-09-18" }, { "url": "https://developers.openai.com/api/openapi (openapi-master.yaml)", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/openai-platform-objects.json" }, { "provider": "openai", "api_family": "evals", "name": "EvalLogsDataSourceConfig", "spec_schema": "EvalLogsDataSourceConfig", "object_type": null, "description": "A LogsDataSourceConfig which specifies the metadata property of your logs query.\nThis is usually metadata like `usecase=chatbot` or `prompt-version=v2`, etc.\nThe schema returned by this data source config is used to defined what variables are available in your evals.\n`item` and `sample` are both defined when using this data source config.", "required": [ "type", "schema" ], "fields": [ { "parameter": "type", "type": "string", "required": true, "enum": [ "logs" ], "default": "logs", "description": "The type of data source. Always `logs`." }, { "parameter": "metadata", "type": "object | null", "description": "" }, { "parameter": "schema", "type": "object", "required": true, "description": "The json schema for the run data source items.\nLearn how to build JSON schemas [here](https://json-schema.org/)." } ], "status": [ "DOCUMENTED", "DEPRECATED" ], "verification": { "method": "docs_only" }, "sources": [ { "url": "https://developers.openai.com/api/reference/resources/evals", "retrieved_at": "2026-09-18" }, { "url": "https://developers.openai.com/api/openapi (openapi-master.yaml)", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/openai-platform-objects.json" }, { "provider": "openai", "api_family": "evals", "name": "EvalStoredCompletionsDataSourceConfig", "spec_schema": "EvalStoredCompletionsDataSourceConfig", "object_type": null, "description": "Deprecated in favor of LogsDataSourceConfig.", "required": [ "type", "schema" ], "fields": [ { "parameter": "type", "type": "string", "required": true, "enum": [ "stored_completions" ], "default": "stored_completions", "description": "The type of data source. Always `stored_completions`." }, { "parameter": "metadata", "type": "object | null", "description": "" }, { "parameter": "schema", "type": "object", "required": true, "description": "The json schema for the run data source items.\nLearn how to build JSON schemas [here](https://json-schema.org/)." } ], "status": [ "DOCUMENTED", "DEPRECATED" ], "verification": { "method": "docs_only" }, "sources": [ { "url": "https://developers.openai.com/api/reference/resources/evals", "retrieved_at": "2026-09-18" }, { "url": "https://developers.openai.com/api/openapi (openapi-master.yaml)", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/openai-platform-objects.json" }, { "provider": "openai", "api_family": "evals", "name": "EvalJsonlFileContentSource", "spec_schema": "EvalJsonlFileContentSource", "object_type": null, "description": "", "required": [ "type", "content" ], "fields": [ { "parameter": "type", "type": "string", "required": true, "enum": [ "file_content" ], "default": "file_content", "description": "The type of jsonl source. Always `file_content`." }, { "parameter": "content", "type": "array", "required": true, "description": "The content of the jsonl file." }, { "parameter": "content[].item", "type": "object", "required": true, "description": "" }, { "parameter": "content[].sample", "type": "object", "description": "" } ], "status": [ "DOCUMENTED", "DEPRECATED" ], "verification": { "method": "docs_only" }, "sources": [ { "url": "https://developers.openai.com/api/reference/resources/evals", "retrieved_at": "2026-09-18" }, { "url": "https://developers.openai.com/api/openapi (openapi-master.yaml)", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/openai-platform-objects.json" }, { "provider": "openai", "api_family": "evals", "name": "EvalJsonlFileIdSource", "spec_schema": "EvalJsonlFileIdSource", "object_type": null, "description": "", "required": [ "type", "id" ], "fields": [ { "parameter": "type", "type": "string", "required": true, "enum": [ "file_id" ], "default": "file_id", "description": "The type of jsonl source. Always `file_id`." }, { "parameter": "id", "type": "string", "required": true, "description": "The identifier of the file." } ], "status": [ "DOCUMENTED", "DEPRECATED" ], "verification": { "method": "docs_only" }, "sources": [ { "url": "https://developers.openai.com/api/reference/resources/evals", "retrieved_at": "2026-09-18" }, { "url": "https://developers.openai.com/api/openapi (openapi-master.yaml)", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/openai-platform-objects.json" }, { "provider": "openai", "api_family": "evals", "name": "EvalStoredCompletionsSource", "spec_schema": "EvalStoredCompletionsSource", "object_type": null, "description": "A StoredCompletionsRunDataSource configuration describing a set of filters", "required": [ "type" ], "fields": [ { "parameter": "type", "type": "string", "required": true, "enum": [ "stored_completions" ], "default": "stored_completions", "description": "The type of source. Always `stored_completions`." }, { "parameter": "metadata", "type": "object | null", "description": "" }, { "parameter": "model", "type": "string | null", "description": "" }, { "parameter": "created_after", "type": "integer | null", "description": "" }, { "parameter": "created_before", "type": "integer | null", "description": "" }, { "parameter": "limit", "type": "integer | null", "description": "" } ], "status": [ "DOCUMENTED", "DEPRECATED" ], "verification": { "method": "docs_only" }, "sources": [ { "url": "https://developers.openai.com/api/reference/resources/evals", "retrieved_at": "2026-09-18" }, { "url": "https://developers.openai.com/api/openapi (openapi-master.yaml)", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/openai-platform-objects.json" }, { "provider": "openai", "api_family": "evals", "name": "EvalResponsesSource", "spec_schema": "EvalResponsesSource", "object_type": null, "description": "A EvalResponsesSource object describing a run data source configuration.", "required": [ "type" ], "fields": [ { "parameter": "type", "type": "string", "required": true, "enum": [ "responses" ], "description": "The type of run data source. Always `responses`." }, { "parameter": "metadata", "type": "object | null", "description": "" }, { "parameter": "model", "type": "string | null", "description": "" }, { "parameter": "instructions_search", "type": "string | null", "description": "" }, { "parameter": "created_after", "type": "integer | null", "description": "" }, { "parameter": "created_before", "type": "integer | null", "description": "" }, { "parameter": "reasoning_effort", "type": "ReasoningEffort | null", "description": "" }, { "parameter": "temperature", "type": "number | null", "description": "" }, { "parameter": "top_p", "type": "number | null", "description": "" }, { "parameter": "users", "type": "array | null", "description": "" }, { "parameter": "tools", "type": "array | null", "description": "" } ], "status": [ "DOCUMENTED", "DEPRECATED" ], "verification": { "method": "docs_only" }, "sources": [ { "url": "https://developers.openai.com/api/reference/resources/evals", "retrieved_at": "2026-09-18" }, { "url": "https://developers.openai.com/api/openapi (openapi-master.yaml)", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/openai-platform-objects.json" }, { "provider": "openai", "api_family": "batches", "name": "BatchRequestInputLine", "spec_schema": null, "object_type": null, "description": "One line of the batch input JSONL file.", "required": [ "custom_id", "method", "url", "body" ], "fields": [ { "parameter": "custom_id", "type": "string", "required": true, "description": "Unique id per line, echoed in output." }, { "parameter": "method", "type": "string", "required": true, "enum": [ "POST" ], "description": "HTTP method." }, { "parameter": "url", "type": "string", "required": true, "description": "Target endpoint path; must match batch.endpoint." }, { "parameter": "body", "type": "object", "required": true, "description": "Request body of the target endpoint." } ], "status": [ "DOCUMENTED" ], "verification": { "method": "docs_only" }, "sources": [ { "url": "https://developers.openai.com/api/docs/guides/batch#1-prepare-your-batch-file", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/openai-platform-objects.json" }, { "provider": "openai", "api_family": "batches", "name": "BatchRequestOutputLine", "spec_schema": null, "object_type": null, "description": "One line of the batch output (output_file_id) or error (error_file_id) JSONL file. Exactly one of response/error is non-null.", "required": [ "id", "custom_id", "response", "error" ], "fields": [ { "parameter": "id", "type": "string", "required": true, "description": "batch_req_… id." }, { "parameter": "custom_id", "type": "string", "required": true, "description": "Echo of the input custom_id." }, { "parameter": "response", "type": "object | null", "required": true, "description": "{status_code, request_id, body} — body is the normal endpoint response." }, { "parameter": "response.status_code", "type": "integer", "required": true, "description": "HTTP status of the individual request." }, { "parameter": "response.request_id", "type": "string", "required": true, "description": "req_… id usable with support." }, { "parameter": "response.body", "type": "object", "required": true, "description": "Endpoint response object (e.g. Response, ChatCompletion, embeddings list)." }, { "parameter": "error", "type": "object | null", "required": true, "description": "{code, message}; e.g. code=batch_expired for requests cancelled at the 24h window." } ], "status": [ "DOCUMENTED" ], "verification": { "method": "docs_only" }, "sources": [ { "url": "https://developers.openai.com/api/docs/guides/batch#5-retrieve-the-results", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/openai-platform-objects.json" }, { "provider": "openai", "object": "Response", "type_or_object_value": "object = \"response\"", "description": "The Response object returned by POST/GET /v1/responses (also inside response.* events).", "fields": [ { "field": "metadata", "type": "map", "required": true, "enum": null, "default": null, "description": "Set of 16 key-value pairs that can be attached to an object. This can be useful for storing additional information about the object in a structured format, and querying for objects via API or the dashboard. Keys are strings with a maximum length of 64 characters. Values are strings with a maximum length of 512 characters." }, { "field": "top_logprobs", "type": "integer | null", "required": false, "enum": null, "default": null, "description": "An integer between 0 and 20 specifying the maximum number of most likely tokens to return at each token position, each with an associated log probability. In some cases, the number of returned tokens may be fewer than requested." }, { "field": "temperature", "type": "number | null", "required": true, "enum": null, "default": 1, "description": "What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. We generally recommend altering this or `top_p` but not both." }, { "field": "top_p", "type": "number | null", "required": true, "enum": null, "default": 1, "description": "An alternative to sampling with temperature, called nucleus sampling, where the model considers the results of the tokens with top_p probability mass. So 0.1 means only the tokens comprising the top 10% probability mass are considered. We generally recommend altering this or `temperature` but not both." }, { "field": "user", "type": "string", "required": false, "enum": null, "default": null, "description": "This field is being replaced by `safety_identifier` and `prompt_cache_key`. Use `prompt_cache_key` instead to maintain caching optimizations. A stable identifier for your end-users. Used to boost cache hit rates by better bucketing similar requests and to help OpenAI detect and prevent abuse. [Learn more](https://developers.openai.com/api/docs/guides/safety-best-practices#implement-safety-identifi", "deprecated": true }, { "field": "safety_identifier", "type": "string | null", "required": false, "enum": null, "default": null, "description": "A stable identifier used to help detect users of your application that may be violating OpenAI's usage policies. The IDs should be a string that uniquely identifies each user, with a maximum length of 64 characters. We recommend hashing their username or email address, in order to avoid sending us any identifying information. [Learn more](https://developers.openai.com/api/docs/guides/safety-best-p" }, { "field": "prompt_cache_key", "type": "string | null", "required": false, "enum": null, "default": null, "description": "Used by OpenAI to cache responses for similar requests to optimize your cache hit rates. Replaces the `user` field. [Learn more](https://developers.openai.com/api/docs/guides/prompt-caching)." }, { "field": "prompt_cache_retention", "type": "string | null", "required": false, "enum": [ "in_memory", "24h" ], "default": null, "description": "Deprecated. Use `prompt_cache_options.ttl` instead. The retention policy for the prompt cache. Set to `24h` to enable extended prompt caching, which keeps cached prefixes active for longer, up to a maximum of 24 hours. [Learn more](https://developers.openai.com/api/docs/guides/prompt-caching#prompt-cache-retention). This field expresses a maximum retention policy, while `prompt_cache_options.ttl` ", "deprecated": true }, { "field": "previous_response_id", "type": "string | null", "required": false, "enum": null, "default": null, "description": "The unique ID of the previous response to the model. Use this to create multi-turn conversations. Learn more about [conversation state](https://developers.openai.com/api/docs/guides/conversation-state). Cannot be used in conjunction with `conversation`." }, { "field": "model", "type": "string", "required": true, "enum": null, "default": null, "description": "Model ID used to generate the response, like `gpt-6-astra`. OpenAI offers a wide range of models with different capabilities, performance characteristics, and price points. Refer to the [model guide](https://developers.openai.com/api/docs/models) to browse and compare available models." }, { "field": "background", "type": "boolean | null", "required": false, "enum": null, "default": false, "description": "Whether to run the model response in the background. [Learn more](https://developers.openai.com/api/docs/guides/background)." }, { "field": "max_tool_calls", "type": "integer | null", "required": false, "enum": null, "default": null, "description": "The maximum number of total calls to built-in tools that can be processed in a response. This maximum number applies across all built-in tool calls, not per individual tool. Any further attempts to call a tool by the model will be ignored." }, { "field": "text", "type": "object", "required": false, "enum": null, "default": null, "description": "Configuration options for a text response from the model. Can be plain text or structured JSON data. Learn more: - [Text inputs and outputs](https://developers.openai.com/api/docs/guides/text) - [Structured Outputs](https://developers.openai.com/api/docs/guides/structured-outputs)" }, { "field": "text.format", "type": "object | object | object", "required": false, "enum": null, "default": null, "description": "An object specifying the format that the model must output. Configuring `{ \"type\": \"json_schema\" }` enables Structured Outputs, which ensures the model will match your supplied JSON schema. Learn more in the [Structured Outputs guide](https://developers.openai.com/api/docs/guides/structured-outputs). The default format is `{ \"type\": \"text\" }` with no additional options. **Not recommended for gpt-4" }, { "field": "text.verbosity", "type": "string | null", "required": false, "enum": [ "low", "medium", "high" ], "default": "medium", "description": "Constrains the verbosity of the model's response. Lower values will result in more concise responses, while higher values will result in more verbose responses. Currently supported values are `low`, `medium`, and `high`. The default is `medium`." }, { "field": "prompt", "type": "object | null", "required": false, "enum": null, "default": null, "description": "Reference to a prompt template and its variables. [Learn more](https://developers.openai.com/api/docs/guides/text?api-mode=responses#version-prompts-in-code)." }, { "field": "prompt.id", "type": "string", "required": true, "enum": null, "default": null, "description": "The unique identifier of the prompt template to use." }, { "field": "prompt.version", "type": "string | null", "required": false, "enum": null, "default": null, "description": "Optional version of the prompt template." }, { "field": "prompt.variables", "type": "map | object | object>", "required": false, "enum": null, "default": null, "description": "Optional map of values to substitute in for variables in your prompt. The substitution values can either be strings, or other Response input types like images or files." }, { "field": "service_tier", "type": "string | null", "required": false, "enum": [ "auto", "default", "flex", "scale", "priority", "fast", "ultrafast" ], "default": "auto", "description": "Specifies the processing type used for serving the request. - If set to 'auto', then the request will be processed with the service tier configured in the Project settings. Unless otherwise configured, the Project will use 'default'. - If set to 'default', then the request will be processed with the standard pricing and performance for the selected model. - If set to '[flex](https://developers.ope" }, { "field": "truncation", "type": "string | null", "required": false, "enum": [ "auto", "disabled" ], "default": "disabled", "description": "The truncation strategy to use for the model response. - `auto`: If the input to this Response exceeds the model's context window size, the model will truncate the response to fit the context window by dropping items from the beginning of the conversation. - `disabled` (default): If the input size will exceed the context window size for a model, the request will fail with a 400 error." }, { "field": "id", "type": "string", "required": true, "enum": null, "default": null, "description": "Unique identifier for this Response." }, { "field": "object", "type": "string", "required": true, "enum": [ "response" ], "default": null, "description": "The object type of this resource - always set to `response`." }, { "field": "status", "type": "string", "required": false, "enum": [ "completed", "failed", "in_progress", "cancelled", "queued", "incomplete" ], "default": null, "description": "The status of the response generation. One of `completed`, `failed`, `in_progress`, `cancelled`, `queued`, or `incomplete`." }, { "field": "created_at", "type": "number", "required": true, "enum": null, "default": null, "description": "Unix timestamp (in seconds) of when this Response was created." }, { "field": "completed_at", "type": "number | null", "required": false, "enum": null, "default": null, "description": "Unix timestamp (in seconds) of when this Response was completed. Only present when the status is `completed`." }, { "field": "error", "type": "object | null", "required": true, "enum": null, "default": null, "description": "An error object returned when the model fails to generate a Response." }, { "field": "error.code", "type": "string", "required": true, "enum": [ "server_error", "rate_limit_exceeded", "invalid_prompt", "data_residency_mismatch", "bio_policy", "misalignment_policy_violation", "vector_store_timeout", "invalid_image", "invalid_image_format", "invalid_base64_image", "invalid_image_url", "image_too_large", "image_too_small", "image_parse_error", "image_content_policy_violation", "invalid_image_mode", "image_file_too_large", "unsupported_image_media_type", "empty_image_file", "failed_to_download_image", "image_file_not_found" ], "default": null, "description": "The error code for the response." }, { "field": "error.message", "type": "string", "required": true, "enum": null, "default": null, "description": "A human-readable description of the error." }, { "field": "error.misalignment", "type": "object", "required": false, "enum": null, "default": null, "description": "" }, { "field": "incomplete_details", "type": "object | null", "required": true, "enum": null, "default": null, "description": "Details about why the response is incomplete." }, { "field": "incomplete_details.reason", "type": "string", "required": false, "enum": [ "max_output_tokens", "max_messages", "content_filter", "steered" ], "default": null, "description": "The reason why the response is incomplete. `steered` means the response stopped at a safe output boundary after a WebSocket `response.steer` event. The server can then create a successor response automatically with the queued input." }, { "field": "output", "type": "array | object | object | object | object | object | object | object | object | object | object | object | object | object | object | object | object | object | object | object | object | object | object | object | object | object | object | object>", "required": true, "enum": null, "default": null, "description": "An array of content items generated by the model. - The length and order of items in the `output` array is dependent on the model's response. - Rather than accessing the first item in the `output` array and assuming it's an `assistant` message with the content generated by the model, you might consider using the `output_text` property where supported in SDKs." }, { "field": "reasoning", "type": "object | null", "required": false, "enum": null, "default": null, "description": "Configuration options for [reasoning models](https://developers.openai.com/api/docs/guides/reasoning)." }, { "field": "reasoning.mode", "type": "string", "required": false, "enum": null, "default": null, "description": "Controls the reasoning execution mode for the request. When returned on a response, this is the effective execution mode." }, { "field": "reasoning.effort", "type": "string | null", "required": false, "enum": [ "none", "minimal", "low", "medium", "high", "xhigh", "max" ], "default": "medium", "description": "Constrains effort on reasoning for reasoning models. Currently supported values are `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`. Reducing reasoning effort can result in faster responses and fewer tokens used on reasoning in a response. Not all reasoning models support every value. See the [reasoning guide](https://developers.openai.com/api/docs/guides/reasoning) for model-specif" }, { "field": "reasoning.summary", "type": "string | null", "required": false, "enum": [ "auto", "concise", "detailed" ], "default": null, "description": "A summary of the reasoning performed by the model. This can be useful for debugging and understanding the model's reasoning process. One of `auto`, `concise`, or `detailed`. `concise` is supported for `computer-use-preview` models and all reasoning models after `gpt-5`." }, { "field": "reasoning.context", "type": "string | null", "required": false, "enum": [ "auto", "current_turn", "all_turns" ], "default": null, "description": "Controls which reasoning items are rendered back to the model on later turns. If omitted or set to `auto`, the model determines the context mode. The `gpt-5.6` model family defaults to `all_turns`; earlier models default to `current_turn`. When returned on a response, this is the effective reasoning context mode used for the response." }, { "field": "reasoning.generate_summary", "type": "string | null", "required": false, "enum": [ "auto", "concise", "detailed" ], "default": null, "description": "**Deprecated:** use `summary` instead. A summary of the reasoning performed by the model. This can be useful for debugging and understanding the model's reasoning process. One of `auto`, `concise`, or `detailed`.", "deprecated": true }, { "field": "instructions", "type": "string | array | object | object | object | object | object | object | object | object | object | object | object | object | object | object | object | object | object | object | object | object | object | object | object | object | object | object | object | object | ItemReferenceParam | object | object>", "required": true, "enum": null, "default": null, "description": "A system (or developer) message inserted into the model's context. When using along with `previous_response_id`, the instructions from a previous response will not be carried over to the next response. This makes it simple to swap out system (or developer) messages in new responses." }, { "field": "output_text", "type": "string | null", "required": false, "enum": null, "default": null, "description": "SDK-only convenience property that contains the aggregated text output from all `output_text` items in the `output` array, if any are present. Supported in the Python and JavaScript SDKs." }, { "field": "usage", "type": "object", "required": false, "enum": null, "default": null, "description": "Represents token usage details including input tokens, output tokens, a breakdown of output tokens, and the total tokens used." }, { "field": "usage.input_tokens", "type": "integer", "required": true, "enum": null, "default": null, "description": "The number of input tokens." }, { "field": "usage.input_tokens_details", "type": "object", "required": true, "enum": null, "default": null, "description": "A detailed breakdown of the input tokens." }, { "field": "usage.output_tokens", "type": "integer", "required": true, "enum": null, "default": null, "description": "The number of output tokens." }, { "field": "usage.output_tokens_details", "type": "object", "required": true, "enum": null, "default": null, "description": "A detailed breakdown of the output tokens." }, { "field": "usage.total_tokens", "type": "integer", "required": true, "enum": null, "default": null, "description": "The total number of tokens used." }, { "field": "prompt_cache_options", "type": "object", "required": false, "enum": null, "default": null, "description": "The prompt-caching options that were applied to the response. Supported for `gpt-5.6` and later models." }, { "field": "prompt_cache_options.ttl", "type": "string", "required": true, "enum": [ "30m" ], "default": null, "description": "The minimum lifetime applied to each cache breakpoint." }, { "field": "prompt_cache_options.mode", "type": "string", "required": true, "enum": [ "implicit", "explicit" ], "default": null, "description": "Whether implicit prompt-cache breakpoints were enabled." }, { "field": "prompt_cache_options.comparison_response_id", "type": "string | null", "required": false, "enum": null, "default": null, "description": "The response ID supplied as the prompt cache diagnostics comparison." }, { "field": "prompt_cache_diagnostics", "type": "object | object | object | object", "required": false, "enum": null, "default": null, "description": "Prompt cache diagnostics requested for this response." }, { "field": "prompt_cache_diagnostics(cache_miss)", "type": "object", "required": false, "enum": null, "default": null, "description": "" }, { "field": "prompt_cache_diagnostics(cache_hit)", "type": "object", "required": false, "enum": null, "default": null, "description": "" }, { "field": "prompt_cache_diagnostics(comparison_response_not_found)", "type": "object", "required": false, "enum": null, "default": null, "description": "" }, { "field": "prompt_cache_diagnostics(unavailable)", "type": "object", "required": false, "enum": null, "default": null, "description": "" }, { "field": "moderation", "type": "object | null", "required": false, "enum": null, "default": null, "description": "Moderation results for the response input and output, if moderated completions were requested." }, { "field": "moderation.input", "type": "object | object", "required": true, "enum": null, "default": null, "description": "Moderation for the response input." }, { "field": "moderation.output", "type": "object | object", "required": true, "enum": null, "default": null, "description": "Moderation for the response output." }, { "field": "parallel_tool_calls", "type": "boolean", "required": true, "enum": null, "default": true, "description": "Whether to allow the model to run tool calls in parallel." }, { "field": "conversation", "type": "object | null", "required": false, "enum": null, "default": null, "description": "The conversation that this response belonged to. Input items and output items from this response were automatically added to this conversation." }, { "field": "conversation.id", "type": "string", "required": true, "enum": null, "default": null, "description": "The unique ID of the conversation that this response was associated with." }, { "field": "max_output_tokens", "type": "integer | null", "required": false, "enum": null, "default": null, "description": "An upper bound for the number of tokens that can be generated for a response, including visible output tokens and [reasoning tokens](https://developers.openai.com/api/docs/guides/reasoning)." } ], "status": [ "DOCUMENTED", "LIVE_VERIFIED" ], "sources": [ { "url": "https://developers.openai.com/api/reference/resources/responses/methods/create", "retrieved_at": "2026-09-18" }, { "url": "https://raw.githubusercontent.com/openai/openai-openapi/master/openapi.yaml", "retrieved_at": "2026-09-18" } ], "live_example": { "id": "resp_0d1a3b13e2bf34dd006aade8fd690487d2847f660abddbda1b", "object": "response", "created_at": 1789782269, "status": "completed", "background": false, "billing": { "payer": "developer" }, "completed_at": 1789782270, "error": null, "frequency_penalty": 0.0, "incomplete_details": null, "instructions": null, "max_output_tokens": 32, "max_tool_calls": null, "model": "gpt-5.4-nano-2026-03-17", "moderation": null, "output": [ { "id": "msg_0d1a3b13e2bf34dd006aade8fdd89c87d290d9a0f6c0dfc081", "type": "message", "status": "completed", "content": [ { "type": "output_text", "annotations": [], "logprobs": [], "text": "OK." } ], "phase": "final_answer", "role": "assistant" } ], "parallel_tool_calls": true, "presence_penalty": 0.0, "previous_response_id": null, "prompt_cache_key": null, "prompt_cache_retention": "24h", "reasoning": { "context": "current_turn", "effort": "none", "mode": "standard", "summary": null }, "safety_identifier": null, "service_tier": "default", "store": true, "temperature": 1.0, "text": { "format": { "type": "text" }, "verbosity": "medium" }, "tool_choice": "auto", "tool_usage": { "image_gen": { "input_tokens": 0, "input_tokens_details": { "image_tokens": 0, "text_tokens": 0 }, "output_tokens": 0, "output_tokens_details": { "image_tokens": 0, "text_tokens": 0 }, "total_tokens": 0 }, "web_search": { "num_requests": 0 } }, "tools": [], "top_logprobs": 0, "top_p": 0.98, "truncation": "disabled", "usage": { "input_tokens": 10, "input_tokens_details": { "cache_write_tokens": 0, "cached_tokens": 0 }, "output_tokens": 6, "output_tokens_details": { "reasoning_tokens": 0 }, "total_tokens": 16 }, "user": null, "metadata": {} }, "live_fields_not_in_spec": [ "billing", "frequency_penalty", "presence_penalty", "store", "tool_choice", "tool_usage", "tools" ], "live_notes": { "billing": "{\"payer\": \"developer\"} — undocumented; likely marks who pays (developer vs end-user via sign-in with ChatGPT).", "tool_usage": "image_gen token breakdown + web_search.num_requests — undocumented in Response schema.", "frequency_penalty/presence_penalty": "echoed as 0.0 although not Responses request parameters.", "reasoning": "echoed as {context, effort, mode, summary} even when not requested (effort \"none\" default on gpt-5.4-nano).", "top_p": "0.98 default on gpt-5.4-nano.", "text.verbosity": "\"medium\" default.", "prompt_cache_retention": "\"24h\" default (non-ZDR org)." }, "_fragment": "generated/fragments/objects/openai-responses-objects.json" }, { "provider": "openai", "object": "Response.usage (ResponseUsage)", "type_or_object_value": "usage", "description": "Token accounting for a response.", "fields": [ { "field": "input_tokens", "type": "integer", "required": true, "enum": null, "default": null, "description": "The number of input tokens." }, { "field": "input_tokens_details", "type": "object", "required": true, "enum": null, "default": null, "description": "A detailed breakdown of the input tokens." }, { "field": "input_tokens_details.cached_tokens", "type": "integer", "required": true, "enum": null, "default": null, "description": "The number of tokens that were retrieved from the cache. [More on prompt caching](https://developers.openai.com/api/docs/guides/prompt-caching)." }, { "field": "input_tokens_details.cache_write_tokens", "type": "integer", "required": true, "enum": null, "default": null, "description": "The number of input tokens that were written to the cache." }, { "field": "output_tokens", "type": "integer", "required": true, "enum": null, "default": null, "description": "The number of output tokens." }, { "field": "output_tokens_details", "type": "object", "required": true, "enum": null, "default": null, "description": "A detailed breakdown of the output tokens." }, { "field": "output_tokens_details.reasoning_tokens", "type": "integer", "required": true, "enum": null, "default": null, "description": "The number of reasoning tokens." }, { "field": "total_tokens", "type": "integer", "required": true, "enum": null, "default": null, "description": "The total number of tokens used." } ], "status": [ "DOCUMENTED", "LIVE_VERIFIED" ], "sources": [ { "url": "https://developers.openai.com/api/reference/resources/responses/methods/create", "retrieved_at": "2026-09-18" }, { "url": "https://raw.githubusercontent.com/openai/openai-openapi/master/openapi.yaml", "retrieved_at": "2026-09-18" } ], "live_example": { "input_tokens": 28, "input_tokens_details": { "cache_write_tokens": 0, "cached_tokens": 0 }, "output_tokens": 125, "output_tokens_details": { "reasoning_tokens": 118 }, "total_tokens": 153 }, "notes": "reasoning_tokens counted inside output_tokens; cached_tokens/cache_write_tokens inside input_tokens (cache_write_tokens only billed extra on GPT-5.6+).", "_fragment": "generated/fragments/objects/openai-responses-objects.json" }, { "provider": "openai", "object": "Response.incomplete_details", "type_or_object_value": "incomplete_details", "description": "Why a response ended with status=incomplete.", "fields": [ { "field": "reason", "type": "string", "required": false, "enum": [ "max_output_tokens", "max_messages", "content_filter", "steered" ], "description": "steered = stopped at a safe boundary after a WebSocket response.steer." } ], "status": [ "DOCUMENTED", "LIVE_VERIFIED" ], "sources": [ { "url": "https://developers.openai.com/api/reference/resources/responses/methods/create", "retrieved_at": "2026-09-18" }, { "url": "https://raw.githubusercontent.com/openai/openai-openapi/master/openapi.yaml", "retrieved_at": "2026-09-18" } ], "live_example": { "reason": "max_output_tokens" }, "notes": "Live f2: reasoning consumed all 32 output tokens -> status incomplete, output=[reasoning item only].", "_fragment": "generated/fragments/objects/openai-responses-objects.json" }, { "provider": "openai", "object": "Response.error (ResponseError)", "type_or_object_value": "error", "description": "Error object set when status=failed.", "fields": [ { "field": "code", "type": "string", "required": true, "enum": [ "server_error", "rate_limit_exceeded", "invalid_prompt", "data_residency_mismatch", "bio_policy", "misalignment_policy_violation", "vector_store_timeout", "invalid_image", "invalid_image_format", "invalid_base64_image", "invalid_image_url", "image_too_large", "image_too_small", "image_parse_error", "image_content_policy_violation", "invalid_image_mode", "image_file_too_large", "unsupported_image_media_type", "empty_image_file", "failed_to_download_image", "image_file_not_found" ], "default": null, "description": "The error code for the response." }, { "field": "message", "type": "string", "required": true, "enum": null, "default": null, "description": "A human-readable description of the error." }, { "field": "misalignment", "type": "object", "required": false, "enum": null, "default": null, "description": "" }, { "field": "misalignment.error_type", "type": "string", "required": false, "enum": null, "default": null, "description": "An optional classification; clients must accept additional values." }, { "field": "misalignment.detailed_explanation", "type": "string", "required": false, "enum": null, "default": null, "description": "The public explanation for this block." }, { "field": "misalignment.steer", "type": "object", "required": false, "enum": null, "default": null, "description": "An optional public continuation instruction." }, { "field": "misalignment.steer.message", "type": "string", "required": true, "enum": null, "default": null, "description": "The public continuation instruction." } ], "status": [ "DOCUMENTED" ], "sources": [ { "url": "https://developers.openai.com/api/reference/resources/responses/methods/create", "retrieved_at": "2026-09-18" }, { "url": "https://raw.githubusercontent.com/openai/openai-openapi/master/openapi.yaml", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/openai-responses-objects.json" }, { "provider": "openai", "object": "Response.reasoning (Reasoning, echoed)", "type_or_object_value": "reasoning", "description": "Effective reasoning configuration echoed on the response (mode, effort, summary, context).", "fields": [ { "field": "mode", "type": "string | null", "required": false, "enum": [ "standard", "pro" ], "description": "Effective execution mode" }, { "field": "effort", "type": "string | null", "required": false, "enum": [ "none", "minimal", "low", "medium", "high", "xhigh", "max" ], "description": "Effective effort" }, { "field": "summary", "type": "string | null", "required": false, "enum": [ "auto", "concise", "detailed" ], "description": "Requested summary mode; \"auto\" echoed as \"detailed\" live" }, { "field": "context", "type": "string | null", "required": false, "enum": [ "auto", "current_turn", "all_turns" ], "description": "Effective reasoning context mode" } ], "status": [ "DOCUMENTED", "LIVE_VERIFIED" ], "sources": [ { "url": "https://developers.openai.com/api/reference/resources/responses/methods/create", "retrieved_at": "2026-09-18" }, { "url": "https://raw.githubusercontent.com/openai/openai-openapi/master/openapi.yaml", "retrieved_at": "2026-09-18" } ], "live_example": { "context": "current_turn", "effort": "medium", "mode": "standard", "summary": "detailed" }, "_fragment": "generated/fragments/objects/openai-responses-objects.json" }, { "provider": "openai", "object": "Response.conversation (ResponseConversation)", "type_or_object_value": "conversation", "description": "Conversation the response belongs to.", "fields": [ { "field": "id", "type": "string", "required": true, "enum": null, "default": null, "description": "The unique ID of the conversation that this response was associated with." } ], "status": [ "DOCUMENTED", "LIVE_VERIFIED" ], "sources": [ { "url": "https://developers.openai.com/api/reference/resources/responses/methods/create", "retrieved_at": "2026-09-18" }, { "url": "https://raw.githubusercontent.com/openai/openai-openapi/master/openapi.yaml", "retrieved_at": "2026-09-18" } ], "live_example": { "id": "conv_..." }, "_fragment": "generated/fragments/objects/openai-responses-objects.json" }, { "provider": "openai", "object": "Response.prompt_cache_options / prompt_cache_diagnostics", "type_or_object_value": "prompt_cache_options", "description": "Echo of caching options and (GPT-5.6+) diagnostics: type cache_hit | cache_miss{reason, comparison_reusable_tokens, cache_missed_tokens} | comparison_response_not_found | unavailable.", "fields": [ { "field": "ttl", "type": "string", "required": true, "enum": [ "30m" ], "default": null, "description": "The minimum lifetime applied to each cache breakpoint." }, { "field": "mode", "type": "string", "required": true, "enum": [ "implicit", "explicit" ], "default": null, "description": "Whether implicit prompt-cache breakpoints were enabled." }, { "field": "comparison_response_id", "type": "string | null", "required": false, "enum": null, "default": null, "description": "The response ID supplied as the prompt cache diagnostics comparison." }, { "field": "(cache_miss)", "type": "object", "required": false, "enum": null, "default": null, "description": "" }, { "field": "(cache_hit)", "type": "object", "required": false, "enum": null, "default": null, "description": "" }, { "field": "(comparison_response_not_found)", "type": "object", "required": false, "enum": null, "default": null, "description": "" }, { "field": "(unavailable)", "type": "object", "required": false, "enum": null, "default": null, "description": "" } ], "status": [ "DOCUMENTED", "UNVERIFIED" ], "sources": [ { "url": "https://developers.openai.com/api/docs/guides/prompt-caching/diagnostics", "retrieved_at": "2026-09-18" }, { "url": "https://raw.githubusercontent.com/openai/openai-openapi/master/openapi.yaml", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/openai-responses-objects.json" }, { "provider": "openai", "object": "Response.moderation (Moderation)", "type_or_object_value": "moderation", "description": "Moderation results when `moderation` was requested on create.", "fields": [ { "field": "input", "type": "object | object", "required": true, "enum": null, "default": null, "description": "Moderation for the response input." }, { "field": "input(moderation_result)", "type": "object", "required": true, "enum": null, "default": null, "description": "A moderation result produced for the response input or output." }, { "field": "input(moderation_result).type", "type": "string", "required": true, "enum": [ "moderation_result" ], "default": "moderation_result", "description": "The object type, which was always `moderation_result` for successful moderation results." }, { "field": "input(moderation_result).model", "type": "string", "required": true, "enum": null, "default": null, "description": "The moderation model that produced this result." }, { "field": "input(moderation_result).flagged", "type": "boolean", "required": true, "enum": null, "default": null, "description": "A boolean indicating whether the content was flagged by any category." }, { "field": "input(moderation_result).categories", "type": "map", "required": true, "enum": null, "default": null, "description": "A dictionary of moderation categories to booleans, True if the input is flagged under this category." }, { "field": "input(moderation_result).category_scores", "type": "map", "required": true, "enum": null, "default": null, "description": "A dictionary of moderation categories to scores." }, { "field": "input(moderation_result).category_applied_input_types", "type": "map>", "required": true, "enum": null, "default": null, "description": "Which modalities of input are reflected by the score for each category." }, { "field": "input(error)", "type": "object", "required": true, "enum": null, "default": null, "description": "An error produced while attempting moderation for the response input or output." }, { "field": "input(error).type", "type": "string", "required": true, "enum": [ "error" ], "default": "error", "description": "The object type, which was always `error` for moderation failures." }, { "field": "input(error).code", "type": "string", "required": true, "enum": null, "default": null, "description": "The error code." }, { "field": "input(error).message", "type": "string", "required": true, "enum": null, "default": null, "description": "The error message." }, { "field": "output", "type": "object | object", "required": true, "enum": null, "default": null, "description": "Moderation for the response output." }, { "field": "output(moderation_result)", "type": "object", "required": true, "enum": null, "default": null, "description": "A moderation result produced for the response input or output." }, { "field": "output(moderation_result).type", "type": "string", "required": true, "enum": [ "moderation_result" ], "default": "moderation_result", "description": "The object type, which was always `moderation_result` for successful moderation results." }, { "field": "output(moderation_result).model", "type": "string", "required": true, "enum": null, "default": null, "description": "The moderation model that produced this result." }, { "field": "output(moderation_result).flagged", "type": "boolean", "required": true, "enum": null, "default": null, "description": "A boolean indicating whether the content was flagged by any category." }, { "field": "output(moderation_result).categories", "type": "map", "required": true, "enum": null, "default": null, "description": "A dictionary of moderation categories to booleans, True if the input is flagged under this category." }, { "field": "output(moderation_result).category_scores", "type": "map", "required": true, "enum": null, "default": null, "description": "A dictionary of moderation categories to scores." }, { "field": "output(moderation_result).category_applied_input_types", "type": "map>", "required": true, "enum": null, "default": null, "description": "Which modalities of input are reflected by the score for each category." }, { "field": "output(error)", "type": "object", "required": true, "enum": null, "default": null, "description": "An error produced while attempting moderation for the response input or output." }, { "field": "output(error).type", "type": "string", "required": true, "enum": [ "error" ], "default": "error", "description": "The object type, which was always `error` for moderation failures." }, { "field": "output(error).code", "type": "string", "required": true, "enum": null, "default": null, "description": "The error code." }, { "field": "output(error).message", "type": "string", "required": true, "enum": null, "default": null, "description": "The error message." } ], "status": [ "DOCUMENTED", "UNVERIFIED" ], "sources": [ { "url": "https://developers.openai.com/api/reference/resources/responses/methods/create", "retrieved_at": "2026-09-18" }, { "url": "https://raw.githubusercontent.com/openai/openai-openapi/master/openapi.yaml", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/openai-responses-objects.json" }, { "provider": "openai", "object": "Output item: message (OutputMessage)", "type_or_object_value": "type = \"message\"", "description": "Assistant message output item. content[] is output_text | refusal. Live adds `phase` (commentary | final_answer).", "fields": [ { "field": "id", "type": "string", "required": true, "enum": null, "default": null, "description": "The unique ID of the output message." }, { "field": "type", "type": "string", "required": true, "enum": [ "message" ], "default": null, "description": "The type of the output message. Always `message`." }, { "field": "role", "type": "string", "required": true, "enum": [ "assistant" ], "default": null, "description": "The role of the output message. Always `assistant`." }, { "field": "content", "type": "array | object>", "required": true, "enum": null, "default": null, "description": "The content of the output message." }, { "field": "content[]", "type": "object | object", "required": false, "enum": null, "default": null, "description": "" }, { "field": "content[](output_text)", "type": "object", "required": false, "enum": null, "default": null, "description": "A text output from the model." }, { "field": "content[](output_text).type", "type": "string", "required": true, "enum": [ "output_text" ], "default": "output_text", "description": "The type of the output text. Always `output_text`." }, { "field": "content[](output_text).text", "type": "string", "required": true, "enum": null, "default": null, "description": "The text output from the model." }, { "field": "content[](output_text).annotations", "type": "array | object | object | object>", "required": true, "enum": null, "default": null, "description": "The annotations of the text output." }, { "field": "content[](output_text).logprobs", "type": "array", "required": true, "enum": null, "default": null, "description": "" }, { "field": "content[](refusal)", "type": "object", "required": false, "enum": null, "default": null, "description": "A refusal from the model." }, { "field": "content[](refusal).type", "type": "string", "required": true, "enum": [ "refusal" ], "default": "refusal", "description": "The type of the refusal. Always `refusal`." }, { "field": "content[](refusal).refusal", "type": "string", "required": true, "enum": null, "default": null, "description": "The refusal explanation from the model." }, { "field": "phase", "type": "string | null", "required": false, "enum": [ "commentary", "final_answer" ], "default": null, "description": "Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend phase on all assistant messages — dropping it can degrade performance. Not used for user messages." }, { "field": "status", "type": "string", "required": true, "enum": [ "in_progress", "completed", "incomplete" ], "default": null, "description": "The status of the message input. One of `in_progress`, `completed`, or `incomplete`. Populated when input items are returned via API." } ], "status": [ "DOCUMENTED", "LIVE_VERIFIED" ], "sources": [ { "url": "https://developers.openai.com/api/reference/resources/responses/methods/create", "retrieved_at": "2026-09-18" }, { "url": "https://raw.githubusercontent.com/openai/openai-openapi/master/openapi.yaml", "retrieved_at": "2026-09-18" } ], "live_example": { "id": "msg_0d1a3b13e2bf34dd006aade8fdd89c87d290d9a0f6c0dfc081", "type": "message", "status": "completed", "content": [ { "type": "output_text", "annotations": [], "logprobs": [], "text": "OK." } ], "phase": "final_answer", "role": "assistant" }, "_fragment": "generated/fragments/objects/openai-responses-objects.json" }, { "provider": "openai", "object": "Output content: output_text", "type_or_object_value": "type = \"output_text\"", "description": "Text content part with annotations[] and logprobs[].", "fields": [ { "field": "type", "type": "string", "required": true, "enum": [ "output_text" ], "default": "output_text", "description": "The type of the output text. Always `output_text`." }, { "field": "text", "type": "string", "required": true, "enum": null, "default": null, "description": "The text output from the model." }, { "field": "annotations", "type": "array | object | object | object>", "required": true, "enum": null, "default": null, "description": "The annotations of the text output." }, { "field": "annotations[]", "type": "object | object | object | object", "required": false, "enum": null, "default": null, "description": "An annotation that applies to a span of output text." }, { "field": "annotations[](file_citation)", "type": "object", "required": false, "enum": null, "default": null, "description": "A citation to a file." }, { "field": "annotations[](url_citation)", "type": "object", "required": false, "enum": null, "default": null, "description": "A citation for a web resource used to generate a model response." }, { "field": "annotations[](container_file_citation)", "type": "object", "required": false, "enum": null, "default": null, "description": "A citation for a container file used to generate a model response." }, { "field": "annotations[](file_path)", "type": "object", "required": false, "enum": null, "default": null, "description": "A path to a file." }, { "field": "logprobs", "type": "array", "required": true, "enum": null, "default": null, "description": "" }, { "field": "logprobs[]", "type": "object", "required": false, "enum": null, "default": null, "description": "The log probability of a token." }, { "field": "logprobs[].token", "type": "string", "required": true, "enum": null, "default": null, "description": "" }, { "field": "logprobs[].logprob", "type": "number", "required": true, "enum": null, "default": null, "description": "" }, { "field": "logprobs[].bytes", "type": "array", "required": true, "enum": null, "default": null, "description": "" }, { "field": "logprobs[].top_logprobs", "type": "array", "required": true, "enum": null, "default": null, "description": "" }, { "field": "annotations[] (Annotation)", "type": "file_citation | url_citation | container_file_citation | file_path", "required": true, "description": "See Annotation schema (tools agents document citation shapes)." } ], "status": [ "DOCUMENTED", "LIVE_VERIFIED" ], "sources": [ { "url": "https://developers.openai.com/api/reference/resources/responses/methods/create", "retrieved_at": "2026-09-18" }, { "url": "https://raw.githubusercontent.com/openai/openai-openapi/master/openapi.yaml", "retrieved_at": "2026-09-18" } ], "live_example": { "type": "output_text", "annotations": [], "logprobs": [], "text": "OK." }, "_fragment": "generated/fragments/objects/openai-responses-objects.json" }, { "provider": "openai", "object": "Output content: refusal", "type_or_object_value": "type = \"refusal\"", "description": "Refusal content part.", "fields": [ { "field": "type", "type": "string", "required": true, "enum": [ "refusal" ], "default": "refusal", "description": "The type of the refusal. Always `refusal`." }, { "field": "refusal", "type": "string", "required": true, "enum": null, "default": null, "description": "The refusal explanation from the model." } ], "status": [ "DOCUMENTED" ], "sources": [ { "url": "https://developers.openai.com/api/reference/resources/responses/methods/create", "retrieved_at": "2026-09-18" }, { "url": "https://raw.githubusercontent.com/openai/openai-openapi/master/openapi.yaml", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/openai-responses-objects.json" }, { "provider": "openai", "object": "Output item: reasoning (ReasoningItem)", "type_or_object_value": "type = \"reasoning\"", "description": "Reasoning item: summary[] (summary_text), content[] (reasoning_text, rarely populated), encrypted_content (populated by default in stateless mode), status.", "fields": [ { "field": "type", "type": "string", "required": true, "enum": [ "reasoning" ], "default": null, "description": "The type of the object. Always `reasoning`." }, { "field": "id", "type": "string", "required": true, "enum": null, "default": null, "description": "The unique identifier of the reasoning content." }, { "field": "encrypted_content", "type": "string | null", "required": false, "enum": null, "default": null, "description": "The encrypted content of the reasoning item. This is populated by default for reasoning items returned by `POST /v1/responses` and WebSocket `response.create` requests. When streaming, use the completed reasoning item and its `encrypted_content` from the `response.output_item.done` event in subsequent requests. The `encrypted_content` in `response.output_item.added` may be incomplete. This is espe" }, { "field": "summary", "type": "array", "required": true, "enum": null, "default": null, "description": "Reasoning summary content." }, { "field": "summary[]", "type": "object", "required": false, "enum": null, "default": null, "description": "A summary text from the model." }, { "field": "summary[].type", "type": "string", "required": true, "enum": [ "summary_text" ], "default": "summary_text", "description": "The type of the object. Always `summary_text`." }, { "field": "summary[].text", "type": "string", "required": true, "enum": null, "default": null, "description": "A summary of the reasoning output from the model so far." }, { "field": "content", "type": "array", "required": false, "enum": null, "default": null, "description": "Reasoning text content." }, { "field": "content[]", "type": "object", "required": false, "enum": null, "default": null, "description": "Reasoning text from the model." }, { "field": "content[].type", "type": "string", "required": true, "enum": [ "reasoning_text" ], "default": "reasoning_text", "description": "The type of the reasoning text. Always `reasoning_text`." }, { "field": "content[].text", "type": "string", "required": true, "enum": null, "default": null, "description": "The reasoning text from the model." }, { "field": "status", "type": "string", "required": false, "enum": [ "in_progress", "completed", "incomplete" ], "default": null, "description": "The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API." }, { "field": "type", "type": "string", "required": true, "enum": [ "summary_text" ], "default": "summary_text", "description": "The type of the object. Always `summary_text`." }, { "field": "text", "type": "string", "required": true, "enum": null, "default": null, "description": "A summary of the reasoning output from the model so far." } ], "status": [ "DOCUMENTED", "LIVE_VERIFIED" ], "sources": [ { "url": "https://developers.openai.com/api/reference/resources/responses/methods/create", "retrieved_at": "2026-09-18" }, { "url": "https://raw.githubusercontent.com/openai/openai-openapi/master/openapi.yaml", "retrieved_at": "2026-09-18" } ], "live_example": { "id": "rs_09d16d4375ddfc5d016aade9a2978c87d29fe2d737d2975c93", "type": "reasoning", "content": [], "encrypted_content": "gAAAAABqremkK8TpNynRJayx...(truncated)", "summary": [ { "type": "summary_text", "text": "**Counting letters in 'strawberry'**\n\nI need to count the letter 'r' in \"strawberry\". So, breaking it down: s, t, r, a, w, b, e, r, r, y. The 'r' appears at the 3rd position and also twice at the end. Let’s double-check: I count them as s(1), t(2), r(3), a(4), w(5), b(6), e(7), r(8), r(9), y(10). So, the total for 'r' is indeed 3. The user wants the final answer to be just the number: \"3\"." } ] }, "notes": "Live f3 (effort medium, summary auto): 118 reasoning tokens, one summary_text; encrypted_content present with store=false.", "_fragment": "generated/fragments/objects/openai-responses-objects.json" }, { "provider": "openai", "object": "Output/Input item: function_call (FunctionToolCall)", "type_or_object_value": "type = \"function_call\"", "description": "Model-generated function call (id, call_id, name, arguments JSON string, status, caller/namespace/async for programmatic calling).", "fields": [ { "field": "id", "type": "string", "required": false, "enum": null, "default": null, "description": "The unique ID of the function tool call." }, { "field": "type", "type": "string", "required": true, "enum": [ "function_call" ], "default": null, "description": "The type of the function tool call. Always `function_call`." }, { "field": "call_id", "type": "string", "required": true, "enum": null, "default": null, "description": "The unique ID of the function tool call generated by the model." }, { "field": "caller", "type": "object | object", "required": false, "enum": null, "default": null, "description": "The execution context that produced this tool call." }, { "field": "caller(direct)", "type": "object", "required": false, "enum": null, "default": null, "description": "" }, { "field": "caller(program)", "type": "object", "required": false, "enum": null, "default": null, "description": "" }, { "field": "namespace", "type": "string", "required": false, "enum": null, "default": null, "description": "The namespace of the function to run." }, { "field": "name", "type": "string", "required": true, "enum": null, "default": null, "description": "The name of the function to run." }, { "field": "arguments", "type": "string", "required": true, "enum": null, "default": null, "description": "A JSON string of the arguments to pass to the function." }, { "field": "status", "type": "string", "required": false, "enum": [ "in_progress", "completed", "incomplete" ], "default": null, "description": "The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API." }, { "field": "async", "type": "boolean", "required": false, "enum": null, "default": null, "description": "Whether the function tool call runs asynchronously." } ], "status": [ "DOCUMENTED" ], "sources": [ { "url": "https://developers.openai.com/api/reference/resources/responses/methods/create", "retrieved_at": "2026-09-18" }, { "url": "https://raw.githubusercontent.com/openai/openai-openapi/master/openapi.yaml", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/openai-responses-objects.json" }, { "provider": "openai", "object": "Input item: function_call_output", "type_or_object_value": "type = \"function_call_output\"", "description": "Your function result: call_id + output (string or input_text/input_image/input_file parts).", "fields": [ { "field": "id", "type": "string | null", "required": false, "enum": null, "default": null, "description": "The unique ID of the function tool call output. Populated when this item is returned via API." }, { "field": "call_id", "type": "string | null", "required": false, "enum": null, "default": null, "description": "The unique ID of the function tool call generated by the model." }, { "field": "type", "type": "string", "required": true, "enum": [ "function_call_output" ], "default": "function_call_output", "description": "The type of the function tool call output. Always `function_call_output`." }, { "field": "output", "type": "string | array | object | object>", "required": true, "enum": null, "default": null, "description": "Text, image, or file output of the function tool call." }, { "field": "output[]", "type": "array | object | object> | object | object", "required": false, "enum": null, "default": null, "description": "An array of content outputs (text, image, file) for the function tool call." }, { "field": "output[](input_text)", "type": "object", "required": false, "enum": null, "default": null, "description": "A text input to the model." }, { "field": "output[](input_image)", "type": "object", "required": false, "enum": null, "default": null, "description": "An image input to the model. Learn about [image inputs](https://developers.openai.com/api/docs/guides/images-vision)" }, { "field": "output[](input_file)", "type": "object", "required": false, "enum": null, "default": null, "description": "A file input to the model." }, { "field": "name", "type": "string | null", "required": false, "enum": null, "default": null, "description": "The name of the tool that produced the output." }, { "field": "namespace", "type": "string | null", "required": false, "enum": null, "default": null, "description": "The namespace of the tool that produced the output." }, { "field": "caller", "type": "object | object", "required": false, "enum": null, "default": null, "description": "The execution context that produced this tool call." }, { "field": "caller(direct)", "type": "object", "required": false, "enum": null, "default": null, "description": "" }, { "field": "caller(direct).type", "type": "string", "required": true, "enum": [ "direct" ], "default": "direct", "description": "The caller type. Always `direct`." }, { "field": "caller(program)", "type": "object", "required": false, "enum": null, "default": null, "description": "" }, { "field": "caller(program).type", "type": "string", "required": true, "enum": [ "program" ], "default": "program", "description": "The caller type. Always `program`." }, { "field": "caller(program).caller_id", "type": "string", "required": true, "enum": null, "default": null, "description": "The call ID of the program item that produced this tool call." }, { "field": "status", "type": "string | null", "required": false, "enum": [ "in_progress", "completed", "incomplete" ], "default": null, "description": "The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API." } ], "status": [ "DOCUMENTED" ], "sources": [ { "url": "https://developers.openai.com/api/reference/resources/responses/methods/create", "retrieved_at": "2026-09-18" }, { "url": "https://raw.githubusercontent.com/openai/openai-openapi/master/openapi.yaml", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/openai-responses-objects.json" }, { "provider": "openai", "object": "Item: compaction (CompactionSummaryItemParam)", "type_or_object_value": "type = \"compaction\"", "description": "Opaque compacted context (encrypted_content) produced by /responses/compact or server-side compaction; replay as an input item.", "fields": [ { "field": "id", "type": "string | null", "required": false, "enum": null, "default": null, "description": "The ID of the compaction item." }, { "field": "type", "type": "string", "required": true, "enum": [ "compaction" ], "default": "compaction", "description": "The type of the item. Always `compaction`." }, { "field": "encrypted_content", "type": "string", "required": true, "enum": null, "default": null, "description": "The encrypted content of the compaction summary." } ], "status": [ "DOCUMENTED", "LIVE_VERIFIED" ], "sources": [ { "url": "https://developers.openai.com/api/reference/resources/responses/methods/create", "retrieved_at": "2026-09-18" }, { "url": "https://raw.githubusercontent.com/openai/openai-openapi/master/openapi.yaml", "retrieved_at": "2026-09-18" } ], "live_example": { "id": "cmp_0ed5b67e8da655fb016aade904992087d2a7f4f8dbfac97dfa", "type": "compaction", "encrypted_content": "gAAAAABqrekFMDjkZ64ju-Up...(truncated)" }, "_fragment": "generated/fragments/objects/openai-responses-objects.json" }, { "provider": "openai", "object": "Input item: compaction_trigger", "type_or_object_value": "type = \"compaction_trigger\"", "description": "Requests compaction of the current context; must be the final input item.", "fields": [ { "field": "type", "type": "string", "required": true, "enum": [ "compaction_trigger" ], "description": "" }, { "field": "id", "type": "string | null", "required": false, "description": "" } ], "status": [ "DOCUMENTED", "UNVERIFIED" ], "sources": [ { "url": "https://developers.openai.com/api/reference/resources/responses/methods/create", "retrieved_at": "2026-09-18" }, { "url": "https://raw.githubusercontent.com/openai/openai-openapi/master/openapi.yaml", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/openai-responses-objects.json" }, { "provider": "openai", "object": "Input item: configuration_update", "type_or_object_value": "type = \"configuration_update\"", "description": "Changes reasoning effort mid-conversation without rewriting the cached prefix (gpt-6-astra only).", "fields": [ { "field": "type", "type": "string", "required": true, "enum": [ "configuration_update" ], "description": "" }, { "field": "reasoning.effort", "type": "string", "required": false, "enum": [ "none", "minimal", "low", "medium", "high", "xhigh", "max" ], "description": "" } ], "status": [ "DOCUMENTED", "UNVERIFIED" ], "sources": [ { "url": "https://developers.openai.com/api/docs/guides/reasoning#change-reasoning-mid-conversation", "retrieved_at": "2026-09-18" }, { "url": "https://raw.githubusercontent.com/openai/openai-openapi/master/openapi.yaml", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/openai-responses-objects.json" }, { "provider": "openai", "object": "Input item: item_reference", "type_or_object_value": "type = \"item_reference\"", "description": "Reference to an existing stored item by id.", "fields": [ { "field": "type", "type": "string | null", "required": false, "enum": [ "item_reference" ], "default": "item_reference", "description": "The type of item to reference. Always `item_reference`." }, { "field": "id", "type": "string", "required": true, "enum": null, "default": null, "description": "The ID of the item to reference." } ], "status": [ "DOCUMENTED", "UNVERIFIED" ], "sources": [ { "url": "https://developers.openai.com/api/reference/resources/responses/methods/create", "retrieved_at": "2026-09-18" }, { "url": "https://raw.githubusercontent.com/openai/openai-openapi/master/openapi.yaml", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/openai-responses-objects.json" }, { "provider": "openai", "object": "Input item: message (EasyInputMessage / InputMessage)", "type_or_object_value": "type = \"message\" (type optional)", "description": "Input message: role user|assistant|system|developer, content string or parts (input_text | input_image | input_file | input_audio), optional phase for assistant.", "fields": [ { "field": "role", "type": "string", "required": true, "enum": [ "user", "assistant", "system", "developer" ], "default": null, "description": "The role of the message input. One of `user`, `assistant`, `system`, or `developer`." }, { "field": "content", "type": "string | array | object | object>", "required": true, "enum": null, "default": null, "description": "Text, image, or audio input to the model, used to generate a response. Can also contain previous assistant responses." }, { "field": "content[]", "type": "array | object | object> | object | object", "required": false, "enum": null, "default": null, "description": "A list of one or many input items to the model, containing different content types." }, { "field": "phase", "type": "string | null", "required": false, "enum": [ "commentary", "final_answer" ], "default": null, "description": "Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend phase on all assistant messages — dropping it can degrade performance. Not used for user messages." }, { "field": "type", "type": "string", "required": false, "enum": [ "message" ], "default": null, "description": "The type of the message input. Always `message`." }, { "field": "status", "type": "string", "required": false, "enum": [ "in_progress", "completed", "incomplete" ], "default": null, "description": "The status of item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API." }, { "field": "content[]", "type": "object | object | object", "required": false, "enum": null, "default": null, "description": "" }, { "field": "content[](input_text)", "type": "object", "required": false, "enum": null, "default": null, "description": "A text input to the model." }, { "field": "content[](input_image)", "type": "object", "required": false, "enum": null, "default": null, "description": "An image input to the model. Learn about [image inputs](https://developers.openai.com/api/docs/guides/images-vision)." }, { "field": "content[](input_file)", "type": "object", "required": false, "enum": null, "default": null, "description": "A file input to the model." } ], "status": [ "DOCUMENTED", "LIVE_VERIFIED" ], "sources": [ { "url": "https://developers.openai.com/api/reference/resources/responses/methods/create", "retrieved_at": "2026-09-18" }, { "url": "https://raw.githubusercontent.com/openai/openai-openapi/master/openapi.yaml", "retrieved_at": "2026-09-18" } ], "live_example": { "id": "msg_0d1a3b13e2bf34dd006aade8ffb8bc87d2b391468751423de3", "type": "message", "status": "completed", "content": [ { "type": "input_text", "text": "Reply with OK again." } ], "role": "user" }, "_fragment": "generated/fragments/objects/openai-responses-objects.json" }, { "provider": "openai", "object": "Input content parts (InputContent)", "type_or_object_value": "input_text | input_image | input_file", "description": "Content parts for input messages and tool outputs. input_image: image_url (URL or data URL) or file_id, detail low|high|auto|original; input_file: file_id | file_url | file_data(+filename), detail auto|low|high; prompt_cache_breakpoint {mode: explicit} on any part (GPT-5.6+).", "fields": [ { "field": "(input_text)", "type": "object", "required": false, "enum": null, "default": null, "description": "A text input to the model." }, { "field": "(input_text).type", "type": "string", "required": true, "enum": [ "input_text" ], "default": "input_text", "description": "The type of the input item. Always `input_text`." }, { "field": "(input_text).text", "type": "string", "required": true, "enum": null, "default": null, "description": "The text input to the model." }, { "field": "(input_text).prompt_cache_breakpoint", "type": "object", "required": false, "enum": null, "default": null, "description": "Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block." }, { "field": "(input_text).prompt_cache_breakpoint.mode", "type": "string", "required": true, "enum": [ "explicit" ], "default": "explicit", "description": "The breakpoint mode. Always `explicit`." }, { "field": "(input_image)", "type": "object", "required": false, "enum": null, "default": null, "description": "An image input to the model. Learn about [image inputs](https://developers.openai.com/api/docs/guides/images-vision)." }, { "field": "(input_image).type", "type": "string", "required": true, "enum": [ "input_image" ], "default": "input_image", "description": "The type of the input item. Always `input_image`." }, { "field": "(input_image).image_url", "type": "string | null", "required": false, "enum": null, "default": null, "description": "The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL." }, { "field": "(input_image).file_id", "type": "string | null", "required": false, "enum": null, "default": null, "description": "The ID of the file to be sent to the model." }, { "field": "(input_image).detail", "type": "string", "required": true, "enum": [ "low", "high", "auto", "original" ], "default": null, "description": "The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`." }, { "field": "(input_image).prompt_cache_breakpoint", "type": "object", "required": false, "enum": null, "default": null, "description": "Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block." }, { "field": "(input_image).prompt_cache_breakpoint.mode", "type": "string", "required": true, "enum": [ "explicit" ], "default": "explicit", "description": "The breakpoint mode. Always `explicit`." }, { "field": "(input_file)", "type": "object", "required": false, "enum": null, "default": null, "description": "A file input to the model." }, { "field": "(input_file).type", "type": "string", "required": true, "enum": [ "input_file" ], "default": "input_file", "description": "The type of the input item. Always `input_file`." }, { "field": "(input_file).file_id", "type": "string | null", "required": false, "enum": null, "default": null, "description": "The ID of the file to be sent to the model." }, { "field": "(input_file).filename", "type": "string", "required": false, "enum": null, "default": null, "description": "The name of the file to be sent to the model." }, { "field": "(input_file).file_data", "type": "string", "required": false, "enum": null, "default": null, "description": "The content of the file to be sent to the model." }, { "field": "(input_file).prompt_cache_breakpoint", "type": "object", "required": false, "enum": null, "default": null, "description": "Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block." }, { "field": "(input_file).prompt_cache_breakpoint.mode", "type": "string", "required": true, "enum": [ "explicit" ], "default": "explicit", "description": "The breakpoint mode. Always `explicit`." }, { "field": "(input_file).file_url", "type": "string", "required": false, "enum": null, "default": null, "description": "The URL of the file to be sent to the model." }, { "field": "(input_file).detail", "type": "string", "required": false, "enum": [ "auto", "low", "high" ], "default": null, "description": "The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`." } ], "status": [ "DOCUMENTED", "LIVE_VERIFIED" ], "sources": [ { "url": "https://developers.openai.com/api/reference/resources/responses/methods/create", "retrieved_at": "2026-09-18" }, { "url": "https://raw.githubusercontent.com/openai/openai-openapi/master/openapi.yaml", "retrieved_at": "2026-09-18" } ], "live_example": { "type": "input_image", "image_url": "data:image/png;base64,iVBORw0KGgo...(1x1 png)", "detail": "low" }, "_fragment": "generated/fragments/objects/openai-responses-objects.json" }, { "provider": "openai", "object": "Input content part: input_audio", "type_or_object_value": "type = \"input_audio\"", "description": "Audio input part {input_audio: {data (base64), format: mp3|wav}} — accepted by audio-capable models.", "fields": [ { "field": "type", "type": "string", "required": true, "enum": [ "input_audio" ], "description": "" }, { "field": "input_audio.data", "type": "string", "required": true, "description": "Base64 audio" }, { "field": "input_audio.format", "type": "string", "required": true, "enum": [ "mp3", "wav" ], "description": "" } ], "status": [ "DOCUMENTED", "UNVERIFIED" ], "sources": [ { "url": "https://developers.openai.com/api/reference/resources/responses/methods/create", "retrieved_at": "2026-09-18" }, { "url": "https://raw.githubusercontent.com/openai/openai-openapi/master/openapi.yaml", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/openai-responses-objects.json" }, { "provider": "openai", "object": "Output item types (union OutputItem)", "type_or_object_value": "output[].type", "description": "All output item types in the OpenAPI OutputItem union; tool-call items are documented by the tools fragments.", "fields": [ { "field": "additional_tools", "type": "object", "required": false, "description": "" }, { "field": "apply_patch_call", "type": "object", "required": false, "description": "" }, { "field": "apply_patch_call_output", "type": "object", "required": false, "description": "" }, { "field": "click", "type": "object", "required": false, "description": "" }, { "field": "code_interpreter_call", "type": "object", "required": false, "description": "" }, { "field": "compaction", "type": "object", "required": false, "description": "" }, { "field": "computer_call", "type": "object", "required": false, "description": "" }, { "field": "computer_call_output", "type": "object", "required": false, "description": "" }, { "field": "container_reference", "type": "object", "required": false, "description": "" }, { "field": "create_file", "type": "object", "required": false, "description": "" }, { "field": "custom_tool_call", "type": "object", "required": false, "description": "" }, { "field": "custom_tool_call_output", "type": "object", "required": false, "description": "" }, { "field": "delete_file", "type": "object", "required": false, "description": "" }, { "field": "direct", "type": "object", "required": false, "description": "" }, { "field": "double_click", "type": "object", "required": false, "description": "" }, { "field": "drag", "type": "object", "required": false, "description": "" }, { "field": "file_search_call", "type": "object", "required": false, "description": "" }, { "field": "find_in_page", "type": "object", "required": false, "description": "" }, { "field": "function_call", "type": "object", "required": false, "description": "" }, { "field": "function_call_output", "type": "object", "required": false, "description": "" }, { "field": "http_error", "type": "object", "required": false, "description": "" }, { "field": "image_generation_call", "type": "object", "required": false, "description": "" }, { "field": "keypress", "type": "object", "required": false, "description": "" }, { "field": "local", "type": "object", "required": false, "description": "" }, { "field": "local_shell_call", "type": "object", "required": false, "description": "" }, { "field": "local_shell_call_output", "type": "object", "required": false, "description": "" }, { "field": "mcp_approval_request", "type": "object", "required": false, "description": "" }, { "field": "mcp_approval_response", "type": "object", "required": false, "description": "" }, { "field": "mcp_call", "type": "object", "required": false, "description": "" }, { "field": "mcp_list_tools", "type": "object", "required": false, "description": "" }, { "field": "mcp_protocol_error", "type": "object", "required": false, "description": "" }, { "field": "mcp_tool_execution_error", "type": "object", "required": false, "description": "" }, { "field": "message", "type": "object", "required": false, "description": "" }, { "field": "move", "type": "object", "required": false, "description": "" }, { "field": "open_page", "type": "object", "required": false, "description": "" }, { "field": "program", "type": "object", "required": false, "description": "" }, { "field": "program_output", "type": "object", "required": false, "description": "" }, { "field": "reasoning", "type": "object", "required": false, "description": "" }, { "field": "screenshot", "type": "object", "required": false, "description": "" }, { "field": "scroll", "type": "object", "required": false, "description": "" }, { "field": "search", "type": "object", "required": false, "description": "" }, { "field": "shell_call", "type": "object", "required": false, "description": "" }, { "field": "shell_call_output", "type": "object", "required": false, "description": "" }, { "field": "tool_search_call", "type": "object", "required": false, "description": "" }, { "field": "tool_search_output", "type": "object", "required": false, "description": "" }, { "field": "type", "type": "object", "required": false, "description": "" }, { "field": "update_file", "type": "object", "required": false, "description": "" }, { "field": "wait", "type": "object", "required": false, "description": "" }, { "field": "web_search_call", "type": "object", "required": false, "description": "" } ], "status": [ "DOCUMENTED" ], "sources": [ { "url": "https://developers.openai.com/api/reference/resources/responses/methods/create", "retrieved_at": "2026-09-18" }, { "url": "https://raw.githubusercontent.com/openai/openai-openapi/master/openapi.yaml", "retrieved_at": "2026-09-18" } ], "notes": "Live observed: message, reasoning, compaction (from /responses/compact).", "_fragment": "generated/fragments/objects/openai-responses-objects.json" }, { "provider": "openai", "object": "Item types (union Item, usable as input)", "type_or_object_value": "input[].type", "description": "All item types accepted in `input`/conversation items.", "fields": [ { "field": "additional_tools", "type": "object", "required": false, "description": "" }, { "field": "apply_patch_call", "type": "object", "required": false, "description": "" }, { "field": "apply_patch_call_output", "type": "object", "required": false, "description": "" }, { "field": "click", "type": "object", "required": false, "description": "" }, { "field": "code_interpreter_call", "type": "object", "required": false, "description": "" }, { "field": "compaction", "type": "object", "required": false, "description": "" }, { "field": "computer_call", "type": "object", "required": false, "description": "" }, { "field": "computer_call_output", "type": "object", "required": false, "description": "" }, { "field": "configuration_update", "type": "object", "required": false, "description": "" }, { "field": "container_reference", "type": "object", "required": false, "description": "" }, { "field": "create_file", "type": "object", "required": false, "description": "" }, { "field": "custom_tool_call", "type": "object", "required": false, "description": "" }, { "field": "custom_tool_call_output", "type": "object", "required": false, "description": "" }, { "field": "delete_file", "type": "object", "required": false, "description": "" }, { "field": "direct", "type": "object", "required": false, "description": "" }, { "field": "double_click", "type": "object", "required": false, "description": "" }, { "field": "drag", "type": "object", "required": false, "description": "" }, { "field": "file_search_call", "type": "object", "required": false, "description": "" }, { "field": "find_in_page", "type": "object", "required": false, "description": "" }, { "field": "function_call", "type": "object", "required": false, "description": "" }, { "field": "function_call_output", "type": "object", "required": false, "description": "" }, { "field": "http_error", "type": "object", "required": false, "description": "" }, { "field": "image_generation_call", "type": "object", "required": false, "description": "" }, { "field": "keypress", "type": "object", "required": false, "description": "" }, { "field": "local", "type": "object", "required": false, "description": "" }, { "field": "local_shell_call", "type": "object", "required": false, "description": "" }, { "field": "local_shell_call_output", "type": "object", "required": false, "description": "" }, { "field": "mcp_approval_request", "type": "object", "required": false, "description": "" }, { "field": "mcp_approval_response", "type": "object", "required": false, "description": "" }, { "field": "mcp_call", "type": "object", "required": false, "description": "" }, { "field": "mcp_list_tools", "type": "object", "required": false, "description": "" }, { "field": "mcp_protocol_error", "type": "object", "required": false, "description": "" }, { "field": "mcp_tool_execution_error", "type": "object", "required": false, "description": "" }, { "field": "message", "type": "object", "required": false, "description": "" }, { "field": "move", "type": "object", "required": false, "description": "" }, { "field": "open_page", "type": "object", "required": false, "description": "" }, { "field": "program", "type": "object", "required": false, "description": "" }, { "field": "reasoning", "type": "object", "required": false, "description": "" }, { "field": "screenshot", "type": "object", "required": false, "description": "" }, { "field": "scroll", "type": "object", "required": false, "description": "" }, { "field": "search", "type": "object", "required": false, "description": "" }, { "field": "shell_call", "type": "object", "required": false, "description": "" }, { "field": "shell_call_output", "type": "object", "required": false, "description": "" }, { "field": "tool_search_call", "type": "object", "required": false, "description": "" }, { "field": "tool_search_output", "type": "object", "required": false, "description": "" }, { "field": "type", "type": "object", "required": false, "description": "" }, { "field": "update_file", "type": "object", "required": false, "description": "" }, { "field": "wait", "type": "object", "required": false, "description": "" }, { "field": "web_search_call", "type": "object", "required": false, "description": "" } ], "status": [ "DOCUMENTED" ], "sources": [ { "url": "https://developers.openai.com/api/reference/resources/responses/methods/create", "retrieved_at": "2026-09-18" }, { "url": "https://raw.githubusercontent.com/openai/openai-openapi/master/openapi.yaml", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/openai-responses-objects.json" }, { "provider": "openai", "object": "ResponseItemList", "type_or_object_value": "object = \"list\"", "description": "Paginated list returned by GET /v1/responses/{id}/input_items.", "fields": [ { "field": "object", "type": "string", "required": true, "enum": [ "list" ], "default": null, "description": "The type of object returned, must be `list`." }, { "field": "data", "type": "array | object | object | object | object | object | object | object | object | object | object | object | object | object | object | object | object | object | object | object | object | object | object | object | object | object | object | object | object>", "required": true, "enum": null, "default": null, "description": "A list of items used to generate this response." }, { "field": "data[]", "type": "object | object | object | object | object | object | object | object | object | object | object | object | object | object | object | object | object | object | object | object | object | object | object | object | object | object | object | object | object", "required": false, "enum": null, "default": null, "description": "Content item used to generate a response." }, { "field": "has_more", "type": "boolean", "required": true, "enum": null, "default": null, "description": "Whether there are more items available." }, { "field": "first_id", "type": "string", "required": true, "enum": null, "default": null, "description": "The ID of the first item in the list." }, { "field": "last_id", "type": "string", "required": true, "enum": null, "default": null, "description": "The ID of the last item in the list." } ], "status": [ "DOCUMENTED", "LIVE_VERIFIED" ], "sources": [ { "url": "https://developers.openai.com/api/reference/resources/responses/methods/create", "retrieved_at": "2026-09-18" }, { "url": "https://raw.githubusercontent.com/openai/openai-openapi/master/openapi.yaml", "retrieved_at": "2026-09-18" } ], "live_example": { "object": "list", "data": [ { "id": "msg_0d1a3b13e2bf34dd006aade8ffb8bc87d2b391468751423de3", "type": "message", "status": "completed", "content": [ { "type": "input_text", "text": "Reply with OK again." } ], "role": "user" }, { "id": "msg_0d1a3b13e2bf34dd006aade8fdd89c87d290d9a0f6c0dfc081", "type": "message", "status": "completed", "content": [ { "type": "output_text", "annotations": [], "logprobs": [], "text": "OK." } ], "phase": "final_answer", "role": "assistant" }, { "id": "msg_0d1a3b13e2bf34dd006aade8fd836887d2a3fa8a30de5ef805", "type": "message", "status": "completed", "content": [ { "type": "input_text", "text": "Reply with OK." } ], "role": "user" } ], "first_id": "msg_0d1a3b13e2bf34dd006aade8ffb8bc87d2b391468751423de3", "has_more": false, "last_id": "msg_0d1a3b13e2bf34dd006aade8fd836887d2a3fa8a30de5ef805" }, "_fragment": "generated/fragments/objects/openai-responses-objects.json" }, { "provider": "openai", "object": "TokenCountsResource", "type_or_object_value": "object = \"response.input_tokens\"", "description": "Result of POST /v1/responses/input_tokens.", "fields": [ { "field": "object", "type": "string", "required": true, "enum": [ "response.input_tokens" ], "default": "response.input_tokens", "description": "" }, { "field": "input_tokens", "type": "integer", "required": true, "enum": null, "default": null, "description": "" } ], "status": [ "DOCUMENTED", "LIVE_VERIFIED" ], "sources": [ { "url": "https://developers.openai.com/api/reference/resources/responses/methods/create", "retrieved_at": "2026-09-18" }, { "url": "https://raw.githubusercontent.com/openai/openai-openapi/master/openapi.yaml", "retrieved_at": "2026-09-18" } ], "live_example": { "object": "response.input_tokens", "input_tokens": 10 }, "_fragment": "generated/fragments/objects/openai-responses-objects.json" }, { "provider": "openai", "object": "CompactResource", "type_or_object_value": "object = \"response.compaction\"", "description": "Result of POST /v1/responses/compact: id (resp_...), created_at, output[] (retained items + compaction item cmp_...), usage.", "fields": [ { "field": "id", "type": "string", "required": true, "enum": null, "default": null, "description": "The unique identifier for the compacted response." }, { "field": "object", "type": "string", "required": true, "enum": [ "response.compaction" ], "default": "response.compaction", "description": "The object type. Always `response.compaction`." }, { "field": "output", "type": "array | object | object | object | object | object | object | object | object | object | object | object | object | object | object | object | object | object | object | object | object | object | object | object | object | object | object | object>", "required": true, "enum": null, "default": null, "description": "The compacted list of output items." }, { "field": "created_at", "type": "integer", "required": true, "enum": null, "default": null, "description": "Unix timestamp (in seconds) when the compacted conversation was created." }, { "field": "usage", "type": "object", "required": true, "enum": null, "default": null, "description": "Token accounting for the compaction pass, including cached, reasoning, and total tokens." }, { "field": "usage.input_tokens", "type": "integer", "required": true, "enum": null, "default": null, "description": "The number of input tokens." }, { "field": "usage.input_tokens_details", "type": "object", "required": true, "enum": null, "default": null, "description": "A detailed breakdown of the input tokens." }, { "field": "usage.output_tokens", "type": "integer", "required": true, "enum": null, "default": null, "description": "The number of output tokens." }, { "field": "usage.output_tokens_details", "type": "object", "required": true, "enum": null, "default": null, "description": "A detailed breakdown of the output tokens." }, { "field": "usage.total_tokens", "type": "integer", "required": true, "enum": null, "default": null, "description": "The total number of tokens used." } ], "status": [ "DOCUMENTED", "LIVE_VERIFIED" ], "sources": [ { "url": "https://developers.openai.com/api/reference/resources/responses/methods/create", "retrieved_at": "2026-09-18" }, { "url": "https://raw.githubusercontent.com/openai/openai-openapi/master/openapi.yaml", "retrieved_at": "2026-09-18" } ], "live_example": { "id": "resp_0ed5b67e8da655fb016aade904482087d288ab999264156e43", "object": "response.compaction", "created_at": 1789782277, "output": [ { "id": "msg_0ed5b67e8da655fb016aade9044d6087d2a639312c73757f0e", "type": "message", "status": "completed", "content": [ { "type": "input_text", "text": "Reply with OK." } ], "role": "user" }, { "id": "msg_0ed5b67e8da655fb016aade9044da087d2b842c4f1437ae3d5", "type": "message", "status": "completed", "content": [ { "type": "input_text", "text": "Reply with OK again." } ], "role": "user" }, { "id": "cmp_0ed5b67e8da655fb016aade904992087d2a7f4f8dbfac97dfa", "type": "compaction", "encrypted_content": "gAAAAABqrekFMDjkZ64ju-Up...(truncated)" } ], "usage": { "input_tokens": 119, "input_tokens_details": { "cache_write_tokens": 0, "cached_tokens": 0 }, "output_tokens": 217, "output_tokens_details": { "reasoning_tokens": 0 }, "total_tokens": 336 } }, "_fragment": "generated/fragments/objects/openai-responses-objects.json" }, { "provider": "openai", "object": "ConversationResource", "type_or_object_value": "object = \"conversation\"", "description": "Conversation object.", "fields": [ { "field": "id", "type": "string", "required": true, "enum": null, "default": null, "description": "The unique ID of the conversation." }, { "field": "object", "type": "string", "required": true, "enum": [ "conversation" ], "default": "conversation", "description": "The object type, which is always `conversation`." }, { "field": "metadata", "type": "any", "required": true, "enum": null, "default": null, "description": "Set of 16 key-value pairs that can be attached to an object. This can be useful for storing additional information about the object in a structured format, and querying for objects via API or the dashboard. Keys are strings with a maximum length of 64 characters. Values are strings with a maximum length of 512 characters." }, { "field": "created_at", "type": "integer", "required": true, "enum": null, "default": null, "description": "The time at which the conversation was created, measured in seconds since the Unix epoch." } ], "status": [ "DOCUMENTED", "LIVE_VERIFIED" ], "sources": [ { "url": "https://developers.openai.com/api/reference/resources/responses/methods/create", "retrieved_at": "2026-09-18" }, { "url": "https://raw.githubusercontent.com/openai/openai-openapi/master/openapi.yaml", "retrieved_at": "2026-09-18" } ], "live_example": { "id": "conv_6aade90dfa208197bf48e4e09c95ce8104b7a5ba78eb9ec2", "object": "conversation", "created_at": 1789782285, "metadata": { "atlas": "openai-core" } }, "_fragment": "generated/fragments/objects/openai-responses-objects.json" }, { "provider": "openai", "object": "ConversationItemList", "type_or_object_value": "object = \"list\"", "description": "Paginated conversation items.", "fields": [ { "field": "object", "type": "string", "required": true, "enum": [ "list" ], "default": null, "description": "The type of object returned, must be `list`." }, { "field": "data", "type": "array | object | object | object | object | object | object | object | object | object | object | object | object | object | object | object | object | object | object | object | object | object | object | object | object | object | object | object | object>", "required": true, "enum": null, "default": null, "description": "A list of conversation items." }, { "field": "data[]", "type": "object | object | object | object | object | object | object | object | object | object | object | object | object | object | object | object | object | object | object | object | object | object | object | object | object | object | object | object | object", "required": false, "enum": null, "default": null, "description": "A single item within a conversation. The set of possible types are the same as the `output` type of a [Response object](https://developers.openai.com/api/reference/resources/responses#%28resource%29%20responses%20%3E%20%28model%29%20response%20%3E%20%28schema%29%20%3E%20%28property%29%20output)." }, { "field": "has_more", "type": "boolean", "required": true, "enum": null, "default": null, "description": "Whether there are more items available." }, { "field": "first_id", "type": "string", "required": true, "enum": null, "default": null, "description": "The ID of the first item in the list." }, { "field": "last_id", "type": "string", "required": true, "enum": null, "default": null, "description": "The ID of the last item in the list." } ], "status": [ "DOCUMENTED", "LIVE_VERIFIED" ], "sources": [ { "url": "https://developers.openai.com/api/reference/resources/responses/methods/create", "retrieved_at": "2026-09-18" }, { "url": "https://raw.githubusercontent.com/openai/openai-openapi/master/openapi.yaml", "retrieved_at": "2026-09-18" } ], "live_example": { "object": "list", "data": [ { "id": "msg_6aade90e86588197a6134f717609bef004b7a5ba78eb9ec2", "type": "message", "status": "completed", "content": [ { "type": "input_text", "text": "Reply with OK." } ], "role": "user" }, { "id": "msg_04b7a5ba78eb9ec2006aade91073b881978d735ac54c02f920", "type": "message", "status": "completed", "content": [ { "type": "input_text", "text": "Reply with OK once more." } ], "role": "user" }, { "id": "msg_04b7a5ba78eb9ec2006aade910bad48197878d60a9a894a80b", "type": "message", "status": "completed", "content": [ { "type": "output_text", "annotations": [], "logprobs": [], "text": "OK" } ], "role": "assistant" } ], "first_id": "msg_6aade90e86588197a6134f717609bef004b7a5ba78eb9ec2", "has_more": false, "last_id": "msg_04b7a5ba78eb9ec2006aade910bad48197878d60a9a894a80b" }, "_fragment": "generated/fragments/objects/openai-responses-objects.json" }, { "provider": "openai", "object": "DeletedConversationResource", "type_or_object_value": "object = \"conversation.deleted\"", "description": "Delete confirmation.", "fields": [ { "field": "object", "type": "string", "required": true, "enum": [ "conversation.deleted" ], "default": "conversation.deleted", "description": "" }, { "field": "deleted", "type": "boolean", "required": true, "enum": null, "default": null, "description": "" }, { "field": "id", "type": "string", "required": true, "enum": null, "default": null, "description": "" } ], "status": [ "DOCUMENTED", "LIVE_VERIFIED" ], "sources": [ { "url": "https://developers.openai.com/api/reference/resources/responses/methods/create", "retrieved_at": "2026-09-18" }, { "url": "https://raw.githubusercontent.com/openai/openai-openapi/master/openapi.yaml", "retrieved_at": "2026-09-18" } ], "live_example": { "id": "conv_6aade90dfa208197bf48e4e09c95ce8104b7a5ba78eb9ec2", "object": "conversation.deleted", "deleted": true }, "_fragment": "generated/fragments/objects/openai-responses-objects.json" }, { "provider": "openai", "object": "Chat completion (CreateChatCompletionResponse)", "type_or_object_value": "object = \"chat.completion\"", "description": "Chat Completions result: choices[].message{role, content, refusal, annotations, tool_calls, audio}, finish_reason, logprobs; usage (CompletionUsage); service_tier; system_fingerprint (deprecated).", "fields": [ { "field": "id", "type": "string", "required": true, "enum": null, "default": null, "description": "A unique identifier for the chat completion." }, { "field": "choices", "type": "array", "required": true, "enum": null, "default": null, "description": "A list of chat completion choices. Can be more than one if `n` is greater than 1." }, { "field": "choices[]", "type": "object", "required": false, "enum": null, "default": null, "description": "" }, { "field": "choices[].finish_reason", "type": "string", "required": true, "enum": [ "stop", "length", "tool_calls", "content_filter", "function_call" ], "default": null, "description": "The reason the model stopped generating tokens. This will be `stop` if the model hit a natural stop point or a provided stop sequence, `length` if the maximum number of tokens specified in the request was reached, `content_filter` if content was omitted due to a flag from our content filters, `tool_calls` if the model called a tool, or `function_call` (deprecated) if the model called a function. R" }, { "field": "choices[].index", "type": "integer", "required": true, "enum": null, "default": null, "description": "The index of the choice in the list of choices." }, { "field": "choices[].message", "type": "object", "required": true, "enum": null, "default": null, "description": "A chat completion message generated by the model." }, { "field": "choices[].message.content", "type": "string | null", "required": true, "enum": null, "default": null, "description": "The contents of the message." }, { "field": "choices[].message.refusal", "type": "string | null", "required": true, "enum": null, "default": null, "description": "The refusal message generated by the model." }, { "field": "choices[].message.tool_calls", "type": "array | object>", "required": false, "enum": null, "default": null, "description": "The tool calls generated by the model, such as function calls." }, { "field": "choices[].message.annotations", "type": "array", "required": false, "enum": null, "default": null, "description": "Annotations for the message, when applicable, as when using the [web search tool](https://developers.openai.com/api/docs/guides/tools-web-search)." }, { "field": "choices[].message.role", "type": "string", "required": true, "enum": [ "assistant" ], "default": null, "description": "The role of the author of this message." }, { "field": "choices[].message.function_call", "type": "object", "required": false, "enum": null, "default": null, "description": "Deprecated and replaced by `tool_calls`. The name and arguments of a function that should be called, as generated by the model.", "deprecated": true }, { "field": "choices[].message.audio", "type": "object | null", "required": false, "enum": null, "default": null, "description": "If the audio output modality is requested, this object contains data about the audio response from the model. [Learn more](https://developers.openai.com/api/docs/guides/audio)." }, { "field": "choices[].logprobs", "type": "object | null", "required": true, "enum": null, "default": null, "description": "Log probability information for the choice." }, { "field": "choices[].logprobs.content", "type": "array", "required": true, "enum": null, "default": null, "description": "A list of message content tokens with log probability information." }, { "field": "choices[].logprobs.refusal", "type": "array", "required": true, "enum": null, "default": null, "description": "A list of message refusal tokens with log probability information." }, { "field": "created", "type": "integer", "required": true, "enum": null, "default": null, "description": "The Unix timestamp (in seconds) of when the chat completion was created." }, { "field": "model", "type": "string", "required": true, "enum": null, "default": null, "description": "The model used for the chat completion." }, { "field": "metadata", "type": "map", "required": false, "enum": null, "default": null, "description": "Set of 16 key-value pairs that can be attached to an object. This can be useful for storing additional information about the object in a structured format, and querying for objects via API or the dashboard. Keys are strings with a maximum length of 64 characters. Values are strings with a maximum length of 512 characters." }, { "field": "service_tier", "type": "string | null", "required": false, "enum": [ "auto", "default", "flex", "scale", "priority", "fast" ], "default": "auto", "description": "Specifies the processing type used for serving the request. - If set to 'auto', then the request will be processed with the service tier configured in the Project settings. Unless otherwise configured, the Project will use 'default'. - If set to 'default', then the request will be processed with the standard pricing and performance for the selected model. - If set to '[flex](https://developers.ope" }, { "field": "system_fingerprint", "type": "string", "required": false, "enum": null, "default": null, "description": "This fingerprint represents the backend configuration that the model runs with. Can be used in conjunction with the `seed` request parameter to understand when backend changes have been made that might impact determinism.", "deprecated": true }, { "field": "object", "type": "string", "required": true, "enum": [ "chat.completion" ], "default": null, "description": "The object type, which is always `chat.completion`." }, { "field": "usage", "type": "object", "required": false, "enum": null, "default": null, "description": "Usage statistics for the completion request." }, { "field": "usage.completion_tokens", "type": "integer", "required": true, "enum": null, "default": 0, "description": "Number of tokens in the generated completion." }, { "field": "usage.prompt_tokens", "type": "integer", "required": true, "enum": null, "default": 0, "description": "Number of tokens in the prompt." }, { "field": "usage.total_tokens", "type": "integer", "required": true, "enum": null, "default": 0, "description": "Total number of tokens used in the request (prompt + completion)." }, { "field": "usage.completion_tokens_details", "type": "object", "required": false, "enum": null, "default": null, "description": "Breakdown of tokens used in a completion." }, { "field": "usage.completion_tokens_details.accepted_prediction_tokens", "type": "integer", "required": false, "enum": null, "default": 0, "description": "When using Predicted Outputs, the number of tokens in the prediction that appeared in the completion." }, { "field": "usage.completion_tokens_details.audio_tokens", "type": "integer", "required": false, "enum": null, "default": 0, "description": "Audio input tokens generated by the model." }, { "field": "usage.completion_tokens_details.reasoning_tokens", "type": "integer", "required": false, "enum": null, "default": 0, "description": "Tokens generated by the model for reasoning." }, { "field": "usage.completion_tokens_details.text_tokens", "type": "integer", "required": false, "enum": null, "default": null, "description": "Text output tokens generated by the model." }, { "field": "usage.completion_tokens_details.rejected_prediction_tokens", "type": "integer", "required": false, "enum": null, "default": 0, "description": "When using Predicted Outputs, the number of tokens in the prediction that did not appear in the completion. However, like reasoning tokens, these tokens are still counted in the total completion tokens for purposes of billing, output, and context window limits." }, { "field": "usage.prompt_tokens_details", "type": "object", "required": false, "enum": null, "default": null, "description": "Breakdown of tokens used in the prompt." }, { "field": "usage.prompt_tokens_details.audio_tokens", "type": "integer", "required": false, "enum": null, "default": 0, "description": "Audio input tokens present in the prompt." }, { "field": "usage.prompt_tokens_details.cached_tokens", "type": "integer", "required": false, "enum": null, "default": 0, "description": "Cached tokens present in the prompt." }, { "field": "usage.prompt_tokens_details.text_tokens", "type": "integer", "required": false, "enum": null, "default": null, "description": "Text input tokens present in the prompt." }, { "field": "usage.prompt_tokens_details.image_tokens", "type": "integer", "required": false, "enum": null, "default": null, "description": "Image input tokens present in the prompt." }, { "field": "usage.prompt_tokens_details.cache_write_tokens", "type": "integer", "required": false, "enum": null, "default": 0, "description": "The unadjusted number of prompt tokens written to cache." }, { "field": "moderation", "type": "object | null", "required": false, "enum": null, "default": null, "description": "Moderation results for the request input and generated output, if moderated completions were requested." }, { "field": "moderation.input", "type": "object | object", "required": true, "enum": null, "default": null, "description": "Moderation for the request input." }, { "field": "moderation.input(moderation_results)", "type": "object", "required": true, "enum": null, "default": null, "description": "Successful moderation results for the request input or generated output." }, { "field": "moderation.input(error)", "type": "object", "required": true, "enum": null, "default": null, "description": "An error produced while attempting moderation." }, { "field": "moderation.output", "type": "object | object", "required": true, "enum": null, "default": null, "description": "Moderation for the generated output." }, { "field": "moderation.output(moderation_results)", "type": "object", "required": true, "enum": null, "default": null, "description": "Successful moderation results for the request input or generated output." }, { "field": "moderation.output(error)", "type": "object", "required": true, "enum": null, "default": null, "description": "An error produced while attempting moderation." } ], "status": [ "DOCUMENTED", "LIVE_VERIFIED" ], "sources": [ { "url": "https://developers.openai.com/api/reference/resources/chat/subresources/completions/methods/create", "retrieved_at": "2026-09-18" }, { "url": "https://raw.githubusercontent.com/openai/openai-openapi/master/openapi.yaml", "retrieved_at": "2026-09-18" } ], "live_example": { "id": "chatcmpl-EPeQHZhkba6K4Tw2J4h0LJHJfsvbv", "object": "chat.completion", "created": 1789782293, "model": "gpt-4.1-nano-2025-04-14", "choices": [ { "index": 0, "message": { "role": "assistant", "content": "OK", "refusal": null, "annotations": [] }, "logprobs": null, "finish_reason": "stop" } ], "usage": { "prompt_tokens": 11, "completion_tokens": 1, "total_tokens": 12, "prompt_tokens_details": { "cached_tokens": 0, "audio_tokens": 0 }, "completion_tokens_details": { "reasoning_tokens": 0, "audio_tokens": 0, "accepted_prediction_tokens": 0, "rejected_prediction_tokens": 0 } }, "service_tier": "default", "system_fingerprint": "fp_6afed20c8d" }, "live_fields_not_in_spec": [ "frequency_penalty", "input_user", "metadata", "presence_penalty", "request_id", "response_format", "seed", "temperature", "tool_choice", "tools", "top_p" ], "live_notes": "Extra fields appear on GET /v1/chat/completions/{id} (stored request echo): request_id, input_user, seed, temperature, top_p, presence_penalty, frequency_penalty, tool_choice, tools, response_format, metadata.", "_fragment": "generated/fragments/objects/openai-responses-objects.json" }, { "provider": "openai", "object": "Chat completion message (ChatCompletionResponseMessage)", "type_or_object_value": "choices[].message", "description": "Assistant message in a chat completion.", "fields": [ { "field": "content", "type": "string | null", "required": true, "enum": null, "default": null, "description": "The contents of the message." }, { "field": "refusal", "type": "string | null", "required": true, "enum": null, "default": null, "description": "The refusal message generated by the model." }, { "field": "tool_calls", "type": "array | object>", "required": false, "enum": null, "default": null, "description": "The tool calls generated by the model, such as function calls." }, { "field": "tool_calls[]", "type": "object | object", "required": false, "enum": null, "default": null, "description": "" }, { "field": "tool_calls[](function)", "type": "object", "required": false, "enum": null, "default": null, "description": "A call to a function tool created by the model." }, { "field": "tool_calls[](function).id", "type": "string", "required": true, "enum": null, "default": null, "description": "The ID of the tool call." }, { "field": "tool_calls[](function).type", "type": "string", "required": true, "enum": [ "function" ], "default": null, "description": "The type of the tool. Currently, only `function` is supported." }, { "field": "tool_calls[](function).function", "type": "object", "required": true, "enum": null, "default": null, "description": "The function that the model called." }, { "field": "tool_calls[](custom)", "type": "object", "required": false, "enum": null, "default": null, "description": "A call to a custom tool created by the model." }, { "field": "tool_calls[](custom).id", "type": "string", "required": true, "enum": null, "default": null, "description": "The ID of the tool call." }, { "field": "tool_calls[](custom).type", "type": "string", "required": true, "enum": [ "custom" ], "default": null, "description": "The type of the tool. Always `custom`." }, { "field": "tool_calls[](custom).custom", "type": "object", "required": true, "enum": null, "default": null, "description": "The custom tool that the model called." }, { "field": "annotations", "type": "array", "required": false, "enum": null, "default": null, "description": "Annotations for the message, when applicable, as when using the [web search tool](https://developers.openai.com/api/docs/guides/tools-web-search)." }, { "field": "annotations[]", "type": "object", "required": false, "enum": null, "default": null, "description": "A URL citation when using web search." }, { "field": "annotations[].type", "type": "string", "required": true, "enum": [ "url_citation" ], "default": null, "description": "The type of the URL citation. Always `url_citation`." }, { "field": "annotations[].url_citation", "type": "object", "required": true, "enum": null, "default": null, "description": "A URL citation when using web search." }, { "field": "annotations[].url_citation.end_index", "type": "integer", "required": true, "enum": null, "default": null, "description": "The index of the last character of the URL citation in the message." }, { "field": "annotations[].url_citation.start_index", "type": "integer", "required": true, "enum": null, "default": null, "description": "The index of the first character of the URL citation in the message." }, { "field": "annotations[].url_citation.url", "type": "string", "required": true, "enum": null, "default": null, "description": "The URL of the web resource." }, { "field": "annotations[].url_citation.title", "type": "string", "required": true, "enum": null, "default": null, "description": "The title of the web resource." }, { "field": "role", "type": "string", "required": true, "enum": [ "assistant" ], "default": null, "description": "The role of the author of this message." }, { "field": "function_call", "type": "object", "required": false, "enum": null, "default": null, "description": "Deprecated and replaced by `tool_calls`. The name and arguments of a function that should be called, as generated by the model.", "deprecated": true }, { "field": "function_call.arguments", "type": "string", "required": true, "enum": null, "default": null, "description": "The arguments to call the function with, as generated by the model in JSON format. Note that the model does not always generate valid JSON, and may hallucinate parameters not defined by your function schema. Validate the arguments in your code before calling your function." }, { "field": "function_call.name", "type": "string", "required": true, "enum": null, "default": null, "description": "The name of the function to call." }, { "field": "audio", "type": "object | null", "required": false, "enum": null, "default": null, "description": "If the audio output modality is requested, this object contains data about the audio response from the model. [Learn more](https://developers.openai.com/api/docs/guides/audio)." }, { "field": "audio.id", "type": "string", "required": true, "enum": null, "default": null, "description": "Unique identifier for this audio response." }, { "field": "audio.expires_at", "type": "integer", "required": true, "enum": null, "default": null, "description": "The Unix timestamp (in seconds) for when this audio response will no longer be accessible on the server for use in multi-turn conversations." }, { "field": "audio.data", "type": "string", "required": true, "enum": null, "default": null, "description": "Base64 encoded audio bytes generated by the model, in the format specified in the request." }, { "field": "audio.transcript", "type": "string", "required": true, "enum": null, "default": null, "description": "Transcript of the audio generated by the model." } ], "status": [ "DOCUMENTED" ], "sources": [ { "url": "https://developers.openai.com/api/reference/resources/chat/subresources/completions/methods/create", "retrieved_at": "2026-09-18" }, { "url": "https://raw.githubusercontent.com/openai/openai-openapi/master/openapi.yaml", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/openai-responses-objects.json" }, { "provider": "openai", "object": "CompletionUsage", "type_or_object_value": "usage", "description": "Usage for chat/legacy completions: prompt_tokens, completion_tokens, total_tokens, prompt_tokens_details{cached_tokens, audio_tokens}, completion_tokens_details{reasoning_tokens, audio_tokens, accepted_prediction_tokens, rejected_prediction_tokens}.", "fields": [ { "field": "completion_tokens", "type": "integer", "required": true, "enum": null, "default": 0, "description": "Number of tokens in the generated completion." }, { "field": "prompt_tokens", "type": "integer", "required": true, "enum": null, "default": 0, "description": "Number of tokens in the prompt." }, { "field": "total_tokens", "type": "integer", "required": true, "enum": null, "default": 0, "description": "Total number of tokens used in the request (prompt + completion)." }, { "field": "completion_tokens_details", "type": "object", "required": false, "enum": null, "default": null, "description": "Breakdown of tokens used in a completion." }, { "field": "completion_tokens_details.accepted_prediction_tokens", "type": "integer", "required": false, "enum": null, "default": 0, "description": "When using Predicted Outputs, the number of tokens in the prediction that appeared in the completion." }, { "field": "completion_tokens_details.audio_tokens", "type": "integer", "required": false, "enum": null, "default": 0, "description": "Audio input tokens generated by the model." }, { "field": "completion_tokens_details.reasoning_tokens", "type": "integer", "required": false, "enum": null, "default": 0, "description": "Tokens generated by the model for reasoning." }, { "field": "completion_tokens_details.text_tokens", "type": "integer", "required": false, "enum": null, "default": null, "description": "Text output tokens generated by the model." }, { "field": "completion_tokens_details.rejected_prediction_tokens", "type": "integer", "required": false, "enum": null, "default": 0, "description": "When using Predicted Outputs, the number of tokens in the prediction that did not appear in the completion. However, like reasoning tokens, these tokens are still counted in the total completion tokens for purposes of billing, output, and context window limits." }, { "field": "prompt_tokens_details", "type": "object", "required": false, "enum": null, "default": null, "description": "Breakdown of tokens used in the prompt." }, { "field": "prompt_tokens_details.audio_tokens", "type": "integer", "required": false, "enum": null, "default": 0, "description": "Audio input tokens present in the prompt." }, { "field": "prompt_tokens_details.cached_tokens", "type": "integer", "required": false, "enum": null, "default": 0, "description": "Cached tokens present in the prompt." }, { "field": "prompt_tokens_details.text_tokens", "type": "integer", "required": false, "enum": null, "default": null, "description": "Text input tokens present in the prompt." }, { "field": "prompt_tokens_details.image_tokens", "type": "integer", "required": false, "enum": null, "default": null, "description": "Image input tokens present in the prompt." }, { "field": "prompt_tokens_details.cache_write_tokens", "type": "integer", "required": false, "enum": null, "default": 0, "description": "The unadjusted number of prompt tokens written to cache." } ], "status": [ "DOCUMENTED", "LIVE_VERIFIED" ], "sources": [ { "url": "https://developers.openai.com/api/reference/resources/chat/subresources/completions/methods/create", "retrieved_at": "2026-09-18" }, { "url": "https://raw.githubusercontent.com/openai/openai-openapi/master/openapi.yaml", "retrieved_at": "2026-09-18" } ], "live_example": { "prompt_tokens": 11, "completion_tokens": 1, "total_tokens": 12, "prompt_tokens_details": { "cached_tokens": 0, "audio_tokens": 0 }, "completion_tokens_details": { "reasoning_tokens": 0, "audio_tokens": 0, "accepted_prediction_tokens": 0, "rejected_prediction_tokens": 0 } }, "_fragment": "generated/fragments/objects/openai-responses-objects.json" }, { "provider": "openai", "object": "Chat completion chunk (CreateChatCompletionStreamResponse)", "type_or_object_value": "object = \"chat.completion.chunk\"", "description": "Streaming chunk; see streaming-events/openai-chat-completions.json.", "fields": [ { "field": "id", "type": "string", "required": true, "enum": null, "default": null, "description": "A unique identifier for the chat completion. Each chunk has the same ID." }, { "field": "choices", "type": "array", "required": true, "enum": null, "default": null, "description": "A list of chat completion choices. Can contain more than one elements if `n` is greater than 1. Can also be empty for the last chunk if you set `stream_options: {\"include_usage\": true}`." }, { "field": "choices[]", "type": "object", "required": false, "enum": null, "default": null, "description": "" }, { "field": "choices[].delta", "type": "object", "required": true, "enum": null, "default": null, "description": "A chat completion delta generated by streamed model responses." }, { "field": "choices[].delta.content", "type": "string | null", "required": false, "enum": null, "default": null, "description": "The contents of the chunk message." }, { "field": "choices[].delta.function_call", "type": "object", "required": false, "enum": null, "default": null, "description": "Deprecated and replaced by `tool_calls`. The name and arguments of a function that should be called, as generated by the model.", "deprecated": true }, { "field": "choices[].delta.tool_calls", "type": "array", "required": false, "enum": null, "default": null, "description": "" }, { "field": "choices[].delta.role", "type": "string", "required": false, "enum": [ "developer", "system", "user", "assistant", "tool" ], "default": null, "description": "The role of the author of this message." }, { "field": "choices[].delta.refusal", "type": "string | null", "required": false, "enum": null, "default": null, "description": "The refusal message generated by the model." }, { "field": "choices[].logprobs", "type": "object | null", "required": false, "enum": null, "default": null, "description": "Log probability information for the choice." }, { "field": "choices[].logprobs.content", "type": "array", "required": true, "enum": null, "default": null, "description": "A list of message content tokens with log probability information." }, { "field": "choices[].logprobs.refusal", "type": "array", "required": true, "enum": null, "default": null, "description": "A list of message refusal tokens with log probability information." }, { "field": "choices[].finish_reason", "type": "string | null", "required": true, "enum": [ "stop", "length", "tool_calls", "content_filter", "function_call" ], "default": null, "description": "The reason the model stopped generating tokens. This will be `stop` if the model hit a natural stop point or a provided stop sequence, `length` if the maximum number of tokens specified in the request was reached, `content_filter` if content was omitted due to a flag from our content filters, `tool_calls` if the model called a tool, or `function_call` (deprecated) if the model called a function." }, { "field": "choices[].index", "type": "integer", "required": true, "enum": null, "default": null, "description": "The index of the choice in the list of choices." }, { "field": "created", "type": "integer", "required": true, "enum": null, "default": null, "description": "The Unix timestamp (in seconds) of when the chat completion was created. Each chunk has the same timestamp." }, { "field": "model", "type": "string", "required": true, "enum": null, "default": null, "description": "The model to generate the completion." }, { "field": "obfuscation", "type": "string", "required": false, "enum": null, "default": null, "description": "An obfuscation string added to normalize the size of streamed chunks as a mitigation to certain side-channel attacks. The field is included by default and omitted when `stream_options.include_obfuscation` is `false`." }, { "field": "service_tier", "type": "string | null", "required": false, "enum": [ "auto", "default", "flex", "scale", "priority", "fast" ], "default": "auto", "description": "Specifies the processing type used for serving the request. - If set to 'auto', then the request will be processed with the service tier configured in the Project settings. Unless otherwise configured, the Project will use 'default'. - If set to 'default', then the request will be processed with the standard pricing and performance for the selected model. - If set to '[flex](https://developers.ope" }, { "field": "system_fingerprint", "type": "string", "required": false, "enum": null, "default": null, "description": "This fingerprint represents the backend configuration that the model runs with. Can be used in conjunction with the `seed` request parameter to understand when backend changes have been made that might impact determinism.", "deprecated": true }, { "field": "object", "type": "string", "required": true, "enum": [ "chat.completion.chunk" ], "default": null, "description": "The object type, which is always `chat.completion.chunk`." }, { "field": "usage", "type": "object | null", "required": false, "enum": null, "default": null, "description": "An optional field that will only be present when you set `stream_options: {\"include_usage\": true}` in your request. When present, it contains a null value **except for the last chunk** which contains the token usage statistics for the entire request. **NOTE:** If the stream is interrupted or cancelled, you may not receive the final usage chunk which contains the total token usage for the request." }, { "field": "usage.completion_tokens", "type": "integer", "required": true, "enum": null, "default": 0, "description": "Number of tokens in the generated completion." }, { "field": "usage.prompt_tokens", "type": "integer", "required": true, "enum": null, "default": 0, "description": "Number of tokens in the prompt." }, { "field": "usage.total_tokens", "type": "integer", "required": true, "enum": null, "default": 0, "description": "Total number of tokens used in the request (prompt + completion)." }, { "field": "usage.completion_tokens_details", "type": "object", "required": false, "enum": null, "default": null, "description": "Breakdown of tokens used in a completion." }, { "field": "usage.completion_tokens_details.accepted_prediction_tokens", "type": "integer", "required": false, "enum": null, "default": 0, "description": "When using Predicted Outputs, the number of tokens in the prediction that appeared in the completion." }, { "field": "usage.completion_tokens_details.audio_tokens", "type": "integer", "required": false, "enum": null, "default": 0, "description": "Audio input tokens generated by the model." }, { "field": "usage.completion_tokens_details.reasoning_tokens", "type": "integer", "required": false, "enum": null, "default": 0, "description": "Tokens generated by the model for reasoning." }, { "field": "usage.completion_tokens_details.text_tokens", "type": "integer", "required": false, "enum": null, "default": null, "description": "Text output tokens generated by the model." }, { "field": "usage.completion_tokens_details.rejected_prediction_tokens", "type": "integer", "required": false, "enum": null, "default": 0, "description": "When using Predicted Outputs, the number of tokens in the prediction that did not appear in the completion. However, like reasoning tokens, these tokens are still counted in the total completion tokens for purposes of billing, output, and context window limits." }, { "field": "usage.prompt_tokens_details", "type": "object", "required": false, "enum": null, "default": null, "description": "Breakdown of tokens used in the prompt." }, { "field": "usage.prompt_tokens_details.audio_tokens", "type": "integer", "required": false, "enum": null, "default": 0, "description": "Audio input tokens present in the prompt." }, { "field": "usage.prompt_tokens_details.cached_tokens", "type": "integer", "required": false, "enum": null, "default": 0, "description": "Cached tokens present in the prompt." }, { "field": "usage.prompt_tokens_details.text_tokens", "type": "integer", "required": false, "enum": null, "default": null, "description": "Text input tokens present in the prompt." }, { "field": "usage.prompt_tokens_details.image_tokens", "type": "integer", "required": false, "enum": null, "default": null, "description": "Image input tokens present in the prompt." }, { "field": "usage.prompt_tokens_details.cache_write_tokens", "type": "integer", "required": false, "enum": null, "default": 0, "description": "The unadjusted number of prompt tokens written to cache." }, { "field": "moderation", "type": "object | null", "required": false, "enum": null, "default": null, "description": "Moderation results for the request input and generated output. Present on the moderation chunk when moderated completions are requested." }, { "field": "moderation.input", "type": "object | object", "required": true, "enum": null, "default": null, "description": "Moderation for the request input." }, { "field": "moderation.input(moderation_results)", "type": "object", "required": true, "enum": null, "default": null, "description": "Successful moderation results for the request input or generated output." }, { "field": "moderation.input(error)", "type": "object", "required": true, "enum": null, "default": null, "description": "An error produced while attempting moderation." }, { "field": "moderation.output", "type": "object | object", "required": true, "enum": null, "default": null, "description": "Moderation for the generated output." }, { "field": "moderation.output(moderation_results)", "type": "object", "required": true, "enum": null, "default": null, "description": "Successful moderation results for the request input or generated output." }, { "field": "moderation.output(error)", "type": "object", "required": true, "enum": null, "default": null, "description": "An error produced while attempting moderation." } ], "status": [ "DOCUMENTED" ], "sources": [ { "url": "https://developers.openai.com/api/reference/resources/chat/subresources/completions/streaming-events", "retrieved_at": "2026-09-18" }, { "url": "https://raw.githubusercontent.com/openai/openai-openapi/master/openapi.yaml", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/objects/openai-responses-objects.json" }, { "provider": "openai", "object": "ChatCompletionList / ChatCompletionMessageList / ChatCompletionDeleted", "type_or_object_value": "object = \"list\" | \"chat.completion.deleted\"", "description": "List wrappers for stored chat completions and their messages; delete confirmation.", "fields": [ { "field": "object", "type": "string", "required": true, "enum": [ "list" ], "default": "list", "description": "The type of this object. It is always set to \"list\"." }, { "field": "data", "type": "array", "required": true, "enum": null, "default": null, "description": "An array of chat completion objects." }, { "field": "data[]", "type": "object", "required": false, "enum": null, "default": null, "description": "Represents a chat completion response returned by model, based on the provided input." }, { "field": "first_id", "type": "string", "required": true, "enum": null, "default": null, "description": "The identifier of the first chat completion in the data array." }, { "field": "last_id", "type": "string", "required": true, "enum": null, "default": null, "description": "The identifier of the last chat completion in the data array." }, { "field": "has_more", "type": "boolean", "required": true, "enum": null, "default": null, "description": "Indicates whether there are more Chat Completions available." }, { "field": "messages.data[].content", "type": "string | null", "required": true, "enum": null, "default": null, "description": "The contents of the message." }, { "field": "messages.data[].refusal", "type": "string | null", "required": true, "enum": null, "default": null, "description": "The refusal message generated by the model." }, { "field": "messages.data[].tool_calls", "type": "array | object>", "required": false, "enum": null, "default": null, "description": "The tool calls generated by the model, such as function calls." }, { "field": "messages.data[].tool_calls[]", "type": "object | object", "required": false, "enum": null, "default": null, "description": "" }, { "field": "messages.data[].annotations", "type": "array", "required": false, "enum": null, "default": null, "description": "Annotations for the message, when applicable, as when using the [web search tool](https://developers.openai.com/api/docs/guides/tools-web-search)." }, { "field": "messages.data[].annotations[]", "type": "object", "required": false, "enum": null, "default": null, "description": "A URL citation when using web search." }, { "field": "messages.data[].role", "type": "string", "required": true, "enum": [ "assistant" ], "default": null, "description": "The role of the author of this message." }, { "field": "messages.data[].function_call", "type": "object", "required": false, "enum": null, "default": null, "description": "Deprecated and replaced by `tool_calls`. The name and arguments of a function that should be called, as generated by the model.", "deprecated": true }, { "field": "messages.data[].audio", "type": "object | null", "required": false, "enum": null, "default": null, "description": "If the audio output modality is requested, this object contains data about the audio response from the model. [Learn more](https://developers.openai.com/api/docs/guides/audio)." }, { "field": "messages.data[].id", "type": "string", "required": true, "enum": null, "default": null, "description": "The identifier of the chat message." }, { "field": "messages.data[].content_parts", "type": "array | object>", "required": false, "enum": null, "default": null, "description": "If a content parts array was provided, this is an array of `text` and `image_url` parts. Otherwise, null." }, { "field": "messages.data[].content_parts[]", "type": "object | object", "required": false, "enum": null, "default": null, "description": "" }, { "field": "object", "type": "string", "required": true, "enum": [ "chat.completion.deleted" ], "default": null, "description": "The type of object being deleted." }, { "field": "id", "type": "string", "required": true, "enum": null, "default": null, "description": "The ID of the chat completion that was deleted." }, { "field": "deleted", "type": "boolean", "required": true, "enum": null, "default": null, "description": "Whether the chat completion was deleted." } ], "status": [ "DOCUMENTED", "LIVE_VERIFIED" ], "sources": [ { "url": "https://developers.openai.com/api/reference/resources/chat/subresources/completions/methods/list", "retrieved_at": "2026-09-18" }, { "url": "https://raw.githubusercontent.com/openai/openai-openapi/master/openapi.yaml", "retrieved_at": "2026-09-18" } ], "live_example": { "messages": { "object": "list", "data": [ { "id": "chatcmpl-EPeQIxYbGWnmCZK1AVyIkziHT8E7j-0", "role": "user", "content": "Reply with OK.", "content_parts": null, "name": null } ], "first_id": "chatcmpl-EPeQIxYbGWnmCZK1AVyIkziHT8E7j-0", "last_id": "chatcmpl-EPeQIxYbGWnmCZK1AVyIkziHT8E7j-0", "has_more": false }, "deleted": { "object": "chat.completion.deleted", "id": "chatcmpl-EPeQIxYbGWnmCZK1AVyIkziHT8E7j", "deleted": true } }, "_fragment": "generated/fragments/objects/openai-responses-objects.json" }, { "provider": "openai", "object": "Text completion (CreateCompletionResponse)", "type_or_object_value": "object = \"text_completion\"", "description": "Legacy completion object: choices[].{text, index, logprobs{tokens, token_logprobs, top_logprobs, text_offset}, finish_reason}, usage.", "fields": [ { "field": "id", "type": "string", "required": true, "enum": null, "default": null, "description": "A unique identifier for the completion." }, { "field": "choices", "type": "array", "required": true, "enum": null, "default": null, "description": "The list of completion choices the model generated for the input prompt." }, { "field": "choices[]", "type": "object", "required": false, "enum": null, "default": null, "description": "" }, { "field": "choices[].finish_reason", "type": "string", "required": true, "enum": [ "stop", "length", "content_filter" ], "default": null, "description": "The reason the model stopped generating tokens. This will be `stop` if the model hit a natural stop point or a provided stop sequence, `length` if the maximum number of tokens specified in the request was reached, or `content_filter` if content was omitted due to a flag from our content filters." }, { "field": "choices[].index", "type": "integer", "required": true, "enum": null, "default": null, "description": "" }, { "field": "choices[].logprobs", "type": "object | null", "required": true, "enum": null, "default": null, "description": "" }, { "field": "choices[].logprobs.text_offset", "type": "array", "required": false, "enum": null, "default": null, "description": "" }, { "field": "choices[].logprobs.token_logprobs", "type": "array", "required": false, "enum": null, "default": null, "description": "" }, { "field": "choices[].logprobs.tokens", "type": "array", "required": false, "enum": null, "default": null, "description": "" }, { "field": "choices[].logprobs.top_logprobs", "type": "array>", "required": false, "enum": null, "default": null, "description": "" }, { "field": "choices[].text", "type": "string", "required": true, "enum": null, "default": null, "description": "" }, { "field": "created", "type": "integer", "required": true, "enum": null, "default": null, "description": "The Unix timestamp (in seconds) of when the completion was created." }, { "field": "model", "type": "string", "required": true, "enum": null, "default": null, "description": "The model used for completion." }, { "field": "system_fingerprint", "type": "string", "required": false, "enum": null, "default": null, "description": "This fingerprint represents the backend configuration that the model runs with. Can be used in conjunction with the `seed` request parameter to understand when backend changes have been made that might impact determinism." }, { "field": "object", "type": "string", "required": true, "enum": [ "text_completion" ], "default": null, "description": "The object type, which is always \"text_completion\"" }, { "field": "usage", "type": "object", "required": false, "enum": null, "default": null, "description": "Usage statistics for the completion request." }, { "field": "usage.completion_tokens", "type": "integer", "required": true, "enum": null, "default": 0, "description": "Number of tokens in the generated completion." }, { "field": "usage.prompt_tokens", "type": "integer", "required": true, "enum": null, "default": 0, "description": "Number of tokens in the prompt." }, { "field": "usage.total_tokens", "type": "integer", "required": true, "enum": null, "default": 0, "description": "Total number of tokens used in the request (prompt + completion)." }, { "field": "usage.completion_tokens_details", "type": "object", "required": false, "enum": null, "default": null, "description": "Breakdown of tokens used in a completion." }, { "field": "usage.completion_tokens_details.accepted_prediction_tokens", "type": "integer", "required": false, "enum": null, "default": 0, "description": "When using Predicted Outputs, the number of tokens in the prediction that appeared in the completion." }, { "field": "usage.completion_tokens_details.audio_tokens", "type": "integer", "required": false, "enum": null, "default": 0, "description": "Audio input tokens generated by the model." }, { "field": "usage.completion_tokens_details.reasoning_tokens", "type": "integer", "required": false, "enum": null, "default": 0, "description": "Tokens generated by the model for reasoning." }, { "field": "usage.completion_tokens_details.text_tokens", "type": "integer", "required": false, "enum": null, "default": null, "description": "Text output tokens generated by the model." }, { "field": "usage.completion_tokens_details.rejected_prediction_tokens", "type": "integer", "required": false, "enum": null, "default": 0, "description": "When using Predicted Outputs, the number of tokens in the prediction that did not appear in the completion. However, like reasoning tokens, these tokens are still counted in the total completion tokens for purposes of billing, output, and context window limits." }, { "field": "usage.prompt_tokens_details", "type": "object", "required": false, "enum": null, "default": null, "description": "Breakdown of tokens used in the prompt." }, { "field": "usage.prompt_tokens_details.audio_tokens", "type": "integer", "required": false, "enum": null, "default": 0, "description": "Audio input tokens present in the prompt." }, { "field": "usage.prompt_tokens_details.cached_tokens", "type": "integer", "required": false, "enum": null, "default": 0, "description": "Cached tokens present in the prompt." }, { "field": "usage.prompt_tokens_details.text_tokens", "type": "integer", "required": false, "enum": null, "default": null, "description": "Text input tokens present in the prompt." }, { "field": "usage.prompt_tokens_details.image_tokens", "type": "integer", "required": false, "enum": null, "default": null, "description": "Image input tokens present in the prompt." }, { "field": "usage.prompt_tokens_details.cache_write_tokens", "type": "integer", "required": false, "enum": null, "default": 0, "description": "The unadjusted number of prompt tokens written to cache." } ], "status": [ "DOCUMENTED", "LEGACY", "LIVE_VERIFIED" ], "sources": [ { "url": "https://developers.openai.com/api/reference/resources/completions/methods/create", "retrieved_at": "2026-09-18" }, { "url": "https://raw.githubusercontent.com/openai/openai-openapi/master/openapi.yaml", "retrieved_at": "2026-09-18" } ], "live_example": { "id": "cmpl-EPeQRoNLGecGLCec2TobwS3m5VPKn", "object": "text_completion", "created": 1789782303, "model": "gpt-3.5-turbo-instruct:20230824-v2", "choices": [ { "text": "\n\nOK.", "index": 0, "logprobs": null, "finish_reason": "stop" } ], "usage": { "prompt_tokens": 3, "completion_tokens": 3, "total_tokens": 6 } }, "_fragment": "generated/fragments/objects/openai-responses-objects.json" }, { "provider": "openai", "object": "Logprobs (ResponseLogProb / ChatCompletionTokenLogprob)", "type_or_object_value": "logprobs[]", "description": "Per-token log probabilities: token, logprob, bytes[], top_logprobs[].", "fields": [ { "field": "token", "type": "string", "required": true, "enum": null, "default": null, "description": "A possible text token." }, { "field": "logprob", "type": "number", "required": true, "enum": null, "default": null, "description": "The log probability of this token." }, { "field": "top_logprobs", "type": "array", "required": false, "enum": null, "default": null, "description": "The log probabilities of up to 20 of the most likely tokens." }, { "field": "top_logprobs[]", "type": "object", "required": false, "enum": null, "default": null, "description": "" }, { "field": "top_logprobs[].token", "type": "string", "required": false, "enum": null, "default": null, "description": "A possible text token." }, { "field": "top_logprobs[].logprob", "type": "number", "required": false, "enum": null, "default": null, "description": "The log probability of this token." }, { "field": "chat: token", "type": "string", "required": true, "enum": null, "default": null, "description": "The token." }, { "field": "chat: logprob", "type": "number", "required": true, "enum": null, "default": null, "description": "The log probability of this token, if it is within the top 20 most likely tokens. Otherwise, the value `-9999.0` is used to signify that the token is very unlikely." }, { "field": "chat: bytes", "type": "array", "required": true, "enum": null, "default": null, "description": "A list of integers representing the UTF-8 bytes representation of the token. Useful in instances where characters are represented by multiple tokens and their byte representations must be combined to generate the correct text representation. Can be `null` if there is no bytes representation for the token." }, { "field": "chat: bytes[]", "type": "integer", "required": false, "enum": null, "default": null, "description": "" }, { "field": "chat: top_logprobs", "type": "array", "required": true, "enum": null, "default": null, "description": "List of the most likely tokens and their log probability, at this token position. The number of entries may be fewer than the requested `top_logprobs`." }, { "field": "chat: top_logprobs[]", "type": "object", "required": false, "enum": null, "default": null, "description": "" }, { "field": "chat: top_logprobs[].token", "type": "string", "required": true, "enum": null, "default": null, "description": "The token." }, { "field": "chat: top_logprobs[].logprob", "type": "number", "required": true, "enum": null, "default": null, "description": "The log probability of this token, if it is within the top 20 most likely tokens. Otherwise, the value `-9999.0` is used to signify that the token is very unlikely." }, { "field": "chat: top_logprobs[].bytes", "type": "array", "required": true, "enum": null, "default": null, "description": "A list of integers representing the UTF-8 bytes representation of the token. Useful in instances where characters are represented by multiple tokens and their byte representations must be combined to generate the correct text representation. Can be `null` if there is no bytes representation for the token." } ], "status": [ "DOCUMENTED", "LIVE_VERIFIED" ], "sources": [ { "url": "https://developers.openai.com/api/reference/resources/responses/methods/create", "retrieved_at": "2026-09-18" }, { "url": "https://raw.githubusercontent.com/openai/openai-openapi/master/openapi.yaml", "retrieved_at": "2026-09-18" } ], "live_example": { "responses": { "bytes": [ 79, 75 ], "logprob": -9e-06, "token": "OK", "top_logprobs": [ { "bytes": [ 79, 75 ], "logprob": -8e-06, "token": "OK" } ] } }, "_fragment": "generated/fragments/objects/openai-responses-objects.json" }, { "provider": "xai", "object": "ChatCompletion", "name": "ChatCompletion", "type_or_object_value": "object = \"chat.completion\"", "description": "Non-streaming /v1/chat/completions (and deferred-completion, batch chat_get_completion) response. Live extras vs spec: none; `service_tier` always present; `citations`/`output_files` absent when unused; usage.cost_in_usd_ticks present (1e10 ticks = $1).", "fields": [ { "field": "choices", "type": "array", "required": true, "enum": null, "default": null, "description": "A list of response choices from the model. The length corresponds to the `n` in request body (default to 1)." }, { "field": "choices[].finish_reason", "type": "string | null", "required": false, "enum": null, "default": null, "description": "Finish reason. `\"stop\"` means the inference has reached a model-defined or user-supplied stop sequence in `stop`. `\"length\"` means the inference result has reached models' maximum allowed token length or user defined value in `max_tokens`. `\"end_turn\"` or `null` in streaming mode when the chunk is not the last." }, { "field": "choices[].index", "type": "integer", "required": true, "enum": null, "default": null, "description": "Index of the choice within the response choices, starting from 0." }, { "field": "choices[].logprobs", "type": "null | LogProbs", "required": false, "enum": null, "default": null, "description": null }, { "field": "choices[].logprobs.content", "type": "array | null", "required": false, "enum": null, "default": null, "description": "An array the log probabilities of each output token returned." }, { "field": "choices[].logprobs.content[].bytes", "type": "array | null", "required": false, "enum": null, "default": null, "description": "The ASCII encoding of the output character." }, { "field": "choices[].logprobs.content[].logprob", "type": "number", "required": true, "enum": null, "default": null, "description": "The log probability of returning this token." }, { "field": "choices[].logprobs.content[].token", "type": "string", "required": true, "enum": null, "default": null, "description": "The token." }, { "field": "choices[].logprobs.content[].top_logprobs", "type": "array", "required": true, "enum": null, "default": null, "description": "An array of the most likely tokens to return at this token position." }, { "field": "choices[].logprobs.content[].top_logprobs[].bytes", "type": "array | null", "required": false, "enum": null, "default": null, "description": "The ASCII encoding of the output character." }, { "field": "choices[].logprobs.content[].top_logprobs[].logprob", "type": "number", "required": true, "enum": null, "default": null, "description": "The log probability of returning this token." }, { "field": "choices[].logprobs.content[].top_logprobs[].token", "type": "string", "required": true, "enum": null, "default": null, "description": "The token." }, { "field": "choices[].message", "type": "ChoiceMessage", "required": true, "enum": null, "default": null, "description": "The generated chat completion message." }, { "field": "choices[].message.content", "type": "string | null", "required": false, "enum": null, "default": null, "description": "The content of the message." }, { "field": "choices[].message.reasoning_content", "type": "string | null", "required": false, "enum": null, "default": null, "description": "The reasoning trace generated by the model." }, { "field": "choices[].message.refusal", "type": "string | null", "required": false, "enum": null, "default": null, "description": "The reason given by model if the model is unable to generate a response. null if model is able to generate." }, { "field": "choices[].message.role", "type": "string", "required": true, "enum": null, "default": null, "description": "The role that the message belongs to, the response from model is always `\"assistant\"`." }, { "field": "choices[].message.tool_calls", "type": "array | null", "required": false, "enum": null, "default": null, "description": "A list of tool calls asked by model for user to perform." }, { "field": "choices[].message.tool_calls[].function", "type": "Function", "required": true, "enum": null, "default": null, "description": "Function to call for the tool call." }, { "field": "choices[].message.tool_calls[].function.arguments", "type": "string", "required": true, "enum": null, "default": null, "description": null }, { "field": "choices[].message.tool_calls[].function.name", "type": "string", "required": true, "enum": null, "default": null, "description": null }, { "field": "choices[].message.tool_calls[].id", "type": "string", "required": true, "enum": null, "default": null, "description": "A unique ID of the tool call generated by xAI. After performing tool call's function, user provides this ID with tool call's result in the subsequent request to xAI. xAI can then match the tool call result sent with tool call request." }, { "field": "choices[].message.tool_calls[].index", "type": "integer | null", "required": false, "enum": null, "default": null, "description": "Index of the tool call." }, { "field": "choices[].message.tool_calls[].type", "type": "string | null", "required": false, "enum": null, "default": null, "description": "Type of tool call, should be `\"function\"` or `\"web_search_call\"` or `\"x_search_call\"` or `\"code_interpreter_call\"` or `\"mcp_call\"`" }, { "field": "citations", "type": "array | null", "required": false, "enum": null, "default": null, "description": "List of all the external pages used by the model to answer." }, { "field": "created", "type": "integer", "required": true, "enum": null, "default": null, "description": "The chat completion creation time in Unix timestamp." }, { "field": "id", "type": "string", "required": true, "enum": null, "default": null, "description": "A unique ID for the chat response." }, { "field": "model", "type": "string", "required": true, "enum": null, "default": null, "description": "Model ID used to create chat completion." }, { "field": "object", "type": "string", "required": true, "enum": null, "default": null, "description": "The object type, which is always `\"chat.completion\"`." }, { "field": "output_files", "type": "array | null", "required": false, "enum": null, "default": null, "description": "Files generated during the response (e.g., by the code execution tool).\nOnly populated when `code_execution_files_output` is included." }, { "field": "output_files[].file_id", "type": "string", "required": true, "enum": null, "default": null, "description": "The file ID from the Files API. Use this to download the file." }, { "field": "output_files[].name", "type": "string", "required": true, "enum": null, "default": null, "description": "The display name of the file." }, { "field": "service_tier", "type": "ServiceTier", "required": true, "enum": [ "default", "priority" ], "default": null, "description": "The processing tier used for this request." }, { "field": "system_fingerprint", "type": "string | null", "required": false, "enum": null, "default": null, "description": "System fingerprint, used to indicate xAI system configuration changes." }, { "field": "usage", "type": "null | Usage", "required": false, "enum": null, "default": null, "description": null }, { "field": "usage.completion_tokens", "type": "integer", "required": true, "enum": null, "default": null, "description": "Total completion token used." }, { "field": "usage.completion_tokens_details", "type": "CompletionUsageDetail", "required": true, "enum": null, "default": null, "description": "Breakdown of completion token usage of different types." }, { "field": "usage.completion_tokens_details.accepted_prediction_tokens", "type": "integer", "required": true, "enum": null, "default": null, "description": "The number of tokens in the prediction that appeared in the completion." }, { "field": "usage.completion_tokens_details.audio_tokens", "type": "integer", "required": true, "enum": null, "default": null, "description": "Audio input tokens generated by the model." }, { "field": "usage.completion_tokens_details.reasoning_tokens", "type": "integer", "required": true, "enum": null, "default": null, "description": "Tokens generated by the model for reasoning." }, { "field": "usage.completion_tokens_details.rejected_prediction_tokens", "type": "integer", "required": true, "enum": null, "default": null, "description": "The number of tokens in the prediction that did not appear in the completion." }, { "field": "usage.cost_in_usd_ticks", "type": "integer", "required": true, "enum": null, "default": null, "description": "Accurate cost of this request in USD ticks, where \"tick\" is defined as follows:\nTICKS_IN_USD_CENT: i64 = 100_000_000\nwhich means there is 10'000'000'000 ticks in one *dollar*." }, { "field": "usage.num_sources_used", "type": "integer", "required": true, "enum": null, "default": null, "description": "Number of individual live search source used." }, { "field": "usage.prompt_tokens", "type": "integer", "required": true, "enum": null, "default": null, "description": "Total prompt token used." }, { "field": "usage.prompt_tokens_details", "type": "PromptUsageDetail", "required": true, "enum": null, "default": null, "description": "Breakdown of prompt token usage of different types." }, { "field": "usage.prompt_tokens_details.audio_tokens", "type": "integer", "required": true, "enum": null, "default": null, "description": "Audio prompt token used." }, { "field": "usage.prompt_tokens_details.cached_tokens", "type": "integer", "required": true, "enum": null, "default": null, "description": "Token cached by xAI from previous requests and reused for this request." }, { "field": "usage.prompt_tokens_details.image_tokens", "type": "integer", "required": true, "enum": null, "default": null, "description": "Image prompt token used." }, { "field": "usage.prompt_tokens_details.text_tokens", "type": "integer", "required": true, "enum": null, "default": null, "description": "Total text prompt token used (cached + non-cached text tokens)." }, { "field": "usage.total_tokens", "type": "integer", "required": true, "enum": null, "default": null, "description": "Total token used, the sum of prompt token and completion token amount." } ], "status": [ "DOCUMENTED", "LIVE_VERIFIED" ], "source": "https://docs.x.ai/developers/rest-api-reference/inference/chat-completions", "schema_name": "ChatResponse", "live_example": { "id": "c444b604-51ed-913f-83cd-26f986d756ee", "object": "chat.completion", "created": 1789789350, "model": "grok-4.3", "choices": [ { "index": 0, "message": { "role": "assistant", "content": "OK.", "reasoning_content": "The user requested a reply of \"OK.\"", "refusal": null }, "finish_reason": "stop" } ], "usage": { "prompt_tokens": 196, "completion_tokens": 2, "total_tokens": 331, "prompt_tokens_details": { "text_tokens": 196, "audio_tokens": 0, "image_tokens": 0, "cached_tokens": 192 }, "completion_tokens_details": { "reasoning_tokens": 133, "audio_tokens": 0, "accepted_prediction_tokens": 0, "rejected_prediction_tokens": 0 }, "num_sources_used": 0, "cost_in_usd_ticks": 3809000 }, "system_fingerprint": "fp_eb3c003fc66c14ed", "service_tier": "default" }, "_fragment": "generated/fragments/objects/xai-inference-objects.json" }, { "provider": "xai", "object": "ChatCompletion.choices[].message (ChoiceMessage)", "name": "ChatCompletion.choices[].message (ChoiceMessage)", "type_or_object_value": null, "description": "Assistant message. `reasoning_content` present on reasoning models (grok-4.3) — a short summary-like trace, absent on grok-4.20-0309-non-reasoning; `tool_calls[]` = {id:'call--', type:'function', function:{name, arguments}} (no `index` in non-stream).", "fields": [ { "field": "content", "type": "string | null", "required": false, "enum": null, "default": null, "description": "The content of the message." }, { "field": "reasoning_content", "type": "string | null", "required": false, "enum": null, "default": null, "description": "The reasoning trace generated by the model." }, { "field": "refusal", "type": "string | null", "required": false, "enum": null, "default": null, "description": "The reason given by model if the model is unable to generate a response. null if model is able to generate." }, { "field": "role", "type": "string", "required": true, "enum": null, "default": null, "description": "The role that the message belongs to, the response from model is always `\"assistant\"`." }, { "field": "tool_calls", "type": "array | null", "required": false, "enum": null, "default": null, "description": "A list of tool calls asked by model for user to perform." }, { "field": "tool_calls[].function", "type": "Function", "required": true, "enum": null, "default": null, "description": "Function to call for the tool call." }, { "field": "tool_calls[].function.arguments", "type": "string", "required": true, "enum": null, "default": null, "description": null }, { "field": "tool_calls[].function.name", "type": "string", "required": true, "enum": null, "default": null, "description": null }, { "field": "tool_calls[].id", "type": "string", "required": true, "enum": null, "default": null, "description": "A unique ID of the tool call generated by xAI. After performing tool call's function, user provides this ID with tool call's result in the subsequent request to xAI. xAI can then match the tool call result sent with tool call request." }, { "field": "tool_calls[].index", "type": "integer | null", "required": false, "enum": null, "default": null, "description": "Index of the tool call." }, { "field": "tool_calls[].type", "type": "string | null", "required": false, "enum": null, "default": null, "description": "Type of tool call, should be `\"function\"` or `\"web_search_call\"` or `\"x_search_call\"` or `\"code_interpreter_call\"` or `\"mcp_call\"`" } ], "status": [ "DOCUMENTED", "LIVE_VERIFIED" ], "source": "https://docs.x.ai/developers/rest-api-reference/inference/chat-completions", "schema_name": "ChoiceMessage", "_fragment": "generated/fragments/objects/xai-inference-objects.json" }, { "provider": "xai", "object": "ChatCompletionChunk", "name": "ChatCompletionChunk", "type_or_object_value": "object = \"chat.completion.chunk\"", "description": "Streaming chunk. Live: `created` is 0 in every chunk; first chunk delta has role+content (or role+reasoning_content); reasoning_content deltas stream BEFORE content deltas; finish chunk has delta:{} + finish_reason; with stream_options.include_usage a final chunk has choices:[] + usage; then `data: [DONE]`. A whole function tool call arrives in one chunk (delta.tool_calls[] with index).", "fields": [ { "field": "choices", "type": "array", "required": true, "enum": null, "default": null, "description": "A list of response choices from the model. The length corresponds to the `n` in request body (default to 1)." }, { "field": "choices[].delta", "type": "Delta", "required": true, "enum": null, "default": null, "description": "Additional difference (delta) of the result." }, { "field": "choices[].delta.content", "type": "string | null", "required": false, "enum": null, "default": null, "description": null }, { "field": "choices[].delta.images", "type": "array | null", "required": false, "enum": null, "default": null, "description": "Images generated by the model." }, { "field": "choices[].delta.reasoning_content", "type": "string | null", "required": false, "enum": null, "default": null, "description": null }, { "field": "choices[].delta.role", "type": "string | null", "required": false, "enum": null, "default": null, "description": null }, { "field": "choices[].delta.tool_calls", "type": "array | null", "required": false, "enum": null, "default": null, "description": null }, { "field": "choices[].delta.tool_calls[].function", "type": "Function", "required": true, "enum": null, "default": null, "description": "Function to call for the tool call." }, { "field": "choices[].delta.tool_calls[].function.arguments", "type": "string", "required": true, "enum": null, "default": null, "description": null }, { "field": "choices[].delta.tool_calls[].function.name", "type": "string", "required": true, "enum": null, "default": null, "description": null }, { "field": "choices[].delta.tool_calls[].id", "type": "string", "required": true, "enum": null, "default": null, "description": "A unique ID of the tool call generated by xAI. After performing tool call's function, user provides this ID with tool call's result in the subsequent request to xAI. xAI can then match the tool call result sent with tool call request." }, { "field": "choices[].delta.tool_calls[].index", "type": "integer | null", "required": false, "enum": null, "default": null, "description": "Index of the tool call." }, { "field": "choices[].delta.tool_calls[].type", "type": "string | null", "required": false, "enum": null, "default": null, "description": "Type of tool call, should be `\"function\"` or `\"web_search_call\"` or `\"x_search_call\"` or `\"code_interpreter_call\"` or `\"mcp_call\"`" }, { "field": "choices[].finish_reason", "type": "string | null", "required": false, "enum": null, "default": null, "description": "Finish reason. `\"stop\"` means the inference has reached a model-defined or user-supplied stop sequence in `stop`. `\"length\"` means the inference result has reached models' maximum allowed token length or user defined value in `max_tokens`. `\"end_turn\"` or `null` in streaming mode when the chunk is not the last." }, { "field": "choices[].index", "type": "integer", "required": true, "enum": null, "default": null, "description": "Index of the choice." }, { "field": "choices[].logprobs", "type": "null | LogProbs", "required": false, "enum": null, "default": null, "description": null }, { "field": "choices[].logprobs.content", "type": "array | null", "required": false, "enum": null, "default": null, "description": "An array the log probabilities of each output token returned." }, { "field": "choices[].logprobs.content[].bytes", "type": "array | null", "required": false, "enum": null, "default": null, "description": "The ASCII encoding of the output character." }, { "field": "choices[].logprobs.content[].logprob", "type": "number", "required": true, "enum": null, "default": null, "description": "The log probability of returning this token." }, { "field": "choices[].logprobs.content[].token", "type": "string", "required": true, "enum": null, "default": null, "description": "The token." }, { "field": "choices[].logprobs.content[].top_logprobs", "type": "array", "required": true, "enum": null, "default": null, "description": "An array of the most likely tokens to return at this token position." }, { "field": "choices[].logprobs.content[].top_logprobs[].bytes", "type": "array | null", "required": false, "enum": null, "default": null, "description": "The ASCII encoding of the output character." }, { "field": "choices[].logprobs.content[].top_logprobs[].logprob", "type": "number", "required": true, "enum": null, "default": null, "description": "The log probability of returning this token." }, { "field": "choices[].logprobs.content[].top_logprobs[].token", "type": "string", "required": true, "enum": null, "default": null, "description": "The token." }, { "field": "citations", "type": "array | null", "required": false, "enum": null, "default": null, "description": "List of all the external pages used by the model to answer. Only populated for the last chunk." }, { "field": "created", "type": "integer", "required": true, "enum": null, "default": null, "description": "The chat completion creation time in Unix timestamp." }, { "field": "id", "type": "string", "required": true, "enum": null, "default": null, "description": "A unique ID for the chat completion. Each chunk in a streaming response has the same ID." }, { "field": "model", "type": "string", "required": true, "enum": null, "default": null, "description": "The model ID used to create chat completion." }, { "field": "object", "type": "string", "required": true, "enum": null, "default": null, "description": "The object type, which is always `\"chat.completion.chunk\"`." }, { "field": "output_files", "type": "array | null", "required": false, "enum": null, "default": null, "description": "Files generated during the response (e.g., by the code execution tool).\nOnly populated for the final chunk when `code_execution_files_output` is included." }, { "field": "output_files[].file_id", "type": "string", "required": true, "enum": null, "default": null, "description": "The file ID from the Files API. Use this to download the file." }, { "field": "output_files[].name", "type": "string", "required": true, "enum": null, "default": null, "description": "The display name of the file." }, { "field": "service_tier", "type": "ServiceTier", "required": true, "enum": [ "default", "priority" ], "default": null, "description": "The processing tier used for this request." }, { "field": "system_fingerprint", "type": "string | null", "required": false, "enum": null, "default": null, "description": "System fingerprint, used to indicate xAI system configuration changes." }, { "field": "usage", "type": "null | Usage", "required": false, "enum": null, "default": null, "description": null }, { "field": "usage.completion_tokens", "type": "integer", "required": true, "enum": null, "default": null, "description": "Total completion token used." }, { "field": "usage.completion_tokens_details", "type": "CompletionUsageDetail", "required": true, "enum": null, "default": null, "description": "Breakdown of completion token usage of different types." }, { "field": "usage.completion_tokens_details.accepted_prediction_tokens", "type": "integer", "required": true, "enum": null, "default": null, "description": "The number of tokens in the prediction that appeared in the completion." }, { "field": "usage.completion_tokens_details.audio_tokens", "type": "integer", "required": true, "enum": null, "default": null, "description": "Audio input tokens generated by the model." }, { "field": "usage.completion_tokens_details.reasoning_tokens", "type": "integer", "required": true, "enum": null, "default": null, "description": "Tokens generated by the model for reasoning." }, { "field": "usage.completion_tokens_details.rejected_prediction_tokens", "type": "integer", "required": true, "enum": null, "default": null, "description": "The number of tokens in the prediction that did not appear in the completion." }, { "field": "usage.cost_in_usd_ticks", "type": "integer", "required": true, "enum": null, "default": null, "description": "Accurate cost of this request in USD ticks, where \"tick\" is defined as follows:\nTICKS_IN_USD_CENT: i64 = 100_000_000\nwhich means there is 10'000'000'000 ticks in one *dollar*." }, { "field": "usage.num_sources_used", "type": "integer", "required": true, "enum": null, "default": null, "description": "Number of individual live search source used." }, { "field": "usage.prompt_tokens", "type": "integer", "required": true, "enum": null, "default": null, "description": "Total prompt token used." }, { "field": "usage.prompt_tokens_details", "type": "PromptUsageDetail", "required": true, "enum": null, "default": null, "description": "Breakdown of prompt token usage of different types." }, { "field": "usage.prompt_tokens_details.audio_tokens", "type": "integer", "required": true, "enum": null, "default": null, "description": "Audio prompt token used." }, { "field": "usage.prompt_tokens_details.cached_tokens", "type": "integer", "required": true, "enum": null, "default": null, "description": "Token cached by xAI from previous requests and reused for this request." }, { "field": "usage.prompt_tokens_details.image_tokens", "type": "integer", "required": true, "enum": null, "default": null, "description": "Image prompt token used." }, { "field": "usage.prompt_tokens_details.text_tokens", "type": "integer", "required": true, "enum": null, "default": null, "description": "Total text prompt token used (cached + non-cached text tokens)." }, { "field": "usage.total_tokens", "type": "integer", "required": true, "enum": null, "default": null, "description": "Total token used, the sum of prompt token and completion token amount." } ], "status": [ "DOCUMENTED", "LIVE_VERIFIED" ], "source": "https://docs.x.ai/developers/rest-api-reference/inference/chat-completions", "schema_name": "ChatResponseChunk", "live_example": { "raw_sse": null }, "_fragment": "generated/fragments/objects/xai-inference-objects.json" }, { "provider": "xai", "object": "Delta", "name": "Delta", "type_or_object_value": null, "description": "choices[].delta of a chunk: role, content, reasoning_content, tool_calls[], images[] (image generation tool).", "fields": [ { "field": "content", "type": "string | null", "required": false, "enum": null, "default": null, "description": null }, { "field": "images", "type": "array | null", "required": false, "enum": null, "default": null, "description": "Images generated by the model." }, { "field": "reasoning_content", "type": "string | null", "required": false, "enum": null, "default": null, "description": null }, { "field": "role", "type": "string | null", "required": false, "enum": null, "default": null, "description": null }, { "field": "tool_calls", "type": "array | null", "required": false, "enum": null, "default": null, "description": null }, { "field": "tool_calls[].function", "type": "Function", "required": true, "enum": null, "default": null, "description": "Function to call for the tool call." }, { "field": "tool_calls[].function.arguments", "type": "string", "required": true, "enum": null, "default": null, "description": null }, { "field": "tool_calls[].function.name", "type": "string", "required": true, "enum": null, "default": null, "description": null }, { "field": "tool_calls[].id", "type": "string", "required": true, "enum": null, "default": null, "description": "A unique ID of the tool call generated by xAI. After performing tool call's function, user provides this ID with tool call's result in the subsequent request to xAI. xAI can then match the tool call result sent with tool call request." }, { "field": "tool_calls[].index", "type": "integer | null", "required": false, "enum": null, "default": null, "description": "Index of the tool call." }, { "field": "tool_calls[].type", "type": "string | null", "required": false, "enum": null, "default": null, "description": "Type of tool call, should be `\"function\"` or `\"web_search_call\"` or `\"x_search_call\"` or `\"code_interpreter_call\"` or `\"mcp_call\"`" } ], "status": [ "DOCUMENTED", "LIVE_VERIFIED" ], "source": "https://docs.x.ai/developers/rest-api-reference/inference/chat-completions", "schema_name": "Delta", "_fragment": "generated/fragments/objects/xai-inference-objects.json" }, { "provider": "xai", "object": "Usage (chat)", "name": "Usage (chat)", "type_or_object_value": null, "description": "Chat-style usage. prompt_tokens_details.cached_tokens = automatic prefix cache hits (192 on a 196-token minimal prompt — the system-prompt prefix is cached by default); completion_tokens excludes reasoning; total_tokens = prompt + completion + reasoning; num_sources_used (Live Search, always 0 now); cost_in_usd_ticks.", "fields": [ { "field": "completion_tokens", "type": "integer", "required": true, "enum": null, "default": null, "description": "Total completion token used." }, { "field": "completion_tokens_details", "type": "CompletionUsageDetail", "required": true, "enum": null, "default": null, "description": "Breakdown of completion token usage of different types." }, { "field": "completion_tokens_details.accepted_prediction_tokens", "type": "integer", "required": true, "enum": null, "default": null, "description": "The number of tokens in the prediction that appeared in the completion." }, { "field": "completion_tokens_details.audio_tokens", "type": "integer", "required": true, "enum": null, "default": null, "description": "Audio input tokens generated by the model." }, { "field": "completion_tokens_details.reasoning_tokens", "type": "integer", "required": true, "enum": null, "default": null, "description": "Tokens generated by the model for reasoning." }, { "field": "completion_tokens_details.rejected_prediction_tokens", "type": "integer", "required": true, "enum": null, "default": null, "description": "The number of tokens in the prediction that did not appear in the completion." }, { "field": "cost_in_usd_ticks", "type": "integer", "required": true, "enum": null, "default": null, "description": "Accurate cost of this request in USD ticks, where \"tick\" is defined as follows:\nTICKS_IN_USD_CENT: i64 = 100_000_000\nwhich means there is 10'000'000'000 ticks in one *dollar*." }, { "field": "num_sources_used", "type": "integer", "required": true, "enum": null, "default": null, "description": "Number of individual live search source used." }, { "field": "prompt_tokens", "type": "integer", "required": true, "enum": null, "default": null, "description": "Total prompt token used." }, { "field": "prompt_tokens_details", "type": "PromptUsageDetail", "required": true, "enum": null, "default": null, "description": "Breakdown of prompt token usage of different types." }, { "field": "prompt_tokens_details.audio_tokens", "type": "integer", "required": true, "enum": null, "default": null, "description": "Audio prompt token used." }, { "field": "prompt_tokens_details.cached_tokens", "type": "integer", "required": true, "enum": null, "default": null, "description": "Token cached by xAI from previous requests and reused for this request." }, { "field": "prompt_tokens_details.image_tokens", "type": "integer", "required": true, "enum": null, "default": null, "description": "Image prompt token used." }, { "field": "prompt_tokens_details.text_tokens", "type": "integer", "required": true, "enum": null, "default": null, "description": "Total text prompt token used (cached + non-cached text tokens)." }, { "field": "total_tokens", "type": "integer", "required": true, "enum": null, "default": null, "description": "Total token used, the sum of prompt token and completion token amount." } ], "status": [ "DOCUMENTED", "LIVE_VERIFIED" ], "source": "https://docs.x.ai/developers/rest-api-reference/inference/chat-completions", "schema_name": "Usage", "live_example": { "prompt_tokens": 196, "completion_tokens": 2, "total_tokens": 331, "prompt_tokens_details": { "text_tokens": 196, "audio_tokens": 0, "image_tokens": 0, "cached_tokens": 192 }, "completion_tokens_details": { "reasoning_tokens": 133, "audio_tokens": 0, "accepted_prediction_tokens": 0, "rejected_prediction_tokens": 0 }, "num_sources_used": 0, "cost_in_usd_ticks": 3809000 }, "_fragment": "generated/fragments/objects/xai-inference-objects.json" }, { "provider": "xai", "object": "ToolCall (chat)", "name": "ToolCall (chat)", "type_or_object_value": null, "description": "Tool call inside choices[].message.tool_calls / delta.tool_calls.", "fields": [ { "field": "function", "type": "Function", "required": true, "enum": null, "default": null, "description": "Function to call for the tool call." }, { "field": "function.arguments", "type": "string", "required": true, "enum": null, "default": null, "description": null }, { "field": "function.name", "type": "string", "required": true, "enum": null, "default": null, "description": null }, { "field": "id", "type": "string", "required": true, "enum": null, "default": null, "description": "A unique ID of the tool call generated by xAI. After performing tool call's function, user provides this ID with tool call's result in the subsequent request to xAI. xAI can then match the tool call result sent with tool call request." }, { "field": "index", "type": "integer | null", "required": false, "enum": null, "default": null, "description": "Index of the tool call." }, { "field": "type", "type": "string | null", "required": false, "enum": null, "default": null, "description": "Type of tool call, should be `\"function\"` or `\"web_search_call\"` or `\"x_search_call\"` or `\"code_interpreter_call\"` or `\"mcp_call\"`" } ], "status": [ "DOCUMENTED", "LIVE_VERIFIED" ], "source": "https://docs.x.ai/developers/rest-api-reference/inference/chat-completions", "schema_name": "ToolCall", "_fragment": "generated/fragments/objects/xai-inference-objects.json" }, { "provider": "xai", "object": "LogProbs / TokenLogProb / TopLogProb", "name": "LogProbs / TokenLogProb / TopLogProb", "type_or_object_value": null, "description": "Log-prob objects. Live: never populated on grok-4.20+ (choices[].logprobs = null; output_text.logprobs = []).", "fields": [ { "field": "bytes", "type": "array | null", "required": false, "enum": null, "default": null, "description": "The ASCII encoding of the output character." }, { "field": "logprob", "type": "number", "required": true, "enum": null, "default": null, "description": "The log probability of returning this token." }, { "field": "token", "type": "string", "required": true, "enum": null, "default": null, "description": "The token." }, { "field": "top_logprobs", "type": "array", "required": true, "enum": null, "default": null, "description": "An array of the most likely tokens to return at this token position." }, { "field": "top_logprobs[].bytes", "type": "array | null", "required": false, "enum": null, "default": null, "description": "The ASCII encoding of the output character." }, { "field": "top_logprobs[].logprob", "type": "number", "required": true, "enum": null, "default": null, "description": "The log probability of returning this token." }, { "field": "top_logprobs[].token", "type": "string", "required": true, "enum": null, "default": null, "description": "The token." } ], "status": [ "DOCUMENTED" ], "source": "https://docs.x.ai/developers/rest-api-reference/inference/chat-completions", "schema_name": "TokenLogProb", "_fragment": "generated/fragments/objects/xai-inference-objects.json" }, { "provider": "xai", "object": "StartDeferredChatResponse", "name": "StartDeferredChatResponse", "type_or_object_value": null, "description": "Body returned by POST /v1/chat/completions when deferred:true. Poll GET /v1/chat/deferred-completion/{request_id}: 202 empty body while pending, then 200 ChatCompletion.", "fields": [ { "field": "request_id", "type": "string", "required": true, "enum": null, "default": null, "description": "A unique request ID for the chat response." } ], "status": [ "DOCUMENTED", "LIVE_VERIFIED" ], "source": "https://docs.x.ai/developers/rest-api-reference/inference/chat-completions", "schema_name": "StartDeferredChatResponse", "live_example": { "request_id": "3ee7c57a-5322-9829-84ca-45f1d95cda81" }, "_fragment": "generated/fragments/objects/xai-inference-objects.json" }, { "provider": "xai", "object": "Response (ModelResponse)", "name": "Response (ModelResponse)", "type_or_object_value": "object = \"response\"", "description": "POST/GET /v1/responses body. Live-observed extras/quirks: `metadata` = {system_fingerprint} (object, not user metadata); `reasoning` echoes {effort:'low', summary:'detailed'} on grok-4.3 even when unset ({effort:null, summary:null} on the non-reasoning model and inside stream `response.created`); temperature/top_p echo 0.7/0.95 defaults; `service_tier`, `truncation:'disabled'`, `top_logprobs:0`, `max_tool_calls`, `prompt_cache_key`, `safety_identifier`, `error`, `instructions`, `background:false` always present. Output items: reasoning (optional, sometimes omitted), message, function_call, web_search_call, custom_tool_call (x_search sub-tools), code_interpreter_call, file_search_call, mcp_call, image_generation_call, tool_search_call/output, shell_call, compaction (input only).", "fields": [ { "field": "background", "type": "boolean", "required": true, "enum": null, "default": false, "description": "OpenResponses compatibility fields.\nNot used at the moment. Just for OpenResponses compatibility.\nWhether to process the response asynchronously in the background." }, { "field": "completed_at", "type": "integer | null", "required": false, "enum": null, "default": null, "description": "The Unix timestamp (in seconds) for the response completion time. Only set when the response is completed." }, { "field": "created_at", "type": "integer", "required": true, "enum": null, "default": null, "description": "The Unix timestamp (in seconds) for the response creation time." }, { "field": "error", "type": "any", "required": false, "enum": null, "default": null, "description": "An error object returned when the model fails to generate a response." }, { "field": "frequency_penalty", "type": "number", "required": true, "enum": null, "default": null, "description": "(NOT SUPPORTED in Responses API) Positive values penalize new tokens based on their existing frequency in the text so far, decreasing the model's likelihood to repeat the same line verbatim." }, { "field": "id", "type": "string", "required": true, "enum": null, "default": null, "description": "Unique ID of the response." }, { "field": "incomplete_details", "type": "null | IncompleteDetails", "required": false, "enum": null, "default": null, "description": null }, { "field": "incomplete_details.reason", "type": "string", "required": true, "enum": [ "max_output_tokens" ], "default": null, "description": null }, { "field": "incomplete_details.reason", "type": "string", "required": true, "enum": [ "max_prompt_tokens" ], "default": null, "description": null }, { "field": "incomplete_details.reason", "type": "string", "required": true, "enum": [ "max_time_limit" ], "default": null, "description": null }, { "field": "instructions", "type": "string | null", "required": false, "enum": null, "default": null, "description": "A system (or developer) message inserted into the model's context." }, { "field": "max_output_tokens", "type": "integer | null", "required": false, "enum": null, "default": null, "description": "Max number of tokens that can be generated in a response. This includes both output and reasoning tokens." }, { "field": "max_tool_calls", "type": "integer | null", "required": false, "enum": null, "default": null, "description": "The maximum number of tool calls allowed for this response." }, { "field": "metadata", "type": "any", "required": true, "enum": null, "default": null, "description": "Only included for compatibility." }, { "field": "model", "type": "string", "required": true, "enum": null, "default": null, "description": "Model name used to generate the response." }, { "field": "object", "type": "string", "required": true, "enum": null, "default": null, "description": "The object type of this resource. Always set to `response`." }, { "field": "output", "type": "array", "required": true, "enum": null, "default": null, "description": "The response generated by the model." }, { "field": "output[].content", "type": "array", "required": true, "enum": null, "default": null, "description": "Content of the output message.", "variant": "item=An output message from the model" }, { "field": "output[].content[].annotations", "type": "array", "required": false, "enum": null, "default": null, "description": "Citations.", "variant": "type=output_text" }, { "field": "output[].content[].annotations[].end_index", "type": "integer | null", "required": false, "enum": null, "default": null, "description": "The end index of the annotation.", "variant": "type=output_text" }, { "field": "output[].content[].annotations[].start_index", "type": "integer | null", "required": false, "enum": null, "default": null, "description": "The summary of the annotation.", "variant": "type=output_text" }, { "field": "output[].content[].annotations[].title", "type": "string | null", "required": false, "enum": null, "default": null, "description": "The title of the annotation.", "variant": "type=output_text" }, { "field": "output[].content[].annotations[].type", "type": "string", "required": true, "enum": null, "default": null, "description": "The type of the annotation. Only supported type currently is `url_citation`.", "variant": "type=output_text" }, { "field": "output[].content[].annotations[].url", "type": "string", "required": true, "enum": null, "default": null, "description": "The URL of the web resource.", "variant": "type=output_text" }, { "field": "output[].content[].logprobs", "type": "array", "required": false, "enum": null, "default": null, "description": "The log probabilities of each output token returned in the content of message.", "variant": "type=output_text" }, { "field": "output[].content[].logprobs[].bytes", "type": "array | null", "required": false, "enum": null, "default": null, "description": "The ASCII encoding of the output character.", "variant": "type=output_text" }, { "field": "output[].content[].logprobs[].logprob", "type": "number", "required": true, "enum": null, "default": null, "description": "The log probability of returning this token.", "variant": "type=output_text" }, { "field": "output[].content[].logprobs[].token", "type": "string", "required": true, "enum": null, "default": null, "description": "The token.", "variant": "type=output_text" }, { "field": "output[].content[].logprobs[].top_logprobs", "type": "array", "required": true, "enum": null, "default": null, "description": "An array of the most likely tokens to return at this token position.", "variant": "type=output_text" }, { "field": "output[].content[].logprobs[].top_logprobs[].bytes", "type": "array | null", "required": false, "enum": null, "default": null, "description": "The ASCII encoding of the output character.", "variant": "type=output_text" }, { "field": "output[].content[].logprobs[].top_logprobs[].logprob", "type": "number", "required": true, "enum": null, "default": null, "description": "The log probability of returning this token.", "variant": "type=output_text" }, { "field": "output[].content[].logprobs[].top_logprobs[].token", "type": "string", "required": true, "enum": null, "default": null, "description": "The token.", "variant": "type=output_text" }, { "field": "output[].content[].text", "type": "string", "required": true, "enum": null, "default": null, "description": "The text output from the model.", "variant": "type=output_text" }, { "field": "output[].content[].type", "type": "string", "required": true, "enum": [ "output_text" ], "default": null, "description": null, "variant": "type=output_text" }, { "field": "output[].content[].refusal", "type": "string", "required": true, "enum": null, "default": null, "description": "The reason for the refusal.", "variant": "type=refusal" }, { "field": "output[].content[].type", "type": "string", "required": true, "enum": [ "refusal" ], "default": null, "description": null, "variant": "type=refusal" }, { "field": "output[].id", "type": "string", "required": false, "enum": null, "default": null, "description": "The unique ID of the output message.", "variant": "item=An output message from the model" }, { "field": "output[].role", "type": "string", "required": true, "enum": null, "default": null, "description": "The role of the output message, which can be `assistant` or `tool`.", "variant": "item=An output message from the model" }, { "field": "output[].status", "type": "string", "required": false, "enum": null, "default": null, "description": "Status of the item. One of `completed`, `in_progress` or `incomplete`.", "variant": "item=An output message from the model" }, { "field": "output[].type", "type": "string", "required": true, "enum": null, "default": null, "description": "The type of the output message, which is always `message`.", "variant": "item=An output message from the model" }, { "field": "output[].arguments", "type": "string", "required": true, "enum": null, "default": null, "description": "The arguments to pass to the function, as a JSON string.", "variant": "item=A tool call to run a function" }, { "field": "output[].call_id", "type": "string", "required": true, "enum": null, "default": null, "description": "The unique ID of the function tool call generated by the model.", "variant": "item=A tool call to run a function" }, { "field": "output[].id", "type": "string", "required": false, "enum": null, "default": null, "description": "The unique ID of the function tool call.", "variant": "item=A tool call to run a function" }, { "field": "output[].name", "type": "string", "required": true, "enum": null, "default": null, "description": "The name of the function.", "variant": "item=A tool call to run a function" }, { "field": "output[].status", "type": "string", "required": false, "enum": null, "default": null, "description": "Status of the item. One of `completed`, `in_progress` or `incomplete`.", "variant": "item=A tool call to run a function" }, { "field": "output[].type", "type": "string", "required": true, "enum": null, "default": null, "description": "The type of the function tool call, which can be `\"function_call\"` for client-side tool calls,\nand `\"web_search_call\"` or `\"x_search_call\"` or `\"code_interpreter_call\"` or `\"mcp_call\"` for server-side tool calls.", "variant": "item=A tool call to run a function" }, { "field": "output[].content", "type": "array", "required": false, "enum": null, "default": null, "description": "The reasoning text contents.", "variant": "item=The reasoning done by the model" }, { "field": "output[].content[].text", "type": "string", "required": true, "enum": null, "default": null, "description": "Reasoning done by the model.", "variant": "item=The reasoning done by the model" }, { "field": "output[].content[].type", "type": "string", "required": true, "enum": null, "default": null, "description": "The type of the object, which is always `reasoning_text`.", "variant": "item=The reasoning done by the model" }, { "field": "output[].encrypted_content", "type": "string | null", "required": false, "enum": null, "default": null, "description": "The enrypted reasoning. Returned when `reasoning.encrypted_content` is passed in `include`.", "variant": "item=The reasoning done by the model" }, { "field": "output[].id", "type": "string", "required": false, "enum": null, "default": null, "description": "The unique ID of the reasoning content.", "variant": "item=The reasoning done by the model" }, { "field": "output[].status", "type": "string", "required": false, "enum": null, "default": null, "description": "Status of the item. One of `completed`, `in_progress` or `incomplete`.", "variant": "item=The reasoning done by the model" }, { "field": "output[].summary", "type": "array", "required": true, "enum": null, "default": null, "description": "The summarized reasoning text contents.", "variant": "item=The reasoning done by the model" }, { "field": "output[].summary[].text", "type": "string", "required": true, "enum": null, "default": null, "description": "Summary of the reasoning done by the model.", "variant": "item=The reasoning done by the model" }, { "field": "output[].summary[].type", "type": "string", "required": true, "enum": null, "default": null, "description": "The type of the object, which is always `summary_text`.", "variant": "item=The reasoning done by the model" }, { "field": "output[].type", "type": "string", "required": true, "enum": null, "default": null, "description": "The type of the object, which is always `reasoning`.", "variant": "item=The reasoning done by the model" }, { "field": "output[].action", "type": "WebSearchAction", "required": true, "enum": null, "default": null, "description": "An object describing the specific action taken in this web search call.\nIncludes details on how the model used the web (search, open_page, find).", "variant": "item=The output of a web search tool call" }, { "field": "output[].action.query", "type": "string", "required": true, "enum": null, "default": null, "description": "The search query.", "variant": "type=search" }, { "field": "output[].action.sources", "type": "array", "required": false, "enum": null, "default": null, "description": "The sources used in the search.", "variant": "type=search" }, { "field": "output[].action.sources[].type", "type": "string", "required": true, "enum": null, "default": null, "description": "The type of source.", "variant": "type=search" }, { "field": "output[].action.sources[].url", "type": "string", "required": false, "enum": null, "default": null, "description": "The URL of the source.", "variant": "type=search" }, { "field": "output[].action.type", "type": "string", "required": true, "enum": [ "search" ], "default": null, "description": null, "variant": "type=search" }, { "field": "output[].action.type", "type": "string", "required": true, "enum": [ "open_page" ], "default": null, "description": null, "variant": "type=open_page" }, { "field": "output[].action.url", "type": "string", "required": true, "enum": null, "default": null, "description": "The URL of the page to open.", "variant": "type=open_page" }, { "field": "output[].action.pattern", "type": "string", "required": true, "enum": null, "default": null, "description": "The pattern or text to search for within the page.", "variant": "type=find_in_page" }, { "field": "output[].action.type", "type": "string", "required": true, "enum": [ "find_in_page" ], "default": null, "description": null, "variant": "type=find_in_page" }, { "field": "output[].action.url", "type": "string", "required": true, "enum": null, "default": null, "description": "The URL of the page being searched within.", "variant": "type=find_in_page" }, { "field": "output[].id", "type": "string", "required": false, "enum": null, "default": null, "description": "The unique ID of the web search tool call.", "variant": "item=The output of a web search tool call" }, { "field": "output[].status", "type": "string", "required": false, "enum": null, "default": null, "description": "The status of the web search tool call.", "variant": "item=The output of a web search tool call" }, { "field": "output[].type", "type": "string", "required": true, "enum": null, "default": null, "description": "The type of the web search tool call. Always `web_search_call`.", "variant": "item=The output of a web search tool call" }, { "field": "output[].id", "type": "string", "required": false, "enum": null, "default": null, "description": "The unique ID of the file search tool call.", "variant": "item=The output of a web search tool call" }, { "field": "output[].queries", "type": "array", "required": true, "enum": null, "default": null, "description": "The queries used to search for files.", "variant": "item=The output of a web search tool call" }, { "field": "output[].results", "type": "array", "required": true, "enum": null, "default": null, "description": "The results of the file search tool call.", "variant": "item=The output of a web search tool call" }, { "field": "output[].results[].file_id", "type": "string", "required": true, "enum": null, "default": null, "description": "The file ID of the file search result.", "variant": "item=The output of a web search tool call" }, { "field": "output[].results[].filename", "type": "string", "required": true, "enum": null, "default": null, "description": "The filename of the file search result.", "variant": "item=The output of a web search tool call" }, { "field": "output[].results[].score", "type": "number", "required": false, "enum": null, "default": null, "description": "The score of the file search result.\nProto3 omits float fields with value 0.0; default to 0.0 when absent.", "variant": "item=The output of a web search tool call" }, { "field": "output[].results[].text", "type": "string", "required": true, "enum": null, "default": null, "description": "The text of the file search result.", "variant": "item=The output of a web search tool call" }, { "field": "output[].status", "type": "string", "required": false, "enum": null, "default": null, "description": "The status of the file search tool call.", "variant": "item=The output of a web search tool call" }, { "field": "output[].type", "type": "string", "required": true, "enum": null, "default": null, "description": "The type of the file search tool call. Always `file_search_call`.", "variant": "item=The output of a web search tool call" }, { "field": "output[].code", "type": "string", "required": false, "enum": null, "default": null, "description": "The code of the code interpreter tool call.", "variant": "item=The output of a code interpreter tool call" }, { "field": "output[].id", "type": "string", "required": false, "enum": null, "default": null, "description": "The unique ID of the code interpreter tool call.", "variant": "item=The output of a code interpreter tool call" }, { "field": "output[].outputs", "type": "array", "required": true, "enum": null, "default": null, "description": "The outputs of the code interpreter tool call.", "variant": "item=The output of a code interpreter tool call" }, { "field": "output[].outputs[].logs", "type": "string", "required": true, "enum": null, "default": null, "description": "The output of the code interpreter tool call.", "variant": "type=logs" }, { "field": "output[].outputs[].type", "type": "string", "required": true, "enum": [ "logs" ], "default": null, "description": null, "variant": "type=logs" }, { "field": "output[].outputs[].type", "type": "string", "required": true, "enum": [ "image" ], "default": null, "description": null, "variant": "type=image" }, { "field": "output[].outputs[].url", "type": "string", "required": true, "enum": null, "default": null, "description": "The error of the code interpreter tool call.", "variant": "type=image" }, { "field": "output[].status", "type": "string", "required": false, "enum": null, "default": null, "description": "The status of the code interpreter tool call.", "variant": "item=The output of a code interpreter tool call" }, { "field": "output[].type", "type": "string", "required": true, "enum": null, "default": null, "description": "The type of the code interpreter tool call. Always `code_interpreter_call`.", "variant": "item=The output of a code interpreter tool call" }, { "field": "output[].arguments", "type": "string", "required": true, "enum": null, "default": null, "description": "A JSON string of the arguments passed to the tool.", "variant": "item=The output of a MCP tool call" }, { "field": "output[].error", "type": "string", "required": false, "enum": null, "default": null, "description": "The error message of the MCP tool call.", "variant": "item=The output of a MCP tool call" }, { "field": "output[].id", "type": "string", "required": false, "enum": null, "default": null, "description": "The unique ID of the MCP tool call.", "variant": "item=The output of a MCP tool call" }, { "field": "output[].name", "type": "string", "required": true, "enum": null, "default": null, "description": "The name of the tool that was run.", "variant": "item=The output of a MCP tool call" }, { "field": "output[].output", "type": "string", "required": true, "enum": null, "default": null, "description": "The output of the MCP tool call.", "variant": "item=The output of a MCP tool call" }, { "field": "output[].server_label", "type": "string", "required": true, "enum": null, "default": null, "description": "The label of the MCP server running the tool.", "variant": "item=The output of a MCP tool call" }, { "field": "output[].status", "type": "string", "required": false, "enum": null, "default": null, "description": "The status of the MCP tool call.", "variant": "item=The output of a MCP tool call" }, { "field": "output[].type", "type": "string", "required": true, "enum": null, "default": null, "description": "The type of the MCP tool call. Always `mcp_call`.", "variant": "item=The output of a MCP tool call" }, { "field": "output[].call_id", "type": "string", "required": true, "enum": null, "default": null, "description": "The unique ID of the function tool call generated by the model.", "variant": "item=The output of a custom tool call" }, { "field": "output[].id", "type": "string", "required": true, "enum": null, "default": null, "description": "The status of the custom tool call.", "variant": "item=The output of a custom tool call" }, { "field": "output[].input", "type": "string", "required": false, "enum": null, "default": null, "description": "The unique ID of the custom tool call,", "variant": "item=The output of a custom tool call" }, { "field": "output[].name", "type": "string", "required": true, "enum": null, "default": null, "description": "An identifier used to map this custom tool call to a tool call output.", "variant": "item=The output of a custom tool call" }, { "field": "output[].status", "type": "string", "required": false, "enum": null, "default": null, "description": "Status of the item. One of `completed`, `in_progress` or `incomplete`.", "variant": "item=The output of a custom tool call" }, { "field": "output[].type", "type": "string", "required": true, "enum": null, "default": null, "description": "The input for the custom tool call generated by the model.", "variant": "item=The output of a custom tool call" }, { "field": "output[].action", "type": "ShellCallAction", "required": true, "enum": null, "default": null, "description": "The shell commands and limits that describe how to run the tool call.", "variant": "item=A shell command call emitted by the model for local execution" }, { "field": "output[].action.commands", "type": "array", "required": true, "enum": null, "default": null, "description": "The commands to run.", "variant": "item=A shell command call emitted by the model for local execution" }, { "field": "output[].action.max_output_length", "type": "integer | null", "required": false, "enum": null, "default": null, "description": "Optional maximum number of characters to return from each command.", "variant": "item=A shell command call emitted by the model for local execution" }, { "field": "output[].action.timeout_ms", "type": "integer | null", "required": false, "enum": null, "default": null, "description": "Optional timeout in milliseconds for the commands.", "variant": "item=A shell command call emitted by the model for local execution" }, { "field": "output[].action.type", "type": "string | null", "required": false, "enum": null, "default": null, "description": "The type of the action, which is always `exec`.", "variant": "item=A shell command call emitted by the model for local execution" }, { "field": "output[].call_id", "type": "string", "required": true, "enum": null, "default": null, "description": "The unique ID of the shell tool call generated by the model.", "variant": "item=A shell command call emitted by the model for local execution" }, { "field": "output[].environment", "type": "null | ShellEnvironment", "required": false, "enum": null, "default": null, "description": null, "variant": "item=A shell command call emitted by the model for local execution" }, { "field": "output[].environment.skills", "type": "array", "required": false, "enum": null, "default": null, "description": "An optional list of skills available in the local environment.", "variant": "item=A shell command call emitted by the model for local execution" }, { "field": "output[].environment.skills[].description", "type": "string", "required": true, "enum": null, "default": null, "description": "A description of what the skill does.", "variant": "item=A shell command call emitted by the model for local execution" }, { "field": "output[].environment.skills[].name", "type": "string", "required": true, "enum": null, "default": null, "description": "The name of the skill.", "variant": "item=A shell command call emitted by the model for local execution" }, { "field": "output[].environment.skills[].path", "type": "string", "required": true, "enum": null, "default": null, "description": "The path to the directory containing the skill (with a SKILL.md file).", "variant": "item=A shell command call emitted by the model for local execution" }, { "field": "output[].environment.type", "type": "string", "required": true, "enum": null, "default": null, "description": "The type of the environment. Currently only `local` is supported.", "variant": "item=A shell command call emitted by the model for local execution" }, { "field": "output[].id", "type": "string", "required": false, "enum": null, "default": null, "description": "The unique ID of the shell call item.", "variant": "item=A shell command call emitted by the model for local execution" }, { "field": "output[].status", "type": "string", "required": false, "enum": null, "default": null, "description": "Status of the item. One of `completed`, `in_progress` or `incomplete`.", "variant": "item=A shell command call emitted by the model for local execution" }, { "field": "output[].type", "type": "string", "required": true, "enum": null, "default": null, "description": "The type of the output item, which is always `shell_call`.", "variant": "item=A shell command call emitted by the model for local execution" }, { "field": "output[].id", "type": "string", "required": false, "enum": null, "default": null, "description": "The unique ID of the image generation tool call.", "variant": "item=The output of an image generation tool call" }, { "field": "output[].prompt", "type": "string | null", "required": false, "enum": null, "default": null, "description": "The prompt used to generate the image.", "variant": "item=The output of an image generation tool call" }, { "field": "output[].result", "type": "string | null", "required": false, "enum": null, "default": null, "description": "The generated image encoded in base64 (OpenAI-compatible: bare\nbase64, no data-URL prefix), or `null` while the call is still in\nprogress or has failed. The image format can be determined from the\ndecoded magic bytes (typically JPEG or PNG).", "variant": "item=The output of an image generation tool call" }, { "field": "output[].status", "type": "string", "required": false, "enum": null, "default": null, "description": "The status of the image generation tool call. One of `in_progress`,\n`generating`, `completed` or `failed`.", "variant": "item=The output of an image generation tool call" }, { "field": "output[].type", "type": "string", "required": true, "enum": [ "image_generation_call" ], "default": null, "description": "The type of the image generation tool call. Always `image_generation_call`.", "variant": "item=The output of an image generation tool call" }, { "field": "output[].arguments", "type": "any", "required": false, "enum": null, "default": null, "description": "The arguments of the tool search call: `{\"query\": ..., \"limit\": ...}`.", "variant": "item=A server-side tool search call made by the model" }, { "field": "output[].call_id", "type": "string | null", "required": false, "enum": null, "default": null, "description": "Always `null`; present for OpenAI compatibility.", "variant": "item=A server-side tool search call made by the model" }, { "field": "output[].execution", "type": "string", "required": false, "enum": null, "default": null, "description": "Where the search runs. Always `server`.", "variant": "item=A server-side tool search call made by the model" }, { "field": "output[].id", "type": "string", "required": true, "enum": null, "default": null, "description": "The unique ID of the tool search call item.", "variant": "item=A server-side tool search call made by the model" }, { "field": "output[].status", "type": "string", "required": false, "enum": null, "default": null, "description": "Status of the item. One of `in_progress`, `completed` or\n`incomplete` (a failed search).", "variant": "item=A server-side tool search call made by the model" }, { "field": "output[].type", "type": "string", "required": true, "enum": [ "tool_search_call" ], "default": null, "description": "The type of the item. Always `tool_search_call`.", "variant": "item=A server-side tool search call made by the model" }, { "field": "output[].call_id", "type": "string | null", "required": false, "enum": null, "default": null, "description": "Always `null`; present for OpenAI compatibility.", "variant": "item=The tool definitions loaded by a completed tool search call" }, { "field": "output[].execution", "type": "string", "required": false, "enum": null, "default": null, "description": "Where the search ran. Always `server`.", "variant": "item=The tool definitions loaded by a completed tool search call" }, { "field": "output[].id", "type": "string", "required": true, "enum": null, "default": null, "description": "The unique ID of the tool search output item.", "variant": "item=The tool definitions loaded by a completed tool search call" }, { "field": "output[].status", "type": "string", "required": false, "enum": null, "default": null, "description": "Status of the item. Always `completed`.", "variant": "item=The tool definitions loaded by a completed tool search call" }, { "field": "output[].tools", "type": "array", "required": false, "enum": null, "default": null, "description": "The loaded tool definitions, echoed in the shape they were supplied in.", "variant": "item=The tool definitions loaded by a completed tool search call" }, { "field": "output[].type", "type": "string", "required": true, "enum": [ "tool_search_output" ], "default": null, "description": "The type of the item. Always `tool_search_output`.", "variant": "item=The tool definitions loaded by a completed tool search call" }, { "field": "parallel_tool_calls", "type": "boolean", "required": true, "enum": null, "default": null, "description": "Whether to allow the model to run parallel tool calls." }, { "field": "presence_penalty", "type": "number", "required": true, "enum": null, "default": null, "description": "(NOT SUPPORTED in Responses API) Positive values penalize new tokens based on whether they appear in the text so far, increasing the model's likelihood to talk about new topics." }, { "field": "previous_response_id", "type": "string | null", "required": false, "enum": null, "default": null, "description": "The ID of the previous response from the model." }, { "field": "prompt_cache_key", "type": "string | null", "required": false, "enum": null, "default": null, "description": "The cache key used for the prompt for routing to the correct engine." }, { "field": "reasoning", "type": "null | ReasoningConfiguration", "required": false, "enum": null, "default": null, "description": null }, { "field": "reasoning.effort", "type": "string | null", "required": false, "enum": null, "default": null, "description": "Constrains how hard a reasoning model thinks before responding. Higher efforts use more reasoning tokens for deeper thinking. The supported values and the default depend on the model." }, { "field": "reasoning.generate_summary", "type": "string | null", "required": false, "enum": null, "default": null, "description": "Only included for compatibility." }, { "field": "reasoning.summary", "type": "string | null", "required": false, "enum": null, "default": null, "description": "A summary of the model's reasoning process. Possible values are `auto`, `concise` and `detailed`. Only included for compatibility. The model shall always return `detailed`." }, { "field": "safety_identifier", "type": "string | null", "required": false, "enum": null, "default": null, "description": "A stable identifier used to help detect users of your application that may be violating xAI's usage policies." }, { "field": "service_tier", "type": "ServiceTier", "required": true, "enum": [ "default", "priority" ], "default": "default", "description": null }, { "field": "status", "type": "string", "required": true, "enum": null, "default": null, "description": "Status of the response. One of `completed`, `in_progress` or `incomplete`." }, { "field": "store", "type": "boolean", "required": true, "enum": null, "default": true, "description": "Whether to store the input message(s) and model response for later retrieval." }, { "field": "temperature", "type": "number | null", "required": false, "enum": null, "default": 1, "description": "What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic." }, { "field": "text", "type": "ModelResponseConfiguration", "required": true, "enum": null, "default": null, "description": "Settings for customizing a text response from the model." }, { "field": "text.format", "type": "null | ModelResponseFormat", "required": false, "enum": null, "default": null, "description": null }, { "field": "text.format.type", "type": "string", "required": true, "enum": [ "text" ], "default": null, "description": null, "variant": "type=text" }, { "field": "text.format.type", "type": "string", "required": true, "enum": [ "json_object" ], "default": null, "description": null, "variant": "type=json_object" }, { "field": "text.format.description", "type": "string | null", "required": false, "enum": null, "default": null, "description": "Only included for compatibility.", "variant": "type=json_schema" }, { "field": "text.format.name", "type": "string | null", "required": false, "enum": null, "default": null, "description": "Only included for compatibility.", "variant": "type=json_schema" }, { "field": "text.format.schema", "type": "any", "required": true, "enum": null, "default": null, "description": "A json schema representing the desired response schema.", "variant": "type=json_schema" }, { "field": "text.format.strict", "type": "boolean | null", "required": false, "enum": null, "default": null, "description": "Only included for compatibility.", "variant": "type=json_schema" }, { "field": "text.format.type", "type": "string", "required": true, "enum": [ "json_schema" ], "default": null, "description": null, "variant": "type=json_schema" }, { "field": "tool_choice", "type": "ModelToolChoice", "required": true, "enum": null, "default": null, "description": "Controls which (if any) tool is called by the model. auto means the model can pick between generating a message or calling one or more tools. required means the model must call one or more tools. Specifying a particular tool via `{\"type\": \"function\", \"function\": {\"name\": \"my_function\"}}` forces the model to call that tool. `none` is the default when no tools are present. `auto` is the default if tools are present." }, { "field": "tool_choice.name", "type": "string", "required": true, "enum": null, "default": null, "description": "Name of the function to use." }, { "field": "tool_choice.type", "type": "string", "required": true, "enum": null, "default": null, "description": "Type is always `\"function\"`." }, { "field": "tools", "type": "array", "required": true, "enum": null, "default": null, "description": "A list of tools the model may call in JSON-schema. Currently, only functions and web search are supported as tools. A max of 350 tools are supported." }, { "field": "tools[].defer_loading", "type": "boolean | null", "required": false, "enum": null, "default": null, "description": "When true, the definition is hidden from the model's prompt but stays\ncallable, loaded via a `tool_search` step (`/v1/responses` only).", "variant": "type=function" }, { "field": "tools[].description", "type": "string | null", "required": false, "enum": null, "default": null, "description": "A description of the function to indicate to the model when to call it.", "variant": "type=function" }, { "field": "tools[].name", "type": "string", "required": true, "enum": null, "default": null, "description": "The name of the function. If the model calls the function, this name is used in the\nresponse.", "variant": "type=function" }, { "field": "tools[].parameters", "type": "any", "required": true, "enum": null, "default": null, "description": "A JSON schema describing the function parameters. The model _should_ follow the schema,\nhowever, this is not enforced at the moment.", "variant": "type=function" }, { "field": "tools[].strict", "type": "boolean | null", "required": false, "enum": null, "default": null, "description": "Not supported. Only maintained for compatibility reasons.", "variant": "type=function" }, { "field": "tools[].type", "type": "string", "required": true, "enum": [ "function" ], "default": null, "description": null, "variant": "type=function" }, { "field": "tools[].filters", "type": "null | WebSearchFilters", "required": false, "enum": null, "default": null, "description": null, "variant": "type=web_search" }, { "field": "tools[].filters.allowed_domains", "type": "array | null", "required": false, "enum": null, "default": null, "description": "List of website domains (without protocol specification or subdomains)\nto restrict search results to (e.g., [\"example.com\"]). A maximum of 5 websites can be allowed.\nUse this as a whitelist to limit results to only these specific sites; no other websites will\nbe considered. If no relevant information is found on these websites, the number of results\nreturned might be smaller than `max_search_results` set in `SearchParameters`. Note: This\nparameter cannot be set together with `excluded_domains`.", "variant": "type=web_search" }, { "field": "tools[].filters.excluded_domains", "type": "array | null", "required": false, "enum": null, "default": null, "description": "List of website domains (without protocol specification or subdomains) to exclude from search results (e.g., [\"example.com\"]).\nUse this to prevent results from unwanted sites. A maximum of 5 websites can be excluded.\nThis parameter cannot be set together with `allowed_domains`.", "variant": "type=web_search" }, { "field": "tools[].search_context_size", "type": "string | null", "required": false, "enum": null, "default": null, "description": "High level guidance for the amount of context window space to use for the\nsearch. Available values are `low`, `medium`, or `high`.\nFor OpenAI API compatibility ONLY. Request will be rejected if this field is set.", "variant": "type=web_search" }, { "field": "tools[].user_location", "type": "null | WebSearchUserLocation", "required": false, "enum": null, "default": null, "description": null, "variant": "type=web_search" }, { "field": "tools[].user_location.city", "type": "string | null", "required": false, "enum": null, "default": null, "description": "City of the user's location.", "variant": "type=web_search" }, { "field": "tools[].user_location.country", "type": "string | null", "required": false, "enum": null, "default": null, "description": "Two-letter ISO 3166-1 alpha-2 country code, like US, GB, etc.", "variant": "type=web_search" }, { "field": "tools[].user_location.region", "type": "string | null", "required": false, "enum": null, "default": null, "description": "Region of the user's location.", "variant": "type=web_search" }, { "field": "tools[].user_location.timezone", "type": "string | null", "required": false, "enum": null, "default": null, "description": "Timezone of the user's location, IANA timezone like America/Chicago, Europe/London, etc.", "variant": "type=web_search" }, { "field": "tools[].user_location.type", "type": "string", "required": true, "enum": null, "default": null, "description": "Type is always `\"approximate\"`.", "variant": "type=web_search" }, { "field": "tools[].allowed_domains", "type": "array | null", "required": false, "enum": null, "default": null, "description": "List of website domains to allow in the search results. This parameter act as a whitelist\nwhere only those websites can be selected. A maximum of 5 websites can be selected.\n\nNote: This parameter cannot be set with `excluded_domains`.", "variant": "type=web_search" }, { "field": "tools[].enable_image_search", "type": "boolean | null", "required": false, "enum": null, "default": null, "description": "When true, activates the image search server-side tool, enabling\nthe model to search for images alongside the standard web search.", "variant": "type=web_search" }, { "field": "tools[].enable_image_understanding", "type": "boolean | null", "required": false, "enum": null, "default": null, "description": "Enable image understanding during web search.", "variant": "type=web_search" }, { "field": "tools[].excluded_domains", "type": "array | null", "required": false, "enum": null, "default": null, "description": "List of website domains to exclude from the search results without protocol specification or\nsubdomains. A maximum of 5 websites can be excluded.\n\nNote: This parameter cannot be set with `allowed_domains`", "variant": "type=web_search" }, { "field": "tools[].external_web_access", "type": "boolean | null", "required": false, "enum": null, "default": null, "description": "Control whether the web search tool fetches live content or uses only cached content.\nFor OpenAI API compatibility ONLY. Request will be rejected if this field is set.", "variant": "type=web_search" }, { "field": "tools[].type", "type": "string", "required": true, "enum": [ "web_search" ], "default": null, "description": null, "variant": "type=web_search" }, { "field": "tools[].allowed_x_handles", "type": "array | null", "required": false, "enum": null, "default": null, "description": "List of X Handles of the users from whom to consider the posts.\n\nNote: This parameter cannot be set with `excluded_x_handles`.", "variant": "type=x_search" }, { "field": "tools[].enable_image_understanding", "type": "boolean | null", "required": false, "enum": null, "default": null, "description": "Enable image understanding during X search.", "variant": "type=x_search" }, { "field": "tools[].enable_video_understanding", "type": "boolean | null", "required": false, "enum": null, "default": null, "description": "Enable video understanding during X search.", "variant": "type=x_search" }, { "field": "tools[].excluded_x_handles", "type": "array | null", "required": false, "enum": null, "default": null, "description": "List of X Handles of the users from whom to exclude the posts.\n\nNote: This parameter cannot be set with `allowed_x_handles`.", "variant": "type=x_search" }, { "field": "tools[].from_date", "type": "string | null", "required": false, "enum": null, "default": null, "description": "Date from which to consider the results in ISO-8601 YYYY-MM-DD. See\n.", "variant": "type=x_search" }, { "field": "tools[].to_date", "type": "string | null", "required": false, "enum": null, "default": null, "description": "Date up to which to consider the results in ISO-8601 YYYY-MM-DD. See\n.", "variant": "type=x_search" }, { "field": "tools[].type", "type": "string", "required": true, "enum": [ "x_search" ], "default": null, "description": null, "variant": "type=x_search" }, { "field": "tools[].action", "type": "string | null", "required": false, "enum": null, "default": null, "description": "Which image capabilities to expose to the model. One of `auto`\n(the default; both generation and editing), `generate`\n(text-to-image only), or `edit` (image editing only).", "variant": "type=image_generation" }, { "field": "tools[].type", "type": "string", "required": true, "enum": [ "image_generation" ], "default": null, "description": null, "variant": "type=image_generation" }, { "field": "tools[].filters", "type": "any", "required": false, "enum": null, "default": null, "description": "A filter to apply.\nFor OpenAI API compatibility ONLY. Request will be rejected if this field is set.", "variant": "type=file_search" }, { "field": "tools[].max_num_results", "type": "integer | null", "required": false, "enum": null, "default": null, "description": null, "variant": "type=file_search" }, { "field": "tools[].ranking_options", "type": "any", "required": false, "enum": null, "default": null, "description": "Ranking options for search.\nFor OpenAI API compatibility ONLY. Request will be rejected if this field is set.", "variant": "type=file_search" }, { "field": "tools[].type", "type": "string", "required": true, "enum": [ "file_search" ], "default": null, "description": null, "variant": "type=file_search" }, { "field": "tools[].vector_store_ids", "type": "array", "required": true, "enum": null, "default": null, "description": "List of vector store IDs to search within.", "variant": "type=file_search" }, { "field": "tools[].container", "type": "any", "required": false, "enum": null, "default": null, "description": "The code interpreter container. Can be a container ID or an object that specifies\nuploaded file IDs to make available to your code.\nFor OpenAI API compatibility ONLY. Request will be rejected if this field is set.", "variant": "type=code_interpreter" }, { "field": "tools[].type", "type": "string", "required": true, "enum": [ "code_interpreter" ], "default": null, "description": null, "variant": "type=code_interpreter" }, { "field": "tools[].allowed_tools", "type": "array | null", "required": false, "enum": null, "default": null, "description": null, "variant": "type=mcp" }, { "field": "tools[].authorization", "type": "string | null", "required": false, "enum": null, "default": null, "description": null, "variant": "type=mcp" }, { "field": "tools[].connector_id", "type": "string | null", "required": false, "enum": null, "default": null, "description": null, "variant": "type=mcp" }, { "field": "tools[].defer_loading", "type": "boolean | null", "required": false, "enum": null, "default": null, "description": "When true, this server's tool definitions are hidden from the\nmodel's prompt but stay callable, loaded via a `tool_search` step.", "variant": "type=mcp" }, { "field": "tools[].headers", "type": "object | null", "required": false, "enum": null, "default": null, "description": null, "variant": "type=mcp" }, { "field": "tools[].require_approval", "type": "string | null", "required": false, "enum": null, "default": null, "description": null, "variant": "type=mcp" }, { "field": "tools[].server_description", "type": "string | null", "required": false, "enum": null, "default": null, "description": null, "variant": "type=mcp" }, { "field": "tools[].server_label", "type": "string", "required": true, "enum": null, "default": null, "description": null, "variant": "type=mcp" }, { "field": "tools[].server_url", "type": "string", "required": true, "enum": null, "default": null, "description": null, "variant": "type=mcp" }, { "field": "tools[].type", "type": "string", "required": true, "enum": [ "mcp" ], "default": null, "description": null, "variant": "type=mcp" }, { "field": "tools[].environment", "type": "ShellEnvironment", "required": true, "enum": null, "default": null, "description": "The environment configuration for the shell tool.", "variant": "type=shell" }, { "field": "tools[].environment.skills", "type": "array", "required": false, "enum": null, "default": null, "description": "An optional list of skills available in the local environment.", "variant": "type=shell" }, { "field": "tools[].environment.skills[].description", "type": "string", "required": true, "enum": null, "default": null, "description": "A description of what the skill does.", "variant": "type=shell" }, { "field": "tools[].environment.skills[].name", "type": "string", "required": true, "enum": null, "default": null, "description": "The name of the skill.", "variant": "type=shell" }, { "field": "tools[].environment.skills[].path", "type": "string", "required": true, "enum": null, "default": null, "description": "The path to the directory containing the skill (with a SKILL.md file).", "variant": "type=shell" }, { "field": "tools[].environment.type", "type": "string", "required": true, "enum": null, "default": null, "description": "The type of the environment. Currently only `local` is supported.", "variant": "type=shell" }, { "field": "tools[].type", "type": "string", "required": true, "enum": [ "shell" ], "default": null, "description": null, "variant": "type=shell" }, { "field": "tools[].execution", "type": "string | null", "required": false, "enum": null, "default": null, "description": "Where the search runs. Only `\"server\"` (or unset) is supported.", "variant": "type=tool_search" }, { "field": "tools[].type", "type": "string", "required": true, "enum": [ "tool_search" ], "default": null, "description": null, "variant": "type=tool_search" }, { "field": "top_logprobs", "type": "integer", "required": true, "enum": null, "default": null, "description": "An integer between 0 and 8 specifying the number of most likely tokens to return at each token position." }, { "field": "top_p", "type": "number | null", "required": false, "enum": null, "default": 1, "description": "An alternative to sampling with `temperature`, called nucleus sampling, where the model considers the results of the tokens with `top_p` probability mass. So 0.1 means only the tokens comprising the top 10% probability mass are considered. It is generally recommended to alter this or `temperature` but not both." }, { "field": "truncation", "type": "string", "required": true, "enum": null, "default": "disabled", "description": "The truncation strategy to use for the model response." }, { "field": "usage", "type": "null | ModelUsage", "required": false, "enum": null, "default": null, "description": null }, { "field": "usage.context_details", "type": "null | ContextDetails", "required": false, "enum": null, "default": null, "description": null }, { "field": "usage.context_details.input_tokens", "type": "integer", "required": true, "enum": null, "default": null, "description": "Prompt tokens in the latest context (sourced from\n`SamplingUsage.context_prompt_tokens`)." }, { "field": "usage.context_details.output_tokens", "type": "integer", "required": true, "enum": null, "default": null, "description": "Completion + reasoning tokens in the latest context (sourced from\n`SamplingUsage.context_output_tokens`)." }, { "field": "usage.cost_in_nano_usd", "type": "integer | null", "required": false, "enum": null, "default": null, "description": "Cost in nano US dollars for this request." }, { "field": "usage.cost_in_usd_ticks", "type": "integer | null", "required": false, "enum": null, "default": null, "description": "Accurate cost of this request in USD ticks, where \"tick\" is defined as follows:\nTICKS_IN_USD_CENT: i64 = 100_000_000\nwhich means there is 10'000'000'000 ticks in one *dollar*." }, { "field": "usage.input_tokens", "type": "integer", "required": true, "enum": null, "default": null, "description": "Number of input tokens used." }, { "field": "usage.input_tokens_details", "type": "InputTokensDetails", "required": true, "enum": null, "default": null, "description": "Breakdown of the input tokens." }, { "field": "usage.input_tokens_details.cached_tokens", "type": "integer", "required": true, "enum": null, "default": null, "description": "Token cached by xAI from previous requests and reused for this request." }, { "field": "usage.num_server_side_tools_used", "type": "integer", "required": true, "enum": null, "default": null, "description": "Number of server side tools used." }, { "field": "usage.num_sources_used", "type": "integer", "required": true, "enum": null, "default": null, "description": "Number of sources used (for live search)." }, { "field": "usage.output_tokens", "type": "integer", "required": true, "enum": null, "default": null, "description": "Number of output tokens used." }, { "field": "usage.output_tokens_details", "type": "OutputTokensDetails", "required": true, "enum": null, "default": null, "description": "Breakdown of the output tokens." }, { "field": "usage.output_tokens_details.reasoning_tokens", "type": "integer", "required": true, "enum": null, "default": null, "description": "Tokens generated by the model for reasoning." }, { "field": "usage.server_side_tool_usage_details", "type": "null | ServerSideToolUsageDetails", "required": false, "enum": null, "default": null, "description": null }, { "field": "usage.server_side_tool_usage_details.code_interpreter_calls", "type": "integer", "required": true, "enum": null, "default": null, "description": "Number of code interpreter calls." }, { "field": "usage.server_side_tool_usage_details.document_search_calls", "type": "integer", "required": true, "enum": null, "default": null, "description": "Number of document search calls." }, { "field": "usage.server_side_tool_usage_details.file_search_calls", "type": "integer", "required": true, "enum": null, "default": null, "description": "Number of file search calls." }, { "field": "usage.server_side_tool_usage_details.image_generation_calls", "type": "integer", "required": true, "enum": null, "default": null, "description": "Number of image generation calls." }, { "field": "usage.server_side_tool_usage_details.mcp_calls", "type": "integer", "required": true, "enum": null, "default": null, "description": "Number of MCP calls." }, { "field": "usage.server_side_tool_usage_details.web_search_calls", "type": "integer", "required": true, "enum": null, "default": null, "description": "Number of web search calls." }, { "field": "usage.server_side_tool_usage_details.x_search_calls", "type": "integer", "required": true, "enum": null, "default": null, "description": "Number of X search calls." }, { "field": "usage.total_tokens", "type": "integer", "required": true, "enum": null, "default": null, "description": "Total tokens used." }, { "field": "user", "type": "string | null", "required": false, "enum": null, "default": null, "description": "A unique identifier representing your end-user, which can help xAI to monitor and detect abuse." } ], "status": [ "DOCUMENTED", "LIVE_VERIFIED" ], "source": "https://docs.x.ai/developers/rest-api-reference/inference/responses", "schema_name": "ModelResponse", "live_example": { "created_at": 1789789464, "completed_at": 1789789464, "id": "b778ce56-4832-956e-b930-b7af340820a2", "max_output_tokens": 2000, "model": "grok-4.3", "object": "response", "output": [ { "id": "rs_b778ce56-4832-956e-b930-b7af340820a2", "summary": [ { "text": "The user requested a reply of \"OK.\"", "type": "summary_text" } ], "type": "reasoning", "status": "completed" }, { "content": [ { "type": "output_text", "text": "OK.", "logprobs": [], "annotations": [] } ], "id": "msg_b778ce56-4832-956e-b930-b7af340820a2", "role": "assistant", "type": "message", "status": "completed" } ], "parallel_tool_calls": true, "previous_response_id": null, "reasoning": { "effort": "low", "summary": "detailed" }, "temperature": 0.7, "text": { "format": { "type": "text" } }, "tool_choice": "auto", "tools": [], "top_p": 0.95, "usage": { "input_tokens": 196, "input_tokens_details": { "cached_tokens": 192 }, "output_tokens": 98, "output_tokens_details": { "reasoning_tokens": 96 }, "total_tokens": 294, "num_sources_used": 0, "num_server_side_tools_used": 0, "cost_in_usd_ticks": 2884000, "context_details": { "input_tokens": 196, "output_tokens": 106 } }, "user": null, "incomplete_details": null, "status": "completed", "store": true, "metadata": { "system_fingerprint": "fp_eb3c003fc66c14ed" }, "background": false, "service_tier": "default", "truncation": "disabled", "top_logprobs": 0, "presence_penalty": 0.0, "frequency_penalty": 0.0, "prompt_cache_key": null, "max_tool_calls": null, "safety_identifier": null, "error": null, "instructions": null }, "_fragment": "generated/fragments/objects/xai-inference-objects.json" }, { "provider": "xai", "object": "OutputMessage", "name": "OutputMessage", "type_or_object_value": "type = \"message\"", "description": "Assistant message item: id msg_, role assistant, status completed, content[] of output_text {text, logprobs:[], annotations:[]} or refusal.", "fields": [ { "field": "content", "type": "array", "required": true, "enum": null, "default": null, "description": "Content of the output message." }, { "field": "content[].annotations", "type": "array", "required": false, "enum": null, "default": null, "description": "Citations.", "variant": "type=output_text" }, { "field": "content[].annotations[].end_index", "type": "integer | null", "required": false, "enum": null, "default": null, "description": "The end index of the annotation.", "variant": "type=output_text" }, { "field": "content[].annotations[].start_index", "type": "integer | null", "required": false, "enum": null, "default": null, "description": "The summary of the annotation.", "variant": "type=output_text" }, { "field": "content[].annotations[].title", "type": "string | null", "required": false, "enum": null, "default": null, "description": "The title of the annotation.", "variant": "type=output_text" }, { "field": "content[].annotations[].type", "type": "string", "required": true, "enum": null, "default": null, "description": "The type of the annotation. Only supported type currently is `url_citation`.", "variant": "type=output_text" }, { "field": "content[].annotations[].url", "type": "string", "required": true, "enum": null, "default": null, "description": "The URL of the web resource.", "variant": "type=output_text" }, { "field": "content[].logprobs", "type": "array", "required": false, "enum": null, "default": null, "description": "The log probabilities of each output token returned in the content of message.", "variant": "type=output_text" }, { "field": "content[].logprobs[].bytes", "type": "array | null", "required": false, "enum": null, "default": null, "description": "The ASCII encoding of the output character.", "variant": "type=output_text" }, { "field": "content[].logprobs[].logprob", "type": "number", "required": true, "enum": null, "default": null, "description": "The log probability of returning this token.", "variant": "type=output_text" }, { "field": "content[].logprobs[].token", "type": "string", "required": true, "enum": null, "default": null, "description": "The token.", "variant": "type=output_text" }, { "field": "content[].logprobs[].top_logprobs", "type": "array", "required": true, "enum": null, "default": null, "description": "An array of the most likely tokens to return at this token position.", "variant": "type=output_text" }, { "field": "content[].logprobs[].top_logprobs[].bytes", "type": "array | null", "required": false, "enum": null, "default": null, "description": "The ASCII encoding of the output character.", "variant": "type=output_text" }, { "field": "content[].logprobs[].top_logprobs[].logprob", "type": "number", "required": true, "enum": null, "default": null, "description": "The log probability of returning this token.", "variant": "type=output_text" }, { "field": "content[].logprobs[].top_logprobs[].token", "type": "string", "required": true, "enum": null, "default": null, "description": "The token.", "variant": "type=output_text" }, { "field": "content[].text", "type": "string", "required": true, "enum": null, "default": null, "description": "The text output from the model.", "variant": "type=output_text" }, { "field": "content[].type", "type": "string", "required": true, "enum": [ "output_text" ], "default": null, "description": null, "variant": "type=output_text" }, { "field": "content[].refusal", "type": "string", "required": true, "enum": null, "default": null, "description": "The reason for the refusal.", "variant": "type=refusal" }, { "field": "content[].type", "type": "string", "required": true, "enum": [ "refusal" ], "default": null, "description": null, "variant": "type=refusal" }, { "field": "id", "type": "string", "required": false, "enum": null, "default": null, "description": "The unique ID of the output message." }, { "field": "role", "type": "string", "required": true, "enum": null, "default": null, "description": "The role of the output message, which can be `assistant` or `tool`." }, { "field": "status", "type": "string", "required": false, "enum": null, "default": null, "description": "Status of the item. One of `completed`, `in_progress` or `incomplete`." }, { "field": "type", "type": "string", "required": true, "enum": null, "default": null, "description": "The type of the output message, which is always `message`." } ], "status": [ "DOCUMENTED", "LIVE_VERIFIED" ], "source": "https://docs.x.ai/developers/rest-api-reference/inference/responses", "schema_name": "OutputMessage", "_fragment": "generated/fragments/objects/xai-inference-objects.json" }, { "provider": "xai", "object": "Annotation (url_citation)", "name": "Annotation (url_citation)", "type_or_object_value": "type = \"url_citation\"", "description": "Inline citation annotation on output_text. Docs: start_index/end_index = char offsets of the `[[N]](url)` markdown, title = display number. Live (x_search, web_search): start_index=end_index=0 and title = the URL itself; no [[N]](url) markdown appeared in the short answers.", "fields": [ { "field": "end_index", "type": "integer | null", "required": false, "enum": null, "default": null, "description": "The end index of the annotation." }, { "field": "start_index", "type": "integer | null", "required": false, "enum": null, "default": null, "description": "The summary of the annotation." }, { "field": "title", "type": "string | null", "required": false, "enum": null, "default": null, "description": "The title of the annotation." }, { "field": "type", "type": "string", "required": true, "enum": null, "default": null, "description": "The type of the annotation. Only supported type currently is `url_citation`." }, { "field": "url", "type": "string", "required": true, "enum": null, "default": null, "description": "The URL of the web resource." } ], "status": [ "DOCUMENTED", "LIVE_VERIFIED" ], "source": "https://docs.x.ai/developers/tools/citations", "schema_name": "Annotation", "_fragment": "generated/fragments/objects/xai-inference-objects.json" }, { "provider": "xai", "object": "Reasoning item", "name": "Reasoning item", "type_or_object_value": "type = \"reasoning\"", "description": "Reasoning output item: id rs_, summary[] of summary_text (may be empty), encrypted_content only with include:['reasoning.encrypted_content'] (also present in stream output_item.done). Replayable verbatim in `input`.", "fields": [ { "field": "content", "type": "array", "required": false, "enum": null, "default": null, "description": "The reasoning text contents." }, { "field": "content[].text", "type": "string", "required": true, "enum": null, "default": null, "description": "Reasoning done by the model." }, { "field": "content[].type", "type": "string", "required": true, "enum": null, "default": null, "description": "The type of the object, which is always `reasoning_text`." }, { "field": "encrypted_content", "type": "string | null", "required": false, "enum": null, "default": null, "description": "The enrypted reasoning. Returned when `reasoning.encrypted_content` is passed in `include`." }, { "field": "id", "type": "string", "required": false, "enum": null, "default": null, "description": "The unique ID of the reasoning content." }, { "field": "status", "type": "string", "required": false, "enum": null, "default": null, "description": "Status of the item. One of `completed`, `in_progress` or `incomplete`." }, { "field": "summary", "type": "array", "required": true, "enum": null, "default": null, "description": "The summarized reasoning text contents." }, { "field": "summary[].text", "type": "string", "required": true, "enum": null, "default": null, "description": "Summary of the reasoning done by the model." }, { "field": "summary[].type", "type": "string", "required": true, "enum": null, "default": null, "description": "The type of the object, which is always `summary_text`." }, { "field": "type", "type": "string", "required": true, "enum": null, "default": null, "description": "The type of the object, which is always `reasoning`." } ], "status": [ "DOCUMENTED", "LIVE_VERIFIED" ], "source": "https://docs.x.ai/developers/rest-api-reference/inference/responses", "schema_name": "Reasoning", "live_example": { "created_at": 1789789472, "completed_at": 1789789472, "id": "55cd9277-96ff-94a4-8bf0-eb8be757df36", "max_output_tokens": 2000, "model": "grok-4.3", "object": "response", "output": [ { "id": "rs_55cd9277-96ff-94a4-8bf0-eb8be757df36", "summary": [ { "text": "The user requested a reply of \"OK.\"", "type": "summary_text" } ], "type": "reasoning", "status": "completed", "encrypted_content": "Q6ZU669gB3GA2GWN/2NldWA9…" }, { "content": [ { "type": "output_text", "text": "OK.", "logprobs": [], "annotations": [] } ], "id": "msg_55cd9277-96ff-94a4-8bf0-eb8be757df36", "role": "assistant", "type": "message", "status": "completed" } ], "parallel_tool_calls": true, "previous_response_id": null, "reasoning": { "effort": "low", "summary": "detailed" }, "temperature": 0.7, "text": { "format": { "type": "text" } }, "tool_choice": "auto", "tools": [], "top_p": 0.95, "usage": { "input_tokens": 196, "input_tokens_details": { "cached_tokens": 192 }, "output_tokens": 171, "output_tokens_details": { "reasoning_tokens": 169 }, "total_tokens": 367, "num_sources_used": 0, "num_server_side_tools_used": 0, "cost_in_usd_ticks": 4709000, "context_details": { "input_tokens": 196, "output_tokens": 179 } }, "user": null, "incomplete_details": null, "status": "completed", "store": false, "metadata": { "system_fingerprint": "fp_eb3c003fc66c14ed" }, "background": false, "service_tier": "default", "truncation": "disabled", "top_logprobs": 0, "presence_penalty": 0.0, "frequency_penalty": 0.0, "prompt_cache_key": null, "max_tool_calls": null, "safety_identifier": null, "error": null, "instructions": null }, "_fragment": "generated/fragments/objects/xai-inference-objects.json" }, { "provider": "xai", "object": "FunctionToolCall", "name": "FunctionToolCall", "type_or_object_value": "type = \"function_call\"", "description": "Client-side function call item: id fc__, call_id call--, name, arguments (JSON string), status completed.", "fields": [ { "field": "arguments", "type": "string", "required": true, "enum": null, "default": null, "description": "The arguments to pass to the function, as a JSON string." }, { "field": "call_id", "type": "string", "required": true, "enum": null, "default": null, "description": "The unique ID of the function tool call generated by the model." }, { "field": "id", "type": "string", "required": false, "enum": null, "default": null, "description": "The unique ID of the function tool call." }, { "field": "name", "type": "string", "required": true, "enum": null, "default": null, "description": "The name of the function." }, { "field": "status", "type": "string", "required": false, "enum": null, "default": null, "description": "Status of the item. One of `completed`, `in_progress` or `incomplete`." }, { "field": "type", "type": "string", "required": true, "enum": null, "default": null, "description": "The type of the function tool call, which can be `\"function_call\"` for client-side tool calls,\nand `\"web_search_call\"` or `\"x_search_call\"` or `\"code_interpreter_call\"` or `\"mcp_call\"` for server-side tool calls." } ], "status": [ "DOCUMENTED", "LIVE_VERIFIED" ], "source": "https://docs.x.ai/developers/rest-api-reference/inference/responses", "schema_name": "FunctionToolCall", "live_example": { "arguments": "{\"city\":\"Paris\"}", "call_id": "call-314593e6-4fc6-44ac-9863-835deb25e745-0", "name": "get_weather", "type": "function_call", "id": "fc_b46a942c-1ac2-91fb-a546-1cb5b2bcb36e_0", "status": "completed" }, "_fragment": "generated/fragments/objects/xai-inference-objects.json" }, { "provider": "xai", "object": "FunctionToolCallOutput", "name": "FunctionToolCallOutput", "type_or_object_value": "type = \"function_call_output\"", "description": "Client-supplied tool result item ({call_id, output}) — sent with previous_response_id or after the replayed output items.", "fields": [ { "field": "call_id", "type": "string", "required": true, "enum": null, "default": null, "description": "The unique ID of the function tool call generated by the model." }, { "field": "output", "type": "ModelInputContent", "required": true, "enum": null, "default": null, "description": "The output of the function tool call. Can be a plain string or a list\nof content items (`input_text`, `input_image`, `input_file`)." }, { "field": "output[].text", "type": "string", "required": true, "enum": null, "default": null, "description": "Text input.", "variant": "type=input_text" }, { "field": "output[].type", "type": "string", "required": true, "enum": [ "input_text" ], "default": null, "description": null, "variant": "type=input_text" }, { "field": "output[].text", "type": "string", "required": true, "enum": null, "default": null, "description": null, "variant": "type=output_text" }, { "field": "output[].type", "type": "string", "required": true, "enum": [ "output_text" ], "default": null, "description": null, "variant": "type=output_text" }, { "field": "output[].file_id", "type": "string | null", "required": false, "enum": null, "default": null, "description": "Only included for compatibility.", "variant": "type=input_image" }, { "field": "output[].image_url", "type": "string", "required": true, "enum": null, "default": null, "description": "A public URL of image prompt, only available for vision models.", "variant": "type=input_image" }, { "field": "output[].type", "type": "string", "required": true, "enum": [ "input_image" ], "default": null, "description": null, "variant": "type=input_image" }, { "field": "output[].file_data", "type": "string | null", "required": false, "enum": null, "default": null, "description": "Inline file bytes (base64 encoded).\n\nWhen set, the file content is provided directly in the request and does NOT need\nto be uploaded to the Files API first.\n\nExactly one of `file_id`, `file_data`, or `file_url` should be set.", "variant": "type=input_file" }, { "field": "output[].file_id", "type": "string | null", "required": false, "enum": null, "default": null, "description": "The file ID from the Files API.\n\nSet this to reference a previously-uploaded file.\nExactly one of `file_id`, `file_data`, or `file_url` should be set.", "variant": "type=input_file" }, { "field": "output[].file_url", "type": "string | null", "required": false, "enum": null, "default": null, "description": "Public URL for a file attachment.\n\nWhen set, the file content is fetched from this URL.\nExactly one of `file_id`, `file_data`, or `file_url` should be set.", "variant": "type=input_file" }, { "field": "output[].filename", "type": "string | null", "required": false, "enum": null, "default": null, "description": "Filename for inline uploads.\n\nRequired when `file_data` is set.", "variant": "type=input_file" }, { "field": "output[].mime_type", "type": "string | null", "required": false, "enum": null, "default": null, "description": "Optional MIME type for inline uploads (e.g. \"application/pdf\").", "variant": "type=input_file" }, { "field": "output[].type", "type": "string", "required": true, "enum": [ "input_file" ], "default": null, "description": null, "variant": "type=input_file" }, { "field": "type", "type": "string", "required": true, "enum": null, "default": null, "description": "The type of the function tool call, which is always `function_call_output`." } ], "status": [ "DOCUMENTED", "LIVE_VERIFIED" ], "source": "https://docs.x.ai/developers/rest-api-reference/inference/responses", "schema_name": "FunctionToolCallOutput", "_fragment": "generated/fragments/objects/xai-inference-objects.json" }, { "provider": "xai", "object": "WebSearchCall", "name": "WebSearchCall", "type_or_object_value": "type = \"web_search_call\"", "description": "Server-side web search item. Live: {id:'ws__call-…', status:'completed', action:{type:'open_page', url}}; action variants search {query, sources[] (with include web_search_call.action.sources)}, open_page {url}, find_in_page {url, pattern}.", "fields": [ { "field": "action", "type": "WebSearchAction", "required": true, "enum": null, "default": null, "description": "An object describing the specific action taken in this web search call.\nIncludes details on how the model used the web (search, open_page, find)." }, { "field": "action.query", "type": "string", "required": true, "enum": null, "default": null, "description": "The search query.", "variant": "type=search" }, { "field": "action.sources", "type": "array", "required": false, "enum": null, "default": null, "description": "The sources used in the search.", "variant": "type=search" }, { "field": "action.sources[].type", "type": "string", "required": true, "enum": null, "default": null, "description": "The type of source.", "variant": "type=search" }, { "field": "action.sources[].url", "type": "string", "required": false, "enum": null, "default": null, "description": "The URL of the source.", "variant": "type=search" }, { "field": "action.type", "type": "string", "required": true, "enum": [ "search" ], "default": null, "description": null, "variant": "type=search" }, { "field": "action.type", "type": "string", "required": true, "enum": [ "open_page" ], "default": null, "description": null, "variant": "type=open_page" }, { "field": "action.url", "type": "string", "required": true, "enum": null, "default": null, "description": "The URL of the page to open.", "variant": "type=open_page" }, { "field": "action.pattern", "type": "string", "required": true, "enum": null, "default": null, "description": "The pattern or text to search for within the page.", "variant": "type=find_in_page" }, { "field": "action.type", "type": "string", "required": true, "enum": [ "find_in_page" ], "default": null, "description": null, "variant": "type=find_in_page" }, { "field": "action.url", "type": "string", "required": true, "enum": null, "default": null, "description": "The URL of the page being searched within.", "variant": "type=find_in_page" }, { "field": "id", "type": "string", "required": false, "enum": null, "default": null, "description": "The unique ID of the web search tool call." }, { "field": "status", "type": "string", "required": false, "enum": null, "default": null, "description": "The status of the web search tool call." }, { "field": "type", "type": "string", "required": true, "enum": null, "default": null, "description": "The type of the web search tool call. Always `web_search_call`." } ], "status": [ "DOCUMENTED", "LIVE_VERIFIED" ], "source": "https://docs.x.ai/developers/tools/web-search", "schema_name": "WebSearchCall", "live_example": { "id": "ws_2afc3b15-4234-9349-9aa8-d7f43ef2f07d_call-f9edaef6-83ca-45d8-896a-3d5bab2aeaba-0", "type": "web_search_call", "status": "completed", "action": { "type": "open_page", "url": "https://x.ai/news" } }, "_fragment": "generated/fragments/objects/xai-inference-objects.json" }, { "provider": "xai", "object": "CustomToolCall (x_search sub-tool calls)", "name": "CustomToolCall (x_search sub-tool calls)", "type_or_object_value": "type = \"custom_tool_call\"", "description": "LIVE_DISCOVERED: x_search activity is emitted as `custom_tool_call` items {id:'ctc_…', call_id:'xs_call-…', name: x_keyword_search | x_semantic_search | x_user_search | x_thread_fetch, input: JSON string args, status} — NOT the documented `x_search_call` type. usage.server_side_tool_usage_details.x_search_calls counts them.", "fields": [ { "field": "call_id", "type": "string", "required": true, "enum": null, "default": null, "description": "The unique ID of the function tool call generated by the model." }, { "field": "id", "type": "string", "required": true, "enum": null, "default": null, "description": "The status of the custom tool call." }, { "field": "input", "type": "string", "required": false, "enum": null, "default": null, "description": "The unique ID of the custom tool call," }, { "field": "name", "type": "string", "required": true, "enum": null, "default": null, "description": "An identifier used to map this custom tool call to a tool call output." }, { "field": "status", "type": "string", "required": false, "enum": null, "default": null, "description": "Status of the item. One of `completed`, `in_progress` or `incomplete`." }, { "field": "type", "type": "string", "required": true, "enum": null, "default": null, "description": "The input for the custom tool call generated by the model." } ], "status": [ "DOCUMENTED", "LIVE_DISCOVERED" ], "source": "https://docs.x.ai/developers/tools/x-search", "schema_name": "CustomToolCall", "live_example": { "call_id": "xs_call-a7572496-dec0-42a6-a3ae-014948c80294-0", "input": "{\"query\":\"from:xai\",\"limit\":\"3\",\"mode\":\"Latest\"}", "name": "x_keyword_search", "type": "custom_tool_call", "id": "ctc_8bc02d6c-67ff-951d-a6ed-74ba0d1416f4_call-a7572496-dec0-42a6-a3ae-014948c80294-0", "status": "completed" }, "_fragment": "generated/fragments/objects/xai-inference-objects.json" }, { "provider": "xai", "object": "CodeInterpreterCall", "name": "CodeInterpreterCall", "type_or_object_value": "type = \"code_interpreter_call\"", "description": "Server-side Python execution item {id:'ci_…', code, outputs[], status}. outputs[] only with include:['code_interpreter_call.outputs']; live: [{type:'logs', logs:'{\"stdout\":\"4\\n\",\"stderr\":\"\",\"exit_code\":0,\"command_timed_out\":false}'}] (logs is a JSON string) or {type:'image', url}.", "fields": [ { "field": "code", "type": "string", "required": false, "enum": null, "default": null, "description": "The code of the code interpreter tool call." }, { "field": "id", "type": "string", "required": false, "enum": null, "default": null, "description": "The unique ID of the code interpreter tool call." }, { "field": "outputs", "type": "array", "required": true, "enum": null, "default": null, "description": "The outputs of the code interpreter tool call." }, { "field": "outputs[].logs", "type": "string", "required": true, "enum": null, "default": null, "description": "The output of the code interpreter tool call.", "variant": "type=logs" }, { "field": "outputs[].type", "type": "string", "required": true, "enum": [ "logs" ], "default": null, "description": null, "variant": "type=logs" }, { "field": "outputs[].type", "type": "string", "required": true, "enum": [ "image" ], "default": null, "description": null, "variant": "type=image" }, { "field": "outputs[].url", "type": "string", "required": true, "enum": null, "default": null, "description": "The error of the code interpreter tool call.", "variant": "type=image" }, { "field": "status", "type": "string", "required": false, "enum": null, "default": null, "description": "The status of the code interpreter tool call." }, { "field": "type", "type": "string", "required": true, "enum": null, "default": null, "description": "The type of the code interpreter tool call. Always `code_interpreter_call`." } ], "status": [ "DOCUMENTED", "LIVE_VERIFIED" ], "source": "https://docs.x.ai/developers/tools/code-execution", "schema_name": "CodeInterpreterCall", "live_example": { "id": "ci_f07d1837-c6f3-901c-b001-11ec3ec8c73e_call-5edde310-3df6-4a73-9944-0d13796b487b-0", "type": "code_interpreter_call", "status": "completed", "code": "print(2+2)", "outputs": [ { "type": "logs", "logs": "{\"stdout\":\"4\\n\",\"stderr\":\"\",\"exit_code\":0,\"command_timed_out\":false}" } ] }, "_fragment": "generated/fragments/objects/xai-inference-objects.json" }, { "provider": "xai", "object": "FileSearchCall", "name": "FileSearchCall", "type_or_object_value": "type = \"file_search_call\"", "description": "Collections search item {id:'fs_…', queries[], results[] (with include file_search_call.results; {file_id, filename, score, text}), status}. Live: status 'failed' with results [] against an empty / still-indexing collection.", "fields": [ { "field": "id", "type": "string", "required": false, "enum": null, "default": null, "description": "The unique ID of the file search tool call." }, { "field": "queries", "type": "array", "required": true, "enum": null, "default": null, "description": "The queries used to search for files." }, { "field": "results", "type": "array", "required": true, "enum": null, "default": null, "description": "The results of the file search tool call." }, { "field": "results[].file_id", "type": "string", "required": true, "enum": null, "default": null, "description": "The file ID of the file search result." }, { "field": "results[].filename", "type": "string", "required": true, "enum": null, "default": null, "description": "The filename of the file search result." }, { "field": "results[].score", "type": "number", "required": false, "enum": null, "default": null, "description": "The score of the file search result.\nProto3 omits float fields with value 0.0; default to 0.0 when absent." }, { "field": "results[].text", "type": "string", "required": true, "enum": null, "default": null, "description": "The text of the file search result." }, { "field": "status", "type": "string", "required": false, "enum": null, "default": null, "description": "The status of the file search tool call." }, { "field": "type", "type": "string", "required": true, "enum": null, "default": null, "description": "The type of the file search tool call. Always `file_search_call`." } ], "status": [ "DOCUMENTED", "LIVE_VERIFIED" ], "source": "https://docs.x.ai/developers/tools/collections-search", "schema_name": "FileSearchCall", "_fragment": "generated/fragments/objects/xai-inference-objects.json" }, { "provider": "xai", "object": "McpCall", "name": "McpCall", "type_or_object_value": "type = \"mcp_call\"", "description": "Remote MCP call item {id:'mcp_…', server_label, name, arguments (JSON string), output (JSON string of the MCP result), error:'', status}. Output always returned (no include needed).", "fields": [ { "field": "arguments", "type": "string", "required": true, "enum": null, "default": null, "description": "A JSON string of the arguments passed to the tool." }, { "field": "error", "type": "string", "required": false, "enum": null, "default": null, "description": "The error message of the MCP tool call." }, { "field": "id", "type": "string", "required": false, "enum": null, "default": null, "description": "The unique ID of the MCP tool call." }, { "field": "name", "type": "string", "required": true, "enum": null, "default": null, "description": "The name of the tool that was run." }, { "field": "output", "type": "string", "required": true, "enum": null, "default": null, "description": "The output of the MCP tool call." }, { "field": "server_label", "type": "string", "required": true, "enum": null, "default": null, "description": "The label of the MCP server running the tool." }, { "field": "status", "type": "string", "required": false, "enum": null, "default": null, "description": "The status of the MCP tool call." }, { "field": "type", "type": "string", "required": true, "enum": null, "default": null, "description": "The type of the MCP tool call. Always `mcp_call`." } ], "status": [ "DOCUMENTED", "LIVE_VERIFIED" ], "source": "https://docs.x.ai/developers/tools/remote-mcp", "schema_name": "McpCall", "live_example": { "id": "mcp_9521b861-be2e-95b6-a1ee-1d7a8e1cc82b_call-8793ce37-4470-4ac5-bd4a-5e54c6ca0e7f-0", "type": "mcp_call", "status": "completed", "name": "ask_question", "server_label": "deepwiki", "error": "", "arguments": "{\"repoName\":[\"xai-org/xai-sdk-python\"],\"question\":\"what does the repo do?\"}", "output": "{\"content\":[{\"type\":\"text\",\"text\":\"This repository, `xai-org/xai-sdk-python`, provides a Python SDK for interacting with xAI's language models, primarily focusi…" }, "_fragment": "generated/fragments/objects/xai-inference-objects.json" }, { "provider": "xai", "object": "ImageGenerationCall", "name": "ImageGenerationCall", "type_or_object_value": "type = \"image_generation_call\"", "description": "Image generation tool item (see the images/imagine agent for the tool itself).", "fields": [ { "field": "id", "type": "string", "required": false, "enum": null, "default": null, "description": "The unique ID of the image generation tool call." }, { "field": "prompt", "type": "string | null", "required": false, "enum": null, "default": null, "description": "The prompt used to generate the image." }, { "field": "result", "type": "string | null", "required": false, "enum": null, "default": null, "description": "The generated image encoded in base64 (OpenAI-compatible: bare\nbase64, no data-URL prefix), or `null` while the call is still in\nprogress or has failed. The image format can be determined from the\ndecoded magic bytes (typically JPEG or PNG)." }, { "field": "status", "type": "string", "required": false, "enum": null, "default": null, "description": "The status of the image generation tool call. One of `in_progress`,\n`generating`, `completed` or `failed`." }, { "field": "type", "type": "string", "required": true, "enum": [ "image_generation_call" ], "default": null, "description": "The type of the image generation tool call. Always `image_generation_call`." } ], "status": [ "DOCUMENTED" ], "source": "https://docs.x.ai/developers/tools/image-generation", "schema_name": "ImageGenerationCall", "_fragment": "generated/fragments/objects/xai-inference-objects.json" }, { "provider": "xai", "object": "ToolSearchCall / ToolSearchOutput", "name": "ToolSearchCall / ToolSearchOutput", "type_or_object_value": "type = \"tool_search_call\" | \"tool_search_output\"", "description": "Deferred-loading tool search (alpha; 403 for this key).", "fields": [ { "field": "arguments", "type": "any", "required": false, "enum": null, "default": null, "description": "The arguments of the tool search call: `{\"query\": ..., \"limit\": ...}`." }, { "field": "call_id", "type": "string | null", "required": false, "enum": null, "default": null, "description": "Always `null`; present for OpenAI compatibility." }, { "field": "execution", "type": "string", "required": false, "enum": null, "default": null, "description": "Where the search runs. Always `server`." }, { "field": "id", "type": "string", "required": true, "enum": null, "default": null, "description": "The unique ID of the tool search call item." }, { "field": "status", "type": "string", "required": false, "enum": null, "default": null, "description": "Status of the item. One of `in_progress`, `completed` or\n`incomplete` (a failed search)." }, { "field": "type", "type": "string", "required": true, "enum": [ "tool_search_call" ], "default": null, "description": "The type of the item. Always `tool_search_call`." } ], "status": [ "DOCUMENTED", "ACCOUNT_RESTRICTED" ], "source": "https://docs.x.ai/openapi.json", "schema_name": "ToolSearchCall", "_fragment": "generated/fragments/objects/xai-inference-objects.json" }, { "provider": "xai", "object": "ShellCall / ShellCallOutput", "name": "ShellCall / ShellCallOutput", "type_or_object_value": "type = \"shell_call\" | \"shell_call_output\"", "description": "Local shell tool items (tool type `shell` accepted live with environment {type:'local'}; no call was triggered).", "fields": [ { "field": "action", "type": "ShellCallAction", "required": true, "enum": null, "default": null, "description": "The shell commands and limits that describe how to run the tool call." }, { "field": "action.commands", "type": "array", "required": true, "enum": null, "default": null, "description": "The commands to run." }, { "field": "action.max_output_length", "type": "integer | null", "required": false, "enum": null, "default": null, "description": "Optional maximum number of characters to return from each command." }, { "field": "action.timeout_ms", "type": "integer | null", "required": false, "enum": null, "default": null, "description": "Optional timeout in milliseconds for the commands." }, { "field": "action.type", "type": "string | null", "required": false, "enum": null, "default": null, "description": "The type of the action, which is always `exec`." }, { "field": "call_id", "type": "string", "required": true, "enum": null, "default": null, "description": "The unique ID of the shell tool call generated by the model." }, { "field": "environment", "type": "null | ShellEnvironment", "required": false, "enum": null, "default": null, "description": null }, { "field": "environment.skills", "type": "array", "required": false, "enum": null, "default": null, "description": "An optional list of skills available in the local environment." }, { "field": "environment.skills[].description", "type": "string", "required": true, "enum": null, "default": null, "description": "A description of what the skill does." }, { "field": "environment.skills[].name", "type": "string", "required": true, "enum": null, "default": null, "description": "The name of the skill." }, { "field": "environment.skills[].path", "type": "string", "required": true, "enum": null, "default": null, "description": "The path to the directory containing the skill (with a SKILL.md file)." }, { "field": "environment.type", "type": "string", "required": true, "enum": null, "default": null, "description": "The type of the environment. Currently only `local` is supported." }, { "field": "id", "type": "string", "required": false, "enum": null, "default": null, "description": "The unique ID of the shell call item." }, { "field": "status", "type": "string", "required": false, "enum": null, "default": null, "description": "Status of the item. One of `completed`, `in_progress` or `incomplete`." }, { "field": "type", "type": "string", "required": true, "enum": null, "default": null, "description": "The type of the output item, which is always `shell_call`." } ], "status": [ "DOCUMENTED", "LIVE_VERIFIED" ], "source": "https://docs.x.ai/openapi.json", "schema_name": "ShellCall", "_fragment": "generated/fragments/objects/xai-inference-objects.json" }, { "provider": "xai", "object": "CompactionOutputItem", "name": "CompactionOutputItem", "type_or_object_value": "type = \"compaction\"", "description": "Opaque compacted conversation {type:'compaction', id:'cmp_…', encrypted_content}; returned by /v1/responses/compact and accepted at the head of `input`.", "fields": [ { "field": "encrypted_content", "type": "string", "required": true, "enum": null, "default": null, "description": "The encrypted content of the compacted conversation." }, { "field": "id", "type": "string | null", "required": false, "enum": null, "default": null, "description": "The unique ID of the compaction item (e.g. `cmp_`)." }, { "field": "type", "type": "string", "required": true, "enum": null, "default": null, "description": "The type of the item. Always `\"compaction\"`." } ], "status": [ "DOCUMENTED", "LIVE_VERIFIED" ], "source": "https://docs.x.ai/developers/advanced-api-usage/context-compaction", "schema_name": "CompactionOutputItem", "_fragment": "generated/fragments/objects/xai-inference-objects.json" }, { "provider": "xai", "object": "CompactResponse", "name": "CompactResponse", "type_or_object_value": "object = \"response.compaction\"", "description": "Body of POST /v1/responses/compact. Live: 5 messages → dropped_message_count 3, usage.output_tokens 138, reasoning_tokens 711 (total_tokens 1437 = input 588 + output 138 + reasoning 711).", "fields": [ { "field": "created_at", "type": "integer", "required": true, "enum": null, "default": null, "description": "Unix timestamp (in seconds) when the compacted conversation was created." }, { "field": "id", "type": "string", "required": true, "enum": null, "default": null, "description": "Unique ID for this compaction (e.g. `cmp_`)." }, { "field": "model", "type": "string", "required": true, "enum": null, "default": null, "description": "Model used for the compaction summary." }, { "field": "object", "type": "string", "required": true, "enum": null, "default": null, "description": "Always `\"response.compaction\"`." }, { "field": "output", "type": "array", "required": true, "enum": null, "default": null, "description": "Compacted output containing a single compaction item.\nPass this verbatim as input to the next `/v1/responses` call." }, { "field": "output[].content", "type": "ModelInputContent", "required": true, "enum": null, "default": null, "description": "Text, image or audio input.", "variant": "item=Message input to the model" }, { "field": "output[].content[].text", "type": "string", "required": true, "enum": null, "default": null, "description": "Text input.", "variant": "type=input_text" }, { "field": "output[].content[].type", "type": "string", "required": true, "enum": [ "input_text" ], "default": null, "description": null, "variant": "type=input_text" }, { "field": "output[].content[].text", "type": "string", "required": true, "enum": null, "default": null, "description": null, "variant": "type=output_text" }, { "field": "output[].content[].type", "type": "string", "required": true, "enum": [ "output_text" ], "default": null, "description": null, "variant": "type=output_text" }, { "field": "output[].content[].file_id", "type": "string | null", "required": false, "enum": null, "default": null, "description": "Only included for compatibility.", "variant": "type=input_image" }, { "field": "output[].content[].image_url", "type": "string", "required": true, "enum": null, "default": null, "description": "A public URL of image prompt, only available for vision models.", "variant": "type=input_image" }, { "field": "output[].content[].type", "type": "string", "required": true, "enum": [ "input_image" ], "default": null, "description": null, "variant": "type=input_image" }, { "field": "output[].content[].file_data", "type": "string | null", "required": false, "enum": null, "default": null, "description": "Inline file bytes (base64 encoded).\n\nWhen set, the file content is provided directly in the request and does NOT need\nto be uploaded to the Files API first.\n\nExactly one of `file_id`, `file_data`, or `file_url` should be set.", "variant": "type=input_file" }, { "field": "output[].content[].file_id", "type": "string | null", "required": false, "enum": null, "default": null, "description": "The file ID from the Files API.\n\nSet this to reference a previously-uploaded file.\nExactly one of `file_id`, `file_data`, or `file_url` should be set.", "variant": "type=input_file" }, { "field": "output[].content[].file_url", "type": "string | null", "required": false, "enum": null, "default": null, "description": "Public URL for a file attachment.\n\nWhen set, the file content is fetched from this URL.\nExactly one of `file_id`, `file_data`, or `file_url` should be set.", "variant": "type=input_file" }, { "field": "output[].content[].filename", "type": "string | null", "required": false, "enum": null, "default": null, "description": "Filename for inline uploads.\n\nRequired when `file_data` is set.", "variant": "type=input_file" }, { "field": "output[].content[].mime_type", "type": "string | null", "required": false, "enum": null, "default": null, "description": "Optional MIME type for inline uploads (e.g. \"application/pdf\").", "variant": "type=input_file" }, { "field": "output[].content[].type", "type": "string", "required": true, "enum": [ "input_file" ], "default": null, "description": null, "variant": "type=input_file" }, { "field": "output[].name", "type": "string | null", "required": false, "enum": null, "default": null, "description": "A unique identifier representing your end-user, which can help xAI to monitor and detect abuse. Only supported for `user` messages.", "variant": "item=Message input to the model" }, { "field": "output[].role", "type": "string", "required": true, "enum": null, "default": null, "description": "The role of the message. Possible values are `user`, `assistant`, `system` and `developer`.", "variant": "item=Message input to the model" }, { "field": "output[].type", "type": "string | null", "required": false, "enum": null, "default": null, "description": "The type of the message, which is always `message`.", "variant": "item=Message input to the model" }, { "field": "output[].call_id", "type": "string", "required": true, "enum": null, "default": null, "description": "The unique ID of the function tool call generated by the model.", "variant": "item=The output of a function tool call" }, { "field": "output[].output", "type": "ModelInputContent", "required": true, "enum": null, "default": null, "description": "The output of the function tool call. Can be a plain string or a list\nof content items (`input_text`, `input_image`, `input_file`).", "variant": "item=The output of a function tool call" }, { "field": "output[].output[].text", "type": "string", "required": true, "enum": null, "default": null, "description": "Text input.", "variant": "type=input_text" }, { "field": "output[].output[].type", "type": "string", "required": true, "enum": [ "input_text" ], "default": null, "description": null, "variant": "type=input_text" }, { "field": "output[].output[].text", "type": "string", "required": true, "enum": null, "default": null, "description": null, "variant": "type=output_text" }, { "field": "output[].output[].type", "type": "string", "required": true, "enum": [ "output_text" ], "default": null, "description": null, "variant": "type=output_text" }, { "field": "output[].output[].file_id", "type": "string | null", "required": false, "enum": null, "default": null, "description": "Only included for compatibility.", "variant": "type=input_image" }, { "field": "output[].output[].image_url", "type": "string", "required": true, "enum": null, "default": null, "description": "A public URL of image prompt, only available for vision models.", "variant": "type=input_image" }, { "field": "output[].output[].type", "type": "string", "required": true, "enum": [ "input_image" ], "default": null, "description": null, "variant": "type=input_image" }, { "field": "output[].output[].file_data", "type": "string | null", "required": false, "enum": null, "default": null, "description": "Inline file bytes (base64 encoded).\n\nWhen set, the file content is provided directly in the request and does NOT need\nto be uploaded to the Files API first.\n\nExactly one of `file_id`, `file_data`, or `file_url` should be set.", "variant": "type=input_file" }, { "field": "output[].output[].file_id", "type": "string | null", "required": false, "enum": null, "default": null, "description": "The file ID from the Files API.\n\nSet this to reference a previously-uploaded file.\nExactly one of `file_id`, `file_data`, or `file_url` should be set.", "variant": "type=input_file" }, { "field": "output[].output[].file_url", "type": "string | null", "required": false, "enum": null, "default": null, "description": "Public URL for a file attachment.\n\nWhen set, the file content is fetched from this URL.\nExactly one of `file_id`, `file_data`, or `file_url` should be set.", "variant": "type=input_file" }, { "field": "output[].output[].filename", "type": "string | null", "required": false, "enum": null, "default": null, "description": "Filename for inline uploads.\n\nRequired when `file_data` is set.", "variant": "type=input_file" }, { "field": "output[].output[].mime_type", "type": "string | null", "required": false, "enum": null, "default": null, "description": "Optional MIME type for inline uploads (e.g. \"application/pdf\").", "variant": "type=input_file" }, { "field": "output[].output[].type", "type": "string", "required": true, "enum": [ "input_file" ], "default": null, "description": null, "variant": "type=input_file" }, { "field": "output[].type", "type": "string", "required": true, "enum": null, "default": null, "description": "The type of the function tool call, which is always `function_call_output`.", "variant": "item=The output of a function tool call" }, { "field": "output[].call_id", "type": "string", "required": true, "enum": null, "default": null, "description": "The unique ID of the shell tool call generated by the model.", "variant": "item=The output of a shell tool call, sent by the client after local execut" }, { "field": "output[].max_output_length", "type": "integer | null", "required": false, "enum": null, "default": null, "description": "The maximum length of the shell command output. Generated by the model\nand should be passed back with the raw output.", "variant": "item=The output of a shell tool call, sent by the client after local execut" }, { "field": "output[].output", "type": "array", "required": true, "enum": null, "default": null, "description": "An array of shell call output contents.", "variant": "item=The output of a shell tool call, sent by the client after local execut" }, { "field": "output[].output[].outcome", "type": "ShellCallOutcome", "required": true, "enum": null, "default": null, "description": "The outcome of the command execution.", "variant": "item=The output of a shell tool call, sent by the client after local execut" }, { "field": "output[].output[].outcome.exit_code", "type": "integer", "required": true, "enum": null, "default": null, "description": "The exit code of the command.", "variant": "type=exit" }, { "field": "output[].output[].outcome.type", "type": "string", "required": true, "enum": [ "exit" ], "default": null, "description": null, "variant": "type=exit" }, { "field": "output[].output[].outcome.type", "type": "string", "required": true, "enum": [ "timeout" ], "default": null, "description": null, "variant": "type=timeout" }, { "field": "output[].output[].stderr", "type": "string", "required": false, "enum": null, "default": null, "description": "The standard error output that was captured.", "variant": "item=The output of a shell tool call, sent by the client after local execut" }, { "field": "output[].output[].stdout", "type": "string", "required": false, "enum": null, "default": null, "description": "The standard output that was captured.", "variant": "item=The output of a shell tool call, sent by the client after local execut" }, { "field": "output[].type", "type": "string", "required": true, "enum": null, "default": null, "description": "The type of the output item, which is always `shell_call_output`.", "variant": "item=The output of a shell tool call, sent by the client after local execut" }, { "field": "output[].encrypted_content", "type": "string", "required": true, "enum": null, "default": null, "description": "The encrypted content of the compacted conversation.", "variant": "item=A compaction item from a previous `/v1/responses/compact` call" }, { "field": "output[].id", "type": "string | null", "required": false, "enum": null, "default": null, "description": "The unique ID of the compaction item (e.g. `cmp_`).", "variant": "item=A compaction item from a previous `/v1/responses/compact` call" }, { "field": "output[].type", "type": "string", "required": true, "enum": null, "default": null, "description": "The type of the item. Always `\"compaction\"`.", "variant": "item=A compaction item from a previous `/v1/responses/compact` call" }, { "field": "usage", "type": "null | CompactUsage", "required": false, "enum": null, "default": null, "description": null }, { "field": "usage.dropped_message_count", "type": "integer", "required": true, "enum": null, "default": null, "description": "Number of messages dropped/summarized during compaction." }, { "field": "usage.input_tokens", "type": "integer", "required": true, "enum": null, "default": null, "description": "Number of tokens in the original (pre-compaction) input." }, { "field": "usage.input_tokens_details", "type": "CompactUsageInputTokensDetails", "required": true, "enum": null, "default": null, "description": "Detailed breakdown of input tokens." }, { "field": "usage.input_tokens_details.cached_tokens", "type": "integer", "required": true, "enum": null, "default": null, "description": "Number of input tokens that were served from the prompt cache." }, { "field": "usage.output_tokens", "type": "integer", "required": true, "enum": null, "default": null, "description": "Number of tokens in the compacted output." }, { "field": "usage.output_tokens_details", "type": "CompactUsageOutputTokensDetails", "required": true, "enum": null, "default": null, "description": "Detailed breakdown of output tokens." }, { "field": "usage.output_tokens_details.reasoning_tokens", "type": "integer", "required": true, "enum": null, "default": null, "description": "Number of reasoning tokens generated during compaction." }, { "field": "usage.total_tokens", "type": "integer", "required": true, "enum": null, "default": null, "description": "Total number of tokens used (input + output, including reasoning)." } ], "status": [ "DOCUMENTED", "LIVE_VERIFIED" ], "source": "https://docs.x.ai/developers/rest-api-reference/inference/responses", "schema_name": "CompactResponse", "live_example": { "object": "response.compaction", "id": "cmp_30b4c1a6-2eb1-4ed0-a11a-33296b0898f3", "created_at": 1789789482, "model": "grok-4.3", "output": [ { "type": "compaction", "id": "cmp_30b4c1a6-2eb1-4ed0-a11a-33296b0898f3", "encrypted_content": "ripw1VhFOGcMBHJ1paju3ncB…" } ], "usage": { "input_tokens": 588, "input_tokens_details": { "cached_tokens": 192 }, "output_tokens": 138, "output_tokens_details": { "reasoning_tokens": 711 }, "total_tokens": 1437, "dropped_message_count": 3 } }, "_fragment": "generated/fragments/objects/xai-inference-objects.json" }, { "provider": "xai", "object": "ModelUsage (responses)", "name": "ModelUsage (responses)", "type_or_object_value": null, "description": "Responses usage. Live extras: cost_in_usd_ticks, context_details {input_tokens, output_tokens}; server_side_tool_usage_details only present when a server tool ran; num_sources_used always 0 (Live Search retired); cost_in_nano_usd never observed.", "fields": [ { "field": "context_details", "type": "null | ContextDetails", "required": false, "enum": null, "default": null, "description": null }, { "field": "context_details.input_tokens", "type": "integer", "required": true, "enum": null, "default": null, "description": "Prompt tokens in the latest context (sourced from\n`SamplingUsage.context_prompt_tokens`)." }, { "field": "context_details.output_tokens", "type": "integer", "required": true, "enum": null, "default": null, "description": "Completion + reasoning tokens in the latest context (sourced from\n`SamplingUsage.context_output_tokens`)." }, { "field": "cost_in_nano_usd", "type": "integer | null", "required": false, "enum": null, "default": null, "description": "Cost in nano US dollars for this request." }, { "field": "cost_in_usd_ticks", "type": "integer | null", "required": false, "enum": null, "default": null, "description": "Accurate cost of this request in USD ticks, where \"tick\" is defined as follows:\nTICKS_IN_USD_CENT: i64 = 100_000_000\nwhich means there is 10'000'000'000 ticks in one *dollar*." }, { "field": "input_tokens", "type": "integer", "required": true, "enum": null, "default": null, "description": "Number of input tokens used." }, { "field": "input_tokens_details", "type": "InputTokensDetails", "required": true, "enum": null, "default": null, "description": "Breakdown of the input tokens." }, { "field": "input_tokens_details.cached_tokens", "type": "integer", "required": true, "enum": null, "default": null, "description": "Token cached by xAI from previous requests and reused for this request." }, { "field": "num_server_side_tools_used", "type": "integer", "required": true, "enum": null, "default": null, "description": "Number of server side tools used." }, { "field": "num_sources_used", "type": "integer", "required": true, "enum": null, "default": null, "description": "Number of sources used (for live search)." }, { "field": "output_tokens", "type": "integer", "required": true, "enum": null, "default": null, "description": "Number of output tokens used." }, { "field": "output_tokens_details", "type": "OutputTokensDetails", "required": true, "enum": null, "default": null, "description": "Breakdown of the output tokens." }, { "field": "output_tokens_details.reasoning_tokens", "type": "integer", "required": true, "enum": null, "default": null, "description": "Tokens generated by the model for reasoning." }, { "field": "server_side_tool_usage_details", "type": "null | ServerSideToolUsageDetails", "required": false, "enum": null, "default": null, "description": null }, { "field": "server_side_tool_usage_details.code_interpreter_calls", "type": "integer", "required": true, "enum": null, "default": null, "description": "Number of code interpreter calls." }, { "field": "server_side_tool_usage_details.document_search_calls", "type": "integer", "required": true, "enum": null, "default": null, "description": "Number of document search calls." }, { "field": "server_side_tool_usage_details.file_search_calls", "type": "integer", "required": true, "enum": null, "default": null, "description": "Number of file search calls." }, { "field": "server_side_tool_usage_details.image_generation_calls", "type": "integer", "required": true, "enum": null, "default": null, "description": "Number of image generation calls." }, { "field": "server_side_tool_usage_details.mcp_calls", "type": "integer", "required": true, "enum": null, "default": null, "description": "Number of MCP calls." }, { "field": "server_side_tool_usage_details.web_search_calls", "type": "integer", "required": true, "enum": null, "default": null, "description": "Number of web search calls." }, { "field": "server_side_tool_usage_details.x_search_calls", "type": "integer", "required": true, "enum": null, "default": null, "description": "Number of X search calls." }, { "field": "total_tokens", "type": "integer", "required": true, "enum": null, "default": null, "description": "Total tokens used." } ], "status": [ "DOCUMENTED", "LIVE_VERIFIED" ], "source": "https://docs.x.ai/developers/rest-api-reference/inference/responses", "schema_name": "ModelUsage", "live_example": { "input_tokens": 1940, "input_tokens_details": { "cached_tokens": 192 }, "output_tokens": 384, "output_tokens_details": { "reasoning_tokens": 368 }, "total_tokens": 2324, "num_sources_used": 0, "num_server_side_tools_used": 1, "cost_in_usd_ticks": 81834000, "server_side_tool_usage_details": { "web_search_calls": 0, "x_search_calls": 0, "code_interpreter_calls": 1, "file_search_calls": 0, "mcp_calls": 0, "document_search_calls": 0, "image_generation_calls": 0 }, "context_details": { "input_tokens": 1138, "output_tokens": 66 } }, "_fragment": "generated/fragments/objects/xai-inference-objects.json" }, { "provider": "xai", "object": "ServerSideToolUsageDetails", "name": "ServerSideToolUsageDetails", "type_or_object_value": null, "description": "Billable server-side tool call counts (web_search_calls, x_search_calls, code_interpreter_calls, file_search_calls, mcp_calls, document_search_calls, image_generation_calls).", "fields": [ { "field": "code_interpreter_calls", "type": "integer", "required": true, "enum": null, "default": null, "description": "Number of code interpreter calls." }, { "field": "document_search_calls", "type": "integer", "required": true, "enum": null, "default": null, "description": "Number of document search calls." }, { "field": "file_search_calls", "type": "integer", "required": true, "enum": null, "default": null, "description": "Number of file search calls." }, { "field": "image_generation_calls", "type": "integer", "required": true, "enum": null, "default": null, "description": "Number of image generation calls." }, { "field": "mcp_calls", "type": "integer", "required": true, "enum": null, "default": null, "description": "Number of MCP calls." }, { "field": "web_search_calls", "type": "integer", "required": true, "enum": null, "default": null, "description": "Number of web search calls." }, { "field": "x_search_calls", "type": "integer", "required": true, "enum": null, "default": null, "description": "Number of X search calls." } ], "status": [ "DOCUMENTED", "LIVE_VERIFIED" ], "source": "https://docs.x.ai/developers/rest-api-reference/inference/responses", "schema_name": "ServerSideToolUsageDetails", "_fragment": "generated/fragments/objects/xai-inference-objects.json" }, { "provider": "xai", "object": "IncompleteDetails", "name": "IncompleteDetails", "type_or_object_value": null, "description": "reason: max_output_tokens | max_prompt_tokens | max_time_limit. Live: null even with max_output_tokens=32 (status stayed 'completed').", "fields": [ { "field": "reason", "type": "string", "required": true, "enum": [ "max_output_tokens" ], "default": null, "description": null }, { "field": "reason", "type": "string", "required": true, "enum": [ "max_prompt_tokens" ], "default": null, "description": null }, { "field": "reason", "type": "string", "required": true, "enum": [ "max_time_limit" ], "default": null, "description": null } ], "status": [ "DOCUMENTED" ], "source": "https://docs.x.ai/developers/rest-api-reference/inference/responses", "schema_name": "IncompleteDetails", "_fragment": "generated/fragments/objects/xai-inference-objects.json" }, { "provider": "xai", "object": "DeleteStoredCompletionResponse", "name": "DeleteStoredCompletionResponse", "type_or_object_value": "object = \"response\"", "description": "DELETE /v1/responses/{id} → {id, object:'response', deleted:true}.", "fields": [ { "field": "deleted", "type": "boolean", "required": true, "enum": null, "default": null, "description": "Whether the response was successfully deleted." }, { "field": "id", "type": "string", "required": true, "enum": null, "default": null, "description": "The response_id to be deleted." }, { "field": "object", "type": "string", "required": true, "enum": null, "default": null, "description": "The deleted object type, which is always `response`." } ], "status": [ "DOCUMENTED", "LIVE_VERIFIED" ], "source": "https://docs.x.ai/developers/rest-api-reference/inference/responses", "schema_name": "DeleteStoredCompletionResponse", "live_example": { "id": "b778ce56-4832-956e-b930-b7af340820a2", "object": "response", "deleted": true }, "_fragment": "generated/fragments/objects/xai-inference-objects.json" }, { "provider": "xai", "object": "ListInputItemsResponse", "name": "ListInputItemsResponse", "type_or_object_value": "object = \"list\"", "description": "GET /v1/responses/{id}/input_items. Live: data[] = [{content:'Reply with OK.', role:'user', type:'message', id:'item_0'}], first_id/last_id 'item_0', has_more false.", "fields": [ { "field": "data", "type": "array", "required": true, "enum": null, "default": null, "description": "The list of input items." }, { "field": "data[].id", "type": "string", "required": true, "enum": null, "default": null, "description": "Stable identifier for this item within the response." }, { "field": "first_id", "type": "string | null", "required": false, "enum": null, "default": null, "description": "The ID of the first item in the list." }, { "field": "has_more", "type": "boolean", "required": true, "enum": null, "default": null, "description": "Whether there are more items beyond this page." }, { "field": "last_id", "type": "string | null", "required": false, "enum": null, "default": null, "description": "The ID of the last item in the list." }, { "field": "object", "type": "string", "required": true, "enum": null, "default": null, "description": "The object type, always `list`." } ], "status": [ "DOCUMENTED", "LIVE_VERIFIED" ], "source": "https://docs.x.ai/developers/rest-api-reference/inference/responses", "schema_name": "ListInputItemsResponse", "live_example": { "object": "list", "data": [ { "content": "Reply with OK.", "role": "user", "type": "message", "id": "item_0" } ], "first_id": "item_0", "last_id": "item_0", "has_more": false }, "_fragment": "generated/fragments/objects/xai-inference-objects.json" }, { "provider": "xai", "object": "MessageResponse (Anthropic-compatible)", "name": "MessageResponse (Anthropic-compatible)", "type_or_object_value": "type = \"message\"", "description": "POST /v1/messages body: id, type message, role assistant, content[] of text | thinking {thinking, signature:''} | redacted_thinking | tool_use {id:'call-…', name, input}, model, stop_reason end_turn|max_tokens|stop_sequence|tool_use, usage {input_tokens, cache_creation_input_tokens (always 0), cache_read_input_tokens, output_tokens (INCLUDES reasoning)}.", "fields": [ { "field": "content", "type": "array", "required": true, "enum": null, "default": null, "description": "Response message content." }, { "field": "content[].text", "type": "string", "required": true, "enum": null, "default": null, "description": null, "variant": "type=text" }, { "field": "content[].type", "type": "string", "required": true, "enum": [ "text" ], "default": null, "description": null, "variant": "type=text" }, { "field": "content[].signature", "type": "string", "required": true, "enum": null, "default": null, "description": "Signature of the content", "variant": "type=thinking" }, { "field": "content[].thinking", "type": "string", "required": true, "enum": null, "default": null, "description": "Thinking content", "variant": "type=thinking" }, { "field": "content[].type", "type": "string", "required": true, "enum": [ "thinking" ], "default": null, "description": null, "variant": "type=thinking" }, { "field": "content[].data", "type": "string", "required": true, "enum": null, "default": null, "description": "Signature of the content", "variant": "type=redacted_thinking" }, { "field": "content[].type", "type": "string", "required": true, "enum": [ "redacted_thinking" ], "default": null, "description": null, "variant": "type=redacted_thinking" }, { "field": "content[].id", "type": "string", "required": true, "enum": null, "default": null, "description": "Tool call ID.", "variant": "type=tool_use" }, { "field": "content[].input", "type": "any", "required": true, "enum": null, "default": null, "description": "Input to the tool call follwing the `input_schema`.", "variant": "type=tool_use" }, { "field": "content[].name", "type": "string", "required": true, "enum": null, "default": null, "description": "Name of the tool call to be used.", "variant": "type=tool_use" }, { "field": "content[].type", "type": "string", "required": true, "enum": [ "tool_use" ], "default": null, "description": null, "variant": "type=tool_use" }, { "field": "id", "type": "string", "required": true, "enum": null, "default": null, "description": "Unique object identifier." }, { "field": "model", "type": "string", "required": true, "enum": null, "default": null, "description": "Model name that handled the request." }, { "field": "role", "type": "string", "required": true, "enum": null, "default": null, "description": "Role of the generated message. Always `\"assistant\"`" }, { "field": "stop_reason", "type": "string | null", "required": false, "enum": null, "default": null, "description": "Reason to stop. `\"stop_sequence\"` means the inference has reached a model-defined or user-supplied stop sequence in `stop`. `\"max_tokens\"` means the inference result has reached models' maximum allowed token length or user defined value in `max_tokens`. `\"end_turn\"` or `null` in streaming mode when the chunk is not the last. `\"tool_use\"` means the model has called a tool and is waiting for the tool response." }, { "field": "stop_sequence", "type": "string | null", "required": false, "enum": null, "default": null, "description": "Custom stop sequence used to stop the generation." }, { "field": "type", "type": "string", "required": true, "enum": null, "default": null, "description": "Object type. This is always `\"message\"` for message types." }, { "field": "usage", "type": "MessageUsage", "required": true, "enum": null, "default": null, "description": "Token usage information." }, { "field": "usage.cache_creation_input_tokens", "type": "integer", "required": true, "enum": null, "default": null, "description": "(Unsupported) Number of tokens written to the cache when creating a new entry." }, { "field": "usage.cache_read_input_tokens", "type": "integer", "required": true, "enum": null, "default": null, "description": "Number of tokens retrieved from the cache for this request." }, { "field": "usage.input_tokens", "type": "integer", "required": true, "enum": null, "default": null, "description": "Number of input tokens not served from cache (Anthropic semantics)." }, { "field": "usage.output_tokens", "type": "integer", "required": true, "enum": null, "default": null, "description": "Number of output tokens used" } ], "status": [ "DOCUMENTED", "DEPRECATED", "LIVE_VERIFIED" ], "source": "https://docs.x.ai/developers/rest-api-reference/inference/legacy", "schema_name": "MessageResponse", "live_example": { "id": "dfdeb5c4-92e0-9364-b67b-70713b5c9847", "type": "message", "role": "assistant", "content": [ { "type": "thinking", "signature": "", "thinking": "The user asked about the weather in Paris." }, { "type": "tool_use", "id": "call-d84004a8-356a-466d-8deb-43a9dfa66737-0", "name": "get_weather", "input": { "city": "Paris" } } ], "model": "grok-4.3", "stop_reason": "tool_use", "stop_sequence": null, "usage": { "input_tokens": 160, "cache_creation_input_tokens": 0, "cache_read_input_tokens": 128, "output_tokens": 181 } }, "_fragment": "generated/fragments/objects/xai-inference-objects.json" }, { "provider": "xai", "object": "MessageUsage", "name": "MessageUsage", "type_or_object_value": null, "description": "Anthropic-style usage; input_tokens excludes cached tokens (4 non-cached + 192 cache_read on the minimal prompt).", "fields": [ { "field": "cache_creation_input_tokens", "type": "integer", "required": true, "enum": null, "default": null, "description": "(Unsupported) Number of tokens written to the cache when creating a new entry." }, { "field": "cache_read_input_tokens", "type": "integer", "required": true, "enum": null, "default": null, "description": "Number of tokens retrieved from the cache for this request." }, { "field": "input_tokens", "type": "integer", "required": true, "enum": null, "default": null, "description": "Number of input tokens not served from cache (Anthropic semantics)." }, { "field": "output_tokens", "type": "integer", "required": true, "enum": null, "default": null, "description": "Number of output tokens used" } ], "status": [ "DOCUMENTED", "DEPRECATED", "LIVE_VERIFIED" ], "source": "https://docs.x.ai/developers/rest-api-reference/inference/legacy", "schema_name": "MessageUsage", "_fragment": "generated/fragments/objects/xai-inference-objects.json" }, { "provider": "xai", "object": "CompleteResponse (legacy /v1/complete)", "name": "CompleteResponse (legacy /v1/complete)", "type_or_object_value": "type = \"completion\"", "description": "Documented shape; unreachable live (400 'Raw sampling is not supported for reasoning models' on every listed text model).", "fields": [ { "field": "completion", "type": "string", "required": true, "enum": null, "default": null, "description": "The completion content up to and excluding stop sequences." }, { "field": "id", "type": "string", "required": true, "enum": null, "default": null, "description": "ID of the completion response." }, { "field": "model", "type": "string", "required": true, "enum": null, "default": null, "description": "The model that handled the request." }, { "field": "stop_reason", "type": "string | null", "required": false, "enum": null, "default": null, "description": "The reason to stop completion. `\"stop_sequence\"` means the inference has reached a model-defined or user-supplied stop sequence in `stop`. `\"length\"` means the inference result has reached models' maximum allowed token length or user defined value in `max_tokens`. `\"end_turn\"` or `null` in streaming mode when the chunk is not the last." }, { "field": "type", "type": "string", "required": true, "enum": null, "default": null, "description": "Completion response object type. This is always `\"completion\"`." } ], "status": [ "DOCUMENTED", "LEGACY", "RETIRED" ], "source": "https://docs.x.ai/developers/rest-api-reference/inference/legacy", "schema_name": "CompleteResponse", "_fragment": "generated/fragments/objects/xai-inference-objects.json" }, { "provider": "xai", "object": "SampleResponse (legacy /v1/completions)", "name": "SampleResponse (legacy /v1/completions)", "type_or_object_value": "object = \"text_completion\"", "description": "Documented shape; unreachable live (400 on grok-4.3 and grok-4.20-0309-non-reasoning).", "fields": [ { "field": "choices", "type": "array", "required": true, "enum": null, "default": null, "description": "A list of response choices from the model. The length corresponds to the `n` in request body (default to 1)." }, { "field": "choices[].finish_reason", "type": "string", "required": true, "enum": null, "default": null, "description": "Finish reason. `\"stop\"` means the inference has reached a model-defined or user-supplied stop sequence in `stop`. `\"length\"` means the inference result has reached models' maximum allowed token length or user defined value in `max_tokens`. `\"end_turn\"` or `null` in streaming mode when the chunk is not the last." }, { "field": "choices[].index", "type": "integer", "required": true, "enum": null, "default": null, "description": "Index of the choice." }, { "field": "choices[].text", "type": "string", "required": true, "enum": null, "default": null, "description": "Text response." }, { "field": "created", "type": "integer", "required": true, "enum": null, "default": null, "description": "The chat completion creation time in Unix timestamp." }, { "field": "id", "type": "string", "required": true, "enum": null, "default": null, "description": "ID of the request." }, { "field": "model", "type": "string", "required": true, "enum": null, "default": null, "description": "Model to be used." }, { "field": "object", "type": "string", "required": true, "enum": null, "default": null, "description": "Object type of the response. This is always `\"text_completion\"`." }, { "field": "system_fingerprint", "type": "string | null", "required": false, "enum": null, "default": null, "description": "System fingerprint, used to indicate xAI system configuration changes." }, { "field": "usage", "type": "null | Usage", "required": false, "enum": null, "default": null, "description": null }, { "field": "usage.completion_tokens", "type": "integer", "required": true, "enum": null, "default": null, "description": "Total completion token used." }, { "field": "usage.completion_tokens_details", "type": "CompletionUsageDetail", "required": true, "enum": null, "default": null, "description": "Breakdown of completion token usage of different types." }, { "field": "usage.completion_tokens_details.accepted_prediction_tokens", "type": "integer", "required": true, "enum": null, "default": null, "description": "The number of tokens in the prediction that appeared in the completion." }, { "field": "usage.completion_tokens_details.audio_tokens", "type": "integer", "required": true, "enum": null, "default": null, "description": "Audio input tokens generated by the model." }, { "field": "usage.completion_tokens_details.reasoning_tokens", "type": "integer", "required": true, "enum": null, "default": null, "description": "Tokens generated by the model for reasoning." }, { "field": "usage.completion_tokens_details.rejected_prediction_tokens", "type": "integer", "required": true, "enum": null, "default": null, "description": "The number of tokens in the prediction that did not appear in the completion." }, { "field": "usage.cost_in_usd_ticks", "type": "integer", "required": true, "enum": null, "default": null, "description": "Accurate cost of this request in USD ticks, where \"tick\" is defined as follows:\nTICKS_IN_USD_CENT: i64 = 100_000_000\nwhich means there is 10'000'000'000 ticks in one *dollar*." }, { "field": "usage.num_sources_used", "type": "integer", "required": true, "enum": null, "default": null, "description": "Number of individual live search source used." }, { "field": "usage.prompt_tokens", "type": "integer", "required": true, "enum": null, "default": null, "description": "Total prompt token used." }, { "field": "usage.prompt_tokens_details", "type": "PromptUsageDetail", "required": true, "enum": null, "default": null, "description": "Breakdown of prompt token usage of different types." }, { "field": "usage.prompt_tokens_details.audio_tokens", "type": "integer", "required": true, "enum": null, "default": null, "description": "Audio prompt token used." }, { "field": "usage.prompt_tokens_details.cached_tokens", "type": "integer", "required": true, "enum": null, "default": null, "description": "Token cached by xAI from previous requests and reused for this request." }, { "field": "usage.prompt_tokens_details.image_tokens", "type": "integer", "required": true, "enum": null, "default": null, "description": "Image prompt token used." }, { "field": "usage.prompt_tokens_details.text_tokens", "type": "integer", "required": true, "enum": null, "default": null, "description": "Total text prompt token used (cached + non-cached text tokens)." }, { "field": "usage.total_tokens", "type": "integer", "required": true, "enum": null, "default": null, "description": "Total token used, the sum of prompt token and completion token amount." } ], "status": [ "DOCUMENTED", "LEGACY", "RETIRED" ], "source": "https://docs.x.ai/developers/rest-api-reference/inference/legacy", "schema_name": "SampleResponse", "_fragment": "generated/fragments/objects/xai-inference-objects.json" }, { "provider": "xai", "object": "EmbeddingResponse", "name": "EmbeddingResponse", "type_or_object_value": "object = \"list\"", "description": "Documented shape; no embedding model is exposed to this key (GET /v1/embedding-models → []).", "fields": [ { "field": "data", "type": "array", "required": true, "enum": null, "default": null, "description": "A list of embedding objects." }, { "field": "data[].embedding", "type": "EmbeddingContent", "required": true, "enum": null, "default": null, "description": "Embedding content." }, { "field": "data[].index", "type": "integer", "required": true, "enum": null, "default": null, "description": "Index of the embedding object in the data list." }, { "field": "data[].object", "type": "string", "required": true, "enum": null, "default": null, "description": "The object type, which is always `\"embedding\"`." }, { "field": "model", "type": "string", "required": true, "enum": null, "default": null, "description": "Model ID used to create embedding." }, { "field": "object", "type": "string", "required": true, "enum": null, "default": null, "description": "The object type of `data` field, which is always `\"list\"`." }, { "field": "usage", "type": "null | EmbeddingUsage", "required": false, "enum": null, "default": null, "description": null }, { "field": "usage.prompt_tokens", "type": "integer", "required": true, "enum": null, "default": null, "description": "Prompt token used." }, { "field": "usage.total_tokens", "type": "integer", "required": true, "enum": null, "default": null, "description": "Total token used." } ], "status": [ "DOCUMENTED", "ACCOUNT_RESTRICTED" ], "source": "https://docs.x.ai/developers/rest-api-reference/inference/other", "schema_name": "EmbeddingResponse", "_fragment": "generated/fragments/objects/xai-inference-objects.json" }, { "provider": "xai", "object": "TokenizeResponse", "name": "TokenizeResponse", "type_or_object_value": null, "description": "POST /v1/tokenize-text → token_ids[] {token_id, string_token, token_bytes[]}.", "fields": [ { "field": "token_ids", "type": "array", "required": true, "enum": null, "default": null, "description": "A list of tokens." }, { "field": "token_ids[].string_token", "type": "string", "required": true, "enum": null, "default": null, "description": "The string of the token." }, { "field": "token_ids[].token_bytes", "type": "array", "required": true, "enum": null, "default": null, "description": "The bytes that constituted the token." }, { "field": "token_ids[].token_id", "type": "integer", "required": true, "enum": null, "default": null, "description": "The integer representation of the token for the model." } ], "status": [ "DOCUMENTED", "LIVE_VERIFIED" ], "source": "https://docs.x.ai/developers/rest-api-reference/inference/other", "schema_name": "TokenizeResponse", "live_example": { "token_ids": [ { "token_id": 17286, "string_token": "Hello", "token_bytes": [ 72, 101, 108, 108, 111 ] }, { "token_id": 2314, "string_token": " world", "token_bytes": [ 32, 119, 111, 114, 108, 100 ] }, { "token_id": 161, "string_token": "!", "token_bytes": [ 33 ] } ] }, "_fragment": "generated/fragments/objects/xai-inference-objects.json" }, { "provider": "xai", "object": "File", "name": "File", "type_or_object_value": "object = \"file\"", "description": "Files API metadata. Live: purpose echoed as '' regardless of the uploaded value; expires_at null for permanent files; public_url/public_url_expires_at only when an active public URL exists.", "fields": [ { "field": "bytes", "type": "integer", "required": true, "enum": null, "default": null, "description": "The size of the file, in bytes." }, { "field": "created_at", "type": "integer", "required": true, "enum": null, "default": null, "description": "The Unix timestamp (in seconds) for file creation time." }, { "field": "expires_at", "type": "integer | null", "required": false, "enum": null, "default": null, "description": "The Unix timestamp (in seconds) for file expiry time. null if file does not expire." }, { "field": "filename", "type": "string", "required": true, "enum": null, "default": null, "description": "The name of the file." }, { "field": "id", "type": "string", "required": true, "enum": null, "default": null, "description": "The file identifier, which can be used in other API requests." }, { "field": "object", "type": "string", "required": true, "enum": null, "default": null, "description": "The object type, which is always `file`. Only included for compatability." }, { "field": "public_url", "type": "string | null", "required": false, "enum": null, "default": null, "description": "Public URL for the file. Only present when the file has an active public URL." }, { "field": "public_url_expires_at", "type": "integer | null", "required": false, "enum": null, "default": null, "description": "Unix timestamp (seconds) when the public URL expires. Only present when\nthe public URL has an independent expiry." }, { "field": "purpose", "type": "string", "required": false, "enum": null, "default": null, "description": "The intended purpose of the uploaded file. Only included for OAI compatability." } ], "status": [ "DOCUMENTED", "LIVE_VERIFIED" ], "source": "https://docs.x.ai/developers/rest-api-reference/files/upload", "schema_name": "File", "live_example": { "bytes": 95, "created_at": 1789789835, "expires_at": null, "filename": "atlas-pixel2.png", "id": "file_8377ab50-1677-4099-9e4b-405cb3f04edf", "object": "file", "purpose": "", "public_url": "https://files-cdn.x.ai/e7nuu0ZNSMGJuFIq_MFXmA/file_8377ab50-1677-4099-9e4b-405cb3f04edf.png", "public_url_expires_at": 1789793436 }, "_fragment": "generated/fragments/objects/xai-inference-objects.json" }, { "provider": "xai", "object": "DeleteFileResponse", "name": "DeleteFileResponse", "type_or_object_value": "object = \"file\"", "description": "DELETE /v1/files/{id} → {id, deleted:true, object:'file'}.", "fields": [ { "field": "deleted", "type": "boolean", "required": true, "enum": null, "default": null, "description": "Whether the file was deleted." }, { "field": "id", "type": "string", "required": true, "enum": null, "default": null, "description": "The ID of the file." }, { "field": "object", "type": "string", "required": true, "enum": null, "default": null, "description": "The object type, which is always \"file\". Only included for compatibility." } ], "status": [ "DOCUMENTED", "LIVE_VERIFIED" ], "source": "https://docs.x.ai/developers/rest-api-reference/files/manage", "schema_name": "DeleteFileResponse", "live_example": { "id": "file_e5480432-ab7e-4528-8685-5bd6041365a8", "deleted": true, "object": "file" }, "_fragment": "generated/fragments/objects/xai-inference-objects.json" }, { "provider": "xai", "object": "ListFilesResponse", "name": "ListFilesResponse", "type_or_object_value": null, "description": "GET /v1/files → {data[], pagination_token} (null on the last page).", "fields": [ { "field": "data", "type": "array", "required": true, "enum": null, "default": null, "description": "List of files." }, { "field": "data[].bytes", "type": "integer", "required": true, "enum": null, "default": null, "description": "The size of the file, in bytes." }, { "field": "data[].created_at", "type": "integer", "required": true, "enum": null, "default": null, "description": "The Unix timestamp (in seconds) for file creation time." }, { "field": "data[].expires_at", "type": "integer | null", "required": false, "enum": null, "default": null, "description": "The Unix timestamp (in seconds) for file expiry time. null if file does not expire." }, { "field": "data[].filename", "type": "string", "required": true, "enum": null, "default": null, "description": "The name of the file." }, { "field": "data[].id", "type": "string", "required": true, "enum": null, "default": null, "description": "The file identifier, which can be used in other API requests." }, { "field": "data[].object", "type": "string", "required": true, "enum": null, "default": null, "description": "The object type, which is always `file`. Only included for compatability." }, { "field": "data[].public_url", "type": "string | null", "required": false, "enum": null, "default": null, "description": "Public URL for the file. Only present when the file has an active public URL." }, { "field": "data[].public_url_expires_at", "type": "integer | null", "required": false, "enum": null, "default": null, "description": "Unix timestamp (seconds) when the public URL expires. Only present when\nthe public URL has an independent expiry." }, { "field": "data[].purpose", "type": "string", "required": false, "enum": null, "default": null, "description": "The intended purpose of the uploaded file. Only included for OAI compatability." }, { "field": "pagination_token", "type": "string | null", "required": false, "enum": null, "default": null, "description": "Pagination token to use with next request." } ], "status": [ "DOCUMENTED", "LIVE_VERIFIED" ], "source": "https://docs.x.ai/developers/rest-api-reference/files/manage", "schema_name": "ListFilesResponse", "_fragment": "generated/fragments/objects/xai-inference-objects.json" }, { "provider": "xai", "object": "CreatePublicUrlResponse", "name": "CreatePublicUrlResponse", "type_or_object_value": null, "description": "POST …/public-url → {public_url (https://files-cdn.x.ai//.png), expires_at?}.", "fields": [ { "field": "expires_at", "type": "integer | null", "required": false, "enum": null, "default": null, "description": "Unix timestamp (seconds) when the public URL expires. Present when\nthe public URL has an expiry, either from an explicit `expires_after`\nin the request or inherited from the file's TTL. Absent when the\npublic URL is valid indefinitely." }, { "field": "public_url", "type": "string", "required": true, "enum": null, "default": null, "description": "The full public URL." } ], "status": [ "DOCUMENTED", "LIVE_VERIFIED" ], "source": "https://docs.x.ai/developers/files/public-urls", "schema_name": "CreatePublicUrlResponse", "live_example": { "public_url": "https://files-cdn.x.ai/e7nuu0ZNSMGJuFIq_MFXmA/file_8377ab50-1677-4099-9e4b-405cb3f04edf.png" }, "_fragment": "generated/fragments/objects/xai-inference-objects.json" }, { "provider": "xai", "object": "RevokePublicUrlResponse", "name": "RevokePublicUrlResponse", "type_or_object_value": null, "description": "POST …/public-url/revoke → {id, revoked, public_url?}.", "fields": [ { "field": "id", "type": "string", "required": true, "enum": null, "default": null, "description": "The file ID whose public URL was revoked." }, { "field": "public_url", "type": "string | null", "required": false, "enum": null, "default": null, "description": "The full public URL that was revoked. Only present when `revoked` is `true`." }, { "field": "revoked", "type": "boolean", "required": true, "enum": null, "default": null, "description": "Whether a public URL was actually revoked. `false` if the file had no\nactive public URL (no-op)." } ], "status": [ "DOCUMENTED", "LIVE_VERIFIED" ], "source": "https://docs.x.ai/developers/files/public-urls", "schema_name": "RevokePublicUrlResponse", "live_example": { "id": "file_8377ab50-1677-4099-9e4b-405cb3f04edf", "revoked": true, "public_url": "https://files-cdn.x.ai/e7nuu0ZNSMGJuFIq_MFXmA/file_8377ab50-1677-4099-9e4b-405cb3f04edf.png" }, "_fragment": "generated/fragments/objects/xai-inference-objects.json" }, { "provider": "xai", "object": "OutputFile / FileOutput", "name": "OutputFile / FileOutput", "type_or_object_value": null, "description": "Files generated by code execution (chat `output_files[]` with include code_execution_files_output) / stored generation outputs.", "fields": [ { "field": "file_id", "type": "string", "required": true, "enum": null, "default": null, "description": "The file ID from the Files API. Use this to download the file." }, { "field": "name", "type": "string", "required": true, "enum": null, "default": null, "description": "The display name of the file." } ], "status": [ "DOCUMENTED" ], "source": "https://docs.x.ai/developers/rest-api-reference/inference/chat-completions", "schema_name": "OutputFile", "_fragment": "generated/fragments/objects/xai-inference-objects.json" }, { "provider": "xai", "object": "SearchRequest / SearchMatch (documents search)", "name": "SearchRequest / SearchMatch (documents search)", "type_or_object_value": null, "description": "POST /v1/documents/search → {matches[]: {file_id, chunk_id, chunk_content, score, collection_ids[], fields{}, page_number}}.", "fields": [ { "field": "chunk_content", "type": "string", "required": true, "enum": null, "default": null, "description": "The chunk content." }, { "field": "chunk_id", "type": "string", "required": true, "enum": null, "default": null, "description": "The chunk ID." }, { "field": "collection_ids", "type": "array", "required": true, "enum": null, "default": null, "description": "The collection ID(s)." }, { "field": "fields", "type": "map", "required": true, "enum": null, "default": null, "description": "Metadata fields belonging to the document of this chunk." }, { "field": "file_id", "type": "string", "required": true, "enum": null, "default": null, "description": "The document ID." }, { "field": "page_number", "type": "integer", "required": false, "enum": null, "default": null, "description": "The dominant page number this chunk belongs to (0 for single-page docs)." }, { "field": "score", "type": "number", "required": true, "enum": null, "default": null, "description": "The relevance score." } ], "status": [ "DOCUMENTED" ], "source": "https://docs.x.ai/developers/rest-api-reference/collections/search", "schema_name": "SearchMatch", "_fragment": "generated/fragments/objects/xai-inference-objects.json" }, { "provider": "xai", "object": "Collection", "name": "Collection", "type_or_object_value": null, "description": "Collection metadata (documented on the Management API; live on api.x.ai too). Live extras not in docs: total_file_size, cloned_from_id, lineage_group_id, clone_version, disable_rag_lookup, sharing{}, effective_privilege, is_owned, owner_team_id, enable_wiki_summary_generation, eval_project_id, organization_id, is_estimated; chunk_configuration nests under `config.BytesConfiguration`.", "fields": [ { "field": "collection_id", "type": "string", "required": false, "enum": null, "default": null, "description": "collection_" }, { "field": "collection_name", "type": "string", "required": false, "enum": null, "default": null, "description": "" }, { "field": "created_at", "type": "string", "required": false, "enum": null, "default": null, "description": "RFC 3339" }, { "field": "index_configuration.model_name", "type": "string", "required": false, "enum": null, "default": null, "description": "grok-embedding-small" }, { "field": "chunk_configuration", "type": "object", "required": false, "enum": null, "default": null, "description": "see parameters" }, { "field": "documents_count", "type": "integer", "required": false, "enum": null, "default": null, "description": "" }, { "field": "field_definitions[]", "type": "array", "required": false, "enum": null, "default": null, "description": "{key, required, inject_into_chunk, unique, description}" }, { "field": "collection_description", "type": "string", "required": false, "enum": null, "default": null, "description": "" }, { "field": "collection_type", "type": "string", "required": false, "enum": null, "default": null, "description": "'text' in the docs example (list only)" } ], "status": [ "DOCUMENTED", "LIVE_DISCOVERED", "LIVE_VERIFIED" ], "source": "https://docs.x.ai/developers/rest-api-reference/collections/collection", "schema_name": null, "live_example": { "collection_id": "collection_64a51299-ce5c-492d-becd-ed04896173b9", "collection_name": "atlas-probe", "created_at": "2026-09-19T03:50:37.920958+00:00", "index_configuration": { "model_name": "grok-embedding-small" }, "chunk_configuration": { "strip_whitespace": true, "inject_name_into_chunks": false, "config": { "BytesConfiguration": { "max_chunk_size_bytes": 4000, "chunk_overlap_bytes": 800 } } }, "documents_count": 0, "field_definitions": [], "collection_description": "atlas probe", "total_file_size": 0, "cloned_from_id": null, "lineage_group_id": null, "clone_version": null, "disable_rag_lookup": false, "sharing": { "shared_team_ids": [], "shared_with_org": false, "shared_teams": [], "org_privilege": 0, "shared_users": [] }, "effective_privilege": 3, "is_owned": true, "owner_team_id": "c5cbff47-a8c3-4203-92d5-fe33647a7d93", "enable_wiki_summary_generation": false, "eval_project_id": null, "organization_id": null, "is_estimated": false }, "_fragment": "generated/fragments/objects/xai-inference-objects.json" }, { "provider": "xai", "object": "Document (collection member)", "name": "Document (collection member)", "type_or_object_value": null, "description": "GET /v1/collections/{id}/documents[/{file_id}] item: {file_metadata{file_id, name, size_bytes, content_type, created_at, expires_at, hash, upload_status, upload_error_message, processing_status, file_path, public_url…}, fields{}, status, error_message, last_indexed_at, chunk_count, chunks_processed_count}. Docs: status is a string enum DOCUMENT_STATUS_UNKNOWN|PROCESSING|PROCESSED|FAILED; live: integer 1 while processing.", "fields": [], "status": [ "DOCUMENTED", "LIVE_DISCOVERED", "LIVE_VERIFIED" ], "source": "https://docs.x.ai/developers/rest-api-reference/collections/collection", "schema_name": null, "live_example": { "file_metadata": { "file_id": "file_d41110c9-e9eb-4a82-b028-81970c108234", "name": "atlas-coll.txt", "size_bytes": 208, "content_type": "text/plain", "created_at": "2026-09-19T03:52:50.490+00:00", "expires_at": null, "hash": "dc672bac69c06743645232db9e5a89b65a47fa27fa826ad8e768fc5222eef880", "upload_status": "Complete", "upload_error_message": null, "processing_status": "Processing", "file_path": "", "public_url": null, "public_url_expires_at": null, "description": null, "collections": [] }, "fields": { "type": "note" }, "status": 1, "error_message": null, "last_indexed_at": null, "chunk_count": null, "chunks_processed_count": 0 }, "_fragment": "generated/fragments/objects/xai-inference-objects.json" }, { "provider": "xai", "object": "Batch", "name": "Batch", "type_or_object_value": null, "description": "Batch container: batch_id (batch_), name, create_time / expire_time (dates 'YYYY-MM-DD'; expiry +30 days live), create_api_key_id, cancel_time, cancel_by_xai_message, state{num_requests, num_pending, num_success, num_error, num_cancelled}. Docs also mention cost_breakdown.total_cost_usd_ticks (SDK) — not present in the REST body live.", "fields": [ { "field": "batch_id", "type": "string", "required": true, "enum": null, "default": null, "description": "" }, { "field": "name", "type": "string", "required": true, "enum": null, "default": null, "description": "" }, { "field": "create_time", "type": "string", "required": true, "enum": null, "default": null, "description": "" }, { "field": "expire_time", "type": "string | null", "required": true, "enum": null, "default": null, "description": "" }, { "field": "create_api_key_id", "type": "string", "required": true, "enum": null, "default": null, "description": "" }, { "field": "cancel_time", "type": "string | null", "required": true, "enum": null, "default": null, "description": "" }, { "field": "cancel_by_xai_message", "type": "string | null", "required": true, "enum": null, "default": null, "description": "" }, { "field": "state.num_requests", "type": "integer", "required": true, "enum": null, "default": null, "description": "" }, { "field": "state.num_pending", "type": "integer", "required": true, "enum": null, "default": null, "description": "" }, { "field": "state.num_success", "type": "integer", "required": true, "enum": null, "default": null, "description": "" }, { "field": "state.num_error", "type": "integer", "required": true, "enum": null, "default": null, "description": "" }, { "field": "state.num_cancelled", "type": "integer", "required": true, "enum": null, "default": null, "description": "" } ], "status": [ "DOCUMENTED", "LIVE_VERIFIED" ], "source": "https://docs.x.ai/developers/rest-api-reference/inference/batches", "schema_name": null, "live_example": { "batch_id": "batch_e9db5280-d3c6-4dcc-b052-44ca69ceebc8", "name": "atlas-probe", "create_time": "2026-09-19", "expire_time": "2026-10-19", "create_api_key_id": "cde030d8-a3a2-44b2-9a27-5d8d0a09bd05", "cancel_time": null, "cancel_by_xai_message": null, "state": { "num_requests": 2, "num_pending": 0, "num_success": 2, "num_error": 0, "num_cancelled": 0 } }, "_fragment": "generated/fragments/objects/xai-inference-objects.json" }, { "provider": "xai", "object": "BatchRequestMetadata", "name": "BatchRequestMetadata", "type_or_object_value": null, "description": "GET /v1/batches/{id}/requests item: {batch_request_id, endpoint ('xai_api.Chat/GetCompletion' live for both chat and responses requests), model, state unknown|pending|succeeded|cancelled|failed, create_time, finish_time}.", "fields": [], "status": [ "DOCUMENTED", "LIVE_VERIFIED" ], "source": "https://docs.x.ai/developers/rest-api-reference/inference/batches", "schema_name": null, "live_example": { "batch_request_metadata": [ { "batch_request_id": "r1", "endpoint": "xai_api.Chat/GetCompletion", "model": "grok-4.3", "state": "succeeded", "create_time": "2026-09-19", "finish_time": "2026-09-19" }, { "batch_request_id": "r2", "endpoint": "xai_api.Chat/GetCompletion", "model": "grok-4.3", "state": "succeeded", "create_time": "2026-09-19", "finish_time": "2026-09-19" } ], "pagination_token": null }, "_fragment": "generated/fragments/objects/xai-inference-objects.json" }, { "provider": "xai", "object": "BatchResult", "name": "BatchResult", "type_or_object_value": null, "description": "GET /v1/batches/{id}/results item: {batch_request_id, batch_result: {response: {chat_get_completion: ChatCompletion | image_generation | video_generation}} | {error: string}}. Live: `responses` requests are returned as chat_get_completion.", "fields": [], "status": [ "DOCUMENTED", "LIVE_VERIFIED" ], "source": "https://docs.x.ai/developers/rest-api-reference/inference/batches", "schema_name": null, "live_example": { "results": [ { "batch_request_id": "r1", "batch_result": { "response": { "chat_get_completion": { "id": "445efed6-dce8-99f3-a8a3-63555b7714af", "object": "chat.completion", "created": 1789789576, "model": "grok-4.3", "choices": [ { "index": 0, "message": { "role": "assistant", "content": "OK.", "reasoning_content": "The user requested a reply of \"OK.\"", "refusal": null }, "finish_reason": "stop" } ], "usage": { "prompt_tokens": 196, "completion_tokens": 2, "total_tokens": 373, "prompt_tokens_details": { "text_tokens": 196, "audio_tokens": 0, "image_tokens": 0, "cached_tokens": 192 }, "completion_tokens_details": { "reasoning_tokens": 175, "audio_tokens": 0, "accepted_prediction_tokens": 0, "rejected_prediction_tokens": 0 }, "num_sources_used": 0, "cost_in_usd_ticks": 3887200 }, "system_fingerprint": "fp_eb3c003fc66c14ed", "service_tier": "default" } } } }, { "batch_request_id": "r2", "batch_result": { "response": { "chat_get_completion": { "id": "0f369eed-f865-9921-bc50-c1173b380a5b", "object": "chat.completion", "created": 1789789575, "model": "grok-4.3", "choices": [ { "index": 0, "message": { "role": "assistant", "content": "OK", "refusal": null }, "finish_reason": "stop" } ], "usage": { "prompt_tokens": 196, "completion_tokens": 1, "total_tokens": 288, "prompt_tokens_details": { "text_tokens": 196, "audio_tokens": 0, "image_tokens": 0, "cached_tokens": 192 }, "completion_tokens_details": { "reasoning_tokens": 91, "audio_tokens": 0, "accepted_prediction_tokens": 0, "rejected_prediction_tokens": 0 }, "num_sources_used": 0, "cost_in_usd_ticks": 2187200 }, "system_fingerprint": "fp_eb3c003fc66c14ed", "service_tier": "default" } } } } ], "pagination_token": null }, "_fragment": "generated/fragments/objects/xai-inference-objects.json" }, { "provider": "xai", "object": "ListBatchesResponse", "name": "ListBatchesResponse", "type_or_object_value": null, "description": "GET /v1/batches → {batches[], pagination_token}.", "fields": [], "status": [ "DOCUMENTED", "LIVE_VERIFIED" ], "source": "https://docs.x.ai/developers/rest-api-reference/inference/batches", "schema_name": null, "_fragment": "generated/fragments/objects/xai-inference-objects.json" }, { "provider": "xai", "object": "ApiKey (GET /v1/api-key)", "name": "ApiKey (GET /v1/api-key)", "type_or_object_value": null, "description": "API-key introspection: redacted_api_key, user_id, name, create_time, modify_time, modified_by, team_id, acls[] ('api-key:model:*', 'api-key:endpoint:*'), api_key_id, team_blocked, api_key_blocked, api_key_disabled. Live: create_time/modify_time = '' .", "fields": [ { "field": "acls", "type": "array", "required": true, "enum": null, "default": null, "description": "A list of ACLs authorized with the API key, e.g. `\"api-key:endpoint:*\"`, `\"api-key:model:*\"`." }, { "field": "api_key_blocked", "type": "boolean", "required": true, "enum": null, "default": null, "description": "Indicates whether the API key is blocked." }, { "field": "api_key_disabled", "type": "boolean", "required": true, "enum": null, "default": null, "description": "Indicates whether the API key is disabled." }, { "field": "api_key_id", "type": "string", "required": true, "enum": null, "default": null, "description": "ID of the API key." }, { "field": "create_time", "type": "string", "required": true, "enum": null, "default": null, "description": "Creation time of the API key in Unix timestamp." }, { "field": "modified_by", "type": "string", "required": true, "enum": null, "default": null, "description": "User ID of the user who last modified the API key." }, { "field": "modify_time", "type": "string", "required": true, "enum": null, "default": null, "description": "Last modification time of the API key in Unix timestamp." }, { "field": "name", "type": "string", "required": true, "enum": null, "default": null, "description": "The name of the API key specified by user." }, { "field": "redacted_api_key", "type": "string", "required": true, "enum": null, "default": null, "description": "The redacted API key." }, { "field": "team_blocked", "type": "boolean", "required": true, "enum": null, "default": null, "description": "Indicates whether the team that owns the API key." }, { "field": "team_id", "type": "string", "required": true, "enum": null, "default": null, "description": "The team ID of the team that owns the API key." }, { "field": "user_id", "type": "string", "required": true, "enum": null, "default": null, "description": "User ID the API key belongs to." } ], "status": [ "DOCUMENTED", "LIVE_VERIFIED" ], "source": "https://docs.x.ai/developers/rest-api-reference/inference/other", "schema_name": "ApiKey", "_fragment": "generated/fragments/objects/xai-inference-objects.json" }, { "provider": "xai", "name": "GeneratedImageResponse", "kind": "response", "description": "Body of POST /v1/images/generations and /v1/images/edits.", "schema": { "data": "GeneratedImage[] (required)", "usage": "MediaUsage|null" }, "status": [ "DOCUMENTED", "LIVE_VERIFIED" ], "example": { "data": [ { "b64_json": "", "mime_type": "image/jpeg" } ], "usage": { "cost_in_usd_ticks": 200000000 } }, "notes": null, "verification": { "method": "live_api", "verified_at": "2026-09-18", "result": "success", "http_status": 200, "request_note": "generation + edit" }, "sources": [ { "url": "https://docs.x.ai/developers/rest-api-reference/inference/images", "retrieved_at": "2026-09-18" } ], "last_verified": "2026-09-18", "_fragment": "generated/fragments/objects/xai-media-objects.json" }, { "provider": "xai", "name": "GeneratedImage", "kind": "object", "description": "One generated image.", "schema": { "url": "string|null (ephemeral https://imgen.x.ai/xai-imgen/xai-.jpeg; default)", "b64_json": "string|null (bare base64, no data-URI prefix; when response_format=b64_json)", "mime_type": "string|null (image/png | image/jpeg | image/webp; live always image/jpeg)", "file_output": "FileOutput (only with storage_options)", "storage_error": "string|null", "respect_moderation": "boolean (xAI SDK / gRPC field; not present on the REST body observed)" }, "status": [ "DOCUMENTED", "LIVE_VERIFIED" ], "example": { "url": "https://imgen.x.ai/xai-imgen/xai-.jpeg", "mime_type": "image/jpeg" }, "notes": null, "verification": { "method": "live_api", "verified_at": "2026-09-18", "result": "success", "http_status": 200, "request_note": "url and b64_json variants both observed" }, "sources": [ { "url": "https://docs.x.ai/developers/rest-api-reference/inference/images", "retrieved_at": "2026-09-18" } ], "last_verified": "2026-09-18", "_fragment": "generated/fragments/objects/xai-media-objects.json" }, { "provider": "xai", "name": "MediaUsage", "kind": "object", "description": "Billing block on image and video responses (`usage`).", "schema": { "cost_in_usd_ticks": "integer (required; 1 USD = 1e10 ticks, 1 cent = 1e8)", "input_tokens": "integer|null", "input_tokens_details": "{cached_tokens, image_tokens, text_tokens}", "output_tokens": "integer|null", "output_tokens_details": "{image_tokens, reasoning_tokens, text_tokens}", "total_tokens": "integer|null" }, "status": [ "DOCUMENTED", "LIVE_VERIFIED" ], "example": { "cost_in_usd_ticks": 220000000 }, "notes": "Live responses contained only cost_in_usd_ticks (image $0.02 = 2e8, edit $0.022 = 2.2e8, 1-s video $0.05 = 5e8).", "verification": { "method": "live_api", "verified_at": "2026-09-18", "result": "success", "http_status": 200, "request_note": "3 media responses" }, "sources": [ { "url": "https://docs.x.ai/developers/rest-api-reference/inference/images", "retrieved_at": "2026-09-18" }, { "url": "https://docs.x.ai/developers/cost-tracking", "retrieved_at": "2026-09-18" } ], "last_verified": "2026-09-18", "_fragment": "generated/fragments/objects/xai-media-objects.json" }, { "provider": "xai", "name": "FileOutput", "kind": "object", "description": "Stored-file reference returned when `storage_options` is set (images: data[].file_output; videos: video.file_output).", "schema": { "file_id": "string (Files API id)", "filename": "string", "expires_at": "integer|null (unix s)", "public_url": "string|null", "public_url_error": "string|null", "public_url_expires_at": "integer|null" }, "status": [ "DOCUMENTED" ], "example": null, "notes": null, "verification": { "method": "docs_only", "verified_at": "2026-09-18", "result": "not_tested", "http_status": null, "request_note": "documentation only (paid, needs media input, or enterprise-gated)" }, "sources": [ { "url": "https://docs.x.ai/developers/rest-api-reference/inference/images", "retrieved_at": "2026-09-18" }, { "url": "https://docs.x.ai/developers/model-capabilities/imagine/files/outputs", "retrieved_at": "2026-09-18" } ], "last_verified": "2026-09-18", "_fragment": "generated/fragments/objects/xai-media-objects.json" }, { "provider": "xai", "name": "StorageOptions", "kind": "request object", "description": "`storage_options` on every Imagine request.", "schema": { "filename": "string (required)", "expires_after": "integer|null (≤ 2592000 s)", "public_url": "boolean|object" }, "status": [ "DOCUMENTED" ], "example": null, "notes": null, "verification": { "method": "docs_only", "verified_at": "2026-09-18", "result": "not_tested", "http_status": null, "request_note": "documentation only (paid, needs media input, or enterprise-gated)" }, "sources": [ { "url": "https://docs.x.ai/developers/rest-api-reference/inference/images", "retrieved_at": "2026-09-18" }, { "url": "https://docs.x.ai/developers/model-capabilities/imagine/files/outputs", "retrieved_at": "2026-09-18" } ], "last_verified": "2026-09-18", "_fragment": "generated/fragments/objects/xai-media-objects.json" }, { "provider": "xai", "name": "ImageGenerationModel", "kind": "model record", "description": "Item of GET /v1/image-generation-models.", "schema": { "id": "string", "object": "'model'", "owned_by": "'xai'", "version": "string", "fingerprint": "string (fp_…)", "created": "integer", "max_prompt_length": "integer", "input_modalities": "string[]", "output_modalities": "string[]", "image_price": "integer (USD ticks per image, default tier)", "pricing": "ImagePricingTier[] (only grok-imagine-image-2.0)", "aliases": "string[]" }, "status": [ "DOCUMENTED", "LIVE_VERIFIED" ], "example": { "id": "grok-imagine-image-2.0", "image_price": 600000000, "pricing": [ { "quality": "low", "resolution": "1k", "price_per_image": 400000000 } ], "max_prompt_length": 64000 }, "notes": null, "verification": { "method": "live_api", "verified_at": "2026-09-18", "result": "success", "http_status": 200, "request_note": "3 models" }, "sources": [ { "url": "https://docs.x.ai/openapi.json (local copy sources/xai/openapi/openapi.json)", "retrieved_at": "2026-09-18" } ], "last_verified": "2026-09-18", "_fragment": "generated/fragments/objects/xai-media-objects.json" }, { "provider": "xai", "name": "ImagePricingTier", "kind": "object", "description": "Per-image price for one (quality, resolution) tier.", "schema": { "quality": "'low'|'medium'|'high'", "resolution": "'1k'|'1.5k'|'2k'", "price_per_image": "integer (USD ticks)" }, "status": [ "DOCUMENTED", "LIVE_VERIFIED" ], "example": { "quality": "medium", "resolution": "2k", "price_per_image": 800000000 }, "notes": null, "verification": { "method": "live_api", "verified_at": "2026-09-18", "result": "success", "http_status": 200, "request_note": "6 tiers on 2.0: low 4e8/5e8/6e8, medium 6e8/7e8/8e8" }, "sources": [ { "url": "https://docs.x.ai/openapi.json (local copy sources/xai/openapi/openapi.json)", "retrieved_at": "2026-09-18" } ], "last_verified": "2026-09-18", "_fragment": "generated/fragments/objects/xai-media-objects.json" }, { "provider": "xai", "name": "VideoGenerationModel", "kind": "model record", "description": "Item of GET /v1/video-generation-models (no price field).", "schema": { "id": "string", "object": "'model'", "owned_by": "'xai'", "version": "string", "fingerprint": "string", "created": "integer", "input_modalities": "string[] (text|image|video|audio)", "output_modalities": "['video']", "aliases": "string[]" }, "status": [ "DOCUMENTED", "LIVE_VERIFIED" ], "example": { "id": "grok-imagine-video-1.5", "input_modalities": [ "text", "image", "audio" ], "aliases": [ "grok-imagine-video-1.5-preview", "grok-imagine-video-1.5-2026-05-30" ] }, "notes": null, "verification": { "method": "live_api", "verified_at": "2026-09-18", "result": "success", "http_status": 200, "request_note": "2 models" }, "sources": [ { "url": "https://docs.x.ai/openapi.json (local copy sources/xai/openapi/openapi.json)", "retrieved_at": "2026-09-18" } ], "last_verified": "2026-09-18", "_fragment": "generated/fragments/objects/xai-media-objects.json" }, { "provider": "xai", "name": "VideoStartResponse", "kind": "response", "description": "Body of POST /v1/videos/{generations,edits,extensions}.", "schema": { "request_id": "string (UUID; also echoed as x-request-id header)" }, "status": [ "DOCUMENTED", "LIVE_VERIFIED" ], "example": { "request_id": "60407e87-a722-92de-8eeb-9a71491aa8e1" }, "notes": null, "verification": { "method": "live_api", "verified_at": "2026-09-18", "result": "success", "http_status": 200, "request_note": "generation" }, "sources": [ { "url": "https://docs.x.ai/developers/rest-api-reference/inference/videos", "retrieved_at": "2026-09-18" } ], "last_verified": "2026-09-18", "_fragment": "generated/fragments/objects/xai-media-objects.json" }, { "provider": "xai", "name": "VideoResponse (poll result)", "kind": "response", "description": "Body of GET /v1/videos/{request_id}. HTTP 202 while pending, 200 when done. The OpenAPI wrapper GetDeferredVideoResponse {status, response} is NOT used by REST.", "schema": { "status": "'pending'|'done'|'failed'|'expired'", "progress": "integer|null 0–100 (omitted when failed)", "video": "GeneratedVideo (done only)", "model": "string|null (done only)", "usage": "MediaUsage|null", "error": "VideoError (failed only)" }, "status": [ "DOCUMENTED", "LIVE_VERIFIED" ], "example": { "status": "done", "video": { "url": "https://vidgen.x.ai/xai-vidgen-bucket/xai-video-.mp4", "duration": 1, "respect_moderation": true }, "model": "grok-imagine-video", "usage": { "cost_in_usd_ticks": 500000000 }, "progress": 100 }, "notes": null, "verification": { "method": "live_api", "verified_at": "2026-09-18", "result": "success", "http_status": 200, "request_note": "202 {status:pending, progress:1} → 202 {pending, 87} → 200 done" }, "sources": [ { "url": "https://docs.x.ai/developers/rest-api-reference/inference/videos", "retrieved_at": "2026-09-18" }, { "url": "https://docs.x.ai/developers/model-capabilities/video/generation", "retrieved_at": "2026-09-18" } ], "last_verified": "2026-09-18", "_fragment": "generated/fragments/objects/xai-media-objects.json" }, { "provider": "xai", "name": "GeneratedVideo", "kind": "object", "description": "`video` of a done poll.", "schema": { "url": "string|null (temporary; empty when respect_moderation=false)", "duration": "integer (s)", "respect_moderation": "boolean", "file_output": "FileOutput (with storage_options)", "storage_error": "string|null" }, "status": [ "DOCUMENTED", "LIVE_VERIFIED" ], "example": { "url": "https://vidgen.x.ai/…/xai-video-.mp4", "duration": 1, "respect_moderation": true }, "notes": null, "verification": { "method": "live_api", "verified_at": "2026-09-18", "result": "success", "http_status": 200, "request_note": "MP4 53 KB, video/mp4" }, "sources": [ { "url": "https://docs.x.ai/developers/rest-api-reference/inference/videos", "retrieved_at": "2026-09-18" } ], "last_verified": "2026-09-18", "_fragment": "generated/fragments/objects/xai-media-objects.json" }, { "provider": "xai", "name": "VideoError", "kind": "object", "description": "`error` of a failed poll.", "schema": { "code": "'invalid_argument'|'permission_denied'|'failed_precondition'|'service_unavailable'|'internal_error'", "message": "string" }, "status": [ "DOCUMENTED" ], "example": { "code": "invalid_argument", "message": "Prompt cannot be empty. Please provide a prompt." }, "notes": "Auth, model-not-found and synchronous rate-limit errors are HTTP errors, never VideoError.", "verification": { "method": "docs_only", "verified_at": "2026-09-18", "result": "not_tested", "http_status": null, "request_note": "documentation only (paid, needs media input, or enterprise-gated)" }, "sources": [ { "url": "https://docs.x.ai/developers/rest-api-reference/inference/videos", "retrieved_at": "2026-09-18" }, { "url": "https://docs.x.ai/developers/model-capabilities/video/generation", "retrieved_at": "2026-09-18" } ], "last_verified": "2026-09-18", "_fragment": "generated/fragments/objects/xai-media-objects.json" }, { "provider": "xai", "name": "ClientSecret", "kind": "response", "description": "Body of POST /v1/realtime/client_secrets.", "schema": { "value": "string (prefix xai-realtime-… / observed 'xai-real', 111 chars)", "expires_at": "integer (unix s)" }, "status": [ "DOCUMENTED", "LIVE_VERIFIED" ], "example": { "value": "xai-realtime-…", "expires_at": 1789789324 }, "notes": null, "verification": { "method": "live_api", "verified_at": "2026-09-18", "result": "success", "http_status": 200, "request_note": "60 s TTL" }, "sources": [ { "url": "https://docs.x.ai/developers/rest-api-reference/inference/voice", "retrieved_at": "2026-09-18" } ], "last_verified": "2026-09-18", "_fragment": "generated/fragments/objects/xai-media-objects.json" }, { "provider": "xai", "name": "realtime.session", "kind": "object", "description": "`session` in session.created / session.updated.", "schema": { "id": "string (32 hex)", "object": "'realtime.session'", "model": "string", "instructions": "string", "voice": "string", "modalities": "['audio'] observed", "turn_detection": "{type: 'server_vad'|null, …}", "tools": "array", "reasoning": "{effort}", "audio": "{input:{format:{type,rate}, transport}, output:{…}}", "resumption": "{enabled}", "replace": "object", "observed_only_in_session.updated": [ "enable_noise_suppression", "enable_phonetic_spelling", "keep_context", "input_audio_format", "output_audio_format", "tool_choice", "temperature", "max_response_output_tokens", "input_audio_transcription" ] }, "status": [ "DOCUMENTED", "LIVE_VERIFIED" ], "example": { "id": "e4af06be…", "object": "realtime.session", "instructions": "", "voice": "xai_ara", "modalities": [ "audio" ], "turn_detection": { "type": null }, "tools": [], "model": "grok-voice-think-fast-2.0" }, "notes": "Default voice reported as 'xai_ara' (docs say eve). session.updated echoes the effective config in a flatter, partly undocumented shape.", "verification": { "method": "live_api", "verified_at": "2026-09-18", "result": "success", "http_status": 101, "request_note": "text-only probe" }, "sources": [ { "url": "https://docs.x.ai/voice-realtime.ws.json", "retrieved_at": "2026-09-18" } ], "last_verified": "2026-09-18", "_fragment": "generated/fragments/objects/xai-media-objects.json" }, { "provider": "xai", "name": "realtime.conversation", "kind": "object", "description": "`conversation` in conversation.created.", "schema": { "id": "string (UUID; use as ?conversation_id= for resumption)", "object": "'realtime.conversation'" }, "status": [ "DOCUMENTED", "LIVE_VERIFIED" ], "example": { "id": "08b1471f-87d5-4963-b94e-092537a06b95", "object": "realtime.conversation" }, "notes": null, "verification": { "method": "live_api", "verified_at": "2026-09-18", "result": "success", "http_status": 101, "request_note": "both probes" }, "sources": [ { "url": "https://docs.x.ai/voice-realtime.ws.json", "retrieved_at": "2026-09-18" } ], "last_verified": "2026-09-18", "_fragment": "generated/fragments/objects/xai-media-objects.json" }, { "provider": "xai", "name": "realtime.item", "kind": "object", "description": "Conversation item (conversation.item.added, response.output_item.*, response.done.output[]).", "schema": { "id": "string (UUID)", "object": "'realtime.item'", "type": "'message'|'function_call'|'function_call_output'|'force_message'", "status": "'in_progress'|'completed'", "role": "'user'|'assistant'", "content": "[{type:'input_text'|'output_text'|'audio'|'input_audio', text?, transcript?}]", "replayed": "boolean (true when replayed by session resumption)", "call_id/name/arguments/output": "function items" }, "status": [ "DOCUMENTED", "LIVE_VERIFIED" ], "example": { "id": "95be5a32-…", "object": "realtime.item", "type": "message", "status": "completed", "role": "user", "content": [ { "type": "input_text", "text": "Reply with OK." } ], "replayed": false }, "notes": null, "verification": { "method": "live_api", "verified_at": "2026-09-18", "result": "success", "http_status": 101, "request_note": "user + assistant items observed" }, "sources": [ { "url": "https://docs.x.ai/voice-realtime.ws.json", "retrieved_at": "2026-09-18" } ], "last_verified": "2026-09-18", "_fragment": "generated/fragments/objects/xai-media-objects.json" }, { "provider": "xai", "name": "realtime.response", "kind": "object", "description": "`response` in response.created / response.done.", "schema": { "id": "string (UUID)", "object": "'realtime.response'", "status": "'in_progress'|'completed'|'cancelled'|'incomplete'", "status_details": "string ('unimplemented' observed)", "output": "realtime.item[]", "usage": "{} (empty; real usage is top-level on response.done)", "metadata": "object|null" }, "status": [ "DOCUMENTED", "LIVE_VERIFIED" ], "example": { "id": "5e885467-…", "object": "realtime.response", "status": "completed", "status_details": "unimplemented", "output": [ { "type": "message", "role": "assistant", "content": [ { "type": "audio", "transcript": "OK" } ] } ], "usage": {} }, "notes": null, "verification": { "method": "live_api", "verified_at": "2026-09-18", "result": "success", "http_status": 101, "request_note": "response.done" }, "sources": [ { "url": "https://docs.x.ai/voice-realtime.ws.json", "retrieved_at": "2026-09-18" } ], "last_verified": "2026-09-18", "_fragment": "generated/fragments/objects/xai-media-objects.json" }, { "provider": "xai", "name": "realtime response usage (response.done.usage)", "kind": "object", "description": "Top-level `usage` on response.done — the billing signal for Speech to Speech.", "schema": { "input_tokens": "integer", "input_token_details": "{text_tokens, audio_tokens, grok_tokens}", "output_tokens": "integer", "output_token_details": "{text_tokens, audio_tokens, grok_tokens}", "total_tokens": "integer", "output_audio_seconds": "number", "billable_audio_seconds": "integer (rounded up; × $0.08/60)" }, "status": [ "LIVE_DISCOVERED" ], "example": { "input_tokens": 4, "input_token_details": { "text_tokens": 4, "audio_tokens": 0, "grok_tokens": 0 }, "output_tokens": 37, "output_token_details": { "text_tokens": 1, "audio_tokens": 36, "grok_tokens": 0 }, "total_tokens": 41, "output_audio_seconds": 0.71, "billable_audio_seconds": 1 }, "notes": "Not in the ws.json schema (which documents only input/output/total tokens inside response.usage).", "verification": { "method": "live_api", "verified_at": "2026-09-18", "result": "success", "http_status": 101, "request_note": "text-only probe" }, "sources": [ { "url": "tmp-live/xai-media/voice-ws-session.json", "retrieved_at": "2026-09-18" } ], "last_verified": "2026-09-18", "_fragment": "generated/fragments/objects/xai-media-objects.json" }, { "provider": "xai", "name": "realtime audio delta extras", "kind": "object", "description": "Undocumented fields observed on response.output_audio.delta / transcript.delta.", "schema": { "rid": "string (UUID; groups deltas of one synthesis run)", "latency": "string seconds ('0.49' on first delta)", "audio_duration_ms": "integer (ms of PCM in this delta)", "ts": "integer unix ms", "start_time": "number (transcript delta)", "previous_item_id": "string|null (on every event)" }, "status": [ "LIVE_DISCOVERED" ], "example": { "audio_duration_ms": 550, "latency": "0.49", "rid": "07193536-…" }, "notes": null, "verification": { "method": "live_api", "verified_at": "2026-09-18", "result": "success", "http_status": 101, "request_note": "probe" }, "sources": [ { "url": "tmp-live/xai-media/voice-ws-session.json", "retrieved_at": "2026-09-18" } ], "last_verified": "2026-09-18", "_fragment": "generated/fragments/objects/xai-media-objects.json" }, { "provider": "xai", "name": "Voice (built-in)", "kind": "object", "description": "Item of GET /v1/tts/voices.", "schema": { "voice_id": "string (lowercase)", "name": "string", "language": "string|null ('multilingual' live; 'en' in docs)", "gender": "'male'|'female' (undocumented)" }, "status": [ "DOCUMENTED", "LIVE_VERIFIED" ], "example": { "voice_id": "eve", "name": "Eve", "language": "multilingual", "gender": "female" }, "notes": null, "verification": { "method": "live_api", "verified_at": "2026-09-18", "result": "success", "http_status": 200, "request_note": "28 voices" }, "sources": [ { "url": "https://docs.x.ai/developers/rest-api-reference/inference/voice", "retrieved_at": "2026-09-18" } ], "last_verified": "2026-09-18", "_fragment": "generated/fragments/objects/xai-media-objects.json" }, { "provider": "xai", "name": "TTS JSON envelope", "kind": "response", "description": "POST /v1/tts response when with_timestamps=true.", "schema": { "audio": "string base64", "content_type": "string (audio/mpeg …)", "duration": "number s", "audio_timestamps": "{graph_chars: string[], graph_times: [start, end][]}" }, "status": [ "DOCUMENTED", "LIVE_VERIFIED" ], "example": { "audio": "", "content_type": "audio/mpeg", "duration": 0.71, "audio_timestamps": { "graph_chars": [ "O", "K", "." ], "graph_times": [ [ 0.04, 0.06 ], [ 0.2, 0.22 ], [ 0.22, 0.71 ] ] } }, "notes": "graph_times items are [start, end] arrays (guide) — the REST reference's {start, end} objects do not match the live shape.", "verification": { "method": "live_api", "verified_at": "2026-09-18", "result": "success", "http_status": 200, "request_note": "'OK.'" }, "sources": [ { "url": "https://docs.x.ai/developers/rest-api-reference/inference/voice", "retrieved_at": "2026-09-18" }, { "url": "https://docs.x.ai/developers/model-capabilities/audio/text-to-speech", "retrieved_at": "2026-09-18" } ], "last_verified": "2026-09-18", "_fragment": "generated/fragments/objects/xai-media-objects.json" }, { "provider": "xai", "name": "STT transcript", "kind": "response", "description": "Body of POST /v1/stt.", "schema": { "text": "string", "language": "string (BCP-47)", "duration": "number s", "words": "[{text, start, end, confidence?, speaker?}] (omitted when empty)", "channels": "[{index, language, text, words[]}] (multichannel)" }, "status": [ "DOCUMENTED", "LIVE_VERIFIED" ], "example": { "text": "Okay.", "language": "en", "duration": 0.79, "words": [ { "text": "Okay.", "start": 0.122, "end": 0.466 } ] }, "notes": null, "verification": { "method": "live_api", "verified_at": "2026-09-18", "result": "success", "http_status": 200, "request_note": "0.79 s clip" }, "sources": [ { "url": "https://docs.x.ai/developers/rest-api-reference/inference/voice", "retrieved_at": "2026-09-18" } ], "last_verified": "2026-09-18", "_fragment": "generated/fragments/objects/xai-media-objects.json" }, { "provider": "xai", "name": "STT streaming transcript.partial", "kind": "event payload", "description": "State flags: interim (is_final=false) → chunk final (is_final=true, speech_final=false) → utterance final (is_final=true, speech_final=true); end_of_turn_confidence with smart_turn.", "schema": { "type": "'transcript.partial'", "text": "string", "is_final": "boolean", "speech_final": "boolean", "words": "[{text,start,end,speaker?}]", "channel": "integer (multichannel)", "end_of_turn_confidence": "number (smart_turn)" }, "status": [ "DOCUMENTED" ], "example": null, "notes": null, "verification": { "method": "docs_only", "verified_at": "2026-09-18", "result": "not_tested", "http_status": null, "request_note": "documentation only (paid, needs media input, or enterprise-gated)" }, "sources": [ { "url": "https://docs.x.ai/stt-streaming.ws.json", "retrieved_at": "2026-09-18" } ], "last_verified": "2026-09-18", "_fragment": "generated/fragments/objects/xai-media-objects.json" }, { "provider": "xai", "name": "CustomVoice", "kind": "object", "description": "Custom (cloned) voice.", "schema": { "voice_id": "string (8 lowercase alnum)", "name": "string|null", "description": "string|null", "gender": "'male'|'female'|'neutral'|null", "accent": "string|null", "age": "'young'|'middle-aged'|'old'|null", "language": "string|null", "use_case": "string|null", "tone": "string|null", "created_at": "RFC 3339" }, "status": [ "DOCUMENTED" ], "example": { "voice_id": "nlbqfwie", "name": "Friendly Narrator", "gender": "female", "language": "en", "use_case": "narration", "tone": "warm", "created_at": "2026-04-26T18:56:34.872993+00:00" }, "notes": null, "verification": { "method": "docs_only", "verified_at": "2026-09-18", "result": "not_tested", "http_status": null, "request_note": "documentation only (paid, needs media input, or enterprise-gated)" }, "sources": [ { "url": "https://docs.x.ai/developers/rest-api-reference/inference/voice", "retrieved_at": "2026-09-18" }, { "url": "https://docs.x.ai/developers/model-capabilities/audio/custom-voices", "retrieved_at": "2026-09-18" } ], "last_verified": "2026-09-18", "_fragment": "generated/fragments/objects/xai-media-objects.json" }, { "provider": "xai", "name": "CustomVoiceList", "kind": "response", "description": "GET /v1/custom-voices.", "schema": { "voices": "CustomVoice[]", "pagination_token": "string|null (absent when no more)", "total_count": "integer (undocumented)", "cap": "integer (undocumented; 30)" }, "status": [ "DOCUMENTED", "LIVE_VERIFIED" ], "example": { "voices": [], "total_count": 0, "cap": 30 }, "notes": null, "verification": { "method": "live_api", "verified_at": "2026-09-18", "result": "success", "http_status": 200, "request_note": "empty" }, "sources": [ { "url": "https://docs.x.ai/developers/rest-api-reference/inference/voice", "retrieved_at": "2026-09-18" } ], "last_verified": "2026-09-18", "_fragment": "generated/fragments/objects/xai-media-objects.json" }, { "provider": "xai", "name": "PhoneNumber (SIP)", "kind": "object", "description": "POST /v2/phone-numbers response.", "schema": { "phone_number": "{phone_number_id, team_id, phone_number (E.164), name, agent_id, webhook_id, origin, sip_host ('sip.voice.x.ai'), inbound_trunk_id, sip_auth:{auth_username, allowed_addresses[]}, created_at, updated_at, agent_name}", "webhook": "{webhook_id, dispatch_signing_secret (returned once)}" }, "status": [ "DOCUMENTED" ], "example": null, "notes": null, "verification": { "method": "docs_only", "verified_at": "2026-09-18", "result": "not_tested", "http_status": null, "request_note": "documentation only (paid, needs media input, or enterprise-gated)" }, "sources": [ { "url": "https://docs.x.ai/developers/rest-api-reference/inference/voice", "retrieved_at": "2026-09-18" }, { "url": "https://docs.x.ai/developers/model-capabilities/audio/speech-to-speech/sip", "retrieved_at": "2026-09-18" } ], "last_verified": "2026-09-18", "_fragment": "generated/fragments/objects/xai-media-objects.json" }, { "provider": "xai", "name": "Skill", "kind": "object", "description": "Hosted skill (OpenAPI).", "schema": { "id": "string", "object": "'skill'", "name": "string (SKILL.md frontmatter)", "description": "string (frontmatter)", "created_at": "integer unix s", "default_version": "'1'", "latest_version": "'1'" }, "status": [ "DOCUMENTED", "ACCOUNT_RESTRICTED" ], "example": null, "notes": null, "verification": { "method": "live_api", "verified_at": "2026-09-18", "result": "restricted", "http_status": 404, "request_note": "all /v1/skills routes 404 with our key" }, "sources": [ { "url": "https://docs.x.ai/openapi.json (local copy sources/xai/openapi/openapi.json)", "retrieved_at": "2026-09-18" } ], "last_verified": "2026-09-18", "_fragment": "generated/fragments/objects/xai-media-objects.json" }, { "provider": "xai", "name": "SkillList", "kind": "response", "description": "GET /v1/skills.", "schema": { "object": "'list'", "data": "Skill[]", "first_id": "string", "last_id": "string", "has_more": "boolean" }, "status": [ "DOCUMENTED", "ACCOUNT_RESTRICTED" ], "example": null, "notes": null, "verification": { "method": "docs_only", "verified_at": "2026-09-18", "result": "not_tested", "http_status": null, "request_note": "documentation only (paid, needs media input, or enterprise-gated)" }, "sources": [ { "url": "https://docs.x.ai/openapi.json (local copy sources/xai/openapi/openapi.json)", "retrieved_at": "2026-09-18" } ], "last_verified": "2026-09-18", "_fragment": "generated/fragments/objects/xai-media-objects.json" }, { "provider": "xai", "name": "DeletedSkill", "kind": "response", "description": "DELETE /v1/skills/{id}.", "schema": { "id": "string", "object": "'skill.deleted'", "deleted": "boolean" }, "status": [ "DOCUMENTED", "ACCOUNT_RESTRICTED" ], "example": null, "notes": null, "verification": { "method": "docs_only", "verified_at": "2026-09-18", "result": "not_tested", "http_status": null, "request_note": "documentation only (paid, needs media input, or enterprise-gated)" }, "sources": [ { "url": "https://docs.x.ai/openapi.json (local copy sources/xai/openapi/openapi.json)", "retrieved_at": "2026-09-18" } ], "last_verified": "2026-09-18", "_fragment": "generated/fragments/objects/xai-media-objects.json" }, { "provider": "xai", "name": "LocalShellSkill", "kind": "request object", "description": "Skill made available to a local `shell` tool environment (ShellCall.environment.skills[]).", "schema": { "name": "string", "description": "string", "path": "string (directory containing SKILL.md)" }, "status": [ "DOCUMENTED" ], "example": null, "notes": null, "verification": { "method": "docs_only", "verified_at": "2026-09-18", "result": "not_tested", "http_status": null, "request_note": "documentation only (paid, needs media input, or enterprise-gated)" }, "sources": [ { "url": "https://docs.x.ai/openapi.json (local copy sources/xai/openapi/openapi.json)", "retrieved_at": "2026-09-18" } ], "last_verified": "2026-09-18", "_fragment": "generated/fragments/objects/xai-media-objects.json" }, { "provider": "xai", "name": "xAI error envelopes (media/voice)", "kind": "error", "description": "Three shapes observed on this surface.", "schema": { "A (most 4xx, application/json)": "{code: 'invalid-argument'|'not-found'|…, error: string}", "B (routing 404, application/json)": "{error: {code: 404, message: string}}", "C (body deserialization, 422 text/plain)": "'Failed to deserialize the JSON body into the target type: : unknown variant `x`, expected one of …' / 'missing field `y`'" }, "status": [ "LIVE_VERIFIED" ], "example": { "A": { "code": "invalid-argument", "error": "The number of images to generate (n) must be between 1 and 10 inclusive." }, "B": { "error": { "code": 404, "message": "The requested resource was not found. Please check the URL and try again. Documentation is available at https://docs.x.ai/" } }, "C": "Failed to deserialize the JSON body into the target type: missing field `language` at line 1 column 34" }, "notes": null, "verification": { "method": "live_api", "verified_at": "2026-09-18", "result": "success", "http_status": 422, "request_note": "images 7:7, n=0, png; videos 99 s, 4k, missing video; tts missing language; skills 404" }, "sources": [ { "url": "tmp-live/xai-media/*.json", "retrieved_at": "2026-09-18" } ], "last_verified": "2026-09-18", "_fragment": "generated/fragments/objects/xai-media-objects.json" } ]