Prompts API

The Prompts API manages versioned prompt templates. Prompts support Mustache ({{variable}}) placeholders and can be labeled (e.g., production, staging) to control which version is active.

Create Prompt

POST /api/public/v2/prompts

Request Body

Field	Type	Required	Description
`name`	`string`	Yes	Unique prompt name
`prompt`	`string \| array`	Yes	Template string (text) or messages array (chat)
`type`	`string`	No	`text` (default) or `chat`
`labels`	`string[]`	No	Version labels (e.g., `["production"]`)
`tags`	`string[]`	No	Tags for organization
`config`	`object`	No	Arbitrary config metadata
`modelParams`	`object`	No	Model parameters (model, temperature, etc.)
`toolList`	`array`	No	Tools attached to the prompt
`commitMessage`	`string`	No	Version commit message

Text Prompt Example

curl -X POST https://evals-api.browserstack.com/api/public/v2/prompts \
  -u "pk-lf-...:sk-lf-..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "summarizer",
    "type": "text",
    "prompt": "Summarize the following article in 3 bullet points:\n\n{{article}}",
    "labels": ["production"],
    "tags": ["summarization"],
    "modelParams": { "model": "gpt-4o", "temperature": 0.3 },
    "commitMessage": "Initial version"
  }'

Chat Prompt Example

curl -X POST https://evals-api.browserstack.com/api/public/v2/prompts \
  -u "pk-lf-...:sk-lf-..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "support-assistant",
    "type": "chat",
    "prompt": [
      { "role": "system", "content": "You are a support agent for {{product}}." },
      { "role": "user", "content": "{{user_message}}" }
    ],
    "labels": ["staging"]
  }'

Response:

{
  "id": "prompt-uuid-1",
  "name": "summarizer",
  "type": "text",
  "version": 1,
  "prompt": "Summarize the following article in 3 bullet points:\n\n{{article}}",
  "labels": ["production"],
  "tags": ["summarization"],
  "config": {},
  "modelParams": { "model": "gpt-4o", "temperature": 0.3 },
  "createdAt": "2026-04-03T10:00:00.000Z",
  "updatedAt": "2026-04-03T10:00:00.000Z"
}

Get Prompt

GET /api/public/v2/prompts/{promptName}

Retrieves a prompt by name. You can pin to a specific version or label. Defaults to the latest label.

Path Parameters

Parameter	Type	Description
`promptName`	`string`	Prompt name (URL-encoded)

Query Parameters

Parameter	Type	Description
`version`	`integer`	Pin to a specific version number
`label`	`string`	Fetch by label (e.g., `"production"`)

# Fetch latest version
curl "https://evals-api.browserstack.com/api/public/v2/prompts/summarizer" \
  -u "pk-lf-...:sk-lf-..."

# Fetch production label
curl "https://evals-api.browserstack.com/api/public/v2/prompts/summarizer?label=production" \
  -u "pk-lf-...:sk-lf-..."

# Fetch a specific version
curl "https://evals-api.browserstack.com/api/public/v2/prompts/summarizer?version=3" \
  -u "pk-lf-...:sk-lf-..."

Response:

{
  "id": "prompt-uuid-1",
  "name": "summarizer",
  "type": "text",
  "version": 1,
  "prompt": "Summarize the following article in 3 bullet points:\n\n{{article}}",
  "labels": ["production"],
  "tags": ["summarization"],
  "config": {},
  "modelParams": { "model": "gpt-4o", "temperature": 0.3 },
  "createdAt": "2026-04-03T10:00:00.000Z",
  "updatedAt": "2026-04-03T10:00:00.000Z"
}

List Prompts

GET /api/public/v2/prompts

Parameter	Type	Description
`page`	`integer`	Page number
`limit`	`integer`	Items per page
`name`	`string`	Filter by prompt name
`label`	`string`	Filter by label
`tag`	`string`	Filter by tag
`fromUpdatedAt`	`ISO 8601`	Filter updated at or after
`toUpdatedAt`	`ISO 8601`	Filter updated at or before

curl "https://evals-api.browserstack.com/api/public/v2/prompts?label=production&page=1&limit=20" \
  -u "pk-lf-...:sk-lf-..."

Response:

{
  "data": [
    {
      "name": "summarizer",
      "lastConfig": {},
      "labels": ["production"],
      "tags": ["summarization"],
      "versions": [1, 2],
      "createdAt": "2026-04-03T10:00:00.000Z",
      "updatedAt": "2026-04-03T10:05:00.000Z"
    }
  ],
  "meta": {
    "page": 1,
    "limit": 20,
    "totalItems": 5,
    "totalPages": 1
  }
}

Delete Prompt

DELETE /api/public/v2/prompts/{promptName}

Deletes all versions of a prompt.

curl -X DELETE "https://evals-api.browserstack.com/api/public/v2/prompts/summarizer" \
  -u "pk-lf-...:sk-lf-..."

Versioning

Each call to POST /api/public/v2/prompts with the same name creates a new version. Versions are immutable once created. Labels (like "production") are mutable pointers to versions.

Label	Typical Use
`latest`	Most recently created version (automatic)
`production`	Version currently serving in production
`staging`	Version under test

To promote a version to production, create a new version with labels: ["production"].

Prompts API

On this page