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.