Prompts - Docs - Braintrust

GET

/v1/prompt

List prompts

List out all prompts. The prompts are sorted by creation date, with the most recently-created prompts coming first

Most Braintrust endpoints are authenticated by providing your API key as a header Authorization: Bearer [api_key] to your HTTP request. You can create an API key in the Braintrust organization settings page.

In: header

Query Parameters

`limit`integer | null

Limit the number of objects to return

Minimum: 0

`starting_after`string

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

Format: "uuid"

`ending_before`string

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

Format: "uuid"

`ids`Any properties in string, array<string>

Filter search results to a particular set of object IDs. To specify a list of IDs, include the query param multiple times

`prompt_name`string

Name of the prompt to search for

`project_name`string

Name of the project to search for

`project_id`string

Project id

Format: "uuid"

`slug`string

Retrieve prompt with a specific slug

`version`string

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').

`org_name`string

Filter search results to within a particular organization

curl -X GET "https://api.braintrust.dev/v1/prompt?limit=0&starting_after=497f6eca-6276-4993-bfeb-53cbbbba6f08&ending_before=497f6eca-6276-4993-bfeb-53cbbbba6f08&ids=497f6eca-6276-4993-bfeb-53cbbbba6f08&prompt_name=string&project_name=string&project_id=497f6eca-6276-4993-bfeb-53cbbbba6f08&slug=string&version=string&org_name=string" \
  -H "Authorization: Bearer <token>"

Returns a list of prompt objects

{
  "objects": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "_xact_id": "string",
      "project_id": "405d8375-3514-403b-8c43-83ae74cfe0e9",
      "log_id": "p",
      "org_id": "a40f5d1f-d889-42e9-94ea-b9b33585fc6b",
      "name": "string",
      "slug": "string",
      "description": "string",
      "created": "2019-08-24T14:15:22Z",
      "prompt_data": {
        "prompt": {
          "type": "completion",
          "content": "string"
        },
        "options": {
          "model": "string",
          "params": {
            "use_cache": true,
            "temperature": 0,
            "top_p": 0,
            "max_tokens": 0,
            "max_completion_tokens": 0,
            "frequency_penalty": 0,
            "presence_penalty": 0,
            "response_format": {
              "type": "json_object"
            },
            "tool_choice": "auto",
            "function_call": "auto",
            "n": 0,
            "stop": [
              "string"
            ],
            "reasoning_effort": "low"
          },
          "position": "string"
        },
        "parser": {
          "type": "llm_classifier",
          "use_cot": true,
          "choice_scores": {
            "property1": 1,
            "property2": 1
          }
        },
        "tool_functions": [
          {
            "type": "function",
            "id": "string"
          }
        ],
        "origin": {
          "prompt_id": "string",
          "project_id": "string",
          "prompt_version": "string"
        }
      },
      "tags": [
        "string"
      ],
      "metadata": {
        "property1": null,
        "property2": null
      },
      "function_type": "llm"
    }
  ]
}

POST

/v1/prompt

Create prompt

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

Authorization

`Authorization`
Required
Bearer <token>

In: header

Request Body

application/jsonOptional

Any desired information about the new prompt object

`project_id`
Required
string

Unique identifier for the project that the prompt belongs under

Format: "uuid"

`name`
Required
string

Name of the prompt

Minimum length: 1

`slug`
Required
string

Unique identifier for the prompt

Minimum length: 1

`description`string | null

Textual description of the prompt

`prompt_data`object | null

The prompt, model, and its parameters

`tags`array<string> | null

A list of tags for the prompt

`function_type`string | null

Value in: "llm" | "scorer" | "task" | "tool" | null

curl -X POST "https://api.braintrust.dev/v1/prompt" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "project_id": "405d8375-3514-403b-8c43-83ae74cfe0e9",
    "name": "string",
    "slug": "string",
    "description": "string",
    "prompt_data": {
      "prompt": {
        "type": "completion",
        "content": "string"
      },
      "options": {
        "model": "string",
        "params": {
          "use_cache": true,
          "temperature": 0,
          "top_p": 0,
          "max_tokens": 0,
          "max_completion_tokens": 0,
          "frequency_penalty": 0,
          "presence_penalty": 0,
          "response_format": {
            "type": "json_object"
          },
          "tool_choice": "auto",
          "function_call": "auto",
          "n": 0,
          "stop": [
            "string"
          ],
          "reasoning_effort": "low"
        },
        "position": "string"
      },
      "parser": {
        "type": "llm_classifier",
        "use_cot": true,
        "choice_scores": {
          "property1": 1,
          "property2": 1
        }
      },
      "tool_functions": [
        {
          "type": "function",
          "id": "string"
        }
      ],
      "origin": {
        "prompt_id": "string",
        "project_id": "string",
        "prompt_version": "string"
      }
    },
    "tags": [
      "string"
    ],
    "function_type": "llm"
  }'

