Braintrust Functions API

openapi: 3.2.0
info:
  version: 1.0.0
  title: Braintrust Acls Functions 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: Functions
paths:
  /v1/function:
    post:
      tags:
      - Functions
      security:
      - bearerAuth: []
      - {}
      operationId: postFunction
      description: Create a new function. If there is an existing function in the project with the same slug as the one specified in the request, will return the existing function unmodified
      summary: Create function
      requestBody:
        description: Any desired information about the new function object
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateFunction'
      responses:
        '200':
          description: Returns the new function object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Function'
        '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
    put:
      tags:
      - Functions
      security:
      - bearerAuth: []
      - {}
      operationId: putFunction
      description: Create or replace function. If there is an existing function in the project with the same slug as the one specified in the request, will replace the existing function with the provided fields
      summary: Create or replace function
      requestBody:
        description: Any desired information about the new function object
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateFunction'
      responses:
        '200':
          description: Returns the new function object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Function'
        '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: getFunction
      tags:
      - Functions
      description: List out all functions. The functions are sorted by creation date, with the most recently-created functions coming first
      summary: List functions
      security:
      - bearerAuth: []
      - {}
      parameters:
      - $ref: '#/components/parameters/AppLimitParam'
      - $ref: '#/components/parameters/StartingAfter'
      - $ref: '#/components/parameters/EndingBefore'
      - $ref: '#/components/parameters/Ids'
      - $ref: '#/components/parameters/FunctionName'
      - $ref: '#/components/parameters/ProjectName'
      - $ref: '#/components/parameters/ProjectIdQuery'
      - $ref: '#/components/parameters/Slug'
      - $ref: '#/components/parameters/PromptVersion'
      - $ref: '#/components/parameters/PromptEnvironment'
      - $ref: '#/components/parameters/OrgName'
      responses:
        '200':
          description: Returns a list of function objects
          content:
            application/json:
              schema:
                type: object
                properties:
                  objects:
                    type: array
                    items:
                      $ref: '#/components/schemas/Function'
                    description: A list of function 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/function/{function_id}:
    get:
      operationId: getFunctionId
      tags:
      - Functions
      description: Get a function object by its id
      summary: Get function
      security:
      - bearerAuth: []
      - {}
      parameters:
      - $ref: '#/components/parameters/FunctionIdParam'
      - $ref: '#/components/parameters/PromptVersion'
      - $ref: '#/components/parameters/PromptEnvironment'
      responses:
        '200':
          description: Returns the function object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Function'
        '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: patchFunctionId
      tags:
      - Functions
      description: Partially update a function 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 function
      security:
      - bearerAuth: []
      - {}
      parameters:
      - $ref: '#/components/parameters/FunctionIdParam'
      requestBody:
        description: Fields to update
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatchFunction'
      responses:
        '200':
          description: Returns the function object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Function'
        '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: deleteFunctionId
      tags:
      - Functions
      description: Delete a function object by its id
      summary: Delete function
      security:
      - bearerAuth: []
      - {}
      parameters:
      - $ref: '#/components/parameters/FunctionIdParam'
      responses:
        '200':
          description: Returns the deleted function object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Function'
        '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/function/{function_id}/invoke:
    post:
      operationId: postFunctionIdInvoke
      tags:
      - Functions
      description: Invoke a function.
      summary: Invoke function
      security:
      - bearerAuth: []
      - {}
      parameters:
      - $ref: '#/components/parameters/FunctionIdParam'
      requestBody:
        description: Function invocation parameters
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InvokeApi'
      responses:
        '200':
          description: Function invocation response
          content:
            application/json:
              schema:
                nullable: true
