Braintrust Prompts API

openapi: 3.2.0
info:
  version: 1.0.0
  title: Braintrust Acls Prompts 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: Prompts
paths:
  /v1/prompt:
    post:
      tags:
      - Prompts
      security:
      - bearerAuth: []
      - {}
      operationId: postPrompt
      description: Create a new prompt. If there is an existing prompt in the project with the same slug as the one specified in the request, will return the existing prompt unmodified
      summary: Create prompt
      requestBody:
        description: Any desired information about the new prompt object
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreatePrompt'
      responses:
        '200':
          description: Returns the new prompt object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Prompt'
        '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:
      - Prompts
      security:
      - bearerAuth: []
      - {}
      operationId: putPrompt
      description: Create or replace prompt. If there is an existing prompt in the project with the same slug as the one specified in the request, will replace the existing prompt with the provided fields
      summary: Create or replace prompt
      requestBody:
        description: Any desired information about the new prompt object
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreatePrompt'
      responses:
        '200':
          description: Returns the new prompt object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Prompt'
        '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: getPrompt
      tags:
      - Prompts
      description: List out all prompts. The prompts are sorted by creation date, with the most recently-created prompts coming first
      summary: List prompts
      security:
      - bearerAuth: []
      - {}
      parameters:
      - $ref: '#/components/parameters/AppLimitParam'
      - $ref: '#/components/parameters/StartingAfter'
      - $ref: '#/components/parameters/EndingBefore'
      - $ref: '#/components/parameters/Ids'
      - $ref: '#/components/parameters/PromptName'
      - $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 prompt objects
          content:
            application/json:
              schema:
                type: object
                properties:
                  objects:
                    type: array
                    items:
                      $ref: '#/components/schemas/Prompt'
                    description: A list of prompt 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/prompt/{prompt_id}:
    get:
      operationId: getPromptId
      tags:
      - Prompts
      description: Get a prompt object by its id
      summary: Get prompt
      security:
      - bearerAuth: []
      - {}
      parameters:
      - $ref: '#/components/parameters/PromptIdParam'
      - $ref: '#/components/parameters/PromptVersion'
      - $ref: '#/components/parameters/PromptEnvironment'
      responses:
        '200':
          description: Returns the prompt object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Prompt'
        '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: patchPromptId
      tags:
      - Prompts
      description: Partially update a prompt 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 prompt
      security:
      - bearerAuth: []
      - {}
      parameters:
      - $ref: '#/components/parameters/PromptIdParam'
      requestBody:
        description: Fields to update
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatchPrompt'
      responses:
        '200':
          description: Returns the prompt object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Prompt'
        '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: deletePromptId
      tags:
      - Prompts
      description: Delete a prompt object by its id
      summary: Delete prompt
      security:
      - bearerAuth: []
      - {}
      parameters:
      - $ref: '#/components/parameters/PromptIdParam'
      responses:
        '200':
          description: Returns the deleted prompt object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Prompt'
        '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:
    PromptIdParam:
      type: string
      format: uuid
      description: Prompt id
    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`'
    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
    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
    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
    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
    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'
    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
    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.
    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
    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:
            anyOf:
            - type: string
              default: ''
              title: text
            - type: array
              items:
                $ref: '#/components/schemas/ChatCompletionContentPart'
              title: array
          role:
            type: string
            enum:
            - user
          name:
            type: string
        required:
        - role
        title: user
      - type: object
        properties:
          role:
            type: string
            enum:
            - assistant
          content:
            anyOf:
            - type: string
            - type: array
              items:
                $ref: '#/components/schemas/ChatCompletionContentPartText'
            - type: 'null'
          function_call:
            type: object
            nullable: true
            properties:
              arguments:
                type: string
              name:
                type: string
            required:
            - arguments
            - name
          name:
            type: string
            nullable: true
          tool_calls:
            type: array
            nullable: true
            items:
              $ref: '#/components/schemas/ChatCompletionMessageToolCall'
          reasoning:
            type: array
            nullable: true
            items:
              $ref: '#/components/schemas/ChatCompletionMessageReasoning'
          reasoning_signature:
            type: string
            nullable: true
        required:
        - role
        title: assistant
      - type: object
        properties:
          content:
            anyOf:
            - type: string
              default: ''
              title: text
            - type: array
              items:
                $ref: '#/components/schemas/ChatCompletionContentPartText'
              title: array
          role:
            type: string
            enum:
            - tool
          tool_call_id:
            type: string
            default: ''
        required:
        - role
        title: tool
      - type: object
        properties:
          content:
            type: string
            nullable: true
          name:
            type: string
          role:
            type: string
            enum:
            - function
        required:
        - content
        - name
        - role
        title: function
      - type: object
        properties:
          content:
            anyOf:
            - type: string
              default: ''
              title: text
            - type: array
              items:
                $ref: '#/components/schemas/ChatCompletionContentPartText'
              title: array
          role:
            type: string
            enum:
            - developer
          name:
            type: string
        required:
        - role
        title: developer
      - type: object
        properties:
          role:
            type: string
            enum:
            - model
          content:
            type: string
            nullable: true
        required:
        - role
        title: fallback
    ChatCompletionMessageReasoning:
      type: object
      properties:
        id:
          type: string
          nullable: true
        content:
          type: string
          nullable: true
      description: 'Note: This is not part of the OpenAI API spec, but we added it for interoperability with multiple reasoning models.'
    ModelParams:
      anyOf:
      - type: object
        properties:
          use_cache:
            type: boolean
          reasoning_enabled:
            type: boolean
          reasoning_budget:
            type: number
          temperature:
            type: number
          top_p:
            type: number
          max_tokens:
            type: number
          max_completion_tokens:
            type: number
            description: The successor to max_tokens
          frequency_penalty:
            type: number
          presence_penalty:
            type: number
          response_format:
            $ref: '#/components/schemas/ResponseFormatNullish'
          tool_choice:
            anyOf:
            - type: string
              enum:
              - auto
              title: auto
            - type: string
              enum:
              - none
              title: none
            - type: string
              enum:
              - required
              title: required
            - type: object
              properties:
                type:
                  type: string
                  enum:
                  - function
                function:
                  type: object
                  properties:
                    name:
                      type: string
                  required:
                  - name
              required:
              - type
              - function
              title: function
          function_call:
            anyOf:
            - type: string
              enum:
              - auto
              title: auto
            - type: string
              enum:
              - none
              title: none
            - type: object
              properties:
                name:
                  type: string
              required:
              - name
              title: function
          n:
            type: number
          stop:
            type: array
            items:
              type: string
          reasoning_effort:
            type: string
            enum:
            - none
            - minimal
            - low
            - medium
            - high
          verbosity:
            type: string
            enum:
            - low
            - medium
            - high
        additionalProperties:
          nullable: true
        title: OpenAIModelParams
        x-stainless-skip:
        - go
      - type: object
        properties:
          use_cache:
            type: boolean
          reasoning_enabled:
            type: boolean
          reasoning_budget:
            type: number
          max_tokens:
            type: number
          temperature:
            type: number
          top_p:
            type: number
          top_k:
            type: number
          stop_sequences:
            type: array
            items:
              type: string
          max_tokens_to_sample:
            type: number
            description: This is a legacy parameter that should not be used.
        required:
        - max_tokens
        - temperature
        additionalProperties:
          nullable: true
        title: AnthropicModelParams
        x-stainless-skip:
        - go
      - type: object
        properties:
          use_cache:
            type: boolean
          reasoning_enabled:
            type: boolean
          reasoning_budget:
            type: number
          temperature:
            type: number
          maxOutputTokens:
            type: number
          topP:
            type: number
          topK:
            type: number
        additionalProperties:
          nullable: true
        title: GoogleModelParams
        x-stainless-skip:
        - go
      - type: object
        properties:
          use_cache:
            type: boolean
          reasoning_enabled:
            type: boolean
          reasoning_budget:
            type: number
          temperature:
            type: number
          topK:
            type: number
        additionalProperties:
          nullable: true
        title: WindowAIModelParams
        x-stainless-skip:
        - go
      - type: object
        properties:
          use_cache:
            type: boolean
          reasoning_enabled:
            type: boolean
          reasoning_budget:
            type: number
        additionalProperties:
          nullable: true
        title: JsCompletionParams
        x-stainless-skip:
        - go
    ResponseFormatJsonSchema:
      type: object
      properties:
        name:
          type: string
        description:
          type: string
        schema:
          anyOf:
          - type: object
            additionalProperties:
              nullable: true
            title: object
            x-stainless-skip:
            - go
          - type: string
            title: string
        strict:
          type: boolean
          nullable: true
      required:
      - name
    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
    CreatePrompt:
      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'
      required:
      - project_id
      - name
      - slug
    ChatCompletionContentPart:
      anyOf:
      - $ref: '#/components/schemas/ChatCompletionContentPartTextWithTitle'
      - $ref: '#/components/schemas/ChatCompletionContentPartImageWithTitle'
      - $ref: '#/components/schemas/ChatCompletionContentPartFileWithTitle'
      title: chat_completion_content_part
    PromptVersion:
      type: string
      description: 'Retrieve prompt at a specific version.


        The version id can either be a transaction id (e.g. ''1000192656880881099'') or a version identifier (e.g. ''81cd05ee665fdfb3'').'
    ChatCompletionContentPartTextWithTitle:
      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
      title: text
    PromptOptionsNullish:
      type: object
      nullable: true
      properties:
        model:
          type: string
        params:
          $ref: '#/components/schemas/ModelParams'
        position:
          type: string
    PromptDataNullish:
      type: object
      nullable: true
      properties:
        prompt:
          $ref: '#/components/schemas/PromptBlockDataNullish'
        options:
          $ref: '#/components/schemas/PromptOptionsNullish'
        parser:
          $ref: '#/components/schemas/PromptParserNullish'
        tool_functions:
          type: array
          nullable: true
          items:
            allOf:
            - $ref: '#/components/schemas/SavedFunctionId'
            - 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
        template_format:
          type: string
          nullable: true
          enum:
          - mustache
          - nunjucks
          - none
          - null
        mcp:
          type: object
          nullable: true
          additionalProperties:
            oneOf:
            - type: object
              properties:
                type:
                  type: string
                  enum:
                  - id
                id:
                  type: string
                  format: uuid
                is_disabled:
                  type: boolean
                enabled_tools:
                  type: array
                  nullable: true
                  items:
                    type: string
                  description: If omitted, all tools are enabled
              required:
              - type
              - id
              title: MCP server id. This is used for project-level MCP server defini

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