Clarity Llm Admin API

openapi: 3.2.0
info:
  title: Fast Llm Admin API
  version: 0.1.0
tags:
- name: llm_admin
paths:
  /api/v1/admin/projects/{project_id}/llm/models:
    get:
      tags:
      - llm_admin
      summary: List Models
      description: The models each provider offers us, and whether ``/generate`` takes them.
      operationId: list_models_api_v1_admin_projects__project_id__llm_models_get
      security:
      - HTTPBearer: []
      parameters:
      - name: project_id
        in: path
        required: true
        schema:
          type: integer
          title: Project Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ModelCatalogResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/admin/projects/{project_id}/llm/generate:
    post:
      tags:
      - llm_admin
      summary: Generate
      description: Structured generation, as ``POST /api/v1/llm/generate``, recorded without a user.
      operationId: generate_api_v1_admin_projects__project_id__llm_generate_post
      security:
      - HTTPBearer: []
      parameters:
      - name: project_id
        in: path
        required: true
        schema:
          type: integer
          title: Project Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LlmGenerateRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LlmGenerateResponse'
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LlmErrorResponse'
          description: Bad Request
        '409':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LlmErrorResponse'
          description: Conflict
        '502':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LlmErrorResponse'
          description: Bad Gateway
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/admin/projects/{project_id}/llm/proxy/{provider}/v1/{path}:
    get:
      tags:
      - llm_admin
      summary: Forward to the provider
      description: 'Forward to the provider''s ``/v1/``, as the member route does, recorded without a

        user; ``X-Voc-Caller``/``-Purpose``/``-Trace-Id`` carry who called and why.'
      operationId: proxy_api_v1_admin_projects__project_id__llm_proxy__provider__v1__path__get
      security:
      - HTTPBearer: []
      parameters:
      - name: provider
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/src__llm__providers__upstreams__Provider'
      - name: path
        in: path
        required: true
        schema:
          type: string
          title: Path
      - name: project_id
        in: path
        required: true
        schema:
          type: integer
          title: Project Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    post:
      tags:
      - llm_admin
      summary: Forward to the provider
      description: 'Forward to the provider''s ``/v1/``, as the member route does, recorded without a

        user; ``X-Voc-Caller``/``-Purpose``/``-Trace-Id`` carry who called and why.'
      operationId: postApiV1AdminProjectsByProjectIdLlmProxyByProviderV1ByPath
      security:
      - HTTPBearer: []
      parameters:
      - name: provider
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/src__llm__providers__upstreams__Provider'
      - name: path
        in: path
        required: true
        schema:
          type: string
          title: Path
      - name: project_id
        in: path
        required: true
        schema:
          type: integer
          title: Project Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-operation-id-source: normalized
      x-operation-id-original: proxy_api_v1_admin_projects__project_id__llm_proxy__provider__v1__path__get
