Prompts

Version and compare prompt templates, and link them to traces for analytics.

AgentVista tracks prompt templates as versioned records so you can see how changes to your prompts affect agent performance. Each named prompt can have multiple versions. You link prompt versions to traces to get per-version analytics including success rate, cost, and latency.

---

Create a prompt version

cURL

curl -X POST https://api.agentvista.dev/api/v1/dashboard/prompts/ \
  -H "Authorization: Bearer av_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "classify-intent",
    "version": 3,
    "template_text": "You are a lead classification agent. Classify the following inquiry as qualified, unqualified, or escalate:\n\n{{inquiry}}",
    "description": "Added escalation class for high-value leads"
  }'

POST /dashboard/prompts/

Creates a new prompt template version. The combination of name and version must be unique per user. Returns 409 if that version already exists for this prompt name.

Request body

name · string · required

Prompt name used to group versions together (e.g. "classify-intent").

version · number · default: "1"

Integer version number. Increment this with each iteration of the prompt.

template_text · string · required

The full prompt text at this version.

description · string

Optional human-readable description of what changed in this version.

Response — 201

id · string

UUID of the new prompt template record.

name · string

Prompt name.

version · number

Version number.

template_text · string

The full prompt text.

description · string | null

Description of this version.

is_active · boolean

Whether this version is active. Always true on creation.

created_at · string

ISO 8601 creation timestamp.

Example response

{
  "id": "b2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e",
  "name": "classify-intent",
  "version": 3,
  "template_text": "You are a lead classification agent...",
  "description": "Added escalation class for high-value leads",
  "is_active": true,
  "created_at": "2024-01-15T10:00:00Z"
}

---

List all prompt versions

cURL

curl https://api.agentvista.dev/api/v1/dashboard/prompts/ \
  -H "Authorization: Bearer av_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

GET /dashboard/prompts/

Returns all prompt template versions for the authenticated user, ordered by name then version descending (newest version first within each name).

Response — 200

An array of prompt template objects. Each object has the same fields as the create response.

---

List versions of a named prompt

cURL

curl https://api.agentvista.dev/api/v1/dashboard/prompts/classify-intent/versions \
  -H "Authorization: Bearer av_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

GET /dashboard/prompts/{name}/versions

Returns all versions of a named prompt ordered newest-first. Returns 404 if no prompt with this name exists for the authenticated user.

Path parameters

name · string · required

The prompt name (e.g. "classify-intent").

Response — 200

An array of prompt template objects for this prompt name.

---

Compare versions

cURL

curl https://api.agentvista.dev/api/v1/dashboard/prompts/classify-intent/compare \
  -H "Authorization: Bearer av_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

GET /dashboard/prompts/{name}/compare

Returns per-version analytics for a named prompt. Metrics are computed from all traces linked to each version via the record usage endpoint. Returns 404 if the prompt name does not exist for the authenticated user.

Path parameters

name · string · required

The prompt name to compare versions for.

Response — 200

name · string

Prompt name.

versions · object[]

Per-version analytics, one entry per version.

Show version stats fields

version · number

Version number.

template_text · string

The full prompt text at this version.

total_traces · number

Number of traces that used this prompt version.

success_rate · number | null

Fraction of linked traces with success: true. Null if no traces have a success signal.

avg_cost_usd · number | null

Average total_cost_usd across linked traces in USD.

avg_latency_ms · number | null

Average duration_ms across linked traces.

p95_latency_ms · number | null

95th-percentile duration_ms across linked traces.

Example response

{
  "name": "classify-intent",
  "versions": [
    {
      "version": 3,
      "template_text": "You are a lead classification agent...",
      "total_traces": 842,
      "success_rate": 0.81,
      "avg_cost_usd": 0.0038,
      "avg_latency_ms": 1420.5,
      "p95_latency_ms": 2100
    },
    {
      "version": 2,
      "template_text": "Classify the following lead inquiry...",
      "total_traces": 1200,
      "success_rate": 0.73,
      "avg_cost_usd": 0.0041,
      "avg_latency_ms": 1650.2,
      "p95_latency_ms": 2500
    }
  ]
}

---

Record prompt usage

cURL

curl -X POST https://api.agentvista.dev/api/v1/dashboard/prompts/usage \
  -H "Authorization: Bearer av_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt_name": "classify-intent",
    "prompt_version": 3,
    "trace_id": "550e8400-e29b-41d4-a716-446655440000",
    "span_id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8"
  }'

POST /dashboard/prompts/usage

Records that a specific trace used a prompt template version. Call this after a trace completes to link it to the prompt used. This link powers the per-version analytics in the compare endpoint. The call is idempotent — calling it multiple times with the same arguments is safe.

Request body

prompt_name · string · required

Name of the prompt template that was used.

prompt_version · number · required

Version number of the prompt that was used.

trace_id · string · required

UUID of the trace that used this prompt version.

span_id · string

UUID of the specific span within the trace where this prompt was used. Optional but recommended for multi-prompt traces.

Response — 201

status · string

Always "recorded" on success.

{ "status": "recorded" }