Claude · Schema
Claude Message
Schema for Anthropic Claude Messages API request and response objects including messages, content blocks, and usage tracking.
Artificial IntelligenceChatbotConversational 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" }
]
}