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

# List models

> List the models you can call. The `id` of each entry is what you send as `model`.

Each entry is the OpenAI model object with a `hopscotch` block beside it, carrying what OpenAI's own object has no field for: who serves the model, what it can do, its context window, and the provider's list price.



## OpenAPI

````yaml /api-reference/openapi.public.json get /v1/models
openapi: 3.0.3
info:
  title: Hopscotch
  version: v1
  description: >-
    An OpenAI-compatible inference API. Point an OpenAI client at
    https://api.hopscotchlabs.ai, give it a Hopscotch API key, and call models
    across providers on one prepaid balance.


    Every response, errors included, matches the shape an unmodified OpenAI SDK
    expects.
servers:
  - url: https://api.hopscotchlabs.ai
    description: Production
security:
  - customerApiKey: []
tags:
  - name: Chat
    description: Chat completions, streamed or not.
  - name: Models
    description: What you can call.
paths:
  /v1/models:
    get:
      tags:
        - Models
      summary: List models
      description: >-
        List the models you can call. The `id` of each entry is what you send as
        `model`.


        Each entry is the OpenAI model object with a `hopscotch` block beside
        it, carrying what OpenAI's own object has no field for: who serves the
        model, what it can do, its context window, and the provider's list
        price.
      operationId: listModels
      responses:
        '200':
          description: The models available to your key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ModelList'
              example:
                object: list
                data:
                  - id: openai/gpt-4o-mini
                    object: model
                    created: 1756080000
                    owned_by: openai
                    hopscotch:
                      model_id: openai/gpt-4o-mini
                      display_name: GPT-4o mini
                      author: openai
                      context_window_tokens: 128000
                      max_output_tokens: 16384
                      input_rate_thousandths: 150
                      output_rate_thousandths: 600
                      currency_code: USD
                      endpoint_families:
                        - chat_completions
                      provider_display_names:
                        - OpenAI
                      capabilities:
                        audio: 'no'
                        json_mode: 'yes'
                        streaming: 'yes'
                        tools: 'yes'
                        vision: 'yes'
          headers:
            x-hopscotch-request-id:
              $ref: '#/components/headers/RequestId'
        '401':
          description: >-
            No key, a scheme other than Bearer, a key of the wrong shape, a key
            we reject, or a key past its own expiry date, which carries code
            `key_expired` and names the date it expired on.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  message: >-
                    Incorrect API key format. A Hopscotch key looks like
                    ub_live_ followed by 43 characters. Check you have not
                    pasted a key from another provider.
                  type: authentication_error
                  param: null
                  code: invalid_api_key
                  request_id: REQUEST_ID
          headers:
            x-hopscotch-request-id:
              $ref: '#/components/headers/RequestId'
        '405':
          description: >-
            A method other than GET on a path that exists. The route boundary
            answers this before any key is looked at, so it costs nothing and
            reveals nothing.
          headers:
            Allow:
              schema:
                type: string
                enum:
                  - GET
              description: The methods this path accepts.
              example: GET
            x-hopscotch-request-id:
              $ref: '#/components/headers/RequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  message: POST is not supported for /v1/models in this release.
                  type: invalid_request_error
                  param: null
                  code: method_not_allowed
                  request_id: REQUEST_ID
        '429':
          description: >-
            This key's own request rate limit. Every route on this API is
            subject to it.
          headers:
            Retry-After:
              schema:
                type: integer
                minimum: 1
              example: 17
              description: Seconds to wait.
            x-hopscotch-request-id:
              $ref: '#/components/headers/RequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  message: >-
                    Rate limit reached for this key. Try again in 12 seconds.
                    Request id REQUEST_ID.
                  type: rate_limit_error
                  param: null
                  code: rate_limit_exceeded
                  request_id: REQUEST_ID
        '500':
          description: A fault on our side. The request id is the one thing worth keeping.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  message: >-
                    The server had an error while processing your request. Sorry
                    about that! Quote the request id if you contact support.
                  type: api_error
                  param: null
                  code: null
                  request_id: REQUEST_ID
          headers:
            x-hopscotch-request-id:
              $ref: '#/components/headers/RequestId'
        '503':
          description: We are not currently configured to serve a model list. Retry later.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  message: >-
                    No provider is configured, so there is nothing to serve this
                    request.
                  type: api_error
                  param: null
                  code: no_provider_configured
                  request_id: REQUEST_ID
          headers:
            x-hopscotch-request-id:
              $ref: '#/components/headers/RequestId'
      security:
        - customerApiKey: []
      servers:
        - url: https://api.hopscotchlabs.ai
          description: Production