components:
  schemas:
    CreateFunction:
      type: object
      properties:
        project_id:
          type: string
          format: uuid
          description: Unique identifier for the project that the prompt belongs under
        name:
          type: string
          minLength: 1
          description: Name of the prompt
        slug:
          type: string
          minLength: 1
          description: Unique identifier for the prompt
        description:
          type: string
          nullable: true
          description: Textual description of the prompt
        prompt_data:
          $ref: '#/components/schemas/PromptDataNullish'
        tags:
          type: array
          nullable: true
          items:
            type: string
          description: A list of tags for the prompt
        function_type:
          $ref: '#/components/schemas/FunctionTypeEnumNullish'
        function_data:
          $ref: '#/components/schemas/FunctionData'
        origin:
          type: object
          nullable: true
          properties:
            object_type:
              $ref: '#/components/schemas/AclObjectType'
            object_id:
              type: string
              format: uuid
              description: Id of the object the function is originating from
            internal:
              type: boolean
              nullable: true
              description: The function exists for internal purposes and should not be displayed in the list of functions.
          required:
          - object_type
          - object_id
        function_schema:
          type: object
          nullable: true
          properties:
            parameters:
              nullable: true
            returns:
              nullable: true
          description: JSON schema for the function's parameters and return type
      required:
      - project_id
      - name
      - slug
      - function_data
    OrgName:
      type: string
      description: Filter search results to within a particular organization
    ChatCompletionContentPartText:
      type: object
      properties:
        text:
          type: string
          default: ''
        type:
          type: string
          enum:
          - text
        cache_control:
          type: object
          properties:
            type:
              type: string
              enum:
              - ephemeral
          required:
          - type
      required:
      - type
    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`'
    ChatCompletionContentPartFileWithTitle:
      type: object
      properties:
        file:
          $ref: '#/components/schemas/ChatCompletionContentPartFileFile'
        type:
          type: string
          enum:
          - file
      required:
      - file
      - type
      title: file
    FunctionTypeEnumNullish:
      type: string
      nullable: true
      enum:
      - llm
      - scorer
      - task
      - tool
      - custom_view
      - preprocessor
      - facet
      - classifier
      - tag
      - parameters
      - sandbox
      - null
    GraphData:
      type: object
      properties:
        type:
          type: string
          enum:
          - graph
        nodes:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/GraphNode'
        edges:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/GraphEdge'
      required:
      - type
      - nodes
      - edges
      description: This feature is preliminary and unsupported.
      title: graph
    PromptBlockData:
      anyOf:
      - type: object
        properties:
          type:
            type: string
            enum:
            - chat
          messages:
            type: array
            items:
              $ref: '#/components/schemas/ChatCompletionMessageParam'
          tools:
            type: string
        required:
        - type
        - messages
        title: chat
      - type: object
        properties:
          type:
            type: string
            enum:
            - completion
          content:
            type: string
        required:
        - type
        - content
        title: completion
    GraphEdge:
      type: object
      properties:
        source:
          type: object
          properties:
            node:
              type: string
              maxLength: 1024
              description: The id of the node in the graph
            variable:
              type: string
          required:
          - node
          - variable
        target:
          type: object
          properties:
            node:
              type: string
              maxLength: 1024
              description: The id of the node in the graph
            variable:
              type: string
          required:
          - node
          - variable
        purpose:
          type: string
          enum:
          - control
          - data
          - messages
          description: The purpose of the edge
      required:
      - source
      - target
      - purpose
    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`'
    Slug:
      type: string
      description: Retrieve prompt with a specific slug
    BatchedFacetData:
      type: object
      properties:
        type:
          type: string
          enum:
          - batched_facet
        preprocessor:
          allOf:
          - $ref: '#/components/schemas/NullableSavedFunctionId'
          - description: The preprocessor function to use for facet extraction. If not provided, the project default preprocessor will be used, falling back to the global 'thread' preprocessor.
        facets:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
                description: The name of the facet
              prompt:
                type: string
                description: The prompt to use for LLM extraction. The preprocessed text will be provided as context.
              model:
                type: string
                description: The model to use for facet extraction
              embedding_model:
                type: string
                description: The embedding model to use for vectorizing facet results.
              no_match_pattern:
                type: string
                description: Regex pattern to identify outputs that do not match the facet. If the output matches, the facet will be saved as 'no_match'
            required:
            - name
            - prompt
        topic_maps:
          type: object
          additionalProperties:
            type: array
            items:
              type: object
              properties:
                function_name:
                  type: string
                  description: The name of the topic map function
                topic_map_id:
                  type: string
                  description: The id of the topic map function
                topic_map_data:
                  $ref: '#/components/schemas/TopicMapData'
              required:
              - function_name
              - topic_map_data
          description: Topic maps that depend on facets in this batch, keyed by source facet name. Each source facet can have multiple topic maps.
      required:
      - type
      - facets
      title: batched_facet
    FunctionDataNullish:
      anyOf:
      - type: object
        properties:
          type:
            type: string
            enum:
            - prompt
        required:
        - type
        title: prompt
      - type: object
        properties:
          type:
            type: string
            enum:
            - code
          data:
            anyOf:
            - allOf:
              - type: object
                properties:
                  type:
                    type: string
                    enum:
                    - bundle
                required:
                - type
              - $ref: '#/components/schemas/CodeBundle'
              title: bundle
            - type: object
              properties:
                type:
                  type: string
                  enum:
                  - inline
                runtime_context:
                  type: object
                  properties:
                    runtime:
                      type: string
                      enum:
                      - node
                      - python
                      - browser
                      - quickjs
                    version:
                      type: string
                  required:
                  - runtime
                  - version
                code:
                  type: string
                code_hash:
                  type: string
                  description: SHA256 hash of the code, computed at save time
              required:
              - type
              - runtime_context
              - code
              title: inline
        required:
        - type
        - data
        title: code
      - $ref: '#/components/schemas/GraphData'
      - type: object
        properties:
          type:
            type: string
            enum:
            - remote_eval
          endpoint:
            type: string
          eval_name:
            type: string
          parameters:
            type: object
            additionalProperties:
              nullable: true
          parameters_version:
            type: string
            nullable: true
            description: The version (transaction ID) of the parameters being used
        required:
        - type
        - endpoint
        - eval_name
        - parameters
        description: A remote eval to run
        title: remote_eval
      - type: object
        properties:
          type:
            type: string
            enum:
            - global
          name:
            type: string
          function_type:
            $ref: '#/components/schemas/FunctionTypeEnum'
          config:
            type: object
            nullable: true
            additionalProperties:
              nullable: true
            description: Configuration options to pass to the global function (e.g., for preprocessor customization)
        required:
        - type
        - name
        title: global
      - $ref: '#/components/schemas/FacetData'
      - $ref: '#/components/schemas/BatchedFacetData'
      - type: object
        properties:
          type:
            type: string
            enum:
            - parameters
          data:
            type: object
            additionalProperties:
              nullable: true
            description: The parameters data
          __schema:
            type: object
            properties:
              type:
                type: string
                enum:
                - object
              properties:
                type: object
                additionalProperties:
                  type: object
                  additionalProperties:
                    nullable: true
              required:
                type: array
                items:
                  type: string
              additionalProperties:
                type: boolean
            required:
            - type
            - properties
            description: JSON Schema format for parameters
        required:
        - type
        - data
        - __schema
        title: parameters
      - allOf:
        - $ref: '#/components/schemas/TopicMapData'
        - title: topic_map
      - type: 'null'
    PromptParserNullish:
      type: object
      nullable: true
      properties:
        type:
          type: string
          enum:
          - llm_classifier
        use_cot:
          type: boolean
        choice_scores:
          type: object
          additionalProperties:
            type: number
            minimum: 0
            maximum: 1
          description: Map of choices to scores (0-1). Used by scorers.
        choice:
          type: array
          items:
            type: string
          description: List of valid choices without score mapping. Used by classifiers that deposit output to tags.
        allow_no_match:
          type: boolean
          description: If true, adds a 'No match' option. When selected, no tag is deposited.
      required:
      - type
      - use_cot
    InvokeParent:
      anyOf:
      - type: object
        properties:
          object_type:
            type: string
            enum:
            - project_logs
            - experiment
            - playground_logs
          object_id:
            type: string
            description: The id of the container object you are logging to
          row_ids:
            type: object
            nullable: true
            properties:
              id:
                type: string
                description: The id of the row
              span_id:
                type: string
                description: The span_id of the row
              root_span_id:
                type: string
                description: The root_span_id of the row
            required:
            - id
            - span_id
            - root_span_id
            description: Identifiers for the row to to log a subspan under
          propagated_event:
            type: object
            nullable: true
            additionalProperties:
              nullable: true
            description: Include these properties in every span created under this parent
        required:
        - object_type
        - object_id
        description: Span parent properties
        title: span_parent_struct
      - type: string
        description: The parent's span identifier, created by calling `.export()` on a span
      description: Options for tracing the function call
    PromptBlockDataNullish:
      anyOf:
      - type: object
        properties:
          type:
            type: string
            enum:
            - chat
          messages:
            type: array
            items:
              $ref: '#/components/schemas/ChatCompletionMessageParam'
          tools:
            type: string
        required:
        - type
        - messages
        title: chat
      - type: object
        properties:
          type:
            type: string
            enum:
            - completion
          content:
            type: string
        required:
        - type
        - content
        title: completion
      - type: 'null'
    ChatCompletionMessageToolCall:
      type: object
      properties:
        id:
          type: string
        function:
          type: object
          properties:
            arguments:
              type: string
            name:
              type: string
          required:
          - arguments
          - name
        type:
          type: string
          enum:
          - function
      required:
      - id
      - function
      - type
    ChatCompletionContentPartFileFile:
      type: object
      properties:
        file_data:
          type: string
        filename:
          type: string
        file_id:
          type: string
          title: The ID of an uploaded file to use as input.
    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
    TopicMapGenerationSettings:
      type: object
      properties:
        algorithm:
          type: string
          enum:
          - hdbscan
          - kmeans
        dimension_reduction:
          type: string
          enum:
          - umap
          - pca
          - none
        sample_size:
          type: integer
          minimum: 0
          exclusiveMinimum: true
        n_clusters:
          type: integer
          minimum: 0
          exclusiveMinimum: true
        min_cluster_size:
          type: integer
          minimum: 0
          exclusiveMinimum: true
        min_samples:
          type: integer
          minimum: 0
          exclusiveMinimum: true
        hierarchy_threshold:
          type: integer
          minimum: 0
          exclusiveMinimum: true
        naming_model:
          type: string
      required:
      - algorithm
      - dimension_reduction
      description: Clustering and naming settings used to generate this topic map
    ChatCompletionMessageParam:
      anyOf:
      - type: object
        properties:
          content:
            anyOf:
            - type: string
              default: ''
              title: text
            - type: array
              items:
                $ref: '#/components/schemas/ChatCompletionContentPartText'
              title: array
          role:
            type: string
            enum:
            - system
          name:
            type: string
        required:
        - role
        title: system
      - type: object
        properties:
          content:
       

# --- truncated at 32 KB (74 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/braintrust/refs/heads/main/openapi/braintrust-functions-api-openapi.yml