Anthropic Message

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://api-evangelist.com/schemas/anthropic/anthropic-message-schema.json",
  "title": "Anthropic Message",
  "description": "Schema for the Anthropic Messages API request and response objects. Covers the Create Message request body and the Message response returned by POST /v1/messages.",
  "type": "object",
  "definitions": {
    "MessageRequest": {
      "type": "object",
      "description": "The request body for creating a message via the Anthropic Messages API.",
      "required": ["model", "messages", "max_tokens"],
      "properties": {
        "model": {
          "type": "string",
          "description": "The model that will complete your prompt (e.g. claude-opus-4-6, claude-sonnet-4-6, claude-haiku-4-5)."
        },
        "messages": {
          "type": "array",
          "description": "Input messages. Each message has a role and content. Roles must alternate between user and assistant. The first message must use the user role.",
          "minItems": 1,
          "items": {
            "$ref": "#/definitions/MessageParam"
          }
        },
        "max_tokens": {
          "type": "integer",
          "description": "The maximum number of tokens to generate before stopping.",
          "minimum": 1
        },
        "system": {
          "description": "A system prompt providing context and instructions to Claude. Can be a string or an array of text content blocks.",
          "oneOf": [
            { "type": "string" },
            {
              "type": "array",
              "items": { "$ref": "#/definitions/TextBlockParam" }
            }
          ]
        },
        "temperature": {
          "type": "number",
          "description": "Amount of randomness injected into the response. Ranges from 0.0 to 1.0. Default is 1.0.",
          "minimum": 0.0,
          "maximum": 1.0,
          "default": 1.0
        },
        "top_p": {
          "type": "number",
          "description": "Nucleus sampling probability cutoff. Use either temperature or top_p, 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": 0
        },
        "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": "#/definitions/Metadata"
        },
        "tools": {
          "type": "array",
          "description": "Definitions of tools that the model may use.",
          "items": { "$ref": "#/definitions/ToolDefinition" }
        },
        "tool_choice": {
          "$ref": "#/definitions/ToolChoice"
        },
        "thinking": {
          "$ref": "#/definitions/ThinkingConfig"
        },
        "service_tier": {
          "type": "string",
          "description": "The service tier to use for this request.",
          "enum": ["auto", "standard_only"]
        }
      },
      "additionalProperties": false
    },

    "MessageParam": {
      "type": "object",
      "description": "A single message in the conversation.",
      "required": ["role", "content"],
      "properties": {
        "role": {
          "type": "string",
          "description": "The role of the message sender.",
          "enum": ["user", "assistant"]
        },
        "content": {
          "description": "The content of the message. Can be a string or an array of content blocks.",
          "oneOf": [
            { "type": "string" },
            {
              "type": "array",
              "items": { "$ref": "#/definitions/ContentBlockParam" }
            }
          ]
        }
      }
    },

    "ContentBlockParam": {
      "description": "A content block in a request message.",
      "oneOf": [
        { "$ref": "#/definitions/TextBlockParam" },
        { "$ref": "#/definitions/ImageBlockParam" },
        { "$ref": "#/definitions/DocumentBlockParam" },
        { "$ref": "#/definitions/ToolUseBlockParam" },
        { "$ref": "#/definitions/ToolResultBlockParam" }
      ]
    },

    "TextBlockParam": {
      "type": "object",
      "description": "A text content block.",
      "required": ["type", "text"],
      "properties": {
        "type": { "type": "string", "const": "text" },
        "text": { "type": "string", "description": "The text content." },
        "cache_control": { "$ref": "#/definitions/CacheControl" }
      }
    },

    "ImageBlockParam": {
      "type": "object",
      "description": "An image content block.",
      "required": ["type", "source"],
      "properties": {
        "type": { "type": "string", "const": "image" },
        "source": { "$ref": "#/definitions/ImageSource" },
        "cache_control": { "$ref": "#/definitions/CacheControl" }
      }
    },

    "ImageSource": {
      "type": "object",
      "description": "The source of an image.",
      "required": ["type"],
      "properties": {
        "type": {
          "type": "string",
          "enum": ["base64", "url"]
        },
        "media_type": {
          "type": "string",
          "enum": ["image/jpeg", "image/png", "image/gif", "image/webp"]
        },
        "data": {
          "type": "string",
          "description": "Base64-encoded image data."
        },
        "url": {
          "type": "string",
          "format": "uri",
          "description": "URL of the image."
        }
      }
    },

    "DocumentBlockParam": {
      "type": "object",
      "description": "A document content block for PDFs or plain text.",
      "required": ["type", "source"],
      "properties": {
        "type": { "type": "string", "const": "document" },
        "source": { "$ref": "#/definitions/DocumentSource" },
        "title": { "type": "string", "description": "Optional title for the document." },
        "context": { "type": "string", "description": "Optional context about the document." },
        "cache_control": { "$ref": "#/definitions/CacheControl" }
      }
    },

    "DocumentSource": {
      "type": "object",
      "description": "The source of a document.",
      "required": ["type"],
      "properties": {
        "type": {
          "type": "string",
          "enum": ["base64", "text", "url", "content"]
        },
        "media_type": {
          "type": "string",
          "enum": ["application/pdf", "text/plain"]
        },
        "data": { "type": "string", "description": "Base64-encoded document data." },
        "text": { "type": "string", "description": "Plain text content." },
        "url": { "type": "string", "format": "uri", "description": "URL of the document." }
      }
    },

    "ToolUseBlockParam": {
      "type": "object",
      "description": "A tool use content block in a request (for multi-turn tool conversations).",
      "required": ["type", "id", "name", "input"],
      "properties": {
        "type": { "type": "string", "const": "tool_use" },
        "id": { "type": "string", "description": "A unique identifier for this tool use block." },
        "name": { "type": "string", "description": "The name of the tool being used." },
        "input": { "type": "object", "description": "The input passed to the tool.", "additionalProperties": true },
        "cache_control": { "$ref": "#/definitions/CacheControl" }
      }
    },

    "ToolResultBlockParam": {
      "type": "object",
      "description": "A tool result content block returned to Claude after executing a tool.",
      "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 result corresponds to." },
        "content": {
          "description": "The result of the tool call.",
          "oneOf": [
            { "type": "string" },
            {
              "type": "array",
              "items": { "$ref": "#/definitions/TextBlockParam" }
            }
          ]
        },
        "is_error": {
          "type": "boolean",
          "description": "Whether the tool call resulted in an error.",
          "default": false
        },
        "cache_control": { "$ref": "#/definitions/CacheControl" }
      }
    },

    "ToolDefinition": {
      "type": "object",
      "description": "A tool definition specifying a tool the model may use.",
      "required": ["name", "input_schema"],
      "properties": {
        "type": {
          "type": "string",
          "description": "The type of tool.",
          "default": "custom"
        },
        "name": {
          "type": "string",
          "description": "The name of the tool. Must match ^[a-zA-Z0-9_-]{1,64}$.",
          "pattern": "^[a-zA-Z0-9_-]{1,64}$"
        },
        "description": {
          "type": "string",
          "description": "A detailed description of what the tool does and when it should be used."
        },
        "input_schema": {
          "type": "object",
          "description": "A 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" } }
          },
          "additionalProperties": true
        },
        "cache_control": { "$ref": "#/definitions/CacheControl" }
      }
    },

    "ToolChoice": {
      "type": "object",
      "description": "Specifies how the model should use tools.",
      "required": ["type"],
      "properties": {
        "type": {
          "type": "string",
          "description": "The type of tool choice.",
          "enum": ["auto", "any", "tool", "none"]
        },
        "name": {
          "type": "string",
          "description": "The name of the tool to use. Required when type is tool."
        },
        "disable_parallel_tool_use": {
          "type": "boolean",
          "description": "Whether to disable parallel tool use.",
          "default": false
        }
      }
    },

    "ThinkingConfig": {
      "type": "object",
      "description": "Configuration for extended thinking.",
      "required": ["type"],
      "properties": {
        "type": {
          "type": "string",
          "enum": ["enabled", "disabled", "adaptive"]
        },
        "budget_tokens": {
          "type": "integer",
          "description": "The maximum number of tokens for thinking. Required when type is enabled.",
          "minimum": 1024
        }
      }
    },

    "Metadata": {
      "type": "object",
      "description": "Metadata about the request.",
      "properties": {
        "user_id": {
          "type": "string",
          "description": "An external identifier for the user. Should be a UUID or hash, not PII."
        }
      }
    },

    "CacheControl": {
      "type": "object",
      "description": "Cache control configuration for prompt caching.",
      "properties": {
        "type": {
          "type": "string",
          "enum": ["ephemeral"]
        },
        "ttl": {
          "type": "string",
          "description": "The time-to-live for cached content.",
          "enum": ["5m", "1h"]
        }
      }
    },

    "MessageResponse": {
      "type": "object",
      "description": "The response object returned by the Messages API.",
      "required": ["id", "type", "role", "content", "model", "stop_reason", "usage"],
      "properties": {
        "id": {
          "type": "string",
          "description": "Unique message identifier (e.g. msg_01XFDUDYJgAACzvnptvVoYEL)."
        },
        "type": {
          "type": "string",
          "const": "message",
          "description": "Object type. Always 'message'."
        },
        "role": {
          "type": "string",
          "const": "assistant",
          "description": "The role of the generated message. Always 'assistant'."
        },
        "content": {
          "type": "array",
          "description": "Content generated by the model as an array of content blocks.",
          "items": { "$ref": "#/definitions/ResponseContentBlock" }
        },
        "model": {
          "type": "string",
          "description": "The model that handled the request."
        },
        "stop_reason": {
          "type": ["string", "null"],
          "description": "The reason the model stopped generating.",
          "enum": ["end_turn", "max_tokens", "stop_sequence", "tool_use", "pause_turn", null]
        },
        "stop_sequence": {
          "type": ["string", "null"],
          "description": "Which custom stop sequence was generated, if any."
        },
        "usage": {
          "$ref": "#/definitions/Usage"
        }
      }
    },

    "ResponseContentBlock": {
      "description": "A content block in a response message.",
      "oneOf": [
        { "$ref": "#/definitions/TextBlock" },
        { "$ref": "#/definitions/ToolUseBlock" },
        { "$ref": "#/definitions/ThinkingBlock" }
      ]
    },

    "TextBlock": {
      "type": "object",
      "description": "A text content block in the response.",
      "required": ["type", "text"],
      "properties": {
        "type": { "type": "string", "const": "text" },
        "text": { "type": "string", "description": "The generated text." },
        "citations": {
          "type": "array",
          "description": "Citations for the generated text.",
          "items": { "$ref": "#/definitions/Citation" }
        }
      }
    },

    "Citation": {
      "type": "object",
      "description": "A citation referencing a source document.",
      "required": ["type", "cited_text"],
      "properties": {
        "type": {
          "type": "string",
          "enum": ["char_location", "page_location", "content_block_location"]
        },
        "cited_text": { "type": "string", "description": "The text being cited." },
        "document_index": { "type": "integer", "description": "Index of the cited document." },
        "document_title": { "type": "string", "description": "Title of the cited document." },
        "file_id": { "type": "string", "description": "File ID of the cited document." },
        "start_char_index": { "type": "integer" },
        "end_char_index": { "type": "integer" }
      }
    },

    "ToolUseBlock": {
      "type": "object",
      "description": "A tool use content block in the response indicating Claude wants to call 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 request." },
        "name": { "type": "string", "description": "The name of the tool the model wants to call." },
        "input": { "type": "object", "description": "The tool input generated by the model.", "additionalProperties": true }
      }
    },

    "ThinkingBlock": {
      "type": "object",
      "description": "A thinking content block showing the model's internal reasoning.",
      "required": ["type", "thinking", "signature"],
      "properties": {
        "type": { "type": "string", "const": "thinking" },
        "thinking": { "type": "string", "description": "The model's thinking process." },
        "signature": { "type": "string", "description": "Cryptographic signature verifying this block." }
      }
    },

    "Usage": {
      "type": "object",
      "description": "Token usage information for the request.",
      "required": ["input_tokens", "output_tokens"],
      "properties": {
        "input_tokens": {
          "type": "integer",
          "description": "The number of input tokens consumed.",
          "minimum": 0
        },
        "output_tokens": {
          "type": "integer",
          "description": "The number of output tokens generated.",
          "minimum": 0
        },
        "cache_creation_input_tokens": {
          "type": "integer",
          "description": "The number of input tokens used to create a cache entry.",
          "minimum": 0
        },
        "cache_read_input_tokens": {
          "type": "integer",
          "description": "The number of input tokens read from a cache.",
          "minimum": 0
        }
      }
    },

    "ErrorResponse": {
      "type": "object",
      "description": "An error response from the API.",
      "required": ["type", "error"],
      "properties": {
        "type": {
          "type": "string",
          "const": "error"
        },
        "error": {
          "type": "object",
          "required": ["type", "message"],
          "properties": {
            "type": {
              "type": "string",
              "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 error message."
            }
          }
        }
      }
    }
  },

  "oneOf": [
    { "$ref": "#/definitions/MessageRequest" },
    { "$ref": "#/definitions/MessageResponse" }
  ]
}