Anthropic Messages API

openapi: 3.1.0
info:
  title: Anthropic Messages API
  description: >
    Send a structured list of input messages with text and/or image content, and
    the model will generate the next message in the conversation. The Messages
    API can be used for both single-turn and multi-turn conversations. It
    supports text, images, tool use, extended thinking, streaming, and
    structured output.
  version: 2023-06-01
  contact:
    name: Anthropic Support
    url: https://support.anthropic.com
  license:
    name: Anthropic Terms of Service
    url: https://www.anthropic.com/terms

servers:
  - url: https://api.anthropic.com
    description: Production Server

security:
  - ApiKeyAuth: []

tags:
  - name: Messages
    description: Create messages using Claude models

paths:
  /v1/messages:
    post:
      summary: Anthropic Create A Message
      description: >
        Send a structured list of input messages with text and/or image content,
        and the model will generate the next message in the conversation. The
        Messages API can be used for both single-turn and multi-turn
        conversations.
      operationId: createMessage
      tags:
        - Messages
      x-microcks-operation:
        dispatcher: FALLBACK
        dispatcherRules: ""
        delay: 100
      parameters:
        - $ref: '#/components/parameters/AnthropicVersionHeader'
        - $ref: '#/components/parameters/ApiKeyHeader'
        - $ref: '#/components/parameters/ContentTypeHeader'
        - $ref: '#/components/parameters/AnthropicBetaHeader'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateMessageRequest'
            examples:
              SimpleMessage:
                $ref: '#/components/examples/SimpleMessageRequestExample'
              ToolUseMessage:
                $ref: '#/components/examples/ToolUseMessageRequestExample'
              ThinkingMessage:
                $ref: '#/components/examples/ThinkingMessageRequestExample'
      responses:
        '200':
          description: Successful message response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
              examples:
                SimpleResponse:
                  $ref: '#/components/examples/SimpleMessageResponseExample'
                ToolUseResponse:
                  $ref: '#/components/examples/ToolUseMessageResponseExample'
        '400':
          description: Bad Request - Invalid input parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                BadRequestExample:
                  $ref: '#/components/examples/ErrorBadRequestExample'
        '401':
          description: Unauthorized - Invalid or missing API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                UnauthorizedExample:
                  $ref: '#/components/examples/ErrorUnauthorizedExample'
        '403':
          description: Forbidden - Access denied
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                ForbiddenExample:
                  $ref: '#/components/examples/ErrorForbiddenExample'
        '429':
          description: Too Many Requests - Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                RateLimitExample:
                  $ref: '#/components/examples/ErrorRateLimitExample'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                ServerErrorExample:
                  $ref: '#/components/examples/ErrorServerExample'
        '529':
          description: API Overloaded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                OverloadedExample:
                  $ref: '#/components/examples/ErrorOverloadedExample'

