Skip to main content
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 -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 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 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 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.
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 -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" }