Prompt Templates API

Manage version-controlled prompt templates via the REST API. Templates are project-scoped and require API key authentication.

GET /api/v1/prompt-templates

List all templates for a project, or resolve a specific template by name and optional version.

Query Parameters

Examples

List all templates:

curl "https://api.2signal.dev/api/v1/prompt-templates" \
  -H "Authorization: Bearer ts_your_api_key"

# Response:
{
  "data": [
    {
      "id": "tmpl-abc-123",
      "name": "customer-support",
      "description": "Main support agent prompt",
      "latestVersion": 3,
      "createdAt": "2026-03-01T00:00:00Z",
      "updatedAt": "2026-03-15T00:00:00Z"
    }
  ]
}

Resolve latest version by name:

curl "https://api.2signal.dev/api/v1/prompt-templates?name=customer-support" \
  -H "Authorization: Bearer ts_your_api_key"

# Response:
{
  "data": {
    "id": "tmpl-abc-123",
    "name": "customer-support",
    "version": {
      "id": "ver-xyz-789",
      "version": 3,
      "content": "You are a helpful customer support agent...",
      "variables": ["company_name", "customer_name"],
      "commitMessage": "Added tone instructions",
      "createdAt": "2026-03-15T00:00:00Z"
    }
  }
}

Resolve specific version:

curl "https://api.2signal.dev/api/v1/prompt-templates?name=customer-support&version=1" \
  -H "Authorization: Bearer ts_your_api_key"

POST /api/v1/prompt-templates

Create a new prompt template, or push a new version to an existing template. If a template with the given name already exists, the version number is auto-incremented.

Request Body

Example

curl -X POST "https://api.2signal.dev/api/v1/prompt-templates" \
  -H "Authorization: Bearer ts_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "customer-support",
    "content": "You are a helpful and empathetic customer support agent for {{company_name}}. The customer is {{customer_name}}. Always be polite, accurate, and concise.",
    "variables": ["company_name", "customer_name"],
    "commitMessage": "Added empathy and conciseness instructions"
  }'

# Response (201 Created):
{
  "data": {
    "templateId": "tmpl-abc-123",
    "templateName": "customer-support",
    "versionId": "ver-new-456",
    "version": 4
  }
}

Error Responses

Related

• Prompt Templates Guide — concepts, workflows, and best practices
• Trace Replay — replay traces with different prompt template versions
• Data Model — PromptTemplate and PromptTemplateVersion schemas