components:
  schemas:
    ModelList:
      type: object
      description: An OpenAI model list.
      additionalProperties: true
      properties:
        object:
          type: string
          example: list
        data:
          type: array
          items:
            $ref: '#/components/schemas/Model'
    Error:
      type: object
      description: The error envelope. One top-level `error` key, always, at every status.
      required:
        - error
      additionalProperties: false
      properties:
        error:
          type: object
          required:
            - message
            - type
            - param
            - code
          additionalProperties: false
          properties:
            message:
              type: string
              description: Prose for a person. It may be reworded, so do not branch on it.
            type:
              type: string
              description: The category an SDK branches on. A closed set.
              enum:
                - invalid_request_error
                - authentication_error
                - permission_error
                - not_found_error
                - rate_limit_error
                - api_error
                - insufficient_quota
                - server_error
            param:
              type: string
              nullable: true
              description: >-
                The request field at fault, or null. Present and null rather
                than absent.
            code:
              type: string
              nullable: true
              description: The stable machine-readable reason. Branch on this.
            request_id:
              type: string
              description: >-
                Our id for this request, the same value as the
                x-hopscotch-request-id header. Quote it when you contact
                support.
    Model:
      type: object
      description: One model you may call.
      additionalProperties: true
      properties:
        id:
          type: string
          description: The value to send as `model`.
          example: openai/gpt-4o-mini
        object:
          type: string
          example: model
        created:
          type: integer
          description: >-
            A unix timestamp in seconds. The release time where one is recorded
            and the record's own creation time otherwise, so it is not a release
            date for most of the list.
        owned_by:
          type: string
        shutdown_date:
          type: integer
          description: >-
            When the model stops serving, in unix seconds. Absent when there is
            none, rather than null.
        hopscotch:
          $ref: '#/components/schemas/ModelExtension'
    ModelExtension:
      type: object
      description: >-
        Our own facts about a model, under the `hopscotch` key. Everything
        OpenAI's own model object defines stays at the top level; everything it
        does not define lives here.
      additionalProperties: true
      required:
        - model_id
        - display_name
        - author
        - input_rate_thousandths
        - endpoint_families
        - provider_display_names
        - capabilities
      properties:
        model_id:
          type: string
          description: >-
            The same value as `id`, repeated inside the extension so a client
            reading only this block still has it.
        display_name:
          type: string
        author:
          type: string
          description: Who made the model, which is not who serves it.
        context_window_tokens:
          type: integer
          nullable: true
        max_output_tokens:
          type: integer
          nullable: true
        input_rate_thousandths:
          type: integer
          description: >-
            The provider's own list price for prompt tokens, in thousandths of
            the currency unit per million tokens. Nothing this platform charges
            on top is folded in: the fee is taken when credit is bought, and a
            request then costs the provider's price.
        output_rate_thousandths:
          type: integer
          description: >-
            The same unit, for completion tokens. Absent when the model
            publishes no separate output rate.
        currency_code:
          type: string
          nullable: true
          description: ISO 4217, or null where nobody recorded one.
        endpoint_families:
          type: array
          items:
            type: string
          description: The request families this model answers.
        provider_display_names:
          type: array
          items:
            type: string
          description: >-
            Who can serve it. Which one answered a given request is on the
            response headers, not here.
        capabilities:
          $ref: '#/components/schemas/CatalogCapabilities'
    CatalogCapabilities:
      type: object
      description: >-
        What the catalog records this model can do. Each answer is one of three
        words, and `unknown` is not `no`: it means nobody has established the
        answer.
      additionalProperties: false
      required:
        - audio
        - json_mode
        - streaming
        - tools
        - vision
      properties:
        audio:
          type: string
          enum:
            - 'no'
            - unknown
            - 'yes'
        json_mode:
          type: string
          enum:
            - 'no'
            - unknown
            - 'yes'
        streaming:
          type: string
          enum:
            - 'no'
            - unknown
            - 'yes'
        tools:
          type: string
          enum:
            - 'no'
            - unknown
            - 'yes'
        vision:
          type: string
          enum:
            - 'no'
            - unknown
            - 'yes'
  headers:
    RequestId:
      description: >-
        Our id for this request. Quote it when you contact support. Present on
        every response, errors included.
      schema:
        type: string
  securitySchemes:
    customerApiKey:
      type: http
      scheme: bearer
      description: >-
        A workspace API key in an `Authorization: Bearer` header. A missing
        header, a scheme other than Bearer, a key of the wrong shape, and a key
        we reject are all 401.

````