Braintrust Prompts API

openapi: 3.1.1
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:
    ResponseFormatNullish:
      anyOf:
      - type: object
        properties:
          type:
            type: string
            enum:
            - json_object
        required:
        - type
        title: json_object
      - type: object
        properties:
          type:
            type: string
            enum:
            - json_schema
          json_schema:
            $ref: '#/components/schemas/ResponseFormatJsonSchema'
        required:
        - type
        - json_schema
        title: json_schema
      - type: object
        properties:
          type:
            type: string
            enum:
            - text
        required:
        - type
        title: text
      - type: 'null'
    PromptOptionsNullish:
      type: object
      nullable: true
      properties:
        model:
          type: string
        params:
          $ref: '#/components/schemas/ModelParams'
        position:
          type: string
    OrgName:
      type: string
      description: Filter search results to within a particular organization
    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'').'
    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
    PromptEnvironment:
      type: string
      description: 'Filter by environment slug. Cannot be used together with `version`.


        For `GET /v1/prompt`, environment resolution currently requires the request to match a single prompt. If multiple prompts match, the endpoint returns `400` (for example when `limit=1` is not set). Use `limit=1` or other filters (for example `slug`, `project_id`) to narrow results.'
    Slug:
      type: string
      description: Retrieve prompt with a specific slug
    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
    Prompt:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier for the prompt
        _xact_id:
          type: string
          description: The transaction id of an event is unique to the network operation that processed the event insertion. Transaction ids are monotonically increasing over time and can be used to retrieve a versioned snapshot of the prompt (see the `version` parameter)
        project_id:
          type: string
          format: uuid
          description: Unique identifier for the project that the prompt belongs under
        log_id:
          type: string
          enum:
          - p
          description: A literal 'p' which identifies the object as a project prompt
        org_id:
          type: string
          format: uuid
          description: Unique identifier for the organization
        name:
          type: string
          description: Name of the prompt
        slug:
          type: string
          description: Unique identifier for the prompt
        description:
          type: string
          nullable: true
          description: Textual description of the prompt
        created:
          type: string
          nullable: true
          format: date-time
          description: Date of prompt creation
        prompt_data:
          $ref: '#/components/schemas/PromptDataNullish'
        tags:
          type: array
          nullable: true
          items:
            type: string
          description: A list of tags for the prompt
        metadata:
          type: object
          nullable: true
          additionalProperties:
            nullable: true
          description: User-controlled metadata about the prompt
        function_type:
          $ref: '#/components/schemas/FunctionTypeEnumNullish'
      required:
      - id
      - _xact_id
      - project_id
      - log_id
      - org_id
      - name
      - slug
    ChatCompletionContentPart:
      anyOf:
      - $ref: '#/components/schemas/ChatCompletionContentPartTextWithTitle'
      - $ref: '#/components/schemas/ChatCompletionContentPartImageWithTitle'
      - $ref: '#/components/schemas/ChatCompletionContentPartFileWithTitle'
      title: chat_completion_content_part
    AppLimitParam:
      type: integer
      nullable: true
      minimum: 0
      description: Limit the number of objects to return
    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
    PromptName:
      type: string
      description: Name of the prompt to search for
    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
    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.'
    ChatCompletionContentPartFileWithTitle:
      type: object
      properties:
        file:
          $ref: '#/components/schemas/ChatCompletionContentPartFileFile'
        type:
          type: string
          enum:
          - file
      required:
      - file
      - type
      title: file
    ChatCompletionContentPartImageWithTitle:
      type: object
      properties:
        image_url:
          type: object
          properties:
            url:
              type: string
            detail:
              anyOf:
              - type: string
                enum:
                - auto
                title: auto
              - type: string
                enum:
                - low
                title: low
              - type: string
                enum:
                - high
                title: high
          required:
          - url
        type:
          type: string
          enum:
          - image_url
      required:
      - image_url
      - type
      title: image_url
    ProjectName:
      type: string
      description: Name of the project to search for
    PromptIdParam:
      type: string
      format: uuid
      description: Prompt id
    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'.
    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`'
    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
    ProjectIdQuery:
      type: string
      format: uuid
      description: Project id
    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 definitions.
            - type: object
              properties:
                type:
                  type: string
                  enum:
                  - url
                url:
                  type: string
                is_disabled:
                  type: boolean
                enabled_tools:
                  type: array
                  nullable: true
                  items:
                    type: string
                  description: If omitted, all tools are enabled
              required:
              - type
              - url
              title: MCP server url. This is used for inline definitions of MCP servers.
        origin:
          type: object
          nullable: true
          properties:
            prompt_id:
              type: string
            project_id:
              type: string
            prompt_version:
              type: string
      description: The prompt, model, and its parameters
    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
    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:

# --- 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