components:
  schemas:
    LlmErrorResponse:
      properties:
        detail:
          $ref: '#/components/schemas/LlmErrorDetail'
      type: object
      required:
      - detail
      title: LlmErrorResponse
    LlmUsageResponse:
      properties:
        input_tokens:
          type: integer
          title: Input Tokens
          description: Prompt tokens, cached ones included.
        cached_input_tokens:
          type: integer
          title: Cached Input Tokens
          description: Prompt tokens served from the provider's cache.
        output_tokens:
          type: integer
          title: Output Tokens
          description: Answer tokens, reasoning ones included.
        reasoning_tokens:
          type: integer
          title: Reasoning Tokens
          description: Tokens the model spent reasoning before answering.
      type: object
      required:
      - input_tokens
      - cached_input_tokens
      - output_tokens
      - reasoning_tokens
      title: LlmUsageResponse
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    JsonValue: {}
    LlmErrorDetail:
      properties:
        code:
          type: string
          title: Code
          description: invalid_request | provider_rejected | model_unavailable | refused | output_truncated | invalid_output | timeout | provider_busy | provider_unavailable
        message:
          type: string
          title: Message
      type: object
      required:
      - code
      - message
      title: LlmErrorDetail
    src__llm__providers__upstreams__Provider:
      type: string
      enum:
      - openai
      - anthropic
      title: Provider
    ModelCatalogResponse:
      properties:
        providers:
          items:
            $ref: '#/components/schemas/ProviderModels'
          type: array
          title: Providers
      type: object
      required:
      - providers
      title: ModelCatalogResponse
    LlmGenerateRequest:
      properties:
        prompt:
          type: string
          minLength: 1
          title: Prompt
          description: The task.
        system:
          anyOf:
          - type: string
          - type: 'null'
          title: System
          description: System instructions.
        input:
          $ref: '#/components/schemas/JsonValue'
          description: Data for the task, sent to the model as JSON.
        schema:
          additionalProperties:
            $ref: '#/components/schemas/JsonValue'
          type: object
          title: Schema
          description: 'JSON Schema of the answer, in OpenAI strict mode: the root is an object and every object lists all of its properties in `required` (an optional field is a nullable type).'
        model:
          anyOf:
          - type: string
          - type: 'null'
          title: Model
          description: An OpenAI model id from GET /api/v1/llm/models. Omitted or empty = the project's base model (config llm.base_model) with its preset's defaults.
        config:
          $ref: '#/components/schemas/OpenAIGenerationConfig'
        caller:
          anyOf:
          - $ref: '#/components/schemas/LlmCaller'
          - type: 'null'
      additionalProperties: false
      type: object
      required:
      - prompt
      - schema
      title: LlmGenerateRequest
    LlmGenerateResponse:
      properties:
        data:
          additionalProperties:
            $ref: '#/components/schemas/JsonValue'
          type: object
          title: Data
          description: The answer, already validated against the schema.
        model:
          type: string
          title: Model
          description: The model that answered.
        usage:
          anyOf:
          - $ref: '#/components/schemas/LlmUsageResponse'
          - type: 'null'
      type: object
      required:
      - data
      - model
      title: LlmGenerateResponse
    ProviderModels:
      properties:
        provider:
          type: string
          title: Provider
        generate:
          type: boolean
          title: Generate
          description: Whether POST /api/v1/llm/generate takes this provider's models.
        models:
          items:
            $ref: '#/components/schemas/ModelInfo'
          type: array
          title: Models
        error:
          anyOf:
          - type: string
          - type: 'null'
          title: Error
          description: Set when the provider's list could not be read.
      type: object
      required:
      - provider
      - generate
      - models
      title: ProviderModels
    ModelInfo:
      properties:
        id:
          type: string
          title: Id
          description: The model id to send as `model`.
        display_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Display Name
          description: Anthropic's display name; OpenAI has none.
        created_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Created At
          description: ISO 8601, as the provider reports it.
        owned_by:
          anyOf:
          - type: string
          - type: 'null'
          title: Owned By
      type: object
      required:
      - id
      title: ModelInfo
    LlmCaller:
      properties:
        surface:
          type: string
          enum:
          - mini_app
          - report
          - dashboard
          - canvas
          - cloud_function
          title: Surface
        ref:
          anyOf:
          - type: string
            maxLength: 200
          - type: 'null'
          title: Ref
          description: Mini-app slug, widget id or cloud function id.
      additionalProperties: false
      type: object
      required:
      - surface
      title: LlmCaller
      description: Where the call comes from, as the host page knows it. Recorded for accounting only.
    OpenAIGenerationConfig:
      properties:
        temperature:
          anyOf:
          - type: number
            maximum: 2.0
            minimum: 0.0
          - type: 'null'
          title: Temperature
          description: Sampling temperature. Sent as given; a model that does not take one (gpt-5) rejects it.
        effort:
          anyOf:
          - type: string
            enum:
            - none
            - minimal
            - low
            - medium
            - high
            - xhigh
          - type: 'null'
          title: Effort
          description: Reasoning effort. Omitted = the model preset's default. Not every model takes every level.
      additionalProperties: false
      type: object
      title: OpenAIGenerationConfig
      description: 'Provider-specific settings. Only OpenAI is called today, so these are OpenAI''s. An

        unknown key is refused rather than ignored, so a setting added later never silently

        changes what an existing caller gets.'
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer
    HTTPBasic:
      type: http
      scheme: basic