Prompts

Overview

Prompts are reusable message templates used for stimulus generation. They consist of a sequence of messages with roles (system, user, assistant) and content.

Endpoints

List Prompts

List all prompts in a repository. Endpoint: GET /v1/repo/{repo_name}/prompts Request:

curl -X GET "https://bapi.bread.com.ai/v1/repo/my_repo/prompts" \
  -H "Authorization: Bearer $BREAD_API_KEY"

repo_name

string

required

Repository name

Response: 200 OK

{
  "prompts": ["system_prompt", "user_prompt", "assistant_prompt"]
}

Get Prompt

Get a specific prompt’s definition and metadata. Endpoint: GET /v1/repo/{repo_name}/prompts/{prompt_name} Request:

curl -X GET "https://bapi.bread.com.ai/v1/repo/my_repo/prompts/system_prompt_coding" \
  -H "Authorization: Bearer $BREAD_API_KEY"

prompt_name

string

required

Prompt name to retrieve

repo_name

string

required

Repository name

Response: 200 OK

{
  "prompt_name": "system_prompt_coding",
  "messages": [
    {
      "role": "system",
      "content": "You are a helpful coding assistant."
    }
  ]
}

Response Fields:

prompt_name: string - Prompt identifier
messages: Array<Message> - List of messages in the prompt

Create or Update Prompt

Create or update a prompt. This operation is idempotent. Endpoint: POST /v1/repo/{repo_name}/prompts Request:

curl -X POST "https://bapi.bread.com.ai/v1/repo/my_repo/prompts" \
  -H "Authorization: Bearer $BREAD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt_name": "system_prompt_coding",
    "messages": [
      {
        "role": "system",
        "content": "You are a helpful coding assistant."
      },
      {
        "role": "user",
        "content": "Write a function to {task}"
      }
    ]
  }'

repo_name

string

required

Repository name

prompt_name

string

required

Prompt name

messages

array

required

List of messages in the prompt. Each message has:

role (string, required): “system”, “user”, or “assistant”
content (string, required): Message content

Invalid prompt names return a 422 Unprocessable Entity error.

Response: 200 OK

{
  "prompt_name": "system_prompt_coding",
  "messages": [
    {
      "role": "system",
      "content": "You are a helpful coding assistant."
    },
    {
      "role": "user",
      "content": "Write a function to {task}"
    }
  ]
}

Batch Create or Update Prompts

Create or update multiple prompts in a single request. Endpoint: POST /v1/repo/{repo_name}/prompts/batch Request:

curl -X POST "https://bapi.bread.com.ai/v1/repo/my_repo/prompts/batch" \
  -H "Authorization: Bearer $BREAD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompts": {
      "system_prompt": [
        {"role": "system", "content": "Hello"}
      ],
      "user_prompt": [
        {"role": "user", "content": "World"}
      ]
    }
  }'

repo_name

string

required

Repository name

prompts

object

required

Dictionary mapping prompt names to message arrays

Response: 200 OK

{
  "created": ["system_prompt", "user_prompt"],
  "failed": {}
}

Response Fields:

created: Array<string> - Successfully created prompt names
failed: Object<string, string> - Failed prompts with error messages

Create or Update Prompt (Deprecated)

Deprecated: Use POST /v1/repo/{repo_name}/prompts instead. This endpoint will be removed in a future version.

Endpoint: PUT /v1/repo/{repo_name}/prompts/{prompt_name} Request:

curl -X PUT "https://bapi.bread.com.ai/v1/repo/my_repo/prompts/system_prompt_coding" \
  -H "Authorization: Bearer $BREAD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "role": "system",
        "content": "You are a helpful coding assistant."
      }
    ]
  }'

Batch Create or Update Prompts (Deprecated)

Deprecated: Use POST /v1/repo/{repo_name}/prompts/batch instead. This endpoint will be removed in a future version.

Endpoint: PUT /v1/repo/{repo_name}/prompts/batch Request:

curl -X PUT "https://bapi.bread.com.ai/v1/repo/my_repo/prompts/batch" \
  -H "Authorization: Bearer $BREAD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompts": {
      "system_prompt": [
        {"role": "system", "content": "Hello"}
      ]
    }
  }'

Delete Prompt

Delete a prompt from the repository. Endpoint: DELETE /v1/repo/{repo_name}/prompts/{prompt_name} Request:

curl -X DELETE "https://bapi.bread.com.ai/v1/repo/my_repo/prompts/old_prompt" \
  -H "Authorization: Bearer $BREAD_API_KEY"

prompt_name

string

required

Prompt name to delete

repo_name

string

required

Repository name

Response: 200 OK

{
  "message": "Prompt deleted successfully"
}

Response Fields:

message: string - Success confirmation

Examples

Create System Prompt

curl -X POST "https://bapi.bread.com.ai/v1/repo/my_repo/prompts" \
  -H "Authorization: Bearer $BREAD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt_name": "system_prompt_coding",
    "messages": [
      {
        "role": "system",
        "content": "You are an expert Python programmer. Provide clear, concise, and well-documented code."
      }
    ]
  }'

