Everyn Models API

openapi: 3.2.0
info:
  description: 'everyn self-serve API for dataset upload sessions, job specs, managed runs, run inspection, retry lineage, exports, alerts, webhooks, model catalog reads, usage and managed-AI balance reads, and organization administration.


    API routes use the `/v1` prefix. API-key product calls use `Authorization: Bearer sk-everyn-...` and derive organization context from the key. Job creation, editing and forking require a human browser session and CSRF protection; product API keys may read and run saved jobs but cannot author them. Browser-admin organization routes use bearer credentials and organization IDs in the route. Successful list responses use `{ "data": [], "nextCursor": null }`, and every response includes `X-Request-Id`.'
  title: everyn Public Models API
  version: 1.0.0
servers:
- description: Production API
  url: https://api.everyn.ai
- description: Local development API
  url: http://localhost:8000
tags:
- description: Product model catalog. Reads require job_specs:read; job-spec create/update still validates model IDs against this catalog.
  name: Models
paths:
  /v1/model-providers:
    get:
      description: 'List Model Providers. Authenticated Everyn public API operation. Send the request to the selected server from this document with a product API key (Authorization: Bearer sk-everyn-...). Parameters and responses are typed in this document.'
      operationId: list_model_providers_v1_model_providers_get
      parameters: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Page_ModelProviderResponse_'
          description: Successful Response
          headers:
            X-Request-Id:
              description: Canonical everyn request ID generated by the API.
              schema:
                examples:
                - req_abc123
                type: string
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicErrorEnvelope'
          description: Malformed request, header, cursor, or multipart form field.
          headers:
            X-Request-Id:
              description: Canonical everyn request ID generated by the API.
              schema:
                examples:
                - req_abc123
                type: string
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicErrorEnvelope'
          description: Missing, malformed, unknown, revoked, or expired credential.
          headers:
            X-Request-Id:
              description: Canonical everyn request ID generated by the API.
              schema:
                examples:
                - req_abc123
                type: string
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicErrorEnvelope'
          description: Authenticated principal lacks the required scope or role.
          headers:
            X-Request-Id:
              description: Canonical everyn request ID generated by the API.
              schema:
                examples:
                - req_abc123
                type: string
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicErrorEnvelope'
          description: Resource not found, including cross-organization resources.
          headers:
            X-Request-Id:
              description: Canonical everyn request ID generated by the API.
              schema:
                examples:
                - req_abc123
                type: string
        '409':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicErrorEnvelope'
          description: Idempotency conflict or invalid resource state.
          headers:
            X-Request-Id:
              description: Canonical everyn request ID generated by the API.
              schema:
                examples:
                - req_abc123
                type: string
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicErrorEnvelope'
          description: Public error
          headers:
            X-Request-Id:
              description: Canonical everyn request ID generated by the API.
              schema:
                examples:
                - req_abc123
                type: string
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicErrorEnvelope'
          description: Rate limit exceeded.
          headers:
            X-Request-Id:
              description: Canonical everyn request ID generated by the API.
              schema:
                examples:
                - req_abc123
                type: string
      security:
      - BearerAuth: []
      summary: List Model Providers
      tags:
      - Models
  /v1/models:
    get:
      description: 'List Models. Authenticated Everyn public API operation. Send the request to the selected server from this document with a product API key (Authorization: Bearer sk-everyn-...). Parameters and responses are typed in this document.'
      operationId: list_models_v1_models_get
      parameters: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Page_ModelResponse_'
          description: Successful Response
          headers:
            X-Request-Id:
              description: Canonical everyn request ID generated by the API.
              schema:
                examples:
                - req_abc123
                type: string
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicErrorEnvelope'
          description: Malformed request, header, cursor, or multipart form field.
          headers:
            X-Request-Id:
              description: Canonical everyn request ID generated by the API.
              schema:
                examples:
                - req_abc123
                type: string
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicErrorEnvelope'
          description: Missing, malformed, unknown, revoked, or expired credential.
          headers:
            X-Request-Id:
              description: Canonical everyn request ID generated by the API.
              schema:
                examples:
                - req_abc123
                type: string
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicErrorEnvelope'
          description: Authenticated principal lacks the required scope or role.
          headers:
            X-Request-Id:
              description: Canonical everyn request ID generated by the API.
              schema:
                examples:
                - req_abc123
                type: string
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicErrorEnvelope'
          description: Resource not found, including cross-organization resources.
          headers:
            X-Request-Id:
              description: Canonical everyn request ID generated by the API.
              schema:
                examples:
                - req_abc123
                type: string
        '409':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicErrorEnvelope'
          description: Idempotency conflict or invalid resource state.
          headers:
            X-Request-Id:
              description: Canonical everyn request ID generated by the API.
              schema:
                examples:
                - req_abc123
                type: string
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicErrorEnvelope'
          description: Public error
          headers:
            X-Request-Id:
              description: Canonical everyn request ID generated by the API.
              schema:
                examples:
                - req_abc123
                type: string
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicErrorEnvelope'
          description: Rate limit exceeded.
          headers:
            X-Request-Id:
              description: Canonical everyn request ID generated by the API.
              schema:
                examples:
                - req_abc123
                type: string
      security:
      - BearerAuth: []
      summary: List Models
      tags:
      - Models
  /v1/models/{model_id_or_key}:
    get:
      description: 'Get Model. Authenticated Everyn public API operation. Send the request to the selected server from this document with a product API key (Authorization: Bearer sk-everyn-...). Parameters and responses are typed in this document.'
      operationId: get_model_v1_models__model_id_or_key__get
      parameters:
      - description: model_id_or_key for this Everyn API operation.
        in: path
        name: model_id_or_key
        required: true
        schema:
          title: Model Id Or Key
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ModelResponse'
          description: Successful Response
          headers:
            X-Request-Id:
              description: Canonical everyn request ID generated by the API.
              schema:
                examples:
                - req_abc123
                type: string
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicErrorEnvelope'
          description: Malformed request, header, cursor, or multipart form field.
          headers:
            X-Request-Id:
              description: Canonical everyn request ID generated by the API.
              schema:
                examples:
                - req_abc123
                type: string
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicErrorEnvelope'
          description: Missing, malformed, unknown, revoked, or expired credential.
          headers:
            X-Request-Id:
              description: Canonical everyn request ID generated by the API.
              schema:
                examples:
                - req_abc123
                type: string
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicErrorEnvelope'
          description: Authenticated principal lacks the required scope or role.
          headers:
            X-Request-Id:
              description: Canonical everyn request ID generated by the API.
              schema:
                examples:
                - req_abc123
                type: string
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicErrorEnvelope'
          description: Resource not found, including cross-organization resources.
          headers:
            X-Request-Id:
              description: Canonical everyn request ID generated by the API.
              schema:
                examples:
                - req_abc123
                type: string
        '409':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicErrorEnvelope'
          description: Idempotency conflict or invalid resource state.
          headers:
            X-Request-Id:
              description: Canonical everyn request ID generated by the API.
              schema:
                examples:
                - req_abc123
                type: string
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicErrorEnvelope'
          description: Public error
          headers:
            X-Request-Id:
              description: Canonical everyn request ID generated by the API.
              schema:
                examples:
                - req_abc123
                type: string
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicErrorEnvelope'
          description: Rate limit exceeded.
          headers:
            X-Request-Id:
              description: Canonical everyn request ID generated by the API.
              schema:
                examples:
                - req_abc123
                type: string
      security:
      - BearerAuth: []
      summary: Get Model
      tags:
      - Models
components:
  schemas:
    ModelResponse:
      additionalProperties: false
      properties:
        capabilities:
          $ref: '#/components/schemas/ModelCapabilitiesResponse'
        contextWindowTokens:
          anyOf:
          - type: integer
          - type: 'null'
          title: Contextwindowtokens
        customerPrice:
          anyOf:
          - $ref: '#/components/schemas/CustomerPriceResponse'
          - type: 'null'
        discovery:
          $ref: '#/components/schemas/ModelDiscoveryStateResponse'
        displayName:
          title: Displayname
          type: string
        id:
          minLength: 1
          title: Id
          type: string
        maxOutputTokens:
          anyOf:
          - type: integer
          - type: 'null'
          title: Maxoutputtokens
        model:
          title: Model
          type: string
        modelVersion:
          title: Modelversion
          type: integer
        modelVersionId:
          title: Modelversionid
          type: string
        notBillable:
          title: Notbillable
          type: boolean
        observation:
          anyOf:
          - $ref: '#/components/schemas/ModelObservationResponse'
          - type: 'null'
        pricingStatus:
          title: Pricingstatus
          type: string
        providerKey:
          title: Providerkey
          type: string
        providerListPrice:
          anyOf:
          - $ref: '#/components/schemas/ProviderListPriceResponse'
          - type: 'null'
        providerModelId:
          title: Providermodelid
          type: string
        selectionTier:
          anyOf:
          - type: string
          - type: 'null'
          title: Selectiontier
        status:
          title: Status
          type: string
        versionStatus:
          title: Versionstatus
          type: string
      required:
      - id
      - model
      - providerKey
      - providerModelId
      - modelVersionId
      - status
      - versionStatus
      - pricingStatus
      - notBillable
      - displayName
      - selectionTier
      - modelVersion
      - contextWindowTokens
      - maxOutputTokens
      - capabilities
      - discovery
      - observation
      - providerListPrice
      - customerPrice
      title: ModelResponse
      type: object
    ModelDiscoveryStateResponse:
      additionalProperties: false
      properties:
        blockerReasonCodes:
          items:
            type: string
          title: Blockerreasoncodes
          type: array
        recommended:
          title: Recommended
          type: boolean
        runnable:
          title: Runnable
          type: boolean
        warningReasonCodes:
          items:
            type: string
          title: Warningreasoncodes
          type: array
      required:
      - runnable
      - recommended
      - blockerReasonCodes
      - warningReasonCodes
      title: ModelDiscoveryStateResponse
      type: object
    Page_ModelProviderResponse_:
      additionalProperties: false
      properties:
        data:
          items:
            $ref: '#/components/schemas/ModelProviderResponse'
          title: Data
          type: array
        nextCursor:
          anyOf:
          - type: string
          - type: 'null'
          title: Nextcursor
      required:
      - data
      title: Page[ModelProviderResponse]
      type: object
    ProviderListPriceResponse:
      additionalProperties: false
      properties:
        components:
          items:
            $ref: '#/components/schemas/ProviderPriceComponentResponse'
          title: Components
          type: array
        currencyCode:
          title: Currencycode
          type: string
        effectiveAt:
          description: UTC RFC 3339 timestamp string.
          examples:
          - '2026-06-12T12:00:00Z'
          title: Effectiveat
          type: string
        id:
          minLength: 1
          title: Id
          type: string
        pricingProfile:
          title: Pricingprofile
          type: string
        retiredAt:
          anyOf:
          - description: UTC RFC 3339 timestamp string.
            examples:
            - '2026-06-12T12:00:00Z'
            type: string
          - type: 'null'
          title: Retiredat
        sourceUrl:
          title: Sourceurl
          type: string
        verifiedAt:
          description: UTC RFC 3339 timestamp string.
          examples:
          - '2026-06-12T12:00:00Z'
          title: Verifiedat
          type: string
      required:
      - id
      - currencyCode
      - pricingProfile
      - sourceUrl
      - verifiedAt
      - effectiveAt
      - retiredAt
      - components
      title: ProviderListPriceResponse
      type: object
    ModelCapabilitiesResponse:
      additionalProperties: false
      properties:
        images:
          title: Images
          type: boolean
        structuredOutput:
          title: Structuredoutput
          type: boolean
        text:
          title: Text
          type: boolean
        tools:
          title: Tools
          type: boolean
      required:
      - text
      - images
      - tools
      - structuredOutput
      title: ModelCapabilitiesResponse
      type: object
    ModelProviderResponse:
      additionalProperties: false
      properties:
        createdAt:
          description: UTC RFC 3339 timestamp string.
          examples:
          - '2026-06-12T12:00:00Z'
          title: Createdat
          type: string
        displayName:
          title: Displayname
          type: string
        id:
          minLength: 1
          title: Id
          type: string
        providerKey:
          title: Providerkey
          type: string
        status:
          title: Status
          type: string
        updatedAt:
          description: UTC RFC 3339 timestamp string.
          examples:
          - '2026-06-12T12:00:00Z'
          title: Updatedat
          type: string
      required:
      - id
      - providerKey
      - displayName
      - status
      - createdAt
      - updatedAt
      title: ModelProviderResponse
      type: object
    PublicError:
      additionalProperties: false
      properties:
        code:
          type: string
        details:
          additionalProperties: true
          type: object
        docsUrl:
          format: uri
          type: string
        fieldErrors:
          items:
            $ref: '#/components/schemas/PublicFieldError'
          type: array
        message:
          type: string
        requestId:
          type: string
        status:
          type: integer
      required:
      - status
      - code
      - message
      - requestId
      - docsUrl
      - fieldErrors
      type: object
    Page_ModelResponse_:
      additionalProperties: false
      properties:
        data:
          items:
            $ref: '#/components/schemas/ModelResponse'
          title: Data
          type: array
        nextCursor:
          anyOf:
          - type: string
          - type: 'null'
          title: Nextcursor
      required:
      - data
      title: Page[ModelResponse]
      type: object
    CustomerPriceComponentResponse:
      additionalProperties: false
      properties:
        amount:
          title: Amount
          type: string
        metric:
          title: Metric
          type: string
        perQuantity:
          title: Perquantity
          type: integer
      required:
      - metric
      - amount
      - perQuantity
      title: CustomerPriceComponentResponse
      type: object
    CustomerPriceResponse:
      additionalProperties: false
      properties:
        components:
          items:
            $ref: '#/components/schemas/CustomerPriceComponentResponse'
          title: Components
          type: array
        currencyCode:
          title: Currencycode
          type: string
        effectiveAt:
          description: UTC RFC 3339 timestamp string.
          examples:
          - '2026-06-12T12:00:00Z'
          title: Effectiveat
          type: string
        fingerprint:
          title: Fingerprint
          type: string
        inputTokenMaximum:
          anyOf:
          - type: integer
          - type: 'null'
          title: Inputtokenmaximum
        maximumDebitAmount:
          title: Maximumdebitamount
          type: string
        rateBasis:
          title: Ratebasis
          type: string
        rateId:
          title: Rateid
          type: string
        retiredAt:
          anyOf:
          - description: UTC RFC 3339 timestamp string.
            examples:
            - '2026-06-12T12:00:00Z'
            type: string
          - type: 'null'
          title: Retiredat
        tiers:
          items:
            $ref: '#/components/schemas/CustomerPriceTierResponse'
          title: Tiers
          type: array
      required:
      - rateId
      - fingerprint
      - rateBasis
      - currencyCode
      - effectiveAt
      - retiredAt
      - inputTokenMaximum
      - maximumDebitAmount
      - components
      - tiers
      title: CustomerPriceResponse
      type: object
    PublicErrorEnvelope:
      additionalProperties: false
      properties:
        error:
          $ref: '#/components/schemas/PublicError'
      required:
      - error
      type: object
    CustomerPriceTierResponse:
      additionalProperties: false
      properties:
        components:
          items:
            $ref: '#/components/schemas/CustomerPriceComponentResponse'
          title: Components
          type: array
        inputTokensGreaterThan:
          title: Inputtokensgreaterthan
          type: integer
      required:
      - inputTokensGreaterThan
      - components
      title: CustomerPriceTierResponse
      type: object
    ModelObservationResponse:
      additionalProperties: false
      properties:
        accountVisible:
          title: Accountvisible
          type: boolean
        capabilities:
          additionalProperties: true
          title: Capabilities
          type: object
        displayName:
          anyOf:
          - type: string
          - type: 'null'
          title: Displayname
        freshness:
          title: Freshness
          type: string
        maxInputTokens:
          anyOf:
          - type: integer
          - type: 'null'
          title: Maxinputtokens
        maxOutputTokens:
          anyOf:
          - type: integer
          - type: 'null'
          title: Maxoutputtokens
        observedAt:
          description: UTC RFC 3339 timestamp string.
          examples:
          - '2026-06-12T12:00:00Z'
          title: Observedat
          type: string
        refreshId:
          minLength: 1
          title: Refreshid
          type: string
        releaseTime:
          anyOf:
          - description: UTC RFC 3339 timestamp string.
            examples:
            - '2026-06-12T12:00:00Z'
            type: string
          - type: 'null'
          title: Releasetime
      required:
      - refreshId
      - observedAt
      - freshness
      - accountVisible
      - displayName
      - releaseTime
      - maxInputTokens
      - maxOutputTokens
      - capabilities
      title: ModelObservationResponse
      type: object
    PublicFieldError:
      additionalProperties: false
      properties:
        actual: {}
        code:
          type: string
        expected: {}
        message:
          type: string
        source:
          $ref: '#/components/schemas/PublicFieldErrorSource'
      required:
      - source
      - code
      - message
      type: object
    PublicFieldErrorSource:
      additionalProperties: false
      minProperties: 1
      properties:
        formField:
          type: string
        header:
          type: string
        parameter:
          type: string
        pointer:
          type: string
      type: object
    ProviderPriceComponentResponse:
      additionalProperties: false
      properties:
        condition:
          additionalProperties: true
          title: Condition
          type: object
        conditionKey:
          title: Conditionkey
          type: string
        ratePerUnit:
          title: Rateperunit
          type: string
        unit:
          title: Unit
          type: string
        unitQuantity:
          title: Unitquantity
          type: integer
        usageCategory:
          title: Usagecategory
          type: string
      required:
      - usageCategory
      - conditionKey
      - condition
      - unit
      - unitQuantity
      - ratePerUnit
      title: ProviderPriceComponentResponse
      type: object
  securitySchemes:
    BearerAuth:
      scheme: bearer
      type: http
    BrowserCsrf:
      description: csrfToken returned by GET /v1/auth/session for the same authenticated browser session.
      in: header
      name: X-CSRF-Token
      type: apiKey
    BrowserSession:
      description: HttpOnly session cookie issued by browser login; deployment may configure its name.
      in: cookie
      name: everyn_session
      type: apiKey