Skip to content

🪢 Open source agent evals & observability: Trace, evaluate, and improve LLM applications with one open platform.

431 KB
Raw Blame
openapi: 3.0.1
info:
  title: server
  version: ''
  description: >-
    ## Real-time data


    The only real-time path to get tracing data is to ingest via OpenTelemetry
    (`POST /api/public/otel/v1/traces`) and retrieve via Observations API v2
    (`GET /api/public/v2/observations`) and Metrics API v2 (`GET
    /api/public/v2/metrics`). Other public API write and read endpoints can
    delay data by about 10 minutes. Direct OpenTelemetry exporters must send the
    `x-langfuse-ingestion-version: 4` header; current Python and JS SDKs already
    do. See the [Public API
    docs](https://langfuse.com/docs/api-and-data-platform/features/public-api)
    and [real-time
    ingestion](https://langfuse.com/integrations/native/opentelemetry.md#real-time-ingestion).


    ## Authentication


    Authenticate with the API using [Basic
    Auth](https://en.wikipedia.org/wiki/Basic_access_authentication), get API
    keys in the project settings:


    - username: Langfuse Public Key

    - password: Langfuse Secret Key


    ## Exports


    - OpenAPI spec: https://cloud.langfuse.com/generated/api/openapi.yml

    - Self-hosted deployments: interactive API reference at `/api/docs` and
    OpenAPI spec at `/api/openapi.yaml`
paths:
  /api/public/annotation-queues:
    get:
      description: Get all annotation queues
      operationId: annotationQueues_listQueues
      tags:
        - AnnotationQueues
      parameters:
        - name: page
          in: query
          description: page number, starts at 1
          required: false
          schema:
            type: integer
            nullable: true
        - name: limit
          in: query
          description: limit of items per page
          required: false
          schema:
            type: integer
            nullable: true
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedAnnotationQueues'
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
      security: &ref_0
        - BasicAuth: []
    post:
      description: Create an annotation queue
      operationId: annotationQueues_createQueue
      tags:
        - AnnotationQueues
      parameters: []
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnnotationQueue'
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
      security: *ref_0
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateAnnotationQueueRequest'
  /api/public/annotation-queues/{queueId}:
    get:
      description: Get an annotation queue by ID
      operationId: annotationQueues_getQueue
      tags:
        - AnnotationQueues
      parameters:
        - name: queueId
          in: path
          description: The unique identifier of the annotation queue
          required: true
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnnotationQueue'
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
      security: *ref_0
  /api/public/annotation-queues/{queueId}/items:
    get:
      description: Get items for a specific annotation queue
      operationId: annotationQueues_listQueueItems
      tags:
        - AnnotationQueues
      parameters:
        - name: queueId
          in: path
          description: The unique identifier of the annotation queue
          required: true
          schema:
            type: string
        - name: status
          in: query
          description: Filter by status
          required: false
          schema:
            $ref: '#/components/schemas/AnnotationQueueStatus'
            nullable: true
        - name: page
          in: query
          description: page number, starts at 1
          required: false
          schema:
            type: integer
            nullable: true
        - name: limit
          in: query
          description: limit of items per page
          required: false
          schema:
            type: integer
            nullable: true
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedAnnotationQueueItems'
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
      security: *ref_0
    post:
      description: Add an item to an annotation queue
      operationId: annotationQueues_createQueueItem
      tags:
        - AnnotationQueues
      parameters:
        - name: queueId
          in: path
          description: The unique identifier of the annotation queue
          required: true
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnnotationQueueItem'
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
      security: *ref_0
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateAnnotationQueueItemRequest'
  /api/public/annotation-queues/{queueId}/items/{itemId}:
    get:
      description: Get a specific item from an annotation queue
      operationId: annotationQueues_getQueueItem
      tags:
        - AnnotationQueues
      parameters:
        - name: queueId
          in: path
          description: The unique identifier of the annotation queue
          required: true
          schema:
            type: string
        - name: itemId
          in: path
          description: The unique identifier of the annotation queue item
          required: true
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnnotationQueueItem'
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
      security: *ref_0
    patch:
      description: Update an annotation queue item
      operationId: annotationQueues_updateQueueItem
      tags:
        - AnnotationQueues
      parameters:
        - name: queueId
          in: path
          description: The unique identifier of the annotation queue
          required: true
          schema:
            type: string
        - name: itemId
          in: path
          description: The unique identifier of the annotation queue item
          required: true
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnnotationQueueItem'
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
      security: *ref_0
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateAnnotationQueueItemRequest'
    delete:
      description: Remove an item from an annotation queue
      operationId: annotationQueues_deleteQueueItem
      tags:
        - AnnotationQueues
      parameters:
        - name: queueId
          in: path
          description: The unique identifier of the annotation queue
          required: true
          schema:
            type: string
        - name: itemId
          in: path
          description: The unique identifier of the annotation queue item
          required: true
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteAnnotationQueueItemResponse'
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
      security: *ref_0
  /api/public/annotation-queues/{queueId}/assignments:
    post:
      description: Create an assignment for a user to an annotation queue
      operationId: annotationQueues_createQueueAssignment
      tags:
        - AnnotationQueues
      parameters:
        - name: queueId
          in: path
          description: The unique identifier of the annotation queue
          required: true
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateAnnotationQueueAssignmentResponse'
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
      security: *ref_0
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AnnotationQueueAssignmentRequest'
    delete:
      description: Delete an assignment for a user to an annotation queue
      operationId: annotationQueues_deleteQueueAssignment
      tags:
        - AnnotationQueues
      parameters:
        - name: queueId
          in: path
          description: The unique identifier of the annotation queue
          required: true
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteAnnotationQueueAssignmentResponse'
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
      security: *ref_0
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AnnotationQueueAssignmentRequest'
  /api/public/integrations/blob-storage:
    get:
      description: >-
        Get all blob storage integrations for the organization (requires
        organization-scoped API key)
      operationId: blobStorageIntegrations_getBlobStorageIntegrations
      tags:
        - BlobStorageIntegrations
      parameters: []
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BlobStorageIntegrationsResponse'
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
      security: *ref_0
    put:
      description: >-
        Create or update a blob storage integration for a specific project
        (requires organization-scoped API key). The configuration is validated
        by performing a test upload to the bucket.
      operationId: blobStorageIntegrations_upsertBlobStorageIntegration
      tags:
        - BlobStorageIntegrations
      parameters: []
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BlobStorageIntegrationResponse'
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
      security: *ref_0
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateBlobStorageIntegrationRequest'
  /api/public/integrations/blob-storage/{id}:
    get:
      description: >-
        Get the sync status of a blob storage integration by integration ID
        (requires organization-scoped API key)
      operationId: blobStorageIntegrations_getBlobStorageIntegrationStatus
      tags:
        - BlobStorageIntegrations
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BlobStorageIntegrationStatusResponse'
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
      security: *ref_0
    delete:
      description: >-
        Delete a blob storage integration by ID (requires organization-scoped
        API key)
      operationId: blobStorageIntegrations_deleteBlobStorageIntegration
      tags:
        - BlobStorageIntegrations
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BlobStorageIntegrationDeletionResponse'
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
      security: *ref_0
  /api/public/comments:
    post:
      description: >-
        Create a comment. Comments may be attached to different object types
        (trace, observation, session, prompt).
      operationId: comments_create
      tags:
        - Comments
      parameters: []
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateCommentResponse'
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
      security: *ref_0
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateCommentRequest'
    get:
      description: Get all comments
      operationId: comments_get
      tags:
        - Comments
      parameters:
        - name: page
          in: query
          description: Page number, starts at 1.
          required: false
          schema:
            type: integer
            nullable: true
        - name: limit
          in: query
          description: >-
            Limit of items per page. If you encounter api issues due to too
            large page sizes, try to reduce the limit
          required: false
          schema:
            type: integer
            nullable: true
        - name: objectType
          in: query
          description: >-
            Filter comments by object type (trace, observation, session, prompt).
          required: false
          schema:
            type: string
            nullable: true
        - name: objectId
          in: query
          description: >-
            Filter comments by object id. If objectType is not provided, an
            error will be thrown.
          required: false
          schema:
            type: string
            nullable: true
        - name: authorUserId
          in: query
          description: Filter comments by author user id.
          required: false
          schema:
            type: string
            nullable: true
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetCommentsResponse'
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
      security: *ref_0
  /api/public/comments/{commentId}:
    get:
      description: Get a comment by id
      operationId: comments_get-by-id
      tags:
        - Comments
      parameters:
        - name: commentId
          in: path
          description: The unique langfuse identifier of a comment
          required: true
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Comment'
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
      security: *ref_0
  /api/public/dataset-items:
    post:
      description: Create a dataset item
      operationId: datasetItems_create
      tags:
        - DatasetItems
      parameters: []
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DatasetItem'
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
      security: *ref_0
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateDatasetItemRequest'
    get:
      description: >-
        Get dataset items. Optionally specify a version to get the items as they
        existed at that point in time.

        Note: If version parameter is provided, datasetName must also be
        provided.
      operationId: datasetItems_list
      tags:
        - DatasetItems
      parameters:
        - name: datasetName
          in: query
          required: false
          schema:
            type: string
            nullable: true
        - name: sourceTraceId
          in: query
          required: false
          schema:
            type: string
            nullable: true
        - name: sourceObservationId
          in: query
          required: false
          schema:
            type: string
            nullable: true
        - name: version
          in: query
          description: >-
            ISO 8601 timestamp (RFC 3339, Section 5.6) in UTC (e.g.,
            "2026-01-21T14:35:42Z").

            If provided, returns state of dataset at this timestamp.

            If not provided, returns the latest version. Requires datasetName to
            be specified.
          required: false
          schema:
            type: string
            format: date-time
            nullable: true
        - name: page
          in: query
          description: page number, starts at 1
          required: false
          schema:
            type: integer
            nullable: true
        - name: limit
          in: query
          description: limit of items per page
          required: false
          schema:
            type: integer
            nullable: true
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedDatasetItems'
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
      security: *ref_0
  /api/public/dataset-items/{id}:
    get:
      description: Get a dataset item
      operationId: datasetItems_get
      tags:
        - DatasetItems
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DatasetItem'
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
      security: *ref_0
    delete:
      description: >-
        Delete a dataset item and all its run items. This action is irreversible.
      operationId: datasetItems_delete
      tags:
        - DatasetItems
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteDatasetItemResponse'
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
      security: *ref_0
  /api/public/v2/datasets:
    get:
      description: Get all datasets
      operationId: datasets_list
      tags:
        - Datasets
      parameters:
        - name: page
          in: query
          description: page number, starts at 1
          required: false
          schema:
            type: integer
            nullable: true
        - name: limit
          in: query
          description: limit of items per page
          required: false
          schema:
            type: integer
            nullable: true
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedDatasets'
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
      security: *ref_0
    post:
      description: Create a dataset
      operationId: datasets_create
      tags:
        - Datasets
      parameters: []
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Dataset'
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
      security: *ref_0
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateDatasetRequest'
  /api/public/v2/datasets/{datasetName}:
    get:
      description: Get a dataset
      operationId: datasets_get
      tags:
        - Datasets
      parameters:
        - name: datasetName
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Dataset'
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
      security: *ref_0
  /api/public/v2/evaluation-rules:
    post:
      description: >-
        Create an evaluation rule using stable evaluator identifiers.


        An evaluation rule defines **which** incoming observations should be
        evaluated and how prompt variables should be populated.


        Key behavior:

        - rule names are not identifiers and do not need to be unique

        - rules always use the latest version of each associated evaluator

        - an enabled rule requires at least one evaluator assignment

        - omit `sampling` to evaluate every matching observation

        - omit `filter` to match every incoming observation

        - `datasetId` is the public filter name for selecting experiment
        datasets
      operationId: evaluationRules_create
      tags:
        - EvaluationRules
      parameters: []
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EvaluationRule'
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
        '409':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiError'
        '429':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiError'
        '500':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiError'
      security: *ref_0
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateEvaluationRuleRequest'
    get:
      description: >-
        List evaluation rules in newest-first creation order.


        This includes legacy trace and dataset rules so they can be inspected
        and migrated. Treat the cursor as opaque and return it unchanged.
      operationId: evaluationRules_list
      tags:
        - EvaluationRules
      parameters:
        - name: limit
          in: query
          description: >-
            Maximum number of items to return. Defaults to `50` and cannot
            exceed `100`.
          required: false
          schema:
            type: integer
            nullable: true
        - name: cursor
          in: query
          description: Opaque cursor returned by the previous page.
          required: false
          schema:
            type: string
            nullable: true
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EvaluationRulesPage'
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
        '429':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiError'
        '500':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiError'
      security: *ref_0
  /api/public/v2/evaluation-rules/{evaluationRuleId}:
    get:
      description: >-
        Get one evaluation rule, including a legacy trace or dataset rule, by
        its stable identifier.
      operationId: evaluationRules_get
      tags:
        - EvaluationRules
      parameters:
        - name: evaluationRuleId
          in: path
          description: >-
            Stable evaluation-rule identifier returned by the evaluation-rule
            endpoints.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EvaluationRule'
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
        '429':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiError'
        '500':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiError'
      security: *ref_0
    patch:
      description: >-
        Update an evaluation rule by its stable identifier.


        Provide only the fields to change. Providing `evaluatorAssignments`
        replaces the complete assignment list. Replacing the list with an empty
        array disables the rule. Setting `enabled=true` is rejected when the
        resulting assignment list is empty, including when both fields are sent
        in the same request.


        Legacy trace and dataset rules follow the existing lifecycle
        restrictions: they can be deactivated with `enabled=false`, but their
        name, filters, sampling, and evaluator assignments cannot be changed.
      operationId: evaluationRules_update
      tags:
        - EvaluationRules
      parameters:
        - name: evaluationRuleId
          in: path
          description: >-
            Stable evaluation-rule identifier returned by the evaluation-rule
            endpoints.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EvaluationRule'
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
        '409':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiError'
        '429':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiError'
        '500':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiError'
      security: *ref_0
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateEvaluationRuleRequest'
    delete:
      description: >-
        Delete an evaluation rule.


        This removes the live-ingestion rule only. It does not delete associated
        evaluators or scores already produced by them.


        Legacy trace and dataset rules can also be deleted. Their evaluators and
        previously produced scores are preserved.
      operationId: evaluationRules_delete
      tags:
        - EvaluationRules
      parameters:
        - name: evaluationRuleId
          in: path
          description: >-
            Stable evaluation-rule identifier returned by the evaluation-rule
            endpoints.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeletedEvaluationRule'
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
        '429':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiError'
        '500':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiError'
      security: *ref_0
  /api/public/v2/evaluators:
    post:
      description: >-
        Create an evaluator in the authenticated project.


        An evaluator defines **how** Langfuse should score data. LLM-as-a-judge
        evaluators define a prompt, expected structured output, and optional
        model configuration. Code evaluators define source code and a runtime
        language.


        This always creates a new evaluator with version `1`. Names are not
        identifiers and do not need to be unique.
      operationId: evaluators_create
      tags:
        - Evaluators
      parameters: []
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Evaluator'
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
        '412':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiError'
        '429':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiError'
        '500':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiError'
      security: *ref_0
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateEvaluatorRequest'
    get:
      description: >-
        List evaluators in newest-first creation order.


        Every evaluator includes its latest definition and version metadata
        flattened into the evaluator object, plus associated evaluation rules.
        Treat the cursor as opaque and return it unchanged.
      operationId: evaluators_list
      tags:
        - Evaluators
      parameters:
        - name: limit
          in: query
          description: >-
            Maximum number of items to return. Defaults to `50` and cannot
            exceed `100`.
          required: false
          schema:
            type: integer
            nullable: true
        - name: cursor
          in: query
          description: Opaque cursor returned by the previous page.
          required: false
          schema:
            type: string
            nullable: true
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EvaluatorsPage'
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
        '429':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiError'
        '500':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiError'
      security: *ref_0
  /api/public/v2/evaluators/{evaluatorId}:
    get:
      description: >-
        Get one evaluator by its stable identifier.


        The response includes the evaluator's latest definition and version
        metadata flattened into the evaluator object, plus associated evaluation
        rules. Use the version-history endpoint when older definitions are
        needed.
      operationId: evaluators_get
      tags:
        - Evaluators
      parameters:
        - name: evaluatorId
          in: path
          description: Stable evaluator identifier returned by the evaluator endpoints.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Evaluator'
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
        '429':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiError'
        '500':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiError'
      security: *ref_0
    patch:
      description: >-
        Update an evaluator by its stable identifier.


        Provide only the top-level fields to change. Metadata-only changes do
        not create a version. Evaluator type cannot change.


        Definition fields are flattened into the request. To replace a
        definition, include `type` and every definition field for that type.
        Definition fields are replaced as a complete unit rather than merged.
        For LLM-as-a-judge evaluators, omitting or setting `modelConfig` to
        `null` selects the project's default evaluation model.


        Replacing a definition automatically returns an evaluator paused by an
        invalid or missing model configuration to `active`, while preserving its
        id and evaluation-rule assignments. Pauses caused by provider
        authentication, billing, connectivity, account state, or an unknown
        legacy reason remain paused until the explicit reactivation check
        succeeds.
      operationId: evaluators_update
      tags:
        - Evaluators
      parameters:
        - name: evaluatorId
          in: path
          description: Stable evaluator identifier returned by the evaluator endpoints.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Evaluator'
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
        '409':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiError'
        '412':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiError'
        '429':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiError'
        '500':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiError'
      security: *ref_0
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateEvaluatorRequest'
    delete:
      description: >-
        Delete an evaluator and all of its stored versions.


        Associated evaluation-rule assignments are also removed. Scores already
        produced by the evaluator are preserved.
      operationId: evaluators_delete
      tags:
        - Evaluators
      parameters:
        - name: evaluatorId
          in: path
          description: Stable evaluator identifier returned by the evaluator endpoints.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeletedEvaluator'
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
        '429':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiError'
        '500':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiError'
      security: *ref_0
  /api/public/v2/evaluators/{evaluatorId}/versions:
    get:
      description: >-
        List an evaluator's version history in newest-first order.


        This endpoint is intended for history and audit use cases. Ordinary
        clients can use the flattened `version` and definition fields on the
        evaluator response.
      operationId: evaluators_listVersions
      tags:
        - Evaluators
      parameters:
        - name: evaluatorId
          in: path
          description: Stable evaluator identifier returned by the evaluator endpoints.
          required: true
          schema:
            type: string
        - name: limit
          in: query
          description: >-
            Maximum number of versions to return. Defaults to `50` and cannot
            exceed `100`.
          required: false
          schema:
            type: integer
            nullable: true
        - name: cursor
          in: query
          description: Opaque cursor returned by the previous page.
          required: false
          schema:
            type: string
            nullable: true
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EvaluatorVersionsPage'
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
        '429':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiError'
        '500':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiError'
      security: *ref_0
  /api/public/experiments:
    get:
      description: |-
        List experiments with cursor-based pagination. Results are ordered by
        latest experiment activity descending.
      operationId: experiments_list
      tags:
        - Experiments
      parameters:
        - name: fields
          in: query
          description: |-
            Comma-separated list of field groups to include. Available groups:
            `core`, `metadata`, `scores`. If omitted, `core` is returned.
          required: false
          schema:
            type: string
            nullable: true
        - name: limit
          in: query
          description: Number of experiments to return per page. Maximum 100, default 50.
          required: false
          schema:
            type: integer
            nullable: true
        - name: scoreLimit
          in: query
          description: >-
            Number of scores to return per experiment when `fields=scores` is
            requested. Maximum 50, default 50.
          required: false
          schema:
            type: integer
            nullable: true
        - name: cursor
          in: query
          description: Versioned base64url cursor from the previous response page.
          required: false
          schema:
            type: string
            nullable: true
        - name: fromStartTime
          in: query
          description: |-
            Required. Retrieve only experiments with events on or after this
            datetime. A lower bound is required so the query stays fast on
            large projects; pair it with an upper bound to select a specific
            window.
          required: true
          schema:
            type: string
            format: date-time
        - name: toStartTime
          in: query
          description: Retrieve only experiments before this datetime.
          required: false
          schema:
            type: string
            format: date-time
            nullable: true
        - name: id
          in: query
          description: Comma-separated list of experiment IDs.
          required: false
          schema:
            type: string
            nullable: true
        - name: name
          in: query
          description: Comma-separated list of experiment names.
          required: false
          schema:
            type: string
            nullable: true
        - name: datasetId
          in: query
          description: Comma-separated list of dataset IDs.
          required: false
          schema:
            type: string
            nullable: true
        - name: filter
          in: query
          description: |-
            JSON string containing an array of structured filter conditions.
            Supported columns are `id`, `name`, and `datasetId`.
          required: false
          schema:
            type: string
            nullable: true
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExperimentsResponse'
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
      security: *ref_0
  /api/public/experiment-items:
    get:
      description: |-
        List experiment items with cursor-based pagination. Use this endpoint
        to export experiment item inputs, outputs, expected outputs, metadata,
        and optionally item/trace scores. Results are ordered by time
        descending.
      operationId: experiments_listItems
      tags:
        - Experiments
      parameters:
        - name: fields
          in: query
          description: |-
            Comma-separated list of field groups to include. Available groups:
            `core`, `dataset`, `io`, `metadata`, `itemMetadata`,
            `experimentMetadata`, `scores`. If omitted, `core,dataset` is
            returned.
          required: false
          schema:
            type: string
            nullable: true
        - name: limit
          in: query
          description: >-
            Number of experiment items to return per page. Maximum 100, default
            50.
          required: false
          schema:
            type: integer
            nullable: true
        - name: scoreLimit
          in: query
          description: >-
            Number of scores to return per experiment item when `fields=scores`
            is requested. Maximum 50, default 50.
          required: false
          schema:
            type: integer
            nullable: true
        - name: cursor
          in: query
          description: Versioned base64url cursor from the previous response page.
          required: false
          schema:
            type: string
            nullable: true
        - name: fromStartTime
          in: query
          description: |-
            Required. Retrieve only experiment items started on or after this
            datetime. A lower bound is required so the query stays fast on
            large projects; pair it with an upper bound to select a specific
            window.
          required: true
          schema:
            type: string
            format: date-time
        - name: toStartTime
          in: query
          description: Retrieve only experiment items started before this datetime.
          required: false
          schema:
            type: string
            format: date-time
            nullable: true
        - name: experimentId
          in: query
          description: Comma-separated list of experiment IDs.
          required: false
          schema:
            type: string
            nullable: true
        - name: experimentName
          in: query
          description: Comma-separated list of experiment names.
          required: false
          schema:
            type: string
            nullable: true
        - name: experimentItemId
          in: query
          description: Comma-separated list of experiment item IDs.
          required: false
          schema:
            type: string
            nullable: true
        - name: datasetId
          in: query
          description: Comma-separated list of dataset IDs.
          required: false
          schema:
            type: string
            nullable: true
        - name: filter
          in: query
          description: |-
            JSON string containing an array of structured filter conditions.
            Supported columns are `experimentId`, `experimentName`,
            `experimentItemId`, and `datasetId`.
          required: false
          schema:
            type: string
            nullable: true
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExperimentItemsResponse'
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
      security: *ref_0
  /api/public/feedback:
    post:
      description: >-
        Submit explicit user-approved feedback about Langfuse skills, MCP tools,
        CLI, docs, or public API. Do not include secrets, credentials, customer
        data, trace payloads, or unrelated use-case details.


        Not available in the HIPAA cloud region.
      operationId: feedback_submit
      tags:
        - Feedback
      parameters: []
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubmitFeedbackResponse'
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
        '409':
          description: ''
      security: *ref_0
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SubmitFeedbackRequest'
  /api/public/health:
    get:
      description: Check health of API and database
      operationId: health_health
      tags:
        - Health
      parameters: []
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HealthResponse'
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
        '503':
          description: ''
  /api/public/llm-connections:
    get:
      description: Get all LLM connections in a project
      operationId: llmConnections_list
      tags:
        - LlmConnections
      parameters:
        - name: page
          in: query
          description: page number, starts at 1
          required: false
          schema:
            type: integer
            nullable: true
        - name: limit
          in: query
          description: limit of items per page
          required: false
          schema:
            type: integer
            nullable: true
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedLlmConnections'
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
      security: *ref_0
    put:
      description: >-
        Create or update an LLM connection. The connection is upserted on
        provider.
      operationId: llmConnections_upsert
      tags:
        - LlmConnections
      parameters: []
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LlmConnection'
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
      security: *ref_0
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpsertLlmConnectionRequest'
  /api/public/llm-connections/{id}:
    delete:
      description: >-
        Delete an LLM connection by id. Evaluators that depend on the deleted
        connection are automatically paused.
      operationId: llmConnections_delete
      tags:
        - LlmConnections
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteLlmConnectionResponse'
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
      security: *ref_0
  /api/public/organizations/llm-connections:
    get:
      description: >-
        Get all organization-level LLM connections. Requires an
        organization-scoped API key.
      operationId: llmConnections_listOrganization
      tags:
        - LlmConnections
      parameters:
        - name: page
          in: query
          description: page number, starts at 1
          required: false
          schema:
            type: integer
            nullable: true
        - name: limit
          in: query
          description: limit of items per page
          required: false
          schema:
            type: integer
            nullable: true
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedLlmConnections'
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
      security: *ref_0
    put:
      description: >-
        Create or update an organization-level LLM connection. The connection is
        upserted on provider and inherited by projects without a provider
        override. Requires an organization-scoped API key.
      operationId: llmConnections_upsertOrganization
      tags:
        - LlmConnections
      parameters: []
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LlmConnection'
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
      security: *ref_0
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpsertLlmConnectionRequest'
  /api/public/organizations/llm-connections/{id}:
    delete:
      description: >-
        Delete an organization-level LLM connection by id. Evaluators in
        projects without an override for the provider are automatically paused.
        Requires an organization-scoped API key.
      operationId: llmConnections_deleteOrganization
      tags:
        - LlmConnections
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteLlmConnectionResponse'
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
      security: *ref_0
  /api/public/media/{mediaId}:
    get:
      description: Get a media record
      operationId: media_get
      tags:
        - Media
      parameters:
        - name: mediaId
          in: path
          description: The unique langfuse identifier of a media record
          required: true
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetMediaResponse'
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
      security: *ref_0
    patch:
      description: Patch a media record
      operationId: media_patch
      tags:
        - Media
      parameters:
        - name: mediaId
          in: path
          description: The unique langfuse identifier of a media record
          required: true
          schema:
            type: string
      responses:
        '204':
          description: ''
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
      security: *ref_0
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatchMediaBody'
  /api/public/media:
    post:
      description: Get a presigned upload URL for a media record
      operationId: media_getUploadUrl
      tags:
        - Media
      parameters: []
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetMediaUploadUrlResponse'
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
      security: *ref_0
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GetMediaUploadUrlRequest'
  /api/public/v2/metrics:
    get:
      description: >-
        Get metrics from the Langfuse project using a query object. V2 endpoint
        with optimized performance.


        Together with OpenTelemetry ingestion and Observations API v2, this is
        the only real-time read path. Other public API endpoints can delay data
        by about 10 minutes.


        ## V2 Differences

        - Supports `observations`, `scores-numeric`, `scores-boolean`, and
        `scores-categorical` views only (traces view not supported)

        - Direct access to tags and release fields on observations

        - Semantic-root filtering and grouping through the v2-only
        `isRootObservation` dimension

        - Backwards-compatible: traceName, traceRelease, traceVersion dimensions
        are still available on observations view

        - High cardinality dimensions are not supported and will return a 400
        error (see below)


        For more details, see the [Metrics API
        documentation](https://langfuse.com/docs/metrics/features/metrics-api).


        ## Available Views


        ### observations

        Query observation-level data (spans, generations, events).


        **Dimensions:**

        - `environment` - Deployment environment (e.g., production, staging)

        - `type` - Type of observation (SPAN, GENERATION, EVENT)

        - `name` - Name of the observation

        - `level` - Logging level of the observation

        - `version` - Version of the observation

        - `tags` - User-defined tags

        - `release` - Release version

        - `traceName` - Name of the parent trace (backwards-compatible)

        - `traceRelease` - Release version of the parent trace
        (backwards-compatible, maps to release)

        - `traceVersion` - Version of the parent trace (backwards-compatible,
        maps to version)

        - `providedModelName` - Name of the model used

        - `promptName` - Name of the prompt used

        - `promptVersion` - Version of the prompt used

        - `isRootObservation` - Boolean semantic-root status. `true` includes
        physical roots and app roots whose SDK parent is external (so
        `parentObservationId` may be non-null).

        - `startTimeMonth` - Month of start_time in YYYY-MM format


        **Measures:**

        - `count` - Total number of observations

        - `latency` - Observation latency (milliseconds)

        - `streamingLatency` - Generation latency from completion start to end
        (milliseconds)

        - `inputTokens` - Sum of input tokens consumed

        - `outputTokens` - Sum of output tokens produced

        - `totalTokens` - Sum of all tokens consumed

        - `outputTokensPerSecond` - Output tokens per second

        - `tokensPerSecond` - Total tokens per second

        - `inputCost` - Input cost (USD)

        - `outputCost` - Output cost (USD)

        - `totalCost` - Total cost (USD)

        - `timeToFirstToken` - Time to first token (milliseconds)

        - `countScores` - Number of scores attached to the observation


        ### scores-numeric

        Query numeric and boolean score data.


        **Dimensions:**

        - `environment` - Deployment environment

        - `name` - Name of the score (e.g., accuracy, toxicity)

        - `source` - Origin of the score (API, ANNOTATION, EVAL)

        - `dataType` - Data type (NUMERIC, BOOLEAN)

        - `configId` - Identifier of the score config

        - `timestampMonth` - Month in YYYY-MM format

        - `timestampDay` - Day in YYYY-MM-DD format

        - `value` - Numeric value of the score

        - `traceName` - Name of the parent trace

        - `tags` - Tags

        - `traceRelease` - Release version

        - `traceVersion` - Version

        - `observationName` - Name of the associated observation

        - `observationModelName` - Model name of the associated observation

        - `observationPromptName` - Prompt name of the associated observation

        - `observationPromptVersion` - Prompt version of the associated
        observation


        **Measures:**

        - `count` - Total number of scores

        - `value` - Score value (for aggregations)


        ### scores-boolean

        Query boolean score data. It has the same score and parent
        trace/observation dimensions as scores-numeric, plus:


        **Dimensions:**

        - `booleanValue` - Boolean value for true/false grouping and filtering


        **Measures:**

        - `count` - Total number of boolean scores

        - `value` - Numeric 0/1 score value; `avg` returns the true-rate


        ### scores-categorical

        Query categorical score data. Same dimensions as scores-numeric except
        uses `stringValue` instead of `value`.


        **Measures:**

        - `count` - Total number of scores


        ## High Cardinality Dimensions

        The following dimensions cannot be used as grouping dimensions in v2
        metrics API as they can cause performance issues.

        Use them in filters instead.


        **observations view:**

        - `id` - Use traceId filter to narrow down results

        - `traceId` - Use traceId filter instead

        - `userId` - Use userId filter instead

        - `sessionId` - Use sessionId filter instead

        - `parentObservationId` - Use parentObservationId filter instead


        **scores-numeric / scores-boolean / scores-categorical views:**

        - `id` - Use specific filters to narrow down results

        - `traceId` - Use traceId filter instead

        - `userId` - Use userId filter instead

        - `sessionId` - Use sessionId filter instead

        - `observationId` - Use observationId filter instead


        ## Aggregations

        Available aggregation functions: `sum`, `avg`, `count`, `max`, `min`,
        `p50`, `p75`, `p90`, `p95`, `p99`, `histogram`


        ## Time Granularities

        Available granularities for timeDimension: `auto`, `minute`, `hour`,
        `day`, `week`, `month`

        - `auto` bins the data into approximately 50 buckets based on the time
        range
      operationId: metrics_metrics
      tags:
        - Metrics
      parameters:
        - name: query
          in: query
          description: >-
            JSON string containing the query parameters with the following
            structure:

            ```json

            {
              "view": string,           // Required. One of "observations", "scores-numeric", "scores-boolean", "scores-categorical"
              "dimensions": [           // Optional. Default: []
                {
                  "field": string       // Field to group by (see available dimensions above)
                }
              ],
              "metrics": [              // Required. At least one metric must be provided
                {
                  "measure": string,    // What to measure (see available measures above)
                  "aggregation": string // How to aggregate: "sum", "avg", "count", "max", "min", "p50", "p75", "p90", "p95", "p99", "histogram"
                }
              ],
              "filters": [              // Optional. Default: []
                {
                  "column": string,     // Column to filter on (any dimension field)
                  "operator": string,   // Operator based on type:
                                        // - datetime: ">", "<", ">=", "<="
                                        // - string: "=", "contains", "does not contain", "starts with", "ends with"
                                        // - stringOptions: "any of", "none of"
                                        // - arrayOptions: "any of", "none of", "all of"
                                        // - number: "=", ">", "<", ">=", "<="
                                        // - stringObject/numberObject: same as string/number with required "key"
                                        // - boolean: "=", "<>"
                                        // - null: "is null", "is not null"
                  "value": any,         // Value to compare against
                  "type": string,       // Data type: "datetime", "string", "number", "stringOptions", "categoryOptions", "arrayOptions", "stringObject", "numberObject", "boolean", "null"
                  "key": string         // Required only for stringObject/numberObject types (e.g., metadata filtering)
                }
              ],
              "timeDimension": {        // Optional. Default: null. If provided, results will be grouped by time
                "granularity": string   // One of "auto", "minute", "hour", "day", "week", "month"
              },
              "fromTimestamp": string,  // Required. ISO datetime string for start of time range
              "toTimestamp": string,    // Required. ISO datetime string for end of time range (must be after fromTimestamp)
              "orderBy": [              // Optional. Default: null
                {
                  "field": string,      // Field to order by (dimension or metric alias)
                  "direction": string   // "asc" or "desc"
                }
              ],
              "config": {               // Optional. Query-specific configuration
                "bins": number,         // Optional. Number of bins for histogram aggregation (1-100), default: 10
                "row_limit": number     // Optional. Maximum number of rows to return (1-1000), default: 100
              }
            }

            ```


            For example, to count semantic roots (including app roots with a
            non-null external parent), use a boolean filter:

            ```json

            {
              "view": "observations",
              "metrics": [{"measure": "count", "aggregation": "count"}],
              "filters": [{"column": "isRootObservation", "operator": "=", "value": true, "type": "boolean"}],
              "fromTimestamp": "2025-01-01T00:00:00.000Z",
              "toTimestamp": "2025-02-01T00:00:00.000Z"
            }

            ```
          required: true
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MetricsV2Response'
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
      security: *ref_0
  /api/public/models:
    post:
      description: Create a model
      operationId: models_create
      tags:
        - Models
      parameters: []
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Model'
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
      security: *ref_0
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateModelRequest'
    get:
      description: Get all models
      operationId: models_list
      tags:
        - Models
      parameters:
        - name: page
          in: query
          description: page number, starts at 1
          required: false
          schema:
            type: integer
            nullable: true
        - name: limit
          in: query
          description: limit of items per page
          required: false
          schema:
            type: integer
            nullable: true
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedModels'
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
      security: *ref_0
  /api/public/models/{id}:
    put:
      description: >-
        Create or replace a project-owned model using its id. Built-in models
        cannot be modified.
      operationId: models_upsert
      tags:
        - Models
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Model'
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
      security: *ref_0
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateModelRequest'
    get:
      description: Get a model
      operationId: models_get
      tags:
        - Models
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Model'
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
      security: *ref_0
    delete:
      description: >-
        Delete a model. Cannot delete models managed by Langfuse. You can create
        your own definition with the same modelName to override the definition
        though.
      operationId: models_delete
      tags:
        - Models
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '204':
          description: ''
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
      security: *ref_0
  /api/public/v2/observations:
    get:
      description: >-
        Get a list of observations with cursor-based pagination and flexible
        field selection.


        Together with OpenTelemetry ingestion and Metrics API v2, this is the
        only real-time read path. Other public API endpoints can delay data by
        about 10 minutes.


        ## Cursor-based Pagination

        This endpoint uses cursor-based pagination for efficient traversal of
        large datasets.

        The cursor is returned in the response metadata and should be passed in
        subsequent requests

        to retrieve the next page of results. The `limit` parameter is a
        maximum: a page may contain

        fewer items than the requested limit, including zero items, while
        `meta.cursor` is present.

        Continue requesting pages until `meta.cursor` is absent.

        Requests without a lower start-time bound may search only from January
        1, 2020.


        ## Field Selection

        Use the `fields` parameter to control which observation fields are
        returned:

        - `core` - Always included: id, traceId, startTime, endTime, projectId,
        parentObservationId, type

        - `basic` - name, level, statusMessage, version, environment,
        bookmarked, public, userId, sessionId, isRootObservation

        - `time` - completionStartTime, createdAt, updatedAt

        - `io` - input, output

        - `metadata` - metadata (truncated to 200 chars by default, use
        `expandMetadata` to get full values)

        - `model` - model, internalModelId, modelParameters

        - `usage` - usageDetails, costDetails, totalCost, usagePricingTierName

        - `prompt` - promptId, promptName, promptVersion

        - `metrics` - latency, timeToFirstToken

        - `trace_context` - tags, release, traceName


        If not specified, `core` and `basic` field groups are returned.


        ## Filters

        Multiple filtering options are available via query parameters or the
        structured `filter` parameter.

        When using the `filter` parameter, it takes precedence over individual
        query parameter filters.
      operationId: observations_getMany
      tags:
        - Observations
      parameters:
        - name: fields
          in: query
          description: >-
            Comma-separated list of field groups to include in the response.

            Available groups: core, basic, time, io, metadata, model, usage,
            prompt, metrics, trace_context.

            If not specified, `core` and `basic` field groups are returned.

            Example: "basic,usage,model"
          required: false
          schema:
            type: string
            nullable: true
        - name: expandMetadata
          in: query
          description: |-
            Comma-separated list of metadata keys to return non-truncated.
            By default, metadata values over 200 characters are truncated.
            Use this parameter to retrieve full values for specific keys.
            Example: "key1,key2"
          required: false
          schema:
            type: string
            nullable: true
        - name: limit
          in: query
          description: >-
            Maximum number of items to return per page. A page may contain fewer
            items, including zero items, while meta.cursor is present. Maximum
            1000, default 50.
          required: false
          schema:
            type: integer
            nullable: true
        - name: cursor
          in: query
          description: >-
            Base64-encoded cursor for pagination. Use the cursor from the
            previous response to get the next page.
          required: false
          schema:
            type: string
            nullable: true
        - name: parseIoAsJson
          in: query
          description: |-
            **Deprecated.** Setting this to `true` will return a 400 error.
            Input/output fields are always returned as raw strings.
            Remove this parameter or set it to `false`.
          required: false
          schema:
            type: boolean
            nullable: true
        - name: name
          in: query
          required: false
          schema:
            type: string
            nullable: true
        - name: userId
          in: query
          required: false
          schema:
            type: string
            nullable: true
        - name: sessionId
          in: query
          description: Filter by session ID.
          required: false
          schema:
            type: string
            nullable: true
        - name: type
          in: query
          description: >-
            Filter by observation type (e.g., "GENERATION", "SPAN", "EVENT",
            "AGENT", "TOOL", "CHAIN", "RETRIEVER", "EVALUATOR", "EMBEDDING",
            "GUARDRAIL")
          required: false
          schema:
            type: string
            nullable: true
        - name: traceId
          in: query
          required: false
          schema:
            type: string
            nullable: true
        - name: level
          in: query
          description: >-
            Optional filter for observations with a specific level (e.g.
            "DEBUG", "DEFAULT", "WARNING", "ERROR").
          required: false
          schema:
            $ref: '#/components/schemas/ObservationLevel'
            nullable: true
        - name: parentObservationId
          in: query
          description: >-
            Filter by the physical parent observation ID.

            An empty value matches only observations without a physical parent.
            Use `isRootObservation` to include observations marked as app roots
            by the SDK, which may retain a non-null `parentObservationId`.
          required: false
          schema:
            type: string
            nullable: true
        - name: isRootObservation
          in: query
          description: >-
            Filter by whether an observation is a logical root.

            Root observations include observations without a physical parent and
            observations marked as app roots by the SDK.

            An app-root observation may have `isRootObservation=true` and a
            non-null `parentObservationId`.
          required: false
          schema:
            type: boolean
            nullable: true
        - name: environment
          in: query
          description: >-
            Optional filter for observations where the environment is one of the
            provided values.
          required: false
          schema:
            type: array
            items:
              type: string
              nullable: true
        - name: fromStartTime
          in: query
          description: >-
            Retrieve only observations with a start_time on or after this
            datetime (ISO 8601).
          required: false
          schema:
            type: string
            format: date-time
            nullable: true
        - name: toStartTime
          in: query
          description: >-
            Retrieve only observations with a start_time before this datetime
            (ISO 8601).
          required: false
          schema:
            type: string
            format: date-time
            nullable: true
        - name: version
          in: query
          description: Optional filter to only include observations with a certain version.
          required: false
          schema:
            type: string
            nullable: true
        - name: filter
          in: query
          description: >-
            JSON string containing an array of filter conditions. When provided,
            this takes precedence over query parameter filters (userId, name,
            type, level, environment, fromStartTime, ...).


            ## Filter Structure

            Each filter condition has the following structure:

            ```json

            [
              {
                "type": string,           // Required. One of: "datetime", "string", "number", "stringOptions", "categoryOptions", "arrayOptions", "stringObject", "numberObject", "boolean", "null"
                "column": string,         // Required. Column to filter on (see available columns below)
                "operator": string,       // Required. Operator based on type:
                                          // - datetime: ">", "<", ">=", "<="
                                          // - string: "=", "contains", "does not contain", "starts with", "ends with", "matches"
                                          // - stringOptions: "any of", "none of"
                                          // - categoryOptions: "any of", "none of"
                                          // - arrayOptions: "any of", "none of", "all of"
                                          // - number: "=", ">", "<", ">=", "<="
                                          // - stringObject: "=", "contains", "does not contain", "starts with", "ends with", "matches", "is set", "is not set"
                                          // - numberObject: "=", ">", "<", ">=", "<="
                                          // - boolean: "=", "<>"
                                          // - null: "is null", "is not null"
                "value": any,             // Required (except for null type). Value to compare against. Type depends on filter type
                "key": string             // Required only for stringObject, numberObject, and categoryOptions types when filtering on nested fields like metadata
              }
            ]

            ```


            ## Available Columns


            ### Core Observation Fields

            - `id` (string) - Observation ID

            - `type` (string) - Observation type (SPAN, GENERATION, EVENT)

            - `name` (string) - Observation name

            - `traceId` (string) - Associated trace ID

            - `startTime` (datetime) - Observation start time

            - `endTime` (datetime) - Observation end time

            - `environment` (string) - Environment tag

            - `level` (string) - Log level (DEBUG, DEFAULT, WARNING, ERROR)

            - `statusMessage` (string) - Status message

            - `version` (string) - Version tag

            - `userId` (string) - User ID

            - `sessionId` (string) - Session ID

            - `isRootObservation` (boolean) - Whether the observation is a
            logical root. Observations marked as app roots by the SDK may retain
            a non-null parentObservationId.


            ### Trace-Related Fields

            - `traceName` (string) - Name of the parent trace

            - `traceTags` (arrayOptions) - Tags from the parent trace

            - `tags` (arrayOptions) - Alias for traceTags


            ### Performance Metrics

            - `latency` (number) - Latency in seconds (calculated: end_time -
            start_time)

            - `timeToFirstToken` (number) - Time to first token in seconds

            - `tokensPerSecond` (number) - Output tokens per second


            ### Token Usage

            - `inputTokens` (number) - Number of input tokens

            - `outputTokens` (number) - Number of output tokens

            - `totalTokens` (number) - Total tokens (alias: `tokens`)


            ### Cost Metrics

            - `inputCost` (number) - Input cost in USD

            - `outputCost` (number) - Output cost in USD

            - `totalCost` (number) - Total cost in USD


            ### Model Information

            - `model` (string) - Provided model name (alias:
            `providedModelName`)

            - `promptName` (string) - Associated prompt name

            - `promptVersion` (number) - Associated prompt version


            ### Structured Data

            - `input` (string) - Observation input. Supports accelerated indexed
            literal search with the `matches` operator.

            - `output` (string) - Observation output. Supports accelerated
            indexed literal search with the `matches` operator.

            - `metadata` (stringObject/numberObject/categoryOptions) - Metadata
            key-value pairs. Use `key` parameter to filter on specific metadata
            keys.


            The `matches` operator is only supported for `input`, `output`, and
            stringObject `metadata` filters. It performs indexed literal search
            with token-boundary pruning using the events table text indexes.
            Case sensitivity differs by target: `input` and `output` matches are
            case-insensitive, while metadata value matches are case-sensitive.
            Unlike SQL `LIKE`, `%` and `_` are treated as literal characters.
            Use `contains` for legacy substring semantics where the API allows
            it. Any v2 `input` or `output` filter must be accompanied by at
            least one `=` or `matches` filter on `input` or `output`; standalone
            `contains`, `starts with`, `ends with`, and `does not contain`
            filters on these columns are rejected.


            ## Filter Examples

            ```json

            [
              {
                "type": "string",
                "column": "type",
                "operator": "=",
                "value": "GENERATION"
              },
              {
                "type": "number",
                "column": "latency",
                "operator": ">=",
                "value": 2.5
              },
              {
                "type": "stringObject",
                "column": "metadata",
                "key": "environment",
                "operator": "=",
                "value": "production"
              },
              {
                "type": "string",
                "column": "output",
                "operator": "matches",
                "value": "needle"
              },
              {
                "type": "boolean",
                "column": "isRootObservation",
                "operator": "=",
                "value": true
              }
            ]

            ```
          required: false
          schema:
            type: string
            nullable: true
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ObservationsV2Response'
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
      security: *ref_0
  /api/public/otel/v1/traces:
    post:
      description: >-
        **OpenTelemetry Traces Ingestion Endpoint**


        This endpoint implements the OTLP/HTTP specification for trace
        ingestion, providing native OpenTelemetry integration for Langfuse
        Observability.


        Together with Observations API v2 and Metrics API v2, this is the only
        real-time write path. Other public API endpoints can delay data by about
        10 minutes. Direct exporters must send `x-langfuse-ingestion-version:
        4`; current Python and JS SDKs already do.


        **Supported Formats:**

        - Binary Protobuf: `Content-Type: application/x-protobuf`

        - JSON Protobuf: `Content-Type: application/json`

        - Supports gzip compression via `Content-Encoding: gzip` header


        **Specification Compliance:**

        - Conforms to [OTLP/HTTP Trace
        Export](https://opentelemetry.io/docs/specs/otlp/#otlphttp)

        - Implements `ExportTraceServiceRequest` message format


        **Documentation:**

        - Integration guide:
        https://langfuse.com/integrations/native/opentelemetry

        - Data model: https://langfuse.com/docs/observability/data-model
      operationId: opentelemetry_exportTraces
      tags:
        - Opentelemetry
      parameters: []
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OtelTraceResponse'
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
      security: *ref_0
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                resourceSpans:
                  type: array
                  items:
                    $ref: '#/components/schemas/OtelResourceSpan'
                  description: >-
                    Array of resource spans containing trace data as defined in
                    the OTLP specification
              required:
                - resourceSpans
  /api/public/organizations/memberships:
    get:
      description: >-
        Get all memberships for the organization associated with the API key
        (requires organization-scoped API key)
      operationId: organizations_getOrganizationMemberships
      tags:
        - Organizations
      parameters: []
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MembershipsResponse'
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
      security: *ref_0
    put:
      description: >-
        Create or update a membership for the organization associated with the
        API key (requires organization-scoped API key)
      operationId: organizations_updateOrganizationMembership
      tags:
        - Organizations
      parameters: []
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MembershipResponse'
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
      security: *ref_0
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MembershipRequest'
    delete:
      description: >-
        Delete a membership from the organization associated with the API key
        (requires organization-scoped API key)
      operationId: organizations_deleteOrganizationMembership
      tags:
        - Organizations
      parameters: []
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MembershipDeletionResponse'
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
      security: *ref_0
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeleteMembershipRequest'
  /api/public/projects/{projectId}/memberships:
    get:
      description: >-
        Get all memberships for a specific project (requires organization-scoped
        API key)
      operationId: organizations_getProjectMemberships
      tags:
        - Organizations
      parameters:
        - name: projectId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MembershipsResponse'
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
      security: *ref_0
    put:
      description: >-
        Create or update a membership for a specific project (requires
        organization-scoped API key). The user must already be a member of the
        organization.
      operationId: organizations_updateProjectMembership
      tags:
        - Organizations
      parameters:
        - name: projectId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MembershipResponse'
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
      security: *ref_0
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MembershipRequest'
    delete:
      description: >-
        Delete a membership from a specific project (requires
        organization-scoped API key). The user must be a member of the
        organization.
      operationId: organizations_deleteProjectMembership
      tags:
        - Organizations
      parameters:
        - name: projectId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MembershipDeletionResponse'
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
      security: *ref_0
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeleteMembershipRequest'
  /api/public/organizations/projects:
    get:
      description: >-
        Get all projects for the organization associated with the API key
        (requires organization-scoped API key)
      operationId: organizations_getOrganizationProjects
      tags:
        - Organizations
      parameters: []
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrganizationProjectsResponse'
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
      security: *ref_0
  /api/public/organizations/apiKeys:
    get:
      description: >-
        Get all API keys for the organization associated with the API key
        (requires organization-scoped API key)
      operationId: organizations_getOrganizationApiKeys
      tags:
        - Organizations
      parameters: []
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrganizationApiKeysResponse'
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
      security: *ref_0
  /api/public/projects:
    get:
      description: >-
        Get Project associated with API key (requires project-scoped API key).
        You can use GET /api/public/organizations/projects to get all projects
        with an organization-scoped key.
      operationId: projects_get
      tags:
        - Projects
      parameters: []
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Projects'
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
      security: *ref_0
    post:
      description: Create a new project (requires organization-scoped API key)
      operationId: projects_create
      tags:
        - Projects
      parameters: []
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Project'
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
      security: *ref_0
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                metadata:
                  type: object
                  additionalProperties: true
                  nullable: true
                  description: Optional metadata for the project
                retention:
                  type: integer
                  description: >-
                    Number of days to retain data. Must be 0 or at least 3 days.
                    Requires data-retention entitlement for non-zero values.
                    Optional.
              required:
                - name
                - retention
  /api/public/projects/{projectId}:
    put:
      description: Update a project by ID (requires organization-scoped API key).
      operationId: projects_update
      tags:
        - Projects
      parameters:
        - name: projectId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Project'
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
      security: *ref_0
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                metadata:
                  type: object
                  additionalProperties: true
                  nullable: true
                  description: Optional metadata for the project
                retention:
                  type: integer
                  nullable: true
                  description: |-
                    Number of days to retain data.
                    Must be 0 or at least 3 days.
                    Requires data-retention entitlement for non-zero values.
                    Optional. Will retain existing retention setting if omitted.
              required:
                - name
    delete:
      description: >-
        Delete a project by ID (requires organization-scoped API key). Project
        deletion is processed asynchronously. Deleting the AI Gateway ingestion
        project turns off the AI Gateway for the organization until another
        ingestion project is selected.
      operationId: projects_delete
      tags:
        - Projects
      parameters:
        - name: projectId
          in: path
          required: true
          schema:
            type: string
      responses:
        '202':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProjectDeletionResponse'
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
      security: *ref_0
  /api/public/projects/{projectId}/apiKeys:
    get:
      description: Get all API keys for a project (requires organization-scoped API key)
      operationId: projects_getApiKeys
      tags:
        - Projects
      parameters:
        - name: projectId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiKeyList'
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
      security: *ref_0
    post:
      description: >-
        Create a new API key for a project (requires organization-scoped API key)
      operationId: projects_createApiKey
      tags:
        - Projects
      parameters:
        - name: projectId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiKeyResponse'
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
      security: *ref_0
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  nullable: true
                  description: >-
                    Optional name for the API key. Cannot be provided together
                    with note, even if either value is an empty string.
                note:
                  type: string
                  nullable: true
                  description: >-
                    Deprecated alias for name. Cannot be provided together with
                    name, even if either value is an empty string.
                  deprecated: true
                expiresAt:
                  type: string
                  format: date-time
                  nullable: true
                  description: >-
                    Optional expiration timestamp in ISO 8601 format. Must be in
                    the future. Omit or set to null for a key that does not
                    expire.
                publicKey:
                  type: string
                  nullable: true
                  description: >-
                    Optional predefined public key. Must start with 'pk-lf-'. If
                    provided, secretKey must also be provided.
                secretKey:
                  type: string
                  nullable: true
                  description: >-
                    Optional predefined secret key. Must start with 'sk-lf-'. If
                    provided, publicKey must also be provided.
  /api/public/projects/{projectId}/apiKeys/{apiKeyId}:
    delete:
      description: Delete an API key for a project (requires organization-scoped API key)
      operationId: projects_deleteApiKey
      tags:
        - Projects
      parameters:
        - name: projectId
          in: path
          required: true
          schema:
            type: string
        - name: apiKeyId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiKeyDeletionResponse'
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
      security: *ref_0
  /api/public/v2/prompts/{name}/versions/{version}:
    patch:
      description: Update labels for a specific prompt version
      operationId: promptVersion_update
      tags:
        - PromptVersion
      parameters:
        - name: name
          in: path
          description: >-
            The name of the prompt. If the prompt is in a folder (e.g.,
            "folder/subfolder/prompt-name"), 

            the folder path must be URL encoded.
          required: true
          schema:
            type: string
        - name: version
          in: path
          description: Version of the prompt to update
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Prompt'
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
      security: *ref_0
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                newLabels:
                  type: array
                  items:
                    type: string
                  description: >-
                    New labels for the prompt version. Labels are unique across
                    versions. The "latest" label is reserved and managed by
                    Langfuse.
              required:
                - newLabels
  /api/public/v2/prompts/{promptName}:
    get:
      description: Get a prompt
      operationId: prompts_get
      tags:
        - Prompts
      parameters:
        - name: promptName
          in: path
          description: >-
            The name of the prompt. If the prompt is in a folder (e.g.,
            "folder/subfolder/prompt-name"), 

            the folder path must be URL encoded.
          required: true
          schema:
            type: string
        - name: version
          in: query
          description: Version of the prompt to be retrieved.
          required: false
          schema:
            type: integer
            nullable: true
        - name: label
          in: query
          description: >-
            Label of the prompt to be retrieved. Defaults to "production" if no
            label or version is set.
          required: false
          schema:
            type: string
            nullable: true
        - name: resolve
          in: query
          description: >-
            Resolve prompt dependencies before returning the prompt. Defaults to
            `true`. Set to `false` to return the raw stored prompt with
            dependency tags intact. This bypasses prompt caching and is intended
            for debugging or one-off jobs, not production runtime fetches.
          required: false
          schema:
            type: boolean
            nullable: true
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Prompt'
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
      security: *ref_0
    delete:
      description: >-
        Delete prompt versions. If neither version nor label is specified, all
        versions of the prompt are deleted.
      operationId: prompts_delete
      tags:
        - Prompts
      parameters:
        - name: promptName
          in: path
          description: The name of the prompt
          required: true
          schema:
            type: string
        - name: label
          in: query
          description: >-
            Optional label to filter deletion. If specified, deletes all prompt
            versions that have this label.
          required: false
          schema:
            type: string
            nullable: true
        - name: version
          in: query
          description: >-
            Optional version to filter deletion. If specified, deletes only this
            specific version of the prompt.
          required: false
          schema:
            type: integer
            nullable: true
      responses:
        '204':
          description: ''
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
      security: *ref_0
  /api/public/v2/prompts:
    get:
      description: Get a list of prompt names with versions and labels
      operationId: prompts_list
      tags:
        - Prompts
      parameters:
        - name: name
          in: query
          required: false
          schema:
            type: string
            nullable: true
        - name: label
          in: query
          required: false
          schema:
            type: string
            nullable: true
        - name: tag
          in: query
          required: false
          schema:
            type: string
            nullable: true
        - name: page
          in: query
          description: page number, starts at 1
          required: false
          schema:
            type: integer
            nullable: true
        - name: limit
          in: query
          description: limit of items per page
          required: false
          schema:
            type: integer
            nullable: true
        - name: fromUpdatedAt
          in: query
          description: >-
            Optional filter to only include prompt versions created/updated on
            or after a certain datetime (ISO 8601)
          required: false
          schema:
            type: string
            format: date-time
            nullable: true
        - name: toUpdatedAt
          in: query
          description: >-
            Optional filter to only include prompt versions created/updated
            before a certain datetime (ISO 8601)
          required: false
          schema:
            type: string
            format: date-time
            nullable: true
        - name: filter
          in: query
          description: >-
            JSON string containing an array of filter conditions, combined with
            AND.

            When provided, this takes precedence over name, version,

            label, tag, fromUpdatedAt, and toUpdatedAt. An empty array applies
            no

            filters. Project scoping and pagination always apply.


            Each condition requires `type`, `column`, `operator`, and `value`.

            Supported types and columns:

            - `string`: `id`, `name`, `type`. Operators: `=`, `contains`, `does
            not contain`, `starts with`, `ends with`, `is not empty`.

            - `stringOptions`: `id`, `name`, `type`. Operators: `any of`, `none
            of`. Value: non-empty string array.

            - `number`: `version`. Operators: `=`, `>`, `<`, `>=`, `<=`. Value:
            number.

            - `datetime`: `createdAt`, `updatedAt`. Operators: `>`, `<`, `>=`,
            `<=`. Value: ISO 8601 timestamp.

            - `arrayOptions`: `labels`, `tags`. Operators: `any of`, `all of`,
            `none of`. Value: non-empty string array.

            - `stringObject`: `config`. Requires an additional `key` field.
            Operators: `=`, `contains`, `does not contain`, `starts with`, `ends
            with`, `is set`, `is not set`. Value: string (use an empty string
            for key-presence operators).


            String equality is case-sensitive. String search operators use

            case-insensitive SQL pattern matching: `%` matches any sequence and

            `_` matches a single character. A backslash escapes these
            characters;

            JSON-escape the backslash in the filter value. Asterisks are
            literal.

            For config, an empty search value is treated as `is set`.


            Filters apply to prompt versions before aggregation: returned
            versions,

            labels, and lastConfig reflect only matching versions.


            Example: [{"type":"string","column":"name","operator":"starts
            with","value":"tools/"},{"type":"string","column":"name","operator":"ends
            with","value":"/description"}]
          required: false
          schema:
            type: string
            nullable: true
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PromptMetaListResponse'
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
      security: *ref_0
    post:
      description: Create a new version for the prompt with the given `name`
      operationId: prompts_create
      tags:
        - Prompts
      parameters: []
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Prompt'
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
      security: *ref_0
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreatePromptRequest'
  /api/public/scim/ServiceProviderConfig:
    get:
      description: >-
        Get SCIM Service Provider Configuration (requires organization-scoped
        API key)
      operationId: scim_getServiceProviderConfig
      tags:
        - Scim
      parameters: []
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceProviderConfig'
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
      security: *ref_0
  /api/public/scim/ResourceTypes:
    get:
      description: Get SCIM Resource Types (requires organization-scoped API key)
      operationId: scim_getResourceTypes
      tags:
        - Scim
      parameters: []
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceTypesResponse'
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
      security: *ref_0
  /api/public/scim/Schemas:
    get:
      description: Get SCIM Schemas (requires organization-scoped API key)
      operationId: scim_getSchemas
      tags:
        - Scim
      parameters: []
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SchemasResponse'
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
      security: *ref_0
  /api/public/scim/Users:
    get:
      description: List users in the organization (requires organization-scoped API key)
      operationId: scim_listUsers
      tags:
        - Scim
      parameters:
        - name: filter
          in: query
          description: Filter expression (e.g. userName eq "value")
          required: false
          schema:
            type: string
            nullable: true
        - name: startIndex
          in: query
          description: 1-based index of the first result to return (default 1)
          required: false
          schema:
            type: integer
            nullable: true
        - name: count
          in: query
          description: Maximum number of results to return (default 100)
          required: false
          schema:
            type: integer
            nullable: true
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScimUsersListResponse'
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
      security: *ref_0
    post:
      description: >-
        Create a new user in the organization (requires organization-scoped API
        key)
      operationId: scim_createUser
      tags:
        - Scim
      parameters: []
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScimUser'
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
      security: *ref_0
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                userName:
                  type: string
                  description: User's email address (required)
                name:
                  $ref: '#/components/schemas/ScimName'
                  description: User's name information
                emails:
                  type: array
                  items:
                    $ref: '#/components/schemas/ScimEmail'
                  nullable: true
                  description: User's email addresses
                active:
                  type: boolean
                  nullable: true
                  description: Whether the user is active
                password:
                  type: string
                  nullable: true
                  description: >-
                    Ignored. Accepted only for compatibility with identity
                    providers that always send a password on user creation (Okta
                    sends a placeholder value even when password sync is
                    disabled). No credential is created for the user;
                    provisioned users authenticate via SSO or set a password
                    themselves through the password reset flow.
                  deprecated: true
              required:
                - userName
                - name
  /api/public/scim/Users/{userId}:
    get:
      description: Get a specific user by ID (requires organization-scoped API key)
      operationId: scim_getUser
      tags:
        - Scim
      parameters:
        - name: userId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScimUser'
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
      security: *ref_0
    delete:
      description: >-
        Remove a user from the organization (requires organization-scoped API
        key). Note that this only removes the user from the organization but
        does not delete the user entity itself.
      operationId: scim_deleteUser
      tags:
        - Scim
      parameters:
        - name: userId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmptyResponse'
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
      security: *ref_0
  /api/public/score-configs:
    post:
      description: >-
        Create a score configuration (config). Score configs are used to define
        the structure of scores
      operationId: scoreConfigs_create
      tags:
        - ScoreConfigs
      parameters: []
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScoreConfig'
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
      security: *ref_0
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateScoreConfigRequest'
    get:
      description: Get all score configs
      operationId: scoreConfigs_get
      tags:
        - ScoreConfigs
      parameters:
        - name: page
          in: query
          description: Page number, starts at 1.
          required: false
          schema:
            type: integer
            nullable: true
        - name: limit
          in: query
          description: >-
            Limit of items per page. If you encounter api issues due to too
            large page sizes, try to reduce the limit
          required: false
          schema:
            type: integer
            nullable: true
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScoreConfigs'
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
      security: *ref_0
  /api/public/score-configs/{configId}:
    get:
      description: Get a score config
      operationId: scoreConfigs_get-by-id
      tags:
        - ScoreConfigs
      parameters:
        - name: configId
          in: path
          description: The unique langfuse identifier of a score config
          required: true
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScoreConfig'
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
      security: *ref_0
    patch:
      description: Update a score config
      operationId: scoreConfigs_update
      tags:
        - ScoreConfigs
      parameters:
        - name: configId
          in: path
          description: The unique langfuse identifier of a score config
          required: true
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScoreConfig'
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
      security: *ref_0
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateScoreConfigRequest'
  /api/public/scores:
    post:
      description: >-
        Create scores asynchronously from a list of scores. Returns 202 if all
        scores are accepted, or 207 with accepted/rejected counts and error
        messages. Do not automatically retry a 207 batch. The generated
        reference shows only 200; the endpoint returns 202 or 207.
      operationId: scores_create
      tags:
        - Scores
      parameters: []
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateScoresResponse'
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
      security: *ref_0
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateScoresRequest'
  /api/public/scores/{scoreId}:
    delete:
      description: Delete a score (supports both trace and session scores)
      operationId: scores_delete
      tags:
        - Scores
      parameters:
        - name: scoreId
          in: path
          description: The unique langfuse identifier of a score
          required: true
          schema:
            type: string
      responses:
        '204':
          description: ''
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
      security: *ref_0
  /api/public/v3/scores:
    get:
      description: |-
        Get a list of scores with a polymorphic `value` field (v3).

        The `value` field type depends on `dataType`:
        - `NUMERIC` → number
        - `BOOLEAN` → boolean
        - `CATEGORICAL`, `TEXT`, `CORRECTION` → string

        The response always includes the core fields: id, projectId, name,
        value, dataType, source, timestamp, environment, createdAt, updatedAt.

        Additional field groups can be requested via the `fields` parameter:
        - `details` — adds comment, configId, metadata
        - `subject` — adds the subject object describing the entity the score
          is attached to: kind (trace, observation, session, or experiment),
          id, and traceId for observation-level scores
        - `annotation` — adds authorUserId, queueId

        Unknown group names return HTTP 400.
      operationId: scores_getMany
      tags:
        - Scores
      parameters:
        - name: limit
          in: query
          description: >-
            Number of items per page. Maximum 100, default 50. Requests with a
            limit greater than 100 return HTTP 400.
          required: false
          schema:
            type: integer
            nullable: true
        - name: cursor
          in: query
          description: >-
            URL-safe base64 (base64url) cursor for pagination. Use the cursor
            from the previous response to get the next page. Absent on the final
            page.
          required: false
          schema:
            type: string
            nullable: true
        - name: fields
          in: query
          description: >-
            Comma-separated field groups to include in addition to the
            always-returned core fields. Allowed: details, subject, annotation —
            see the endpoint description for the fields each group adds. Unknown
            names return HTTP 400.
          required: false
          schema:
            type: string
            nullable: true
        - name: id
          in: query
          description: >-
            Comma-separated list of score IDs to filter by (OR within, AND
            across filters).
          required: false
          schema:
            type: string
            nullable: true
        - name: name
          in: query
          description: Comma-separated list of score names to filter by.
          required: false
          schema:
            type: string
            nullable: true
        - name: source
          in: query
          description: >-
            Comma-separated list of score sources to filter by (e.g. API,
            ANNOTATION, EVAL). Case-insensitive — `api` and `API` are
            equivalent.
          required: false
          schema:
            type: string
            nullable: true
        - name: dataType
          in: query
          description: >-
            Comma-separated list of data types to filter by (NUMERIC, BOOLEAN,
            CATEGORICAL, TEXT, CORRECTION). Case-insensitive — `numeric` and
            `NUMERIC` are equivalent. Must be a single value when used with
            value, valueMin, or valueMax; otherwise the request returns HTTP
            400. Must be NUMERIC when used with valueMin or valueMax.
          required: false
          schema:
            type: string
            nullable: true
        - name: environment
          in: query
          description: Comma-separated list of environments to filter by.
          required: false
          schema:
            type: string
            nullable: true
        - name: configId
          in: query
          description: Comma-separated list of score config IDs to filter by.
          required: false
          schema:
            type: string
            nullable: true
        - name: queueId
          in: query
          description: Comma-separated list of annotation queue IDs to filter by.
          required: false
          schema:
            type: string
            nullable: true
        - name: authorUserId
          in: query
          description: Comma-separated list of author user IDs to filter by.
          required: false
          schema:
            type: string
            nullable: true
        - name: value
          in: query
          description: >-
            Comma-separated list of exact values to filter by. Requires a single
            dataType from NUMERIC, BOOLEAN, or CATEGORICAL; any other dataType,
            multiple dataTypes, or omitting dataType returns HTTP 400. For
            BOOLEAN, each value must be "true" or "false"; for NUMERIC, each
            value must be a finite number. Otherwise the request returns HTTP
            400.
          required: false
          schema:
            type: string
            nullable: true
        - name: valueMin
          in: query
          description: >-
            Inclusive lower bound on the numeric value. Requires
            dataType=NUMERIC as a single value; otherwise the request returns
            HTTP 400.
          required: false
          schema:
            type: number
            format: double
            nullable: true
        - name: valueMax
          in: query
          description: >-
            Inclusive upper bound on the numeric value. Requires
            dataType=NUMERIC as a single value; otherwise the request returns
            HTTP 400.
          required: false
          schema:
            type: number
            format: double
            nullable: true
        - name: traceId
          in: query
          description: >-
            Comma-separated list of trace IDs to filter by. Mutually exclusive
            with sessionId, experimentId. May be combined with observationId to
            scope the observation lookup to a specific trace.
          required: false
          schema:
            type: string
            nullable: true
        - name: sessionId
          in: query
          description: >-
            Comma-separated list of session IDs to filter by. Mutually exclusive
            with traceId, observationId, experimentId.
          required: false
          schema:
            type: string
            nullable: true
        - name: observationId
          in: query
          description: >-
            Comma-separated list of observation IDs to filter by. Requires
            traceId to be specified, because observation IDs are scoped to a
            trace. Mutually exclusive with sessionId, experimentId. Returns HTTP
            400 when used without traceId.
          required: false
          schema:
            type: string
            nullable: true
        - name: experimentId
          in: query
          description: >-
            Comma-separated list of dataset run IDs (experiment IDs) to filter
            by. Mutually exclusive with traceId, sessionId, observationId.
          required: false
          schema:
            type: string
            nullable: true
        - name: fromTimestamp
          in: query
          description: Inclusive lower bound on the score timestamp.
          required: false
          schema:
            type: string
            format: date-time
            nullable: true
        - name: toTimestamp
          in: query
          description: Exclusive upper bound on the score timestamp.
          required: false
          schema:
            type: string
            format: date-time
            nullable: true
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetScoresV3Response'
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
      security: *ref_0
  /api/public/skills:
    get:
      description: >-
        List skills with metadata and timestamps from their latest version,
        shared tags, and the version assigned to production when present.
      operationId: skills_list
      tags:
        - Skills
      parameters:
        - name: name
          in: query
          description: Filter by exact skill name.
          required: false
          schema:
            type: string
            nullable: true
        - name: search
          in: query
          description: >-
            Case-insensitive search across skill names and latest-version
            descriptions.
          required: false
          schema:
            type: string
            nullable: true
        - name: tag
          in: query
          description: Filter by a shared skill tag.
          required: false
          schema:
            type: string
            nullable: true
        - name: page
          in: query
          required: false
          schema:
            type: integer
            nullable: true
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            nullable: true
        - name: fromUpdatedAt
          in: query
          description: >-
            Include skills whose latest version was updated at or after this
            timestamp.
          required: false
          schema:
            type: string
            format: date-time
            nullable: true
        - name: toUpdatedAt
          in: query
          description: >-
            Include skills whose latest version was updated before this
            timestamp.
          required: false
          schema:
            type: string
            format: date-time
            nullable: true
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SkillMetaListResponse'
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
      security: *ref_0
    post:
      description: Create skill version
      operationId: skills_createVersion
      tags:
        - Skills
      parameters: []
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SkillVersion'
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
      security: *ref_0
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateSkillVersionRequest'
  /api/public/skills/{skillName}:
    get:
      description: >-
        Resolve a skill's metadata and file manifest by version or label.
        Defaults to the production label. Set includeContent to return file
        contents inline, or use each file's sha256Hash with getFileContents.
      operationId: skills_get
      tags:
        - Skills
      parameters:
        - name: skillName
          in: path
          required: true
          schema:
            type: string
        - name: version
          in: query
          required: false
          schema:
            type: integer
            nullable: true
        - name: label
          in: query
          required: false
          schema:
            type: string
            nullable: true
        - name: includeContent
          in: query
          description: Include UTF-8 text content in each file. Defaults to false.
          required: false
          schema:
            type: boolean
            nullable: true
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SkillVersion'
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
      security: *ref_0
    patch:
      description: >-
        Replace the shared tags across all versions of a skill. An empty tags
        list clears all tags. Returns the latest skill version with the updated
        tags.
      operationId: skills_update
      tags:
        - Skills
      parameters:
        - name: skillName
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SkillVersion'
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
      security: *ref_0
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateSkillRequest'
  /api/public/skills/files/content:
    get:
      description: >-
        Read a batch of text contents by canonical base64-encoded SHA-256 hashes.
      operationId: skills_getFileContents
      tags:
        - Skills
      parameters:
        - name: sha256Hashes
          in: query
          description: >-
            Comma-separated list of one to 50 canonical base64-encoded SHA-256
            hashes from skill file manifests. URL-encode the value, including +,
            /, and = characters.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SkillFileContentsResponse'
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
      security: *ref_0
  /api/public/skills/{skillName}/versions/{skillVersion}:
    patch:
      description: >-
        Replace the labels on a skill version and atomically move them from
        other versions.
      operationId: skills_setLabels
      tags:
        - Skills
      parameters:
        - name: skillName
          in: path
          required: true
          schema:
            type: string
        - name: skillVersion
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SkillVersion'
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
      security: *ref_0
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateSkillLabelsRequest'
    delete:
      description: >-
        Delete one immutable skill version. Unreferenced blobs are retained for
        asynchronous cleanup.
      operationId: skills_deleteVersion
      tags:
        - Skills
      parameters:
        - name: skillName
          in: path
          required: true
          schema:
            type: string
        - name: skillVersion
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteSkillVersionResponse'
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
      security: *ref_0
  /api/public/traces/{traceId}:
    delete:
      description: Delete a specific trace
      operationId: trace_delete
      tags:
        - Trace
      parameters:
        - name: traceId
          in: path
          description: The unique langfuse identifier of the trace to delete
          required: true
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteTraceResponse'
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
      security: *ref_0
  /api/public/traces:
    delete:
      description: Delete multiple traces
      operationId: trace_deleteMultiple
      tags:
        - Trace
      parameters: []
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteTraceResponse'
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
      security: *ref_0
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                traceIds:
                  type: array
                  items:
                    type: string
                  description: List of trace IDs to delete
              required:
                - traceIds
  /api/public/unstable/dashboard-widgets:
    get:
      description: |-
        List dashboard widgets in the project, ordered by most recently
        updated first.

        Responses may include legacy `traces` widgets created before this
        API existed. New widgets cannot be created with `view: traces`.
      operationId: unstable_dashboardWidgets_list
      tags:
        - UnstableDashboardWidgets
      parameters:
        - name: page
          in: query
          description: 1-based page number. Defaults to `1`.
          required: false
          schema:
            type: integer
            nullable: true
        - name: limit
          in: query
          description: Maximum number of items per page. Defaults to `50`.
          required: false
          schema:
            type: integer
            nullable: true
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/unstableDashboardWidgetList'
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
        '429':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/unstablePublicApiError'
        '500':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/unstablePublicApiError'
      security: *ref_0
    post:
      description: >-
        Create a dashboard widget (a standalone chart definition you place on

        any dashboard).


        This endpoint creates the widget only; place it on a dashboard via

        `POST /dashboards/{dashboardId}/placements`.


        Supported views are `observations`, `scores-numeric`, `scores-boolean`,
        and `scores-categorical`.

        The legacy `traces` view is not supported by this unstable API.

        Widgets are created as v2 internally.


        `chartConfig` is optional and defaults to the plain config for

        `chartType`; when `chartConfig.type` is given it must match

        `chartType`.


        Unstable API note:

        - This surface may evolve while dashboard/widget APIs are being
        finalized.
      operationId: unstable_dashboardWidgets_create
      tags:
        - UnstableDashboardWidgets
      parameters: []
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/unstableDashboardWidget'
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
        '429':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/unstablePublicApiError'
        '500':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/unstablePublicApiError'
      security: *ref_0
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/unstableCreateDashboardWidgetRequest'
  /api/public/unstable/dashboard-widgets/{widgetId}:
    get:
      description: |-
        Get a dashboard widget by id.

        The response may use `view: traces` for legacy widgets.
      operationId: unstable_dashboardWidgets_get
      tags:
        - UnstableDashboardWidgets
      parameters:
        - name: widgetId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/unstableDashboardWidget'
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
        '429':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/unstablePublicApiError'
        '500':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/unstablePublicApiError'
      security: *ref_0
    patch:
      description: |-
        Update a dashboard widget.

        All fields are optional; at least one field is required.
        Changing `chartType` without sending `chartConfig` resets the config
        to the new chart type's defaults. When `chartConfig.type` is given
        it must match the widget's (possibly updated) `chartType`.

        `view` cannot be changed to the legacy `traces` value. Existing
        `traces` widgets may be updated on other fields.
      operationId: unstable_dashboardWidgets_update
      tags:
        - UnstableDashboardWidgets
      parameters:
        - name: widgetId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/unstableDashboardWidget'
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
        '429':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/unstablePublicApiError'
        '500':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/unstablePublicApiError'
      security: *ref_0
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/unstableUpdateDashboardWidgetRequest'
    delete:
      description: |-
        Delete a dashboard widget.

        The API returns `409` while the widget is still placed on a dashboard.
        Remove those placements first.
      operationId: unstable_dashboardWidgets_delete
      tags:
        - UnstableDashboardWidgets
      parameters:
        - name: widgetId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/unstableDeleteDashboardWidgetResponse'
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
        '409':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/unstablePublicApiError'
        '429':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/unstablePublicApiError'
        '500':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/unstablePublicApiError'
      security: *ref_0
  /api/public/unstable/dashboards:
    get:
      description: |-
        List dashboards in the project, ordered by most recently updated
        first.
      operationId: unstable_dashboards_list
      tags:
        - UnstableDashboards
      parameters:
        - name: page
          in: query
          description: 1-based page number. Defaults to `1`.
          required: false
          schema:
            type: integer
            nullable: true
        - name: limit
          in: query
          description: Maximum number of items per page. Defaults to `50`.
          required: false
          schema:
            type: integer
            nullable: true
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/unstableDashboardList'
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
        '429':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/unstablePublicApiError'
        '500':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/unstablePublicApiError'
      security: *ref_0
    post:
      description: Create a dashboard.
      operationId: unstable_dashboards_create
      tags:
        - UnstableDashboards
      parameters: []
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/unstableDashboard'
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
        '429':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/unstablePublicApiError'
        '500':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/unstablePublicApiError'
      security: *ref_0
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/unstableCreateDashboardRequest'
  /api/public/unstable/dashboards/{dashboardId}:
    get:
      description: Get a dashboard by id.
      operationId: unstable_dashboards_get
      tags:
        - UnstableDashboards
      parameters:
        - name: dashboardId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/unstableDashboard'
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
        '429':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/unstablePublicApiError'
        '500':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/unstablePublicApiError'
      security: *ref_0
    patch:
      description: Update a dashboard's name, description, definition, or filters.
      operationId: unstable_dashboards_update
      tags:
        - UnstableDashboards
      parameters:
        - name: dashboardId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/unstableDashboard'
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
        '429':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/unstablePublicApiError'
        '500':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/unstablePublicApiError'
      security: *ref_0
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/unstableUpdateDashboardRequest'
    delete:
      description: Delete a dashboard.
      operationId: unstable_dashboards_delete
      tags:
        - UnstableDashboards
      parameters:
        - name: dashboardId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/unstableDeleteDashboardResponse'
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
        '429':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/unstablePublicApiError'
        '500':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/unstablePublicApiError'
      security: *ref_0
  /api/public/unstable/dashboards/{dashboardId}/placements:
    post:
      description: |-
        Add a placement to a dashboard grid (see `DashboardPlacement` for
        grid semantics).

        `id` and the position fields are optional: when omitted, the
        placement gets a server-generated id and is appended below all
        existing tiles as a 6x6 tile. Returns the created placement.

        The referenced widget must exist in the same project or be a
        Langfuse-managed widget. The API returns `409` if a placement with
        the same `id` already exists on the dashboard.
      operationId: unstable_dashboards_addPlacement
      tags:
        - UnstableDashboards
      parameters:
        - name: dashboardId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/unstableDashboardPlacement'
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
        '409':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/unstablePublicApiError'
        '429':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/unstablePublicApiError'
        '500':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/unstablePublicApiError'
      security: *ref_0
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/unstableCreateDashboardPlacementRequest'
  /api/public/unstable/dashboards/{dashboardId}/placements/{placementId}:
    patch:
      description: |-
        Move or resize a placement. All fields are optional; at least one is
        required. Omitted fields keep their current value. The placement's
        content (widget/preset reference) and id cannot change — delete and
        re-add the placement to swap content. Returns the updated placement.
      operationId: unstable_dashboards_updatePlacement
      tags:
        - UnstableDashboards
      parameters:
        - name: dashboardId
          in: path
          required: true
          schema:
            type: string
        - name: placementId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/unstableDashboardPlacement'
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
        '429':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/unstablePublicApiError'
        '500':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/unstablePublicApiError'
      security: *ref_0
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/unstableUpdateDashboardPlacementRequest'
    delete:
      description: >-
        Remove a placement from a dashboard grid without deleting the referenced
        widget.
      operationId: unstable_dashboards_deletePlacement
      tags:
        - UnstableDashboards
      parameters:
        - name: dashboardId
          in: path
          required: true
          schema:
            type: string
        - name: placementId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/unstableDeleteDashboardPlacementResponse'
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
        '429':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/unstablePublicApiError'
        '500':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/unstablePublicApiError'
      security: *ref_0
  /api/public/unstable/topic-facets:
    get:
      description: |-
        Unstable: Topics is in closed beta. The shape may change without notice.

        List the project's Topics facets. Only active facets (attached to the
        project's Topics rule, or all facets if the project has no rule) are
        returned unless `filter` contains an `active` condition.

        `filter` is a JSON array of filter conditions combined with AND.
        String matching is case-insensitive. Columns: `id` (stringOptions),
        `name` (string, stringOptions), `description` (string), `isBuiltIn`
        (boolean), `active` (boolean).
      operationId: unstable_topics_listFacets
      tags:
        - UnstableTopics
      parameters:
        - name: filter
          in: query
          description: >-
            JSON array of filter conditions, for example
            `[{"type":"string","column":"name","operator":"contains","value":"issue"}]`.
          required: false
          schema:
            type: string
            nullable: true
        - name: page
          in: query
          description: 1-based page number. Defaults to `1`.
          required: false
          schema:
            type: integer
            nullable: true
        - name: limit
          in: query
          description: Maximum number of items per page. Defaults to `50`, at most `100`.
          required: false
          schema:
            type: integer
            nullable: true
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/unstableTopicFacetList'
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
        '429':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/unstablePublicApiError'
        '500':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/unstablePublicApiError'
      security: *ref_0
  /api/public/unstable/topic-facets/{facetId}:
    get:
      description: |-
        Unstable: Topics is in closed beta. The shape may change without notice.

        Get one Topics facet by id, including inactive facets.
      operationId: unstable_topics_getFacet
      tags:
        - UnstableTopics
      parameters:
        - name: facetId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/unstableTopicFacet'
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
        '429':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/unstablePublicApiError'
        '500':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/unstablePublicApiError'
      security: *ref_0
  /api/public/unstable/topics:
    get:
      description: |-
        Unstable: Topics is in closed beta. The shape may change without notice.

        List the topics of each active facet's current published map, with
        the number of traces currently assigned to each topic in the window.
        Retired topics are not listed. `facets` holds per-facet trace counts
        by topic status.

        The window applies to the trace start time. It defaults to the last
        7 days and can span at most 93 days.

        `filter` is a JSON array of filter conditions combined with AND.
        String matching is case-insensitive. Columns: `facetId`
        (stringOptions), `facetName` (string, stringOptions), `id`
        (stringOptions), `name` (string, stringOptions). Facet conditions also
        restrict `facets`.
      operationId: unstable_topics_list
      tags:
        - UnstableTopics
      parameters:
        - name: fromTimestamp
          in: query
          description: >-
            Start of the window (trace start time, inclusive). Defaults to 7
            days before `toTimestamp`.
          required: false
          schema:
            type: string
            format: date-time
            nullable: true
        - name: toTimestamp
          in: query
          description: End of the window (trace start time, exclusive). Defaults to now.
          required: false
          schema:
            type: string
            format: date-time
            nullable: true
        - name: filter
          in: query
          description: >-
            JSON array of filter conditions, for example
            `[{"type":"stringOptions","column":"facetName","operator":"any
            of","value":["Issues"]}]`.
          required: false
          schema:
            type: string
            nullable: true
        - name: orderBy
          in: query
          description: Defaults to `traceCount.desc`.
          required: false
          schema:
            $ref: '#/components/schemas/unstableTopicsOrderBy'
            nullable: true
        - name: page
          in: query
          description: 1-based page number. Defaults to `1`.
          required: false
          schema:
            type: integer
            nullable: true
        - name: limit
          in: query
          description: Maximum number of items per page. Defaults to `50`, at most `100`.
          required: false
          schema:
            type: integer
            nullable: true
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/unstableTopicList'
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
        '429':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/unstablePublicApiError'
        '500':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/unstablePublicApiError'
      security: *ref_0
  /api/public/unstable/topics/{topicId}:
    get:
      description: |-
        Unstable: Topics is in closed beta. The shape may change without notice.

        Get one topic by its stable id. Topics on the current map are always
        found. A retired topic is found while traces in the window are still
        assigned to it, with `inCurrentMap: false`.
      operationId: unstable_topics_get
      tags:
        - UnstableTopics
      parameters:
        - name: topicId
          in: path
          required: true
          schema:
            type: string
        - name: fromTimestamp
          in: query
          description: >-
            Start of the window used for `traceCount`. Defaults to 7 days before
            `toTimestamp`.
          required: false
          schema:
            type: string
            format: date-time
            nullable: true
        - name: toTimestamp
          in: query
          description: End of the window used for `traceCount`. Defaults to now.
          required: false
          schema:
            type: string
            format: date-time
            nullable: true
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/unstableTopicWithStatus'
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
        '429':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/unstablePublicApiError'
        '500':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/unstablePublicApiError'
      security: *ref_0
components:
  schemas:
    AnnotationQueueStatus:
      title: AnnotationQueueStatus
      type: string
      enum:
        - PENDING
        - COMPLETED
    AnnotationQueueObjectType:
      title: AnnotationQueueObjectType
      type: string
      enum:
        - TRACE
        - OBSERVATION
        - SESSION
    AnnotationQueue:
      title: AnnotationQueue
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        description:
          type: string
          nullable: true
        scoreConfigIds:
          type: array
          items:
            type: string
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
      required:
        - id
        - name
        - description
        - scoreConfigIds
        - createdAt
        - updatedAt
    AnnotationQueueItem:
      title: AnnotationQueueItem
      type: object
      properties:
        id:
          type: string
        queueId:
          type: string
        objectId:
          type: string
        objectType:
          $ref: '#/components/schemas/AnnotationQueueObjectType'
        status:
          $ref: '#/components/schemas/AnnotationQueueStatus'
        completedAt:
          type: string
          format: date-time
          nullable: true
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
      required:
        - id
        - queueId
        - objectId
        - objectType
        - status
        - createdAt
        - updatedAt
    PaginatedAnnotationQueues:
      title: PaginatedAnnotationQueues
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/AnnotationQueue'
        meta:
          $ref: '#/components/schemas/utilsMetaResponse'
      required:
        - data
        - meta
    PaginatedAnnotationQueueItems:
      title: PaginatedAnnotationQueueItems
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/AnnotationQueueItem'
        meta:
          $ref: '#/components/schemas/utilsMetaResponse'
      required:
        - data
        - meta
    CreateAnnotationQueueRequest:
      title: CreateAnnotationQueueRequest
      type: object
      properties:
        name:
          type: string
        description:
          type: string
          nullable: true
        scoreConfigIds:
          type: array
          items:
            type: string
      required:
        - name
        - scoreConfigIds
    CreateAnnotationQueueItemRequest:
      title: CreateAnnotationQueueItemRequest
      type: object
      properties:
        objectId:
          type: string
        objectType:
          $ref: '#/components/schemas/AnnotationQueueObjectType'
        status:
          $ref: '#/components/schemas/AnnotationQueueStatus'
          nullable: true
          description: Defaults to PENDING for new queue items
      required:
        - objectId
        - objectType
    UpdateAnnotationQueueItemRequest:
      title: UpdateAnnotationQueueItemRequest
      type: object
      properties:
        status:
          $ref: '#/components/schemas/AnnotationQueueStatus'
          nullable: true
    DeleteAnnotationQueueItemResponse:
      title: DeleteAnnotationQueueItemResponse
      type: object
      properties:
        success:
          type: boolean
        message:
          type: string
      required:
        - success
        - message
    AnnotationQueueAssignmentRequest:
      title: AnnotationQueueAssignmentRequest
      type: object
      properties:
        userId:
          type: string
      required:
        - userId
    DeleteAnnotationQueueAssignmentResponse:
      title: DeleteAnnotationQueueAssignmentResponse
      type: object
      properties:
        success:
          type: boolean
      required:
        - success
    CreateAnnotationQueueAssignmentResponse:
      title: CreateAnnotationQueueAssignmentResponse
      type: object
      properties:
        userId:
          type: string
        queueId:
          type: string
        projectId:
          type: string
      required:
        - userId
        - queueId
        - projectId
    BlobStorageIntegrationType:
      title: BlobStorageIntegrationType
      type: string
      enum:
        - S3
        - S3_COMPATIBLE
        - AZURE_BLOB_STORAGE
        - GOOGLE_CLOUD_STORAGE
    BlobStorageIntegrationFileType:
      title: BlobStorageIntegrationFileType
      type: string
      enum:
        - JSON
        - CSV
        - JSONL
        - PARQUET
      description: >-
        File format for exported data. `PARQUET` is a columnar binary format
        encoded and compressed by the storage engine; gzip compression does not
        apply to it. Note that the model-price columns (`input_price`,
        `output_price`, `total_price`) are not included in Parquet observation
        exports.
    BlobStorageIntegrationFileTypeResponse:
      title: BlobStorageIntegrationFileTypeResponse
      type: string
      enum:
        - JSON
        - CSV
        - JSONL
        - PARQUET
      description: File type reported for an existing integration.
    BlobStorageExportMode:
      title: BlobStorageExportMode
      type: string
      enum:
        - FULL_HISTORY
        - FROM_TODAY
        - FROM_CUSTOM_DATE
    BlobStorageExportFrequency:
      title: BlobStorageExportFrequency
      type: string
      enum:
        - every_20_minutes
        - hourly
        - daily
        - weekly
    BlobStorageExportSource:
      title: BlobStorageExportSource
      type: string
      enum:
        - LEGACY_TRACES_OBSERVATIONS
        - OBSERVATIONS_V2
        - LEGACY_TRACES_AND_ENRICHED_OBSERVATIONS
      description: >-
        What data the integration exports.

        - `LEGACY_TRACES_OBSERVATIONS`: traces, observations, and scores tables.
        Observation columns are controlled by `exportFieldGroups`; field groups
        without a counterpart in this data model (e.g. `trace_context`) are
        omitted.

        - `OBSERVATIONS_V2`: same data model as the
        `/api/public/v2/observations` endpoint, plus scores. Columns are
        controlled by `exportFieldGroups`.

        - `LEGACY_TRACES_AND_ENRICHED_OBSERVATIONS`: both sets. Observation
        columns of both portions are controlled by `exportFieldGroups`.


        **Note:** which sources a deployment accepts depends on how far it has
        moved to the v4 data model. `OBSERVATIONS_V2` and the
        enriched-observations portion of
        `LEGACY_TRACES_AND_ENRICHED_OBSERVATIONS` read the enriched observations
        table, so they require a deployment that already populates it.
        `LEGACY_TRACES_OBSERVATIONS` and the legacy portion of
        `LEGACY_TRACES_AND_ENRICHED_OBSERVATIONS` read the legacy traces and
        observations tables, so they require a deployment that still populates
        those. A deployment part-way through the migration populates both and
        accepts every source. Selecting a source the deployment cannot serve is
        rejected with `400`, rather than exporting an empty result. See
        https://langfuse.com/docs/v4.
    BlobStorageExportFieldGroup:
      title: BlobStorageExportFieldGroup
      type: string
      enum:
        - core
        - basic
        - time
        - io
        - metadata
        - model
        - usage
        - prompt
        - metrics
        - tools
        - trace_context
        - score_metadata
        - score_provenance
      description: >-
        Field group selecting which columns are included in the export. Applies
        to all export sources.

        - Observation groups (`core` through `trace_context`) select observation
        columns; groups without a counterpart in the legacy data model (e.g.
        `trace_context`) are omitted from the legacy observations export.

        - Score groups (`score_` prefix) add optional columns to the scores
        export. The core score columns (`id`, `timestamp`, `trace_id`, `name`,
        `value`, …) are always exported and are not a selectable group; score
        groups add columns on top of them. `score_metadata` adds the score
        `metadata` column. `score_provenance` adds the references to where a
        score came from: `author_user_id`, `config_id`, `queue_id`,
        `evaluator_id`, `evaluation_rule_id`, `execution_trace_id`. Score groups
        are never selected by default.
    CreateBlobStorageIntegrationRequest:
      title: CreateBlobStorageIntegrationRequest
      type: object
      properties:
        projectId:
          type: string
          description: ID of the project in which to configure the blob storage integration
        type:
          $ref: '#/components/schemas/BlobStorageIntegrationType'
        bucketName:
          type: string
          description: >-
            Name of the storage bucket. For AZURE_BLOB_STORAGE, must be a valid
            Azure container name (3-63 chars, lowercase letters, numbers, and
            hyphens only, must start and end with a letter or number, no
            consecutive hyphens). For GOOGLE_CLOUD_STORAGE with default
            credentials, the bucket must be listed in
            `LANGFUSE_BLOB_STORAGE_GCS_ALLOWED_BUCKETS`.
        endpoint:
          type: string
          nullable: true
          description: >-
            Custom endpoint URL (required for S3_COMPATIBLE type). Ignored for
            GOOGLE_CLOUD_STORAGE.
        region:
          type: string
          description: >-
            Storage region used by S3-compatible clients (AWS, GCS, Cloudflare
            R2, MinIO, Azure location IDs such as eastus, OCI). Leading and
            trailing whitespace is removed. The remaining value must be 1-63
            letters, numbers, or hyphens, and cannot start or end with a hyphen.
            Examples: us-east-1, europe-west1, eastus, auto. Not used by
            GOOGLE_CLOUD_STORAGE; pass auto.
        accessKeyId:
          type: string
          nullable: true
          description: Access key ID for authentication. Not used for GOOGLE_CLOUD_STORAGE.
        secretAccessKey:
          type: string
          nullable: true
          description: >-
            Secret access key for authentication (will be encrypted when
            stored). When omitted on update, the stored secret is kept, unless
            the type changes between GOOGLE_CLOUD_STORAGE and another type.


            For GOOGLE_CLOUD_STORAGE, a GCP service account JSON key. On
            self-hosted deployments, pass `__GCS_DEFAULT_CREDENTIALS__` instead
            to use the deployment's Application Default Credentials; the bucket
            must then be listed in `LANGFUSE_BLOB_STORAGE_GCS_ALLOWED_BUCKETS`.
            Default credentials are not available on Langfuse Cloud.
        prefix:
          type: string
          nullable: true
          description: >-
            Path prefix for exported files (must end with forward slash if
            provided)
        exportFrequency:
          $ref: '#/components/schemas/BlobStorageExportFrequency'
        enabled:
          type: boolean
          description: Whether the integration is active
        forcePathStyle:
          type: boolean
          description: Use path-style URLs for S3 requests
        fileType:
          $ref: '#/components/schemas/BlobStorageIntegrationFileType'
        exportMode:
          $ref: '#/components/schemas/BlobStorageExportMode'
        exportStartDate:
          type: string
          format: date-time
          nullable: true
          description: >-
            Custom start date for exports (required when exportMode is
            FROM_CUSTOM_DATE). Must not be in the future (27 h tolerance for
            timezone differences).
        compressed:
          type: boolean
          nullable: true
          description: >-
            Enable gzip compression for exported files (.csv.gz, .json.gz,
            .jsonl.gz). Defaults to true.
        exportSource:
          $ref: '#/components/schemas/BlobStorageExportSource'
          nullable: true
          description: >-
            Data to export. When omitted on update, the existing value is
            preserved. When omitted on create, the default is `OBSERVATIONS_V2`
            on Langfuse Cloud, and on self-hosted deployments
            `LEGACY_TRACES_OBSERVATIONS` — or `OBSERVATIONS_V2` where the
            deployment no longer populates the legacy tables. The default is
            never a source the deployment cannot serve. Required when
            `exportFieldGroups` is provided.


            **Cloud-only project deprecation gate (effective 2026-05-20):** For
            projects created on or after 2026-05-20 on Langfuse Cloud,
            `LEGACY_TRACES_OBSERVATIONS` and
            `LEGACY_TRACES_AND_ENRICHED_OBSERVATIONS` are rejected with HTTP
            400. Use `OBSERVATIONS_V2` for all new integrations. Self-hosted
            deployments are unaffected.


            **Cloud-only integration deprecation gate (effective 2026-06-22):**
            On Langfuse Cloud, legacy export sources are only accepted for blob
            storage integrations created before 2026-06-22, regardless of
            project age. Requests that would create a new integration with
            `LEGACY_TRACES_OBSERVATIONS` or
            `LEGACY_TRACES_AND_ENRICHED_OBSERVATIONS` are rejected with HTTP
            400. Use `OBSERVATIONS_V2` instead. Self-hosted deployments are
            unaffected.
        exportFieldGroups:
          type: array
          items:
            $ref: '#/components/schemas/BlobStorageExportFieldGroup'
          nullable: true
          description: >-
            Field groups to include in each exported observation and score row.
            Applies to all export sources; must include the observation `core`
            group if provided. Core score columns are always exported; score
            groups add columns on top. When omitted on create, all observation
            groups are selected and no score groups. When omitted on update, the
            existing value is preserved.


            `exportFieldGroups` requires `exportSource` to be provided in the
            same request.
      required:
        - projectId
        - type
        - bucketName
        - region
        - exportFrequency
        - enabled
        - forcePathStyle
        - fileType
        - exportMode
    BlobStorageIntegrationResponse:
      title: BlobStorageIntegrationResponse
      type: object
      properties:
        id:
          type: string
        projectId:
          type: string
        type:
          $ref: '#/components/schemas/BlobStorageIntegrationType'
        bucketName:
          type: string
        endpoint:
          type: string
          nullable: true
        region:
          type: string
        accessKeyId:
          type: string
          nullable: true
        prefix:
          type: string
        exportFrequency:
          $ref: '#/components/schemas/BlobStorageExportFrequency'
        enabled:
          type: boolean
        forcePathStyle:
          type: boolean
        fileType:
          $ref: '#/components/schemas/BlobStorageIntegrationFileTypeResponse'
        exportMode:
          $ref: '#/components/schemas/BlobStorageExportMode'
        exportStartDate:
          type: string
          format: date-time
          nullable: true
        compressed:
          type: boolean
        exportSource:
          $ref: '#/components/schemas/BlobStorageExportSource'
        exportFieldGroups:
          type: array
          items:
            $ref: '#/components/schemas/BlobStorageExportFieldGroup'
          nullable: true
          description: >-
            Field groups included in each exported observation and score row. An
            empty list is treated as all observation groups and no score groups
            during export. Core score columns are always exported.
        nextSyncAt:
          type: string
          format: date-time
          nullable: true
        lastSyncAt:
          type: string
          format: date-time
          nullable: true
        lastError:
          type: string
          nullable: true
        lastErrorAt:
          type: string
          format: date-time
          nullable: true
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
      required:
        - id
        - projectId
        - type
        - bucketName
        - endpoint
        - region
        - accessKeyId
        - prefix
        - exportFrequency
        - enabled
        - forcePathStyle
        - fileType
        - exportMode
        - exportStartDate
        - compressed
        - exportSource
        - exportFieldGroups
        - nextSyncAt
        - lastSyncAt
        - lastError
        - lastErrorAt
        - createdAt
        - updatedAt
    BlobStorageIntegrationsResponse:
      title: BlobStorageIntegrationsResponse
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/BlobStorageIntegrationResponse'
      required:
        - data
    BlobStorageSyncStatus:
      title: BlobStorageSyncStatus
      type: string
      enum:
        - idle
        - running
        - queued
        - up_to_date
        - disabled
        - error
      description: >-
        Sync status of the blob storage integration:

        - `disabled` — integration is not enabled

        - `error` — last export failed (see `lastError` for details)

        - `running` — an export job is currently being processed

        - `queued` — next export is overdue (`nextSyncAt` is in the past) and
        waiting to be picked up by the worker

        - `idle` — enabled but has never exported yet and no export is queued

        - `up_to_date` — all available data has been exported; next export is
        scheduled for the future


        **ETL usage**: poll this endpoint and check for `up_to_date` status.
        Compare `lastSyncAt` against your

        ETL bookmark to determine if new data is available. Note that exports
        run with a 20-minute lag buffer,

        so `lastSyncAt` will always be at least 20 minutes behind real-time.
    BlobStorageIntegrationStatusResponse:
      title: BlobStorageIntegrationStatusResponse
      type: object
      properties:
        id:
          type: string
        projectId:
          type: string
        syncStatus:
          $ref: '#/components/schemas/BlobStorageSyncStatus'
        enabled:
          type: boolean
        lastSyncAt:
          type: string
          format: date-time
          nullable: true
          description: >-
            End of the last successfully exported time window. Compare against
            your ETL bookmark to determine if new data is available. Null if the
            integration has never synced.
        nextSyncAt:
          type: string
          format: date-time
          nullable: true
          description: When the next export is scheduled. Null if no sync has occurred yet.
        lastError:
          type: string
          nullable: true
          description: >-
            Raw error message from the storage provider (S3/Azure/GCS) if the
            last export failed. Cleared on successful export.
        lastErrorAt:
          type: string
          format: date-time
          nullable: true
          description: When the last error occurred. Cleared on successful export.
      required:
        - id
        - projectId
        - syncStatus
        - enabled
        - lastSyncAt
        - nextSyncAt
        - lastError
        - lastErrorAt
    BlobStorageIntegrationDeletionResponse:
      title: BlobStorageIntegrationDeletionResponse
      type: object
      properties:
        message:
          type: string
      required:
        - message
    CreateCommentRequest:
      title: CreateCommentRequest
      type: object
      properties:
        projectId:
          type: string
          description: The id of the project to attach the comment to.
        objectType:
          type: string
          description: >-
            The type of the object to attach the comment to (trace, observation,
            session, prompt).
        objectId:
          type: string
          description: >-
            The id of the object to attach the comment to. If this does not
            reference a valid existing object, an error will be thrown.
        content:
          type: string
          description: >-
            The content of the comment. May include markdown. Currently limited
            to 5000 characters.
        authorUserId:
          type: string
          nullable: true
          description: >-
            The id of the user who created the comment. Must be a member of the
            organization that owns the project, otherwise an error will be
            thrown.
      required:
        - projectId
        - objectType
        - objectId
        - content
    CreateCommentResponse:
      title: CreateCommentResponse
      type: object
      properties:
        id:
          type: string
          description: The id of the created object in Langfuse
      required:
        - id
    GetCommentsResponse:
      title: GetCommentsResponse
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Comment'
        meta:
          $ref: '#/components/schemas/utilsMetaResponse'
      required:
        - data
        - meta
    Deprecation:
      title: Deprecation
      type: object
      description: >-
        Migration signal returned by deprecated endpoints. Optional fields are
        omitted when they have no value.
      properties:
        message:
          type: string
          description: >-
            Human- and agent-readable summary of the deprecation and its
            replacement.
        replacement:
          type: string
          nullable: true
          description: >-
            The replacement endpoint, e.g. "GET /api/public/v2/observations".
            Omitted when the endpoint is being removed without a direct
            replacement.
        docsUrl:
          type: string
          nullable: true
          description: Link to the migration documentation (markdown), when available.
        sunsetAt:
          type: string
          nullable: true
          description: >-
            ISO date after which the endpoint may stop working, when a removal
            date is committed.
      required:
        - message
    ObservationV2:
      title: ObservationV2
      type: object
      description: >-
        An observation from the v2 API with field-group-based selection.

        Core fields are always present. Other fields are included only when
        their field group is requested.
      properties:
        id:
          type: string
          description: The unique identifier of the observation
        traceId:
          type: string
          nullable: true
          description: The trace ID associated with the observation
        startTime:
          type: string
          format: date-time
          description: The start time of the observation
        endTime:
          type: string
          format: date-time
          nullable: true
          description: The end time of the observation
        projectId:
          type: string
          description: The project ID this observation belongs to
        parentObservationId:
          type: string
          nullable: true
          description: >-
            The physical parent observation ID, if present.

            Observations marked as app roots by the SDK may retain a non-null
            parent ID.
        type:
          type: string
          description: The type of the observation (e.g. GENERATION, SPAN, EVENT)
        isRootObservation:
          type: boolean
          nullable: true
          description: >-
            Whether this observation is a logical root.

            This is true for observations without a physical parent and
            observations marked as app roots by the SDK.
        name:
          type: string
          nullable: true
          description: The name of the observation
        level:
          $ref: '#/components/schemas/ObservationLevel'
          nullable: true
          description: The level of the observation
        statusMessage:
          type: string
          nullable: true
          description: The status message of the observation
        version:
          type: string
          nullable: true
          description: The version of the observation
        environment:
          type: string
          nullable: true
          description: The environment from which this observation originated
        bookmarked:
          type: boolean
          nullable: true
          description: Whether the observation is bookmarked
        public:
          type: boolean
          nullable: true
          description: Whether the observation is public
        userId:
          type: string
          nullable: true
          description: The user ID associated with the observation
        sessionId:
          type: string
          nullable: true
          description: The session ID associated with the observation
        completionStartTime:
          type: string
          format: date-time
          nullable: true
          description: The completion start time of the observation
        createdAt:
          type: string
          format: date-time
          nullable: true
          description: The creation timestamp of the observation
        updatedAt:
          type: string
          format: date-time
          nullable: true
          description: The last update timestamp of the observation
        input:
          nullable: true
          description: The input data of the observation
        output:
          nullable: true
          description: The output data of the observation
        metadata:
          type: object
          additionalProperties: true
          nullable: true
          description: Additional metadata of the observation
        model:
          type: string
          nullable: true
          description: The model name as provided by the user
        internalModelId:
          type: string
          nullable: true
          description: The internal model ID matched by Langfuse
        modelParameters:
          nullable: true
          description: The parameters of the model used for the observation
        usageDetails:
          type: object
          additionalProperties:
            type: integer
          nullable: true
          description: >-
            The usage details of the observation. Key is the usage metric name,
            value is the number of units consumed.
        costDetails:
          type: object
          additionalProperties:
            type: number
            format: double
          nullable: true
          description: >-
            The cost details of the observation. Key is the cost metric name,
            value is the cost in USD.
        totalCost:
          type: number
          format: double
          nullable: true
          description: The total cost of the observation in USD
        usagePricingTierName:
          type: string
          nullable: true
          description: >-
            The name of the pricing tier applied to this observation's usage
            costs
        promptId:
          type: string
          nullable: true
          description: The prompt ID associated with the observation
        promptName:
          type: string
          nullable: true
          description: The prompt name associated with the observation
        promptVersion:
          type: integer
          nullable: true
          description: The prompt version associated with the observation
        latency:
          type: number
          format: double
          nullable: true
          description: The latency in seconds
        timeToFirstToken:
          type: number
          format: double
          nullable: true
          description: The time to first token in seconds
        modelId:
          type: string
          nullable: true
          description: >-
            The matched model ID. Null when the `model` field group is not
            requested.
        inputPrice:
          type: string
          nullable: true
          description: >-
            The input token price (USD per unit) from the matched model,
            serialized as a decimal string (e.g. "0.0001"). Null when the
            `model` field group is not requested.
        outputPrice:
          type: string
          nullable: true
          description: >-
            The output token price (USD per unit) from the matched model,
            serialized as a decimal string (e.g. "0.0001"). Null when the
            `model` field group is not requested.
        totalPrice:
          type: string
          nullable: true
          description: >-
            The total token price (USD per unit) from the matched model,
            serialized as a decimal string (e.g. "0.0001"). Null when the
            `model` field group is not requested.
        traceName:
          type: string
          nullable: true
          description: The name of the parent trace
        tags:
          type: array
          items:
            type: string
          nullable: true
          description: Tags from the parent trace (denormalized onto the observation)
        release:
          type: string
          nullable: true
          description: The release version of the parent trace
      required:
        - id
        - traceId
        - startTime
        - endTime
        - projectId
        - parentObservationId
        - type
        - modelId
        - inputPrice
        - outputPrice
        - totalPrice
    Usage:
      title: Usage
      type: object
      description: >-
        (Deprecated. Use usageDetails and costDetails instead.) Standard
        interface for usage and cost
      properties:
        input:
          type: integer
          description: Number of input units (e.g. tokens)
        output:
          type: integer
          description: Number of output units (e.g. tokens)
        total:
          type: integer
          description: Defaults to input+output if not set
        unit:
          type: string
          nullable: true
          description: Unit of measurement
        inputCost:
          type: number
          format: double
          nullable: true
          description: USD input cost
        outputCost:
          type: number
          format: double
          nullable: true
          description: USD output cost
        totalCost:
          type: number
          format: double
          nullable: true
          description: USD total cost, defaults to input+output
      required:
        - input
        - output
        - total
        - unit
    ScoreConfig:
      title: ScoreConfig
      type: object
      description: Configuration for a score
      properties:
        id:
          type: string
        name:
          type: string
          description: Score config name. Maximum 80 characters.
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
        projectId:
          type: string
        dataType:
          $ref: '#/components/schemas/ScoreConfigDataType'
        isArchived:
          type: boolean
          description: Whether the score config is archived. Defaults to false
        minValue:
          type: number
          format: double
          nullable: true
          description: >-
            Sets minimum value for numerical scores. If not set, the minimum
            value defaults to -∞
        maxValue:
          type: number
          format: double
          nullable: true
          description: >-
            Sets maximum value for numerical scores. If not set, the maximum
            value defaults to +∞
        categories:
          type: array
          items:
            $ref: '#/components/schemas/ConfigCategory'
          nullable: true
          description: Configures custom categories for categorical scores
        description:
          type: string
          nullable: true
          description: Description of the score config
      required:
        - id
        - name
        - createdAt
        - updatedAt
        - projectId
        - dataType
        - isArchived
    ConfigCategory:
      title: ConfigCategory
      type: object
      properties:
        value:
          type: number
          format: double
        label:
          type: string
      required:
        - value
        - label
    BaseScore:
      title: BaseScore
      type: object
      properties:
        id:
          type: string
        traceId:
          type: string
          nullable: true
          description: The trace ID associated with the score
        sessionId:
          type: string
          nullable: true
          description: The session ID associated with the score
        observationId:
          type: string
          nullable: true
          description: The observation ID associated with the score
        datasetRunId:
          type: string
          nullable: true
          description: The dataset run ID associated with the score
        name:
          type: string
        source:
          $ref: '#/components/schemas/ScoreSource'
        timestamp:
          type: string
          format: date-time
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
        authorUserId:
          type: string
          nullable: true
          description: The user ID of the author
        comment:
          type: string
          nullable: true
          description: Comment on the score
        metadata:
          type: object
          additionalProperties: true
          nullable: true
          description: Metadata associated with the score
        configId:
          type: string
          nullable: true
          description: >-
            Reference a score config on a score. When set, config and score name
            must be equal and value must comply to optionally defined numerical
            range
        queueId:
          type: string
          nullable: true
          description: >-
            The annotation queue referenced by the score. Indicates if score was
            initially created while processing annotation queue.
        environment:
          type: string
          description: >-
            The environment from which this score originated. Can be any
            lowercase alphanumeric string with hyphens and underscores that does
            not start with 'langfuse'.
      required:
        - id
        - name
        - source
        - timestamp
        - createdAt
        - updatedAt
        - authorUserId
        - comment
        - configId
        - queueId
        - environment
    NumericScore:
      title: NumericScore
      type: object
      properties:
        value:
          type: number
          format: double
          description: The numeric value of the score
      required:
        - value
      allOf:
        - $ref: '#/components/schemas/BaseScore'
    BooleanScore:
      title: BooleanScore
      type: object
      properties:
        value:
          type: number
          format: double
          description: >-
            The numeric value of the score. Equals 1 for "True" and 0 for "False"
        stringValue:
          type: string
          description: >-
            The string representation of the score value. Is inferred from the
            numeric value and equals "True" or "False"
      required:
        - value
        - stringValue
      allOf:
        - $ref: '#/components/schemas/BaseScore'
    CategoricalScore:
      title: CategoricalScore
      type: object
      properties:
        value:
          type: number
          format: double
          description: >-
            Represents the numeric category mapping of the stringValue. If no
            config is linked, defaults to 0.
        stringValue:
          type: string
          description: >-
            The string representation of the score value. If no config is
            linked, can be any string. Otherwise, must map to a config category
      required:
        - value
        - stringValue
      allOf:
        - $ref: '#/components/schemas/BaseScore'
    CorrectionScore:
      title: CorrectionScore
      type: object
      properties:
        value:
          type: number
          format: double
          description: The numeric value of the score. Always 0 for correction scores.
        stringValue:
          type: string
          description: The string representation of the correction content
      required:
        - value
        - stringValue
      allOf:
        - $ref: '#/components/schemas/BaseScore'
    TextScore:
      title: TextScore
      type: object
      properties:
        stringValue:
          type: string
          description: The text content of the score (1-500 characters)
      required:
        - stringValue
      allOf:
        - $ref: '#/components/schemas/BaseScore'
    Score:
      title: Score
      oneOf:
        - type: object
          allOf:
            - type: object
              properties:
                dataType:
                  type: string
                  enum:
                    - NUMERIC
            - $ref: '#/components/schemas/NumericScore'
          required:
            - dataType
          title: NumericScore
        - type: object
          allOf:
            - type: object
              properties:
                dataType:
                  type: string
                  enum:
                    - CATEGORICAL
            - $ref: '#/components/schemas/CategoricalScore'
          required:
            - dataType
          title: CategoricalScore
        - type: object
          allOf:
            - type: object
              properties:
                dataType:
                  type: string
                  enum:
                    - BOOLEAN
            - $ref: '#/components/schemas/BooleanScore'
          required:
            - dataType
          title: BooleanScore
        - type: object
          allOf:
            - type: object
              properties:
                dataType:
                  type: string
                  enum:
                    - CORRECTION
            - $ref: '#/components/schemas/CorrectionScore'
          required:
            - dataType
          title: CorrectionScore
        - type: object
          allOf:
            - type: object
              properties:
                dataType:
                  type: string
                  enum:
                    - TEXT
            - $ref: '#/components/schemas/TextScore'
          required:
            - dataType
          title: TextScore
      properties:
        _deprecation:
          $ref: '#/components/schemas/Deprecation'
          nullable: true
    CreateScoreValue:
      title: CreateScoreValue
      oneOf:
        - type: number
          format: double
          title: DoubleNumber
        - type: string
          title: String
      description: >-
        The value of the score. Must be passed as string for categorical and
        text scores, and numeric for boolean and numeric scores
    Comment:
      title: Comment
      type: object
      properties:
        id:
          type: string
        projectId:
          type: string
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
        objectType:
          $ref: '#/components/schemas/CommentObjectType'
        objectId:
          type: string
        content:
          type: string
        authorUserId:
          type: string
          nullable: true
          description: The user ID of the comment author
      required:
        - id
        - projectId
        - createdAt
        - updatedAt
        - objectType
        - objectId
        - content
    Dataset:
      title: Dataset
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        description:
          type: string
          nullable: true
          description: Description of the dataset
        metadata:
          description: Metadata associated with the dataset
        inputSchema:
          type: object
          additionalProperties: true
          nullable: true
          description: JSON Schema for validating dataset item inputs
        expectedOutputSchema:
          type: object
          additionalProperties: true
          nullable: true
          description: JSON Schema for validating dataset item expected outputs
        projectId:
          type: string
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
      required:
        - id
        - name
        - description
        - metadata
        - inputSchema
        - expectedOutputSchema
        - projectId
        - createdAt
        - updatedAt
    DatasetItem:
      title: DatasetItem
      type: object
      properties:
        id:
          type: string
        status:
          $ref: '#/components/schemas/DatasetStatus'
        input:
          description: Input data for the dataset item
        expectedOutput:
          description: Expected output for the dataset item
        metadata:
          description: Metadata associated with the dataset item
        sourceTraceId:
          type: string
          nullable: true
          description: The trace ID that sourced this dataset item
        sourceObservationId:
          type: string
          nullable: true
          description: The observation ID that sourced this dataset item
        datasetId:
          type: string
        datasetName:
          type: string
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
        version:
          type: string
          format: date-time
          nullable: true
          description: >-
            When this version of the dataset item became current. Listing
            dataset items with a `version` at or after this timestamp returns
            this item version, until the item is changed again. Self-hosted
            deployments that set
            `LANGFUSE_DATASET_SERVICE_WRITE_TO_VERSIONED_IMPLEMENTATION=false`
            update items in place, so there it stays at the item's first write.
        mediaReferences:
          type: array
          items:
            $ref: '#/components/schemas/DatasetItemMediaReference'
          description: >-
            Resolved Langfuse media references found in input, expectedOutput,
            and metadata.
      required:
        - id
        - status
        - input
        - expectedOutput
        - metadata
        - sourceTraceId
        - sourceObservationId
        - datasetId
        - datasetName
        - createdAt
        - updatedAt
        - mediaReferences
    DatasetItemMediaReference:
      title: DatasetItemMediaReference
      type: object
      properties:
        field:
          $ref: '#/components/schemas/DatasetItemMediaReferenceField'
          description: The dataset item field containing the reference
        referenceString:
          type: string
          description: >-
            The Langfuse media reference string, e.g.
            `@@@langfuseMedia:type=image/png|id=...|source=bytes@@@`
        jsonPath:
          type: string
          description: >-
            JSONPath of the string holding the reference within the field, e.g.
            `$['image']`
        media:
          $ref: '#/components/schemas/DatasetItemMediaReferenceMedia'
          description: The resolved media record.
      required:
        - field
        - referenceString
        - jsonPath
        - media
    DatasetItemMediaReferenceField:
      title: DatasetItemMediaReferenceField
      type: string
      enum:
        - input
        - expectedOutput
        - metadata
    DatasetItemMediaReferenceMedia:
      title: DatasetItemMediaReferenceMedia
      type: object
      properties:
        mediaId:
          type: string
          description: The unique langfuse identifier of the media record
        contentType:
          type: string
          description: The MIME type of the media record
        contentLength:
          type: integer
          description: The size of the media record in bytes
        url:
          type: string
          description: The signed download URL of the media record
        urlExpiry:
          type: string
          description: The expiry date and time of the download URL
      required:
        - mediaId
        - contentType
        - contentLength
        - url
        - urlExpiry
    Model:
      title: Model
      type: object
      description: >-
        Model definition used for transforming usage into USD cost and/or
        tokenization.


        Models can have either simple flat pricing or tiered pricing:

        - Flat pricing: Single price per usage type (legacy, but still
        supported)

        - Tiered pricing: Multiple pricing tiers with conditional matching based
        on usage patterns or observation attributes


        The pricing tiers approach is recommended for models with usage-based
        pricing variations.

        When using tiered pricing, the flat price fields (inputPrice,
        outputPrice, prices) are populated

        from the default tier for backward compatibility.
      properties:
        id:
          type: string
        modelName:
          type: string
          description: >-
            Name of the model definition. If multiple with the same name exist,
            they are applied in the following order: (1) custom over built-in,
            (2) newest according to startTime where
            model.startTime<observation.startTime
        matchPattern:
          type: string
          description: >-
            Regex pattern which matches this model definition to
            generation.model. Useful in case of fine-tuned models. If you want
            to exact match, use `(?i)^modelname$`
        startDate:
          type: string
          format: date-time
          nullable: true
          description: Apply only to generations which are newer than this ISO date.
        unit:
          $ref: '#/components/schemas/ModelUsageUnit'
          nullable: true
          description: Unit used by this model.
        inputPrice:
          type: number
          format: double
          nullable: true
          description: Deprecated. See 'prices' instead. Price (USD) per input unit
        outputPrice:
          type: number
          format: double
          nullable: true
          description: Deprecated. See 'prices' instead. Price (USD) per output unit
        totalPrice:
          type: number
          format: double
          nullable: true
          description: >-
            Deprecated. See 'prices' instead. Price (USD) per total unit. Cannot
            be set if input or output price is set.
        tokenizerId:
          type: string
          nullable: true
          description: >-
            Optional. Tokenizer to be applied to observations which match to
            this model. See docs for more details.
        tokenizerConfig:
          description: >-
            Optional. Configuration for the selected tokenizer. Needs to be
            JSON. See docs for more details.
        isLangfuseManaged:
          type: boolean
        createdAt:
          type: string
          format: date-time
          description: Timestamp when the model was created
        prices:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/ModelPrice'
          description: >-
            Deprecated. Use 'pricingTiers' instead for models with usage-based
            pricing variations.


            This field shows prices by usage type from the default pricing tier.
            Maintained for backward compatibility.

            If the model uses tiered pricing, this field will be populated from
            the default tier's prices.
        pricingTiers:
          type: array
          items:
            $ref: '#/components/schemas/PricingTier'
          description: >-
            Array of pricing tiers with conditional pricing based on usage
            thresholds or observation attributes.


            Pricing tiers enable accurate cost tracking for models that charge
            different rates based on usage patterns

            or request attributes (e.g., high-volume usage, large context
            windows, cached tokens, or service tiers).


            Each model must have exactly one default tier (isDefault=true,
            priority=0) that serves as a fallback.

            Additional conditional tiers can be defined with specific matching
            criteria.


            If this array is empty, the model uses legacy flat pricing from the
            inputPrice/outputPrice/totalPrice fields.
      required:
        - id
        - modelName
        - matchPattern
        - startDate
        - inputPrice
        - outputPrice
        - totalPrice
        - tokenizerId
        - tokenizerConfig
        - isLangfuseManaged
        - createdAt
        - prices
        - pricingTiers
    ModelPrice:
      title: ModelPrice
      type: object
      properties:
        price:
          type: number
          format: double
      required:
        - price
    PricingTierCondition:
      title: PricingTierCondition
      oneOf:
        - $ref: '#/components/schemas/PricingTierUsageCondition'
        - $ref: '#/components/schemas/PricingTierAttributeCondition'
      description: >-
        Condition for matching a pricing tier against usage details or
        observation attributes.


        Usage-detail conditions treat usageDetailPattern as a regex, sum all
        matching usage values, and compare the sum to the numeric value.
        Model-parameter and metadata conditions match an exact top-level key
        against one or more string values.
    PricingTierUsageCondition:
      title: PricingTierUsageCondition
      type: object
      description: Condition that sums usage details whose keys match a regex.
      properties:
        usageDetailPattern:
          type: string
          description: Regex pattern matched against usage detail keys.
        operator:
          $ref: '#/components/schemas/PricingTierOperator'
        value:
          type: number
          format: double
          description: Numeric threshold for the summed matching usage values.
        caseSensitive:
          type: boolean
          description: Whether the usage-detail regex is case-sensitive.
      required:
        - usageDetailPattern
        - operator
        - value
        - caseSensitive
    PricingTierAttributeCondition:
      title: PricingTierAttributeCondition
      type: object
      description: >-
        Condition that matches any configured value for a top-level observation
        attribute.
      properties:
        source:
          $ref: '#/components/schemas/PricingTierAttributeSource'
          description: Observation attribute object evaluated by this condition.
        key:
          type: string
          description: Exact top-level attribute key.
        operator:
          type: string
          const: in
          description: Membership operator.
        values:
          type: array
          items:
            type: string
          description: Accepted string attribute values. At least one value is required.
      required:
        - source
        - key
        - operator
        - values
    PricingTierAttributeSource:
      title: PricingTierAttributeSource
      type: string
      enum:
        - model_parameters
        - metadata
    PricingTierConditionInput:
      title: PricingTierConditionInput
      oneOf:
        - $ref: '#/components/schemas/PricingTierUsageConditionInput'
        - $ref: '#/components/schemas/PricingTierAttributeCondition'
      description: Condition input for matching a pricing tier.
    PricingTierUsageConditionInput:
      title: PricingTierUsageConditionInput
      type: object
      description: Input condition that sums usage details whose keys match a regex.
      properties:
        usageDetailPattern:
          type: string
          description: Regex pattern matched against usage detail keys.
        operator:
          $ref: '#/components/schemas/PricingTierOperator'
        value:
          type: number
          format: double
          description: Numeric threshold for the summed matching usage values.
        caseSensitive:
          type: boolean
          nullable: true
          description: Whether the usage-detail regex is case-sensitive. Defaults to false.
      required:
        - usageDetailPattern
        - operator
        - value
    PricingTier:
      title: PricingTier
      type: object
      description: >-
        Pricing tier definition with conditional pricing based on usage
        thresholds or observation attributes.


        Pricing tiers enable accurate cost tracking for LLM providers that
        charge different rates based on usage patterns or request attributes.

        For example, some providers charge higher rates when context size
        exceeds certain thresholds or when an accelerated service tier is
        selected.


        How tier matching works:

        1. Tiers are evaluated in ascending priority order (priority 1 before
        priority 2, etc.)

        2. The first tier where ALL conditions match is selected

        3. If no conditional tiers match, the default tier is used as a fallback

        4. The default tier has priority 0 and no conditions


        Why priorities matter:

        - Lower priority numbers are evaluated first, allowing you to define
        specific cases before general ones

        - Example: Priority 1 for "high usage" (>200K tokens), Priority 2 for
        "medium usage" (>100K tokens), Priority 0 for default

        - Without proper ordering, a less specific condition might match before
        a more specific one


        Every model must have exactly one default tier to ensure cost
        calculation always succeeds.
      properties:
        id:
          type: string
          description: Unique identifier for the pricing tier
        name:
          type: string
          description: >-
            Name of the pricing tier for display and identification purposes.


            Examples: "Standard", "High Volume Tier", "Large Context", "Extended
            Context Tier"
        isDefault:
          type: boolean
          description: >-
            Whether this is the default tier. Every model must have exactly one
            default tier with priority 0 and no conditions.


            The default tier serves as a fallback when no conditional tiers
            match, ensuring cost calculation always succeeds.

            It typically represents the base pricing for standard usage
            patterns.
        priority:
          type: integer
          description: >-
            Priority for tier matching evaluation. Lower numbers = higher
            priority (evaluated first).


            The default tier must always have priority 0. Conditional tiers
            should have priority 1, 2, 3, etc.


            Example ordering:

            - Priority 0: Default tier (no conditions, always matches as
            fallback)

            - Priority 1: High usage tier (e.g., >200K tokens)

            - Priority 2: Medium usage tier (e.g., >100K tokens)


            This ensures more specific conditions are checked before general
            ones.
        conditions:
          type: array
          items:
            $ref: '#/components/schemas/PricingTierCondition'
          description: >-
            Array of conditions that must ALL be met for this tier to match (AND
            logic).


            The default tier must have an empty conditions array. Conditional
            tiers should have one or more conditions

            that define when this tier's pricing applies.


            Multiple conditions enable complex matching scenarios (e.g., "high
            input tokens AND low output tokens").
        prices:
          type: object
          additionalProperties:
            type: number
            format: double
          description: >-
            Prices (USD) by usage type for this tier.


            Common usage types: "input", "output", "total", "request", "image"

            Prices are specified in USD per unit (e.g., per token, per request,
            per second).


            Example: {"input": 0.000003, "output": 0.000015} means $3 per
            million input tokens and $15 per million output tokens.
      required:
        - id
        - name
        - isDefault
        - priority
        - conditions
        - prices
    PricingTierInput:
      title: PricingTierInput
      type: object
      description: >-
        Input schema for creating a pricing tier. The tier ID will be
        automatically generated server-side.


        When creating a model with pricing tiers:

        - Exactly one tier must have isDefault=true (the fallback tier)

        - The default tier must have priority=0 and conditions=[]

        - All tier names and priorities must be unique within the model

        - Each tier must define at least one price


        See PricingTier for detailed information about how tiers work and why
        they're useful.
      properties:
        name:
          type: string
          description: >-
            Name of the pricing tier for display and identification purposes.


            Must be unique within the model. Common patterns: "Standard", "High
            Volume Tier", "Extended Context"
        isDefault:
          type: boolean
          nullable: true
          description: >-
            Whether this is the default tier. Exactly one tier per model must be
            marked as default.


            Requirements for default tier:

            - Must have isDefault=true

            - Must have priority=0

            - Must have empty conditions array (conditions=[])


            The default tier acts as a fallback when no conditional tiers match.
            Defaults to false when omitted.
        priority:
          type: integer
          description: >-
            Priority for tier matching evaluation. Lower numbers = higher
            priority (evaluated first).


            Must be unique within the model. The default tier must have
            priority=0.

            Conditional tiers should use priority 1, 2, 3, etc. based on their
            specificity.
        conditions:
          type: array
          items:
            $ref: '#/components/schemas/PricingTierConditionInput'
          description: >-
            Array of conditions that must ALL be met for this tier to match (AND
            logic).


            The default tier must have an empty array (conditions=[]).

            Conditional tiers should define one or more conditions that specify
            when this tier's pricing applies.


            Conditions can compare summed matching usage details to a numeric
            threshold, or exactly match a top-level model parameter or metadata
            value.
        prices:
          type: object
          additionalProperties:
            type: number
            format: double
          description: >-
            Prices (USD) by usage type for this tier. At least one price must be
            defined.


            Common usage types: "input", "output", "total", "request", "image"

            Prices are in USD per unit (e.g., per token).


            Example: {"input": 0.000003, "output": 0.000015} represents $3 per
            million input tokens and $15 per million output tokens.
      required:
        - name
        - priority
        - conditions
        - prices
    PricingTierOperator:
      title: PricingTierOperator
      type: string
      enum:
        - gt
        - gte
        - lt
        - lte
        - eq
        - neq
      description: Comparison operators for pricing tier conditions
    ModelUsageUnit:
      title: ModelUsageUnit
      type: string
      enum:
        - CHARACTERS
        - TOKENS
        - MILLISECONDS
        - SECONDS
        - IMAGES
        - REQUESTS
      description: Unit of usage in Langfuse
    ObservationLevel:
      title: ObservationLevel
      type: string
      enum:
        - DEBUG
        - DEFAULT
        - WARNING
        - ERROR
    MapValue:
      title: MapValue
      oneOf:
        - type: string
          nullable: true
          title: String
        - type: integer
          nullable: true
          title: Integer
        - type: number
          format: float
          nullable: true
          title: FloatNumber
        - type: boolean
          nullable: true
          title: Boolean
        - type: array
          items:
            type: string
          nullable: true
          title: Array
    CommentObjectType:
      title: CommentObjectType
      type: string
      enum:
        - TRACE
        - OBSERVATION
        - SESSION
        - PROMPT
    DatasetStatus:
      title: DatasetStatus
      type: string
      enum:
        - ACTIVE
        - ARCHIVED
    ScoreSource:
      title: ScoreSource
      type: string
      enum:
        - ANNOTATION
        - API
        - EVAL
    ScoreConfigDataType:
      title: ScoreConfigDataType
      type: string
      enum:
        - NUMERIC
        - BOOLEAN
        - CATEGORICAL
        - TEXT
    ScoreDataType:
      title: ScoreDataType
      type: string
      enum:
        - NUMERIC
        - BOOLEAN
        - CATEGORICAL
        - CORRECTION
        - TEXT
    OpenAIUsage:
      title: OpenAIUsage
      type: object
      description: Usage interface of OpenAI for improved compatibility.
      properties:
        promptTokens:
          type: integer
          nullable: true
        completionTokens:
          type: integer
          nullable: true
        totalTokens:
          type: integer
          nullable: true
    DeleteDatasetItemResponse:
      title: DeleteDatasetItemResponse
      type: object
      properties:
        message:
          type: string
          description: Success message after deletion
      required:
        - message
    CreateDatasetItemRequest:
      title: CreateDatasetItemRequest
      type: object
      properties:
        datasetName:
          type: string
        input:
          nullable: true
        expectedOutput:
          nullable: true
        metadata:
          nullable: true
        sourceTraceId:
          type: string
          nullable: true
        sourceObservationId:
          type: string
          nullable: true
        id:
          type: string
          nullable: true
          description: >-
            Dataset items are upserted on their id. Id needs to be unique
            (project-level), cannot be reused across datasets, and must be at
            most 255 characters.
        status:
          $ref: '#/components/schemas/DatasetStatus'
          nullable: true
          description: Defaults to ACTIVE for newly created items
      required:
        - datasetName
    PaginatedDatasetItems:
      title: PaginatedDatasetItems
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/DatasetItem'
        meta:
          $ref: '#/components/schemas/utilsMetaResponse'
      required:
        - data
        - meta
    PaginatedDatasets:
      title: PaginatedDatasets
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Dataset'
        meta:
          $ref: '#/components/schemas/utilsMetaResponse'
      required:
        - data
        - meta
    CreateDatasetRequest:
      title: CreateDatasetRequest
      type: object
      properties:
        name:
          type: string
        description:
          type: string
          nullable: true
        metadata:
          nullable: true
        inputSchema:
          nullable: true
          description: >-
            JSON Schema for validating dataset item inputs. When set, all new
            and existing dataset items will be validated against this schema.
        expectedOutputSchema:
          nullable: true
          description: >-
            JSON Schema for validating dataset item expected outputs. When set,
            all new and existing dataset items will be validated against this
            schema.
      required:
        - name
    EvaluatorType:
      title: EvaluatorType
      type: string
      enum:
        - llm_as_judge
        - code
      description: |-
        The evaluator type.

        The public API supports LLM-as-a-judge and code evaluators.
    CodeEvaluatorSourceCodeLanguage:
      title: CodeEvaluatorSourceCodeLanguage
      type: string
      enum:
        - PYTHON
        - TYPESCRIPT
      description: Code evaluator runtime language.
    PromptVariableMappingSource:
      title: PromptVariableMappingSource
      type: string
      enum:
        - input
        - output
        - metadata
        - tool_calls
        - expected_output
        - experiment_item_metadata
      description: >-
        Source field used to populate a prompt variable.


        Use these values when mapping evaluator prompt variables to live data.


        Source semantics:

        - `input`: the observation input payload

        - `output`: the observation output payload

        - `metadata`: the observation metadata object. Combine with `jsonPath`
        when you need one nested field instead of the whole object.

        - `tool_calls`: the tool calls recorded on the observation, as an array
        of `{id, name, arguments, type, index}` objects in the order the model
        emitted them. Combine with `jsonPath` (for example `$[*].name`) to
        select parts of each call.

        - `expected_output`: the experiment item's expected output when the
        observation belongs to an experiment.

        - `experiment_item_metadata`: the experiment item's metadata when the
        observation belongs to an experiment.
    EvaluatorOutputScoreType:
      title: EvaluatorOutputScoreType
      type: string
      enum:
        - NUMERIC
        - BOOLEAN
        - CATEGORICAL
      description: >-
        Structured score type returned by an evaluator.


        This controls the type of score value Langfuse stores for evaluation
        results:

        - `NUMERIC`: a numeric score such as `0.82`

        - `BOOLEAN`: a boolean score such as `true`

        - `CATEGORICAL`: one or more category labels from a fixed list
    EvaluatorOutputDefinition:
      title: EvaluatorOutputDefinition
      oneOf:
        - type: object
          allOf:
            - type: object
              properties:
                dataType:
                  type: string
                  enum:
                    - NUMERIC
            - $ref: '#/components/schemas/PublicEvaluatorNumericScore'
          required:
            - dataType
          title: PublicEvaluatorNumericScore
        - type: object
          allOf:
            - type: object
              properties:
                dataType:
                  type: string
                  enum:
                    - BOOLEAN
            - $ref: '#/components/schemas/PublicEvaluatorBooleanScore'
          required:
            - dataType
          title: PublicEvaluatorBooleanScore
        - type: object
          allOf:
            - type: object
              properties:
                dataType:
                  type: string
                  enum:
                    - CATEGORICAL
            - $ref: '#/components/schemas/PublicEvaluatorCategoricalScore'
          required:
            - dataType
          title: PublicEvaluatorCategoricalScore
      description: >-
        Flat structured output definition used when creating or updating an
        evaluator.


        - `dataType` is required.

        - `scoreReasoningInstructions` and `scoreValueInstructions` are optional
        instructions.

        - `minValue` and `maxValue` apply only to `NUMERIC` outputs. If both are
        set, `minValue` must not exceed `maxValue`.

        - `categories` and `shouldAllowMultipleMatches` apply only to
        `CATEGORICAL` outputs.

        - Do not send `version`; that is an internal storage detail.
    EvaluatorOutputDefinitionBase:
      title: EvaluatorOutputDefinitionBase
      type: object
      properties:
        scoreReasoningInstructions:
          type: string
          nullable: true
          description: >-
            Optional instructions for deriving the reasoning returned with the
            score.
        scoreValueInstructions:
          type: string
          nullable: true
          description: Optional instructions for deriving the score value.
    PublicEvaluatorNumericScore:
      title: PublicEvaluatorNumericScore
      type: object
      properties:
        dataType:
          type: string
          const: NUMERIC
          description: Numeric score output.
        minValue:
          type: number
          format: double
          nullable: true
          description: Optional inclusive minimum value.
        maxValue:
          type: number
          format: double
          nullable: true
          description: Optional inclusive maximum value.
      required:
        - dataType
      allOf:
        - $ref: '#/components/schemas/EvaluatorOutputDefinitionBase'
    PublicEvaluatorBooleanScore:
      title: PublicEvaluatorBooleanScore
      type: object
      properties:
        dataType:
          type: string
          const: BOOLEAN
          description: Boolean score output.
      required:
        - dataType
      allOf:
        - $ref: '#/components/schemas/EvaluatorOutputDefinitionBase'
    PublicEvaluatorCategoricalScore:
      title: PublicEvaluatorCategoricalScore
      type: object
      properties:
        dataType:
          type: string
          const: CATEGORICAL
          description: Categorical score output.
        categories:
          type: array
          items:
            type: string
          description: Allowed category values. At least two unique values are required.
        shouldAllowMultipleMatches:
          type: boolean
          description: Whether the evaluator may return more than one category.
      required:
        - dataType
        - categories
        - shouldAllowMultipleMatches
      allOf:
        - $ref: '#/components/schemas/EvaluatorOutputDefinitionBase'
    PublicEvaluatorOutputDefinition:
      title: PublicEvaluatorOutputDefinition
      oneOf:
        - type: object
          allOf:
            - type: object
              properties:
                dataType:
                  type: string
                  enum:
                    - NUMERIC
            - $ref: '#/components/schemas/PublicEvaluatorNumericScore'
          required:
            - dataType
          title: PublicEvaluatorNumericScore
        - type: object
          allOf:
            - type: object
              properties:
                dataType:
                  type: string
                  enum:
                    - BOOLEAN
            - $ref: '#/components/schemas/PublicEvaluatorBooleanScore'
          required:
            - dataType
          title: PublicEvaluatorBooleanScore
        - type: object
          allOf:
            - type: object
              properties:
                dataType:
                  type: string
                  enum:
                    - CATEGORICAL
            - $ref: '#/components/schemas/PublicEvaluatorCategoricalScore'
          required:
            - dataType
          title: PublicEvaluatorCategoricalScore
      description: >-
        Flat evaluator output definition returned by the public API.


        This response always includes `dataType` and never includes an internal
        output-definition `version`.

        Optional empty descriptions from legacy definitions are omitted.
    EvaluationRuleStringFilterOperator:
      title: EvaluationRuleStringFilterOperator
      type: string
      enum:
        - '='
        - contains
        - does not contain
        - starts with
        - ends with
    EvaluationRuleStringObjectFilterOperator:
      title: EvaluationRuleStringObjectFilterOperator
      type: string
      enum:
        - '='
        - contains
        - does not contain
        - starts with
        - ends with
        - is set
        - is not set
    EvaluationRuleNumberFilterOperator:
      title: EvaluationRuleNumberFilterOperator
      type: string
      enum:
        - '='
        - '>'
        - <
        - '>='
        - <=
    EvaluationRuleOptionsFilterOperator:
      title: EvaluationRuleOptionsFilterOperator
      type: string
      enum:
        - any of
        - none of
    EvaluationRuleArrayOptionsFilterOperator:
      title: EvaluationRuleArrayOptionsFilterOperator
      type: string
      enum:
        - any of
        - none of
        - all of
    EvaluationRuleBooleanFilterOperator:
      title: EvaluationRuleBooleanFilterOperator
      type: string
      enum:
        - '='
        - <>
    EvaluationRuleNullFilterOperator:
      title: EvaluationRuleNullFilterOperator
      type: string
      enum:
        - is null
        - is not null
    DateTimeEvaluationRuleFilter:
      title: DateTimeEvaluationRuleFilter
      type: object
      properties:
        column:
          type: string
          description: Column to filter on.
        operator:
          $ref: '#/components/schemas/EvaluationRuleNumberFilterOperator'
          description: Comparison operator for datetime values.
        value:
          type: string
          format: date-time
          description: Datetime value to compare against.
      required:
        - column
        - operator
        - value
    StringEvaluationRuleFilter:
      title: StringEvaluationRuleFilter
      type: object
      properties:
        column:
          type: string
          description: Column to filter on.
        operator:
          $ref: '#/components/schemas/EvaluationRuleStringFilterOperator'
        value:
          type: string
      required:
        - column
        - operator
        - value
    NumberEvaluationRuleFilter:
      title: NumberEvaluationRuleFilter
      type: object
      properties:
        column:
          type: string
          description: Column to filter on.
        operator:
          $ref: '#/components/schemas/EvaluationRuleNumberFilterOperator'
        value:
          type: number
          format: double
      required:
        - column
        - operator
        - value
    StringOptionsEvaluationRuleFilter:
      title: StringOptionsEvaluationRuleFilter
      type: object
      properties:
        column:
          type: string
          description: Column to filter on.
        operator:
          $ref: '#/components/schemas/EvaluationRuleOptionsFilterOperator'
        value:
          type: array
          items:
            type: string
          description: One or more allowed string values.
      required:
        - column
        - operator
        - value
    ArrayOptionsEvaluationRuleFilter:
      title: ArrayOptionsEvaluationRuleFilter
      type: object
      properties:
        column:
          type: string
          description: Column to filter on.
        operator:
          $ref: '#/components/schemas/EvaluationRuleArrayOptionsFilterOperator'
        value:
          type: array
          items:
            type: string
          description: One or more array elements to match.
      required:
        - column
        - operator
        - value
    StringObjectEvaluationRuleFilter:
      title: StringObjectEvaluationRuleFilter
      type: object
      properties:
        column:
          type: string
          description: >-
            Object-valued column to filter on. Currently only `metadata` is
            supported.
        key:
          type: string
          description: Top-level key inside the object-valued column to filter on.
        operator:
          $ref: '#/components/schemas/EvaluationRuleStringObjectFilterOperator'
          description: Use `is set` / `is not set` to filter on key presence.
        value:
          type: string
          description: >-
            Value to compare against. Ignored for `is set` / `is not set`; send
            `""`.
      required:
        - column
        - key
        - operator
        - value
    NumberObjectEvaluationRuleFilter:
      title: NumberObjectEvaluationRuleFilter
      type: object
      properties:
        column:
          type: string
          description: Object-valued column to filter on.
        key:
          type: string
          description: Key inside the object-valued column to filter on.
        operator:
          $ref: '#/components/schemas/EvaluationRuleNumberFilterOperator'
        value:
          type: number
          format: double
      required:
        - column
        - key
        - operator
        - value
    CategoryOptionsEvaluationRuleFilter:
      title: CategoryOptionsEvaluationRuleFilter
      type: object
      properties:
        column:
          type: string
          description: Object-valued column to filter on.
        key:
          type: string
          description: Key inside the object-valued column to filter on.
        operator:
          $ref: '#/components/schemas/EvaluationRuleOptionsFilterOperator'
        value:
          type: array
          items:
            type: string
      required:
        - column
        - key
        - operator
        - value
    BooleanEvaluationRuleFilter:
      title: BooleanEvaluationRuleFilter
      type: object
      properties:
        column:
          type: string
          description: Column to filter on.
        operator:
          $ref: '#/components/schemas/EvaluationRuleBooleanFilterOperator'
        value:
          type: boolean
      required:
        - column
        - operator
        - value
    NullEvaluationRuleFilter:
      title: NullEvaluationRuleFilter
      type: object
      properties:
        column:
          type: string
          description: Column to filter on, for example `parentObservationId`.
        operator:
          $ref: '#/components/schemas/EvaluationRuleNullFilterOperator'
        value:
          type: string
          const: ''
          description: >-
            Required empty-string placeholder used by the runtime filter
            contract.
      required:
        - column
        - operator
        - value
    PromptVariableMappingInput:
      title: PromptVariableMappingInput
      type: object
      description: >-
        Connects one prompt variable to data from an observation or experiment.


        Manual mappings are used for `llm_as_judge` evaluators. `code`
        evaluators use a fixed runtime mapping managed by Langfuse.


        How to build a valid mapping list:

        1. Create the evaluator or fetch it with `GET /evaluators/{id}`.

        2. Read the evaluator `variables` array.

        3. Add exactly one mapping object for each variable in that array.

        4. Use the variable name exactly as returned, without braces such as
        `{{` or `}}`.

        5. Choose the source field that should populate the variable.


        `jsonPath` is optional. Use it only when the selected source is a JSON
        object and you want to extract one nested field before inserting it into
        the evaluator prompt.


        Invalid, missing, or duplicate mappings return a validation error.
        Malformed JSONPath expressions are also rejected.
      properties:
        variable:
          type: string
          description: >-
            Prompt variable name without braces.


            Example: for the prompt `Judge {{input}} against {{output}}`, use
            `input` and `output`.
        source:
          $ref: '#/components/schemas/PromptVariableMappingSource'
          description: >-
            Source field that should populate the prompt variable.


            Available sources are `input`, `output`, `metadata`, `tool_calls`,
            `expected_output`, and `experiment_item_metadata`.
        jsonPath:
          type: string
          nullable: true
          description: >-
            Optional JSONPath selector applied to the selected source before it
            is passed to the evaluator prompt.


            Requirements:

            - Must start with `$`

            - Must be a syntactically valid JSONPath expression

            - Most useful with `source=metadata`
      required:
        - variable
        - source
    PromptVariableMappingRead:
      title: PromptVariableMappingRead
      type: object
      description: |-
        Connects one prompt variable to source data.

        `source` is `null` when the mapping is incomplete.
      properties:
        variable:
          type: string
          description: Prompt variable name without braces.
        source:
          type: string
          nullable: true
          description: >-
            Stored source field populating the variable, or `null` when the
            mapping is incomplete.
        jsonPath:
          type: string
          nullable: true
          description: Optional JSONPath selector applied to the selected source.
      required:
        - variable
        - source
    PromptVariableMapping:
      title: PromptVariableMapping
      oneOf:
        - $ref: '#/components/schemas/PromptVariableMappingRead'
        - $ref: '#/components/schemas/LegacyPromptVariableMapping'
      description: Connects one prompt variable to source data.
    LegacyPromptVariableMapping:
      title: LegacyPromptVariableMapping
      type: object
      description: >-
        **Deprecated:** Connects one prompt variable to data from a legacy trace
        or dataset evaluation rule.


        `langfuseObject` selects the object kind. `objectName` separately
        selects a named observation and is `null` for trace and dataset-item
        mappings.
      properties:
        mappingType:
          type: string
          const: legacy
          description: Explicitly marks this as a legacy mapping.
        variable:
          type: string
          description: Prompt variable name without braces.
        langfuseObject:
          $ref: '#/components/schemas/LegacyEvaluationObject'
          description: Legacy object kind selected as the mapping source.
        objectName:
          type: string
          nullable: true
          description: >-
            Observation name to match, or `null` when `langfuseObject` is
            `trace` or `dataset_item`.
        source:
          type: string
          description: Field selected from the legacy object.
        jsonPath:
          type: string
          nullable: true
          description: Optional JSONPath selector applied to the selected field.
      required:
        - mappingType
        - variable
        - langfuseObject
        - objectName
        - source
    LegacyEvaluationObject:
      title: LegacyEvaluationObject
      type: string
      enum:
        - trace
        - span
        - generation
        - event
        - agent
        - tool
        - chain
        - retriever
        - evaluator
        - embedding
        - guardrail
        - dataset_item
      description: >-
        **Deprecated:** Legacy Langfuse object kind used by trace and dataset
        evaluation rules.
    EvaluationRuleFilter:
      title: EvaluationRuleFilter
      oneOf:
        - type: object
          allOf:
            - type: object
              properties:
                type:
                  type: string
                  enum:
                    - datetime
            - $ref: '#/components/schemas/DateTimeEvaluationRuleFilter'
          required:
            - type
          title: DateTimeEvaluationRuleFilter
        - type: object
          allOf:
            - type: object
              properties:
                type:
                  type: string
                  enum:
                    - string
            - $ref: '#/components/schemas/StringEvaluationRuleFilter'
          required:
            - type
          title: StringEvaluationRuleFilter
        - type: object
          allOf:
            - type: object
              properties:
                type:
                  type: string
                  enum:
                    - number
            - $ref: '#/components/schemas/NumberEvaluationRuleFilter'
          required:
            - type
          title: NumberEvaluationRuleFilter
        - type: object
          allOf:
            - type: object
              properties:
                type:
                  type: string
                  enum:
                    - stringOptions
            - $ref: '#/components/schemas/StringOptionsEvaluationRuleFilter'
          required:
            - type
          title: StringOptionsEvaluationRuleFilter
        - type: object
          allOf:
            - type: object
              properties:
                type:
                  type: string
                  enum:
                    - categoryOptions
            - $ref: '#/components/schemas/CategoryOptionsEvaluationRuleFilter'
          required:
            - type
          title: CategoryOptionsEvaluationRuleFilter
        - type: object
          allOf:
            - type: object
              properties:
                type:
                  type: string
                  enum:
                    - arrayOptions
            - $ref: '#/components/schemas/ArrayOptionsEvaluationRuleFilter'
          required:
            - type
          title: ArrayOptionsEvaluationRuleFilter
        - type: object
          allOf:
            - type: object
              properties:
                type:
                  type: string
                  enum:
                    - stringObject
            - $ref: '#/components/schemas/StringObjectEvaluationRuleFilter'
          required:
            - type
          title: StringObjectEvaluationRuleFilter
        - type: object
          allOf:
            - type: object
              properties:
                type:
                  type: string
                  enum:
                    - numberObject
            - $ref: '#/components/schemas/NumberObjectEvaluationRuleFilter'
          required:
            - type
          title: NumberObjectEvaluationRuleFilter
        - type: object
          allOf:
            - type: object
              properties:
                type:
                  type: string
                  enum:
                    - boolean
            - $ref: '#/components/schemas/BooleanEvaluationRuleFilter'
          required:
            - type
          title: BooleanEvaluationRuleFilter
        - type: object
          allOf:
            - type: object
              properties:
                type:
                  type: string
                  enum:
                    - 'null'
            - $ref: '#/components/schemas/NullEvaluationRuleFilter'
          required:
            - type
          title: NullEvaluationRuleFilter
      description: >-
        One filter condition used to decide whether a live-ingested observation
        should be evaluated.


        All filters must be satisfied for the rule to run. Experiment scope is
        expressed with filters rather than a separate target field:

        - `isExperimentItemRootSpan = true` limits execution to experiment item
        roots.

        - `datasetId` limits execution to experiments for the selected datasets.
        Use dataset IDs from `GET /api/public/v2/datasets`.


        Pick the filter `type` first, as it determines the required fields and
        value shape. Use `key` only for object filters such as `metadata`.


        Operator quick reference by filter `type`:

        - `string`: `"="`, `contains`, `does not contain`, `starts with`, `ends
        with`

        - `number`: `"="`, `">"`, `"<"`, `">="`, `"<="`

        - `datetime`: `"="`, `">"`, `"<"`, `">="`, `"<="`

        - `stringOptions`: `any of`, `none of`

        - `arrayOptions`: `any of`, `none of`, `all of`

        - `stringObject`: `"="`, `contains`, `does not contain`, `starts with`,
        `ends with`, `is set`, `is not set` (use `is set` / `is not set` for key
        presence; an empty value for `contains`, `starts with`, or `ends with`
        is treated as `is set`)

        - `boolean`: `"="`, `"<>"`

        - `null`: `is null`, `is not null`


        Supported columns. Each column accepts exactly one filter `type`;
        sending a column with a different `type` is rejected with `400`.

        - `type`: `stringOptions`, values `SPAN`, `EVENT`, `GENERATION`,
        `AGENT`, `TOOL`, `CHAIN`, `RETRIEVER`, `EVALUATOR`, `EMBEDDING`,
        `GUARDRAIL`

        - `name`: `stringOptions`

        - `environment`: `stringOptions`

        - `level`: `stringOptions`, values `DEBUG`, `DEFAULT`, `WARNING`,
        `ERROR`

        - `version`: `string`

        - `traceName`: `stringOptions`

        - `userId`: `string`

        - `sessionId`: `string`

        - `tags`: `arrayOptions`

        - `metadata`: `stringObject`, requires `key`

        - `isRootObservation`: `boolean`; true when the observation has no
        parent or is explicitly marked as an application root

        - `parentObservationId`: `null`

        - `experimentId`: `stringOptions`

        - `isExperimentItemRootSpan`: `boolean`

        - `calledToolNames`: `arrayOptions`

        - `toolCalls`: `number`, the number of tool calls on the observation

        - `datasetId`: `stringOptions`. Use dataset `id` values from `GET
        /api/public/v2/datasets`, not dataset names.
    EvaluationRuleReadFilterBase:
      title: EvaluationRuleReadFilterBase
      type: object
      description: Stored filter returned verbatim by evaluation-rule read endpoints.
      properties:
        type:
          type: string
          description: >-
            Stored filter type. This is not broken down into separate public
            response types.
        column:
          type: string
        operator:
          type: string
        value:
          nullable: true
          description: Stored filter value. Its shape depends on the filter type.
      required:
        - type
        - column
        - operator
    EvaluationRuleReadFilterWithKey:
      title: EvaluationRuleReadFilterWithKey
      type: object
      properties:
        key:
          type: string
          description: Stored object or legacy filter key.
      required:
        - key
      allOf:
        - $ref: '#/components/schemas/EvaluationRuleReadFilterBase'
    EvaluationRuleReadFilter:
      title: EvaluationRuleReadFilter
      oneOf:
        - $ref: '#/components/schemas/EvaluationRuleReadFilterWithKey'
        - $ref: '#/components/schemas/EvaluationRuleReadFilterBase'
      description: >-
        Filter returned verbatim by evaluation-rule read endpoints.


        Filters with a stored `key` use the keyed shape. All other filters use
        the base shape. Response filters are intentionally not broken down by
        their internal `type` value.
    PublicApiErrorCode:
      title: PublicApiErrorCode
      type: string
      enum:
        - authentication_failed
        - access_denied
        - invalid_request
        - invalid_query
        - invalid_body
        - resource_not_found
        - conflict
        - rate_limited
        - method_not_allowed
        - internal_error
      description: >-
        Stable machine-readable error code returned by the evaluators and
        evaluation-rules API.
    PublicApiValidationIssue:
      title: PublicApiValidationIssue
      type: object
      description: One request validation issue.
      properties:
        code:
          type: string
          description: Validator issue code.
        message:
          type: string
          description: Human-readable explanation.
        path:
          type: array
          items: {}
          description: Path to the invalid request field.
      required:
        - code
        - message
        - path
    PublicApiErrorDetails:
      title: PublicApiErrorDetails
      type: object
      description: Optional structured context for validation and rate-limit errors.
      properties:
        issues:
          type: array
          items:
            $ref: '#/components/schemas/PublicApiValidationIssue'
          nullable: true
          description: Validation issues for an invalid request body or query.
        retryAfterSeconds:
          type: integer
          nullable: true
          description: Number of seconds to wait before retrying a rate-limited request.
        limit:
          type: integer
          nullable: true
          description: Rate-limit request allowance.
        remaining:
          type: integer
          nullable: true
          description: Remaining requests in the current rate-limit window.
        resetAt:
          type: string
          format: date-time
          nullable: true
          description: Time when the current rate-limit window resets.
    PublicApiError:
      title: PublicApiError
      type: object
      description: >-
        Standard error response for the stable evaluators and evaluation-rules
        API.


        Use the HTTP status for the broad failure class and `code` for
        programmatic handling. `details` is included when field-level validation
        or retry information is available.
      properties:
        message:
          type: string
          description: Human-readable description of the failure.
        code:
          $ref: '#/components/schemas/PublicApiErrorCode'
          description: Stable machine-readable error code.
        details:
          $ref: '#/components/schemas/PublicApiErrorDetails'
          nullable: true
          description: Optional structured validation or rate-limit context.
      required:
        - message
        - code
    EvaluationRuleEvaluatorAssignmentInput:
      title: EvaluationRuleEvaluatorAssignmentInput
      type: object
      properties:
        evaluatorId:
          type: string
          description: >-
            Stable evaluator identifier. The rule automatically uses that
            evaluator's latest version.
        variableMapping:
          type: array
          items:
            $ref: '#/components/schemas/PromptVariableMappingInput'
          nullable: true
          description: >-
            Rule-specific prompt-variable mapping.


            Set to `null` or omit to inherit the evaluator's latest default
            mapping. Code evaluators use the fixed runtime mapping and should
            use `null`.
      required:
        - evaluatorId
    EvaluatorAssignment:
      title: EvaluatorAssignment
      type: object
      properties:
        evaluatorId:
          type: string
          description: Stable identifier of the evaluator associated with this rule.
        variableMapping:
          type: array
          items:
            $ref: '#/components/schemas/PromptVariableMapping'
          nullable: true
          description: >-
            Stored rule-specific override, or `null` when the evaluator's latest
            default mapping is inherited. Legacy mappings are returned as an
            explicit `legacy` variant.
      required:
        - evaluatorId
        - variableMapping
    EvaluationRule:
      title: EvaluationRule
      type: object
      description: >-
        Live evaluation rule for incoming observations.


        A rule determines which evaluators should be used, which observations
        should trigger scoring, how often scoring should run, and which
        observation fields should populate prompt variables.
      properties:
        id:
          type: string
          description: Stable evaluation-rule identifier.
        name:
          type: string
          description: >-
            Human-readable rule name. This is independent from evaluator names
            and does not need to be unique.
        createdBy:
          $ref: '#/components/schemas/Creator'
          nullable: true
          description: User who created this rule, or `null` when no user can be resolved.
        enabled:
          type: boolean
          description: Whether live execution is enabled for this rule.
        sampling:
          type: number
          format: double
          description: |-
            Fraction of matching observations that should be evaluated.

            Must be between `0` and `1`.
            - `1` evaluates every matching observation.
            - `0.25` evaluates approximately 25% of matching observations.
        filter:
          type: array
          items:
            $ref: '#/components/schemas/EvaluationRuleReadFilter'
          description: >-
            List of stored filter conditions returned verbatim. Filters with a
            `key` use the keyed response shape; all others use the base shape.
            These response shapes are not broken down by internal filter type.
            An empty list matches every incoming object.
        evaluatorAssignments:
          type: array
          items:
            $ref: '#/components/schemas/EvaluatorAssignment'
          description: Evaluators attached to this rule in deterministic assignment order.
        createdAt:
          type: string
          format: date-time
          description: Timestamp when the evaluation rule was created.
        updatedAt:
          type: string
          format: date-time
          description: Timestamp when the evaluation rule was last updated.
      required:
        - id
        - name
        - createdBy
        - enabled
        - sampling
        - filter
        - evaluatorAssignments
        - createdAt
        - updatedAt
    CreateEvaluationRuleRequest:
      title: CreateEvaluationRuleRequest
      type: object
      properties:
        name:
          type: string
          description: >-
            Human-readable rule name. Names are not identifiers and do not need
            to be unique.
        enabled:
          type: boolean
          description: >-
            Whether live execution should start immediately. Enabled rules
            require at least one evaluator assignment.
        sampling:
          type: number
          format: double
          nullable: true
          description: >-
            Fraction of matching observations to evaluate. Omit this field to
            use the default of `1`, which evaluates every match. `null` is not
            accepted.
        filter:
          type: array
          items:
            $ref: '#/components/schemas/EvaluationRuleFilter'
          nullable: true
          description: >-
            Conditions used to select observations. Defaults to an empty list,
            which matches every incoming observation.
        evaluatorAssignments:
          type: array
          items:
            $ref: '#/components/schemas/EvaluationRuleEvaluatorAssignmentInput'
          description: >-
            Evaluators to attach to this rule. Disabled rules may use an empty
            list as a draft.
      required:
        - name
        - enabled
        - evaluatorAssignments
    UpdateEvaluationRuleRequest:
      title: UpdateEvaluationRuleRequest
      type: object
      description: At least one field must be provided.
      properties:
        name:
          type: string
          nullable: true
          description: New human-readable rule name.
        enabled:
          type: boolean
          nullable: true
          description: New desired live-execution state.
        sampling:
          type: number
          format: double
          nullable: true
          description: >-
            New fraction of matching observations to evaluate. Omit to keep the
            current value.
        filter:
          type: array
          items:
            $ref: '#/components/schemas/EvaluationRuleFilter'
          nullable: true
          description: >-
            Complete replacement filter list. An empty list matches every
            incoming observation.
        evaluatorAssignments:
          type: array
          items:
            $ref: '#/components/schemas/EvaluationRuleEvaluatorAssignmentInput'
          nullable: true
          description: >-
            Complete replacement assignment list. An empty list disables the
            rule.
    EvaluationRulesPage:
      title: EvaluationRulesPage
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/EvaluationRule'
          description: Evaluation rules for this page.
        meta:
          $ref: '#/components/schemas/CursorMeta'
          description: Cursor pagination metadata.
      required:
        - data
        - meta
    DeletedEvaluationRule:
      title: DeletedEvaluationRule
      type: object
      description: Confirmation returned after successful evaluation-rule deletion.
      properties:
        id:
          type: string
          description: Identifier of the deleted evaluation rule.
      required:
        - id
    Creator:
      title: Creator
      type: object
      description: User who created the resource, or `null` when no user can be resolved.
      properties:
        id:
          type: string
          description: User identifier.
        name:
          type: string
          nullable: true
          description: User name, or `null` when unavailable.
      required:
        - id
        - name
    EvaluatorModelConfig:
      title: EvaluatorModelConfig
      type: object
      description: >-
        Explicit model configuration for an evaluator.


        If the complete `modelConfig` is `null`, Langfuse uses the project's
        default evaluation model.

        If provided, the model must be available to the project when the
        evaluator or evaluation rule is enabled.
      properties:
        provider:
          type: string
          description: >-
            Provider identifier, for example `openai` or `anthropic`.


            To discover valid values for the current project, call `GET
            /api/public/llm-connections` and use one of the returned `provider`
            values.
        model:
          type: string
          description: >-
            Model identifier exposed by the provider, for example `gpt-4.1-mini`.
      required:
        - provider
        - model
    EvaluatorChatMessageRole:
      title: EvaluatorChatMessageRole
      type: string
      enum:
        - system
        - user
        - assistant
      description: Role of an evaluator prompt message.
    EvaluatorChatMessage:
      title: EvaluatorChatMessage
      type: object
      description: One chat message in an evaluator prompt.
      properties:
        role:
          $ref: '#/components/schemas/EvaluatorChatMessageRole'
        content:
          type: string
          description: Message content. Evaluator variables use `{{variable}}` syntax.
      required:
        - role
        - content
    EvaluatorChatPrompt:
      title: EvaluatorChatPrompt
      type: array
      items:
        $ref: '#/components/schemas/EvaluatorChatMessage'
      description: >-
        An ordered list of chat messages. A system message is only allowed as
        the first message.
    EvaluatorChatPromptInput:
      title: EvaluatorChatPromptInput
      oneOf:
        - type: string
          title: String
        - $ref: '#/components/schemas/EvaluatorChatPrompt'
      description: A user prompt string shortcut, or an ordered list of chat messages.
    EvaluatorVersionBase:
      title: EvaluatorVersionBase
      type: object
      properties:
        id:
          type: string
          description: Stable identifier of this evaluator version.
        version:
          type: integer
          description: Monotonically increasing evaluator version number.
        createdAt:
          type: string
          format: date-time
          description: Timestamp when this evaluator version was created.
        createdBy:
          $ref: '#/components/schemas/Creator'
          nullable: true
          description: >-
            User who created this version, or `null` when no user can be
            resolved.
      required:
        - id
        - version
        - createdAt
        - createdBy
    LlmAsJudgeEvaluatorVersion:
      title: LlmAsJudgeEvaluatorVersion
      type: object
      properties:
        type:
          type: string
          const: llm_as_judge
          description: Evaluator type.
        prompt:
          $ref: '#/components/schemas/EvaluatorChatPrompt'
          description: Ordered chat messages used during evaluation.
        variables:
          type: array
          items:
            type: string
          description: >-
            Variables extracted from the prompt and available for
            evaluation-rule mappings.


            Every variable must be mapped exactly once when a rule provides an
            explicit mapping.
        variableMapping:
          type: array
          items:
            $ref: '#/components/schemas/PromptVariableMappingRead'
          nullable: true
          description: >-
            Default variable mapping for this evaluator version, or `null` when
            no default is configured.
        modelConfig:
          $ref: '#/components/schemas/EvaluatorModelConfig'
          nullable: true
          description: >-
            Explicit model configuration, or `null` when the project's default
            evaluation model is used.
        outputDefinition:
          $ref: '#/components/schemas/PublicEvaluatorOutputDefinition'
          description: >-
            Structured output schema returned by this evaluator.


            Responses include `dataType` and omit the internal output-definition
            persistence version.
      required:
        - type
        - prompt
        - variables
        - variableMapping
        - modelConfig
        - outputDefinition
      allOf:
        - $ref: '#/components/schemas/EvaluatorVersionBase'
    CodeEvaluatorVersion:
      title: CodeEvaluatorVersion
      type: object
      properties:
        type:
          type: string
          const: code
          description: Evaluator type.
        sourceCode:
          type: string
          description: Source code executed for each matched observation.
        sourceCodeLanguage:
          $ref: '#/components/schemas/CodeEvaluatorSourceCodeLanguage'
          description: Runtime language used to execute the source code.
      required:
        - type
        - sourceCode
        - sourceCodeLanguage
      allOf:
        - $ref: '#/components/schemas/EvaluatorVersionBase'
    EvaluatorVersion:
      title: EvaluatorVersion
      oneOf:
        - type: object
          allOf:
            - type: object
              properties:
                type:
                  type: string
                  enum:
                    - llm_as_judge
            - $ref: '#/components/schemas/LlmAsJudgeEvaluatorVersion'
          required:
            - type
          title: LlmAsJudgeEvaluatorVersion
        - type: object
          allOf:
            - type: object
              properties:
                type:
                  type: string
                  enum:
                    - code
            - $ref: '#/components/schemas/CodeEvaluatorVersion'
          required:
            - type
          title: CodeEvaluatorVersion
    EvaluationRuleAssignment:
      title: EvaluationRuleAssignment
      type: object
      description: Evaluation-rule assignment associated with this evaluator.
      properties:
        evaluationRuleId:
          type: string
          description: Stable identifier of the assigned evaluation rule.
        variableMappingOverride:
          type: array
          items:
            $ref: '#/components/schemas/PromptVariableMapping'
          nullable: true
          description: >-
            Rule-specific variable mapping override. Omitted when the
            evaluator's latest default mapping is inherited. Legacy mappings use
            the explicit `legacy` variant.
      required:
        - evaluationRuleId
    EvaluatorBase:
      title: EvaluatorBase
      type: object
      properties:
        id:
          type: string
          description: Stable identifier of this evaluator across all versions.
        name:
          type: string
          description: >-
            Human-readable evaluator name. Names are not identifiers and do not
            need to be unique.
        description:
          type: string
          nullable: true
          description: Optional human-readable evaluator description.
        createdBy:
          $ref: '#/components/schemas/Creator'
          nullable: true
          description: >-
            User who created this evaluator, or `null` when no user can be
            resolved.
        status:
          $ref: '#/components/schemas/EvaluatorStatus'
          description: >-
            Effective evaluator status after Langfuse validates its runtime
            configuration.
        pausedAt:
          type: string
          format: date-time
          nullable: true
          description: Timestamp when the evaluator was paused, otherwise `null`.
        pausedReason:
          type: string
          nullable: true
          description: Machine-readable reason when `status=paused`, otherwise `null`.
        pausedMessage:
          type: string
          nullable: true
          description: Human-readable explanation when `status=paused`, otherwise `null`.
        evaluationRuleAssignments:
          type: array
          items:
            $ref: '#/components/schemas/EvaluationRuleAssignment'
          description: >-
            All modern and legacy evaluation-rule assignments in
            newest-assignment-first order. Rule-specific mappings are exposed as
            `variableMappingOverride`; inherited defaults are omitted.
        createdAt:
          type: string
          format: date-time
          description: Timestamp when the evaluator was created.
        updatedAt:
          type: string
          format: date-time
          description: Timestamp when the evaluator was last updated.
        versionId:
          type: string
          description: Stable identifier of the latest evaluator version.
        version:
          type: integer
          description: Monotonically increasing latest evaluator version number.
        versionCreatedAt:
          type: string
          format: date-time
          description: Timestamp when the latest evaluator version was created.
        versionCreatedBy:
          $ref: '#/components/schemas/Creator'
          nullable: true
          description: >-
            User who created the latest evaluator version, or `null` when no
            user can be resolved.
      required:
        - id
        - name
        - description
        - createdBy
        - status
        - pausedAt
        - pausedReason
        - pausedMessage
        - evaluationRuleAssignments
        - createdAt
        - updatedAt
        - versionId
        - version
        - versionCreatedAt
        - versionCreatedBy
    LlmAsJudgeEvaluator:
      title: LlmAsJudgeEvaluator
      type: object
      properties:
        type:
          type: string
          const: llm_as_judge
          description: Evaluator type.
        prompt:
          $ref: '#/components/schemas/EvaluatorChatPrompt'
          description: Ordered chat messages used by the latest evaluator version.
        variables:
          type: array
          items:
            type: string
          description: >-
            Variables extracted from the latest prompt and available for
            evaluation-rule mappings.
        variableMapping:
          type: array
          items:
            $ref: '#/components/schemas/PromptVariableMappingRead'
          nullable: true
          description: >-
            Default variable mapping for the latest version, or `null` when no
            default is configured.
        modelConfig:
          $ref: '#/components/schemas/EvaluatorModelConfig'
          nullable: true
          description: >-
            Explicit model configuration for the latest version, or `null` when
            the project's default evaluation model is used.
        outputDefinition:
          $ref: '#/components/schemas/PublicEvaluatorOutputDefinition'
          description: Structured output schema returned by the latest evaluator version.
      required:
        - type
        - prompt
        - variables
        - variableMapping
        - modelConfig
        - outputDefinition
      allOf:
        - $ref: '#/components/schemas/EvaluatorBase'
    CodeEvaluator:
      title: CodeEvaluator
      type: object
      properties:
        type:
          type: string
          const: code
          description: Evaluator type.
        sourceCode:
          type: string
          description: Source code executed by the latest evaluator version.
        sourceCodeLanguage:
          $ref: '#/components/schemas/CodeEvaluatorSourceCodeLanguage'
          description: Runtime language used to execute the latest source code.
      required:
        - type
        - sourceCode
        - sourceCodeLanguage
      allOf:
        - $ref: '#/components/schemas/EvaluatorBase'
    Evaluator:
      title: Evaluator
      oneOf:
        - type: object
          allOf:
            - type: object
              properties:
                type:
                  type: string
                  enum:
                    - llm_as_judge
            - $ref: '#/components/schemas/LlmAsJudgeEvaluator'
          required:
            - type
          title: LlmAsJudgeEvaluator
        - type: object
          allOf:
            - type: object
              properties:
                type:
                  type: string
                  enum:
                    - code
            - $ref: '#/components/schemas/CodeEvaluator'
          required:
            - type
          title: CodeEvaluator
      description: >-
        One evaluator that can be used for scoring.


        An evaluator describes **how** to score data. Associated evaluation
        rules describe **which** live objects should be evaluated.
    EvaluatorStatus:
      title: EvaluatorStatus
      type: string
      enum:
        - active
        - paused
      description: >-
        Effective evaluator runtime status.


        - `active`: the evaluator can run.

        - `paused`: Langfuse paused execution until the underlying issue is
        resolved.
    CreateLlmAsJudgeEvaluatorRequest:
      title: CreateLlmAsJudgeEvaluatorRequest
      type: object
      properties:
        name:
          type: string
          description: >-
            Human-readable evaluator name. Names are not identifiers and do not
            need to be unique.
        description:
          type: string
          nullable: true
          description: Optional human-readable evaluator description.
        type:
          type: string
          const: llm_as_judge
          description: Evaluator type.
        prompt:
          $ref: '#/components/schemas/EvaluatorChatPromptInput'
          description: User prompt string shortcut or an ordered list of chat messages.
        modelConfig:
          $ref: '#/components/schemas/EvaluatorModelConfig'
          nullable: true
          description: >-
            Explicit model configuration. Set to `null` or omit to use the
            project's default evaluation model.
        variableMapping:
          type: array
          items:
            $ref: '#/components/schemas/PromptVariableMappingInput'
          nullable: true
          description: >-
            Default prompt-variable mapping, or `null` when no default is
            configured.
        outputDefinition:
          $ref: '#/components/schemas/EvaluatorOutputDefinition'
          description: >-
            Structured output schema returned by this evaluator. Do not include
            an internal persistence version.
      required:
        - name
        - type
        - prompt
        - outputDefinition
    CreateCodeEvaluatorRequest:
      title: CreateCodeEvaluatorRequest
      type: object
      properties:
        name:
          type: string
          description: >-
            Human-readable evaluator name. Names are not identifiers and do not
            need to be unique.
        description:
          type: string
          nullable: true
          description: Optional human-readable evaluator description.
        type:
          type: string
          const: code
          description: Evaluator type.
        sourceCode:
          type: string
          description: Source code executed for each matched observation.
        sourceCodeLanguage:
          $ref: '#/components/schemas/CodeEvaluatorSourceCodeLanguage'
          description: Runtime language used to execute the source code.
      required:
        - name
        - type
        - sourceCode
        - sourceCodeLanguage
    CreateEvaluatorRequest:
      title: CreateEvaluatorRequest
      oneOf:
        - type: object
          allOf:
            - type: object
              properties:
                type:
                  type: string
                  enum:
                    - llm_as_judge
            - $ref: '#/components/schemas/CreateLlmAsJudgeEvaluatorRequest'
          required:
            - type
          title: CreateLlmAsJudgeEvaluatorRequest
        - type: object
          allOf:
            - type: object
              properties:
                type:
                  type: string
                  enum:
                    - code
            - $ref: '#/components/schemas/CreateCodeEvaluatorRequest'
          required:
            - type
          title: CreateCodeEvaluatorRequest
      description: >-
        Initial evaluator definition with metadata and definition fields at the
        same level. The returned evaluator starts at version `1`.
    UpdateEvaluatorMetadataRequest:
      title: UpdateEvaluatorMetadataRequest
      type: object
      description: Metadata-only update. At least one field must be provided.
      properties:
        name:
          type: string
          nullable: true
          description: New human-readable evaluator name.
        description:
          type: string
          nullable: true
          description: New description. Set to `null` to clear it.
    UpdateLlmAsJudgeEvaluatorRequest:
      title: UpdateLlmAsJudgeEvaluatorRequest
      type: object
      properties:
        name:
          type: string
          nullable: true
          description: New human-readable evaluator name.
        description:
          type: string
          nullable: true
          description: New description. Set to `null` to clear it.
        type:
          type: string
          const: llm_as_judge
          description: Evaluator type. The type of an existing evaluator cannot change.
        prompt:
          $ref: '#/components/schemas/EvaluatorChatPromptInput'
          description: >-
            Complete replacement user prompt string or an ordered list of chat
            messages.
        modelConfig:
          $ref: '#/components/schemas/EvaluatorModelConfig'
          nullable: true
          description: >-
            Explicit model configuration. Set to `null` or omit to use the
            project's default evaluation model.
        variableMapping:
          type: array
          items:
            $ref: '#/components/schemas/PromptVariableMappingInput'
          nullable: true
          description: >-
            Complete replacement default variable mapping, or `null` when no
            default is configured.
        outputDefinition:
          $ref: '#/components/schemas/EvaluatorOutputDefinition'
          description: >-
            Complete replacement output schema. Do not include an internal
            persistence version.
      required:
        - type
        - prompt
        - outputDefinition
    UpdateCodeEvaluatorRequest:
      title: UpdateCodeEvaluatorRequest
      type: object
      properties:
        name:
          type: string
          nullable: true
          description: New human-readable evaluator name.
        description:
          type: string
          nullable: true
          description: New description. Set to `null` to clear it.
        type:
          type: string
          const: code
          description: Evaluator type. The type of an existing evaluator cannot change.
        sourceCode:
          type: string
          description: Complete replacement source code.
        sourceCodeLanguage:
          $ref: '#/components/schemas/CodeEvaluatorSourceCodeLanguage'
          description: Runtime language used to execute the source code.
      required:
        - type
        - sourceCode
        - sourceCodeLanguage
    UpdateEvaluatorRequest:
      title: UpdateEvaluatorRequest
      oneOf:
        - $ref: '#/components/schemas/UpdateEvaluatorMetadataRequest'
        - $ref: '#/components/schemas/UpdateLlmAsJudgeEvaluatorRequest'
        - $ref: '#/components/schemas/UpdateCodeEvaluatorRequest'
      description: >-
        Metadata-only update or complete flattened definition replacement. At
        least one field must be provided.
    EvaluatorsPage:
      title: EvaluatorsPage
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Evaluator'
          description: Evaluators for this page.
        meta:
          $ref: '#/components/schemas/CursorMeta'
          description: Cursor pagination metadata.
      required:
        - data
        - meta
    EvaluatorVersionsPage:
      title: EvaluatorVersionsPage
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/EvaluatorVersion'
          description: Evaluator versions for this page in newest-first order.
        meta:
          $ref: '#/components/schemas/CursorMeta'
          description: Cursor pagination metadata.
      required:
        - data
        - meta
    CursorMeta:
      title: CursorMeta
      type: object
      description: Cursor pagination metadata.
      properties: {}
      allOf:
        - $ref: '#/components/schemas/utilsCursorMetaResponse'
    DeletedEvaluator:
      title: DeletedEvaluator
      type: object
      description: Confirmation returned after successful evaluator deletion.
      properties:
        id:
          type: string
          description: Identifier of the deleted evaluator.
      required:
        - id
    ExperimentsResponse:
      title: ExperimentsResponse
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Experiment'
        meta:
          $ref: '#/components/schemas/ExperimentsResponseMeta'
      required:
        - data
        - meta
    ExperimentsResponseMeta:
      title: ExperimentsResponseMeta
      type: object
      description: Metadata for cursor-based pagination.
      properties: {}
      allOf:
        - $ref: '#/components/schemas/utilsCursorMetaResponse'
    Experiment:
      title: Experiment
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        description:
          type: string
          nullable: true
        startTime:
          type: string
          format: date-time
          description: |-
            Start of the experiment, i.e. the earliest event within the
            requested time range. Clipped to `fromStartTime` when the
            experiment started before the requested range.
        endTime:
          type: string
          format: date-time
          description: |-
            End of the experiment, i.e. the latest event end within the
            requested time range.
        itemCount:
          type: integer
          description: Number of experiment items within the requested time range.
        datasetId:
          type: string
          nullable: true
          description: Null when the experiment is not associated with a dataset.
        metadata:
          type: object
          additionalProperties: true
          nullable: true
          description: Included only when `fields=metadata` is requested.
        scores:
          type: array
          items:
            $ref: '#/components/schemas/ScoreV3'
          nullable: true
          description: >-
            Included only when `fields=scores` is requested. Contains scores
            directly attached to the experiment.
      required:
        - id
        - name
        - description
        - startTime
        - endTime
        - itemCount
        - datasetId
    ExperimentItemsResponse:
      title: ExperimentItemsResponse
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/ExperimentItem'
        meta:
          $ref: '#/components/schemas/ExperimentsResponseMeta'
      required:
        - data
        - meta
    ExperimentItem:
      title: ExperimentItem
      type: object
      properties:
        id:
          type: string
        traceId:
          type: string
        startTime:
          type: string
          format: date-time
        endTime:
          type: string
          format: date-time
          nullable: true
        level:
          $ref: '#/components/schemas/ObservationLevel'
        environment:
          type: string
        experimentId:
          type: string
        experimentName:
          type: string
        experimentItemId:
          type: string
        experimentDatasetId:
          type: string
          nullable: true
          description: Included when `fields=dataset` is requested.
        experimentItemVersion:
          type: string
          format: date-time
          nullable: true
          description: Included when `fields=dataset` is requested.
        input:
          nullable: true
          description: Included when `fields=io` is requested.
        output:
          nullable: true
          description: Included when `fields=io` is requested.
        expectedOutput:
          nullable: true
          description: Included when `fields=io` is requested.
        metadata:
          type: object
          additionalProperties: true
          nullable: true
          description: Included when `fields=metadata` is requested.
        experimentItemMetadata:
          type: object
          additionalProperties: true
          nullable: true
          description: Included when `fields=itemMetadata` is requested.
        experimentMetadata:
          type: object
          additionalProperties: true
          nullable: true
          description: Included when `fields=experimentMetadata` is requested.
        experimentDescription:
          type: string
          nullable: true
          description: Included when `fields=experimentMetadata` is requested.
        scores:
          type: array
          items:
            $ref: '#/components/schemas/ScoreV3'
          nullable: true
          description: >-
            Included only when `fields=scores` is requested. Contains item and
            trace scores only; experiment-level scores are returned by the
            experiments endpoint.
      required:
        - id
        - traceId
        - startTime
        - endTime
        - level
        - environment
        - experimentId
        - experimentName
        - experimentItemId
    FeedbackTargetType:
      title: FeedbackTargetType
      type: string
      enum:
        - skill
        - mcp-tool
        - cli
        - docs
        - public-api
        - other
    SubmitFeedbackRequest:
      title: SubmitFeedbackRequest
      type: object
      properties:
        targetType:
          $ref: '#/components/schemas/FeedbackTargetType'
          description: Category of the thing the feedback is about.
        target:
          type: string
          description: >-
            The specific instance within targetType: the skill name, MCP tool
            name, CLI command, API endpoint path, or docs page path (e.g.
            'queryMetrics', '/docs/mcp'). An identifier, not a sentence. Must be
            between 1 and 200 characters.
        feedback:
          type: string
          description: >-
            Concise feedback text approved by the user. Must be between 1 and
            3000 characters.
        goal:
          type: string
          nullable: true
          description: >-
            Optional user-approved goal or use case they were trying to achieve.
            Must be between 1 and 1500 characters when provided. Do not include
            secrets, customer data, trace payloads, or broad unrelated context.
        referenceUrl:
          type: string
          nullable: true
          description: >-
            Optional HTTP(S) reference URL. Langfuse stores it as text for
            triage and does not fetch it.
      required:
        - targetType
        - target
        - feedback
    SubmitFeedbackResponse:
      title: SubmitFeedbackResponse
      type: object
      properties:
        id:
          type: string
          description: Correlation ID for the submitted feedback.
      required:
        - id
    HealthResponse:
      title: HealthResponse
      type: object
      properties:
        version:
          type: string
          description: Langfuse server version
        status:
          type: string
      required:
        - version
        - status
    LlmConnection:
      title: LlmConnection
      type: object
      description: LLM API connection configuration (secrets excluded)
      properties:
        id:
          type: string
        provider:
          type: string
          description: >-
            Provider name (e.g., 'openai', 'my-gateway'). Must be unique in
            project, used for upserting.
        adapter:
          type: string
          description: The adapter used to interface with the LLM
        displaySecretKey:
          type: string
          description: Masked version of the secret key for display purposes
        baseURL:
          type: string
          nullable: true
          description: Custom base URL for the LLM API
        customModels:
          type: array
          items:
            type: string
          description: List of custom model names available for this connection
        withDefaultModels:
          type: boolean
          description: Whether to include default models for this adapter
        extraHeaderKeys:
          type: array
          items:
            type: string
          description: >-
            Keys of extra headers sent with requests (values excluded for
            security)
        config:
          type: object
          additionalProperties: true
          nullable: true
          description: >-
            Adapter-specific configuration. Required for Bedrock
            (`{"region":"us-east-1"}`), optional for OpenAI
            (`{"useResponsesApi":true}`), optional for VertexAI
            (`{"location":"us-central1"}`), not used by other adapters.
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
      required:
        - id
        - provider
        - adapter
        - displaySecretKey
        - customModels
        - withDefaultModels
        - extraHeaderKeys
        - createdAt
        - updatedAt
    PaginatedLlmConnections:
      title: PaginatedLlmConnections
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/LlmConnection'
        meta:
          $ref: '#/components/schemas/utilsMetaResponse'
      required:
        - data
        - meta
    UpsertLlmConnectionRequest:
      title: UpsertLlmConnectionRequest
      type: object
      description: Request to create or update an LLM connection (upsert)
      properties:
        provider:
          type: string
          description: >-
            Provider name (e.g., 'openai', 'my-gateway'). Must be unique in
            project, used for upserting.
        adapter:
          $ref: '#/components/schemas/LlmAdapter'
          description: The adapter used to interface with the LLM
        secretKey:
          type: string
          description: Secret key for the LLM API.
        baseURL:
          type: string
          nullable: true
          description: Custom base URL for the LLM API
        customModels:
          type: array
          items:
            type: string
          nullable: true
          description: List of custom model names
        withDefaultModels:
          type: boolean
          nullable: true
          description: Whether to include default models. Default is true.
        extraHeaders:
          type: object
          additionalProperties:
            type: string
          nullable: true
          description: Extra headers to send with requests
        config:
          type: object
          additionalProperties: true
          nullable: true
          description: >-
            Adapter-specific configuration. Validation rules: - **Bedrock**:
            Required. Must be `{"region": "<aws-region>"}` (e.g.,
            `{"region":"us-east-1"}`) - **OpenAI**: Optional. If provided, must
            be `{"useResponsesApi": <boolean>}` to control whether Langfuse
            routes calls through OpenAI's Responses API. - **VertexAI**:
            Optional. If provided, must be `{"location": "<gcp-location>"}`
            (e.g., `{"location":"us-central1"}`) - **Other adapters**: Not
            supported. Omit this field or set to null.
      required:
        - provider
        - adapter
        - secretKey
    DeleteLlmConnectionResponse:
      title: DeleteLlmConnectionResponse
      type: object
      properties:
        message:
          type: string
      required:
        - message
    LlmAdapter:
      title: LlmAdapter
      type: string
      enum:
        - anthropic
        - openai
        - azure
        - bedrock
        - google-vertex-ai
        - google-ai-studio
    GetMediaResponse:
      title: GetMediaResponse
      type: object
      properties:
        mediaId:
          type: string
          description: The unique langfuse identifier of a media record
        contentType:
          type: string
          description: The MIME type of the media record
        contentLength:
          type: integer
          description: The size of the media record in bytes
        uploadedAt:
          type: string
          format: date-time
          description: The date and time when the media record was uploaded
        url:
          type: string
          description: The download URL of the media record
        urlExpiry:
          type: string
          description: The expiry date and time of the media record download URL
      required:
        - mediaId
        - contentType
        - contentLength
        - uploadedAt
        - url
        - urlExpiry
    PatchMediaBody:
      title: PatchMediaBody
      type: object
      properties:
        uploadedAt:
          type: string
          format: date-time
          description: The date and time when the media record was uploaded
        uploadHttpStatus:
          type: integer
          description: The HTTP status code of the upload
        uploadHttpError:
          type: string
          nullable: true
          description: The HTTP error message of the upload
        uploadTimeMs:
          type: integer
          nullable: true
          description: The time in milliseconds it took to upload the media record
      required:
        - uploadedAt
        - uploadHttpStatus
    GetMediaUploadUrlRequest:
      title: GetMediaUploadUrlRequest
      type: object
      description: >-
        Request a presigned media upload URL. Provide exactly one context: a
        trace (traceId, optionally observationId) or a dataset item (datasetId +
        datasetItemId). field is required and must match the chosen context.
      properties:
        traceId:
          type: string
          nullable: true
          description: >-
            The trace the media is associated with. Null for dataset item media
            uploads.
        observationId:
          type: string
          nullable: true
          description: >-
            The observation ID associated with the media record. If the media
            record is associated directly with a trace, this will be null.
        datasetId:
          type: string
          nullable: true
          description: >-
            The dataset the media belongs to. Null for trace/observation media
            uploads.
        datasetItemId:
          type: string
          nullable: true
          description: >-
            The dataset item the media is associated with (need not exist yet).
            Null for trace/observation media uploads.
        contentType:
          $ref: '#/components/schemas/MediaContentType'
        contentLength:
          type: integer
          description: The size of the media record in bytes
        sha256Hash:
          type: string
          description: The SHA-256 hash of the media record
        field:
          type: string
          description: >-
            The item field the media is in: `input`/`output`/`metadata` (trace)
            or `input`/`expectedOutput`/`metadata` (dataset item).
      required:
        - contentType
        - contentLength
        - sha256Hash
        - field
    GetMediaUploadUrlResponse:
      title: GetMediaUploadUrlResponse
      type: object
      properties:
        uploadUrl:
          type: string
          nullable: true
          description: >-
            The presigned upload URL. If the asset is already uploaded, this
            will be null
        mediaId:
          type: string
          description: The unique langfuse identifier of a media record
      required:
        - mediaId
    MediaContentType:
      title: MediaContentType
      type: string
      enum:
        - image/png
        - image/jpeg
        - image/jpg
        - image/webp
        - image/gif
        - image/svg+xml
        - image/tiff
        - image/bmp
        - image/avif
        - image/heic
        - audio/mpeg
        - audio/mp3
        - audio/wav
        - audio/ogg
        - audio/oga
        - audio/aac
        - audio/mp4
        - audio/flac
        - audio/opus
        - audio/webm
        - video/mp4
        - video/webm
        - video/ogg
        - video/mpeg
        - video/quicktime
        - video/x-msvideo
        - video/x-matroska
        - text/plain
        - text/html
        - text/css
        - text/csv
        - text/markdown
        - text/x-python
        - application/javascript
        - text/x-typescript
        - application/x-yaml
        - application/pdf
        - application/msword
        - application/vnd.ms-excel
        - application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
        - application/zip
        - application/json
        - application/xml
        - application/octet-stream
        - >-
          application/vnd.openxmlformats-officedocument.wordprocessingml.document
        - >-
          application/vnd.openxmlformats-officedocument.presentationml.presentation
        - application/rtf
        - application/x-ndjson
        - application/vnd.apache.parquet
        - application/gzip
        - application/x-tar
        - application/x-7z-compressed
      description: The MIME type of the media record
    MetricsV2Response:
      title: MetricsV2Response
      type: object
      properties:
        data:
          type: array
          items:
            type: object
            additionalProperties: true
          description: >-
            The metrics data. Each item in the list contains the metric values
            and dimensions requested in the query.

            Format varies based on the query parameters.

            Histograms will return an array with [lower, upper, height] tuples.
      required:
        - data
    ModelTokenizerId:
      title: ModelTokenizerId
      type: string
      enum:
        - openai
        - claude
      description: Tokenizer supported by Langfuse for model usage inference.
    PaginatedModels:
      title: PaginatedModels
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Model'
        meta:
          $ref: '#/components/schemas/utilsMetaResponse'
      required:
        - data
        - meta
    CreateModelRequest:
      title: CreateModelRequest
      type: object
      properties:
        modelName:
          type: string
          description: >-
            Name of the model definition. If multiple with the same name exist,
            they are applied in the following order: (1) custom over built-in,
            (2) newest according to startTime where
            model.startTime<observation.startTime
        matchPattern:
          type: string
          description: >-
            Regex pattern which matches this model definition to
            generation.model. Useful in case of fine-tuned models. If you want
            to exact match, use `(?i)^modelname$`
        startDate:
          type: string
          format: date-time
          nullable: true
          description: Apply only to generations which are newer than this ISO date.
        unit:
          $ref: '#/components/schemas/ModelUsageUnit'
          description: Unit used by this model.
        inputPrice:
          type: number
          format: double
          nullable: true
          description: >-
            Deprecated. Use 'pricingTiers' instead. Price (USD) per input unit.
            Creates a default tier if pricingTiers not provided.
        outputPrice:
          type: number
          format: double
          nullable: true
          description: >-
            Deprecated. Use 'pricingTiers' instead. Price (USD) per output unit.
            Creates a default tier if pricingTiers not provided.
        totalPrice:
          type: number
          format: double
          nullable: true
          description: >-
            Deprecated. Use 'pricingTiers' instead. Price (USD) per total units.
            Cannot be set if input or output price is set. Creates a default
            tier if pricingTiers not provided.
        pricingTiers:
          type: array
          items:
            $ref: '#/components/schemas/PricingTierInput'
          nullable: true
          description: >-
            Optional. Array of pricing tiers for this model.


            Use pricing tiers for all models - both those with threshold-based
            pricing variations and those with simple flat pricing:


            - For models with standard flat pricing: Create a single default
            tier with your prices
              (e.g., one tier with isDefault=true, priority=0, conditions=[], and your standard prices)

            - For models with threshold-based pricing: Create a default tier
            plus additional conditional tiers
              (e.g., default tier for standard usage + high-volume tier for usage above certain thresholds)

            Requirements:

            - Cannot be provided with flat prices
            (inputPrice/outputPrice/totalPrice) - use one approach or the other

            - Must include exactly one default tier with isDefault=true,
            priority=0, and conditions=[]

            - All tier names and priorities must be unique within the model

            - Each tier must define at least one price


            If omitted, you must provide flat prices instead
            (inputPrice/outputPrice/totalPrice),

            which will automatically create a single default tier named
            "Standard".
        tokenizerId:
          $ref: '#/components/schemas/ModelTokenizerId'
          nullable: true
          description: >-
            Optional. Tokenizer to be applied to observations which match to
            this model. See docs for more details.
        tokenizerConfig:
          nullable: true
          description: >-
            Optional. Configuration for the selected tokenizer. Needs to be
            JSON. See docs for more details.
      required:
        - modelName
        - matchPattern
        - unit
    ObservationsV2Response:
      title: ObservationsV2Response
      type: object
      description: >-
        Response containing observations with field-group-based filtering and
        cursor-based pagination.


        The `data` array contains observation objects with only the requested
        field groups included.

        Use the `cursor` in `meta` to retrieve the next page of results. The
        array may contain fewer

        than the requested `limit` items, or be empty, while a cursor is
        present. Continue until the

        cursor is absent.
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/ObservationV2'
          description: >-
            Array of observation objects. Fields included depend on the `fields`
            parameter in the request.
        meta:
          $ref: '#/components/schemas/ObservationsV2Meta'
      required:
        - data
        - meta
    ObservationsV2Meta:
      title: ObservationsV2Meta
      type: object
      description: Metadata for cursor-based pagination.
      properties:
        comment:
          type: string
          nullable: true
          description: >-
            Present when an empty page has a cursor; continue requesting pages
            until the cursor is absent.
      allOf:
        - $ref: '#/components/schemas/utilsCursorMetaResponse'
    OtelResourceSpan:
      title: OtelResourceSpan
      type: object
      description: >-
        Represents a collection of spans from a single resource as per OTLP
        specification
      properties:
        resource:
          $ref: '#/components/schemas/OtelResource'
          nullable: true
          description: Resource information
        scopeSpans:
          type: array
          items:
            $ref: '#/components/schemas/OtelScopeSpan'
          nullable: true
          description: Array of scope spans
    OtelResource:
      title: OtelResource
      type: object
      description: Resource attributes identifying the source of telemetry
      properties:
        attributes:
          type: array
          items:
            $ref: '#/components/schemas/OtelAttribute'
          nullable: true
          description: Resource attributes like service.name, service.version, etc.
    OtelScopeSpan:
      title: OtelScopeSpan
      type: object
      description: Collection of spans from a single instrumentation scope
      properties:
        scope:
          $ref: '#/components/schemas/OtelScope'
          nullable: true
          description: Instrumentation scope information
        spans:
          type: array
          items:
            $ref: '#/components/schemas/OtelSpan'
          nullable: true
          description: Array of spans
    OtelScope:
      title: OtelScope
      type: object
      description: Instrumentation scope information
      properties:
        name:
          type: string
          nullable: true
          description: Instrumentation scope name
        version:
          type: string
          nullable: true
          description: Instrumentation scope version
        attributes:
          type: array
          items:
            $ref: '#/components/schemas/OtelAttribute'
          nullable: true
          description: Additional scope attributes
    OtelSpan:
      title: OtelSpan
      type: object
      description: Individual span representing a unit of work or operation
      properties:
        traceId:
          nullable: true
          description: Trace ID (16 bytes, hex-encoded string in JSON or Buffer in binary)
        spanId:
          nullable: true
          description: Span ID (8 bytes, hex-encoded string in JSON or Buffer in binary)
        parentSpanId:
          nullable: true
          description: Parent span ID if this is a child span
        name:
          type: string
          nullable: true
          description: Span name describing the operation
        kind:
          type: integer
          nullable: true
          description: Span kind (1=INTERNAL, 2=SERVER, 3=CLIENT, 4=PRODUCER, 5=CONSUMER)
        startTimeUnixNano:
          nullable: true
          description: Start time in nanoseconds since Unix epoch
        endTimeUnixNano:
          nullable: true
          description: End time in nanoseconds since Unix epoch
        attributes:
          type: array
          items:
            $ref: '#/components/schemas/OtelAttribute'
          nullable: true
          description: >-
            Span attributes including Langfuse-specific attributes
            (langfuse.observation.*)
        status:
          nullable: true
          description: Span status object
    OtelAttribute:
      title: OtelAttribute
      type: object
      description: Key-value attribute pair for resources, scopes, or spans
      properties:
        key:
          type: string
          nullable: true
          description: Attribute key (e.g., "service.name", "langfuse.observation.type")
        value:
          $ref: '#/components/schemas/OtelAttributeValue'
          nullable: true
          description: Attribute value
    OtelAttributeValue:
      title: OtelAttributeValue
      type: object
      description: Attribute value wrapper supporting different value types
      properties:
        stringValue:
          type: string
          nullable: true
          description: String value
        intValue:
          type: integer
          nullable: true
          description: Integer value
        doubleValue:
          type: number
          format: double
          nullable: true
          description: Double value
        boolValue:
          type: boolean
          nullable: true
          description: Boolean value
    OtelTraceResponse:
      title: OtelTraceResponse
      type: object
      description: Response from trace export request. Empty object indicates success.
      properties: {}
    MembershipRole:
      title: MembershipRole
      type: string
      enum:
        - OWNER
        - ADMIN
        - MEMBER
        - VIEWER
    MembershipRequest:
      title: MembershipRequest
      type: object
      properties:
        userId:
          type: string
        role:
          $ref: '#/components/schemas/MembershipRole'
      required:
        - userId
        - role
    DeleteMembershipRequest:
      title: DeleteMembershipRequest
      type: object
      properties:
        userId:
          type: string
      required:
        - userId
    MembershipResponse:
      title: MembershipResponse
      type: object
      properties:
        userId:
          type: string
        role:
          $ref: '#/components/schemas/MembershipRole'
        email:
          type: string
        name:
          type: string
      required:
        - userId
        - role
        - email
        - name
    MembershipDeletionResponse:
      title: MembershipDeletionResponse
      type: object
      properties:
        message:
          type: string
        userId:
          type: string
      required:
        - message
        - userId
    MembershipsResponse:
      title: MembershipsResponse
      type: object
      properties:
        memberships:
          type: array
          items:
            $ref: '#/components/schemas/MembershipResponse'
      required:
        - memberships
    OrganizationProject:
      title: OrganizationProject
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        metadata:
          type: object
          additionalProperties: true
          nullable: true
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
      required:
        - id
        - name
        - createdAt
        - updatedAt
    OrganizationProjectsResponse:
      title: OrganizationProjectsResponse
      type: object
      properties:
        projects:
          type: array
          items:
            $ref: '#/components/schemas/OrganizationProject'
      required:
        - projects
    OrganizationApiKey:
      title: OrganizationApiKey
      type: object
      properties:
        id:
          type: string
        createdAt:
          type: string
          format: date-time
        expiresAt:
          type: string
          format: date-time
          nullable: true
          description: Expiration timestamp. Null if the key does not expire.
        lastUsedAt:
          type: string
          format: date-time
          nullable: true
        name:
          type: string
          nullable: true
          description: >-
            Name of the API key. Contains the same value as note; null if no
            name was provided.
        note:
          type: string
          nullable: true
          description: Deprecated alias for name. Contains the same value as name.
          deprecated: true
        publicKey:
          type: string
        displaySecretKey:
          type: string
      required:
        - id
        - createdAt
        - publicKey
        - displaySecretKey
    OrganizationApiKeysResponse:
      title: OrganizationApiKeysResponse
      type: object
      properties:
        apiKeys:
          type: array
          items:
            $ref: '#/components/schemas/OrganizationApiKey'
      required:
        - apiKeys
    Projects:
      title: Projects
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Project'
      required:
        - data
    Organization:
      title: Organization
      type: object
      properties:
        id:
          type: string
          description: The unique identifier of the organization
        name:
          type: string
          description: The name of the organization
      required:
        - id
        - name
    Project:
      title: Project
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        organization:
          $ref: '#/components/schemas/Organization'
          description: The organization this project belongs to
        metadata:
          type: object
          additionalProperties: true
          description: Metadata for the project
        retentionDays:
          type: integer
          nullable: true
          description: >-
            Number of days to retain data. Null or 0 means no retention. Omitted
            if no retention is configured.
      required:
        - id
        - name
        - organization
        - metadata
    ProjectDeletionResponse:
      title: ProjectDeletionResponse
      type: object
      properties:
        success:
          type: boolean
        message:
          type: string
      required:
        - success
        - message
    ApiKeyList:
      title: ApiKeyList
      type: object
      description: List of API keys for a project
      properties:
        apiKeys:
          type: array
          items:
            $ref: '#/components/schemas/ApiKeySummary'
      required:
        - apiKeys
    ApiKeySummary:
      title: ApiKeySummary
      type: object
      description: Summary of an API key
      properties:
        id:
          type: string
        createdAt:
          type: string
          format: date-time
        expiresAt:
          type: string
          format: date-time
          nullable: true
          description: Expiration timestamp. Null if the key does not expire.
        lastUsedAt:
          type: string
          format: date-time
          nullable: true
        name:
          type: string
          nullable: true
          description: >-
            Name of the API key. Contains the same value as note; null if no
            name was provided.
        note:
          type: string
          nullable: true
          description: Deprecated alias for name. Contains the same value as name.
          deprecated: true
        publicKey:
          type: string
        displaySecretKey:
          type: string
      required:
        - id
        - createdAt
        - publicKey
        - displaySecretKey
    ApiKeyResponse:
      title: ApiKeyResponse
      type: object
      description: Response for API key creation
      properties:
        id:
          type: string
        createdAt:
          type: string
          format: date-time
        expiresAt:
          type: string
          format: date-time
          nullable: true
          description: Expiration timestamp. Null if the key does not expire.
        publicKey:
          type: string
        secretKey:
          type: string
        displaySecretKey:
          type: string
        name:
          type: string
          nullable: true
          description: >-
            Name of the API key. Contains the same value as note; null if no
            name was provided.
        note:
          type: string
          nullable: true
          description: Deprecated alias for name. Contains the same value as name.
          deprecated: true
      required:
        - id
        - createdAt
        - publicKey
        - secretKey
        - displaySecretKey
    ApiKeyDeletionResponse:
      title: ApiKeyDeletionResponse
      type: object
      description: Response for API key deletion
      properties:
        success:
          type: boolean
      required:
        - success
    PromptMetaListResponse:
      title: PromptMetaListResponse
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/PromptMeta'
        meta:
          $ref: '#/components/schemas/utilsMetaResponse'
      required:
        - data
        - meta
    PromptMeta:
      title: PromptMeta
      type: object
      properties:
        name:
          type: string
        type:
          $ref: '#/components/schemas/PromptType'
          description: Indicates whether the prompt is a text or chat prompt.
        versions:
          type: array
          items:
            type: integer
        labels:
          type: array
          items:
            type: string
        tags:
          type: array
          items:
            type: string
        lastUpdatedAt:
          type: string
          format: date-time
        lastConfig:
          description: >-
            Config object of the most recent prompt version that matches the
            filters (if any are provided)
      required:
        - name
        - type
        - versions
        - labels
        - tags
        - lastUpdatedAt
        - lastConfig
    CreatePromptRequest:
      title: CreatePromptRequest
      oneOf:
        - $ref: '#/components/schemas/CreateChatPromptRequest'
        - $ref: '#/components/schemas/CreateTextPromptRequest'
    CreateChatPromptRequest:
      title: CreateChatPromptRequest
      type: object
      properties:
        name:
          type: string
          description: >-
            The full prompt name, including any folder path, with at most 255
            characters.
        prompt:
          type: array
          items:
            $ref: '#/components/schemas/ChatMessageWithPlaceholders'
        config:
          nullable: true
        type:
          $ref: '#/components/schemas/CreateChatPromptType'
        labels:
          type: array
          items:
            type: string
          nullable: true
          description: List of deployment labels of this prompt version.
        tags:
          type: array
          items:
            type: string
          nullable: true
          description: List of tags to apply to all versions of this prompt.
        commitMessage:
          type: string
          nullable: true
          description: Commit message for this prompt version.
      required:
        - name
        - prompt
        - type
    CreateTextPromptRequest:
      title: CreateTextPromptRequest
      type: object
      properties:
        name:
          type: string
          description: >-
            The full prompt name, including any folder path, with at most 255
            characters.
        prompt:
          type: string
        config:
          nullable: true
        type:
          $ref: '#/components/schemas/CreateTextPromptType'
          nullable: true
        labels:
          type: array
          items:
            type: string
          nullable: true
          description: List of deployment labels of this prompt version.
        tags:
          type: array
          items:
            type: string
          nullable: true
          description: List of tags to apply to all versions of this prompt.
        commitMessage:
          type: string
          nullable: true
          description: Commit message for this prompt version.
      required:
        - name
        - prompt
    Prompt:
      title: Prompt
      oneOf:
        - type: object
          allOf:
            - type: object
              properties:
                type:
                  type: string
                  enum:
                    - chat
            - $ref: '#/components/schemas/ChatPrompt'
          required:
            - type
          title: ChatPrompt
        - type: object
          allOf:
            - type: object
              properties:
                type:
                  type: string
                  enum:
                    - text
            - $ref: '#/components/schemas/TextPrompt'
          required:
            - type
          title: TextPrompt
    PromptType:
      title: PromptType
      type: string
      enum:
        - chat
        - text
    BasePrompt:
      title: BasePrompt
      type: object
      properties:
        name:
          type: string
        version:
          type: integer
        config: {}
        labels:
          type: array
          items:
            type: string
          description: List of deployment labels of this prompt version.
        tags:
          type: array
          items:
            type: string
          description: >-
            List of tags. Used to filter via UI and API. The same across
            versions of a prompt.
        commitMessage:
          type: string
          nullable: true
          description: Commit message for this prompt version.
        resolutionGraph:
          type: object
          additionalProperties: true
          nullable: true
          description: >-
            The dependency resolution graph for the current prompt. Null if the
            prompt has no dependencies or if `resolve=false` was used.
      required:
        - name
        - version
        - config
        - labels
        - tags
    ChatMessageWithPlaceholders:
      title: ChatMessageWithPlaceholders
      oneOf:
        - $ref: '#/components/schemas/ChatMessage'
        - $ref: '#/components/schemas/PlaceholderMessage'
    ChatMessage:
      title: ChatMessage
      type: object
      properties:
        role:
          type: string
        content:
          type: string
        type:
          $ref: '#/components/schemas/ChatMessageType'
          nullable: true
      required:
        - role
        - content
    ChatMessageType:
      title: ChatMessageType
      type: string
      enum:
        - chatmessage
    PlaceholderMessage:
      title: PlaceholderMessage
      type: object
      properties:
        name:
          type: string
        type:
          $ref: '#/components/schemas/PlaceholderMessageType'
          nullable: true
      required:
        - name
    PlaceholderMessageType:
      title: PlaceholderMessageType
      type: string
      enum:
        - placeholder
    TextPrompt:
      title: TextPrompt
      type: object
      properties:
        prompt:
          type: string
      required:
        - prompt
      allOf:
        - $ref: '#/components/schemas/BasePrompt'
    ChatPrompt:
      title: ChatPrompt
      type: object
      properties:
        prompt:
          type: array
          items:
            $ref: '#/components/schemas/ChatMessageWithPlaceholders'
      required:
        - prompt
      allOf:
        - $ref: '#/components/schemas/BasePrompt'
    CreateChatPromptType:
      title: CreateChatPromptType
      type: string
      enum:
        - chat
    CreateTextPromptType:
      title: CreateTextPromptType
      type: string
      enum:
        - text
    ServiceProviderConfig:
      title: ServiceProviderConfig
      type: object
      properties:
        schemas:
          type: array
          items:
            type: string
        documentationUri:
          type: string
        patch:
          $ref: '#/components/schemas/ScimFeatureSupport'
        bulk:
          $ref: '#/components/schemas/BulkConfig'
        filter:
          $ref: '#/components/schemas/FilterConfig'
        changePassword:
          $ref: '#/components/schemas/ScimFeatureSupport'
        sort:
          $ref: '#/components/schemas/ScimFeatureSupport'
        etag:
          $ref: '#/components/schemas/ScimFeatureSupport'
        authenticationSchemes:
          type: array
          items:
            $ref: '#/components/schemas/AuthenticationScheme'
        meta:
          $ref: '#/components/schemas/ResourceMeta'
      required:
        - schemas
        - documentationUri
        - patch
        - bulk
        - filter
        - changePassword
        - sort
        - etag
        - authenticationSchemes
        - meta
    ScimFeatureSupport:
      title: ScimFeatureSupport
      type: object
      properties:
        supported:
          type: boolean
      required:
        - supported
    BulkConfig:
      title: BulkConfig
      type: object
      properties:
        supported:
          type: boolean
        maxOperations:
          type: integer
        maxPayloadSize:
          type: integer
      required:
        - supported
        - maxOperations
        - maxPayloadSize
    FilterConfig:
      title: FilterConfig
      type: object
      properties:
        supported:
          type: boolean
        maxResults:
          type: integer
      required:
        - supported
        - maxResults
    ResourceMeta:
      title: ResourceMeta
      type: object
      properties:
        resourceType:
          type: string
        location:
          type: string
      required:
        - resourceType
        - location
    AuthenticationScheme:
      title: AuthenticationScheme
      type: object
      properties:
        name:
          type: string
        description:
          type: string
        specUri:
          type: string
        type:
          type: string
        primary:
          type: boolean
      required:
        - name
        - description
        - specUri
        - type
        - primary
    ResourceTypesResponse:
      title: ResourceTypesResponse
      type: object
      properties:
        schemas:
          type: array
          items:
            type: string
        totalResults:
          type: integer
        Resources:
          type: array
          items:
            $ref: '#/components/schemas/ResourceType'
      required:
        - schemas
        - totalResults
        - Resources
    ResourceType:
      title: ResourceType
      type: object
      properties:
        schemas:
          type: array
          items:
            type: string
          nullable: true
        id:
          type: string
        name:
          type: string
        endpoint:
          type: string
        description:
          type: string
        schema:
          type: string
        schemaExtensions:
          type: array
          items:
            $ref: '#/components/schemas/SchemaExtension'
        meta:
          $ref: '#/components/schemas/ResourceMeta'
      required:
        - id
        - name
        - endpoint
        - description
        - schema
        - schemaExtensions
        - meta
    SchemaExtension:
      title: SchemaExtension
      type: object
      properties:
        schema:
          type: string
        required:
          type: boolean
      required:
        - schema
        - required
    SchemasResponse:
      title: SchemasResponse
      type: object
      properties:
        schemas:
          type: array
          items:
            type: string
        totalResults:
          type: integer
        Resources:
          type: array
          items:
            $ref: '#/components/schemas/SchemaResource'
      required:
        - schemas
        - totalResults
        - Resources
    SchemaResource:
      title: SchemaResource
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        description:
          type: string
        attributes:
          type: array
          items: {}
        meta:
          $ref: '#/components/schemas/ResourceMeta'
      required:
        - id
        - name
        - description
        - attributes
        - meta
    ScimUsersListResponse:
      title: ScimUsersListResponse
      type: object
      properties:
        schemas:
          type: array
          items:
            type: string
        totalResults:
          type: integer
        startIndex:
          type: integer
        itemsPerPage:
          type: integer
        Resources:
          type: array
          items:
            $ref: '#/components/schemas/ScimUser'
      required:
        - schemas
        - totalResults
        - startIndex
        - itemsPerPage
        - Resources
    ScimUser:
      title: ScimUser
      type: object
      properties:
        schemas:
          type: array
          items:
            type: string
        id:
          type: string
        userName:
          type: string
        name:
          $ref: '#/components/schemas/ScimName'
        emails:
          type: array
          items:
            $ref: '#/components/schemas/ScimEmail'
        meta:
          $ref: '#/components/schemas/UserMeta'
      required:
        - schemas
        - id
        - userName
        - name
        - emails
        - meta
    UserMeta:
      title: UserMeta
      type: object
      properties:
        resourceType:
          type: string
        created:
          type: string
          nullable: true
        lastModified:
          type: string
          nullable: true
      required:
        - resourceType
    ScimName:
      title: ScimName
      type: object
      properties:
        formatted:
          type: string
          nullable: true
    ScimEmail:
      title: ScimEmail
      type: object
      properties:
        primary:
          type: boolean
        value:
          type: string
        type:
          type: string
      required:
        - primary
        - value
        - type
    EmptyResponse:
      title: EmptyResponse
      type: object
      description: Empty response for 204 No Content responses
      properties: {}
    ScoreConfigs:
      title: ScoreConfigs
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/ScoreConfig'
        meta:
          $ref: '#/components/schemas/utilsMetaResponse'
      required:
        - data
        - meta
    CreateScoreConfigRequest:
      title: CreateScoreConfigRequest
      type: object
      properties:
        name:
          type: string
          description: >-
            Name of the score config. Max 80 characters. Only letters, numbers,
            underscores, spaces, periods, parentheses, and hyphens are allowed.
        dataType:
          $ref: '#/components/schemas/ScoreConfigDataType'
        categories:
          type: array
          items:
            $ref: '#/components/schemas/ConfigCategory'
          nullable: true
          description: >-
            Configure custom categories for categorical scores. Pass a list of
            objects with `label` and `value` properties. Categories are
            autogenerated for boolean configs and cannot be passed
        minValue:
          type: number
          format: double
          nullable: true
          description: >-
            Configure a minimum value for numerical scores. If not set, the
            minimum value defaults to -∞
        maxValue:
          type: number
          format: double
          nullable: true
          description: >-
            Configure a maximum value for numerical scores. If not set, the
            maximum value defaults to +∞
        description:
          type: string
          nullable: true
          description: >-
            Description is shown across the Langfuse UI and can be used to e.g.
            explain the config categories in detail, why a numeric range was
            set, or provide additional context on config name or usage
      required:
        - name
        - dataType
    UpdateScoreConfigRequest:
      title: UpdateScoreConfigRequest
      type: object
      properties:
        isArchived:
          type: boolean
          nullable: true
          description: The status of the score config showing if it is archived or not
        name:
          type: string
          nullable: true
          description: >-
            Name of the score config. Max 80 characters. Only letters, numbers,
            underscores, spaces, periods, parentheses, and hyphens are allowed.
        categories:
          type: array
          items:
            $ref: '#/components/schemas/ConfigCategory'
          nullable: true
          description: >-
            Configure custom categories for categorical scores. Pass a list of
            objects with `label` and `value` properties. Categories are
            autogenerated for boolean configs and cannot be passed
        minValue:
          type: number
          format: double
          nullable: true
          description: >-
            Configure a minimum value for numerical scores. If not set, the
            minimum value defaults to -∞
        maxValue:
          type: number
          format: double
          nullable: true
          description: >-
            Configure a maximum value for numerical scores. If not set, the
            maximum value defaults to +∞
        description:
          type: string
          nullable: true
          description: >-
            Description is shown across the Langfuse UI and can be used to e.g.
            explain the config categories in detail, why a numeric range was
            set, or provide additional context on config name or usage
    CreateScoresRequest:
      title: CreateScoresRequest
      type: array
      items:
        $ref: '#/components/schemas/CreateScoreRequest'
    CreateScoreRequest:
      title: CreateScoreRequest
      type: object
      properties:
        id:
          type: string
          nullable: true
        traceId:
          type: string
          nullable: true
        sessionId:
          type: string
          nullable: true
        observationId:
          type: string
          nullable: true
        datasetRunId:
          type: string
          nullable: true
        name:
          type: string
        value:
          $ref: '#/components/schemas/CreateScoreValue'
          description: >-
            The value of the score. Must be passed as string for categorical and
            text scores, and numeric for boolean and numeric scores. Boolean
            score values must equal either 1 or 0 (true or false). Text score
            values must be between 1 and 500 characters.
        comment:
          type: string
          nullable: true
        metadata:
          type: object
          additionalProperties: true
          nullable: true
        environment:
          type: string
          nullable: true
          description: >-
            The environment of the score. Can be any lowercase alphanumeric
            string with hyphens and underscores that does not start with
            'langfuse'.
        queueId:
          type: string
          nullable: true
          description: >-
            The annotation queue referenced by the score. Indicates if score was
            initially created while processing annotation queue.
        dataType:
          $ref: '#/components/schemas/ScoreDataType'
          nullable: true
          description: >-
            The data type of the score. When passing a configId this field is
            inferred. Otherwise, this field must be passed or will default to
            numeric.
        configId:
          type: string
          nullable: true
          description: >-
            Reference a score config on a score. The unique langfuse identifier
            of a score config. When passing this field, the dataType and
            stringValue fields are automatically populated.
        source:
          $ref: '#/components/schemas/CreateScoreSource'
          nullable: true
          description: >-
            The source of the score. Defaults to API. Set to ANNOTATION to
            prefill scores (e.g. from an LLM) for a human reviewer to verify in
            an annotation queue. When source is ANNOTATION, a configId is
            required unless dataType is CORRECTION. EVAL is reserved for
            internal evaluator outputs and is not accepted on this endpoint.
        timestamp:
          type: string
          format: date-time
          nullable: true
          description: >-
            The timestamp of the score, as an ISO 8601 datetime with a timezone
            offset. Defaults to the time the request is received. To update an
            existing score, send it again with the same id and timestamp.
      required:
        - name
        - value
    CreateScoreSource:
      title: CreateScoreSource
      type: string
      enum:
        - API
        - ANNOTATION
      description: |-
        Source values accepted when creating a score via the public REST API.
        EVAL is reserved for internal evaluator outputs and is intentionally not
        exposed here — use commons.ScoreSource when reading scores.
    CreateScoresResponse:
      title: CreateScoresResponse
      oneOf:
        - $ref: '#/components/schemas/CreateScoreBatchResults'
        - $ref: '#/components/schemas/CreateScoreBatchResponse'
    CreateScoreBatchResponse:
      title: CreateScoreBatchResponse
      type: object
      description: Batch accepted (HTTP 202).
      properties:
        message:
          type: string
          const: Accepted
      required:
        - message
    CreateScoreBatchResults:
      title: CreateScoreBatchResults
      type: object
      description: Acceptance counts and errors (HTTP 207).
      properties:
        accepted:
          type: integer
        rejected:
          type: integer
        errors:
          type: array
          items:
            $ref: '#/components/schemas/CreateScoreBatchError'
      required:
        - accepted
        - rejected
        - errors
    CreateScoreBatchError:
      title: CreateScoreBatchError
      type: object
      properties:
        message:
          type: string
      required:
        - message
    ScoreSubjectTraceV3:
      title: ScoreSubjectTraceV3
      type: object
      properties:
        id:
          type: string
          description: The trace ID.
      required:
        - id
    ScoreSubjectObservationV3:
      title: ScoreSubjectObservationV3
      type: object
      properties:
        id:
          type: string
          description: The observation ID.
        traceId:
          type: string
          nullable: true
          description: The parent trace ID, if available.
      required:
        - id
    ScoreSubjectSessionV3:
      title: ScoreSubjectSessionV3
      type: object
      properties:
        id:
          type: string
          description: The session ID.
      required:
        - id
    ScoreSubjectExperimentV3:
      title: ScoreSubjectExperimentV3
      type: object
      properties:
        id:
          type: string
          description: The dataset run ID (experiment ID).
      required:
        - id
    ScoreSubjectV3:
      title: ScoreSubjectV3
      oneOf:
        - type: object
          allOf:
            - type: object
              properties:
                kind:
                  type: string
                  enum:
                    - trace
            - $ref: '#/components/schemas/ScoreSubjectTraceV3'
          required:
            - kind
          title: ScoreSubjectTraceV3
        - type: object
          allOf:
            - type: object
              properties:
                kind:
                  type: string
                  enum:
                    - observation
            - $ref: '#/components/schemas/ScoreSubjectObservationV3'
          required:
            - kind
          title: ScoreSubjectObservationV3
        - type: object
          allOf:
            - type: object
              properties:
                kind:
                  type: string
                  enum:
                    - session
            - $ref: '#/components/schemas/ScoreSubjectSessionV3'
          required:
            - kind
          title: ScoreSubjectSessionV3
        - type: object
          allOf:
            - type: object
              properties:
                kind:
                  type: string
                  enum:
                    - experiment
            - $ref: '#/components/schemas/ScoreSubjectExperimentV3'
          required:
            - kind
          title: ScoreSubjectExperimentV3
      description: >-
        A reference to the entity this score is attached to. Discriminated by
        "kind" — one of trace, observation, session, or experiment.
    BaseScoreV3:
      title: BaseScoreV3
      type: object
      properties:
        id:
          type: string
        projectId:
          type: string
        name:
          type: string
        source:
          $ref: '#/components/schemas/ScoreSource'
        timestamp:
          type: string
          format: date-time
        environment:
          type: string
          description: The environment from which this score originated.
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
        comment:
          type: string
          nullable: true
          description: >-
            Optional comment attached to the score. Present when "details" is
            included in the fields parameter.
        configId:
          type: string
          nullable: true
          description: >-
            The score config ID, if this score was created from a config.
            Present when "details" is included in the fields parameter.
        metadata:
          type: object
          additionalProperties: true
          nullable: true
          description: >-
            Arbitrary metadata attached to the score. Present when "details" is
            included in the fields parameter.
        authorUserId:
          type: string
          nullable: true
          description: >-
            The user who created this score, if available. Present when
            "annotation" is included in the fields parameter.
        queueId:
          type: string
          nullable: true
          description: >-
            The annotation queue this score belongs to, if any. Present when
            "annotation" is included in the fields parameter.
        subject:
          $ref: '#/components/schemas/ScoreSubjectV3'
          nullable: true
          description: >-
            The entity this score is attached to (trace, observation, session,
            or experiment). Present when "subject" is included in the fields
            parameter.
      required:
        - id
        - projectId
        - name
        - source
        - timestamp
        - environment
        - createdAt
        - updatedAt
    NumericScoreV3:
      title: NumericScoreV3
      type: object
      properties:
        value:
          type: number
          format: double
          description: The numeric value of the score.
      required:
        - value
      allOf:
        - $ref: '#/components/schemas/BaseScoreV3'
    BooleanScoreV3:
      title: BooleanScoreV3
      type: object
      properties:
        value:
          type: boolean
          description: The boolean value of the score.
      required:
        - value
      allOf:
        - $ref: '#/components/schemas/BaseScoreV3'
    CategoricalScoreV3:
      title: CategoricalScoreV3
      type: object
      properties:
        value:
          type: string
          description: The string category value of the score.
      required:
        - value
      allOf:
        - $ref: '#/components/schemas/BaseScoreV3'
    TextScoreV3:
      title: TextScoreV3
      type: object
      properties:
        value:
          type: string
          description: The text content of the score.
      required:
        - value
      allOf:
        - $ref: '#/components/schemas/BaseScoreV3'
    CorrectionScoreV3:
      title: CorrectionScoreV3
      type: object
      properties:
        value:
          type: string
          description: The correction content of the score. Empty string if not set.
      required:
        - value
      allOf:
        - $ref: '#/components/schemas/BaseScoreV3'
    ScoreV3:
      title: ScoreV3
      oneOf:
        - type: object
          allOf:
            - type: object
              properties:
                dataType:
                  type: string
                  enum:
                    - NUMERIC
            - $ref: '#/components/schemas/NumericScoreV3'
          required:
            - dataType
          title: NumericScoreV3
        - type: object
          allOf:
            - type: object
              properties:
                dataType:
                  type: string
                  enum:
                    - BOOLEAN
            - $ref: '#/components/schemas/BooleanScoreV3'
          required:
            - dataType
          title: BooleanScoreV3
        - type: object
          allOf:
            - type: object
              properties:
                dataType:
                  type: string
                  enum:
                    - CATEGORICAL
            - $ref: '#/components/schemas/CategoricalScoreV3'
          required:
            - dataType
          title: CategoricalScoreV3
        - type: object
          allOf:
            - type: object
              properties:
                dataType:
                  type: string
                  enum:
                    - TEXT
            - $ref: '#/components/schemas/TextScoreV3'
          required:
            - dataType
          title: TextScoreV3
        - type: object
          allOf:
            - type: object
              properties:
                dataType:
                  type: string
                  enum:
                    - CORRECTION
            - $ref: '#/components/schemas/CorrectionScoreV3'
          required:
            - dataType
          title: CorrectionScoreV3
    GetScoresV3Meta:
      title: GetScoresV3Meta
      type: object
      properties:
        limit:
          type: integer
      required:
        - limit
      allOf:
        - $ref: '#/components/schemas/utilsCursorMetaResponse'
    GetScoresV3Response:
      title: GetScoresV3Response
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/ScoreV3'
        meta:
          $ref: '#/components/schemas/GetScoresV3Meta'
      required:
        - data
        - meta
    ScoreBody:
      title: ScoreBody
      type: object
      properties:
        id:
          type: string
          nullable: true
        traceId:
          type: string
          nullable: true
        sessionId:
          type: string
          nullable: true
        observationId:
          type: string
          nullable: true
        datasetRunId:
          type: string
          nullable: true
        name:
          type: string
          description: >-
            The name of the score. Always overrides "output" for correction
            scores.
        environment:
          type: string
          nullable: true
        queueId:
          type: string
          nullable: true
          description: >-
            The annotation queue referenced by the score. Indicates if score was
            initially created while processing annotation queue.
        value:
          $ref: '#/components/schemas/CreateScoreValue'
          description: >-
            The value of the score. Must be passed as string for categorical and
            text scores, and numeric for boolean and numeric scores. Boolean
            score values must equal either 1 or 0 (true or false). Text score
            values must be between 1 and 500 characters.
        comment:
          type: string
          nullable: true
        metadata:
          nullable: true
        dataType:
          $ref: '#/components/schemas/ScoreDataType'
          nullable: true
          description: >-
            When set, must match the score value's type. If not set, will be
            inferred from the score value or config
        configId:
          type: string
          nullable: true
          description: >-
            Reference a score config on a score. When set, the score name must
            equal the config name and scores must comply with the config's range
            and data type. For categorical scores, the value must map to a
            config category. Numeric scores might be constrained by the score
            config's max and min values
      required:
        - name
        - value
    SkillMetaListResponse:
      title: SkillMetaListResponse
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/SkillMeta'
        meta:
          $ref: '#/components/schemas/SkillListPagination'
      required:
        - data
        - meta
    SkillListPagination:
      title: SkillListPagination
      type: object
      properties:
        hasNextPage:
          type: boolean
      required:
        - hasNextPage
      allOf:
        - $ref: '#/components/schemas/utilsMetaResponse'
    SkillMeta:
      title: SkillMeta
      type: object
      properties:
        name:
          type: string
        description:
          type: string
        tags:
          type: array
          items:
            type: string
        latestVersion:
          type: integer
        latestVersionCreatedAt:
          type: string
          format: date-time
        latestVersionLastUpdatedAt:
          type: string
          format: date-time
        productionVersion:
          type: integer
          nullable: true
          description: >-
            Version assigned the production label, or null when no version is
            assigned.
      required:
        - name
        - description
        - tags
        - latestVersion
        - latestVersionCreatedAt
        - latestVersionLastUpdatedAt
        - productionVersion
    SkillVersionFileInput:
      title: SkillVersionFileInput
      type: object
      properties:
        path:
          type: string
        content:
          type: string
          description: UTF-8 text content. The server computes the hash and byte length.
      required:
        - path
        - content
    SkillVersionFileReference:
      title: SkillVersionFileReference
      type: object
      properties:
        path:
          type: string
        sha256Hash:
          type: string
          description: >-
            Canonical base64-encoded SHA-256 from a skill file manifest. The
            content must already exist in this project.
      required:
        - path
        - sha256Hash
    SkillVersionFileCreateInput:
      title: SkillVersionFileCreateInput
      oneOf:
        - $ref: '#/components/schemas/SkillVersionFileInput'
        - $ref: '#/components/schemas/SkillVersionFileReference'
      description: Provide exactly one of content or sha256Hash for each path.
    CreateSkillVersionRequest:
      title: CreateSkillVersionRequest
      type: object
      properties:
        files:
          type: array
          items:
            $ref: '#/components/schemas/SkillVersionFileCreateInput'
        commitMessage:
          type: string
          nullable: true
      required:
        - files
    SkillFile:
      title: SkillFile
      type: object
      properties:
        id:
          type: string
        path:
          type: string
        blobId:
          type: string
        sha256Hash:
          type: string
        contentType:
          type: string
        contentLength:
          type: integer
          format: int64
        content:
          type: string
          nullable: true
          description: >-
            UTF-8 text content, included when fetching a skill with
            includeContent enabled.
      required:
        - id
        - path
        - blobId
        - sha256Hash
        - contentType
        - contentLength
    SkillFileContentsResponse:
      title: SkillFileContentsResponse
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/SkillFileContent'
      required:
        - data
    SkillFileContent:
      title: SkillFileContent
      type: object
      properties:
        sha256Hash:
          type: string
        content:
          type: string
      required:
        - sha256Hash
        - content
    SkillVersion:
      title: SkillVersion
      type: object
      properties:
        id:
          type: string
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
        projectId:
          type: string
        createdBy:
          type: string
        name:
          type: string
        description:
          type: string
        frontmatter: {}
        version:
          type: integer
        tags:
          type: array
          items:
            type: string
        labels:
          type: array
          items:
            type: string
        commitMessage:
          type: string
          nullable: true
        files:
          type: array
          items:
            $ref: '#/components/schemas/SkillFile'
      required:
        - id
        - createdAt
        - updatedAt
        - projectId
        - createdBy
        - name
        - description
        - frontmatter
        - version
        - tags
        - labels
        - commitMessage
        - files
    UpdateSkillRequest:
      title: UpdateSkillRequest
      type: object
      properties:
        tags:
          type: array
          items:
            type: string
          description: >-
            The complete set of tags to apply to every version of the skill.
            Pass an empty list to clear all tags.
      required:
        - tags
    UpdateSkillLabelsRequest:
      title: UpdateSkillLabelsRequest
      type: object
      properties:
        labels:
          type: array
          items:
            type: string
      required:
        - labels
    DeleteSkillVersionResponse:
      title: DeleteSkillVersionResponse
      type: object
      properties:
        deleted:
          type: boolean
      required:
        - deleted
    DeleteTraceResponse:
      title: DeleteTraceResponse
      type: object
      properties:
        message:
          type: string
      required:
        - message
    unstableDashboardWidgetView:
      title: unstableDashboardWidgetView
      type: string
      enum:
        - observations
        - scores-numeric
        - scores-boolean
        - scores-categorical
    unstableDashboardWidgetViewWithLegacy:
      title: unstableDashboardWidgetViewWithLegacy
      type: string
      enum:
        - observations
        - scores-numeric
        - scores-boolean
        - scores-categorical
        - traces
      description: |-
        Widget data view. Responses may include the legacy `traces` value for
        widgets created before this API existed.
    unstableDashboardWidgetChartType:
      title: unstableDashboardWidgetChartType
      type: string
      enum:
        - LINE_TIME_SERIES
        - AREA_TIME_SERIES
        - BAR_TIME_SERIES
        - HORIZONTAL_BAR
        - VERTICAL_BAR
        - PIE
        - NUMBER
        - HISTOGRAM
        - PIVOT_TABLE
    unstableDashboardWidgetMetricAggregation:
      title: unstableDashboardWidgetMetricAggregation
      type: string
      enum:
        - sum
        - avg
        - count
        - max
        - min
        - p50
        - p75
        - p90
        - p95
        - p99
        - histogram
        - uniq
    unstableDashboardWidgetDimension:
      title: unstableDashboardWidgetDimension
      type: object
      properties:
        field:
          type: string
      required:
        - field
    unstableDashboardWidgetMetric:
      title: unstableDashboardWidgetMetric
      type: object
      properties:
        measure:
          type: string
        agg:
          $ref: '#/components/schemas/unstableDashboardWidgetMetricAggregation'
      required:
        - measure
        - agg
    unstableDashboardWidgetFilter:
      title: unstableDashboardWidgetFilter
      type: object
      description: >-
        A filter in Langfuse filter-state shape. The `value` shape and the

        allowed operators depend on `type`:


        | `type` | `value` | operators |

        |---|---|---|

        | `string` | string | `=`, `contains`, `does not contain`, `starts
        with`, `ends with` |

        | `number` | number | `=`, `>`, `<`, `>=`, `<=` |

        | `datetime` | ISO datetime string | `>`, `<`, `>=`, `<=` |

        | `boolean` | boolean | `=`, `<>` |

        | `null` | `""` | `is null`, `is not null` |

        | `stringOptions` | list of strings | `any of`, `none of` |

        | `arrayOptions` | list of strings | `any of`, `none of`, `all of` |

        | `categoryOptions` | list of strings (requires `key`) | `any of`, `none
        of` |

        | `stringObject` | string (requires `key`, e.g. a metadata key) | same
        as `string` |

        | `numberObject` | number (requires `key`, e.g. a score name) | same as
        `number` |

        | `booleanObject` | boolean (requires `key`) | `=`, `<>` |
      properties:
        column:
          type: string
        operator:
          type: string
        type:
          type: string
        value:
          nullable: true
        key:
          type: string
          nullable: true
      required:
        - column
        - operator
        - type
    unstableDashboardWidgetChartConfig:
      title: unstableDashboardWidgetChartConfig
      type: object
      description: |-
        Chart-specific widget configuration.

        `type` must match the top-level `chartType`.
        `row_limit` applies to total-value charts and pivot tables.
        `bins` applies to histograms.
        `defaultSort` applies to pivot tables.
      properties:
        type:
          $ref: '#/components/schemas/unstableDashboardWidgetChartType'
        row_limit:
          type: integer
          nullable: true
        show_value_labels:
          type: boolean
          nullable: true
        bins:
          type: integer
          nullable: true
        defaultSort:
          $ref: '#/components/schemas/unstableDashboardWidgetDefaultSort'
          nullable: true
      required:
        - type
    unstableDashboardWidgetDefaultSort:
      title: unstableDashboardWidgetDefaultSort
      type: object
      properties:
        column:
          type: string
        order:
          $ref: '#/components/schemas/unstableDashboardWidgetSortOrder'
      required:
        - column
        - order
    unstableDashboardWidgetSortOrder:
      title: unstableDashboardWidgetSortOrder
      type: string
      enum:
        - ASC
        - DESC
    unstableDashboardWidgetChartConfigInput:
      title: unstableDashboardWidgetChartConfigInput
      type: object
      description: |-
        Input-side chart config. `type` is optional and defaults to the
        widget's `chartType`; when given it must match.
      properties:
        type:
          $ref: '#/components/schemas/unstableDashboardWidgetChartType'
          nullable: true
        row_limit:
          type: integer
          nullable: true
        show_value_labels:
          type: boolean
          nullable: true
        bins:
          type: integer
          nullable: true
        defaultSort:
          $ref: '#/components/schemas/unstableDashboardWidgetDefaultSort'
          nullable: true
    unstableCreateDashboardWidgetRequest:
      title: unstableCreateDashboardWidgetRequest
      type: object
      properties:
        name:
          type: string
        description:
          type: string
          nullable: true
          description: Defaults to an empty string.
        view:
          $ref: '#/components/schemas/unstableDashboardWidgetView'
        dimensions:
          type: array
          items:
            $ref: '#/components/schemas/unstableDashboardWidgetDimension'
        metrics:
          type: array
          items:
            $ref: '#/components/schemas/unstableDashboardWidgetMetric'
        filters:
          type: array
          items:
            $ref: '#/components/schemas/unstableDashboardWidgetFilter'
        chartType:
          $ref: '#/components/schemas/unstableDashboardWidgetChartType'
        chartConfig:
          $ref: '#/components/schemas/unstableDashboardWidgetChartConfigInput'
          nullable: true
          description: Defaults to the plain config for `chartType`.
      required:
        - name
        - view
        - dimensions
        - metrics
        - filters
        - chartType
    unstableUpdateDashboardWidgetRequest:
      title: unstableUpdateDashboardWidgetRequest
      type: object
      properties:
        name:
          type: string
          nullable: true
        description:
          type: string
          nullable: true
        view:
          $ref: '#/components/schemas/unstableDashboardWidgetView'
          nullable: true
        dimensions:
          type: array
          items:
            $ref: '#/components/schemas/unstableDashboardWidgetDimension'
          nullable: true
        metrics:
          type: array
          items:
            $ref: '#/components/schemas/unstableDashboardWidgetMetric'
          nullable: true
        filters:
          type: array
          items:
            $ref: '#/components/schemas/unstableDashboardWidgetFilter'
          nullable: true
        chartType:
          $ref: '#/components/schemas/unstableDashboardWidgetChartType'
          nullable: true
        chartConfig:
          $ref: '#/components/schemas/unstableDashboardWidgetChartConfigInput'
          nullable: true
    unstableDashboardWidgetList:
      title: unstableDashboardWidgetList
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/unstableDashboardWidget'
        meta:
          $ref: '#/components/schemas/utilsMetaResponse'
      required:
        - data
        - meta
    unstableDeleteDashboardWidgetResponse:
      title: unstableDeleteDashboardWidgetResponse
      type: object
      properties:
        message:
          type: string
      required:
        - message
    unstableDashboardWidget:
      title: unstableDashboardWidget
      type: object
      properties:
        id:
          type: string
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
        name:
          type: string
        description:
          type: string
        view:
          $ref: '#/components/schemas/unstableDashboardWidgetViewWithLegacy'
        dimensions:
          type: array
          items:
            $ref: '#/components/schemas/unstableDashboardWidgetDimension'
        metrics:
          type: array
          items:
            $ref: '#/components/schemas/unstableDashboardWidgetMetric'
        filters:
          type: array
          items:
            $ref: '#/components/schemas/unstableDashboardWidgetFilter'
        chartType:
          $ref: '#/components/schemas/unstableDashboardWidgetChartType'
        chartConfig:
          $ref: '#/components/schemas/unstableDashboardWidgetChartConfig'
      required:
        - id
        - createdAt
        - updatedAt
        - name
        - description
        - view
        - dimensions
        - metrics
        - filters
        - chartType
        - chartConfig
    unstableDashboardPlacement:
      title: unstableDashboardPlacement
      oneOf:
        - type: object
          allOf:
            - type: object
              properties:
                type:
                  type: string
                  enum:
                    - widget
            - $ref: '#/components/schemas/unstableWidgetPlacement'
          required:
            - type
          title: UnstableWidgetPlacement
        - type: object
          allOf:
            - type: object
              properties:
                type:
                  type: string
                  enum:
                    - preset
            - $ref: '#/components/schemas/unstablePresetPlacement'
          required:
            - type
          title: UnstablePresetPlacement
      description: |-
        A tile on the dashboard's 12-column grid. `x`/`y` are the tile's
        top-left cell (0-based; `y` grows downward), `width`/`height` its size
        in cells. The UI default tile is 6x6 (half width). Overlapping tiles
        are not rejected; prefer appending below existing tiles (or omit the
        position on create to let the server do it).
    unstableWidgetPlacement:
      title: unstableWidgetPlacement
      type: object
      properties:
        id:
          type: string
        widgetId:
          type: string
        x:
          type: integer
        'y':
          type: integer
        width:
          type: integer
        height:
          type: integer
      required:
        - id
        - widgetId
        - x
        - 'y'
        - width
        - height
    unstablePresetPlacement:
      title: unstablePresetPlacement
      type: object
      properties:
        id:
          type: string
        presetId:
          type: string
        x:
          type: integer
        'y':
          type: integer
        width:
          type: integer
        height:
          type: integer
      required:
        - id
        - presetId
        - x
        - 'y'
        - width
        - height
    unstableCreateDashboardPlacementRequest:
      title: unstableCreateDashboardPlacementRequest
      oneOf:
        - type: object
          allOf:
            - type: object
              properties:
                type:
                  type: string
                  enum:
                    - widget
            - $ref: '#/components/schemas/unstableCreateWidgetPlacement'
          required:
            - type
          title: UnstableCreateWidgetPlacement
        - type: object
          allOf:
            - type: object
              properties:
                type:
                  type: string
                  enum:
                    - preset
            - $ref: '#/components/schemas/unstableCreatePresetPlacement'
          required:
            - type
          title: UnstableCreatePresetPlacement
    unstableCreateWidgetPlacement:
      title: unstableCreateWidgetPlacement
      type: object
      properties:
        id:
          type: string
          nullable: true
          description: Server-generated when omitted.
        widgetId:
          type: string
        x:
          type: integer
          nullable: true
          description: Grid column (12-column grid). Defaults to `0`.
        'y':
          type: integer
          nullable: true
          description: Grid row. Defaults to the first row below all existing tiles.
        width:
          type: integer
          nullable: true
          description: Width in grid columns. Defaults to `6`.
        height:
          type: integer
          nullable: true
          description: Height in grid rows. Defaults to `6`.
      required:
        - widgetId
    unstableCreatePresetPlacement:
      title: unstableCreatePresetPlacement
      type: object
      properties:
        id:
          type: string
          nullable: true
          description: Server-generated when omitted.
        presetId:
          type: string
        x:
          type: integer
          nullable: true
          description: Grid column (12-column grid). Defaults to `0`.
        'y':
          type: integer
          nullable: true
          description: Grid row. Defaults to the first row below all existing tiles.
        width:
          type: integer
          nullable: true
          description: Width in grid columns. Defaults to `6`.
        height:
          type: integer
          nullable: true
          description: Height in grid rows. Defaults to `6`.
      required:
        - presetId
    unstableUpdateDashboardPlacementRequest:
      title: unstableUpdateDashboardPlacementRequest
      type: object
      properties:
        x:
          type: integer
          nullable: true
          description: Grid column (12-column grid).
        'y':
          type: integer
          nullable: true
          description: Grid row.
        width:
          type: integer
          nullable: true
          description: Width in grid columns.
        height:
          type: integer
          nullable: true
          description: Height in grid rows.
    unstableDeleteDashboardPlacementResponse:
      title: unstableDeleteDashboardPlacementResponse
      type: object
      properties:
        message:
          type: string
      required:
        - message
    unstableDashboardDefinition:
      title: unstableDashboardDefinition
      type: object
      properties:
        widgets:
          type: array
          items:
            $ref: '#/components/schemas/unstableDashboardPlacement'
      required:
        - widgets
    unstableDashboard:
      title: unstableDashboard
      type: object
      properties:
        id:
          type: string
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
        name:
          type: string
        description:
          type: string
        definition:
          $ref: '#/components/schemas/unstableDashboardDefinition'
        filters:
          type: array
          items:
            $ref: '#/components/schemas/unstableDashboardWidgetFilter'
          description: Dashboard-level filters applied to all widgets on the dashboard.
      required:
        - id
        - createdAt
        - updatedAt
        - name
        - description
        - definition
        - filters
    unstableDashboardList:
      title: unstableDashboardList
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/unstableDashboard'
        meta:
          $ref: '#/components/schemas/utilsMetaResponse'
      required:
        - data
        - meta
    unstableCreateDashboardRequest:
      title: unstableCreateDashboardRequest
      type: object
      properties:
        name:
          type: string
        description:
          type: string
          nullable: true
        definition:
          $ref: '#/components/schemas/unstableDashboardDefinition'
          nullable: true
        filters:
          type: array
          items:
            $ref: '#/components/schemas/unstableDashboardWidgetFilter'
          nullable: true
      required:
        - name
    unstableUpdateDashboardRequest:
      title: unstableUpdateDashboardRequest
      type: object
      properties:
        name:
          type: string
          nullable: true
        description:
          type: string
          nullable: true
        definition:
          $ref: '#/components/schemas/unstableDashboardDefinition'
          nullable: true
        filters:
          type: array
          items:
            $ref: '#/components/schemas/unstableDashboardWidgetFilter'
          nullable: true
    unstableDeleteDashboardResponse:
      title: unstableDeleteDashboardResponse
      type: object
      properties:
        message:
          type: string
      required:
        - message
    unstablePublicApiErrorCode:
      title: unstablePublicApiErrorCode
      type: string
      enum:
        - authentication_failed
        - access_denied
        - invalid_request
        - invalid_query
        - invalid_body
        - resource_not_found
        - conflict
        - rate_limited
        - method_not_allowed
        - internal_error
      description: Machine-readable error code returned by unstable public API endpoints.
    unstablePublicApiValidationIssue:
      title: unstablePublicApiValidationIssue
      type: object
      description: >-
        A validation issue returned for malformed request bodies or query
        parameters.
      properties:
        code:
          type: string
        message:
          type: string
        path:
          type: array
          items: {}
      required:
        - code
        - message
        - path
    unstablePublicApiErrorDetails:
      title: unstablePublicApiErrorDetails
      type: object
      description: Optional structured context attached to an error.
      properties:
        issues:
          type: array
          items:
            $ref: '#/components/schemas/unstablePublicApiValidationIssue'
          nullable: true
        field:
          type: string
          nullable: true
        column:
          type: string
          nullable: true
        invalidValues:
          type: array
          items:
            type: string
          nullable: true
        allowedValues:
          type: array
          items:
            type: string
          nullable: true
        value:
          type: string
          nullable: true
        retryAfterSeconds:
          type: integer
          nullable: true
        limit:
          type: integer
          nullable: true
        remaining:
          type: integer
          nullable: true
        resetAt:
          type: string
          nullable: true
    unstablePublicApiError:
      title: unstablePublicApiError
      type: object
      description: Standard error envelope for unstable public API endpoints.
      properties:
        message:
          type: string
          description: Human-readable description of the failure.
        code:
          $ref: '#/components/schemas/unstablePublicApiErrorCode'
          description: Machine-readable error code.
        details:
          $ref: '#/components/schemas/unstablePublicApiErrorDetails'
          nullable: true
          description: Optional structured error context.
      required:
        - message
        - code
    unstableTopicsOrderBy:
      title: unstableTopicsOrderBy
      type: string
      enum:
        - traceCount.desc
        - traceCount.asc
        - name.asc
        - name.desc
    unstableTopicFacetPublishedRun:
      title: unstableTopicFacetPublishedRun
      type: object
      properties:
        id:
          type: string
        completedAt:
          type: string
          format: date-time
          nullable: true
        topicCount:
          type: integer
      required:
        - id
        - topicCount
    unstableTopicFacet:
      title: unstableTopicFacet
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        description:
          type: string
        isBuiltIn:
          type: boolean
        active:
          type: boolean
          description: >-
            Whether the facet is attached to the project's Topics rule. True for
            all facets if the project has no rule.
        version:
          type: integer
          description: Latest facet version.
        prompt:
          type: string
          description: Prompt of the latest facet version.
        publishedRun:
          $ref: '#/components/schemas/unstableTopicFacetPublishedRun'
          nullable: true
          description: >-
            The run that produced the facet's current map. Null before the first
            map.
      required:
        - id
        - name
        - description
        - isBuiltIn
        - active
        - version
        - prompt
    unstableTopicFacetList:
      title: unstableTopicFacetList
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/unstableTopicFacet'
        meta:
          $ref: '#/components/schemas/utilsMetaResponse'
      required:
        - data
        - meta
    unstableTopicFacetRef:
      title: unstableTopicFacetRef
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        version:
          type: integer
      required:
        - id
        - name
        - version
    unstableTopicWindow:
      title: unstableTopicWindow
      type: object
      properties:
        from:
          type: string
          format: date-time
        to:
          type: string
          format: date-time
      required:
        - from
        - to
    unstableTopic:
      title: unstableTopic
      type: object
      properties:
        id:
          type: string
          description: Stable topic id, kept across map updates.
        versionId:
          type: string
          description: Id of this topic version.
        name:
          type: string
        description:
          type: string
        facet:
          $ref: '#/components/schemas/unstableTopicFacetRef'
        runId:
          type: string
          description: The run that produced this topic version.
        traceCount:
          type: integer
          description: >-
            Traces in the window whose current result for the facet is this
            topic.
      required:
        - id
        - versionId
        - name
        - description
        - facet
        - runId
        - traceCount
    unstableTopicWithStatus:
      title: unstableTopicWithStatus
      type: object
      properties:
        inCurrentMap:
          type: boolean
          description: >-
            False for retired topics that still have assigned traces in the
            window.
        window:
          $ref: '#/components/schemas/unstableTopicWindow'
      required:
        - inCurrentMap
        - window
      allOf:
        - $ref: '#/components/schemas/unstableTopic'
    unstableTopicStatusCounts:
      title: unstableTopicStatusCounts
      type: object
      description: Traces in the window by their current result for one facet.
      properties:
        assigned:
          type: integer
        outlier:
          type: integer
        awaitingMap:
          type: integer
        notApplicable:
          type: integer
        insufficientInput:
          type: integer
      required:
        - assigned
        - outlier
        - awaitingMap
        - notApplicable
        - insufficientInput
    unstableTopicFacetCounts:
      title: unstableTopicFacetCounts
      type: object
      properties:
        facet:
          $ref: '#/components/schemas/unstableTopicFacetRef'
        publishedRunId:
          type: string
          nullable: true
        counts:
          $ref: '#/components/schemas/unstableTopicStatusCounts'
      required:
        - facet
        - counts
    unstableTopicList:
      title: unstableTopicList
      type: object
      properties:
        window:
          $ref: '#/components/schemas/unstableTopicWindow'
        data:
          type: array
          items:
            $ref: '#/components/schemas/unstableTopic'
        facets:
          type: array
          items:
            $ref: '#/components/schemas/unstableTopicFacetCounts'
        meta:
          $ref: '#/components/schemas/utilsMetaResponse'
      required:
        - window
        - data
        - facets
        - meta
    utilsMetaResponse:
      title: utilsMetaResponse
      type: object
      properties:
        page:
          type: integer
          description: current page number
        limit:
          type: integer
          description: number of items per page
        totalItems:
          type: integer
          description: number of total items given the current filters/selection (if any)
        totalPages:
          type: integer
          description: number of total pages given the current limit
      required:
        - page
        - limit
        - totalItems
        - totalPages
    utilsCursorMetaResponse:
      title: utilsCursorMetaResponse
      type: object
      description: Metadata for cursor-based pagination.
      properties:
        cursor:
          type: string
          nullable: true
          description: Opaque cursor for the next page. Omitted when there is no next page.
  securitySchemes:
    BasicAuth:
      type: http
      scheme: basic