Anthropic Messages API

openapi: 3.1.0
info:
  title: Anthropic Admin Agents Messages API
  description: Manage administrative functions for Anthropic organizations, workspaces, users, invites, and API keys.
  version: 1.0.0
  contact:
    name: Anthropic
    url: https://www.anthropic.com
    email: support@anthropic.com
  license:
    name: Anthropic API License
    url: https://www.anthropic.com/terms
servers:
- url: https://api.anthropic.com/v1
  description: Production Server
security:
- AdminApiKeyAuth: []
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:
  schemas:
    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'
    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'
    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'
    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'
    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
    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'
    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
    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
    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.

            '
    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'
    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
    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
    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'
    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'
    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.
    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'
    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.

            '
    ImageBlockParam:
      type: object
      required:
      - type
      - source
      properties:
        type:
          type: string
          enum:
          - image
        source:
          $ref: '#/components/schemas/ImageSource'
        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.
    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'
    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).
    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
    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.
    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
          - null
        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'
    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).
    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'
  examples:
    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?
    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: null
        usage:
          input_tokens: 10
          output_tokens: 15
          cache_creation_input_tokens: 0
          cache_read_input_tokens: 0
    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
    ErrorRateLimitExample:
      summary: Rate limit error
      value:
        type: error
        error:
          type: rate_limit_error
          message: Rate limit exceeded. Please retry after some time.
    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: null
        usage:
          input_tokens: 380
          output_tokens: 65
          cache_creation_input_tokens: 0
          cache_read_input_tokens: 0
    SimpleMessageRequestExample:
      summary: Simple text message
      value:
        model: claude-opus-4-6
        max_tokens: 1024
        messages:
        - role: user
          content: Hello, Claude
    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?
    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
  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'
    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
    ApiKeyHeader:
      name: x-api-key
      in: header
      required: true
      description: A valid Anthropic API key.
      schema:
        type: string
  securitySchemes:
    AdminApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: Your Admin API key for authentication (starts with sk-ant-admin...).