> ## Documentation Index
> Fetch the complete documentation index at: https://moonshotfactory.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

<CodeGroup>
  ```bash cURL theme={null}
  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"
    }'
  ```
</CodeGroup>

`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

<ParamField body="name" type="string" required>
  Prompt name used to group versions together (e.g. `"classify-intent"`).
</ParamField>

<ParamField body="version" type="number" default="1">
  Integer version number. Increment this with each iteration of the prompt.
</ParamField>

<ParamField body="template_text" type="string" required>
  The full prompt text at this version.
</ParamField>

<ParamField body="description" type="string">
  Optional human-readable description of what changed in this version.
</ParamField>

### Response — 201

<ResponseField name="id" type="string">
  UUID of the new prompt template record.
</ResponseField>

<ResponseField name="name" type="string">
  Prompt name.
</ResponseField>

<ResponseField name="version" type="number">
  Version number.
</ResponseField>

<ResponseField name="template_text" type="string">
  The full prompt text.
</ResponseField>

<ResponseField name="description" type="string | null">
  Description of this version.
</ResponseField>

<ResponseField name="is_active" type="boolean">
  Whether this version is active. Always `true` on creation.
</ResponseField>

<ResponseField name="created_at" type="string">
  ISO 8601 creation timestamp.
</ResponseField>

```json Example response theme={null}
{
  "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

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.agentvista.dev/api/v1/dashboard/prompts/ \
    -H "Authorization: Bearer av_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
  ```
</CodeGroup>

`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](#create-a-prompt-version).

***

## List versions of a named prompt

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.agentvista.dev/api/v1/dashboard/prompts/classify-intent/versions \
    -H "Authorization: Bearer av_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
  ```
</CodeGroup>

`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

<ParamField path="name" type="string" required>
  The prompt name (e.g. `"classify-intent"`).
</ParamField>

### Response — 200

An array of prompt template objects for this prompt name.

***

## Compare versions

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.agentvista.dev/api/v1/dashboard/prompts/classify-intent/compare \
    -H "Authorization: Bearer av_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
  ```
</CodeGroup>

`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](#record-prompt-usage) endpoint. Returns `404` if the prompt name does not exist for the authenticated user.

### Path parameters

<ParamField path="name" type="string" required>
  The prompt name to compare versions for.
</ParamField>

### Response — 200

<ResponseField name="name" type="string">
  Prompt name.
</ResponseField>

<ResponseField name="versions" type="object[]">
  Per-version analytics, one entry per version.

  <Expandable title="version stats fields">
    <ResponseField name="version" type="number">
      Version number.
    </ResponseField>

    <ResponseField name="template_text" type="string">
      The full prompt text at this version.
    </ResponseField>

    <ResponseField name="total_traces" type="number">
      Number of traces that used this prompt version.
    </ResponseField>

    <ResponseField name="success_rate" type="number | null">
      Fraction of linked traces with `success: true`. Null if no traces have a success signal.
    </ResponseField>

    <ResponseField name="avg_cost_usd" type="number | null">
      Average `total_cost_usd` across linked traces in USD.
    </ResponseField>

    <ResponseField name="avg_latency_ms" type="number | null">
      Average `duration_ms` across linked traces.
    </ResponseField>

    <ResponseField name="p95_latency_ms" type="number | null">
      95th-percentile `duration_ms` across linked traces.
    </ResponseField>
  </Expandable>
</ResponseField>

```json Example response theme={null}
{
  "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

<CodeGroup>
  ```bash cURL theme={null}
  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"
    }'
  ```
</CodeGroup>

`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

<ParamField body="prompt_name" type="string" required>
  Name of the prompt template that was used.
</ParamField>

<ParamField body="prompt_version" type="number" required>
  Version number of the prompt that was used.
</ParamField>

<ParamField body="trace_id" type="string" required>
  UUID of the trace that used this prompt version.
</ParamField>

<ParamField body="span_id" type="string">
  UUID of the specific span within the trace where this prompt was used. Optional but recommended for multi-prompt traces.
</ParamField>

### Response — 201

<ResponseField name="status" type="string">
  Always `"recorded"` on success.
</ResponseField>

```json theme={null}
{ "status": "recorded" }
```