> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.privategpt.dev/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.privategpt.dev/_mcp/server. # Messages POST /v1/messages Content-Type: application/json Generate a chat completion from a conversation history. This endpoint enables multi-turn conversations with the AI model, with optional tool support and comprehensive message validation. Key Features: * Multi-turn conversations: Support for system, user, and assistant messages * Tool Support: Full tool use/result validation with automatic or manual selection * Citations: Enable `system.citations.enabled` to include references in responses * Streaming: Enable `stream` for partial updates in real-time * Default Prompts: Enable `system.use_default_prompt` for using Zylon prompts * Thinking: Enable `thinking.enabled` for step-by-step reasoning capabilities * Sampling Parameters: Control randomness with temperature, top_p, top_k, etc. Notes: * Tool use/result blocks must be properly paired within assistant messages * Tool choice type must be 'auto', 'tool', or 'none' * When tool_choice.type is 'tool', tool_choice.name must specify a valid tool * All message content is validated for completeness and proper structure * Last message must be from user or assistant for proper conversation flow * MCP servers provide external tool capabilities via Model Context Protocol * Sampling parameters control response randomness and token selection Reference: https://docs.privategpt.dev/api-reference/messages/chat-messages-v-1-messages-post ## Request ### Body (application/json) This endpoint expects a ChatBody. - `model` (string, required, default: default) — Model identifier or alias. - `messages` (list of MessageInput, required) — Conversation messages for the request. - `max_tokens` (integer, required) — Maximum number of tokens to generate in the response. - `system` (list of System, optional) — System prompt input. Accepts str, list[str], System, list[System], or null. It is normalized internally to list[System]. - `tools` (list of ToolSpecBody, optional, nullable) — Optional tool definitions. - `thinking` (Thinking, optional) — Thinking configuration. - `tool_choice` (ToolChoice, optional) — Tool selection policy. - `output_config` (OutputConfigInput, optional) — Optional output configuration options. - `cache_control` (ChatBodyCacheControl, optional, nullable) — Optional request-level cache control. - `stream` (boolean, optional, default: false) — Whether to stream the response back to the client. - `tool_context` (list of ChatBodyToolContextItems, optional, nullable) — Context to provide to the tools, such as documents, databases connection strings, or data relevant to tool usage. - `mcp_servers` (list of McpServerConfig, optional) — List of MCP servers to use for tool retrieval. Each server can have its own configuration. - `container` (string, optional, nullable) — Container identifier for reuse across requests. - `mounts` (list of MountEntry, optional, nullable) — Mount entries requesting files or folders to be available inside the sandbox. - `response_format` (ResponseFormat, optional) — Deprecated response format. Use output_config.format instead. - `priority` (integer, optional, nullable) — Priority of the request, used for prioritizing responses. - `seed` (integer, optional, nullable) — Random seed for reproducibility. - `min_p` (double, optional, nullable) — Minimum probability threshold for token selection. Tokens with probability below this value are filtered out. - `top_p` (double, optional) — Nucleus sampling parameter. Only tokens with cumulative probability up to this value are considered. - `temperature` (double, optional) — Controls randomness in generation. Higher values make output more random, lower values more deterministic. - `top_k` (integer, optional) — Limits token selection to the top K most likely tokens at each step. - `repetition_penalty` (double, optional, nullable) — Penalty applied to tokens that have already appeared in the sequence to reduce repetition. - `presence_penalty` (double, optional, nullable) — Penalty applied based on whether a token has appeared in the text, encouraging topic diversity. - `frequency_penalty` (double, optional, nullable) — Penalty applied based on how frequently a token appears in the text, reducing repetitive content. - `stop_sequences` (list of string, optional) — Custom stop sequences that stop generation when matched. - `metadata` (CompletionMetadata, optional) — Request metadata (for example, user_id). - `service_tier` (enum, optional, default: auto) — Service tier preference (for example, "auto" or "standard_only"). - Allowed values: `auto`, `standard_only` - `inference_geo` (string, optional, nullable) — Geographic region hint for inference processing. - `correlation_id` (string, optional, nullable) — Correlation ID for tracking the request across systems. - `maximum_loaded_skills` (integer, optional, nullable) — Optional cap for concurrently loaded skills in a conversation. When exceeded, the oldest loaded skill is evicted. ## Response ### 200 Successful chat message - `id` (string, optional) — Message identifier. - `type` ("message", optional, default: message) — Object type. - `role` ("assistant", optional, default: assistant) — Message author role. - `content` (list of MessageContentItems, optional) — Assistant content blocks. - `model` (string, optional, default: private-gpt) — Model name used. - `container` (Container, optional, nullable) — Optional execution container. - `stop_details` (RefusalStopDetails, optional, nullable) — Optional structured stop details. - `stop_reason` (string, optional, nullable) — Message stop reason. - `stop_sequence` (string, optional, nullable) — Matched stop sequence, if any. - `usage` (Usage, optional) — Token usage stats. ## Errors ### 401 Unauthorized Error Unauthorized - `any` ## Types ### MessageInput Input message for AI conversations. - `role` (enum, required) — The role of the message sender - Allowed values: `system`, `user`, `assistant` - `content` (MessageInputContent, required) — The message content ### System System message configuration for AI behavior and prompting. - `text` (string, optional, nullable) — System prompt to use for the chat completion - `citations` (Citations, optional) — Citation configuration for source attribution in responses - `extensions` (list of enum, optional) — Set of enabled extensions - Allowed values: `zylon` - `blob_visibility` (enum, optional) — Controls how blobs are exposed: binary (raw data), internal (private S3 URI), or public (public S3 URL) - Allowed values: `binary`, `internal`, `public` - `prompt` (PromptConfig, optional) — Controls which platform-level prompt features are injected. - `use_default_prompt` (boolean, optional, default: false, deprecated) — Deprecated: legacy toggle for built-in default prompt injection. Use system.prompt to control per-category prompt injection. ### ToolSpecBody Definition for a tool the client can call. - `name` (string, required) — Unique name identifier for the tool - `type` (string, optional, nullable) — Type of the tool, use to identify internal tools database_query_v1 or semantic_search_v1 - `description` (string, optional, nullable) — Human-readable description of what the tool does - `inputSchema` (map from string to any, optional, nullable) — JSON schema defining the input parameters the tool accepts - `context` (list of ToolSpecBodyContextItems, optional, nullable) — Additional context or metadata for the tool - `deferLoading` (boolean, optional, default: false) — When true, hide this tool from the model until at least one skill is loaded in the current conversation. - `instructions` (string, optional, nullable) — Optional instructions injected into the system prompt when this tool is available. For internal tools a default template is used; providing a value here overrides that default. Set to an empty string to disable. ### Thinking Configuration for AI reasoning and step-by-step thinking capabilities. - `enabled` (boolean, optional, default: false) — Enable reasoning capabilities for the model, allowing it to think step-by-step - `effort` (enum, optional, nullable, deprecated) — Deprecated. Use output_config.effort instead. Kept for backward compatibility with legacy clients. - Allowed values: `low`, `medium`, `high`, `max`, `xhigh` ### ToolChoice Configuration for tool selection behavior during AI interactions. - `type` (enum, optional, default: auto) — Tool selection strategy - Allowed values: `auto`, `any`, `tool`, `none` - `name` (string, optional, nullable) — Name of the tool to use if not auto-selecting - `disable_parallel_tool_use` (boolean, optional, default: false) — When true, prevents the AI from using multiple tools simultaneously - `validation_mode` (enum, optional, default: lazy) — Tool validation mode. 'eager' validates tool calls before execution, 'lazy' validates if tool call is made. - Allowed values: `eager`, `lazy` ### OutputConfigInput Output configuration shared across Anthropic-compatible request models. - `effort` (enum, optional, nullable) — Reasoning effort level for output generation. - Allowed values: `low`, `medium`, `high`, `max`, `xhigh` - `format` (JsonObjectFormat, optional, nullable) — Optional structured output format schema. ### ChatBodyCacheControl Optional request-level cache control. - `type`: `ephemeral` (CacheControlEphemeral) - `ttl` (enum, optional, default: 5m) — ttl field. - Allowed values: `5m`, `1h` ### ChatBodyToolContextItems - `type`: `file` (FileArtifact) - `value` (string, required) — Base64 encoded file content - `type`: `ingested_artifact` (IngestedArtifact) - `context_filter` (ContextFilter, required) — Already processed ContextFilter - `type`: `skill` (SkillArtifact) - `skill_filter` (SkillFilter, required) — Skill filter declaring the collection and optional skill_or_version_ids whitelist. - `type`: `sql_database` (SqlDatabaseArtifact) - `connection_string` (string, required) — SQL database connection string - `description` (string, optional, default: ) — Optional description of the database - `enable_functions` (boolean, optional, default: true) — Whether to include functions in the inspection - `enable_procedures` (boolean, optional, default: true) — Whether to include stored procedures in the inspection - `enable_tables` (boolean, optional, default: true) — Whether to include tables in the inspection - `enable_views` (boolean, optional, default: true) — Whether to include views in the inspection - `schemas` (list of string, optional, nullable) — List of specific schemas to include, if None includes all non-system schemas - `ssl` (boolean, optional, default: false) — Whether to use SSL for the database connection - `type`: `text` (TextArtifact) - `value` (string, required) — Plain text content - `type`: `uri` (UriArtifact) - `value` (string, required) — URI to download from ### McpServerConfig Configuration for the MCP server. - `url` (string, required) — The URL of the MCP server to connect to. - `name` (string, optional, nullable, default: mcp) — A name for the MCP server configuration. - `authorization_token` (string, optional, nullable) — The authorization token to use when connecting to the MCP server. - `tool_configuration` (McpServerToolConfig, optional) — Configuration for tool filtering from the MCP server ### MountEntry Declares a file or folder to mount into the sandbox. Part of the chat request body (``mounts`` field). Declares *what* content should be visible inside the sandbox and *where* it should appear. Content is located one of two ways: - ``uri`` (preferred): a content origin (``s3://...``, ``https://...``, ``data:...`` or a local disk path). The mount is lazy — content is fetched only when the backing folder is absent or empty. - ``namespace``/``scope``/``path``: a reference into a registered filesystem namespace, resolved to the exact host file/folder. - `namespace` (string, required) — Registered namespace name (e.g. 'session', 'skills', or a custom namespace). - `scope` (string, required) — Opaque scope id within the namespace (e.g. thread-id). - `path` (string, required) — Relative path within the scope. - `target` (string, required) — Absolute container path where the content should be visible. - `mode` (enum, optional, default: rw) — Access mode. - Allowed values: `rw`, `ro` - `etag` (string, optional, nullable) — Optional content checksum. - `uri` (string, optional, nullable) — Content origin: s3://, https://, data: or a local disk path. When set, the mount is lazy — content is fetched only if the backing folder is absent or empty. ### ResponseFormat Deprecated response format model. Use JsonObjectFormat. - `type` (enum, optional) — Response format type - Allowed values: `text`, `json_schema` - `json_schema` (map from string to any, optional, nullable) — JSON schema definition when type is 'json_schema' ### CompletionMetadata CompletionMetadata schema. - `user_id` (string, optional, nullable) — Opaque user identifier for request attribution. ### MessageContentItems ### Container Container handle for request reuse. - `id` (string, required) — Container identifier. - `expires_at` (datetime, required) — Container expiration timestamp. ### RefusalStopDetails Additional metadata when generation stops due to refusal. - `type` ("refusal", required) — Stop-details discriminator. - `category` (enum, optional, nullable) — Optional refusal category. - Allowed values: `cyber`, `bio` - `explanation` (string, optional, nullable) — Optional human-readable refusal explanation. ### Usage Token usage statistics. - `cache_creation` (CacheCreation, optional, nullable) — Cache creation details, when present. - `cache_creation_input_tokens` (integer, optional, nullable) — Number of input tokens written to cache. - `cache_read_input_tokens` (integer, optional, nullable) — Number of input tokens read from cache. - `inference_geo` (string, optional, nullable) — Inference region code, when available. - `input_tokens` (integer, optional, nullable) — Input token count for this response. - `output_tokens` (integer, optional, nullable) — Output token count for this response. - `output_tokens_details` (OutputTokensDetails, optional, nullable) — Breakdown of output tokens by category. - `server_tool_use` (ServerToolUsage, optional, nullable) — Usage counters for server-side tool calls. - `service_tier` (enum, optional, nullable) — Service tier used for this response. - Allowed values: `standard`, `priority`, `batch` ### MessageInputContent The message content ### Citations Configuration for citation generation in AI responses. - `enabled` (boolean, optional, default: false) — Enable citations in responses - `known_citations` (list of ZylonCitation, optional, nullable) — List of known citations to use in the response ### PromptConfig Controls which platform-level prompt features are injected. These flags represent optional AI features adding internal instructions to the system prompt. All flags default to ``False`` — opt-in explicitly. - `tools` (boolean, optional, default: false) — Enable per-tool instruction injection for all available tools. - `citations` (boolean, optional, default: false) — Enable citation formatting guidelines injection. - `thinking` (boolean, optional, default: false) — Enable thinking/reasoning guidelines when thinking is enabled. - `code_execution` (boolean, optional, default: false) — Enable code execution environment instructions (filesystem layout, available paths) when any code execution tool is present. - `skills` (boolean, optional, default: false) — Enable skill management instructions (when to load/unload skills, workflow guidance) when any skill management tool is present. ### ToolSpecBodyContextItems - `type`: `file` (FileArtifact) - `value` (string, required) — Base64 encoded file content - `type`: `ingested_artifact` (IngestedArtifact) - `context_filter` (ContextFilter, required) — Already processed ContextFilter - `type`: `skill` (SkillArtifact) - `skill_filter` (SkillFilter, required) — Skill filter declaring the collection and optional skill_or_version_ids whitelist. - `type`: `sql_database` (SqlDatabaseArtifact) - `connection_string` (string, required) — SQL database connection string - `description` (string, optional, default: ) — Optional description of the database - `enable_functions` (boolean, optional, default: true) — Whether to include functions in the inspection - `enable_procedures` (boolean, optional, default: true) — Whether to include stored procedures in the inspection - `enable_tables` (boolean, optional, default: true) — Whether to include tables in the inspection - `enable_views` (boolean, optional, default: true) — Whether to include views in the inspection - `schemas` (list of string, optional, nullable) — List of specific schemas to include, if None includes all non-system schemas - `ssl` (boolean, optional, default: false) — Whether to use SSL for the database connection - `type`: `text` (TextArtifact) - `value` (string, required) — Plain text content - `type`: `uri` (UriArtifact) - `value` (string, required) — URI to download from ### JsonObjectFormat Structured JSON object format compatible with Anthropic output_config.format. - `type` ("json_schema", required) — Output format type. Always "json_schema". - `schema` (map from string to any, required) — JSON schema used to constrain the model output. ### ContextFilter Filter by collection, artifacts and metadata in the ingested context. The main filter is the collection the context is part of. All artifacts ids are ensured to be part of the context. If any of the ids is not usable in the context (i.e. doesn't exist), the related task will fail. The metadata filter will look for all context matching the metadata, if any, and add it to the context. The filter is a dictionary of key-value pairs. The key is the metadata key, and the value is the metadata value. If both artifacts and metadata filters are provided, the result will be the intersection of the two filters. - `collection` (string, optional, default: pgpt_collection) — The name of the collection to filter on. - `artifacts` (list of string, optional, nullable) — Artifacts ids to filter on. - `metadata_filter` (list of map from string to any, optional, nullable) — Metadata filter to apply on the context. ### SkillFilter Collection-scoped filter used to resolve active skills and versions. - `collection` (string, required) — Tenant collection boundary used to recover skills. - `skill_or_version_ids` (list of string, optional, nullable) — Optional whitelist of identifiers inside collection. Each item may be a skill id (resolved to latest version) or a skill version id. ### McpServerToolConfig Configuration for tool filtering from the MCP server. - `enabled` (boolean, optional, default: true) — Enable tool filtering for the MCP server. - `allowed_tools` (list of string, optional, nullable) — List of enabled tools to filter from the MCP server. ### TextBlock Plain-text content block. - `type` ("text", required) — type field. - `start_timestamp` (datetime, optional, nullable) — start timestamp field. - `stop_timestamp` (datetime, optional, nullable) — stop timestamp field. - `_meta` (map from string to any, optional) — meta field. - `cache_control` (TextBlockCacheControl, optional, nullable) — cache control field. - `text` (string, optional, default: ) — Text payload for this block. - `citations` (list of ZylonCitation, optional, nullable, default: []) — citations field. ### ImageBlock Anthropic-compatible image content block. - `type` ("image", required) — type field. - `source` (ImageBlockSource, required) — Anthropic image source payload - `start_timestamp` (datetime, optional, nullable) — start timestamp field. - `stop_timestamp` (datetime, optional, nullable) — stop timestamp field. - `_meta` (map from string to any, optional) — meta field. - `cache_control` (ImageBlockCacheControl, optional, nullable) — cache control field. ### AudioBlock Anthropic-compatible audio content block. - `type` ("audio", required) — type field. - `source` (AudioBlockSource, required) — Audio source payload - `start_timestamp` (datetime, optional, nullable) — start timestamp field. - `stop_timestamp` (datetime, optional, nullable) — stop timestamp field. - `_meta` (map from string to any, optional) — meta field. - `cache_control` (AudioBlockCacheControl, optional, nullable) — cache control field. ### BinaryBlock Arbitrary binary payload (PDF, ZIP, …) encoded as base64. - `type` ("binary", required) — type field. - `source` (BinaryBlockSource, required) — Binary source payload - `start_timestamp` (datetime, optional, nullable) — start timestamp field. - `stop_timestamp` (datetime, optional, nullable) — stop timestamp field. - `_meta` (map from string to any, optional) — meta field. - `filename` (string, optional, nullable) — filename field. ### LocalResourceBlock Reference to a local file produced by code execution. - `type` ("local_resource", required) — type field. - `file_path` (string, required) — Absolute path to the file inside the execution environment - `name` (string, required) — Human-readable file name (stem, without extension) - `mime_type` (string, required) — MIME type of the file - `start_timestamp` (datetime, optional, nullable) — start timestamp field. - `stop_timestamp` (datetime, optional, nullable) — stop timestamp field. - `_meta` (map from string to any, optional) — meta field. - `file_id` (string, optional, nullable) — Base64url-encoded storage file ID used to download the file via the files API ### ResourceLinkBlock Reference to an external resource by URI (not embedded). - `type` ("resource_link", required) — type field. - `uri` (string, required) — URI of the external resource - `name` (string, required) — Human-readable resource name - `start_timestamp` (datetime, optional, nullable) — start timestamp field. - `stop_timestamp` (datetime, optional, nullable) — stop timestamp field. - `_meta` (map from string to any, optional) — meta field. - `description` (string, optional, nullable) — description field. - `mime_type` (string, optional, nullable) — mime type field. ### ResourceBlock Embedded resource with metadata. - `type` ("resource", required) — type field. - `resource` (Resource, required) — Embedded resource metadata - `start_timestamp` (datetime, optional, nullable) — start timestamp field. - `stop_timestamp` (datetime, optional, nullable) — stop timestamp field. - `_meta` (map from string to any, optional) — meta field. ### SourceBlock Document chunks surfaced as RAG context attribution. - `type` ("source", required) — type field. - `sources` (list of SourceBlockSourcesItems, required) — Document chunks used as context for this response - `start_timestamp` (datetime, optional, nullable) — start timestamp field. - `stop_timestamp` (datetime, optional, nullable) — stop timestamp field. - `_meta` (map from string to any, optional) — meta field. ### ThinkingBlock Extended thinking block containing the model's reasoning process. - `type` ("thinking", required) — type field. - `signature` (string, required) — Anthropic reasoning signature required for extended thinking compatibility - `start_timestamp` (datetime, optional, nullable) — start timestamp field. - `stop_timestamp` (datetime, optional, nullable) — stop timestamp field. - `_meta` (map from string to any, optional) — meta field. - `cache_control` (ThinkingBlockCacheControl, optional, nullable) — cache control field. - `thinking` (string, optional, default: ) — Thinking payload - `citations` (list of ZylonCitation, optional, nullable, default: []) — citations field. ### RedactedThinkingBlock Redacted thinking block returned when thinking content is encrypted. - `type` ("redacted_thinking", required) — type field. - `data` (string, required) — Encrypted thinking payload - `start_timestamp` (datetime, optional, nullable) — start timestamp field. - `stop_timestamp` (datetime, optional, nullable) — stop timestamp field. - `_meta` (map from string to any, optional) — meta field. - `cache_control` (RedactedThinkingBlockCacheControl, optional, nullable) — cache control field. ### ToolUseBlock Represents a model-initiated tool call. - `type` ("tool_use", required) — type field. - `id` (string, required) — Unique identifier for this tool use - `name` (string, required) — Name of the tool being called - `input` (map from string to any, required) — Input payload for the tool call - `start_timestamp` (datetime, optional, nullable) — start timestamp field. - `stop_timestamp` (datetime, optional, nullable) — stop timestamp field. - `_meta` (map from string to any, optional) — meta field. - `cache_control` (ToolUseBlockCacheControl, optional, nullable) — cache control field. - `caller` (ToolUseBlockCaller, optional, nullable) — caller field. ### ServerToolUseBlock Represents a server-side (built-in) tool call initiated by the model. - `type` ("server_tool_use", required) — type field. - `id` (string, required) — Unique identifier for this server tool use - `name` (enum, required) — Name of the server tool being called - Allowed values: `web_search`, `web_fetch`, `code_execution`, `bash_code_execution`, `text_editor_code_execution`, `tool_search_tool_regex`, `tool_search_tool_bm25` - `input` (map from string to any, required) — Input payload for the server tool call - `start_timestamp` (datetime, optional, nullable) — start timestamp field. - `stop_timestamp` (datetime, optional, nullable) — stop timestamp field. - `_meta` (map from string to any, optional) — meta field. - `cache_control` (ServerToolUseBlockCacheControl, optional, nullable) — cache control field. - `caller` (ServerToolUseBlockCaller, optional, nullable) — caller field. ### ContainerUploadBlock References a file that was uploaded to an Anthropic container. - `type` ("container_upload", required) — type field. - `file_id` (string, required) — Container file identifier - `start_timestamp` (datetime, optional, nullable) — start timestamp field. - `stop_timestamp` (datetime, optional, nullable) — stop timestamp field. - `_meta` (map from string to any, optional) — meta field. - `cache_control` (ContainerUploadBlockCacheControl, optional, nullable) — cache control field. ### DocumentBlock Anthropic document block (used for document-grounded generation). - `type` ("document", required) — type field. - `source` (DocumentBlockSource, required) — Document source payload - `start_timestamp` (datetime, optional, nullable) — start timestamp field. - `stop_timestamp` (datetime, optional, nullable) — stop timestamp field. - `_meta` (map from string to any, optional) — meta field. - `cache_control` (DocumentBlockCacheControl, optional, nullable) — cache control field. - `title` (string, optional, nullable) — title field. - `context` (string, optional, nullable) — context field. - `citations` (list of ZylonCitation, optional, nullable) — citations field. ### SearchResultBlock Anthropic search result block. - `type` ("search_result", required) — type field. - `source` (string, required) — Search result source payload - `title` (string, required) — Search result title - `content` (list of TextBlock, required) — Search result content - `start_timestamp` (datetime, optional, nullable) — start timestamp field. - `stop_timestamp` (datetime, optional, nullable) — stop timestamp field. - `_meta` (map from string to any, optional) — meta field. - `cache_control` (SearchResultBlockCacheControl, optional, nullable) — cache control field. - `citations` (list of ZylonCitation, optional, nullable) — citations field. ### MidConvSystemBlock System instructions injected at a specific point mid-conversation. - `type` ("mid_conv_system", required) — type field. - `content` (list of TextBlock, required) — System instruction text blocks. - `start_timestamp` (datetime, optional, nullable) — start timestamp field. - `stop_timestamp` (datetime, optional, nullable) — stop timestamp field. - `_meta` (map from string to any, optional) — meta field. - `cache_control` (MidConvSystemBlockCacheControl, optional, nullable) — cache control field. ### TLDRBlock Condensed summary block. - `type` ("tldr", required) — type field. - `start_timestamp` (datetime, optional, nullable) — start timestamp field. - `stop_timestamp` (datetime, optional, nullable) — stop timestamp field. - `_meta` (map from string to any, optional) — meta field. - `content` (list of TldrBlockContentItems, optional) — content field. - `tldr_side` (enum, optional, default: left) — tldr side field. - Allowed values: `left`, `right` ### ToolResultBlock Result produced by a prior tool_use block. - `type` ("tool_result", required) — type field. - `tool_use_id` (string, required) — ID of the ToolUseBlock this result answers - `start_timestamp` (datetime, optional, nullable) — start timestamp field. - `stop_timestamp` (datetime, optional, nullable) — stop timestamp field. - `_meta` (map from string to any, optional) — meta field. - `cache_control` (ToolResultBlockCacheControl, optional, nullable) — cache control field. - `content` (ToolResultBlockContent, optional, default: ) — Tool execution result - `is_error` (boolean, optional, default: false) — Whether the tool result indicates an error. ### CacheCreation Token counts cached by ephemeral policy. - `ephemeral_1h_input_tokens` (integer, required) — Input tokens cached with 1-hour TTL. - `ephemeral_5m_input_tokens` (integer, required) — Input tokens cached with 5-minute TTL. ### OutputTokensDetails Breakdown of output tokens by category. - `reasoning_tokens` (integer, optional, nullable) — Output tokens spent on internal reasoning. ### ServerToolUsage Usage counters for server-side tools. - `web_fetch_requests` (integer, required) — Number of web fetch requests used. - `web_search_requests` (integer, required) — Number of web search requests used. ### ZylonCitation ZylonCitation represents a citation in the Zylon format. - `id` (string, optional, nullable) — Unique identifier for the citation - `index` (integer, optional, nullable) — Index of the citation in the document - `artifact_id` (string, optional, nullable) — Identifier of the artifact associated with the citation - `source_id` (string, optional, nullable) — Identifier of the source document from which the citation is derived ### TextBlockCacheControl cache control field. - `type`: `ephemeral` (CacheControlEphemeral) - `ttl` (enum, optional, default: 5m) — ttl field. - Allowed values: `5m`, `1h` ### ImageBlockSource Anthropic image source payload - `type`: `base64` (Base64ImageSource) - `data` (string, required) — Base64-encoded image bytes - `media_type` (enum, required) — media type field. - Allowed values: `image/jpeg`, `image/png`, `image/gif`, `image/webp` - `type`: `url` (URLSource) - `url` (string, required) — Publicly reachable URL ### ImageBlockCacheControl cache control field. - `type`: `ephemeral` (CacheControlEphemeral) - `ttl` (enum, optional, default: 5m) — ttl field. - Allowed values: `5m`, `1h` ### AudioBlockSource Audio source payload - `type`: `base64` (Base64AudioSource) - `data` (string, required) — Base64-encoded audio bytes - `media_type` (string, required) — Audio MIME type, e.g. 'audio/mpeg' - `type`: `url` (URLSource) - `url` (string, required) — Publicly reachable URL ### AudioBlockCacheControl cache control field. - `type`: `ephemeral` (CacheControlEphemeral) - `ttl` (enum, optional, default: 5m) — ttl field. - Allowed values: `5m`, `1h` ### BinaryBlockSource Binary source payload - `type`: `base64` (Base64BinarySource) - `data` (string, required) — Base64-encoded binary data - `media_type` (string, required) — MIME type, e.g. 'application/pdf' - `type`: `url` (url) ### Resource Resource schema. - `uri` (string, required) — uri field. - `name` (string, required) — name field. - `description` (string, optional, nullable) — description field. - `mime_type` (string, optional, nullable) — mime type field. ### SourceBlockSourcesItems ### ThinkingBlockCacheControl cache control field. - `type`: `ephemeral` (CacheControlEphemeral) - `ttl` (enum, optional, default: 5m) — ttl field. - Allowed values: `5m`, `1h` ### RedactedThinkingBlockCacheControl cache control field. - `type`: `ephemeral` (CacheControlEphemeral) - `ttl` (enum, optional, default: 5m) — ttl field. - Allowed values: `5m`, `1h` ### ToolUseBlockCacheControl cache control field. - `type`: `ephemeral` (CacheControlEphemeral) - `ttl` (enum, optional, default: 5m) — ttl field. - Allowed values: `5m`, `1h` ### ToolUseBlockCaller caller field. - `type`: `code_execution_20250825` (ServerToolCaller) - `tool_id` (string, required) — Server tool identifier. - `type`: `code_execution_20260120` (ServerToolCaller20260120) - `tool_id` (string, required) — Server tool identifier. - `type`: `direct` (DirectCaller) ### ServerToolUseBlockCacheControl cache control field. - `type`: `ephemeral` (CacheControlEphemeral) - `ttl` (enum, optional, default: 5m) — ttl field. - Allowed values: `5m`, `1h` ### ServerToolUseBlockCaller caller field. - `type`: `code_execution_20250825` (ServerToolCaller) - `tool_id` (string, required) — Server tool identifier. - `type`: `code_execution_20260120` (ServerToolCaller20260120) - `tool_id` (string, required) — Server tool identifier. - `type`: `direct` (DirectCaller) ### ContainerUploadBlockCacheControl cache control field. - `type`: `ephemeral` (CacheControlEphemeral) - `ttl` (enum, optional, default: 5m) — ttl field. - Allowed values: `5m`, `1h` ### DocumentBlockSource Document source payload - `type`: `base64` (Base64Source) - `data` (string, required) — data field. - `media_type` (string, required) — media type field. - `type`: `content` (content) - `type`: `text` (PlainTextSource) - `data` (string, required) — data field. - `media_type` ("text/plain", required) — media type field. - `type`: `url` (URLDocumentSource) - `url` (string, required) — url field. ### DocumentBlockCacheControl cache control field. - `type`: `ephemeral` (CacheControlEphemeral) - `ttl` (enum, optional, default: 5m) — ttl field. - Allowed values: `5m`, `1h` ### SearchResultBlockCacheControl cache control field. - `type`: `ephemeral` (CacheControlEphemeral) - `ttl` (enum, optional, default: 5m) — ttl field. - Allowed values: `5m`, `1h` ### MidConvSystemBlockCacheControl cache control field. - `type`: `ephemeral` (CacheControlEphemeral) - `ttl` (enum, optional, default: 5m) — ttl field. - Allowed values: `5m`, `1h` ### TldrBlockContentItems ### ToolResultBlockCacheControl cache control field. - `type`: `ephemeral` (CacheControlEphemeral) - `ttl` (enum, optional, default: 5m) — ttl field. - Allowed values: `5m`, `1h` ### ToolResultBlockContent Tool execution result ### Chunk Represents a chunk of text content from an ingested document. - `object` ("context.chunk", required) — Object type identifier, always 'context.chunk' for chunk responses - `score` (double, required) — Relevance score indicating how well this chunk matches the query (0.0 to 1.0, higher is better) - `document` (IngestedDoc, required) — Reference to the parent document containing metadata and ingestion information - `text` (string, required) — The actual text content of the chunk extracted from the document - `id` (string, optional, nullable) — Unique identifier for the chunk within the document - `content_type` (string, optional, default: text/plain) — MIME type indicating the format of the chunk content - `previous_texts` (list of string, optional, nullable) — List of text chunks that appear before this chunk in the document, providing preceding context - `next_texts` (list of string, optional, nullable) — List of text chunks that appear after this chunk in the document, providing following context - `metadata` (map from string to any, optional, nullable) — Additional metadata about the chunk including positioning information and document properties ### Website Represents a website URL source. - `id` (string, required) — Unique identifier for the website source - `object` ("context.website", required) — Object type identifier, always 'context.website' for website sources - `url` (string, required) — The URL of the website - `favicon_url` (string, optional, nullable) — The URL of the website's favicon - `title` (string, optional, nullable) — The title of the website or webpage - `description` (string, optional, nullable) — A brief description or summary of the website content - `metadata` (map from string to any, optional, nullable) — Additional metadata about the website source - `content_type` (string, optional, nullable) — MIME type indicating the format of the website content - `content` (string, optional, nullable) — The actual text content extracted from the website ### IngestedDoc Represents a document that has been ingested into the system. - `artifact` (string, required) — Unique identifier for the ingested document artifact. - `object` ("ingest.document", optional, default: ingest.document) — Type of the object, indicating this is an ingested document. - `doc_metadata` (map from string to any, optional, nullable) — Metadata associated with the ingested document, such as title, author, and other ## Examples ### Standard text response **Request** ```json { "model": "default", "messages": [ { "role": "user", "content": "How do you fry an egg? Choose the best method." } ], "max_tokens": 1000, "system": [ { "text": "You are a helpful cooking assistant. Provide clear, step-by-step instructions.", "citations": { "enabled": true } } ], "tools": [ { "name": "egg_fryer", "description": "A tool to fry eggs with precise temperature control", "input_schema": { "properties": { "temperature": { "description": "Temperature in degrees Celsius", "type": "number" }, "time": { "description": "Time in minutes to fry the egg", "type": "number" } }, "required": [ "temperature", "time" ], "type": "object" } } ], "thinking": { "enabled": false }, "tool_choice": { "type": "auto", "disable_parallel_tool_use": false }, "stream": false, "response_format": { "type": "text" }, "temperature": 0.7 } ``` **Response** ```json { "id": "msg_12345", "type": "message", "role": "assistant", "content": [ { "start_timestamp": "2025-07-10T09:11:16.003615Z", "stop_timestamp": "2025-07-10T09:11:28.048942Z", "text": "Based on the analysis, I found 3 potential security issues...", "type": "text" } ], "model": "private-gpt", "stop_reason": "end_turn", "usage": { "input_tokens": 432, "output_tokens": 89 } } ``` **SDK Code** ```python Standard text response import requests url = "https://api.example.com/v1/messages" payload = { "model": "default", "messages": [ { "role": "user", "content": "How do you fry an egg? Choose the best method." } ], "max_tokens": 1000, "system": [ { "text": "You are a helpful cooking assistant. Provide clear, step-by-step instructions.", "citations": { "enabled": True } } ], "tools": [ { "name": "egg_fryer", "description": "A tool to fry eggs with precise temperature control", "input_schema": { "properties": { "temperature": { "description": "Temperature in degrees Celsius", "type": "number" }, "time": { "description": "Time in minutes to fry the egg", "type": "number" } }, "required": ["temperature", "time"], "type": "object" } } ], "thinking": { "enabled": False }, "tool_choice": { "type": "auto", "disable_parallel_tool_use": False }, "stream": False, "response_format": { "type": "text" }, "temperature": 0.7 } headers = {"Content-Type": "application/json"} response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` ```javascript Standard text response const url = 'https://api.example.com/v1/messages'; const options = { method: 'POST', headers: {'Content-Type': 'application/json'}, body: '{"model":"default","messages":[{"role":"user","content":"How do you fry an egg? Choose the best method."}],"max_tokens":1000,"system":[{"text":"You are a helpful cooking assistant. Provide clear, step-by-step instructions.","citations":{"enabled":true}}],"tools":[{"name":"egg_fryer","description":"A tool to fry eggs with precise temperature control","input_schema":{"properties":{"temperature":{"description":"Temperature in degrees Celsius","type":"number"},"time":{"description":"Time in minutes to fry the egg","type":"number"}},"required":["temperature","time"],"type":"object"}}],"thinking":{"enabled":false},"tool_choice":{"type":"auto","disable_parallel_tool_use":false},"stream":false,"response_format":{"type":"text"},"temperature":0.7}' }; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go Standard text response package main import ( "fmt" "strings" "net/http" "io" ) func main() { url := "https://api.example.com/v1/messages" payload := strings.NewReader("{\n \"model\": \"default\",\n \"messages\": [\n {\n \"role\": \"user\",\n \"content\": \"How do you fry an egg? Choose the best method.\"\n }\n ],\n \"max_tokens\": 1000,\n \"system\": [\n {\n \"text\": \"You are a helpful cooking assistant. Provide clear, step-by-step instructions.\",\n \"citations\": {\n \"enabled\": true\n }\n }\n ],\n \"tools\": [\n {\n \"name\": \"egg_fryer\",\n \"description\": \"A tool to fry eggs with precise temperature control\",\n \"input_schema\": {\n \"properties\": {\n \"temperature\": {\n \"description\": \"Temperature in degrees Celsius\",\n \"type\": \"number\"\n },\n \"time\": {\n \"description\": \"Time in minutes to fry the egg\",\n \"type\": \"number\"\n }\n },\n \"required\": [\n \"temperature\",\n \"time\"\n ],\n \"type\": \"object\"\n }\n }\n ],\n \"thinking\": {\n \"enabled\": false\n },\n \"tool_choice\": {\n \"type\": \"auto\",\n \"disable_parallel_tool_use\": false\n },\n \"stream\": false,\n \"response_format\": {\n \"type\": \"text\"\n },\n \"temperature\": 0.7\n}") req, _ := http.NewRequest("POST", url, payload) req.Header.Add("Content-Type", "application/json") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby Standard text response require 'uri' require 'net/http' url = URI("https://api.example.com/v1/messages") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Post.new(url) request["Content-Type"] = 'application/json' request.body = "{\n \"model\": \"default\",\n \"messages\": [\n {\n \"role\": \"user\",\n \"content\": \"How do you fry an egg? Choose the best method.\"\n }\n ],\n \"max_tokens\": 1000,\n \"system\": [\n {\n \"text\": \"You are a helpful cooking assistant. Provide clear, step-by-step instructions.\",\n \"citations\": {\n \"enabled\": true\n }\n }\n ],\n \"tools\": [\n {\n \"name\": \"egg_fryer\",\n \"description\": \"A tool to fry eggs with precise temperature control\",\n \"input_schema\": {\n \"properties\": {\n \"temperature\": {\n \"description\": \"Temperature in degrees Celsius\",\n \"type\": \"number\"\n },\n \"time\": {\n \"description\": \"Time in minutes to fry the egg\",\n \"type\": \"number\"\n }\n },\n \"required\": [\n \"temperature\",\n \"time\"\n ],\n \"type\": \"object\"\n }\n }\n ],\n \"thinking\": {\n \"enabled\": false\n },\n \"tool_choice\": {\n \"type\": \"auto\",\n \"disable_parallel_tool_use\": false\n },\n \"stream\": false,\n \"response_format\": {\n \"type\": \"text\"\n },\n \"temperature\": 0.7\n}" response = http.request(request) puts response.read_body ``` ```java Standard text response import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.post("https://api.example.com/v1/messages") .header("Content-Type", "application/json") .body("{\n \"model\": \"default\",\n \"messages\": [\n {\n \"role\": \"user\",\n \"content\": \"How do you fry an egg? Choose the best method.\"\n }\n ],\n \"max_tokens\": 1000,\n \"system\": [\n {\n \"text\": \"You are a helpful cooking assistant. Provide clear, step-by-step instructions.\",\n \"citations\": {\n \"enabled\": true\n }\n }\n ],\n \"tools\": [\n {\n \"name\": \"egg_fryer\",\n \"description\": \"A tool to fry eggs with precise temperature control\",\n \"input_schema\": {\n \"properties\": {\n \"temperature\": {\n \"description\": \"Temperature in degrees Celsius\",\n \"type\": \"number\"\n },\n \"time\": {\n \"description\": \"Time in minutes to fry the egg\",\n \"type\": \"number\"\n }\n },\n \"required\": [\n \"temperature\",\n \"time\"\n ],\n \"type\": \"object\"\n }\n }\n ],\n \"thinking\": {\n \"enabled\": false\n },\n \"tool_choice\": {\n \"type\": \"auto\",\n \"disable_parallel_tool_use\": false\n },\n \"stream\": false,\n \"response_format\": {\n \"type\": \"text\"\n },\n \"temperature\": 0.7\n}") .asString(); ``` ```php Standard text response request('POST', 'https://api.example.com/v1/messages', [ 'body' => '{ "model": "default", "messages": [ { "role": "user", "content": "How do you fry an egg? Choose the best method." } ], "max_tokens": 1000, "system": [ { "text": "You are a helpful cooking assistant. Provide clear, step-by-step instructions.", "citations": { "enabled": true } } ], "tools": [ { "name": "egg_fryer", "description": "A tool to fry eggs with precise temperature control", "input_schema": { "properties": { "temperature": { "description": "Temperature in degrees Celsius", "type": "number" }, "time": { "description": "Time in minutes to fry the egg", "type": "number" } }, "required": [ "temperature", "time" ], "type": "object" } } ], "thinking": { "enabled": false }, "tool_choice": { "type": "auto", "disable_parallel_tool_use": false }, "stream": false, "response_format": { "type": "text" }, "temperature": 0.7 }', 'headers' => [ 'Content-Type' => 'application/json', ], ]); echo $response->getBody(); ``` ```csharp Standard text response using RestSharp; var client = new RestClient("https://api.example.com/v1/messages"); var request = new RestRequest(Method.POST); request.AddHeader("Content-Type", "application/json"); request.AddParameter("application/json", "{\n \"model\": \"default\",\n \"messages\": [\n {\n \"role\": \"user\",\n \"content\": \"How do you fry an egg? Choose the best method.\"\n }\n ],\n \"max_tokens\": 1000,\n \"system\": [\n {\n \"text\": \"You are a helpful cooking assistant. Provide clear, step-by-step instructions.\",\n \"citations\": {\n \"enabled\": true\n }\n }\n ],\n \"tools\": [\n {\n \"name\": \"egg_fryer\",\n \"description\": \"A tool to fry eggs with precise temperature control\",\n \"input_schema\": {\n \"properties\": {\n \"temperature\": {\n \"description\": \"Temperature in degrees Celsius\",\n \"type\": \"number\"\n },\n \"time\": {\n \"description\": \"Time in minutes to fry the egg\",\n \"type\": \"number\"\n }\n },\n \"required\": [\n \"temperature\",\n \"time\"\n ],\n \"type\": \"object\"\n }\n }\n ],\n \"thinking\": {\n \"enabled\": false\n },\n \"tool_choice\": {\n \"type\": \"auto\",\n \"disable_parallel_tool_use\": false\n },\n \"stream\": false,\n \"response_format\": {\n \"type\": \"text\"\n },\n \"temperature\": 0.7\n}", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` ```swift Standard text response import Foundation let headers = ["Content-Type": "application/json"] let parameters = [ "model": "default", "messages": [ [ "role": "user", "content": "How do you fry an egg? Choose the best method." ] ], "max_tokens": 1000, "system": [ [ "text": "You are a helpful cooking assistant. Provide clear, step-by-step instructions.", "citations": ["enabled": true] ] ], "tools": [ [ "name": "egg_fryer", "description": "A tool to fry eggs with precise temperature control", "input_schema": [ "properties": [ "temperature": [ "description": "Temperature in degrees Celsius", "type": "number" ], "time": [ "description": "Time in minutes to fry the egg", "type": "number" ] ], "required": ["temperature", "time"], "type": "object" ] ] ], "thinking": ["enabled": false], "tool_choice": [ "type": "auto", "disable_parallel_tool_use": false ], "stream": false, "response_format": ["type": "text"], "temperature": 0.7 ] as [String : Any] let postData = JSONSerialization.data(withJSONObject: parameters, options: []) let request = NSMutableURLRequest(url: NSURL(string: "https://api.example.com/v1/messages")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "POST" request.allHTTPHeaderFields = headers request.httpBody = postData as Data let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ``` ### Response with tool usage **Request** ```json { "model": "default", "messages": [ { "role": "user", "content": "How do you fry an egg? Choose the best method." } ], "max_tokens": 1000, "system": [ { "text": "You are a helpful cooking assistant. Provide clear, step-by-step instructions.", "citations": { "enabled": true } } ], "tools": [ { "name": "egg_fryer", "description": "A tool to fry eggs with precise temperature control", "input_schema": { "properties": { "temperature": { "description": "Temperature in degrees Celsius", "type": "number" }, "time": { "description": "Time in minutes to fry the egg", "type": "number" } }, "required": [ "temperature", "time" ], "type": "object" } } ], "thinking": { "enabled": false }, "tool_choice": { "type": "auto", "disable_parallel_tool_use": false }, "stream": false, "response_format": { "type": "text" }, "temperature": 0.7 } ``` **Response** ```json { "id": "msg_67890", "type": "message", "role": "assistant", "content": [ { "text": "I'll help you with precise temperature control.", "type": "text" }, { "id": "scan_001", "input": { "directory": "/src", "scan_type": "vulnerability" }, "name": "security_scanner", "type": "tool_use" } ], "model": "private-gpt", "stop_reason": "tool_use", "usage": { "input_tokens": 156, "output_tokens": 234 } } ``` **SDK Code** ```python Response with tool usage import requests url = "https://api.example.com/v1/messages" payload = { "model": "default", "messages": [ { "role": "user", "content": "How do you fry an egg? Choose the best method." } ], "max_tokens": 1000, "system": [ { "text": "You are a helpful cooking assistant. Provide clear, step-by-step instructions.", "citations": { "enabled": True } } ], "tools": [ { "name": "egg_fryer", "description": "A tool to fry eggs with precise temperature control", "input_schema": { "properties": { "temperature": { "description": "Temperature in degrees Celsius", "type": "number" }, "time": { "description": "Time in minutes to fry the egg", "type": "number" } }, "required": ["temperature", "time"], "type": "object" } } ], "thinking": { "enabled": False }, "tool_choice": { "type": "auto", "disable_parallel_tool_use": False }, "stream": False, "response_format": { "type": "text" }, "temperature": 0.7 } headers = {"Content-Type": "application/json"} response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` ```javascript Response with tool usage const url = 'https://api.example.com/v1/messages'; const options = { method: 'POST', headers: {'Content-Type': 'application/json'}, body: '{"model":"default","messages":[{"role":"user","content":"How do you fry an egg? Choose the best method."}],"max_tokens":1000,"system":[{"text":"You are a helpful cooking assistant. Provide clear, step-by-step instructions.","citations":{"enabled":true}}],"tools":[{"name":"egg_fryer","description":"A tool to fry eggs with precise temperature control","input_schema":{"properties":{"temperature":{"description":"Temperature in degrees Celsius","type":"number"},"time":{"description":"Time in minutes to fry the egg","type":"number"}},"required":["temperature","time"],"type":"object"}}],"thinking":{"enabled":false},"tool_choice":{"type":"auto","disable_parallel_tool_use":false},"stream":false,"response_format":{"type":"text"},"temperature":0.7}' }; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go Response with tool usage package main import ( "fmt" "strings" "net/http" "io" ) func main() { url := "https://api.example.com/v1/messages" payload := strings.NewReader("{\n \"model\": \"default\",\n \"messages\": [\n {\n \"role\": \"user\",\n \"content\": \"How do you fry an egg? Choose the best method.\"\n }\n ],\n \"max_tokens\": 1000,\n \"system\": [\n {\n \"text\": \"You are a helpful cooking assistant. Provide clear, step-by-step instructions.\",\n \"citations\": {\n \"enabled\": true\n }\n }\n ],\n \"tools\": [\n {\n \"name\": \"egg_fryer\",\n \"description\": \"A tool to fry eggs with precise temperature control\",\n \"input_schema\": {\n \"properties\": {\n \"temperature\": {\n \"description\": \"Temperature in degrees Celsius\",\n \"type\": \"number\"\n },\n \"time\": {\n \"description\": \"Time in minutes to fry the egg\",\n \"type\": \"number\"\n }\n },\n \"required\": [\n \"temperature\",\n \"time\"\n ],\n \"type\": \"object\"\n }\n }\n ],\n \"thinking\": {\n \"enabled\": false\n },\n \"tool_choice\": {\n \"type\": \"auto\",\n \"disable_parallel_tool_use\": false\n },\n \"stream\": false,\n \"response_format\": {\n \"type\": \"text\"\n },\n \"temperature\": 0.7\n}") req, _ := http.NewRequest("POST", url, payload) req.Header.Add("Content-Type", "application/json") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby Response with tool usage require 'uri' require 'net/http' url = URI("https://api.example.com/v1/messages") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Post.new(url) request["Content-Type"] = 'application/json' request.body = "{\n \"model\": \"default\",\n \"messages\": [\n {\n \"role\": \"user\",\n \"content\": \"How do you fry an egg? Choose the best method.\"\n }\n ],\n \"max_tokens\": 1000,\n \"system\": [\n {\n \"text\": \"You are a helpful cooking assistant. Provide clear, step-by-step instructions.\",\n \"citations\": {\n \"enabled\": true\n }\n }\n ],\n \"tools\": [\n {\n \"name\": \"egg_fryer\",\n \"description\": \"A tool to fry eggs with precise temperature control\",\n \"input_schema\": {\n \"properties\": {\n \"temperature\": {\n \"description\": \"Temperature in degrees Celsius\",\n \"type\": \"number\"\n },\n \"time\": {\n \"description\": \"Time in minutes to fry the egg\",\n \"type\": \"number\"\n }\n },\n \"required\": [\n \"temperature\",\n \"time\"\n ],\n \"type\": \"object\"\n }\n }\n ],\n \"thinking\": {\n \"enabled\": false\n },\n \"tool_choice\": {\n \"type\": \"auto\",\n \"disable_parallel_tool_use\": false\n },\n \"stream\": false,\n \"response_format\": {\n \"type\": \"text\"\n },\n \"temperature\": 0.7\n}" response = http.request(request) puts response.read_body ``` ```java Response with tool usage import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.post("https://api.example.com/v1/messages") .header("Content-Type", "application/json") .body("{\n \"model\": \"default\",\n \"messages\": [\n {\n \"role\": \"user\",\n \"content\": \"How do you fry an egg? Choose the best method.\"\n }\n ],\n \"max_tokens\": 1000,\n \"system\": [\n {\n \"text\": \"You are a helpful cooking assistant. Provide clear, step-by-step instructions.\",\n \"citations\": {\n \"enabled\": true\n }\n }\n ],\n \"tools\": [\n {\n \"name\": \"egg_fryer\",\n \"description\": \"A tool to fry eggs with precise temperature control\",\n \"input_schema\": {\n \"properties\": {\n \"temperature\": {\n \"description\": \"Temperature in degrees Celsius\",\n \"type\": \"number\"\n },\n \"time\": {\n \"description\": \"Time in minutes to fry the egg\",\n \"type\": \"number\"\n }\n },\n \"required\": [\n \"temperature\",\n \"time\"\n ],\n \"type\": \"object\"\n }\n }\n ],\n \"thinking\": {\n \"enabled\": false\n },\n \"tool_choice\": {\n \"type\": \"auto\",\n \"disable_parallel_tool_use\": false\n },\n \"stream\": false,\n \"response_format\": {\n \"type\": \"text\"\n },\n \"temperature\": 0.7\n}") .asString(); ``` ```php Response with tool usage request('POST', 'https://api.example.com/v1/messages', [ 'body' => '{ "model": "default", "messages": [ { "role": "user", "content": "How do you fry an egg? Choose the best method." } ], "max_tokens": 1000, "system": [ { "text": "You are a helpful cooking assistant. Provide clear, step-by-step instructions.", "citations": { "enabled": true } } ], "tools": [ { "name": "egg_fryer", "description": "A tool to fry eggs with precise temperature control", "input_schema": { "properties": { "temperature": { "description": "Temperature in degrees Celsius", "type": "number" }, "time": { "description": "Time in minutes to fry the egg", "type": "number" } }, "required": [ "temperature", "time" ], "type": "object" } } ], "thinking": { "enabled": false }, "tool_choice": { "type": "auto", "disable_parallel_tool_use": false }, "stream": false, "response_format": { "type": "text" }, "temperature": 0.7 }', 'headers' => [ 'Content-Type' => 'application/json', ], ]); echo $response->getBody(); ``` ```csharp Response with tool usage using RestSharp; var client = new RestClient("https://api.example.com/v1/messages"); var request = new RestRequest(Method.POST); request.AddHeader("Content-Type", "application/json"); request.AddParameter("application/json", "{\n \"model\": \"default\",\n \"messages\": [\n {\n \"role\": \"user\",\n \"content\": \"How do you fry an egg? Choose the best method.\"\n }\n ],\n \"max_tokens\": 1000,\n \"system\": [\n {\n \"text\": \"You are a helpful cooking assistant. Provide clear, step-by-step instructions.\",\n \"citations\": {\n \"enabled\": true\n }\n }\n ],\n \"tools\": [\n {\n \"name\": \"egg_fryer\",\n \"description\": \"A tool to fry eggs with precise temperature control\",\n \"input_schema\": {\n \"properties\": {\n \"temperature\": {\n \"description\": \"Temperature in degrees Celsius\",\n \"type\": \"number\"\n },\n \"time\": {\n \"description\": \"Time in minutes to fry the egg\",\n \"type\": \"number\"\n }\n },\n \"required\": [\n \"temperature\",\n \"time\"\n ],\n \"type\": \"object\"\n }\n }\n ],\n \"thinking\": {\n \"enabled\": false\n },\n \"tool_choice\": {\n \"type\": \"auto\",\n \"disable_parallel_tool_use\": false\n },\n \"stream\": false,\n \"response_format\": {\n \"type\": \"text\"\n },\n \"temperature\": 0.7\n}", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` ```swift Response with tool usage import Foundation let headers = ["Content-Type": "application/json"] let parameters = [ "model": "default", "messages": [ [ "role": "user", "content": "How do you fry an egg? Choose the best method." ] ], "max_tokens": 1000, "system": [ [ "text": "You are a helpful cooking assistant. Provide clear, step-by-step instructions.", "citations": ["enabled": true] ] ], "tools": [ [ "name": "egg_fryer", "description": "A tool to fry eggs with precise temperature control", "input_schema": [ "properties": [ "temperature": [ "description": "Temperature in degrees Celsius", "type": "number" ], "time": [ "description": "Time in minutes to fry the egg", "type": "number" ] ], "required": ["temperature", "time"], "type": "object" ] ] ], "thinking": ["enabled": false], "tool_choice": [ "type": "auto", "disable_parallel_tool_use": false ], "stream": false, "response_format": ["type": "text"], "temperature": 0.7 ] as [String : Any] let postData = JSONSerialization.data(withJSONObject: parameters, options: []) let request = NSMutableURLRequest(url: NSURL(string: "https://api.example.com/v1/messages")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "POST" request.allHTTPHeaderFields = headers request.httpBody = postData as Data let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ``` ### Response with tool usage and result **Request** ```json { "model": "default", "messages": [ { "role": "user", "content": "How do you fry an egg? Choose the best method." } ], "max_tokens": 1000, "system": [ { "text": "You are a helpful cooking assistant. Provide clear, step-by-step instructions.", "citations": { "enabled": true } } ], "tools": [ { "name": "egg_fryer", "description": "A tool to fry eggs with precise temperature control", "input_schema": { "properties": { "temperature": { "description": "Temperature in degrees Celsius", "type": "number" }, "time": { "description": "Time in minutes to fry the egg", "type": "number" } }, "required": [ "temperature", "time" ], "type": "object" } } ], "thinking": { "enabled": false }, "tool_choice": { "type": "auto", "disable_parallel_tool_use": false }, "stream": false, "response_format": { "type": "text" }, "temperature": 0.7 } ``` **Response** ```json { "id": "msg_67890", "type": "message", "role": "assistant", "content": [ { "text": "I'll help you with precise temperature control.", "type": "text" }, { "id": "scan_001", "input": { "directory": "/src", "scan_type": "vulnerability" }, "name": "security_scanner", "type": "tool_use" }, { "content": [ { "start_timestamp": "2025-07-10T09:11:40.123456Z", "stop_timestamp": "2025-07-10T09:11:45.654321Z", "text": "Scan complete. Found 3 vulnerabilities in /src.", "type": "text" } ], "tool_use_id": "scan_001", "type": "tool_result" }, { "text": "Based on the scan results, you should address the vulnerabilities found in /src...", "type": "text" } ], "model": "private-gpt", "stop_reason": "end_turn", "usage": { "input_tokens": 156, "output_tokens": 324 } } ``` **SDK Code** ```python Response with tool usage and result import requests url = "https://api.example.com/v1/messages" payload = { "model": "default", "messages": [ { "role": "user", "content": "How do you fry an egg? Choose the best method." } ], "max_tokens": 1000, "system": [ { "text": "You are a helpful cooking assistant. Provide clear, step-by-step instructions.", "citations": { "enabled": True } } ], "tools": [ { "name": "egg_fryer", "description": "A tool to fry eggs with precise temperature control", "input_schema": { "properties": { "temperature": { "description": "Temperature in degrees Celsius", "type": "number" }, "time": { "description": "Time in minutes to fry the egg", "type": "number" } }, "required": ["temperature", "time"], "type": "object" } } ], "thinking": { "enabled": False }, "tool_choice": { "type": "auto", "disable_parallel_tool_use": False }, "stream": False, "response_format": { "type": "text" }, "temperature": 0.7 } headers = {"Content-Type": "application/json"} response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` ```javascript Response with tool usage and result const url = 'https://api.example.com/v1/messages'; const options = { method: 'POST', headers: {'Content-Type': 'application/json'}, body: '{"model":"default","messages":[{"role":"user","content":"How do you fry an egg? Choose the best method."}],"max_tokens":1000,"system":[{"text":"You are a helpful cooking assistant. Provide clear, step-by-step instructions.","citations":{"enabled":true}}],"tools":[{"name":"egg_fryer","description":"A tool to fry eggs with precise temperature control","input_schema":{"properties":{"temperature":{"description":"Temperature in degrees Celsius","type":"number"},"time":{"description":"Time in minutes to fry the egg","type":"number"}},"required":["temperature","time"],"type":"object"}}],"thinking":{"enabled":false},"tool_choice":{"type":"auto","disable_parallel_tool_use":false},"stream":false,"response_format":{"type":"text"},"temperature":0.7}' }; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go Response with tool usage and result package main import ( "fmt" "strings" "net/http" "io" ) func main() { url := "https://api.example.com/v1/messages" payload := strings.NewReader("{\n \"model\": \"default\",\n \"messages\": [\n {\n \"role\": \"user\",\n \"content\": \"How do you fry an egg? Choose the best method.\"\n }\n ],\n \"max_tokens\": 1000,\n \"system\": [\n {\n \"text\": \"You are a helpful cooking assistant. Provide clear, step-by-step instructions.\",\n \"citations\": {\n \"enabled\": true\n }\n }\n ],\n \"tools\": [\n {\n \"name\": \"egg_fryer\",\n \"description\": \"A tool to fry eggs with precise temperature control\",\n \"input_schema\": {\n \"properties\": {\n \"temperature\": {\n \"description\": \"Temperature in degrees Celsius\",\n \"type\": \"number\"\n },\n \"time\": {\n \"description\": \"Time in minutes to fry the egg\",\n \"type\": \"number\"\n }\n },\n \"required\": [\n \"temperature\",\n \"time\"\n ],\n \"type\": \"object\"\n }\n }\n ],\n \"thinking\": {\n \"enabled\": false\n },\n \"tool_choice\": {\n \"type\": \"auto\",\n \"disable_parallel_tool_use\": false\n },\n \"stream\": false,\n \"response_format\": {\n \"type\": \"text\"\n },\n \"temperature\": 0.7\n}") req, _ := http.NewRequest("POST", url, payload) req.Header.Add("Content-Type", "application/json") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby Response with tool usage and result require 'uri' require 'net/http' url = URI("https://api.example.com/v1/messages") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Post.new(url) request["Content-Type"] = 'application/json' request.body = "{\n \"model\": \"default\",\n \"messages\": [\n {\n \"role\": \"user\",\n \"content\": \"How do you fry an egg? Choose the best method.\"\n }\n ],\n \"max_tokens\": 1000,\n \"system\": [\n {\n \"text\": \"You are a helpful cooking assistant. Provide clear, step-by-step instructions.\",\n \"citations\": {\n \"enabled\": true\n }\n }\n ],\n \"tools\": [\n {\n \"name\": \"egg_fryer\",\n \"description\": \"A tool to fry eggs with precise temperature control\",\n \"input_schema\": {\n \"properties\": {\n \"temperature\": {\n \"description\": \"Temperature in degrees Celsius\",\n \"type\": \"number\"\n },\n \"time\": {\n \"description\": \"Time in minutes to fry the egg\",\n \"type\": \"number\"\n }\n },\n \"required\": [\n \"temperature\",\n \"time\"\n ],\n \"type\": \"object\"\n }\n }\n ],\n \"thinking\": {\n \"enabled\": false\n },\n \"tool_choice\": {\n \"type\": \"auto\",\n \"disable_parallel_tool_use\": false\n },\n \"stream\": false,\n \"response_format\": {\n \"type\": \"text\"\n },\n \"temperature\": 0.7\n}" response = http.request(request) puts response.read_body ``` ```java Response with tool usage and result import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.post("https://api.example.com/v1/messages") .header("Content-Type", "application/json") .body("{\n \"model\": \"default\",\n \"messages\": [\n {\n \"role\": \"user\",\n \"content\": \"How do you fry an egg? Choose the best method.\"\n }\n ],\n \"max_tokens\": 1000,\n \"system\": [\n {\n \"text\": \"You are a helpful cooking assistant. Provide clear, step-by-step instructions.\",\n \"citations\": {\n \"enabled\": true\n }\n }\n ],\n \"tools\": [\n {\n \"name\": \"egg_fryer\",\n \"description\": \"A tool to fry eggs with precise temperature control\",\n \"input_schema\": {\n \"properties\": {\n \"temperature\": {\n \"description\": \"Temperature in degrees Celsius\",\n \"type\": \"number\"\n },\n \"time\": {\n \"description\": \"Time in minutes to fry the egg\",\n \"type\": \"number\"\n }\n },\n \"required\": [\n \"temperature\",\n \"time\"\n ],\n \"type\": \"object\"\n }\n }\n ],\n \"thinking\": {\n \"enabled\": false\n },\n \"tool_choice\": {\n \"type\": \"auto\",\n \"disable_parallel_tool_use\": false\n },\n \"stream\": false,\n \"response_format\": {\n \"type\": \"text\"\n },\n \"temperature\": 0.7\n}") .asString(); ``` ```php Response with tool usage and result request('POST', 'https://api.example.com/v1/messages', [ 'body' => '{ "model": "default", "messages": [ { "role": "user", "content": "How do you fry an egg? Choose the best method." } ], "max_tokens": 1000, "system": [ { "text": "You are a helpful cooking assistant. Provide clear, step-by-step instructions.", "citations": { "enabled": true } } ], "tools": [ { "name": "egg_fryer", "description": "A tool to fry eggs with precise temperature control", "input_schema": { "properties": { "temperature": { "description": "Temperature in degrees Celsius", "type": "number" }, "time": { "description": "Time in minutes to fry the egg", "type": "number" } }, "required": [ "temperature", "time" ], "type": "object" } } ], "thinking": { "enabled": false }, "tool_choice": { "type": "auto", "disable_parallel_tool_use": false }, "stream": false, "response_format": { "type": "text" }, "temperature": 0.7 }', 'headers' => [ 'Content-Type' => 'application/json', ], ]); echo $response->getBody(); ``` ```csharp Response with tool usage and result using RestSharp; var client = new RestClient("https://api.example.com/v1/messages"); var request = new RestRequest(Method.POST); request.AddHeader("Content-Type", "application/json"); request.AddParameter("application/json", "{\n \"model\": \"default\",\n \"messages\": [\n {\n \"role\": \"user\",\n \"content\": \"How do you fry an egg? Choose the best method.\"\n }\n ],\n \"max_tokens\": 1000,\n \"system\": [\n {\n \"text\": \"You are a helpful cooking assistant. Provide clear, step-by-step instructions.\",\n \"citations\": {\n \"enabled\": true\n }\n }\n ],\n \"tools\": [\n {\n \"name\": \"egg_fryer\",\n \"description\": \"A tool to fry eggs with precise temperature control\",\n \"input_schema\": {\n \"properties\": {\n \"temperature\": {\n \"description\": \"Temperature in degrees Celsius\",\n \"type\": \"number\"\n },\n \"time\": {\n \"description\": \"Time in minutes to fry the egg\",\n \"type\": \"number\"\n }\n },\n \"required\": [\n \"temperature\",\n \"time\"\n ],\n \"type\": \"object\"\n }\n }\n ],\n \"thinking\": {\n \"enabled\": false\n },\n \"tool_choice\": {\n \"type\": \"auto\",\n \"disable_parallel_tool_use\": false\n },\n \"stream\": false,\n \"response_format\": {\n \"type\": \"text\"\n },\n \"temperature\": 0.7\n}", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` ```swift Response with tool usage and result import Foundation let headers = ["Content-Type": "application/json"] let parameters = [ "model": "default", "messages": [ [ "role": "user", "content": "How do you fry an egg? Choose the best method." ] ], "max_tokens": 1000, "system": [ [ "text": "You are a helpful cooking assistant. Provide clear, step-by-step instructions.", "citations": ["enabled": true] ] ], "tools": [ [ "name": "egg_fryer", "description": "A tool to fry eggs with precise temperature control", "input_schema": [ "properties": [ "temperature": [ "description": "Temperature in degrees Celsius", "type": "number" ], "time": [ "description": "Time in minutes to fry the egg", "type": "number" ] ], "required": ["temperature", "time"], "type": "object" ] ] ], "thinking": ["enabled": false], "tool_choice": [ "type": "auto", "disable_parallel_tool_use": false ], "stream": false, "response_format": ["type": "text"], "temperature": 0.7 ] as [String : Any] let postData = JSONSerialization.data(withJSONObject: parameters, options: []) let request = NSMutableURLRequest(url: NSURL(string: "https://api.example.com/v1/messages")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "POST" request.allHTTPHeaderFields = headers request.httpBody = postData as Data let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ```