klisten-co-kr Modelroute API

openapi: 3.2.0
info:
  title: Klisten Co Kr Modelroute API
  version: 0.1.0
  description: 'Operations tagged Modelroute across 2 of this provider''s published API definitions: klisten-co-kr-models-openapi.json, klisten-co-kr-openapi.json. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.klisten.co.kr
tags:
- name: Modelroute
paths:
  /v1/modelroute/catalog:
    get:
      operationId: getModelRouteCatalog
      summary: Read the last published model metadata snapshot
      responses:
        '200':
          description: Last published snapshot; may be stale. Check expiry before using.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Catalog'
        '404':
          description: No published catalog
        '503':
          description: Temporarily unavailable
      tags:
      - Modelroute
    servers:
    - url: https://api.klisten.co.kr
  /v1/modelroute/select:
    post:
      operationId: selectDiscoveredModels
      security:
      - ApiKey: []
      x-required-scope: models:select
      x-implementation-status: private-development
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ModelRouteDecision'
        '400':
          description: Request denied or dependency unavailable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Request denied or dependency unavailable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Request denied or dependency unavailable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Request denied or dependency unavailable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: Request denied or dependency unavailable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '413':
          description: Request denied or dependency unavailable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: Request denied or dependency unavailable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Request denied or dependency unavailable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Request denied or dependency unavailable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: Request denied or dependency unavailable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      description: Recommendation only; no inference or payment. Uses the operator discovery store and server time. No client catalog, price, tenant or trust override. Quality benchmark ID, version and threshold must be supplied together. Maximum body 16384 bytes. Idempotency replays the stored historical decision.
      parameters:
      - name: Idempotency-Key
        in: header
        required: true
        schema:
          type: string
          minLength: 16
          maxLength: 128
          pattern: ^[A-Za-z0-9._:-]+$
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ModelRouteRequest'
      tags:
      - Modelroute
      summary: Select discovered models
      x-summary-source: derived
  /v1/modelroute/decisions/{id}:
    get:
      operationId: getModelRouteDecision
      security:
      - ApiKey: []
      x-required-scope: models:read
      x-implementation-status: private-development
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ModelRouteDecision'
        '400':
          description: Request denied or dependency unavailable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Request denied or dependency unavailable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Request denied or dependency unavailable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Request denied or dependency unavailable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: Request denied or dependency unavailable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '413':
          description: Request denied or dependency unavailable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: Request denied or dependency unavailable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Request denied or dependency unavailable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Request denied or dependency unavailable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: Request denied or dependency unavailable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      description: Tenant-private historical recommendation; does not refresh the catalog or call a model.
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      tags:
      - Modelroute
      summary: Get model route decision
      x-summary-source: derived
components:
  schemas:
    Offering:
      type: object
      required:
      - id
      - name
      - pricing_class
      - presence
      - rate_unit
      - issues
      - context_tokens
      - max_output_tokens
      - input_rate
      - output_rate
      - fixed_micro_usd
      - observed_at
      - expires_at
      properties:
        id:
          type: string
        name:
          type: string
        pricing_class:
          enum:
          - free
          - paid
          - unknown
        presence:
          enum:
          - listed
          - missing
        rate_unit:
          const: micro_usd_per_million_tokens
        issues:
          type: array
          items:
            type: string
        context_tokens:
          type:
          - integer
          - 'null'
          minimum: 0
        max_output_tokens:
          type:
          - integer
          - 'null'
          minimum: 0
        input_rate:
          type:
          - integer
          - 'null'
          minimum: 0
        output_rate:
          type:
          - integer
          - 'null'
          minimum: 0
        fixed_micro_usd:
          type:
          - integer
          - 'null'
          minimum: 0
        observed_at:
          type: string
          format: date-time
        expires_at:
          type: string
          format: date-time
    Catalog:
      type: object
      required:
      - observed_at
      - expires_at
      - schema_version
      - stage
      - snapshot_id
      - source_url
      - source_status
      - counts
      - offerings
      properties:
        observed_at:
          type: string
          format: date-time
        expires_at:
          type: string
          format: date-time
        schema_version:
          const: modelroute.public-catalog.v1
        stage:
          const: discovery-beta
        snapshot_id:
          type: string
          pattern: ^[a-f0-9]{64}$
        source_url:
          type: string
          format: uri
        source_status:
          enum:
          - current
          - stale
          - not_yet_valid
        counts:
          type: object
          description: All retained records, including missing records; not currently available model counts.
          properties:
            total:
              type: integer
              minimum: 0
            free:
              type: integer
              minimum: 0
            paid:
              type: integer
              minimum: 0
            unknown:
              type: integer
              minimum: 0
        offerings:
          type: array
          maxItems: 10000
          items:
            $ref: '#/components/schemas/Offering'
    ModelRouteRequest:
      $schema: https://json-schema.org/draft/2020-12/schema
      type: object
      properties:
        task:
          type: string
          minLength: 1
          maxLength: 256
        input_tokens:
          anyOf:
          - type: integer
            minimum: 0
            maximum: 9007199254740991
          - type: 'null'
        max_output_tokens:
          anyOf:
          - type: integer
            minimum: 1
            maximum: 9007199254740991
          - type: 'null'
        max_cost_micro_usd:
          type: integer
          minimum: 0
          maximum: 9007199254740991
        required_capabilities:
          default: []
          maxItems: 128
          type: array
          items:
            type: string
            minLength: 1
            maxLength: 256
        provider_allowlist:
          maxItems: 128
          type: array
          items:
            type: string
            minLength: 1
            maxLength: 256
        region:
          type: string
          minLength: 1
          maxLength: 256
        benchmark_id:
          type: string
          minLength: 1
          maxLength: 256
        benchmark_version:
          type: string
          minLength: 1
          maxLength: 256
        min_quality:
          type: number
          minimum: 0
          maximum: 1
      required:
      - task
      - max_cost_micro_usd
      additionalProperties: false
    ModelRouteDecision:
      $schema: https://json-schema.org/draft/2020-12/schema
      type: object
      properties:
        id:
          type: string
          format: uuid
          pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
        scope:
          type: object
          properties:
            org_id:
              type: string
              format: uuid
              pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
            visibility:
              type: string
              const: private
          required:
          - org_id
          - visibility
          additionalProperties: false
        mode:
          type: string
          const: recommendation_only
        snapshot_id:
          type: string
        source_status:
          type: string
          enum:
          - current
          - stale
          - not_yet_valid
        availability_basis:
          type: string
          const: source_listing
        decision:
          type: object
          properties:
            policy_version:
              type: string
              const: modelroute.selection.v1
            status:
              type: string
              enum:
              - SELECTED
              - NO_ELIGIBLE_MODEL
              - INPUT_REQUIRED
            selected_model_id:
              type:
              - string
              - 'null'
            evaluated_at:
              type: string
              format: date-time
              pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$
            request_snapshot:
              type: object
              properties:
                task:
                  type: string
                  minLength: 1
                  maxLength: 256
                input_tokens:
                  anyOf:
                  - type: integer
                    minimum: 0
                    maximum: 9007199254740991
                  - type: 'null'
                max_output_tokens:
                  anyOf:
                  - type: integer
                    minimum: 1
                    maximum: 9007199254740991
                  - type: 'null'
                max_cost_micro_usd:
                  type: integer
                  minimum: 0
                  maximum: 9007199254740991
                required_capabilities:
                  default: []
                  maxItems: 128
                  type: array
                  items:
                    type: string
                    minLength: 1
                    maxLength: 256
                provider_allowlist:
                  maxItems: 128
                  type: array
                  items:
                    type: string
                    minLength: 1
                    maxLength: 256
                region:
                  type: string
                  minLength: 1
                  maxLength: 256
                benchmark_id:
                  type: string
                  minLength: 1
                  maxLength: 256
                benchmark_version:
                  type: string
                  minLength: 1
                  maxLength: 256
                min_quality:
                  type: number
                  minimum: 0
                  maximum: 1
              required:
              - task
              - max_cost_micro_usd
              additionalProperties: false
            catalog_snapshot:
              type: array
              items:
                type: object
                properties:
                  id:
                    type: string
                    minLength: 1
                    maxLength: 256
                  provider:
                    type: string
                    minLength: 1
                    maxLength: 256
                  available:
                    type: boolean
                  tasks:
                    maxItems: 128
                    type: array
                    items:
                      type: string
                      minLength: 1
                      maxLength: 256
                  capabilities:
                    maxItems: 128
                    type: array
                    items:
                      type: string
                      minLength: 1
                      maxLength: 256
                  regions:
                    maxItems: 128
                    type: array
                    items:
                      type: string
                      minLength: 1
                      maxLength: 256
                  context_tokens:
                    type: integer
                    minimum: 1
                    maximum: 9007199254740991
                  max_output_tokens:
                    type: integer
                    minimum: 1
                    maximum: 9007199254740991
                  observed_at:
                    type: string
                    pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$
                  expires_at:
                    type: string
                    pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$
                  price:
                    anyOf:
                    - type: object
                      properties:
                        version:
                          type: string
                          minLength: 1
                          maxLength: 256
                        currency:
                          type: string
                          minLength: 1
                          maxLength: 256
                        unit:
                          type: string
                          minLength: 1
                          maxLength: 256
                        input_rate:
                          type: integer
                          minimum: 0
                          maximum: 9007199254740991
                        output_rate:
                          type: integer
                          minimum: 0
                          maximum: 9007199254740991
                        fixed_micro_usd:
                          type: integer
                          minimum: 0
                          maximum: 9007199254740991
                        complete_upper_bound:
                          type: boolean
                        valid_from:
                          type: string
                          pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$
                        expires_at:
                          type: string
                          pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$
                        source:
                          type: object
                          properties:
                            kind:
                              type: string
                              enum:
                              - official
                              - third_party
                            url:
                              type: string
                              maxLength: 2048
                              format: uri
                          required:
                          - kind
                          - url
                          additionalProperties: false
                      required:
                      - version
                      - currency
                      - unit
                      - input_rate
                      - output_rate
                      - fixed_micro_usd
                      - complete_upper_bound
                      - valid_from
                      - expires_at
                      - source
                      additionalProperties: false
                    - type: 'null'
                  quality:
                    maxItems: 256
                    type: array
                    items:
                      type: object
                      properties:
                        benchmark_id:
                          type: string
                          minLength: 1
                          maxLength: 256
                        benchmark_version:
                          type: string
                          minLength: 1
                          maxLength: 256
                        task:
                          type: string
                          minLength: 1
                          maxLength: 256
                        score:
                          type: number
                          minimum: 0
                          maximum: 1
                        samples:
                          type: integer
                          minimum: 1
                          maximum: 9007199254740991
                        observed_at:
                          type: string
                          pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$
                        expires_at:
                          type: string
                          pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$
                        source_url:
                          type: string
                          maxLength: 2048
                          format: uri
                      required:
                      - benchmark_id
                      - benchmark_version
                      - task
                      - score
                      - samples
                      - observed_at
                      - expires_at
                      - source_url
                      additionalProperties: false
                required:
                - id
                - provider
                - available
                - tasks
                - capabilities
                - regions
                - context_tokens
                - max_output_tokens
                - observed_at
                - expires_at
                - price
                - quality
                additionalProperties: false
            required_inputs:
              type: array
              items:
                type: string
                enum:
                - input_tokens
                - max_output_tokens
            candidates:
              type: array
              items:
                type: object
                properties:
                  model_id:
                    type: string
                  provider:
                    type: string
                  eligible:
                    type: boolean
                  exclusions:
                    type: array
                    items:
                      type: string
                      enum:
                      - UNAVAILABLE
                      - TASK_UNSUPPORTED
                      - CAPABILITY_UNSUPPORTED
                      - PROVIDER_DISALLOWED
                      - REGION_UNSUPPORTED
                      - CONTEXT_LIMIT
                      - OUTPUT_LIMIT
                      - CAPABILITIES_NOT_CURRENT
                      - PRICE_MISSING
                      - PRICE_STALE
                      - PRICE_NOT_YET_VALID
                      - PRICE_SOURCE_UNTRUSTED
                      - PRICE_BOUND_INCOMPLETE
                      - PRICE_CURRENCY_UNSUPPORTED
                      - PRICE_UNIT_UNSUPPORTED
                      - COST_OUT_OF_RANGE
                      - BUDGET_EXCEEDED
                      - QUALITY_MISSING_OR_INCOMPARABLE
                      - QUALITY_NOT_CURRENT
                      - QUALITY_AMBIGUOUS
                      - QUALITY_BELOW_MINIMUM
                  upper_cost_micro_usd:
                    anyOf:
                    - type: integer
                      minimum: 0
                      maximum: 9007199254740991
                    - type: 'null'
                  price_snapshot:
                    anyOf:
                    - type: object
                      properties:
                        version:
                          type: string
                          minLength: 1
                          maxLength: 256
                        currency:
                          type: string
                          minLength: 1
                          maxLength: 256
                        unit:
                          type: string
                          minLength: 1
                          maxLength: 256
                        input_rate:
                          type: integer
                          minimum: 0
                          maximum: 9007199254740991
                        output_rate:
                          type: integer
                          minimum: 0
                          maximum: 9007199254740991
                        fixed_micro_usd:
                          type: integer
                          minimum: 0
                          maximum: 9007199254740991
                        complete_upper_bound:
                          type: boolean
                        valid_from:
                          type: string
                          pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$
                        expires_at:
                          type: string
                          pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$
                        source:
                          type: object
                          properties:
                            kind:
                              type: string
                              enum:
                              - official
                              - third_party
                            url:
                              type: string
                              maxLength: 2048
                              format: uri
                          required:
                          - kind
                          - url
                          additionalProperties: false
                      required:
                      - version
                      - currency
                      - unit
                      - input_rate
                      - output_rate
                      - fixed_micro_usd
                      - complete_upper_bound
                      - valid_from
                      - expires_at
                      - source
                      additionalProperties: false
                    - type: 'null'
                  quality_snapshot:
                    anyOf:
                    - type: object
                      properties:
                        benchmark_id:
                          type: string
                          minLength: 1
                          maxLength: 256
                        benchmark_version:
                          type: string
                          minLength: 1
                          maxLength: 256
                        task:
                          type: string
                          minLength: 1
                          maxLength: 256
                        score:
                          type: number
                          minimum: 0
                          maximum: 1
                        samples:
                          type: integer
                          minimum: 1
                          maximum: 9007199254740991
                        observed_at:
                          type: string
                          pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$
                        expires_at:
                          type: string
                          pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$
                        source_url:
                          type: string
                          maxLength: 2048
                          format: uri
                      required:
                      - benchmark_id
                      - benchmark_version
                      - task
                      - score
                      - samples
                      - observed_at
                      - expires_at
                      - source_url
                      additionalProperties: false
                    - type: 'null'
                required:
                - model_id
                - provider
                - eligible
                - exclusions
                - upper_cost_micro_usd
                - price_snapshot
                - quality_snapshot
                additionalProperties: false
            ranking:
              type: array
              items:
                type: string
          required:
          - policy_version
          - status
          - selected_model_id
          - evaluated_at
          - request_snapshot
          - catalog_snapshot
          - required_inputs
          - candidates
          - ranking
          additionalProperties: false
      required:
      - id
      - scope
      - mode
      - snapshot_id
      - source_status
      - availability_basis
      - decision
      additionalProperties: false
    Error:
      $schema: https://json-schema.org/draft/2020-12/schema
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
            message:
              type: string
            request_id:
              type: string
              pattern: ^req_[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$
            retryable:
              type: boolean
          required:
          - code
          - message
          - request_id
          - retryable
          additionalProperties: false
      required:
      - error
      additionalProperties: false
  securitySchemes:
    ApiKey:
      type: http
      scheme: bearer
      bearerFormat: ck_live_<secret>
    SupabaseHuman:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Supabase access token for a verified Google user in the configured project. Agent API keys are not accepted.
x-refined-from:
- klisten-co-kr-models-openapi.json
- klisten-co-kr-openapi.json