Opper AI Rerank API

openapi: 3.2.0
info:
  description: Schema-driven generative API that orchestrates LLM-powered workflows.
  title: Task Rerank API
  version: 3.0.0
servers:
- description: Production
  url: https://api.opper.ai
- description: Local development
  url: http://localhost:8080
security:
- BearerAuth: []
tags:
- name: Rerank
paths:
  /v3/rerank:
    post:
      description: 'Reorder `documents` by relevance to `query` and get them back most-relevant first. `model`, `query` and `documents` are required; `top_n` caps how many results come back (integer >=1; default: all). `top_k` is a compatibility alias (zero means unspecified); positive values must match when both fields are supplied, and `return_documents` echoes each document''s text alongside its score. Up to 1000 documents per call. Billed per call or per token depending on the endpoint: `usage.cost` is what was charged, `usage.total_tokens` the provider''s count when it reports one.


        `model` accepts either form, and which one you send decides the routing:


        - a **bare model name** (e.g. `rerank-v3.5`) routes over that model''s pooled endpoints and **falls over to the next one** when an endpoint fails — the case this matters for is provider rate limits, where one endpoint''s quota is exhausted and another''s is not.

        - a **fully-qualified id** (e.g. `aws/cohere/rerank-v3.5`) pins that exact endpoint and never falls over.


        The response''s `model` is the endpoint that actually served the call, which for a pooled name is not necessarily the preferred one. List what is available with `GET /v3/models?type=rerank`.


        The project''s Comply model allowlist applies to every endpoint a bare name can route to, not only the one you named: an endpoint it forbids is never tried, not even as a fallover target. A pinned id the allowlist forbids, or a pool it empties, is refused with `403` rather than substituted. A provider that requires a signed agreement needs the organization''s grant, as everywhere else: no grant, no call, and never as a fallover target.'
      operationId: createRerank
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RerankRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RerankResponse'
          description: Successful response
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Bad request
        '401':
          description: Unauthorized - missing or invalid API key
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Internal server error
      summary: Rerank documents
      tags:
      - Rerank
components:
  schemas:
    ErrorResponse:
      properties:
        error:
          properties:
            code:
              type: string
            details:
              description: Any value
            message:
              type: string
          required:
          - code
          - message
          type: object
        meta:
          type: object
      required:
      - error
      type: object
    RerankRequest:
      properties:
        documents:
          items:
            type: string
          type: array
        model:
          type: string
        query:
          type: string
        return_documents:
          type: boolean
        top_k:
          description: Compatibility alias for top_n. Zero means unspecified. Positive values must match top_n when both are supplied.
          minimum: 0
          type: integer
        top_n:
          description: Maximum number of results. Omit to return all documents.
          minimum: 1
          type: integer
      required:
      - model
      - query
      - documents
      type: object
    RerankResponse:
      properties:
        id:
          type: string
        model:
          type: string
        results:
          items:
            properties:
              document:
                properties:
                  text:
                    type: string
                required:
                - text
                type: object
              index:
                type: integer
              relevance_score:
                type: number
            required:
            - index
            - relevance_score
            type: object
          type: array
        usage:
          properties:
            cost:
              type: number
            total_tokens:
              type: integer
          required:
          - total_tokens
          - cost
          type: object
      required:
      - id
      - model
      - results
      - usage
      type: object
  securitySchemes:
    BearerAuth:
      bearerFormat: API Key
      description: API key authentication. Pass your API key as a Bearer token.
      scheme: bearer
      type: http
    MCPBearer:
      description: Delegated user OAuth access token for the Opper MCP resource. Obtain through advertised OAuth authorization; runtime and management service keys are not accepted.
      scheme: bearer
      type: http
    ManagementBearer:
      bearerFormat: Management API Key
      description: Management API authentication. Pass an `op-mak-…` management token as a Bearer token. Runtime `op-…` API keys are rejected with 403 — they belong on the data-plane endpoints. Mint a management key from the platform UI under Settings → API keys.
      scheme: bearer
      type: http