> ## 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.

# Retrieve a model

> Everything the list carries for one model, plus the fields served only here: the model's own description, the request parameters it accepts, and its deprecation and sunset dates where it has them.

A model id contains slashes and the whole of it is the identifier. Percent-encode it once, or send it unencoded; a double-encoded slash names no model and answers 404.



## OpenAPI

````yaml /api-reference/openapi.public.json get /v1/models/{id}
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/{id}:
    get:
      tags:
        - Models
      summary: Retrieve a model
      description: >-
        Everything the list carries for one model, plus the fields served only
        here: the model's own description, the request parameters it accepts,
        and its deprecation and sunset dates where it has them.


        A model id contains slashes and the whole of it is the identifier.
        Percent-encode it once, or send it unencoded; a double-encoded slash
        names no model and answers 404.
      operationId: retrieveModel
      parameters:
        - name: id
          in: path
          required: true
          description: The model id, exactly as the list gives it.
          schema:
            type: string
          example: openai/gpt-4o-mini
      responses:
        '200':
          description: The model.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ModelDetail'
              example:
                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
                  author_slug: meta
                  author_source: recorded
                  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
                  provider_families:
                    - groq
                  capabilities:
                    streaming: 'yes'
                    tools: 'yes'
                    json_mode: 'yes'
                    vision: 'yes'
                    audio: 'no'
                  parameters:
                    - name: temperature
                      type: number
                      min_milli: 0
                      max_milli: 2000
                      default_milli: 1000
                      enum_values: null
                      sent_by_default: false
                      note: Higher values make the reply less predictable.
                  deprecated_at: null
                  sunset_at: null
                  replacement_model_id: null
                  description: A small, fast model for everyday chat and extraction work.
          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 provided.
                  type: authentication_error
                  param: null
                  code: invalid_api_key
                  request_id: REQUEST_ID
          headers:
            x-hopscotch-request-id:
              $ref: '#/components/headers/RequestId'
        '404':
          description: >-
            No model of that id is in the live catalog. A model we hold but do
            not publish answers the same way as one we have never heard of, on
            purpose.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  message: >-
                    The model "openai/gpt-4o-mini" was not found in the live
                    catalog.
                  type: not_found_error
                  param: model
                  code: model_not_found
                  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/openai/gpt-4o-mini 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: >-
            The catalog could not be served. Nothing is wrong with the request;
            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:
    ModelDetail:
      type: object
      description: >-
        One model, in the same envelope the list uses, with the detail-only
        fields under `hopscotch`.
      additionalProperties: true
      properties:
        id:
          type: string
          example: openai/gpt-4o-mini
        object:
          type: string
          example: model
        created:
          type: integer
        owned_by:
          type: string
        shutdown_date:
          type: integer
          description: Absent when the model has no announced end.
        hopscotch:
          $ref: '#/components/schemas/ModelDetailExtension'
    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.
    ModelDetailExtension:
      description: >-
        Everything the list carries for a model, plus the five fields served
        only when one model is asked for by name.
      allOf:
        - $ref: '#/components/schemas/ModelExtension'
        - type: object
          additionalProperties: true
          required:
            - description
            - parameters
            - deprecated_at
            - sunset_at
            - replacement_model_id
          properties:
            description:
              type: string
              nullable: true
              description: >-
                Detail only. The list is scanned and the detail is read, so the
                prose a model carries is served where somebody asked for that
                one model.
            parameters:
              type: array
              items:
                $ref: '#/components/schemas/ModelParameter'
            deprecated_at:
              type: integer
              nullable: true
              description: Unix seconds.
            sunset_at:
              type: integer
              nullable: true
              description: Unix seconds.
            replacement_model_id:
              type: string
              nullable: true
              description: What to move to, where one is named.
    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'
    ModelParameter:
      type: object
      description: >-
        One request parameter this model accepts. The three bounds are in
        thousandths of the parameter's own unit, so a temperature ceiling of 2
        arrives as 2000 and a default of 0.7 as 700. Integers, because a bound
        that drifted in its last decimal place would be a contract about
        nothing.
      additionalProperties: false
      required:
        - name
        - type
        - min_milli
        - max_milli
        - default_milli
        - enum_values
        - sent_by_default
        - note
      properties:
        name:
          type: string
        type:
          type: string
          enum:
            - boolean
            - enum
            - integer
            - number
            - string
          description: The control shape a client should render.
        min_milli:
          type: integer
          nullable: true
        max_milli:
          type: integer
          nullable: true
        default_milli:
          type: integer
          nullable: true
        enum_values:
          type: array
          nullable: true
          items:
            type: string
        sent_by_default:
          type: boolean
          description: Whether a client sends this parameter unless it is told otherwise.
        note:
          type: string
          nullable: true
    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.

````