Returns the new prompt object

{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "_xact_id": "string",
  "project_id": "405d8375-3514-403b-8c43-83ae74cfe0e9",
  "log_id": "p",
  "org_id": "a40f5d1f-d889-42e9-94ea-b9b33585fc6b",
  "name": "string",
  "slug": "string",
  "description": "string",
  "created": "2019-08-24T14:15:22Z",
  "prompt_data": {
    "prompt": {
      "type": "completion",
      "content": "string"
    },
    "options": {
      "model": "string",
      "params": {
        "use_cache": true,
        "temperature": 0,
        "top_p": 0,
        "max_tokens": 0,
        "max_completion_tokens": 0,
        "frequency_penalty": 0,
        "presence_penalty": 0,
        "response_format": {
          "type": "json_object"
        },
        "tool_choice": "auto",
        "function_call": "auto",
        "n": 0,
        "stop": [
          "string"
        ],
        "reasoning_effort": "low"
      },
      "position": "string"
    },
    "parser": {
      "type": "llm_classifier",
      "use_cot": true,
      "choice_scores": {
        "property1": 1,
        "property2": 1
      }
    },
    "tool_functions": [
      {
        "type": "function",
        "id": "string"
      }
    ],
    "origin": {
      "prompt_id": "string",
      "project_id": "string",
      "prompt_version": "string"
    }
  },
  "tags": [
    "string"
  ],
  "metadata": {
    "property1": null,
    "property2": null
  },
  "function_type": "llm"
}

PUT

/v1/prompt

Create or replace prompt

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

Authorization

`Authorization`
Required
Bearer <token>

In: header

Request Body

application/jsonOptional

Any desired information about the new prompt object

`project_id`
Required
string

Unique identifier for the project that the prompt belongs under

Format: "uuid"

`name`
Required
string

Name of the prompt

Minimum length: 1

`slug`
Required
string

Unique identifier for the prompt

Minimum length: 1

`description`string | null

Textual description of the prompt

`prompt_data`object | null

The prompt, model, and its parameters

`tags`array<string> | null

A list of tags for the prompt

`function_type`string | null

Value in: "llm" | "scorer" | "task" | "tool" | null

curl -X PUT "https://api.braintrust.dev/v1/prompt" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "project_id": "405d8375-3514-403b-8c43-83ae74cfe0e9",
    "name": "string",
    "slug": "string",
    "description": "string",
    "prompt_data": {
      "prompt": {
        "type": "completion",
        "content": "string"
      },
      "options": {
        "model": "string",
        "params": {
          "use_cache": true,
          "temperature": 0,
          "top_p": 0,
          "max_tokens": 0,
          "max_completion_tokens": 0,
          "frequency_penalty": 0,
          "presence_penalty": 0,
          "response_format": {
            "type": "json_object"
          },
          "tool_choice": "auto",
          "function_call": "auto",
          "n": 0,
          "stop": [
            "string"
          ],
          "reasoning_effort": "low"
        },
        "position": "string"
      },
      "parser": {
        "type": "llm_classifier",
        "use_cot": true,
        "choice_scores": {
          "property1": 1,
          "property2": 1
        }
      },
      "tool_functions": [
        {
          "type": "function",
          "id": "string"
        }
      ],
      "origin": {
        "prompt_id": "string",
        "project_id": "string",
        "prompt_version": "string"
      }
    },
    "tags": [
      "string"
    ],
    "function_type": "llm"
  }'

Returns the new prompt object

{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "_xact_id": "string",
  "project_id": "405d8375-3514-403b-8c43-83ae74cfe0e9",
  "log_id": "p",
  "org_id": "a40f5d1f-d889-42e9-94ea-b9b33585fc6b",
  "name": "string",
  "slug": "string",
  "description": "string",
  "created": "2019-08-24T14:15:22Z",
  "prompt_data": {
    "prompt": {
      "type": "completion",
      "content": "string"
    },
    "options": {
      "model": "string",
      "params": {
        "use_cache": true,
        "temperature": 0,
        "top_p": 0,
        "max_tokens": 0,
        "max_completion_tokens": 0,
        "frequency_penalty": 0,
        "presence_penalty": 0,
        "response_format": {
          "type": "json_object"
        },
        "tool_choice": "auto",
        "function_call": "auto",
        "n": 0,
        "stop": [
          "string"
        ],
        "reasoning_effort": "low"
      },
      "position": "string"
    },
    "parser": {
      "type": "llm_classifier",
      "use_cot": true,
      "choice_scores": {
        "property1": 1,
        "property2": 1
      }
    },
    "tool_functions": [
      {
        "type": "function",
        "id": "string"
      }
    ],
    "origin": {
      "prompt_id": "string",
      "project_id": "string",
      "prompt_version": "string"
    }
  },
  "tags": [
    "string"
  ],
  "metadata": {
    "property1": null,
    "property2": null
  },
  "function_type": "llm"
}

