openapi: 3.0.3
info:
  title: Braintrust REST API
  description: >-
    The Braintrust REST API for building, evaluating, and observing AI
    applications. The API is organized around REST, uses predictable
    resource-oriented URLs under https://api.braintrust.dev/v1, accepts and
    returns JSON, and authenticates with a Bearer API key. This specification
    covers the core documented resource surface - projects, experiments,
    datasets, logs/spans, prompts, functions and scorers, evals, project
    configuration, organization/ACL management, credentials, and the
    OpenAI-compatible AI proxy.
  termsOfService: https://www.braintrust.dev/legal/terms-of-service
  contact:
    name: Braintrust Support
    email: support@braintrust.dev
    url: https://www.braintrust.dev/docs
  version: '1.0'
servers:
  - url: https://api.braintrust.dev
    description: US data plane (default)
  - url: https://api-eu.braintrust.dev
    description: EU data plane
security:
  - bearerAuth: []
tags:
  - name: Projects
  - name: Experiments
  - name: Datasets
  - name: Logs
  - name: Prompts
  - name: Functions
  - name: Evals
  - name: Project Configuration
  - name: Organization
  - name: ACL
  - name: Credentials
  - name: AI Proxy
paths:
  /v1/project:
    get:
      operationId: getProject
      tags:
        - Projects
      summary: List projects
      description: List out all projects, optionally filtered and paginated.
      parameters:
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/StartingAfter'
        - $ref: '#/components/parameters/EndingBefore'
        - name: org_name
          in: query
          schema:
            type: string
          description: Filter projects to a single organization by name.
        - name: project_name
          in: query
          schema:
            type: string
          description: Filter to a project with the given name.
      responses:
        '200':
          description: Returns a list of projects.
          content:
            application/json:
              schema:
                type: object
                properties:
                  objects:
                    type: array
                    items:
                      $ref: '#/components/schemas/Project'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: postProject
      tags:
        - Projects
      summary: Create project
      description: >-
        Create a new project. If there is an existing project with the same
        name in the organization, will return the existing project unmodified.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateProject'
      responses:
        '200':
          description: Returns the new project object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Project'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/project/{project_id}:
    parameters:
      - $ref: '#/components/parameters/ProjectId'
    get:
      operationId: getProjectId
      tags:
        - Projects
      summary: Get project
      description: Get a project by its unique identifier.
      responses:
        '200':
          description: Returns the project object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Project'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    patch:
      operationId: patchProjectId
      tags:
        - Projects
      summary: Partially update project
      description: >-
        Partially update a project object. Specify the fields to update in the
        payload. Unspecified fields are left unchanged.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatchProject'
      responses:
        '200':
          description: Returns the updated project object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Project'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      operationId: deleteProjectId
      tags:
        - Projects
      summary: Delete project
      description: Delete a project by its unique identifier.
      responses:
        '200':
          description: Returns the deleted project object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Project'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /v1/experiment:
    get:
      operationId: getExperiment
      tags:
        - Experiments
      summary: List experiments
      description: List out all experiments, optionally filtered and paginated.
      parameters:
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/StartingAfter'
        - $ref: '#/components/parameters/EndingBefore'
        - name: project_id
          in: query
          schema:
            type: string
            format: uuid
          description: Filter experiments to a project.
        - name: experiment_name
          in: query
          schema:
            type: string
          description: Filter to an experiment with the given name.
      responses:
        '200':
          description: Returns a list of experiments.
          content:
            application/json:
              schema:
                type: object
                properties:
                  objects:
                    type: array
                    items:
                      $ref: '#/components/schemas/Experiment'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: postExperiment
      tags:
        - Experiments
      summary: Create experiment
      description: >-
        Create a new experiment. If there is an existing experiment with the
        same name as the one specified in the request, will return the existing
        experiment unmodified.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateExperiment'
      responses:
        '200':
          description: Returns the new experiment object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Experiment'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/experiment/{experiment_id}:
    parameters:
      - $ref: '#/components/parameters/ExperimentId'
    get:
      operationId: getExperimentId
      tags:
        - Experiments
      summary: Get experiment
      responses:
        '200':
          description: Returns the experiment object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Experiment'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    patch:
      operationId: patchExperimentId
      tags:
        - Experiments
      summary: Partially update experiment
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                description:
                  type: string
                metadata:
                  type: object
                  additionalProperties: true
      responses:
        '200':
          description: Returns the updated experiment object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Experiment'
        '401':
          $ref: '#/components/responses/Unauthorized'
    delete:
      operationId: deleteExperimentId
      tags:
        - Experiments
      summary: Delete experiment
      responses:
        '200':
          description: Returns the deleted experiment object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Experiment'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/experiment/{experiment_id}/insert:
    parameters:
      - $ref: '#/components/parameters/ExperimentId'
    post:
      operationId: postExperimentIdInsert
      tags:
        - Experiments
      summary: Insert experiment events
      description: >-
        Insert a set of events into the experiment. Events are upserted by id;
        equivalent to the SDK's logging interface.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - events
              properties:
                events:
                  type: array
                  description: A list of experiment events to insert.
                  items:
                    $ref: '#/components/schemas/InsertEvent'
      responses:
        '200':
          description: Returns the row ids of the inserted events.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InsertEventsResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/experiment/{experiment_id}/fetch:
    parameters:
      - $ref: '#/components/parameters/ExperimentId'
    post:
      operationId: postExperimentIdFetch
      tags:
        - Experiments
      summary: Fetch experiment (POST form)
      description: >-
        Fetch the events in an experiment. Use the POST form to express complex
        filters, limits, and cursors in the request body.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FetchEventsRequest'
      responses:
        '200':
          description: Returns the fetched events.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FetchEventsResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
    get:
      operationId: getExperimentIdFetch
      tags:
        - Experiments
      summary: Fetch experiment (GET form)
      parameters:
        - $ref: '#/components/parameters/Limit'
        - name: max_xact_id
          in: query
          schema:
            type: string
        - name: max_root_span_id
          in: query
          schema:
            type: string
      responses:
        '200':
          description: Returns the fetched events.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FetchEventsResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/experiment/{experiment_id}/feedback:
    parameters:
      - $ref: '#/components/parameters/ExperimentId'
    post:
      operationId: postExperimentIdFeedback
      tags:
        - Experiments
      summary: Feedback for experiment events
      description: Log feedback for a set of experiment events.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - feedback
              properties:
                feedback:
                  type: array
                  items:
                    $ref: '#/components/schemas/FeedbackItem'
      responses:
        '200':
          $ref: '#/components/responses/Empty'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/experiment/{experiment_id}/summarize:
    parameters:
      - $ref: '#/components/parameters/ExperimentId'
    get:
      operationId: getExperimentIdSummarize
      tags:
        - Experiments
      summary: Summarize experiment
      description: Summarize the scores and metrics of an experiment.
      parameters:
        - name: summarize_scores
          in: query
          schema:
            type: boolean
        - name: comparison_experiment_id
          in: query
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Returns the experiment summary.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SummarizeExperimentResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/eval:
    post:
      operationId: evalLaunch
      tags:
        - Evals
      summary: Launch an eval
      description: >-
        Launch an evaluation. This is the API-equivalent of the Eval function
        in the SDK; it runs a task function over a dataset and applies scorers.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EvalLaunchRequest'
      responses:
        '200':
          description: Returns a summary of the launched eval.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SummarizeExperimentResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/dataset:
    get:
      operationId: getDataset
      tags:
        - Datasets
      summary: List datasets
      parameters:
        - $ref: '#/components/parameters/Limit'
        - name: project_id
          in: query
          schema:
            type: string
            format: uuid
        - name: dataset_name
          in: query
          schema:
            type: string
      responses:
        '200':
          description: Returns a list of datasets.
          content:
            application/json:
              schema:
                type: object
                properties:
                  objects:
                    type: array
                    items:
                      $ref: '#/components/schemas/Dataset'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: postDataset
      tags:
        - Datasets
      summary: Create dataset
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateDataset'
      responses:
        '200':
          description: Returns the new dataset object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Dataset'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/dataset/{dataset_id}:
    parameters:
      - $ref: '#/components/parameters/DatasetId'
    get:
      operationId: getDatasetId
      tags:
        - Datasets
      summary: Get dataset
      responses:
        '200':
          description: Returns the dataset object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Dataset'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    patch:
      operationId: patchDatasetId
      tags:
        - Datasets
      summary: Partially update dataset
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                description:
                  type: string
                metadata:
                  type: object
                  additionalProperties: true
      responses:
        '200':
          description: Returns the updated dataset object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Dataset'
        '401':
          $ref: '#/components/responses/Unauthorized'
    delete:
      operationId: deleteDatasetId
      tags:
        - Datasets
      summary: Delete dataset
      responses:
        '200':
          description: Returns the deleted dataset object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Dataset'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/dataset/{dataset_id}/insert:
    parameters:
      - $ref: '#/components/parameters/DatasetId'
    post:
      operationId: postDatasetIdInsert
      tags:
        - Datasets
      summary: Insert dataset events
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - events
              properties:
                events:
                  type: array
                  items:
                    $ref: '#/components/schemas/InsertEvent'
      responses:
        '200':
          description: Returns the row ids of the inserted events.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InsertEventsResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/dataset/{dataset_id}/fetch:
    parameters:
      - $ref: '#/components/parameters/DatasetId'
    post:
      operationId: postDatasetIdFetch
      tags:
        - Datasets
      summary: Fetch dataset (POST form)
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FetchEventsRequest'
      responses:
        '200':
          description: Returns the fetched events.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FetchEventsResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
    get:
      operationId: getDatasetIdFetch
      tags:
        - Datasets
      summary: Fetch dataset (GET form)
      parameters:
        - $ref: '#/components/parameters/Limit'
      responses:
        '200':
          description: Returns the fetched events.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FetchEventsResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/dataset/{dataset_id}/feedback:
    parameters:
      - $ref: '#/components/parameters/DatasetId'
    post:
      operationId: postDatasetIdFeedback
      tags:
        - Datasets
      summary: Feedback for dataset events
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - feedback
              properties:
                feedback:
                  type: array
                  items:
                    $ref: '#/components/schemas/FeedbackItem'
      responses:
        '200':
          $ref: '#/components/responses/Empty'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/dataset/{dataset_id}/summarize:
    parameters:
      - $ref: '#/components/parameters/DatasetId'
    get:
      operationId: getDatasetIdSummarize
      tags:
        - Datasets
      summary: Summarize dataset
      parameters:
        - name: summarize_data
          in: query
          schema:
            type: boolean
      responses:
        '200':
          description: Returns the dataset summary.
          content:
            application/json:
              schema:
                type: object
                properties:
                  project_name:
                    type: string
                  dataset_name:
                    type: string
                  data_summary:
                    type: object
                    nullable: true
                    properties:
                      total_records:
                        type: integer
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/project_logs/{project_id}/insert:
    parameters:
      - $ref: '#/components/parameters/ProjectId'
    post:
      operationId: postProjectLogsIdInsert
      tags:
        - Logs
      summary: Insert project logs events
      description: Insert a set of trace span / log events into a project's logs.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - events
              properties:
                events:
                  type: array
                  items:
                    $ref: '#/components/schemas/InsertEvent'
      responses:
        '200':
          description: Returns the row ids of the inserted events.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InsertEventsResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/project_logs/{project_id}/fetch:
    parameters:
      - $ref: '#/components/parameters/ProjectId'
    post:
      operationId: postProjectLogsIdFetch
      tags:
        - Logs
      summary: Fetch project logs (POST form)
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FetchEventsRequest'
      responses:
        '200':
          description: Returns the fetched log events.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FetchEventsResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
    get:
      operationId: getProjectLogsIdFetch
      tags:
        - Logs
      summary: Fetch project logs (GET form)
      parameters:
        - $ref: '#/components/parameters/Limit'
      responses:
        '200':
          description: Returns the fetched log events.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FetchEventsResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/project_logs/{project_id}/feedback:
    parameters:
      - $ref: '#/components/parameters/ProjectId'
    post:
      operationId: postProjectLogsIdFeedback
      tags:
        - Logs
      summary: Feedback for project logs events
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - feedback
              properties:
                feedback:
                  type: array
                  items:
                    $ref: '#/components/schemas/FeedbackItem'
      responses:
        '200':
          $ref: '#/components/responses/Empty'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/prompt:
    get:
      operationId: getPrompt
      tags:
        - Prompts
      summary: List prompts
      parameters:
        - $ref: '#/components/parameters/Limit'
        - name: project_id
          in: query
          schema:
            type: string
            format: uuid
        - name: prompt_name
          in: query
          schema:
            type: string
        - name: slug
          in: query
          schema:
            type: string
      responses:
        '200':
          description: Returns a list of prompts.
          content:
            application/json:
              schema:
                type: object
                properties:
                  objects:
                    type: array
                    items:
                      $ref: '#/components/schemas/Prompt'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: postPrompt
      tags:
        - Prompts
      summary: Create prompt
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreatePrompt'
      responses:
        '200':
          description: Returns the new prompt object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Prompt'
        '401':
          $ref: '#/components/responses/Unauthorized'
    put:
      operationId: putPrompt
      tags:
        - Prompts
      summary: Create or replace prompt
      description: >-
        Create or replace a prompt. If a prompt with the same slug already
        exists in the project, it will be replaced.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreatePrompt'
      responses:
        '200':
          description: Returns the prompt object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Prompt'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/prompt/{prompt_id}:
    parameters:
      - name: prompt_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
    get:
      operationId: getPromptId
      tags:
        - Prompts
      summary: Get prompt
      responses:
        '200':
          description: Returns the prompt object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Prompt'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    patch:
      operationId: patchPromptId
      tags:
        - Prompts
      summary: Partially update prompt
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                description:
                  type: string
                prompt_data:
                  $ref: '#/components/schemas/PromptData'
                tags:
                  type: array
                  items:
                    type: string
      responses:
        '200':
          description: Returns the updated prompt object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Prompt'
        '401':
          $ref: '#/components/responses/Unauthorized'
    delete:
      operationId: deletePromptId
      tags:
        - Prompts
      summary: Delete prompt
      responses:
        '200':
          description: Returns the deleted prompt object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Prompt'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/function:
    get:
      operationId: getFunction
      tags:
        - Functions
      summary: List functions
      parameters:
        - $ref: '#/components/parameters/Limit'
        - name: project_id
          in: query
          schema:
            type: string
            format: uuid
        - name: function_name
          in: query
          schema:
            type: string
        - name: slug
          in: query
          schema:
            type: string
      responses:
        '200':
          description: Returns a list of functions.
          content:
            application/json:
              schema:
                type: object
                properties:
                  objects:
                    type: array
                    items:
                      $ref: '#/components/schemas/Function'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: postFunction
      tags:
        - Functions
      summary: Create function
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateFunction'
      responses:
        '200':
          description: Returns the new function object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Function'
        '401':
          $ref: '#/components/responses/Unauthorized'
    put:
      operationId: putFunction
      tags:
        - Functions
      summary: Create or replace function
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateFunction'
      responses:
        '200':
          description: Returns the function object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Function'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/function/{function_id}:
    parameters:
      - name: function_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
    get:
      operationId: getFunctionId
      tags:
        - Functions
      summary: Get function
      responses:
        '200':
          description: Returns the function object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Function'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    patch:
      operationId: patchFunctionId
      tags:
        - Functions
      summary: Partially update function
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                description:
                  type: string
                function_data:
                  type: object
                  additionalProperties: true
      responses:
        '200':
          description: Returns the updated function object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Function'
        '401':
          $ref: '#/components/responses/Unauthorized'
    delete:
      operationId: deleteFunctionId
      tags:
        - Functions
      summary: Delete function
      responses:
        '200':
          description: Returns the deleted function object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Function'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/function/{function_id}/invoke:
    parameters:
      - name: function_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
    post:
      operationId: postFunctionIdInvoke
      tags:
        - Functions
      summary: Invoke function
      description: >-
        Invoke a function (a prompt, code, or LLM scorer) server-side with the
        given input. Optionally stream the result and write a trace span to a
        parent object.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InvokeFunctionRequest'
      responses:
        '200':
          description: Returns the function result, or an SSE stream when stream is true.
          content:
            application/json:
              schema:
                description: The return value of the function. Shape depends on the function.
            text/event-stream:
              schema:
                type: string
                description: Server-Sent Events stream of the function result when stream is true.
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/project_score:
    get:
      operationId: getProjectScore
      tags:
        - Project Configuration
      summary: List project scores
      parameters:
        - $ref: '#/components/parameters/Limit'
        - name: project_id
          in: query
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Returns a list of project scores.
          content:
            application/json:
              schema:
                type: object
                properties:
                  objects:
                    type: array
                    items:
                      $ref: '#/components/schemas/ProjectScore'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: postProjectScore
      tags:
        - Project Configuration
      summary: Create project_score
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateProjectScore'
      responses:
        '200':
          description: Returns the new project score object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProjectScore'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/project_score/{project_score_id}:
    parameters:
      - name: project_score_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
    get:
      operationId: getProjectScoreId
      tags:
        - Project Configuration
      summary: Get project_score
      responses:
        '200':
          description: Returns the project score object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProjectScore'
        '401':
          $ref: '#/components/responses/Unauthorized'
    delete:
      operationId: deleteProjectScoreId
      tags:
        - Project Configuration
      summary: Delete project_score
      responses:
        '200':
          description: Returns the deleted project score object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProjectScore'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/project_tag:
    get:
      operationId: getProjectTag
      tags:
        - Project Configuration
      summary: List project tags
      parameters:
        - $ref: '#/components/parameters/Limit'
        - name: project_id
          in: query
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Returns a list of project tags.
          content:
            application/json:
              schema:
                type: object
                properties:
                  objects:
                    type: array
                    items:
                      $ref: '#/components/schemas/ProjectTag'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: postProjectTag
      tags:
        - Project Configuration
      summary: Create project_tag
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - project_id
                - name
              properties:
                project_id:
                  type: string
                  format: uuid
                name:
                  type: string
                description:
                  type: string
                color:
                  type: string
      responses:
        '200':
          description: Returns the new project tag object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProjectTag'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/view:
    get:
      operationId: getView
      tags:
        - Project Configuration
      summary: List views
      parameters:
        - $ref: '#/components/parameters/Limit'
        - name: object_type
          in: query
          schema:
            type: string
        - name: object_id
          in: query
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Returns a list of views.
          content:
            application/json:
              schema:
                type: object
                properties:
                  objects:
                    type: array
                    items:
                      $ref: '#/components/schemas/View'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/organization:
    get:
      operationId: getOrganization
      tags:
        - Organization
      summary: List organizations
      parameters:
        - $ref: '#/components/parameters/Limit'
        - name: org_name
          in: query
          schema:
            type: string
      responses:
        '200':
          description: Returns a list of organizations.
          content:
            application/json:
              schema:
                type: object
                properties:
                  objects:
                    type: array
                    items:
                      $ref: '#/components/schemas/Organization'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/organization/members:
    patch:
      operationId: patchOrganizationMembers
      tags:
        - Organization
      summary: Modify organization membership
      description: Add or remove members from an organization.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                org_id:
                  type: string
                  format: uuid
                org_name:
                  type: string
                invite_users:
                  type: object
                  additionalProperties: true
                remove_users:
                  type: object
                  additionalProperties: true
      responses:
        '200':
          $ref: '#/components/responses/Empty'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/user:
    get:
      operationId: getUser
      tags:
        - Organization
      summary: List users
      parameters:
        - $ref: '#/components/parameters/Limit'
        - name: email
          in: query
          schema:
            type: string
        - name: org_name
          in: query
          schema:
            type: string
      responses:
        '200':
          description: Returns a list of users.
          content:
            application/json:
              schema:
                type: object
                properties:
                  objects:
                    type: array
                    items:
                      $ref: '#/components/schemas/User'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/role:
    get:
      operationId: getRole
      tags:
        - ACL
      summary: List roles
      parameters:
        - $ref: '#/components/parameters/Limit'
        - name: org_name
          in: query
          schema:
            type: string
      responses:
        '200':
          description: Returns a list of roles.
          content:
            application/json:
              schema:
                type: object
                properties:
                  objects:
                    type: array
                    items:
                      $ref: '#/components/schemas/Role'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: postRole
      tags:
        - ACL
      summary: Create role
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - name
              properties:
                name:
                  type: string
                description:
                  type: string
                member_permissions:
                  type: array
                  items:
                    type: object
                    additionalProperties: true
      responses:
        '200':
          description: Returns the new role object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Role'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/group:
    get:
      operationId: getGroup
      tags:
        - ACL
      summary: List groups
      parameters:
        - $ref: '#/components/parameters/Limit'
        - name: org_name
          in: query
          schema:
            type: string
      responses:
        '200':
          description: Returns a list of groups.
          content:
            application/json:
              schema:
                type: object
                properties:
                  objects:
                    type: array
                    items:
                      $ref: '#/components/schemas/Group'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: postGroup
      tags:
        - ACL
      summary: Create group
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - name
              properties:
                name:
                  type: string
                description:
                  type: string
                member_users:
                  type: array
                  items:
                    type: string
                    format: uuid
      responses:
        '200':
          description: Returns the new group object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Group'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/acl:
    get:
      operationId: getAcl
      tags:
        - ACL
      summary: List acls
      description: List ACLs for a given object type and id.
      parameters:
        - $ref: '#/components/parameters/Limit'
        - name: object_type
          in: query
          required: true
          schema:
            type: string
        - name: object_id
          in: query
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Returns a list of ACLs.
          content:
            application/json:
              schema:
                type: object
                properties:
                  objects:
                    type: array
                    items:
                      $ref: '#/components/schemas/Acl'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: postAcl
      tags:
        - ACL
      summary: Create acl
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateAcl'
      responses:
        '200':
          description: Returns the new ACL object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Acl'
        '401':
          $ref: '#/components/responses/Unauthorized'
    delete:
      operationId: deleteAcl
      tags:
        - ACL
      summary: Delete single acl
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateAcl'
      responses:
        '200':
          description: Returns the deleted ACL object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Acl'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/acl/batch_update:
    post:
      operationId: aclBatchUpdate
      tags:
        - ACL
      summary: Batch update acls
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                add_acls:
                  type: array
                  items:
                    $ref: '#/components/schemas/CreateAcl'
                remove_acls:
                  type: array
                  items:
                    $ref: '#/components/schemas/CreateAcl'
      responses:
        '200':
          description: Returns the added and removed ACLs.
          content:
            application/json:
              schema:
                type: object
                properties:
                  added_acls:
                    type: array
                    items:
                      $ref: '#/components/schemas/Acl'
                  removed_acls:
                    type: array
                    items:
                      $ref: '#/components/schemas/Acl'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/api_key:
    get:
      operationId: getApiKey
      tags:
        - Credentials
      summary: List api_keys
      parameters:
        - $ref: '#/components/parameters/Limit'
        - name: org_name
          in: query
          schema:
            type: string
      responses:
        '200':
          description: Returns a list of API keys (without secret values).
          content:
            application/json:
              schema:
                type: object
                properties:
                  objects:
                    type: array
                    items:
                      $ref: '#/components/schemas/ApiKey'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/api_key/{api_key_id}:
    parameters:
      - name: api_key_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
    get:
      operationId: getApiKeyId
      tags:
        - Credentials
      summary: Get api_key
      responses:
        '200':
          description: Returns the API key object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiKey'
        '401':
          $ref: '#/components/responses/Unauthorized'
    delete:
      operationId: deleteApiKeyId
      tags:
        - Credentials
      summary: Delete api_key
      responses:
        '200':
          description: Returns the deleted API key object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiKey'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/ai_secret:
    get:
      operationId: getAiSecret
      tags:
        - Credentials
      summary: List ai_secrets
      parameters:
        - $ref: '#/components/parameters/Limit'
        - name: org_name
          in: query
          schema:
            type: string
      responses:
        '200':
          description: Returns a list of AI secrets (without secret values).
          content:
            application/json:
              schema:
                type: object
                properties:
                  objects:
                    type: array
                    items:
                      $ref: '#/components/schemas/AiSecret'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: postAiSecret
      tags:
        - Credentials
      summary: Create ai_secret
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - name
              properties:
                name:
                  type: string
                type:
                  type: string
                  description: Provider type, e.g. openai, anthropic.
                secret:
                  type: string
                metadata:
                  type: object
                  additionalProperties: true
      responses:
        '200':
          description: Returns the new AI secret object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AiSecret'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/proxy/chat/completions:
    post:
      operationId: proxychatCompletions
      tags:
        - AI Proxy
      summary: Proxy chat/completions
      description: >-
        OpenAI-compatible chat completions proxied to the configured model
        provider, with optional caching and automatic logging. Set stream to
        true for a Server-Sent Events response.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChatCompletionRequest'
      responses:
        '200':
          description: Returns a chat completion, or an SSE stream when stream is true.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChatCompletionResponse'
            text/event-stream:
              schema:
                type: string
                description: Server-Sent Events stream of chat completion chunks.
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/proxy/embeddings:
    post:
      operationId: proxyembeddings
      tags:
        - AI Proxy
      summary: Proxy embeddings
      description: OpenAI-compatible embeddings proxied to the configured model provider.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - model
                - input
              properties:
                model:
                  type: string
                input:
                  oneOf:
                    - type: string
                    - type: array
                      items:
                        type: string
      responses:
        '200':
          description: Returns an embeddings response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  object:
                    type: string
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        index:
                          type: integer
                        embedding:
                          type: array
                          items:
                            type: number
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/proxy/credentials:
    post:
      operationId: proxycredentials
      tags:
        - AI Proxy
      summary: Create temporary credential
      description: >-
        Mint a temporary credential (JWT) scoped for use with the AI proxy,
        suitable for handing to browser or untrusted clients.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                ttl_seconds:
                  type: integer
                  description: Time-to-live for the temporary credential, in seconds.
                logging:
                  type: object
                  additionalProperties: true
                model:
                  type: string
      responses:
        '200':
          description: Returns a temporary credential.
          content:
            application/json:
              schema:
                type: object
                properties:
                  key:
                    type: string
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API key or JWT
      description: >-
        Authenticate requests with your Braintrust API key in the Authorization
        header, e.g. `Authorization: Bearer $BRAINTRUST_API_KEY`.
  parameters:
    Limit:
      name: limit
      in: query
      description: Limit the number of objects to return.
      schema:
        type: integer
        minimum: 0
    StartingAfter:
      name: starting_after
      in: query
      description: >-
        Pagination cursor id. Together with limit, returns the next page after
        the object with this id.
      schema:
        type: string
        format: uuid
    EndingBefore:
      name: ending_before
      in: query
      description: >-
        Pagination cursor id. Together with limit, returns the previous page
        before the object with this id.
      schema:
        type: string
        format: uuid
    ProjectId:
      name: project_id
      in: path
      required: true
      description: Project id, the unique identifier of the project.
      schema:
        type: string
        format: uuid
    ExperimentId:
      name: experiment_id
      in: path
      required: true
      description: Experiment id, the unique identifier of the experiment.
      schema:
        type: string
        format: uuid
    DatasetId:
      name: dataset_id
      in: path
      required: true
      description: Dataset id, the unique identifier of the dataset.
      schema:
        type: string
        format: uuid
  responses:
    Empty:
      description: Success.
      content:
        application/json:
          schema:
            type: object
    Unauthorized:
      description: Authentication failed - missing or invalid API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: The requested resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    Error:
      type: object
      properties:
        error:
          type: string
          description: A human-readable error message.
    Project:
      type: object
      properties:
        id:
          type: string
          format: uuid
        org_id:
          type: string
          format: uuid
        name:
          type: string
        created:
          type: string
          format: date-time
          nullable: true
        deleted_at:
          type: string
          format: date-time
          nullable: true
        user_id:
          type: string
          format: uuid
          nullable: true
        settings:
          type: object
          nullable: true
          additionalProperties: true
    CreateProject:
      type: object
      required:
        - name
      properties:
        name:
          type: string
          description: Name of the project.
        org_name:
          type: string
          description: >-
            For nearly all users, this parameter is unnecessary. Use it to
            disambiguate the organization when you belong to multiple.
    PatchProject:
      type: object
      properties:
        name:
          type: string
        settings:
          type: object
          additionalProperties: true
    Experiment:
      type: object
      properties:
        id:
          type: string
          format: uuid
        project_id:
          type: string
          format: uuid
        name:
          type: string
        description:
          type: string
          nullable: true
        created:
          type: string
          format: date-time
          nullable: true
        repo_info:
          type: object
          nullable: true
          additionalProperties: true
        base_exp_id:
          type: string
          format: uuid
          nullable: true
        dataset_id:
          type: string
          format: uuid
          nullable: true
        public:
          type: boolean
        metadata:
          type: object
          nullable: true
          additionalProperties: true
    CreateExperiment:
      type: object
      required:
        - project_id
      properties:
        project_id:
          type: string
          format: uuid
        name:
          type: string
        description:
          type: string
        base_exp_id:
          type: string
          format: uuid
        dataset_id:
          type: string
          format: uuid
        dataset_version:
          type: string
        public:
          type: boolean
        metadata:
          type: object
          additionalProperties: true
        repo_info:
          type: object
          additionalProperties: true
    Dataset:
      type: object
      properties:
        id:
          type: string
          format: uuid
        project_id:
          type: string
          format: uuid
          nullable: true
        name:
          type: string
        description:
          type: string
          nullable: true
        created:
          type: string
          format: date-time
          nullable: true
        user_id:
          type: string
          format: uuid
          nullable: true
        metadata:
          type: object
          nullable: true
          additionalProperties: true
    CreateDataset:
      type: object
      required:
        - name
      properties:
        project_id:
          type: string
          format: uuid
        name:
          type: string
        description:
          type: string
        metadata:
          type: object
          additionalProperties: true
    Prompt:
      type: object
      properties:
        id:
          type: string
          format: uuid
        project_id:
          type: string
          format: uuid
        name:
          type: string
        slug:
          type: string
        description:
          type: string
          nullable: true
        created:
          type: string
          format: date-time
          nullable: true
        prompt_data:
          $ref: '#/components/schemas/PromptData'
        tags:
          type: array
          nullable: true
          items:
            type: string
        function_type:
          type: string
          nullable: true
        log_id:
          type: string
          enum:
            - p
    CreatePrompt:
      type: object
      required:
        - project_id
        - name
        - slug
      properties:
        project_id:
          type: string
          format: uuid
        name:
          type: string
        slug:
          type: string
        description:
          type: string
        prompt_data:
          $ref: '#/components/schemas/PromptData'
        tags:
          type: array
          items:
            type: string
    PromptData:
      type: object
      description: The prompt template, model, and parameters.
      properties:
        prompt:
          type: object
          additionalProperties: true
          description: The prompt block - chat messages or a completion template.
        options:
          type: object
          additionalProperties: true
          description: Model and parameter options (model, temperature, max_tokens, etc).
        parser:
          type: object
          nullable: true
          additionalProperties: true
        tool_functions:
          type: array
          nullable: true
          items:
            type: object
            additionalProperties: true
    Function:
      type: object
      properties:
        id:
          type: string
          format: uuid
        project_id:
          type: string
          format: uuid
        name:
          type: string
        slug:
          type: string
        description:
          type: string
          nullable: true
        created:
          type: string
          format: date-time
          nullable: true
        function_type:
          type: string
          nullable: true
          enum:
            - llm
            - scorer
            - task
            - tool
        function_data:
          type: object
          additionalProperties: true
        prompt_data:
          $ref: '#/components/schemas/PromptData'
        function_schema:
          type: object
          nullable: true
          additionalProperties: true
        log_id:
          type: string
          enum:
            - p
    CreateFunction:
      type: object
      required:
        - project_id
        - name
        - slug
        - function_data
      properties:
        project_id:
          type: string
          format: uuid
        name:
          type: string
        slug:
          type: string
        description:
          type: string
        function_type:
          type: string
          enum:
            - llm
            - scorer
            - task
            - tool
        function_data:
          type: object
          additionalProperties: true
          description: >-
            The implementation - a prompt, inline code, a global function, or a
            reference to existing code.
        prompt_data:
          $ref: '#/components/schemas/PromptData'
        function_schema:
          type: object
          additionalProperties: true
    InvokeFunctionRequest:
      type: object
      properties:
        input:
          description: The input to the function. Shape depends on the function.
        messages:
          type: array
          items:
            type: object
            additionalProperties: true
        parent:
          description: >-
            Span parent properties; the result of the invocation will be logged
            as a span under this parent.
          oneOf:
            - type: string
            - type: object
              additionalProperties: true
        stream:
          type: boolean
          description: If true, the response is returned as a Server-Sent Events stream.
        version:
          type: string
          description: The version (transaction id) of the function to invoke.
        mode:
          type: string
          enum:
            - auto
            - parallel
    ProjectScore:
      type: object
      properties:
        id:
          type: string
          format: uuid
        project_id:
          type: string
          format: uuid
        name:
          type: string
        description:
          type: string
          nullable: true
        score_type:
          type: string
          enum:
            - slider
            - categorical
            - weighted
            - minimum
            - maximum
            - online
        categories:
          nullable: true
          description: For categorical scores, the configured categories.
        created:
          type: string
          format: date-time
          nullable: true
    CreateProjectScore:
      type: object
      required:
        - project_id
        - name
        - score_type
      properties:
        project_id:
          type: string
          format: uuid
        name:
          type: string
        description:
          type: string
        score_type:
          type: string
          enum:
            - slider
            - categorical
            - weighted
            - minimum
            - maximum
            - online
        categories:
          description: Category configuration for categorical scores.
    ProjectTag:
      type: object
      properties:
        id:
          type: string
          format: uuid
        project_id:
          type: string
          format: uuid
        name:
          type: string
        description:
          type: string
          nullable: true
        color:
          type: string
          nullable: true
        created:
          type: string
          format: date-time
          nullable: true
    View:
      type: object
      properties:
        id:
          type: string
          format: uuid
        object_type:
          type: string
        object_id:
          type: string
          format: uuid
        view_type:
          type: string
          nullable: true
        name:
          type: string
        view_data:
          type: object
          nullable: true
          additionalProperties: true
        created:
          type: string
          format: date-time
          nullable: true
    Organization:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        api_url:
          type: string
          nullable: true
        proxy_url:
          type: string
          nullable: true
        created:
          type: string
          format: date-time
          nullable: true
    User:
      type: object
      properties:
        id:
          type: string
          format: uuid
        given_name:
          type: string
          nullable: true
        family_name:
          type: string
          nullable: true
        email:
          type: string
          nullable: true
        avatar_url:
          type: string
          nullable: true
        created:
          type: string
          format: date-time
          nullable: true
    Role:
      type: object
      properties:
        id:
          type: string
          format: uuid
        org_id:
          type: string
          format: uuid
          nullable: true
        name:
          type: string
        description:
          type: string
          nullable: true
        member_permissions:
          type: array
          nullable: true
          items:
            type: object
            additionalProperties: true
        created:
          type: string
          format: date-time
          nullable: true
    Group:
      type: object
      properties:
        id:
          type: string
          format: uuid
        org_id:
          type: string
          format: uuid
          nullable: true
        name:
          type: string
        description:
          type: string
          nullable: true
        member_users:
          type: array
          nullable: true
          items:
            type: string
            format: uuid
        member_groups:
          type: array
          nullable: true
          items:
            type: string
            format: uuid
        created:
          type: string
          format: date-time
          nullable: true
    Acl:
      type: object
      properties:
        id:
          type: string
          format: uuid
        object_type:
          type: string
        object_id:
          type: string
          format: uuid
        user_id:
          type: string
          format: uuid
          nullable: true
        group_id:
          type: string
          format: uuid
          nullable: true
        permission:
          type: string
          nullable: true
          enum:
            - create
            - read
            - update
            - delete
            - create_acls
            - read_acls
            - update_acls
            - delete_acls
        role_id:
          type: string
          format: uuid
          nullable: true
        restrict_object_type:
          type: string
          nullable: true
        created:
          type: string
          format: date-time
          nullable: true
    CreateAcl:
      type: object
      required:
        - object_type
        - object_id
      properties:
        object_type:
          type: string
        object_id:
          type: string
          format: uuid
        user_id:
          type: string
          format: uuid
        group_id:
          type: string
          format: uuid
        permission:
          type: string
          enum:
            - create
            - read
            - update
            - delete
            - create_acls
            - read_acls
            - update_acls
            - delete_acls
        role_id:
          type: string
          format: uuid
        restrict_object_type:
          type: string
    ApiKey:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        preview_name:
          type: string
          nullable: true
        user_id:
          type: string
          format: uuid
          nullable: true
        org_id:
          type: string
          format: uuid
          nullable: true
        created:
          type: string
          format: date-time
          nullable: true
    AiSecret:
      type: object
      properties:
        id:
          type: string
          format: uuid
        org_id:
          type: string
          format: uuid
          nullable: true
        name:
          type: string
        type:
          type: string
          nullable: true
        metadata:
          type: object
          nullable: true
          additionalProperties: true
        created:
          type: string
          format: date-time
          nullable: true
    InsertEvent:
      type: object
      description: >-
        A single event (trace span, experiment row, or dataset record). Events
        are merged/upserted by id.
      properties:
        id:
          type: string
          description: A unique identifier for the event. If omitted, one is generated.
        input:
          description: The arguments that uniquely define a test case or trace input.
        output:
          description: The output of your application for the given input.
        expected:
          description: The ground-truth value to compare against.
        scores:
          type: object
          additionalProperties:
            type: number
            nullable: true
          description: A map of score names to score values between 0 and 1.
        metadata:
          type: object
          additionalProperties: true
        tags:
          type: array
          items:
            type: string
        metrics:
          type: object
          additionalProperties: true
        span_attributes:
          type: object
          additionalProperties: true
        _is_merge:
          type: boolean
          description: If true, this event is merged into an existing event with the same id.
    InsertEventsResponse:
      type: object
      properties:
        row_ids:
          type: array
          description: The ids of all rows that were inserted, aligning with the input order.
          items:
            type: string
    FeedbackItem:
      type: object
      required:
        - id
      properties:
        id:
          type: string
          description: The id of the event to provide feedback for.
        scores:
          type: object
          additionalProperties:
            type: number
            nullable: true
        expected:
          description: The ground truth value the event should have produced.
        comment:
          type: string
        metadata:
          type: object
          additionalProperties: true
        source:
          type: string
          enum:
            - app
            - api
            - external
    FetchEventsRequest:
      type: object
      properties:
        limit:
          type: integer
          description: Maximum number of events to return.
        max_xact_id:
          type: string
          description: Pagination cursor - the maximum transaction id from a previous page.
        max_root_span_id:
          type: string
          description: Pagination cursor - the maximum root span id from a previous page.
        version:
          type: string
        filters:
          type: array
          description: A list of filters to apply, using path-lookup style.
          items:
            type: object
            additionalProperties: true
    FetchEventsResponse:
      type: object
      properties:
        events:
          type: array
          items:
            type: object
            additionalProperties: true
        cursor:
          type: string
          nullable: true
          description: A pagination cursor to pass to fetch the next page of events.
    SummarizeExperimentResponse:
      type: object
      properties:
        project_name:
          type: string
        experiment_name:
          type: string
        project_url:
          type: string
        experiment_url:
          type: string
        comparison_experiment_name:
          type: string
          nullable: true
        scores:
          type: object
          nullable: true
          additionalProperties:
            type: object
            properties:
              name:
                type: string
              score:
                type: number
              diff:
                type: number
                nullable: true
              improvements:
                type: integer
              regressions:
                type: integer
        metrics:
          type: object
          nullable: true
          additionalProperties: true
    EvalLaunchRequest:
      type: object
      required:
        - project_id
        - data
        - task
        - scores
      properties:
        project_id:
          type: string
          format: uuid
        experiment_name:
          type: string
        data:
          description: A dataset id, dataset name, or inline dataset definition to evaluate over.
          oneOf:
            - type: object
              additionalProperties: true
            - type: string
        task:
          description: A function id or slug naming the task function to run over each input.
          oneOf:
            - type: object
              additionalProperties: true
            - type: string
        scores:
          type: array
          description: A list of scoring functions (by id, slug, or inline) to apply.
          items:
            oneOf:
              - type: object
                additionalProperties: true
              - type: string
        metadata:
          type: object
          additionalProperties: true
        stream:
          type: boolean
    ChatCompletionRequest:
      type: object
      required:
        - model
        - messages
      properties:
        model:
          type: string
        messages:
          type: array
          items:
            type: object
            properties:
              role:
                type: string
                enum:
                  - system
                  - user
                  - assistant
                  - tool
              content:
                type: string
        temperature:
          type: number
          nullable: true
        max_tokens:
          type: integer
          nullable: true
        stream:
          type: boolean
        tools:
          type: array
          items:
            type: object
            additionalProperties: true
    ChatCompletionResponse:
      type: object
      properties:
        id:
          type: string
        object:
          type: string
        created:
          type: integer
        model:
          type: string
        choices:
          type: array
          items:
            type: object
            properties:
              index:
                type: integer
              message:
                type: object
                properties:
                  role:
                    type: string
                  content:
                    type: string
                    nullable: true
              finish_reason:
                type: string
                nullable: true
        usage:
          type: object
          properties:
            prompt_tokens:
              type: integer
            completion_tokens:
              type: integer
            total_tokens:
              type: integer