components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: Anthropic API key for authentication

  parameters:
    AnthropicVersionHeader:
      name: anthropic-version
      in: header
      required: true
      description: The version of the Anthropic API to use (e.g. 2023-06-01).
      schema:
        type: string
        default: '2023-06-01'

    ApiKeyHeader:
      name: x-api-key
      in: header
      required: true
      description: A valid Anthropic API key.
      schema:
        type: string

    ContentTypeHeader:
      name: Content-Type
      in: header
      required: true
      description: The content type of the request body.
      schema:
        type: string
        default: application/json

    AnthropicBetaHeader:
      name: anthropic-beta
      in: header
      description: >
        Optional header to specify the beta version(s) you want to use. To use
        multiple betas, use a comma separated list or specify the header
        multiple times.
      required: false
      schema:
        type: array
        items:
          type: string
      style: simple
      explode: false

  schemas:
    # ---- Request Schemas ----

    CreateMessageRequest:
      type: object
      required:
        - model
        - messages
        - max_tokens
      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-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.
          items:
            $ref: '#/components/schemas/MessageParam'
          minItems: 1
        max_tokens:
          type: integer
          description: >
            The maximum number of tokens to generate before stopping. The model
            may stop before reaching this limit. This parameter was previously
            called max_tokens_to_sample.
          minimum: 1
        system:
          description: >
            A system prompt is a way of providing context and instructions to
            Claude. Can be a string or an array of content blocks.
          oneOf:
            - type: string
            - type: array
              items:
                $ref: '#/components/schemas/TextBlockParam'
        temperature:
          type: number
          description: >
            Amount of randomness injected into the response. Ranges from 0.0 to
            1.0. Use temperature closer to 0.0 for analytical or multiple choice
            tasks, and closer to 1.0 for creative and generative tasks. Default
            is 1.0.
          minimum: 0.0
          maximum: 1.0
          default: 1.0
        top_p:
          type: number
          description: >
            Use nucleus sampling. In nucleus sampling, we compute the cumulative
            distribution over all the options for each subsequent token in
            decreasing probability order and cut it off once it reaches a
            particular probability specified by top_p. Recommended for advanced
            use cases only. 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. Used to
            remove long tail low probability responses. Recommended for advanced
            use cases only.
          minimum: 0
        stop_sequences:
          type: array
          description: >
            Custom text sequences that will cause the model to stop generating.
            If the model encounters one of the custom sequences, the
            stop_reason in the response will be stop_sequence and the
            stop_sequence value will contain the matched stop sequence.
          items:
            type: string
        stream:
          type: boolean
          description: >
            Whether to incrementally stream the response using server-sent
            events.
          default: false
        metadata:
          $ref: '#/components/schemas/Metadata'
        tools:
          type: array
          description: >
            Definitions of tools that the model may use. If you include tools in
            your API request, the model may return tool_use content blocks. Each
            tool definition includes a name, description, and input schema.
          items:
            $ref: '#/components/schemas/ToolUnion'
        tool_choice:
          $ref: '#/components/schemas/ToolChoice'
        thinking:
          $ref: '#/components/schemas/ThinkingConfig'
        service_tier:
          type: string
          description: >
            The service tier to use for this request. Defaults to auto, which
            will use the highest priority tier available.
          enum:
            - auto
            - standard_only
        output_config:
          $ref: '#/components/schemas/OutputConfig'

    # ---- Message Parameters ----

    MessageParam:
      type: object
      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 for simple text messages
            or an array of content blocks for multi-modal input.
          oneOf:
            - type: string
            - type: array
              items:
                $ref: '#/components/schemas/ContentBlockParam'

    # ---- Content Block Parameters (Request) ----

    ContentBlockParam:
      description: A content block in a request message.
      oneOf:
        - $ref: '#/components/schemas/TextBlockParam'
        - $ref: '#/components/schemas/ImageBlockParam'
        - $ref: '#/components/schemas/DocumentBlockParam'
        - $ref: '#/components/schemas/ToolUseBlockParam'
        - $ref: '#/components/schemas/ToolResultBlockParam'
      discriminator:
        propertyName: type
        mapping:
          text: '#/components/schemas/TextBlockParam'
          image: '#/components/schemas/ImageBlockParam'
          document: '#/components/schemas/DocumentBlockParam'
          tool_use: '#/components/schemas/ToolUseBlockParam'
          tool_result: '#/components/schemas/ToolResultBlockParam'

    TextBlockParam:
      type: object
      required:
        - type
        - text
      properties:
        type:
          type: string
          enum:
            - text
        text:
          type: string
          description: The text content.
        cache_control:
          $ref: '#/components/schemas/CacheControl'

    ImageBlockParam:
      type: object
      required:
        - type
        - source
      properties:
        type:
          type: string
          enum:
            - image
        source:
          $ref: '#/components/schemas/ImageSource'
        cache_control:
          $ref: '#/components/schemas/CacheControl'

    ImageSource:
      type: object
      required:
        - type
      properties:
        type:
          type: string
          description: The source type of the image.
          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 (for base64 source type).
        url:
          type: string
          format: uri
          description: URL of the image (for url source type).

    DocumentBlockParam:
      type: object
      required:
        - type
        - source
      properties:
        type:
          type: string
          enum:
            - document
        source:
          $ref: '#/components/schemas/DocumentSource'
        title:
          type: string
          description: Optional title for the document.
        context:
          type: string
          description: Optional context about the document.
        cache_control:
          $ref: '#/components/schemas/CacheControl'

    DocumentSource:
      type: object
      required:
        - type
      properties:
        type:
          type: string
          description: The source type of the document.
          enum:
            - base64
            - text
            - url
            - content
        media_type:
          type: string
          description: The media type of the document.
          enum:
            - application/pdf
            - text/plain
        data:
          type: string
          description: Base64-encoded document data (for base64 source type).
        text:
          type: string
          description: The plain text content (for text source type).
        url:
          type: string
          format: uri
          description: URL of the document (for url source type).

    ToolUseBlockParam:
      type: object
      required:
        - type
        - id
        - name
        - input
      properties:
        type:
          type: string
          enum:
            - tool_use
        id:
          type: string
          description: A unique identifier for this particular tool use block.
        name:
          type: string
          description: The name of the tool being used.
        input:
          type: object
          description: An object containing the input passed to the tool.
          additionalProperties: true
        cache_control:
          $ref: '#/components/schemas/CacheControl'

    ToolResultBlockParam:
      type: object
      required:
        - type
        - tool_use_id
      properties:
        type:
          type: string
          enum:
            - 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. Can be a string or array of content blocks.
          oneOf:
            - type: string
            - type: array
              items:
                $ref: '#/components/schemas/TextBlockParam'
        is_error:
          type: boolean
          description: Whether the tool call resulted in an error.
          default: false
        cache_control:
          $ref: '#/components/schemas/CacheControl'

    # ---- Tool Definitions ----

    ToolUnion:
      description: >
        A tool definition. Can be a custom tool or an Anthropic-defined server
        tool.
      oneOf:
        - $ref: '#/components/schemas/Tool'
        - $ref: '#/components/schemas/ServerTool'

    Tool:
      type: object
      required:
        - name
        - input_schema
      properties:
        type:
          type: string
          description: The type of tool. Defaults to custom.
          enum:
            - custom
          default: custom
        name:
          type: string
          description: >
            Name of the tool. Must match the regex ^[a-zA-Z0-9_-]{1,64}$.
          pattern: '^[a-zA-Z0-9_-]{1,64}$'
        description:
          type: string
          description: >
            Description of what this tool does. Tool descriptions should be as
            detailed as possible to help the model understand when and how to
            use the tool.
        input_schema:
          type: object
          description: >
            JSON Schema object defining the expected parameters for the tool.
          required:
            - type
          properties:
            type:
              type: string
              enum:
                - object
            properties:
              type: object
              additionalProperties: true
            required:
              type: array
              items:
                type: string
          additionalProperties: true
        cache_control:
          $ref: '#/components/schemas/CacheControl'

    ServerTool:
      type: object
      required:
        - type
        - name
      properties:
        type:
          type: string
          description: The Anthropic-defined server tool type.
          enum:
            - web_search_20250305
            - web_search_20260209
            - web_fetch_20250910
            - web_fetch_20260209
            - code_execution_20250825
            - code_execution_20260120
            - bash_20250124
            - text_editor_20250728
            - memory_20250818
        name:
          type: string
          description: The server tool name.

    # ---- Tool Choice ----

    ToolChoice:
      description: >
        How the model should use the provided tools. The model can use a
        specific tool, any available tool, decide by itself, or not use tools.
      type: object
      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. Defaults to false.
          default: false

    # ---- Thinking Configuration ----

    ThinkingConfig:
      description: Configuration for extended thinking.
      type: object
      required:
        - type
      properties:
        type:
          type: string
          description: The type of thinking configuration.
          enum:
            - enabled
            - disabled
            - adaptive
        budget_tokens:
          type: integer
          description: >
            The maximum number of tokens to use for thinking. Must be at least
            1024 and less than max_tokens. Required when type is enabled.
          minimum: 1024

    # ---- Output Configuration ----

    OutputConfig:
      type: object
      description: Configuration for structured output.
      properties:
        format:
          type: object
          description: The output format configuration.
          properties:
            type:
              type: string
              description: The output format type.
              enum:
                - json_schema
            schema:
              type: object
              description: A JSON Schema that the output must conform to.
              additionalProperties: true
        effort:
          type: string
          description: The effort level for the response.
          enum:
            - low
            - medium
            - high
            - max

    # ---- Metadata ----

    Metadata:
      type: object
      description: An object describing metadata about the request.
      properties:
        user_id:
          type: string
          description: >
            An external identifier for the user who is associated with the
            request. This should be a UUID, hash value, or other opaque
            identifier. Do not include any identifying information such as name,
            email, or phone number.

    # ---- Cache Control ----

    CacheControl:
      type: object
      description: Cache control configuration for prompt caching.
      properties:
        type:
          type: string
          description: The type of cache control.
          enum:
            - ephemeral
        ttl:
          type: string
          description: The time-to-live for the cached content.
          enum:
            - 5m
            - 1h

    # ---- Response Schemas ----

    MessageResponse:
      type: object
      required:
        - id
        - type
        - role
        - content
        - model
        - stop_reason
        - usage
      properties:
        id:
          type: string
          description: >
            Unique object identifier. The format and length of IDs may change
            over time.
          examples:
            - msg_01XFDUDYJgAACzvnptvVoYEL
        type:
          type: string
          description: Object type. Always "message" for the Messages API.
          enum:
            - message
        role:
          type: string
          description: >
            Conversational role of the generated message. This will always be
            "assistant".
          enum:
            - assistant
        content:
          type: array
          description: >
            Content generated by the model. This is an array of content blocks,
            each of which has a type that determines its shape.
          items:
            $ref: '#/components/schemas/ContentBlock'
        model:
          type: string
          description: The model that handled the request.
          examples:
            - claude-opus-4-6
            - claude-sonnet-4-6
        stop_reason:
          type:
            - string
            - 'null'
          description: >
            The reason the model stopped generating tokens. This will be
            end_turn if the model reached a natural stopping point, max_tokens
            if the requested max_tokens limit was reached, stop_sequence if one
            of the provided stop sequences was generated, or tool_use if the
            model invoked a tool.
          enum:
            - end_turn
            - max_tokens
            - stop_sequence
            - tool_use
            - pause_turn
            - 
        stop_sequence:
          type:
            - string
            - 'null'
          description: >
            Which custom stop sequence was generated, if any. Will be null if
            the stop reason was not stop_sequence.
        usage:
          $ref: '#/components/schemas/Usage'

    # ---- Response Content Blocks ----

    ContentBlock:
      description: A content block in a response message.
      oneOf:
        - $ref: '#/components/schemas/TextBlock'
        - $ref: '#/components/schemas/ToolUseBlock'
        - $ref: '#/components/schemas/ThinkingBlock'
      discriminator:
        propertyName: type
        mapping:
          text: '#/components/schemas/TextBlock'
          tool_use: '#/components/schemas/ToolUseBlock'
          thinking: '#/components/schemas/ThinkingBlock'

    TextBlock:
      type: object
      required:
        - type
        - text
      properties:
        type:
          type: string
          enum:
            - text
        text:
          type: string
          description: The generated text.
        citations:
          type: array
          description: Citations for the generated text, if any.
          items:
            $ref: '#/components/schemas/Citation'

    Citation:
      type: object
      required:
        - type
        - cited_text
      properties:
        type:
          type: string
          description: The type of citation.
          enum:
            - char_location
            - page_location
            - content_block_location
        cited_text:
          type: string
          description: The text being cited.
        document_index:
          type: integer
          description: The index of the cited document.
        document_title:
          type: string
          description: The title of the cited document.
        file_id:
          type: string
          description: The file ID of the cited document.
        start_char_index:
          type: integer
          description: The starting character index of the citation.
        end_char_index:
          type: integer
          description: The ending character index of the citation.

    ToolUseBlock:
      type: object
      required:
        - type
        - id
        - name
        - input
      properties:
        type:
          type: string
          enum:
            - 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: >
            An object containing the tool input generated by the model, conforming
            to the tool's input_schema.
          additionalProperties: true

    ThinkingBlock:
      type: object
      required:
        - type
        - thinking
        - signature
      properties:
        type:
          type: string
          enum:
            - thinking
        thinking:
          type: string
          description: >
            The model's thinking process. This is the internal reasoning the
            model performed before generating its response.
        signature:
          type: string
          description: >
            A cryptographic signature verifying this thinking block was generated
            by Claude.

    # ---- Usage ----

    Usage:
      type: object
      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

    # ---- Error Schemas ----

    ErrorResponse:
      type: object
      required:
        - type
        - error
      properties:
        type:
          type: string
          enum:
            - 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 error message.

  examples:
    SimpleMessageRequestExample:
      summary: Simple text message
      value:
        model: claude-opus-4-6
        max_tokens: 1024
        messages:
          - role: user
            content: Hello, Claude

    ToolUseMessageRequestExample:
      summary: Message with tool definitions
      value:
        model: claude-opus-4-6
        max_tokens: 1024
        tools:
          - name: get_weather
            description: Get the current weather in a given location
            input_schema:
              type: object
              properties:
                location:
                  type: string
                  description: The city and state, e.g. San Francisco, CA
              required:
                - location
        messages:
          - role: user
            content: What is the weather like in San Francisco?

    ThinkingMessageRequestExample:
      summary: Message with extended thinking enabled
      value:
        model: claude-opus-4-6
        max_tokens: 16000
        thinking:
          type: enabled
          budget_tokens: 10000
        messages:
          - role: user
            content: Solve this step-by-step - what is 27 * 453?

    SimpleMessageResponseExample:
      summary: Simple text response
      value:
        id: msg_01XFDUDYJgAACzvnptvVoYEL
        type: message
        role: assistant
        content:
          - type: text
            text: Hi! How can I help you today?
        model: claude-opus-4-6
        stop_reason: end_turn
        stop_sequence:
        usage:
          input_tokens: 10
          output_tokens: 15
          cache_creation_input_tokens: 0
          cache_read_input_tokens: 0

    ToolUseMessageResponseExample:
      summary: Tool use response
      value:
        id: msg_01Aq9w938a90dw8q
        type: message
        role: assistant
        content:
          - type: text
            text: I'll check the current weather in San Francisco for you.
          - type: tool_use
            id: toolu_01A09q90qw90lq917835lq9
            name: get_weather
            input:
              location: San Francisco, CA
              unit: celsius
        model: claude-opus-4-6
        stop_reason: tool_use
        stop_sequence:
        usage:
          input_tokens: 380
          output_tokens: 65
          cache_creation_input_tokens: 0
          cache_read_input_tokens: 0

    ErrorBadRequestExample:
      summary: Bad request error
      value:
        type: error
        error:
          type: invalid_request_error
          message: "messages: Input messages must have alternating roles"

    ErrorUnauthorizedExample:
      summary: Unauthorized error
      value:
        type: error
        error:
          type: authentication_error
          message: Invalid API Key

    ErrorForbiddenExample:
      summary: Forbidden error
      value:
        type: error
        error:
          type: permission_error
          message: Your API key does not have permission to use this resource

    ErrorRateLimitExample:
      summary: Rate limit error
      value:
        type: error
        error:
          type: rate_limit_error
          message: Rate limit exceeded. Please retry after some time.

    ErrorServerExample:
      summary: Server error
      value:
        type: error
        error:
          type: api_error
          message: An internal server error occurred

    ErrorOverloadedExample:
      summary: API overloaded error
      value:
        type: error
        error:
          type: overloaded_error
          message: Anthropic's API is temporarily overloaded