Claude Message Batches API

openapi: 3.1.0
info:
  title: Claude Messages Message Batches API
  description: Anthropic's Claude Messages API for sending messages to Claude models and receiving responses. Includes endpoints for creating messages, counting tokens, managing message batches, and listing available models.
  version: 2023-06-01
  termsOfService: https://www.anthropic.com/legal/commercial-terms
  contact:
    name: Anthropic Support
    url: https://support.anthropic.com
    email: support@anthropic.com
  license:
    name: Anthropic API Terms
    url: https://www.anthropic.com/legal/commercial-terms
servers:
- url: https://api.anthropic.com/v1
  description: Anthropic Production API
security:
- ApiKeyAuth: []
tags:
- name: Message Batches
  description: Create and manage asynchronous message batches
  externalDocs:
    url: https://docs.anthropic.com/en/api/creating-message-batches
paths:
  /messages/batches:
    post:
      operationId: createMessageBatch
      summary: Create a Message Batch
      description: Send a batch of message creation requests for asynchronous processing. Batches begin processing immediately and can take up to 24 hours to complete. Results are available at a 50 percent discount compared to standard API calls.
      tags:
      - Message Batches
      parameters:
      - $ref: '#/components/parameters/AnthropicVersion'
      - $ref: '#/components/parameters/AnthropicBeta'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateMessageBatchRequest'
      responses:
        '200':
          description: Message batch created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageBatch'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    get:
      operationId: listMessageBatches
      summary: List Message Batches
      description: List all message batches within a workspace.
      tags:
      - Message Batches
      parameters:
      - $ref: '#/components/parameters/AnthropicVersion'
      - $ref: '#/components/parameters/AnthropicBeta'
      - name: after_id
        in: query
        description: ID of the object to use as a cursor for pagination. Returns the page of results immediately after this object.
        schema:
          type: string
      - name: before_id
        in: query
        description: ID of the object to use as a cursor for pagination. Returns the page of results immediately before this object.
        schema:
          type: string
      - name: limit
        in: query
        description: Number of items to return per page.
        schema:
          type: integer
          default: 20
          minimum: 1
          maximum: 1000
      responses:
        '200':
          description: List of message batches
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageBatchList'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /messages/batches/{message_batch_id}:
    get:
      operationId: retrieveMessageBatch
      summary: Retrieve a Message Batch
      description: Retrieve the status and details of a specific message batch.
      tags:
      - Message Batches
      parameters:
      - $ref: '#/components/parameters/AnthropicVersion'
      - $ref: '#/components/parameters/AnthropicBeta'
      - $ref: '#/components/parameters/MessageBatchId'
      responses:
        '200':
          description: Message batch details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageBatch'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    delete:
      operationId: deleteMessageBatch
      summary: Delete a Message Batch
      description: Delete a completed message batch. The batch must have a processing_status of ended before it can be deleted.
      tags:
      - Message Batches
      parameters:
      - $ref: '#/components/parameters/AnthropicVersion'
      - $ref: '#/components/parameters/AnthropicBeta'
      - $ref: '#/components/parameters/MessageBatchId'
      responses:
        '200':
          description: Message batch deleted successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeletedMessageBatch'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /messages/batches/{message_batch_id}/results:
    get:
      operationId: retrieveMessageBatchResults
      summary: Retrieve Message Batch Results
      description: Stream the results of a completed message batch as a JSONL file. Each line contains a JSON object with a custom_id and result.
      tags:
      - Message Batches
      parameters:
      - $ref: '#/components/parameters/AnthropicVersion'
      - $ref: '#/components/parameters/AnthropicBeta'
      - $ref: '#/components/parameters/MessageBatchId'
      responses:
        '200':
          description: Batch results as JSONL stream
          content:
            application/x-jsonlines:
              schema:
                $ref: '#/components/schemas/MessageBatchResult'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /messages/batches/{message_batch_id}/cancel:
    post:
      operationId: cancelMessageBatch
      summary: Cancel a Message Batch
      description: Cancel an in-progress message batch. Cancellation is asynchronous and already-processed requests cannot be undone.
      tags:
      - Message Batches
      parameters:
      - $ref: '#/components/parameters/AnthropicVersion'
      - $ref: '#/components/parameters/AnthropicBeta'
      - $ref: '#/components/parameters/MessageBatchId'
      responses:
        '200':
          description: Message batch cancellation initiated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageBatch'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  schemas:
    BatchRequestItem:
      type: object
      description: A single request within a message batch.
      required:
      - custom_id
      - params
      properties:
        custom_id:
          type: string
          description: Developer-provided identifier for this request. Must be unique within the batch. Used to match results to requests.
          example: request-1
        params:
          $ref: '#/components/schemas/CreateMessageRequest'
    ToolUseBlockParam:
      type: object
      description: A tool use content block in a request (for multi-turn tool use).
      required:
      - type
      - id
      - name
      - input
      properties:
        type:
          type: string
          const: tool_use
          example: example_value
        id:
          type: string
          description: The unique identifier for this tool use.
          example: abc123
        name:
          type: string
          description: The name of the tool.
          example: Example Title
        input:
          type: object
          description: The input to the tool.
          additionalProperties: true
          example: example_value
        cache_control:
          $ref: '#/components/schemas/CacheControl'
    DocumentBlockParam:
      type: object
      description: A document content block for PDFs and text documents.
      required:
      - type
      - source
      properties:
        type:
          type: string
          const: document
          example: example_value
        source:
          type: object
          description: The source of the document.
          required:
          - type
          properties:
            type:
              type: string
              description: The type of document source.
              enum:
              - base64
              - url
              - text
              - 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.
            url:
              type: string
              format: uri
              description: URL of the document.
          example: example_value
        title:
          type: string
          description: Optional title for the document.
          example: Example Title
        context:
          type: string
          description: Optional context about the document.
          example: example_value
        citations:
          type: object
          description: Citation configuration for the document.
          properties:
            enabled:
              type: boolean
          example: example_value
        cache_control:
          $ref: '#/components/schemas/CacheControl'
    Tool:
      type: object
      description: Definition of a tool that the model can use.
      required:
      - name
      - input_schema
      properties:
        name:
          type: string
          description: The name of the tool. Must match the regex ^[a-zA-Z0-9_-]{1,64}$.
          pattern: ^[a-zA-Z0-9_-]{1,64}$
          example: get_stock_price
        description:
          type: string
          description: A detailed description of what the tool does, when it should be used, and what each parameter means.
          example: A sample description.
        input_schema:
          type: object
          description: JSON Schema object defining the expected parameters for the tool.
          properties:
            type:
              type: string
              const: object
            properties:
              type: object
              additionalProperties: true
            required:
              type: array
              items:
                type: string
          required:
          - type
          example: example_value
        cache_control:
          $ref: '#/components/schemas/CacheControl'
        type:
          type: string
          description: The type of tool. Omit for custom tools. Use specific type strings for server tools like web_search_20260209, code_execution_20260120, text_editor_20250728, etc.
          example: example_value
    ImageBlockParam:
      type: object
      description: An image content block. Supports base64-encoded or URL-referenced images.
      required:
      - type
      - source
      properties:
        type:
          type: string
          const: image
          example: example_value
        source:
          type: object
          description: The source of the image.
          required:
          - type
          properties:
            type:
              type: string
              description: The type of image source.
              enum:
              - base64
              - url
            media_type:
              type: string
              description: The media type of the image.
              enum:
              - image/jpeg
              - image/png
              - image/gif
              - image/webp
            data:
              type: string
              description: Base64-encoded image data. Required when type is base64.
            url:
              type: string
              format: uri
              description: URL of the image. Required when type is url.
          example: example_value
        cache_control:
          $ref: '#/components/schemas/CacheControl'
    Message:
      type: object
      description: A message response from Claude.
      properties:
        id:
          type: string
          description: Unique object identifier for the message.
          pattern: ^msg_
          example: msg_01XFDUDYJgAACzvnptvVoYEL
        type:
          type: string
          description: Object type. Always "message" for message responses.
          const: message
          example: example_value
        role:
          type: string
          description: Conversational role of the generated message. Always "assistant".
          const: assistant
          example: example_value
        content:
          type: array
          description: Content generated by the model. Array of content blocks, each of which has a type that determines its shape.
          items:
            $ref: '#/components/schemas/ContentBlock'
          example: []
        model:
          type: string
          description: The model that handled the request.
          example: claude-sonnet-4-6
        stop_reason:
          type: string
          description: The reason the model stopped generating tokens.
          enum:
          - end_turn
          - max_tokens
          - stop_sequence
          - tool_use
          nullable: true
          example: end_turn
        stop_sequence:
          type: string
          description: The stop sequence that caused the model to stop, if applicable. Null if the model stopped for another reason.
          nullable: true
          example: example_value
        usage:
          $ref: '#/components/schemas/Usage'
      required:
      - id
      - type
      - role
      - content
      - model
      - stop_reason
      - usage
    MessageBatch:
      type: object
      description: A message batch object representing an asynchronous batch of message requests.
      properties:
        id:
          type: string
          description: Unique identifier for the message batch.
          pattern: ^msgbatch_
          example: msgbatch_01HkcTjaV5uDC8jWR4ZsDV8d
        type:
          type: string
          description: Object type. Always "message_batch".
          const: message_batch
          example: example_value
        processing_status:
          type: string
          description: The processing status of the batch.
          enum:
          - in_progress
          - canceling
          - ended
          example: in_progress
        request_counts:
          type: object
          description: Tallies of requests by their status within the batch.
          properties:
            processing:
              type: integer
              description: Number of requests still being processed.
            succeeded:
              type: integer
              description: Number of requests that completed successfully.
            errored:
              type: integer
              description: Number of requests that encountered errors.
            canceled:
              type: integer
              description: Number of requests that were canceled.
            expired:
              type: integer
              description: Number of requests that expired.
          example: example_value
        ended_at:
          type: string
          format: date-time
          description: RFC 3339 datetime when the batch ended processing.
          nullable: true
          example: '2026-01-15T10:30:00Z'
        created_at:
          type: string
          format: date-time
          description: RFC 3339 datetime when the batch was created.
          example: '2026-01-15T10:30:00Z'
        expires_at:
          type: string
          format: date-time
          description: RFC 3339 datetime when the batch results will expire.
          example: '2026-01-15T10:30:00Z'
        results_url:
          type: string
          format: uri
          description: URL to retrieve the batch results. Available when the batch is complete.
          nullable: true
          example: https://www.example.com
      required:
      - id
      - type
      - processing_status
      - request_counts
      - created_at
      - expires_at
    CreateMessageBatchRequest:
      type: object
      required:
      - requests
      properties:
        requests:
          type: array
          description: Array of batch request objects. Each contains a custom_id and params.
          items:
            $ref: '#/components/schemas/BatchRequestItem'
          minItems: 1
          example: []
    ToolChoice:
      type: object
      description: How the model should use the provided tools.
      required:
      - type
      properties:
        type:
          type: string
          description: The type of tool choice. "auto" lets the model decide, "any" forces tool use, "tool" forces a specific tool, "none" disables tools.
          enum:
          - auto
          - any
          - tool
          - none
          example: auto
        name:
          type: string
          description: The name of the tool to use. Required when type is "tool".
          example: Example Title
        disable_parallel_tool_use:
          type: boolean
          description: Whether to disable parallel tool use.
          example: true
    MessageBatchList:
      type: object
      description: Paginated list of message batches.
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/MessageBatch'
          example: []
        has_more:
          type: boolean
          description: Whether there are more results available.
          example: true
        first_id:
          type: string
          description: ID of the first item. Use as before_id for the previous page.
          nullable: true
          example: '500123'
        last_id:
          type: string
          description: ID of the last item. Use as after_id for the next page.
          nullable: true
          example: '500123'
    ToolUseBlock:
      type: object
      description: A tool use content block in a response, indicating the model wants to use a tool.
      required:
      - type
      - id
      - name
      - input
      properties:
        type:
          type: string
          const: tool_use
          example: example_value
        id:
          type: string
          description: A unique identifier for this particular tool use block. Used to match tool results to tool use requests.
          pattern: ^toolu_
          example: toolu_01D7FLrfh4GYq7yT1ULFeyMV
        name:
          type: string
          description: The name of the tool being used.
          example: Example Title
        input:
          type: object
          description: An object containing the input passed to the tool, conforming to the tool's input_schema.
          additionalProperties: true
          example: example_value
    MessageParam:
      type: object
      description: An input message in the conversation.
      required:
      - role
      - content
      properties:
        role:
          type: string
          description: The role of the message author.
          enum:
          - user
          - assistant
          example: user
        content:
          description: The content of the message. Can be a string or array of content blocks.
          oneOf:
          - type: string
          - type: array
            items:
              $ref: '#/components/schemas/ContentBlockParam'
          example: example_value
    ToolResultBlockParam:
      type: object
      description: A tool result content block, providing the output from a tool invocation.
      required:
      - type
      - tool_use_id
      properties:
        type:
          type: string
          const: tool_result
          example: example_value
        tool_use_id:
          type: string
          description: The id of the tool use request this is a result for. Must match a tool_use block id.
          example: '500123'
        content:
          description: The result of the tool call. Can be a string or array of content blocks.
          oneOf:
          - type: string
          - type: array
            items:
              oneOf:
              - $ref: '#/components/schemas/TextBlockParam'
              - $ref: '#/components/schemas/ImageBlockParam'
          example: example_value
        is_error:
          type: boolean
          description: Set to true if the tool execution resulted in an error.
          default: false
          example: true
        cache_control:
          $ref: '#/components/schemas/CacheControl'
    Error:
      type: object
      description: An error response from the API.
      required:
      - type
      - error
      properties:
        type:
          type: string
          const: error
          example: example_value
        error:
          type: object
          required:
          - type
          - message
          properties:
            type:
              type: string
              description: The type of error.
              enum:
              - invalid_request_error
              - authentication_error
              - permission_error
              - not_found_error
              - rate_limit_error
              - api_error
              - overloaded_error
            message:
              type: string
              description: A human-readable description of the error.
          example: example_value
    ContentBlockParam:
      description: A content block in a message request.
      oneOf:
      - $ref: '#/components/schemas/TextBlockParam'
      - $ref: '#/components/schemas/ImageBlockParam'
      - $ref: '#/components/schemas/DocumentBlockParam'
      - $ref: '#/components/schemas/ToolUseBlockParam'
      - $ref: '#/components/schemas/ToolResultBlockParam'
      - $ref: '#/components/schemas/ThinkingBlockParam'
      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'
          thinking: '#/components/schemas/ThinkingBlockParam'
    Metadata:
      type: object
      description: Request metadata for tracking and abuse prevention.
      properties:
        user_id:
          type: string
          description: An external identifier for the user making the request. Should be a UUID, hash, or other opaque identifier.
          example: '500123'
    ThinkingBlockParam:
      type: object
      description: A thinking content block in a request (for multi-turn with extended thinking).
      required:
      - type
      - thinking
      - signature
      properties:
        type:
          type: string
          const: thinking
          example: example_value
        thinking:
          type: string
          description: The thinking text from a previous response.
          example: example_value
        signature:
          type: string
          description: The signature from the previous thinking block.
          example: example_value
    OutputConfig:
      type: object
      description: Configuration for structured output format.
      properties:
        type:
          type: string
          description: The output format type.
          enum:
          - json_schema
          example: json_schema
        schema:
          type: object
          description: JSON Schema defining the expected output structure.
          additionalProperties: true
          example: example_value
    TextBlockParam:
      type: object
      description: A text content block in a request.
      required:
      - type
      - text
      properties:
        type:
          type: string
          const: text
          example: example_value
        text:
          type: string
          description: The text content.
          example: example_value
        cache_control:
          $ref: '#/components/schemas/CacheControl'
    CacheControl:
      type: object
      description: Cache control settings for prompt caching.
      required:
      - type
      properties:
        type:
          type: string
          const: ephemeral
          example: example_value
        ttl:
          type: string
          description: Time-to-live for the cache entry.
          enum:
          - 5m
          - 1h
          example: 5m
    Usage:
      type: object
      description: Token usage information for the request.
      required:
      - input_tokens
      - output_tokens
      properties:
        input_tokens:
          type: integer
          description: The number of input tokens consumed.
          example: 25
        output_tokens:
          type: integer
          description: The number of output tokens generated.
          example: 150
        cache_creation_input_tokens:
          type: integer
          description: The number of input tokens used to create a cache entry.
          example: 10
        cache_read_input_tokens:
          type: integer
          description: The number of input tokens read from cache.
          example: 10
    DeletedMessageBatch:
      type: object
      description: Confirmation of a deleted message batch.
      properties:
        id:
          type: string
          description: The ID of the deleted batch.
          example: abc123
        type:
          type: string
          const: message_batch_deleted
          example: example_value
    ThinkingBlock:
      type: object
      description: A thinking content block showing Claude's internal reasoning process.
      required:
      - type
      - thinking
      - signature
      properties:
        type:
          type: string
          const: thinking
          example: example_value
        thinking:
          type: string
          description: Claude's internal reasoning text.
          example: example_value
        signature:
          type: string
          description: A signature verifying the thinking block.
          example: example_value
    CreateMessageRequest:
      type: object
      required:
      - model
      - max_tokens
      - messages
      properties:
        model:
          type: string
          description: The model that will complete your prompt. See the list of available models.
          example: claude-sonnet-4-6
        max_tokens:
          type: integer
          description: The maximum number of tokens to generate before stopping. Different models support different maximum values.
          minimum: 1
          example: 1024
        messages:
          type: array
          description: Input messages. Alternating user and assistant conversational turns. Maximum 100,000 messages per request.
          items:
            $ref: '#/components/schemas/MessageParam'
          minItems: 1
          example: []
        system:
          description: System prompt providing context and instructions to Claude. Can be a string or array of content blocks.
          oneOf:
          - type: string
          - type: array
            items:
              $ref: '#/components/schemas/TextBlockParam'
          example: example_value
        temperature:
          type: number
          description: Amount of randomness injected into the response. Ranges from 0.0 to 1.0. Use closer to 0.0 for analytical tasks, closer to 1.0 for creative tasks.
          minimum: 0.0
          maximum: 1.0
          default: 1.0
          example: 42.5
        top_p:
          type: number
          description: Use nucleus sampling. Recommended to use either temperature or top_p, but not both.
          minimum: 0.0
          maximum: 1.0
          example: 42.5
        top_k:
          type: integer
          description: Only sample from the top K options for each subsequent token.
          minimum: 1
          example: 10
        stop_sequences:
          type: array
          description: Custom text sequences that will cause the model to stop generating.
          items:
            type: string
          example: []
        stream:
          type: boolean
          description: Whether to incrementally stream the response using server-sent events.
          default: false
          example: true
        metadata:
          $ref: '#/components/schemas/Metadata'
        tools:
          type: array
          description: Definitions of tools that the model may use.
          items:
            $ref: '#/components/schemas/Tool'
          example: []
        tool_choice:
          $ref: '#/components/schemas/ToolChoice'
        thinking:
          $ref: '#/components/schemas/ThinkingConfig'
        output_config:
          $ref: '#/components/schemas/OutputConfig'
        service_tier:
          type: string
          description: Service tier to use for this request.
          enum:
          - auto
          - standard_only
          default: auto
          example: auto
        cache_control:
          $ref: '#/components/schemas/CacheControl'
    ContentBlock:
      description: A content block in a message response.
      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
      description: A text content block in a response.
      required:
      - type
      - text
      properties:
        type:
          type: string
          const: text
          example: example_value
        text:
          type: string
          description: The text content.
          example: example_value
        citations:
          type: array
          description: Citations for the text content, if any.
          items:
            type: object
          example: []
    MessageBatchResult:
      type: object
      description: A single result from a message batch.
      properties:
        custom_id:
          type: string
          description: The developer-provided custom_id from the original request.
          example: '500123'
        result:
          type: object
          description: The result of the request.
          properties:
            type:
              type: string
              description: The type of result.
              enum:
              - succeeded
              - errored
              - canceled
              - expired
            message:
              $ref: '#/components/schemas/Message'
            error:
              $ref: '#/components/schemas/Error'
          example: example_value
    ThinkingConfig:
      type: object
      description: Configuration for extended thinking.
      required:
      - type
      properties:
        type:
          type: string
          description: Whether thinking is enabled, disabled, or adaptive.
          enum:
          - enabled
          - disabled
          - adaptive
          example: enabled
        budget_tokens:
          type: integer
          description: Maximum number of tokens for thinking. Minimum 1024 and must be less than max_tokens.
          minimum: 1024
          example: 10
  parameters:
    AnthropicBeta:
      name: anthropic-beta
      in: header
      required: false
      description: Optional header to specify beta ve

# --- truncated at 32 KB (33 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/claude/refs/heads/main/openapi/claude-message-batches-api-openapi.yml