Claude · Schema
Claude Message
Schema for Anthropic Claude Messages API request and response objects including messages, content blocks, and usage tracking.
Artificial IntelligenceChatbotsConversational AIGenerative AILarge Language ModelsMachine-LearningNatural Language Processing
JSON Schema
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://api.anthropic.com/schemas/claude-message-schema.json",
"title": "Claude Message",
"description": "Schema for Anthropic Claude Messages API request and response objects including messages, content blocks, and usage tracking.",
"type": "object",
"$defs": {
"CreateMessageRequest": {
"type": "object",
"title": "Create Message Request",
"description": "Request body for creating a new message with Claude.",
"required": ["model", "max_tokens", "messages"],
"properties": {
"model": {
"type": "string",
"description": "The model that will complete your prompt. See the list of available models.",
"examples": [
"claude-opus-4-6",
"claude-sonnet-4-6",
"claude-sonnet-4-5-20250929",
"claude-3-5-haiku-latest"
]
},
"max_tokens": {
"type": "integer",
"description": "The maximum number of tokens to generate before stopping. Different models support different maximum values.",
"minimum": 1,
"examples": [1024, 4096, 8192]
},
"messages": {
"type": "array",
"description": "Input messages with alternating user and assistant conversational turns. Maximum 100,000 messages per request.",
"items": {
"$ref": "#/$defs/MessageParam"
},
"minItems": 1
},
"system": {
"description": "System prompt providing context and instructions to Claude. Can be a string or array of text content blocks.",
"oneOf": [
{
"type": "string"
},
{
"type": "array",
"items": {
"$ref": "#/$defs/TextBlockParam"
}
}
]
},
"temperature": {
"type": "number",
"description": "Amount of randomness injected into the response. Use closer to 0.0 for analytical tasks, closer to 1.0 for creative tasks.",
"minimum": 0.0,
"maximum": 1.0,
"default": 1.0
},
"top_p": {
"type": "number",
"description": "Use nucleus sampling. Recommended to use either temperature or top_p, but not both.",
"minimum": 0.0,
"maximum": 1.0
},
"top_k": {
"type": "integer",
"description": "Only sample from the top K options for each subsequent token.",
"minimum": 1
},
"stop_sequences": {
"type": "array",
"description": "Custom text sequences that will cause the model to stop generating.",
"items": {
"type": "string"
}
},
"stream": {
"type": "boolean",
"description": "Whether to incrementally stream the response using server-sent events.",
"default": false
},
"metadata": {
"$ref": "#/$defs/Metadata"
},
"tools": {
"type": "array",
"description": "Definitions of tools that the model may use.",
"items": {
"$ref": "#/$defs/ToolDefinition"
}
},
"tool_choice": {
"$ref": "#/$defs/ToolChoice"
},
"thinking": {
"$ref": "#/$defs/ThinkingConfig"
},
"output_config": {
"$ref": "#/$defs/OutputConfig"
},
"service_tier": {
"type": "string",
"description": "Service tier to use for this request.",
"enum": ["auto", "standard_only"],
"default": "auto"
},
"cache_control": {
"$ref": "#/$defs/CacheControl"
}
},
"additionalProperties": false
},
"Message": {
"type": "object",
"title": "Message Response",
"description": "A message response from Claude.",
"required": ["id", "type", "role", "content", "model", "stop_reason", "usage"],
"properties": {
"id": {
"type": "string",
"description": "Unique object identifier for the message.",
"pattern": "^msg_",
"examples": ["msg_01XFDUDYJgAACzvnptvVoYEL"]
},
"type": {
"type": "string",
"description": "Object type. Always 'message' for message responses.",
"const": "message"
},
"role": {
"type": "string",
"description": "Conversational role of the generated message. Always 'assistant'.",
"const": "assistant"
},
"content": {
"type": "array",
"description": "Content generated by the model. Array of content blocks.",
"items": {
"$ref": "#/$defs/ResponseContentBlock"
}
},
"model": {
"type": "string",
"description": "The model that handled the request.",
"examples": ["claude-sonnet-4-6", "claude-opus-4-6"]
},
"stop_reason": {
"type": ["string", "null"],
"description": "The reason the model stopped generating tokens.",
"enum": ["end_turn", "max_tokens", "stop_sequence", "tool_use", null]
},
"stop_sequence": {
"type": ["string", "null"],
"description": "The stop sequence that caused the model to stop, if applicable."
},
"usage": {
"$ref": "#/$defs/Usage"
}
},
"additionalProperties": false
},
"MessageParam": {
"type": "object",
"title": "Message Parameter",
"description": "An input message in the conversation.",
"required": ["role", "content"],
"properties": {
"role": {
"type": "string",
"description": "The role of the message author.",
"enum": ["user", "assistant"]
},
"content": {
"description": "The content of the message. Can be a string or array of content blocks.",
"oneOf": [
{
"type": "string"
},
{
"type": "array",
"items": {
"$ref": "#/$defs/RequestContentBlock"
}
}
]
}
},
"additionalProperties": false
},
"ResponseContentBlock": {
"title": "Response Content Block",
"description": "A content block in a message response from Claude.",
"oneOf": [
{ "$ref": "#/$defs/TextBlock" },
{ "$ref": "#/$defs/ToolUseBlock" },
{ "$ref": "#/$defs/ThinkingBlock" }
]
},
"RequestContentBlock": {
"title": "Request Content Block",
"description": "A content block in a message request.",
"oneOf": [
{ "$ref": "#/$defs/TextBlockParam" },
{ "$ref": "#/$defs/ImageBlockParam" },
{ "$ref": "#/$defs/DocumentBlockParam" },
{ "$ref": "#/$defs/ToolUseBlockParam" },
{ "$ref": "#/$defs/ToolResultBlockParam" },
{ "$ref": "#/$defs/ThinkingBlockParam" }
]
},
"TextBlock": {
"type": "object",
"title": "Text Block",
"description": "A text content block in a response.",
"required": ["type", "text"],
"properties": {
"type": {
"type": "string",
"const": "text"
},
"text": {
"type": "string",
"description": "The generated text content."
},
"citations": {
"type": "array",
"description": "Citations for the text content, if any.",
"items": {
"type": "object"
}
}
},
"additionalProperties": false
},
"TextBlockParam": {
"type": "object",
"title": "Text Block Parameter",
"description": "A text content block in a request.",
"required": ["type", "text"],
"properties": {
"type": {
"type": "string",
"const": "text"
},
"text": {
"type": "string",
"description": "The text content."
},
"cache_control": {
"$ref": "#/$defs/CacheControl"
}
},
"additionalProperties": false
},
"ImageBlockParam": {
"type": "object",
"title": "Image Block Parameter",
"description": "An image content block supporting base64-encoded or URL-referenced images.",
"required": ["type", "source"],
"properties": {
"type": {
"type": "string",
"const": "image"
},
"source": {
"type": "object",
"description": "The source of the image.",
"required": ["type"],
"properties": {
"type": {
"type": "string",
"enum": ["base64", "url"]
},
"media_type": {
"type": "string",
"description": "The media type of the image.",
"enum": ["image/jpeg", "image/png", "image/gif", "image/webp"]
},
"data": {
"type": "string",
"description": "Base64-encoded image data. Required when type is base64."
},
"url": {
"type": "string",
"format": "uri",
"description": "URL of the image. Required when type is url."
}
}
},
"cache_control": {
"$ref": "#/$defs/CacheControl"
}
},
"additionalProperties": false
},
"DocumentBlockParam": {
"type": "object",
"title": "Document Block Parameter",
"description": "A document content block for PDFs and text documents.",
"required": ["type", "source"],
"properties": {
"type": {
"type": "string",
"const": "document"
},
"source": {
"type": "object",
"description": "The source of the document.",
"required": ["type"],
"properties": {
"type": {
"type": "string",
"enum": ["base64", "url", "text", "content"]
},
"media_type": {
"type": "string",
"enum": ["application/pdf", "text/plain"]
},
"data": {
"type": "string",
"description": "Base64-encoded document data."
},
"url": {
"type": "string",
"format": "uri",
"description": "URL of the document."
}
}
},
"title": {
"type": "string",
"description": "Optional title for the document."
},
"context": {
"type": "string",
"description": "Optional context about the document."
},
"citations": {
"type": "object",
"properties": {
"enabled": {
"type": "boolean"
}
}
},
"cache_control": {
"$ref": "#/$defs/CacheControl"
}
},
"additionalProperties": false
},
"ToolUseBlock": {
"type": "object",
"title": "Tool Use Block",
"description": "A tool use content block in a response indicating the model wants to invoke a tool.",
"required": ["type", "id", "name", "input"],
"properties": {
"type": {
"type": "string",
"const": "tool_use"
},
"id": {
"type": "string",
"description": "A unique identifier for this tool use block.",
"pattern": "^toolu_",
"examples": ["toolu_01D7FLrfh4GYq7yT1ULFeyMV"]
},
"name": {
"type": "string",
"description": "The name of the tool being used."
},
"input": {
"type": "object",
"description": "The input passed to the tool, conforming to the tool's input_schema.",
"additionalProperties": true
}
},
"additionalProperties": false
},
"ToolUseBlockParam": {
"type": "object",
"title": "Tool Use Block Parameter",
"description": "A tool use content block in a request for multi-turn tool use conversations.",
"required": ["type", "id", "name", "input"],
"properties": {
"type": {
"type": "string",
"const": "tool_use"
},
"id": {
"type": "string",
"description": "The unique identifier for this tool use."
},
"name": {
"type": "string",
"description": "The name of the tool."
},
"input": {
"type": "object",
"description": "The input to the tool.",
"additionalProperties": true
},
"cache_control": {
"$ref": "#/$defs/CacheControl"
}
},
"additionalProperties": false
},
"ToolResultBlockParam": {
"type": "object",
"title": "Tool Result Block Parameter",
"description": "A tool result content block providing the output from a tool invocation.",
"required": ["type", "tool_use_id"],
"properties": {
"type": {
"type": "string",
"const": "tool_result"
},
"tool_use_id": {
"type": "string",
"description": "The id of the tool use request this is a result for."
},
"content": {
"description": "The result of the tool call. Can be a string or array of content blocks.",
"oneOf": [
{
"type": "string"
},
{
"type": "array",
"items": {
"oneOf": [
{ "$ref": "#/$defs/TextBlockParam" },
{ "$ref": "#/$defs/ImageBlockParam" }
]
}
}
]
},
"is_error": {
"type": "boolean",
"description": "Set to true if the tool execution resulted in an error.",
"default": false
},
"cache_control": {
"$ref": "#/$defs/CacheControl"
}
},
"additionalProperties": false
},
"ThinkingBlock": {
"type": "object",
"title": "Thinking Block",
"description": "A thinking content block showing Claude's internal reasoning process.",
"required": ["type", "thinking", "signature"],
"properties": {
"type": {
"type": "string",
"const": "thinking"
},
"thinking": {
"type": "string",
"description": "Claude's internal reasoning text."
},
"signature": {
"type": "string",
"description": "A signature verifying the thinking block."
}
},
"additionalProperties": false
},
"ThinkingBlockParam": {
"type": "object",
"title": "Thinking Block Parameter",
"description": "A thinking content block in a request for multi-turn with extended thinking.",
"required": ["type", "thinking", "signature"],
"properties": {
"type": {
"type": "string",
"const": "thinking"
},
"thinking": {
"type": "string",
"description": "The thinking text from a previous response."
},
"signature": {
"type": "string",
"description": "The signature from the previous thinking block."
}
},
"additionalProperties": false
},
"ToolDefinition": {
"type": "object",
"title": "Tool Definition",
"description": "Definition of a tool that the model can use.",
"required": ["name", "input_schema"],
"properties": {
"name": {
"type": "string",
"description": "The name of the tool. Must match ^[a-zA-Z0-9_-]{1,64}$.",
"pattern": "^[a-zA-Z0-9_-]{1,64}$",
"examples": ["get_stock_price", "get_weather"]
},
"description": {
"type": "string",
"description": "A detailed description of what the tool does, when it should be used, and what each parameter means."
},
"input_schema": {
"type": "object",
"description": "JSON Schema object defining the expected parameters for the tool.",
"required": ["type"],
"properties": {
"type": {
"type": "string",
"const": "object"
},
"properties": {
"type": "object",
"additionalProperties": true
},
"required": {
"type": "array",
"items": {
"type": "string"
}
}
}
},
"cache_control": {
"$ref": "#/$defs/CacheControl"
},
"type": {
"type": "string",
"description": "The type of tool. Omit for custom tools. Use specific type identifiers for server tools."
}
}
},
"ToolChoice": {
"type": "object",
"title": "Tool Choice",
"description": "How the model should use the provided tools.",
"required": ["type"],
"properties": {
"type": {
"type": "string",
"description": "The tool choice strategy.",
"enum": ["auto", "any", "tool", "none"]
},
"name": {
"type": "string",
"description": "The name of the specific tool to use. Required when type is 'tool'."
},
"disable_parallel_tool_use": {
"type": "boolean",
"description": "Whether to disable parallel tool use."
}
}
},
"ThinkingConfig": {
"type": "object",
"title": "Thinking Configuration",
"description": "Configuration for extended thinking feature.",
"required": ["type"],
"properties": {
"type": {
"type": "string",
"description": "Whether thinking is enabled, disabled, or adaptive.",
"enum": ["enabled", "disabled", "adaptive"]
},
"budget_tokens": {
"type": "integer",
"description": "Maximum number of tokens for thinking. Minimum 1024 and must be less than max_tokens.",
"minimum": 1024
}
}
},
"OutputConfig": {
"type": "object",
"title": "Output Configuration",
"description": "Configuration for structured output format.",
"properties": {
"type": {
"type": "string",
"enum": ["json_schema"]
},
"schema": {
"type": "object",
"description": "JSON Schema defining the expected output structure.",
"additionalProperties": true
}
}
},
"CacheControl": {
"type": "object",
"title": "Cache Control",
"description": "Cache control settings for prompt caching. Creates cost-saving cache breakpoints for reusable context.",
"required": ["type"],
"properties": {
"type": {
"type": "string",
"const": "ephemeral"
},
"ttl": {
"type": "string",
"description": "Time-to-live for the cache entry.",
"enum": ["5m", "1h"]
}
},
"additionalProperties": false
},
"Metadata": {
"type": "object",
"title": "Metadata",
"description": "Request metadata for tracking and abuse prevention.",
"properties": {
"user_id": {
"type": "string",
"description": "An external identifier for the user making the request. Should be a UUID, hash, or other opaque identifier."
}
},
"additionalProperties": false
},
"Usage": {
"type": "object",
"title": "Usage",
"description": "Token usage information for the request.",
"required": ["input_tokens", "output_tokens"],
"properties": {
"input_tokens": {
"type": "integer",
"description": "The number of input tokens consumed.",
"examples": [25]
},
"output_tokens": {
"type": "integer",
"description": "The number of output tokens generated.",
"examples": [150]
},
"cache_creation_input_tokens": {
"type": "integer",
"description": "The number of input tokens used to create a cache entry."
},
"cache_read_input_tokens": {
"type": "integer",
"description": "The number of input tokens read from cache."
}
},
"additionalProperties": false
},
"TokenCount": {
"type": "object",
"title": "Token Count",
"description": "Response from the count tokens endpoint.",
"properties": {
"input_tokens": {
"type": "integer",
"description": "The total number of input tokens in the message."
}
},
"additionalProperties": false
},
"ModelInfo": {
"type": "object",
"title": "Model Info",
"description": "Metadata about a Claude model.",
"required": ["id", "type", "display_name", "created_at"],
"properties": {
"id": {
"type": "string",
"description": "Unique model identifier.",
"examples": ["claude-sonnet-4-6", "claude-opus-4-6"]
},
"type": {
"type": "string",
"description": "Object type. Always 'model' for model objects.",
"const": "model"
},
"display_name": {
"type": "string",
"description": "A human-readable name for the model.",
"examples": ["Claude Sonnet 4.6", "Claude Opus 4.6"]
},
"created_at": {
"type": "string",
"format": "date-time",
"description": "RFC 3339 datetime string representing when the model was released."
}
},
"additionalProperties": false
},
"Error": {
"type": "object",
"title": "Error",
"description": "An error response from the Anthropic API.",
"required": ["type", "error"],
"properties": {
"type": {
"type": "string",
"const": "error"
},
"error": {
"type": "object",
"required": ["type", "message"],
"properties": {
"type": {
"type": "string",
"description": "The type of error.",
"enum": [
"invalid_request_error",
"authentication_error",
"permission_error",
"not_found_error",
"rate_limit_error",
"api_error",
"overloaded_error"
]
},
"message": {
"type": "string",
"description": "A human-readable description of the error."
}
}
}
},
"additionalProperties": false
}
},
"oneOf": [
{ "$ref": "#/$defs/CreateMessageRequest" },
{ "$ref": "#/$defs/Message" }
]
}