Prompts

Prompts are the core reusable AI resource in the platform. They define a named behavior that can be versioned, tested, executed directly, or reused inside agents and voice agents.

What a prompt is

In the current product, a prompt has:

a human-readable name
a slug and a stable prompt key
an optional description
an optional default model
zero or more versions

Each prompt version is the executable unit and can define:

systemPrompt
developerPrompt
variablesSchema
responseFormat
temperature and output token settings
attached prompt layers
attached tools

Current product behavior

The Prompts page in the app is where teams create prompts and see:

published version status
model usage and runtime metrics
usage by agents
usage by voice agents
run counts and average latency

Prompt versions can be previewed, published, and executed. A published version is what the product expects to be reused in more stable workflows.

API workflow

Create a prompt

curl -X POST "$API_BASE/api/prompts" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "organizationId": "org_123",
    "name": "Returns eligibility",
    "description": "Decide whether an order qualifies for return"
  }'

Create a prompt version

curl -X POST "$API_BASE/api/prompts/prompt_123/versions" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "organizationId": "org_123",
    "systemPrompt": "You are a returns specialist.",
    "variablesSchema": {
      "type": "object",
      "properties": {
        "orderId": { "type": "string" }
      }
    }
  }'

Run a prompt

curl -X POST "$API_BASE/api/prompts/prompt_123/run" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "organizationId": "org_123",
    "variables": {
      "orderId": "order_987"
    }
  }'

Tools attach to prompt versions.
Agents compose prompt versions into step-based workflows.
Voice Agents wrap prompt versions for realtime use.
Runs show what happened when a prompt executed.