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

# List models

> Returns a listing of available model versions per model.



## OpenAPI

````yaml https://api.perfectreferral.com/v1/openapi.yml get /models
openapi: 3.1.0
info:
  version: 1.1.0
  title: Perfect Referral
  description: Refer patients to the right specialist the first time.
  contact:
    email: support@threshold.health
servers:
  - url: https://api.perfectreferral.com/v1
security:
  - bearerHttpAuthentication: []
tags:
  - name: Model
  - name: Practitioner
  - name: Practitioner Location
  - name: Specialization
paths:
  /models:
    get:
      tags:
        - Model
      summary: List models
      description: Returns a listing of available model versions per model.
      operationId: listModels
      responses:
        '200':
          description: Expected response to a valid request
          headers:
            X-Ratelimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
            X-Ratelimit-Reset:
              $ref: '#/components/headers/RateLimitReset'
            X-Ratelimit-Limit:
              $ref: '#/components/headers/RateLimitLimit'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Models'
              example:
                referralScopeMatch:
                  - version: v1.2
                    releasedAt: '2026-07-30T22:13:13.000Z'
                staleAffiliationRisk:
                  - version: v1.0
                    releasedAt: '2026-07-30T22:13:13.000Z'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalError'
        5XX:
          $ref: '#/components/responses/ServerError'
      security:
        - bearerHttpAuthentication: []
components:
  headers:
    RateLimitRemaining:
      description: Requests left in the current monthly quota window.
      schema:
        type: integer
    RateLimitReset:
      description: Unix time (seconds) when the monthly quota window resets.
      schema:
        type: integer
    RateLimitLimit:
      description: Total requests allowed per monthly quota window.
      schema:
        type: integer
    RetryAfter:
      description: Seconds to wait before retrying.
      schema:
        type: integer
  schemas:
    Models:
      type: object
      required:
        - referralScopeMatch
        - staleAffiliationRisk
      properties:
        referralScopeMatch:
          type: array
          description: Available versions of the referral scope match model.
          items:
            $ref: '#/components/schemas/ModelVersion'
        staleAffiliationRisk:
          type: array
          description: Available versions of the stale affiliation risk model.
          items:
            $ref: '#/components/schemas/ModelVersion'
    ModelVersion:
      type: object
      required:
        - version
        - releasedAt
      properties:
        version:
          type: string
          description: >-
            The version identifier. Pass this to the corresponding model version
            query parameter to request this version; it is also what a response
            echoes in `servedModels`.
        releasedAt:
          type: string
          format: date-time
          description: >-
            When this version was released. The most recent version is served by
            default.
    Error:
      type: object
      required:
        - code
        - message
      properties:
        code:
          type: string
          description: HTTP status error code.
        message:
          type: string
          description: Human-readable error description.
  responses:
    Unauthorized:
      description: API token missing or invalid.
      headers:
        X-Ratelimit-Remaining:
          $ref: '#/components/headers/RateLimitRemaining'
        X-Ratelimit-Reset:
          $ref: '#/components/headers/RateLimitReset'
        X-Ratelimit-Limit:
          $ref: '#/components/headers/RateLimitLimit'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            code: '401'
            message: Unauthorized
    TooManyRequests:
      description: >-
        Too many requests. Returned when either the monthly request quota or the
        per-second request-rate limit is exceeded; the `message` field
        distinguishes them ("rate limit exceeded" is the monthly quota, "request
        rate exceeded" is the per-second limit).
      headers:
        X-Ratelimit-Remaining:
          $ref: '#/components/headers/RateLimitRemaining'
        X-Ratelimit-Reset:
          $ref: '#/components/headers/RateLimitReset'
        X-Ratelimit-Limit:
          $ref: '#/components/headers/RateLimitLimit'
        Retry-After:
          $ref: '#/components/headers/RetryAfter'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            code: '429'
            message: Too Many Requests
    InternalError:
      description: Unexpected server error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            code: '500'
            message: Unexpected server error
    ServerError:
      description: Server error.
  securitySchemes:
    bearerHttpAuthentication:
      description: >-
        Bearer authentication header of the form `Bearer <token>`, where
        `<token>` is your API token.
      type: http
      scheme: bearer

````