Braintrust Projects API

openapi: 3.2.0
info:
  version: 1.0.0
  title: Braintrust Acls Projects API
  description: 'API specification for the backend data server. The API is hosted globally at

    https://api.braintrust.dev or in your own environment.


    You can access the OpenAPI spec for this API at https://github.com/braintrustdata/braintrust-openapi.'
  license:
    name: Apache 2.0
servers:
- url: https://api.braintrust.dev
security:
- bearerAuth: []
- {}
tags:
- name: Projects
paths:
  /v1/project:
    post:
      tags:
      - Projects
      security:
      - bearerAuth: []
      - {}
      operationId: postProject
      description: Create a new project. If there is an existing project with the same name as the one specified in the request, will return the existing project unmodified
      summary: Create project
      requestBody:
        description: Any desired information about the new project object
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateProject'
      responses:
        '200':
          description: Returns the new project object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Project'
        '400':
          description: The request was unacceptable, often due to missing a required parameter
          content:
            text/plain:
              schema:
                type: string
            application/json:
              schema:
                nullable: true
        '401':
          description: No valid API key provided
          content:
            text/plain:
              schema:
                type: string
            application/json:
              schema:
                nullable: true
        '403':
          description: The API key doesn’t have permissions to perform the request
          content:
            text/plain:
              schema:
                type: string
            application/json:
              schema:
                nullable: true
        '429':
          description: Too many requests hit the API too quickly. We recommend an exponential backoff of your requests
          headers:
            Retry-After:
              schema:
                type: string
          content:
            text/plain:
              schema:
                type: string
            application/json:
              schema:
                nullable: true
        '500':
          description: Something went wrong on Braintrust's end. (These are rare.)
          content:
            text/plain:
              schema:
                type: string
            application/json:
              schema:
                nullable: true
    get:
      operationId: getProject
      tags:
      - Projects
      description: List out all projects. The projects are sorted by creation date, with the most recently-created projects coming first
      summary: List projects
      security:
      - bearerAuth: []
      - {}
      parameters:
      - $ref: '#/components/parameters/AppLimitParam'
      - $ref: '#/components/parameters/StartingAfter'
      - $ref: '#/components/parameters/EndingBefore'
      - $ref: '#/components/parameters/Ids'
      - $ref: '#/components/parameters/ProjectName'
      - $ref: '#/components/parameters/OrgName'
      responses:
        '200':
          description: Returns a list of project objects
          content:
            application/json:
              schema:
                type: object
                properties:
                  objects:
                    type: array
                    items:
                      $ref: '#/components/schemas/Project'
                    description: A list of project objects
                required:
                - objects
                additionalProperties: false
        '400':
          description: The request was unacceptable, often due to missing a required parameter
          content:
            text/plain:
              schema:
                type: string
            application/json:
              schema:
                nullable: true
        '401':
          description: No valid API key provided
          content:
            text/plain:
              schema:
                type: string
            application/json:
              schema:
                nullable: true
        '403':
          description: The API key doesn’t have permissions to perform the request
          content:
            text/plain:
              schema:
                type: string
            application/json:
              schema:
                nullable: true
        '429':
          description: Too many requests hit the API too quickly. We recommend an exponential backoff of your requests
          headers:
            Retry-After:
              schema:
                type: string
          content:
            text/plain:
              schema:
                type: string
            application/json:
              schema:
                nullable: true
        '500':
          description: Something went wrong on Braintrust's end. (These are rare.)
          content:
            text/plain:
              schema:
                type: string
            application/json:
              schema:
                nullable: true
  /v1/project/{project_id}:
    get:
      operationId: getProjectId
      tags:
      - Projects
      description: Get a project object by its id
      summary: Get project
      security:
      - bearerAuth: []
      - {}
      parameters:
      - $ref: '#/components/parameters/ProjectIdParam'
      responses:
        '200':
          description: Returns the project object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Project'
        '400':
          description: The request was unacceptable, often due to missing a required parameter
          content:
            text/plain:
              schema:
                type: string
            application/json:
              schema:
                nullable: true
        '401':
          description: No valid API key provided
          content:
            text/plain:
              schema:
                type: string
            application/json:
              schema:
                nullable: true
        '403':
          description: The API key doesn’t have permissions to perform the request
          content:
            text/plain:
              schema:
                type: string
            application/json:
              schema:
                nullable: true
        '429':
          description: Too many requests hit the API too quickly. We recommend an exponential backoff of your requests
          headers:
            Retry-After:
              schema:
                type: string
          content:
            text/plain:
              schema:
                type: string
            application/json:
              schema:
                nullable: true
        '500':
          description: Something went wrong on Braintrust's end. (These are rare.)
          content:
            text/plain:
              schema:
                type: string
            application/json:
              schema:
                nullable: true
    patch:
      operationId: patchProjectId
      tags:
      - Projects
      description: Partially update a project object. Specify the fields to update in the payload. Any object-type fields will be deep-merged with existing content. Currently we do not support removing fields or setting them to null.
      summary: Partially update project
      security:
      - bearerAuth: []
      - {}
      parameters:
      - $ref: '#/components/parameters/ProjectIdParam'
      requestBody:
        description: Fields to update
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatchProject'
      responses:
        '200':
          description: Returns the project object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Project'
        '400':
          description: The request was unacceptable, often due to missing a required parameter
          content:
            text/plain:
              schema:
                type: string
            application/json:
              schema:
                nullable: true
        '401':
          description: No valid API key provided
          content:
            text/plain:
              schema:
                type: string
            application/json:
              schema:
                nullable: true
        '403':
          description: The API key doesn’t have permissions to perform the request
          content:
            text/plain:
              schema:
                type: string
            application/json:
              schema:
                nullable: true
        '429':
          description: Too many requests hit the API too quickly. We recommend an exponential backoff of your requests
          headers:
            Retry-After:
              schema:
                type: string
          content:
            text/plain:
              schema:
                type: string
            application/json:
              schema:
                nullable: true
        '500':
          description: Something went wrong on Braintrust's end. (These are rare.)
          content:
            text/plain:
              schema:
                type: string
            application/json:
              schema:
                nullable: true
    delete:
      operationId: deleteProjectId
      tags:
      - Projects
      description: Delete a project object by its id
      summary: Delete project
      security:
      - bearerAuth: []
      - {}
      parameters:
      - $ref: '#/components/parameters/ProjectIdParam'
      responses:
        '200':
          description: Returns the deleted project object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Project'
        '400':
          description: The request was unacceptable, often due to missing a required parameter
          content:
            text/plain:
              schema:
                type: string
            application/json:
              schema:
                nullable: true
        '401':
          description: No valid API key provided
          content:
            text/plain:
              schema:
                type: string
            application/json:
              schema:
                nullable: true
        '403':
          description: The API key doesn’t have permissions to perform the request
          content:
            text/plain:
              schema:
                type: string
            application/json:
              schema:
                nullable: true
        '429':
          description: Too many requests hit the API too quickly. We recommend an exponential backoff of your requests
          headers:
            Retry-After:
              schema:
                type: string
          content:
            text/plain:
              schema:
                type: string
            application/json:
              schema:
                nullable: true
        '500':
          description: Something went wrong on Braintrust's end. (These are rare.)
          content:
            text/plain:
              schema:
                type: string
            application/json:
              schema:
                nullable: true