Create User Prompt with Template Variables

curl -X POST "https://bapi.bread.com.ai/v1/repo/my_repo/prompts" \
  -H "Authorization: Bearer $BREAD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt_name": "user_prompt_task",
    "messages": [
      {
        "role": "user",
        "content": "Task: {task}\nDifficulty: {difficulty}\nProvide a solution."
      }
    ]
  }'

Use template variables like {task} in your prompts. These will be filled in during stimulus generation.

Batch Create Prompts

curl -X POST "https://bapi.bread.com.ai/v1/repo/my_repo/prompts/batch" \
  -H "Authorization: Bearer $BREAD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompts": {
      "system_assistant": [
        {"role": "system", "content": "You are a helpful assistant"}
      ],
      "system_coder": [
        {"role": "system", "content": "You are a coding expert"}
      ],
      "user_template": [
        {"role": "user", "content": "Question: {question}"}
      ]
    }
  }'

Multi-Turn Conversation Prompt

curl -X POST "https://bapi.bread.com.ai/v1/repo/my_repo/prompts" \
  -H "Authorization: Bearer $BREAD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt_name": "conversation_starter",
    "messages": [
      {"role": "system", "content": "You are a friendly chatbot"},
      {"role": "user", "content": "Hello!"},
      {"role": "assistant", "content": "Hi! How can I help you today?"},
      {"role": "user", "content": "{user_query}"}
    ]
  }'

Message Roles

system

System instructions that guide the model’s behavior

user

Messages from the user/human

assistant

Messages from the AI assistant

Error Handling

Unprocessable Entity (422)

Invalid prompt name format:

curl -X POST "https://bapi.bread.com.ai/v1/repo/my_repo/prompts" \
  -H "Authorization: Bearer $BREAD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt_name": "invalid name!",
    "messages": [{"role": "system", "content": "Test"}]
  }'

Response: 422 Unprocessable Entity

{
  "error": "Invalid prompt name format"
}

Not Found (404)

Getting a non-existent prompt:

curl -X GET "https://bapi.bread.com.ai/v1/repo/my_repo/prompts/nonexistent" \
  -H "Authorization: Bearer $BREAD_API_KEY"

Response: 404 Not Found

{
  "error": "Prompt not found"
}

Response Types

Message

{
  "role": "system",
  "content": "You are a helpful assistant."
}

PromptResponse

{
  "prompt_name": "system_prompt",
  "messages": [
    {
      "role": "system",
      "content": "You are a helpful assistant."
    }
  ]
}

Best Practices

Use Descriptive Names

Name prompts clearly: system_prompt_coding, user_task_template, assistant_response_format

Template Variables

Use {variable} syntax for dynamic content that will be filled during stimulus generation

System Prompts First

Always start with a system message to set the model’s behavior and role

Batch Operations

Use POST /v1/repo/{repo_name}/prompts/batch when creating multiple prompts to reduce API calls

Version Your Prompts

Consider including version numbers in names: system_prompt_v2, user_task_v3

Next Steps

Targets

Use prompts in target configuration

SDK Quickstart

Use the SDK for programmatic control

API Reference

API Playground

Overview

Endpoints

List Prompts

Get Prompt

Create or Update Prompt

Batch Create or Update Prompts

Create or Update Prompt (Deprecated)

Batch Create or Update Prompts (Deprecated)

Delete Prompt

Examples

Create System Prompt

Create User Prompt with Template Variables

Batch Create Prompts

Multi-Turn Conversation Prompt

Message Roles

system

user

assistant

Error Handling

Unprocessable Entity (422)

Not Found (404)

Response Types

Message

PromptResponse

Best Practices

Next Steps

Targets

SDK Quickstart

API Reference

API Playground

​Overview

​Endpoints

​List Prompts

​Get Prompt

​Create or Update Prompt

​Batch Create or Update Prompts

​Create or Update Prompt (Deprecated)

​Batch Create or Update Prompts (Deprecated)

​Delete Prompt

​Examples

​Create System Prompt

​Create User Prompt with Template Variables

​Batch Create Prompts

​Multi-Turn Conversation Prompt

​Message Roles

system

user

assistant

​Error Handling

​Unprocessable Entity (422)

​Not Found (404)

​Response Types

​Message

​PromptResponse

​Best Practices

​Next Steps

Targets

SDK Quickstart

Overview

Endpoints

List Prompts

Get Prompt

Create or Update Prompt

Batch Create or Update Prompts

Create or Update Prompt (Deprecated)

Batch Create or Update Prompts (Deprecated)

Delete Prompt

Examples

Create System Prompt

Create User Prompt with Template Variables

Batch Create Prompts

Multi-Turn Conversation Prompt

Message Roles

Error Handling

Unprocessable Entity (422)

Not Found (404)

Response Types

Message

PromptResponse

Best Practices

Next Steps