openapi: 3.1.0
info:
  title: Anthropic Models 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.

    This API provides access to list available models, get model details,
    create messages, and count tokens.
  version: '2025-03-05'
  contact:
    name: Anthropic Support
    url: https://support.anthropic.com
  x-logo:
    url: https://www.anthropic.com/favicon.ico

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

security:
  - ApiKeyAuth: []

tags:
  - name: Messages
    description: APIs for creating conversational messages with Claude
  - name: Models
    description: APIs for listing and retrieving model information
  - name: Tokens
    description: APIs for counting tokens in messages

paths:
  /v1/models:
    get:
      summary: Anthropic List Available Models
      description: |
        List available models. The Models API response can be used to determine
        which models are available for use in the API. More recently released
        models are listed first.
      operationId: listModels
      tags:
        - Models
      x-microcks-operation:
        dispatcher: FALLBACK
        dispatcherRules: ""
        delay: 100
      parameters:
        - $ref: '#/components/parameters/AnthropicVersionHeader'
        - $ref: '#/components/parameters/AnthropicBetaHeader'
        - $ref: '#/components/parameters/BeforeIdQuery'
        - $ref: '#/components/parameters/AfterIdQuery'
        - $ref: '#/components/parameters/LimitQuery'
        - $ref: '#/components/parameters/ApiKeyHeader'
        - $ref: '#/components/parameters/ContentTypeHeader'
        - $ref: '#/components/parameters/BrowserAccessHeader'
      responses:
        '200':
          description: Successful Response
          headers:
            retry-after:
              $ref: '#/components/headers/RetryAfter'
            anthropic-ratelimit-requests-limit:
              $ref: '#/components/headers/RateLimitRequestsLimit'
            anthropic-ratelimit-requests-remaining:
              $ref: '#/components/headers/RateLimitRequestsRemaining'
            anthropic-ratelimit-requests-reset:
              $ref: '#/components/headers/RateLimitRequestsReset'
            anthropic-ratelimit-tokens-limit:
              $ref: '#/components/headers/RateLimitTokensLimit'
            anthropic-ratelimit-tokens-remaining:
              $ref: '#/components/headers/RateLimitTokensRemaining'
            anthropic-ratelimit-tokens-reset:
              $ref: '#/components/headers/RateLimitTokensReset'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListModelsResponse'
              examples:
                ListModelsSuccessExample:
                  $ref: '#/components/examples/ListModelsResponseExample'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                BadRequestExample:
                  $ref: '#/components/examples/ErrorBadRequestExample'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                UnauthorizedExample:
                  $ref: '#/components/examples/ErrorUnauthorizedExample'
        '429':
          description: Too Many Requests
          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'

  /v1/models/{model_id}:
    get:
      summary: Anthropic Get A Specific Model
      description: |
        Get a specific model. The Models API response can be used to determine
        information about a specific model or resolve a model alias to a model ID.
      operationId: getModel
      tags:
        - Models
      x-microcks-operation:
        dispatcher: FALLBACK
        dispatcherRules: ""
        delay: 100
      parameters:
        - $ref: '#/components/parameters/ModelIdPath'
        - $ref: '#/components/parameters/AnthropicVersionHeader'
        - $ref: '#/components/parameters/AnthropicBetaHeader'
        - $ref: '#/components/parameters/ApiKeyHeader'
        - $ref: '#/components/parameters/ContentTypeHeader'
        - $ref: '#/components/parameters/BrowserAccessHeader'
      responses:
        '200':
          description: Successful Response
          headers:
            retry-after:
              $ref: '#/components/headers/RetryAfter'
            anthropic-ratelimit-requests-limit:
              $ref: '#/components/headers/RateLimitRequestsLimit'
            anthropic-ratelimit-requests-remaining:
              $ref: '#/components/headers/RateLimitRequestsRemaining'
            anthropic-ratelimit-requests-reset:
              $ref: '#/components/headers/RateLimitRequestsReset'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ModelInfo'
              examples:
                GetModelSuccessExample:
                  $ref: '#/components/examples/ModelInfoExample'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                BadRequestExample:
                  $ref: '#/components/examples/ErrorBadRequestExample'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                UnauthorizedExample:
                  $ref: '#/components/examples/ErrorUnauthorizedExample'
        '404':
          description: Model Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                NotFoundExample:
                  $ref: '#/components/examples/ErrorNotFoundExample'
        '429':
          description: Too Many Requests
          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'

  /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 either single queries or stateless
        multi-turn conversations.
      operationId: createMessage
      tags:
        - Messages
      x-microcks-operation:
        dispatcher: FALLBACK
        dispatcherRules: ""
        delay: 100
      parameters:
        - $ref: '#/components/parameters/AnthropicVersionHeader'
        - $ref: '#/components/parameters/AnthropicBetaHeader'
        - $ref: '#/components/parameters/ApiKeyHeader'
        - $ref: '#/components/parameters/ContentTypeHeader'
        - $ref: '#/components/parameters/BrowserAccessHeader'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MessageRequest'
            examples:
              SimpleMessageExample:
                $ref: '#/components/examples/MessageRequestSimpleExample'
              MessageWithSystemExample:
                $ref: '#/components/examples/MessageRequestWithSystemExample'
              MessageWithToolsExample:
                $ref: '#/components/examples/MessageRequestWithToolsExample'
      responses:
        '200':
          description: Successful Response
          headers:
            retry-after:
              $ref: '#/components/headers/RetryAfter'
            anthropic-ratelimit-requests-limit:
              $ref: '#/components/headers/RateLimitRequestsLimit'
            anthropic-ratelimit-requests-remaining:
              $ref: '#/components/headers/RateLimitRequestsRemaining'
            anthropic-ratelimit-requests-reset:
              $ref: '#/components/headers/RateLimitRequestsReset'
            anthropic-ratelimit-tokens-limit:
              $ref: '#/components/headers/RateLimitTokensLimit'
            anthropic-ratelimit-tokens-remaining:
              $ref: '#/components/headers/RateLimitTokensRemaining'
            anthropic-ratelimit-tokens-reset:
              $ref: '#/components/headers/RateLimitTokensReset'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
              examples:
                MessageSuccessExample:
                  $ref: '#/components/examples/MessageResponseExample'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                BadRequestExample:
                  $ref: '#/components/examples/ErrorBadRequestExample'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                UnauthorizedExample:
                  $ref: '#/components/examples/ErrorUnauthorizedExample'
        '429':
          description: Too Many Requests
          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'

  /v1/messages/count_tokens:
    post:
      summary: Anthropic Count Tokens In A Message
      description: |
        Count the number of tokens in a message before sending it.
        This allows you to make informed decisions about message length
        and manage your token budget effectively.
      operationId: countTokens
      tags:
        - Tokens
      x-microcks-operation:
        dispatcher: FALLBACK
        dispatcherRules: ""
        delay: 100
      parameters:
        - $ref: '#/components/parameters/AnthropicVersionHeader'
        - $ref: '#/components/parameters/AnthropicBetaHeader'
        - $ref: '#/components/parameters/ApiKeyHeader'
        - $ref: '#/components/parameters/ContentTypeHeader'
        - $ref: '#/components/parameters/BrowserAccessHeader'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CountTokensRequest'
            examples:
              CountTokensExample:
                $ref: '#/components/examples/CountTokensRequestExample'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CountTokensResponse'
              examples:
                CountTokensSuccessExample:
                  $ref: '#/components/examples/CountTokensResponseExample'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                BadRequestExample:
                  $ref: '#/components/examples/ErrorBadRequestExample'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                UnauthorizedExample:
                  $ref: '#/components/examples/ErrorUnauthorizedExample'
        '429':
          description: Too Many Requests
          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'

