Braintest
POST/v1/prompt

Create a prompt

Creates a new prompt under a project. Supply project_id, name, and slug, and use prompt_data, tags, and function_type to define the prompt and its classification; an existing prompt with the same project and slug is returned unchanged.

  • IdempotentThe SDK sends Idempotency-Key, so a retried request is only applied once.

7 body fields

Information for the prompt to create. project_id, name, and slug are required.

project_idstringrequired
Unique identifier for the project that the prompt belongs under
namestringrequired
Name of the prompt
slugstringrequired
Unique identifier for the prompt
descriptionstringoptional
Textual description of the prompt
prompt_dataobjectoptional
The prompt, model, and its parameters
tagsarray<string>optional
A list of tags for the prompt
function_typestringoptional
The prompt function type: `llm`, `scorer`, `task`, `tool`, or null.
Allowed:llmscorertasktoolnull

6 status codes
200Returns the new prompt object, including its identifier, project and organization identifiers, slug, name, creation time, prompt data, tags, and function type.
idstringrequired
Unique identifier for the prompt
_xact_idstringrequired
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_idstringrequired
Unique identifier for the project that the prompt belongs under
log_idstringrequired
A literal 'p' which identifies the object as a project prompt
Allowed:p
org_idstringrequired
Unique identifier for the organization
namestringrequired
Name of the prompt
slugstringrequired
Unique identifier for the prompt
descriptionstringoptional
Textual description of the prompt
createdstringoptional
Date of prompt creation
prompt_dataobjectoptional
The prompt, model, and its parameters
tagsarray<string>optional
A list of tags for the prompt
metadataobjectoptional
User-controlled metadata about the prompt
function_typestringoptional
Allowed:llmscorertasktoolnull
400Returned when the request is unacceptable, including when a required field is missing or `name` or `slug` is empty.
401Returned when no valid API key is provided.
403Returned when the API key does not have permission to create prompts.
429Returned when too many requests reach the API too quickly.
500Returned when an unexpected failure occurs on the API side.

Error handling

A 400 is returned when the request is unacceptable, including when project_id, name, or slug is missing, or when name or slug is empty. A 401 is returned without a valid API key, and a 403 is returned when the API key lacks permission. A 429 indicates that requests are being sent too quickly, while a 500 indicates an API-side failure.