components:
  schemas:
    OrgName:
      type: string
      description: Filter search results to within a particular organization
    StartingAfter:
      type: string
      format: uuid
      description: 'Pagination cursor id.


        For example, if the final item in the last page you fetched had an id of `foo`, pass `starting_after=foo` to fetch the next page. Note: you may only pass one of `starting_after` and `ending_before`'
    PatchProject:
      type: object
      properties:
        name:
          type: string
          nullable: true
          description: Name of the project
        description:
          type: string
          nullable: true
        user_id:
          type: string
          nullable: true
        settings:
          allOf:
          - $ref: '#/components/schemas/ProjectSettings'
          - description: Project settings. Patch operations replace all settings, so make sure you include all settings you want to keep.
    EndingBefore:
      type: string
      format: uuid
      description: 'Pagination cursor id.


        For example, if the initial item in the last page you fetched had an id of `foo`, pass `ending_before=foo` to fetch the previous page. Note: you may only pass one of `starting_after` and `ending_before`'
    Project:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier for the project
        org_id:
          type: string
          format: uuid
          description: Unique id for the organization that the project belongs under
        name:
          type: string
          description: Name of the project
        description:
          type: string
          nullable: true
          description: Textual description of the project
        created:
          type: string
          nullable: true
          format: date-time
          description: Date of project creation
        deleted_at:
          type: string
          nullable: true
          format: date-time
          description: Date of project deletion, or null if the project is still active
        user_id:
          type: string
          nullable: true
          format: uuid
          description: Identifies the user who created the project
        settings:
          $ref: '#/components/schemas/ProjectSettings'
      required:
      - id
      - org_id
      - name
    Ids:
      anyOf:
      - type: string
        format: uuid
      - type: array
        items:
          type: string
          format: uuid
      description: Filter search results to a particular set of object IDs. To specify a list of IDs, include the query param multiple times
    CreateProject:
      type: object
      properties:
        name:
          type: string
          minLength: 1
          description: Name of the project
        description:
          type: string
          nullable: true
          description: Textual description of the project
        org_name:
          type: string
          nullable: true
          description: For nearly all users, this parameter should be unnecessary. But in the rare case that your API key belongs to multiple organizations, you may specify the name of the organization the project belongs in.
      required:
      - name
    ProjectSettings:
      type: object
      nullable: true
      properties:
        comparison_key:
          type: string
          nullable: true
          description: The key used to join two experiments (defaults to `input`)
        baseline_experiment_id:
          type: string
          nullable: true
          format: uuid
          description: The id of the experiment to use as the default baseline for comparisons
        spanFieldOrder:
          type: array
          nullable: true
          items:
            type: object
            properties:
              object_type:
                type: string
              column_id:
                type: string
              position:
                type: string
              layout:
                anyOf:
                - type: string
                  enum:
                  - full
                - type: string
                  enum:
                  - two_column
                - type: 'null'
            required:
            - object_type
            - column_id
            - position
          description: The order of the fields to display in the trace view
        remote_eval_sources:
          type: array
          nullable: true
          items:
            type: object
            properties:
              url:
                type: string
              name:
                type: string
                nullable: true
              description:
                type: string
                nullable: true
            required:
            - url
          description: The remote eval sources to use for the project
        disable_realtime_queries:
          type: boolean
          nullable: true
          description: If true, disable real-time queries for this project. This can improve query performance for high-volume logs.
        default_preprocessor:
          $ref: '#/components/schemas/NullableSavedFunctionId'
    FunctionTypeEnum:
      type: string
      enum:
      - llm
      - scorer
      - task
      - tool
      - custom_view
      - preprocessor
      - facet
      - classifier
      - tag
      - parameters
      - sandbox
      - null
      default: scorer
      description: The type of global function. Defaults to 'scorer'.
    AppLimitParam:
      type: integer
      nullable: true
      minimum: 0
      description: Limit the number of objects to return
    ProjectName:
      type: string
      description: Name of the project to search for
    NullableSavedFunctionId:
      anyOf:
      - type: object
        properties:
          type:
            type: string
            enum:
            - function
          id:
            type: string
          version:
            type: string
            description: The version of the function
        required:
        - type
        - id
        title: function
      - type: object
        properties:
          type:
            type: string
            enum:
            - global
          name:
            type: string
          function_type:
            $ref: '#/components/schemas/FunctionTypeEnum'
        required:
        - type
        - name
        title: global
      - type: 'null'
      description: Default preprocessor for this project. When set, functions that use preprocessors will use this instead of their built-in default.
    ProjectIdParam:
      type: string
      format: uuid
      description: Project id
  parameters:
    ProjectIdParam:
      schema:
        $ref: '#/components/schemas/ProjectIdParam'
      required: true
      description: Project id
      name: project_id
      in: path
    StartingAfter:
      schema:
        $ref: '#/components/schemas/StartingAfter'
      required: false
      description: 'Pagination cursor id.


        For example, if the final item in the last page you fetched had an id of `foo`, pass `starting_after=foo` to fetch the next page. Note: you may only pass one of `starting_after` and `ending_before`'
      name: starting_after
      in: query
    OrgName:
      schema:
        $ref: '#/components/schemas/OrgName'
      required: false
      description: Filter search results to within a particular organization
      name: org_name
      in: query
      allowReserved: true
    AppLimitParam:
      schema:
        $ref: '#/components/schemas/AppLimitParam'
      required: false
      description: Limit the number of objects to return
      name: limit
      in: query
    ProjectName:
      schema:
        $ref: '#/components/schemas/ProjectName'
      required: false
      description: Name of the project to search for
      name: project_name
      in: query
      allowReserved: true
    Ids:
      schema:
        $ref: '#/components/schemas/Ids'
      required: false
      description: Filter search results to a particular set of object IDs. To specify a list of IDs, include the query param multiple times
      name: ids
      in: query
    EndingBefore:
      schema:
        $ref: '#/components/schemas/EndingBefore'
      required: false
      description: 'Pagination cursor id.


        For example, if the initial item in the last page you fetched had an id of `foo`, pass `ending_before=foo` to fetch the previous page. Note: you may only pass one of `starting_after` and `ending_before`'
      name: ending_before
      in: query
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API key or JWT
      description: 'Most Braintrust endpoints are authenticated by providing your API key as a header `Authorization: Bearer [api_key]` to your HTTP request. You can create an API key in the Braintrust [organization settings page](https://www.braintrustdata.com/app/settings?subroute=api-keys).'