> ## Documentation Index
> Fetch the complete documentation index at: https://doc.agentfirst.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Batch completions

> Queue multiple LLM conversations for later retrieval.



## OpenAPI

````yaml post /ai/batches
openapi: 3.1.0
info:
  title: Agent First
  description: The missing services for agent-first development.
  version: 1.0.0
servers:
  - url: https://api.agentfirst.dev
security:
  - bearerAuth: []
paths:
  /ai/batches:
    post:
      summary: Batch completions
      description: Queue multiple LLM conversations for later retrieval.
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                prompts:
                  description: The questions or instructions to use as chat prompts.
                  type: array
                  items:
                    type: string
                    maxLength: 2047
                  minItems: 1
                  maxItems: 1000
                  example:
                    - Where can I buy a vintage guitar?
                    - Help me find guitar repair shops nearby.
                    - Do any local stores sell vinyl records?
                    - '[Additional prompts here]'
                model:
                  description: The AI model to chat with.
                  type: string
                  enum:
                    - chatgpt
                    - gemini
                    - perplexity
                    - copilot
                  default: chatgpt
                  example: gemini
                device:
                  description: >-
                    The name as returned by the [devices resource](devices) of
                    the device to emulate chatting on (these names are case
                    insensitive but must include form- or URL-encoded spaces and
                    punctuation marks); device emulation is unused by default.
                  type: string
                  example: null
                country:
                  description: >-
                    The [two-letter ISO
                    code](https://www.iso.org/obp/ui/#search/code) of the
                    country to chat from (these codes are case insensitive); a
                    random country is used by default.
                  type: string
                  example: null
                subdivision:
                  description: >-
                    The alphanumeric second part (proceeding the separator) of a
                    [first-level subdivision
                    code](https://www.iso.org/obp/ui/#search/code) in the
                    (prerequisite) country to chat from (these codes are case
                    insensitive); a random subdivision is used by default.
                  type: string
                  example: null
                city:
                  description: >-
                    The [commonly spelled name](https://www.geonames.org/) of
                    the city in the (prerequisite) country to chat from (these
                    names are temporarily case sensitive and required to include
                    form- or URL-encoded spaces and punctuation marks); a random
                    city is used by default.
                  type: string
                  example: null
                language (planned):
                  description: >-
                    The commonly spelled name or [two-letter ISO
                    code](https://www.loc.gov/standards/iso639-2/php/code_list.php)
                    of the language to chat in (these names and codes are case
                    insensitive but required to include form- or URL-encoded
                    spaces and punctuation marks); the language is unset by
                    default.
                  type: string
                  example: null
                display (planned):
                  description: >-
                    The commonly spelled name or [two-letter ISO
                    code](https://www.loc.gov/standards/iso639-2/php/code_list.php)
                    of the chat interface’s display language (these names and
                    codes are case insensitive but required to include form- or
                    URL-encoded spaces and punctuation marks); the display
                    language is unset by default or set to the language if
                    given.
                  type: string
                  example: null
                format:
                  description: The format to output to.
                  type: string
                  enum:
                    - json
                    - rendered
                    - raw (planned)
                  default: json
                  example: rendered
                expiration:
                  description: >-
                    The age in days of when to consider a cached completion
                    expired, where `0` disables caching.
                  type: integer
                  minimum: 0
                  maximum: 1
                  default: 1
                  example: 0
                callback (planned):
                  description: >-
                    The HTTP or HTTPS callback URL or Amazon SQS queue URL or
                    ARN to notify when the batch completions have been
                    retrieved; any SQS queue must grant `sqs:SendMessage`
                    permission to the
                    `arn:aws:iam::180363035301:role/api-instance` AWS principal.
                  type: string
                  example: https://webhook.site/02e249f8-1faf-4fab-bcf5-78ce683e85a8
              required:
                - prompts
        required: true
      responses:
        '202':
          description: A job identifier and confirmation count.
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    description: The identifier to retrieve the batch conversations with.
                    type: string
                    format: uuid
                    example: a0482596-c2ad-445a-a435-727002156a20
                  count:
                    description: >-
                      The number of prompts in the batch as confirmed by the
                      API.
                    type: integer
                    minimum: 1
                    maximum: 1000
                    example: 37
                required:
                  - id
                  - count
        '401':
          $ref: '#/components/responses/authenticationError'
        '402':
          $ref: '#/components/responses/creditsError'
        '403':
          $ref: '#/components/responses/authorizationError'
        '422':
          $ref: '#/components/responses/paramsError'
        '500':
          $ref: '#/components/responses/unknownError'
components:
  responses:
    authenticationError:
      description: The authorization header was missing.
      content:
        text/plain:
          schema:
            type: string
            example: Authorization header must be provided
    creditsError:
      description: No more credits are available.
      content:
        text/plain:
          schema:
            type: string
            example: Credit balance is 0; top up at https://agentfirst.dev/#pricing
    authorizationError:
      description: The API token was invalid.
      content:
        text/plain:
          schema:
            type: string
            example: Valid API token must be provided
    paramsError:
      description: One or more parameters were invalid.
      content:
        text/plain:
          schema:
            type: string
            example: Character counts must be no more than 255
    unknownError:
      description: An unknown error occurred.
      content:
        text/plain:
          schema:
            type: string
            example: Unknown error occurred
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

````