Sail Batches API API

openapi: 3.1.0
info:
  title: Sail Batches API API
  version: '2026-02-18'
  description: Sail provides OpenAI-compatible Responses and Chat Completions endpoints, plus an Anthropic-compatible Messages endpoint. This reference documents the currently supported subset of fields.
servers:
- url: https://api.sailresearch.com/v1
security:
- BearerAuth: []
tags:
- name: Batches API
  description: Submit and manage batches of requests.
paths:
  /batches:
    post:
      operationId: createBatch
      tags:
      - Batches API
      summary: Create a batch
      description: Submit a batch of requests for asynchronous processing.
      parameters:
      - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateBatchRequest'
            example:
              endpoint: /v1/responses
              label: my-batch-job
              requests:
              - custom_id: my-first-request
                params:
                  model: zai-org/GLM-5.2-FP8
                  max_output_tokens: 1024
                  input:
                  - role: user
                    content: Hello, world!
              - custom_id: my-second-request
                params:
                  model: zai-org/GLM-5.2-FP8
                  max_output_tokens: 1024
                  input:
                  - role: user
                    content: Hello again!
      responses:
        '200':
          description: Batch created.
          content:
            application/json:
              schema:
                type: object
                required:
                - id
                - request_counts
                - created_at
                properties:
                  id:
                    type: string
                    description: Unique identifier for the batch.
                  request_counts:
                    type: integer
                    description: Total number of requests in the batch.
                  created_at:
                    type: integer
                    description: Unix timestamp of when the batch was created.
                  label:
                    type: string
                    description: The label for the batch, if provided.
              example:
                id: batch_abc123
                request_counts: 2
                created_at: 1741564800
                label: my-batch-job
        '400':
          description: Invalid request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Authentication error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    get:
      operationId: listBatches
      tags:
      - Batches API
      summary: List batches
      description: List batches with optional pagination.
      parameters:
      - name: after_id
        in: query
        required: false
        schema:
          type: string
        description: Return batches created after this batch ID.
      - name: before_id
        in: query
        required: false
        schema:
          type: string
        description: Return batches created before this batch ID.
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          default: 25
          minimum: 1
          maximum: 200
        description: Maximum number of batches to return. Min 1, defaults to 25, max 200.
      responses:
        '200':
          description: List of batches.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  required:
                  - id
                  - request_counts
                  - created_at
                  properties:
                    id:
                      type: string
                      description: Unique identifier for the batch.
                    request_counts:
                      type: integer
                      description: Total number of requests in the batch.
                    created_at:
                      type: integer
                      description: Unix timestamp of when the batch was created.
                    label:
                      type: string
                      description: The label for the batch, if provided.
              example:
              - id: batch_abc123
                request_counts: 2
                created_at: 1741564800
                label: my-batch-job
        '400':
          description: Invalid request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Authentication error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /batches/{batch_id}:
    get:
      operationId: getBatch
      tags:
      - Batches API
      summary: Get batch status
      description: Retrieve the current status of a batch.
      parameters:
      - name: batch_id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Returns the current status of a batch.
          content:
            application/json:
              schema:
                type: object
                required:
                - id
                - request_counts
                - created_at
                - request_status
                properties:
                  id:
                    type: string
                    description: Unique identifier for the batch.
                  request_counts:
                    type: integer
                    description: Total number of requests in the batch.
                  created_at:
                    type: integer
                    description: Unix timestamp of when the batch was created.
                  label:
                    type: string
                    description: The label for the batch, if provided.
                  request_status:
                    type: object
                    description: A map of custom_id to its current status.
                    additionalProperties:
                      type: object
                      required:
                      - status
                      properties:
                        status:
                          type: string
              example:
                id: batch_abc123
                request_counts: 2
                created_at: 1741564800
                label: my-batch-job
                request_status:
                  my-first-request:
                    status: COMPLETED
                  my-second-request:
                    status: RUNNING
        '400':
          description: Invalid request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Authentication error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Batch not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /batches/{batch_id}/{custom_id}:
    get:
      operationId: getBatchRequestResult
      tags:
      - Batches API
      summary: Get batch request result
      description: Retrieve the result of a specific request within a batch by its custom_id.
      parameters:
      - name: batch_id
        in: path
        required: true
        schema:
          type: string
        description: The ID of the batch.
      - name: custom_id
        in: path
        required: true
        schema:
          type: string
        description: The custom_id of the request within the batch.
      responses:
        '200':
          description: The response object for the given request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseObject'
        '400':
          description: Invalid request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Authentication error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Batch or request not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    ResponseInputMessage:
      type: object
      required:
      - role
      - content
      properties:
        role:
          type: string
          enum:
          - system
          - user
          - assistant
          - tool
          - function
        content:
          oneOf:
          - type: string
          - type: array
            minItems: 1
            items:
              oneOf:
              - $ref: '#/components/schemas/ResponseInputTextPart'
              - $ref: '#/components/schemas/ResponseInputImagePart'
        name:
          type: string
        tool_calls:
          type: array
          items:
            type: object
            additionalProperties: true
        tool_call_id:
          type: string
        function_call:
          type: object
          additionalProperties: true
      additionalProperties: false
    ResponseInputImagePart:
      type: object
      description: Image content part. Image input is supported only on multimodal models; see the Models page.
      required:
      - type
      - image_url
      properties:
        type:
          type: string
          enum:
          - input_image
        image_url:
          type: string
          description: Public http(s) URL or a base64 data URI (data:<media-type>;base64,<data>).
        detail:
          type: string
          enum:
          - auto
          - low
          - high
      additionalProperties: false
    ResponseTextConfiguration:
      type: object
      required:
      - format
      properties:
        format:
          oneOf:
          - $ref: '#/components/schemas/ResponseTextFormat'
          - $ref: '#/components/schemas/ResponseJsonSchemaFormat'
      additionalProperties: false
    ResponseInputObject:
      type: object
      required:
      - messages
      properties:
        messages:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/ResponseInputMessage'
      additionalProperties: false
    BatchRequestItem:
      type: object
      required:
      - custom_id
      - params
      properties:
        custom_id:
          type: string
          pattern: ^[a-z0-9][a-z0-9_-]*$
          minLength: 1
          maxLength: 64
          description: A unique identifier for this request within the batch. Must be lowercase alphanumeric and can include hyphens and underscores. Min 1 character, max 64 characters.
        params:
          type: object
          description: The request parameters (same fields as a Responses API request body).
          additionalProperties: true
      additionalProperties: false
    ErrorResponse:
      type: object
      required:
      - error
      properties:
        error:
          $ref: '#/components/schemas/ErrorObject'
      additionalProperties: false
    ResponseInputTextPart:
      type: object
      required:
      - type
      - text
      properties:
        type:
          type: string
          enum:
          - input_text
        text:
          type: string
      additionalProperties: false
    ResponseUsage:
      type: object
      required:
      - input_tokens
      - input_tokens_details
      - output_tokens
      - output_tokens_details
      - total_tokens
      properties:
        input_tokens:
          type: integer
        input_tokens_details:
          $ref: '#/components/schemas/ResponseUsageDetails'
        output_tokens:
          type: integer
        output_tokens_details:
          $ref: '#/components/schemas/ResponseUsageDetails'
        total_tokens:
          type: integer
        prompt_tokens:
          type: integer
        completion_tokens:
          type: integer
      additionalProperties: false
    ResponseTextFormat:
      type: object
      required:
      - type
      properties:
        type:
          type: string
          enum:
          - text
      additionalProperties: false
    ResponseInput:
      description: Text input, plus image input (input_image) on multimodal models. Audio, files, and item references are not currently supported.
      oneOf:
      - type: string
        minLength: 1
      - type: array
        minItems: 1
        items:
          $ref: '#/components/schemas/ResponseInputMessage'
      - $ref: '#/components/schemas/ResponseInputObject'
    CreateBatchRequest:
      type: object
      required:
      - endpoint
      - requests
      properties:
        endpoint:
          type: string
          enum:
          - /v1/responses
          description: The API endpoint to use for all requests in the batch. Currently only /v1/responses is supported.
        requests:
          type: array
          minItems: 1
          maxItems: 100000
          description: The list of requests in the batch. Min 1, max 100,000 requests. Total request body must not exceed 256 MB.
          items:
            $ref: '#/components/schemas/BatchRequestItem'
        label:
          type: string
          pattern: ^[a-zA-Z0-9_-]+$
          maxLength: 128
          description: An optional label for the batch. Must be alphanumeric (hyphens and underscores allowed), max 128 characters.
      additionalProperties: false
    ResponseObject:
      type: object
      required:
      - id
      - object
      - created_at
      - status
      - model
      - metadata
      - usage
      properties:
        id:
          type: string
        object:
          type: string
          enum:
          - response
        created_at:
          type: integer
        status:
          type: string
          enum:
          - pending
          - running
          - failed
          - completed
          - cancelled
        model:
          type: string
        input:
          $ref: '#/components/schemas/ResponseInput'
        output:
          oneOf:
          - type: string
          - type: array
            items:
              type: object
              additionalProperties: true
          - type: object
            additionalProperties: true
          - type: 'null'
        error:
          oneOf:
          - type: object
            additionalProperties: true
          - type: 'null'
        incomplete_details:
          oneOf:
          - type: object
            additionalProperties: true
          - type: 'null'
        max_output_tokens:
          oneOf:
          - type: integer
          - type: 'null'
        reasoning:
          type: object
          additionalProperties: true
        text:
          $ref: '#/components/schemas/ResponseTextConfiguration'
        store:
          type: boolean
        temperature:
          type: number
        top_p:
          type: number
        parallel_tool_calls:
          type: boolean
        tool_choice:
          oneOf:
          - type: string
          - type: object
            additionalProperties: true
        tools:
          type: array
          items:
            type: object
            additionalProperties: true
        truncation:
          oneOf:
          - type: string
          - type: object
            additionalProperties: true
        usage:
          $ref: '#/components/schemas/ResponseUsage'
        user:
          oneOf:
          - type: string
          - type: 'null'
        metadata:
          type: object
          additionalProperties: true
      additionalProperties: true
    ErrorObject:
      type: object
      required:
      - message
      - type
      properties:
        message:
          type: string
        type:
          type: string
        param:
          oneOf:
          - type: string
          - type: 'null'
        code:
          oneOf:
          - type: string
          - type: integer
          - type: 'null'
      additionalProperties: true
    ResponseUsageDetails:
      type: object
      required:
      - cached_tokens
      - reasoning_tokens
      properties:
        cached_tokens:
          type: integer
        reasoning_tokens:
          type: integer
      additionalProperties: false
    ResponseJsonSchemaFormat:
      type: object
      required:
      - type
      - name
      properties:
        type:
          type: string
          enum:
          - json_schema
        name:
          type: string
        description:
          type: string
        schema:
          type: object
          additionalProperties: true
        strict:
          type: boolean
      additionalProperties: false
  parameters:
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      required: false
      schema:
        type: string
        maxLength: 255
      description: Makes the request retry-safe. Sail stores a reservation keyed by (organization, API key, Idempotency-Key); retrying with the same value returns the previously stored response instead of re-running inference. Keys are capped at 255 characters. See [Idempotent Requests](/idempotency) for full semantics.
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key