GET

/v1/prompt/{prompt_id}

Get prompt

Get a prompt object by its id

Authorization

`Authorization`
Required
Bearer <token>

In: header

Path Parameters

`prompt_id`
Required
string

Prompt id

Format: "uuid"

curl -X GET "https://api.braintrust.dev/v1/prompt/497f6eca-6276-4993-bfeb-53cbbbba6f08" \
  -H "Authorization: Bearer <token>"

Returns the prompt object

{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "_xact_id": "string",
  "project_id": "405d8375-3514-403b-8c43-83ae74cfe0e9",
  "log_id": "p",
  "org_id": "a40f5d1f-d889-42e9-94ea-b9b33585fc6b",
  "name": "string",
  "slug": "string",
  "description": "string",
  "created": "2019-08-24T14:15:22Z",
  "prompt_data": {
    "prompt": {
      "type": "completion",
      "content": "string"
    },
    "options": {
      "model": "string",
      "params": {
        "use_cache": true,
        "temperature": 0,
        "top_p": 0,
        "max_tokens": 0,
        "max_completion_tokens": 0,
        "frequency_penalty": 0,
        "presence_penalty": 0,
        "response_format": {
          "type": "json_object"
        },
        "tool_choice": "auto",
        "function_call": "auto",
        "n": 0,
        "stop": [
          "string"
        ],
        "reasoning_effort": "low"
      },
      "position": "string"
    },
    "parser": {
      "type": "llm_classifier",
      "use_cot": true,
      "choice_scores": {
        "property1": 1,
        "property2": 1
      }
    },
    "tool_functions": [
      {
        "type": "function",
        "id": "string"
      }
    ],
    "origin": {
      "prompt_id": "string",
      "project_id": "string",
      "prompt_version": "string"
    }
  },
  "tags": [
    "string"
  ],
  "metadata": {
    "property1": null,
    "property2": null
  },
  "function_type": "llm"
}

PATCH

/v1/prompt/{prompt_id}

Partially update prompt

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.

Authorization

`Authorization`
Required
Bearer <token>

In: header

Request Body

application/jsonOptional

Fields to update

`name`string | null

Name of the prompt

`slug`string | null

Unique identifier for the prompt

`description`string | null

Textual description of the prompt

`prompt_data`object | null

The prompt, model, and its parameters

`tags`array<string> | null

A list of tags for the prompt

Path Parameters

`prompt_id`
Required
string

Prompt id

Format: "uuid"

curl -X PATCH "https://api.braintrust.dev/v1/prompt/497f6eca-6276-4993-bfeb-53cbbbba6f08" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "string",
    "slug": "string",
    "description": "string",
    "prompt_data": {
      "prompt": {
        "type": "completion",
        "content": "string"
      },
      "options": {
        "model": "string",
        "params": {
          "use_cache": true,
          "temperature": 0,
          "top_p": 0,
          "max_tokens": 0,
          "max_completion_tokens": 0,
          "frequency_penalty": 0,
          "presence_penalty": 0,
          "response_format": {
            "type": "json_object"
          },
          "tool_choice": "auto",
          "function_call": "auto",
          "n": 0,
          "stop": [
            "string"
          ],
          "reasoning_effort": "low"
        },
        "position": "string"
      },
      "parser": {
        "type": "llm_classifier",
        "use_cot": true,
        "choice_scores": {
          "property1": 1,
          "property2": 1
        }
      },
      "tool_functions": [
        {
          "type": "function",
          "id": "string"
        }
      ],
      "origin": {
        "prompt_id": "string",
        "project_id": "string",
        "prompt_version": "string"
      }
    },
    "tags": [
      "string"
    ]
  }'

Returns the prompt object

{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "_xact_id": "string",
  "project_id": "405d8375-3514-403b-8c43-83ae74cfe0e9",
  "log_id": "p",
  "org_id": "a40f5d1f-d889-42e9-94ea-b9b33585fc6b",
  "name": "string",
  "slug": "string",
  "description": "string",
  "created": "2019-08-24T14:15:22Z",
  "prompt_data": {
    "prompt": {
      "type": "completion",
      "content": "string"
    },
    "options": {
      "model": "string",
      "params": {
        "use_cache": true,
        "temperature": 0,
        "top_p": 0,
        "max_tokens": 0,
        "max_completion_tokens": 0,
        "frequency_penalty": 0,
        "presence_penalty": 0,
        "response_format": {
          "type": "json_object"
        },
        "tool_choice": "auto",
        "function_call": "auto",
        "n": 0,
        "stop": [
          "string"
        ],
        "reasoning_effort": "low"
      },
      "position": "string"
    },
    "parser": {
      "type": "llm_classifier",
      "use_cot": true,
      "choice_scores": {
        "property1": 1,
        "property2": 1
      }
    },
    "tool_functions": [
      {
        "type": "function",
        "id": "string"
      }
    ],
    "origin": {
      "prompt_id": "string",
      "project_id": "string",
      "prompt_version": "string"
    }
  },
  "tags": [
    "string"
  ],
  "metadata": {
    "property1": null,
    "property2": null
  },
  "function_type": "llm"
}