components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: |
        Your unique API key for authentication. This key is required in the
        header of all API requests, to authenticate your account and access
        Anthropic's services. Get your API key through the Console. Each key is
        scoped to a Workspace.

  parameters:
    AnthropicVersionHeader:
      name: anthropic-version
      in: header
      required: true
      description: |
        The version of the Anthropic API you want to use. Read more about
        versioning and our version history here.
      schema:
        type: string
        default: '2023-06-01'

    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 like beta1,beta2 or
        specify the header multiple times for each beta.
      required: false
      schema:
        type: array
        items:
          type: string
      style: simple
      explode: false

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

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

    BrowserAccessHeader:
      name: anthropic-dangerous-direct-browser-access
      in: header
      required: false
      description: Enable CORS.
      schema:
        type: string
        default: "true"

    BeforeIdQuery:
      name: before_id
      in: query
      description: |
        ID of the object to use as a cursor for pagination. When provided,
        returns the page of results immediately before this object.
      schema:
        type: string

    AfterIdQuery:
      name: after_id
      in: query
      description: |
        ID of the object to use as a cursor for pagination. When provided,
        returns the page of results immediately after this object.
      schema:
        type: string

    LimitQuery:
      name: limit
      in: query
      description: |
        Number of items to return per page. Defaults to 20. Ranges from 1 to 1000.
      schema:
        type: integer
        minimum: 1
        maximum: 1000
        default: 20

    ModelIdPath:
      name: model_id
      in: path
      required: true
      description: Model identifier or alias.
      schema:
        type: string
      example: claude-sonnet-4-20250514

  headers:
    RetryAfter:
      description: |
        The number of seconds to wait until you can retry the request.
        Earlier retries will fail.
      schema:
        type: string

    RateLimitRequestsLimit:
      description: |
        The maximum number of requests allowed within any rate limit period.
      schema:
        type: string

    RateLimitRequestsRemaining:
      description: |
        The number of requests remaining before being rate limited.
      schema:
        type: string

    RateLimitRequestsReset:
      description: |
        The time when the request rate limit will be fully replenished,
        provided in RFC 3339 format.
      schema:
        type: string

    RateLimitTokensLimit:
      description: |
        The maximum number of tokens allowed within any rate limit period.
      schema:
        type: string

    RateLimitTokensRemaining:
      description: |
        The number of tokens remaining (rounded to the nearest thousand)
        before being rate limited.
      schema:
        type: string

    RateLimitTokensReset:
      description: |
        The time when the token rate limit will be fully replenished,
        provided in RFC 3339 format.
      schema:
        type: string

  schemas:
    # Model Schemas
    ModelInfo:
      type: object
      required:
        - id
        - type
        - display_name
        - created_at
      properties:
        id:
          type: string
          description: Unique identifier for the model.
        type:
          type: string
          enum:
            - model
          description: Object type. For models, this is always "model".
        display_name:
          type: string
          description: Human-readable name of the model.
        created_at:
          type: string
          format: date-time
          description: The date and time when the model was created.

    ListModelsResponse:
      type: object
      required:
        - data
        - first_id
        - has_more
        - last_id
      properties:
        data:
          type: array
          description: List of available models
          items:
            $ref: '#/components/schemas/ModelInfo'
        first_id:
          type: string
          nullable: true
          description: |
            First ID in the data list. Can be used as the before_id for the previous page.
        has_more:
          type: boolean
          description: |
            Indicates if there are more results in the requested page direction.
        last_id:
          type: string
          nullable: true
          description: |
            Last ID in the data list. Can be used as the after_id for the next page.

    # Message Schemas
    TextContentBlock:
      type: object
      required:
        - type
        - text
      properties:
        type:
          type: string
          enum:
            - text
        text:
          type: string
          description: The text content

    ImageSourceBlock:
      type: object
      required:
        - type
        - media_type
        - data
      properties:
        type:
          type: string
          enum:
            - base64
        media_type:
          type: string
          enum:
            - image/jpeg
            - image/png
            - image/gif
            - image/webp
        data:
          type: string
          format: byte
          description: Base64 encoded image data

    ImageContentBlock:
      type: object
      required:
        - type
        - source
      properties:
        type:
          type: string
          enum:
            - image
        source:
          $ref: '#/components/schemas/ImageSourceBlock'

    ToolUseContentBlock:
      type: object
      required:
        - type
        - id
        - name
        - input
      properties:
        type:
          type: string
          enum:
            - tool_use
        id:
          type: string
          description: Unique identifier for this tool use
        name:
          type: string
          description: Name of the tool to use
        input:
          type: object
          description: Input parameters for the tool

    ToolResultContentBlock:
      type: object
      required:
        - type
        - tool_use_id
        - content
      properties:
        type:
          type: string
          enum:
            - tool_result
        tool_use_id:
          type: string
          description: ID of the tool use this result corresponds to
        content:
          oneOf:
            - type: string
            - type: array
              items:
                $ref: '#/components/schemas/ContentBlock'
        is_error:
          type: boolean
          description: Whether this tool result represents an error

    ContentBlock:
      oneOf:
        - $ref: '#/components/schemas/TextContentBlock'
        - $ref: '#/components/schemas/ImageContentBlock'
        - $ref: '#/components/schemas/ToolUseContentBlock'
        - $ref: '#/components/schemas/ToolResultContentBlock'

    InputMessage:
      type: object
      required:
        - role
        - content
      properties:
        role:
          type: string
          enum:
            - user
            - assistant
          description: The role of the message author
        content:
          oneOf:
            - type: string
            - type: array
              items:
                $ref: '#/components/schemas/ContentBlock'
          description: |
            The content of the message. Can be a single string or an array of content blocks.

    SystemContentBlock:
      type: object
      required:
        - type
        - text
      properties:
        type:
          type: string
          enum:
            - text
        text:
          type: string

    ToolDefinition:
      type: object
      required:
        - name
        - input_schema
      properties:
        name:
          type: string
          description: Name of the tool
        description:
          type: string
          description: Optional, but strongly-recommended description of the tool
        input_schema:
          type: object
          description: JSON schema for the tool input shape
          properties:
            type:
              type: string
              enum:
                - object
            properties:
              type: object
            required:
              type: array
              items:
                type: string

    ToolChoiceAuto:
      type: object
      required:
        - type
      properties:
        type:
          type: string
          enum:
            - auto

    ToolChoiceAny:
      type: object
      required:
        - type
      properties:
        type:
          type: string
          enum:
            - any

    ToolChoiceTool:
      type: object
      required:
        - type
        - name
      properties:
        type:
          type: string
          enum:
            - tool
        name:
          type: string
          description: Name of the specific tool to use

    ToolChoiceNone:
      type: object
      required:
        - type
      properties:
        type:
          type: string
          enum:
            - none

    ToolChoice:
      oneOf:
        - $ref: '#/components/schemas/ToolChoiceAuto'
        - $ref: '#/components/schemas/ToolChoiceAny'
        - $ref: '#/components/schemas/ToolChoiceTool'
        - $ref: '#/components/schemas/ToolChoiceNone'

    ThinkingConfig:
      type: object
      description: |
        Configuration for enabling Claude's extended thinking. When enabled,
        responses include thinking content blocks showing Claude's thinking
        process before the final answer.
      properties:
        enabled:
          type: boolean
          description: Whether to enable extended thinking

    MetadataInfo:
      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

    UsageInfo:
      type: object
      required:
        - input_tokens
        - output_tokens
      description: |
        Billing and rate-limit usage. Anthropic's API bills and rate-limits by
        token counts, as tokens represent the underlying cost to our systems.
      properties:
        input_tokens:
          type: integer
          description: Number of input tokens consumed
        output_tokens:
          type: integer
          description: Number of output tokens generated
        cache_creation_input_tokens:
          type: integer
          description: Number of tokens used for cache creation
        cache_read_input_tokens:
          type: integer
          description: Number of tokens read from cache

    ContainerInfo:
      type: object
      description: |
        Information about the container used in this request. This will be
        non-null if a container tool (e.g. code execution) was used.
      properties:
        id:
          type: string
          description: Container identifier
        status:
          type: string
          description: Container status

    # Request Schemas
    MessageRequest:
      type: object
      required:
        - model
        - messages
        - max_tokens
      properties:
        model:
          type: string
          description: |
            The model that will complete your prompt. See models for additional
            details and options.
          minLength: 1
          maxLength: 256
        messages:
          type: array
          description: |
            Input messages. Our models are trained to operate on alternating
            user and assistant conversational turns. When creating a new
            Message, you specify the prior conversational turns with the
            messages parameter, and the model then generates the next Message in
            the conversation.
          maxItems: 100000
          items:
            $ref: '#/components/schemas/InputMessage'
        max_tokens:
          type: integer
          description: |
            The maximum number of tokens to generate before stopping. Note that
            our models may stop before reaching this maximum. This parameter
            only specifies the absolute maximum number of tokens to generate.
          minimum: 1
        container:
          type: string
          nullable: true
          description: Container identifier for reuse across requests.
        metadata:
          $ref: '#/components/schemas/MetadataInfo'
        service_tier:
          type: string
          enum:
            - auto
            - standard_only
          description: |
            Determines whether to use priority capacity (if available) or
            standard capacity for this request.
        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.
        system:
          oneOf:
            - type: string
            - type: array
              items:
                $ref: '#/components/schemas/SystemContentBlock'
          description: |
            System prompt. A system prompt is a way of providing context and
            instructions to Claude, such as specifying a particular goal or role.
        temperature:
          type: number
          description: |
            Amount of randomness injected into the response. Defaults to 1.0.
            Ranges from 0.0 to 1.0.
          minimum: 0
          maximum: 1
        thinking:
          $ref: '#/components/schemas/ThinkingConfig'
        tool_choice:
          $ref: '#/components/schemas/ToolChoice'
        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.
          items:
            $ref: '#/components/schemas/ToolDefinition'
        top_k:
          type: integer
          description: |
            Only sample from the top K options for each subsequent token.
          minimum: 0
        top_p:
          type: number
          description: |
            Use nucleus sampling.
          minimum: 0
          maximum: 1

    # Response Schemas
    ResponseContentBlock:
      oneOf:
        - $ref: '#/components/schemas/TextContentBlock'
        - $ref: '#/components/schemas/ThinkingContentBlock'
        - $ref: '#/components/schemas/ToolUseContentBlock'
        - $ref: '#/components/schemas/ServerToolUseContentBlock'
        - $ref: '#/components/schemas/WebSearchResultBlock'
        - $ref: '#/components/schemas/CodeExecutionResultBlock'
        - $ref: '#/components/schemas/McpToolUseContentBlock'
        - $ref: '#/components/schemas/McpToolResultBlock'
        - $ref: '#/components/schemas/ContainerUploadBlock'

    ThinkingContentBlock:
      type: object
      required:
        - type
        - text
      properties:
        type:
          type: string
          enum:
            - thinking
        text:
          type: string
          description: Claude's thinking process

    ServerToolUseContentBlock:
      type: object
      required:
        - type
        - id
        - name
        - input
      properties:
        type:
          type: string
          enum:
            - server_tool_use
        id:
          type: string
        name:
          type: string
        input:
          type: object

    WebSearchResultBlock:
      type: object
      required:
        - type
        - id
        - name
        - input
        - result
      properties:
        type:
          type: string
          enum:
            - web_search_result
        id:
          type: string
        name:
          type: string
        input:
          type: object
        result:
          type: object

    CodeExecutionResultBlock:
      type: object
      required:
        - type
        - id
        - name
        - input
        - result
      properties:
        type:
          type: string
          enum:
            - code_execution_result
        id:
          type: string
        name:
          type: string
        input:
          type: object
        result:
          type: object

    McpToolUseContentBlock:
      type: object
      required:
        - type
        - id
        - name
        - input
      properties:
        type:
          type: string
          enum:
            - mcp_tool_use
        id:
          type: string
        name:
          type: string
        input:
          type: object

    McpToolResultBlock:
      type: object
      required:
        - type
        - id
        - name
        - input
        - result
      properties:
        type:
          type: string
          enum:
            - mcp_tool_result
        id:
          type: string
        name:
          type: string
        input:
          type: object
        result:
          type: object

    ContainerUploadBlock:
      type: object
      required:
        - type
        - container_id
        - path
        - size
      properties:
        type:
          type: string
          enum:
            - container_upload
        container_id:
          type: string
        path:
          type: string
        size:
          type: integer

    MessageResponse:
      type: object
      required:
        - id
        - type
        - role
        - content
        - model
        - stop_reason
        - stop_sequence
        - usage
      properties:
        id:
          type: string
          description: |
            Unique object identifier. The format and length of IDs may change over time.
        type:
          type: string
          enum:
            - message
          default: message
          description: Object type. For Messages, this is always "message".
        role:
          type: string
          enum:
            - assistant
          default: assistant
          description: |
            Conversational role of the generated message. This will always be "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/ResponseContentBlock'
        model:
          type: string
          description: The model that handled the request
          minLength: 1
          maxLength: 256
        stop_reason:
          type: string
          enum:
            - end_turn
            - max_tokens
            - stop_sequence
            - tool_use
            - pause_turn
            - refusal
          nullable: true
          description: |
            The reason that we stopped. This may be one the following values:
            - "end_turn": the model reached a natural stopping point
            - "max_tokens": we exceeded the requested max_tokens or the model's maximum
            - "stop_sequence": one of your provided custom stop_sequences was generated
            - "tool_use": the model invoked one or more tools
            - "pause_turn": we paused a long-running turn
            - "refusal": when streaming classifiers intervene
        stop_sequence:
          type: string
          nullable: true
          description: |
            Which custom stop sequence was generated, if any.
        usage:
          $ref: '#/components/schemas/UsageInfo'
        container:
          $ref: '#/components/schemas/ContainerInfo'

    # Count Tokens Schemas
    CountTokensRequest:
      type: object
      required:
        - model
        - messages
      properties:
        messages:
          type: array
          description: |
            Input messages to count tokens for.
          maxItems: 100000
          items:
            $ref: '#/components/schemas/InputMessage'
        model:
          type: string
          description: |
            The model that will complete your prompt.
          minLength: 1
          maxLength: 256
        system:
          oneOf:
            - type: string
            - type: array
              items:
                $ref: '#/components/schemas/SystemContentBlock'
          description: System prompt to include in token count.
        thinking:
          $ref: '#/components/schemas/ThinkingConfig'
        tool_choice:
          $ref: '#/components/schemas/ToolChoice'
        tools:
          type: array
          description: Tools to include in token count.
          items:
            $ref: '#/components/schemas/ToolDefinition'

    CountTokensResponse:
      type: object
      required:
        - input_tokens
      properties:
        input_tokens:
          type: integer
          description: |
            The total number of tokens across the provided list of messages,
            system prompt, and tools.

    # Error Schema
    ErrorResponse:
      type: object
      required:
        - type
        - message
      properties:
        type:
          type: string
          description: The type of error
        message:
          type: string
          description: A human-readable error message

  examples:
    # Model Examples
    ModelInfoExample:
      summary: Claude Sonnet 4 model info
      value:
        id: claude-sonnet-4-20250514
        type: model
        display_name: Claude Sonnet 4
        created_at: "2025-05-14T00:00:00Z"

    ListModelsResponseExample:
      summary: List of available models
      value:
        data:
          - id: claude-sonnet-4-20250514
            type: model
            display_name: Claude Sonnet 4
            created_at: "2025-05-14T00:00:00Z"
          - id: claude-3-5-sonnet-20241022
            type: model
            display_name: Claude 3.5 Sonnet
            created_at: "2024-10-22T00:00:00Z"
          - id: claude-3-haiku-20240307
            type: model
            display_name: Claude 3 Haiku
            created_at: "2024-03-07T00:00:00Z"
        first_id: claude-sonnet-4-20250514
        has_more: true
        last_id: claude-3-haiku-20240307

    # Message Request Examples
    MessageRequestSimpleExample:
      summary: Simple message request
      value:
        model: claude-sonnet-4-20250514
        max_tokens: 1024
        messages:
          - role: user
            content: "Hello, Claude! How are you today?"

    MessageRequestWithSystemExample:
      summary: Message request with system prompt
      value:
        model: claude-sonnet-4-20250514
        max_tokens: 1024
        system: "You are a helpful assistant that specializes in explaining complex topics simply."
        messages:
          - role: user
            content: "Can you explain quantum computing to me?"

    MessageRequestWithToolsExample:
      summary: Message request with tools
      value:
        model: claude-sonnet-4-20250514
        max_tokens: 1024
        messages:
          - role: user
            content: "What's the weather like in San Francisco?"
        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"
                unit:
                  type: string
                  description: "Unit for the output - one of (celsius, fahrenheit)"
              required:
                - location

    # Message Response Examples
    MessageResponseExample:
      summary: Successful message response
      value:
        id: msg_013Zva2CMHLNnXjNJJKqJ2EF
        type: message
        role: assistant
        content:
          - type: text
            text: "Hi! My name is Claude. I'm doing well, thank you for asking! How can I help you today?"
        model: claude-sonnet-4-20250514
        stop_reason: end_turn
        stop_sequence:
        usage:
          input_tokens: 12
          output_tokens: 25

    # Count Tokens Examples
    CountTokensRequestExample:
      summary: Count tokens request
      value:
        model: claude-sonnet-4-20250514
        messages:
          - role: user
            content: "Hello, how are you?"

    CountTokensResponseExample:
      summary: Count tokens response
      value:
        input_tokens: 2095

    # Error Examples
    ErrorBadRequestExample:
      summary: Bad request error
      value:
        type: invalid_request_error
        message: Invalid request format

    ErrorUnauthorizedExample:
      summary: Unauthorized error
      value:
        type: authentication_error
        message: Invalid or missing API key

    ErrorNotFoundExample:
      summary: Not found error
      value:
        type: not_found_error
        message: The requested model was not found

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

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