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

# Responses

> Create OpenAI Responses-compatible output with Capriole AI Responses models.

Use this endpoint when your application, SDK, or agent expects the OpenAI Responses request and response format.

Send a standard Responses payload with `model` and `input`. Capriole AI resolves latest aliases to the selected upstream model ID before upstream dispatch, forwards compatible fields such as `instructions`, `tools`, `reasoning`, `previous_response_id`, and `stream`, and returns the upstream JSON or SSE stream unchanged.

`POST /v1/responses` accepts `openai-latest`, `openai/gpt-5.6-terra`, `openai/gpt-5.6-luna`, `openai/gpt-5.5`, and `openai/gpt-5.4-mini`. Use `openai-latest` to let Capriole AI choose our recommended flagship OpenAI Responses model.

Claude and Google latest aliases are not supported on this endpoint. Grok 4.5 and GLM 5.2 use Chat Completions and are also not supported here. Use `POST /v1/chat/completions` when you want one OpenAI-compatible endpoint that can call every public model.

For simple Capriole-native text generation, use `POST /v1/chat`. Use `POST /v1/responses` when OpenAI Responses wire behavior is required.


## OpenAPI

````yaml api-reference/openapi.json POST /v1/responses
openapi: 3.1.0
info:
  title: Capriole AI API
  description: >-
    Public API for model discovery, text chat, and protocol-compatible model
    endpoints.
  version: 1.0.0
servers:
  - url: https://api.caprioletech.com
security: []
paths:
  /v1/responses:
    post:
      summary: Create response
      description: >-
        Creates an OpenAI Responses-compatible response for models that use the
        Responses request and response format.
      operationId: createResponse
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ResponsesRequest'
            examples:
              text:
                value:
                  model: openai-latest
                  input: Hello World!
              streaming:
                value:
                  model: openai/gpt-5.6-luna
                  input: Write a short Python function.
                  stream: true
      responses:
        '200':
          description: OpenAI Responses-compatible JSON response or SSE stream
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponsesResponse'
            text/event-stream:
              schema:
                type: string
                description: OpenAI Responses-compatible SSE chunks.
        '400':
          $ref: '#/components/responses/ValidationOrDetailErrorResponse'
        '401':
          $ref: '#/components/responses/DetailErrorResponse'
        '403':
          $ref: '#/components/responses/DetailErrorResponse'
        '429':
          $ref: '#/components/responses/RateLimitErrorResponse'
        '500':
          $ref: '#/components/responses/InternalServerErrorResponse'
        '502':
          $ref: '#/components/responses/DetailErrorResponse'
      security:
        - bearerAuth: []
components:
  schemas:
    ResponsesRequest:
      type: object
      additionalProperties: true
      required:
        - model
        - input
      properties:
        model:
          type: string
          description: Public Responses-compatible model identifier or OpenAI latest alias
          enum:
            - openai-latest
            - openai/gpt-5.6-terra
            - openai/gpt-5.6-luna
            - openai/gpt-5.5
            - openai/gpt-5.4-mini
        input:
          description: OpenAI Responses input string or item list.
          oneOf:
            - type: string
            - type: array
              items:
                type: object
                additionalProperties: true
        instructions:
          type: string
          description: Optional system-level instructions.
        tools:
          type: array
          description: OpenAI Responses-compatible tool definitions.
          items:
            type: object
            additionalProperties: true
        reasoning:
          type: object
          description: OpenAI Responses-compatible reasoning options.
          additionalProperties: true
        stream:
          type: boolean
          default: false
          description: >-
            Stream the response as OpenAI Responses-compatible server-sent
            events.
    ResponsesResponse:
      type: object
      description: OpenAI Responses-compatible response body.
      additionalProperties: true
    ValidationError:
      type: object
      required:
        - detail
        - errors
      properties:
        detail:
          type: string
          description: Validation summary
        errors:
          type: array
          items:
            type: string
          description: Per-field validation errors
    DetailError:
      type: object
      required:
        - detail
      properties:
        detail:
          type: string
          description: Error detail from the API
  responses:
    ValidationOrDetailErrorResponse:
      description: Validation error or request-level error response
      content:
        application/json:
          schema:
            oneOf:
              - $ref: '#/components/schemas/ValidationError'
              - $ref: '#/components/schemas/DetailError'
          examples:
            invalidPayload:
              value:
                detail: Invalid input parameters received.
                errors:
                  - >-
                    Field 'body -> input': String should have at least 1
                    character
    DetailErrorResponse:
      description: Error response with a detail message
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/DetailError'
          examples:
            missingBearerToken:
              value:
                detail: Missing Bearer token
            invalidApiKey:
              value:
                detail: Invalid API key
            usageMetadataUnavailable:
              value:
                detail: Missing usage metadata
    RateLimitErrorResponse:
      description: Rate limit error response
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/DetailError'
          examples:
            rateLimitExceeded:
              value:
                detail: 'Rate limit exceeded: 100 per 1 minute'
    InternalServerErrorResponse:
      description: Internal server error response
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/DetailError'
          examples:
            internalServerError:
              value:
                detail: An internal server error occurred. Please try again later.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        Use an API key created in the Capriole AI page. Send it as
        `Authorization: Bearer sk-...`.

````