DELETE

/v1/prompt/{prompt_id}

Delete prompt

Delete a prompt object by its id

Authorization

`Authorization`
Required
Bearer <token>

In: header

Path Parameters

`prompt_id`
Required
string

Prompt id

Format: "uuid"

curl -X DELETE "https://api.braintrust.dev/v1/prompt/497f6eca-6276-4993-bfeb-53cbbbba6f08" \
  -H "Authorization: Bearer <token>"

Returns the deleted prompt object

{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "_xact_id": "string",
  "project_id": "405d8375-3514-403b-8c43-83ae74cfe0e9",
  "log_id": "p",
  "org_id": "a40f5d1f-d889-42e9-94ea-b9b33585fc6b",
  "name": "string",
  "slug": "string",
  "description": "string",
  "created": "2019-08-24T14:15:22Z",
  "prompt_data": {
    "prompt": {
      "type": "completion",
      "content": "string"
    },
    "options": {
      "model": "string",
      "params": {
        "use_cache": true,
        "temperature": 0,
        "top_p": 0,
        "max_tokens": 0,
        "max_completion_tokens": 0,
        "frequency_penalty": 0,
        "presence_penalty": 0,
        "response_format": {
          "type": "json_object"
        },
        "tool_choice": "auto",
        "function_call": "auto",
        "n": 0,
        "stop": [
          "string"
        ],
        "reasoning_effort": "low"
      },
      "position": "string"
    },
    "parser": {
      "type": "llm_classifier",
      "use_cot": true,
      "choice_scores": {
        "property1": 1,
        "property2": 1
      }
    },
    "tool_functions": [
      {
        "type": "function",
        "id": "string"
      }
    ],
    "origin": {
      "prompt_id": "string",
      "project_id": "string",
      "prompt_version": "string"
    }
  },
  "tags": [
    "string"
  ],
  "metadata": {
    "property1": null,
    "property2": null
  },
  "function_type": "llm"
}

Query

AuthorizationRequiredBearer <token>

limitinteger | null

starting_afterstring

ending_beforestring

idsAny properties in string, array<string>

Object 1

prompt_namestring

project_namestring

project_idstring

slugstring

versionstring

org_namestring

Response

TypeScript

Body

AuthorizationRequiredBearer <token>

project_idRequiredstring

nameRequiredstring

slugRequiredstring

descriptionstring | null

prompt_dataobject | null

Attributes

tagsarray<string> | null

function_typestring | null

Response

TypeScript

Body

AuthorizationRequiredBearer <token>

project_idRequiredstring

nameRequiredstring

slugRequiredstring

descriptionstring | null

prompt_dataobject | null

Attributes

tagsarray<string> | null

function_typestring | null

Response

TypeScript

Path

AuthorizationRequiredBearer <token>

prompt_idRequiredstring

Response

TypeScript

Path

Body

AuthorizationRequiredBearer <token>

namestring | null

slugstring | null

descriptionstring | null

prompt_dataobject | null

Attributes

tagsarray<string> | null

prompt_idRequiredstring

Response

TypeScript

Path

AuthorizationRequiredBearer <token>

prompt_idRequiredstring

Response

TypeScript

On this page

`Authorization`
Required
Bearer <token>

`limit`integer | null

`starting_after`string

`ending_before`string

`ids`Any properties in string, array<string>

`prompt_name`string

`project_name`string

`project_id`string

`slug`string

`version`string

`org_name`string

`Authorization`
Required
Bearer <token>

`project_id`
Required
string

`name`
Required
string

`slug`
Required
string

`description`string | null

`prompt_data`object | null

`tags`array<string> | null

`function_type`string | null

`Authorization`
Required
Bearer <token>

`project_id`
Required
string

`name`
Required
string

`slug`
Required
string

`description`string | null

`prompt_data`object | null

`tags`array<string> | null

`function_type`string | null

`Authorization`
Required
Bearer <token>

`prompt_id`
Required
string

`Authorization`
Required
Bearer <token>

`name`string | null

`slug`string | null

`description`string | null

`prompt_data`object | null

`tags`array<string> | null

`prompt_id`
Required
string

`Authorization`
Required
Bearer <token>

`prompt_id`
Required
string