> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orbit.devotel.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Prompt Template Library: browse, fork, and seed a new agent

> Start an AI agent from a curated, versioned system-prompt starter: browse the shared catalog, fill in its variables, and fork the resolved prompt into the create-agent wizard.

# Prompt Template Library

The Prompt Template Library is a curated, versioned catalog of system-prompt starters every tenant can browse and fork. Each template targets a common intent — support triage, inbound sales qualification, appointment scheduling, payment reminders, tier-1 technical support, and post-interaction surveys — and ships with a tested base prompt you resolve with your own details instead of writing from scratch.

Open it in the dashboard at **Agents → Prompt Template Library** (`/agents/prompt-templates`).

Use it when you want a proven starting point: pick a template, fill in its variables, and fork the result straight into the [create-agent wizard](/agents/creating-agents) or paste it into an existing agent's `system_prompt`.

## 1. What the library is

The catalog is shared platform content — the same set of templates is available to every tenant, maintained and versioned centrally. A template bundles:

* A **base system prompt** written for one intent (for example, the inbound sales qualifier qualifies leads and books a follow-up with a human rep).
* A **category** (`customer_support`, `sales`, `scheduling`, `collections`, `technical_support`, `survey`) and an **agent type** hint (`voice`, `chatbot`, `router`, `workflow`, `custom`).
* A set of **variables** the prompt body references as `{{placeholders}}`.
* A **version history** — every revision of the prompt body with its own version string and changelog.

Because the catalog is curated centrally, a template reads as a complete, production-ready prompt: tone, escalation behavior, and guardrails for the intent are already in the text.

## 2. Browse the catalog

List every template with `GET /agents/prompt-templates`. Each entry returns its stable `id`, `name`, `description`, `category`, `agent_type`, `tags`, the `variables` it declares, `latest_version`, and its full `versions` history.

```bash theme={null}
curl https://api.orbit.devotel.io/api/v1/agents/prompt-templates \
  -H "X-API-Key: dv_live_sk_..."
```

Narrow the list with optional query filters. An empty or unknown filter value is ignored (the full catalog for that dimension comes back), never rejected:

* `category` — one template category, e.g. `sales`.
* `agentType` — the authored agent type, e.g. `voice`.
* `tag` — match a single tag (for example `bant`, `csat`).
* `search` — case-insensitive substring match over the id, name, description, and tags.

```bash theme={null}
curl "https://api.orbit.devotel.io/api/v1/agents/prompt-templates?category=sales&agentType=voice" \
  -H "X-API-Key: dv_live_sk_..."
```

The response also returns the valid `categories` and `agent_types` lists, so a picker can render the filter options without an extra round-trip. Fetch one template with its complete version history at `GET /agents/prompt-templates/:id`, or a single version's body at `GET /agents/prompt-templates/:id/versions/:version` (`:version` accepts an exact version string or the `latest` alias).

## 3. Fill the variables

Every template declares a `variables` schema — the placeholders its body references. Each variable has a `name`, a `description`, and an optional `default_value`:

* A variable with **no default** (`default_value: null`) should be filled before you fork. Forking without it still succeeds, but the `{{placeholder}}` stays literal in the resolved prompt and is listed in `unresolved_variables` so you can catch it before saving the agent.
* A variable **with a default** is optional — leave it blank and the default is substituted for you.

Unknown variable keys in the fork request are ignored, and a variable is never allowed to break the request — a partially filled fork resolves what it can and reports what it could not.

## 4. Fork to create

`POST /agents/prompt-templates/:id/fork` resolves a chosen version's body against your variable values and returns a ready-to-use system prompt. No agent is created and nothing is persisted — the fork only lands when you save it.

```bash theme={null}
curl -X POST https://api.orbit.devotel.io/api/v1/agents/prompt-templates/inbound-sales-qualifier/fork \
  -H "X-API-Key: dv_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "version": "1.0.0",
    "variables": {
      "company": "Acme Corp",
      "product": "cloud call recording"
    }
  }'
```

The response carries the resolved prompt plus lineage metadata, so you always know which template and version produced it:

```json theme={null}
{
  "data": {
    "template_id": "inbound-sales-qualifier",
    "template_name": "Inbound sales qualifier",
    "template_version": "1.0.0",
    "system_prompt": "You are an inbound sales assistant for Acme Corp selling cloud call recording. ...",
    "unresolved_variables": []
  },
  "meta": { "request_id": "req_...", "timestamp": "2026-08-27T12:00:00.000Z" }
}
```

Take the returned `system_prompt` into either surface:

* **Dashboard** — on `/agents/prompt-templates`, fork a template and click **Use in new agent**. The create-agent wizard opens pre-seeded with the resolved prompt, the template name, and the authored agent type (`agent_type` is a hint — you can change it in the wizard).
* **API** — pass `system_prompt` on the standard [create-agent](/agents/creating-agents) body, or `PUT /agents/:id` to update an existing agent.

Check `unresolved_variables` in the fork response before saving: any placeholder you skipped is listed there and remains literal `{{placeholder}}` text in the prompt. Fill it on the next fork, or edit the prompt in the wizard.

Omit `version` in the fork body to resolve the latest version.

## 5. Versioning: pin the version you fork

Every revision of a template is an immutable, published entry with its own version string, release date, and changelog. Curated catalog updates **append a new version**; they never rewrite an existing one.

That makes the version you fork your safety anchor:

* Fork with an explicit `version` (for example `1.1.0`) and your agent keeps exactly that prompt text even when the catalog later publishes `1.2.0`.
* Fork with no `version` and you track `latest` — convenient for a first pass, but a later catalog update changes what the same call returns.

For a production agent, record the version you forked (the response's `template_version`) so a re-fork after a catalog update resolves the same body rather than silently picking up new prompt text. The dashboard's version picker shows every published version newest-first, with the changelog line for each, so you can see what changed before you move an agent to a newer revision.

## 6. Where it lives

* **Dashboard:** `Agents → Prompt Template Library` (`/agents/prompt-templates`) — browse, search, filter by category, fork, and drop the resolved prompt into the create-agent wizard.
* **API:** list at `GET /agents/prompt-templates`, one template at `GET /agents/prompt-templates/:id`, one version at `GET /agents/prompt-templates/:id/versions/:version`, fork at `POST /agents/prompt-templates/:id/fork`.

The catalog is read-only — templates are curated centrally, so there is no create, update, or delete endpoint. Your fork exists only as the `system_prompt` you save onto an agent.

## 7. End-to-end example: seed a sales agent

Fork `inbound-sales-qualifier` with your company and product, then create the agent with the resolved prompt.

**Fork the template:**

```bash theme={null}
curl -X POST https://api.orbit.devotel.io/api/v1/agents/prompt-templates/inbound-sales-qualifier/fork \
  -H "X-API-Key: dv_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "variables": {
      "company": "Acme Corp",
      "product": "cloud call recording"
    }
  }'
```

**Create the agent** from the returned `system_prompt` (a `PUT /agents/:id` with the same field updates an existing agent):

```bash theme={null}
curl -X POST https://api.orbit.devotel.io/api/v1/agents \
  -H "X-API-Key: dv_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Inbound sales qualifier",
    "description": "Qualifies inbound leads and books follow-ups",
    "model": "claude-sonnet-4-6",
    "system_prompt": "You are an inbound sales assistant for Acme Corp selling cloud call recording. Greet the caller warmly, learn what problem they are trying to solve, and qualify their need, timeline, and decision role with a few natural questions — do not interrogate. Never quote a firm price or make a commitment you are not authorised to make. When the lead is qualified and interested, offer to book time with a human rep and confirm the details back to them. If the caller is not a fit, thank them politely and end the call.",
    "temperature": 0.3
  }'
```

From there the forked prompt is ordinary agent configuration: attach tools and a knowledge base, set guardrails, and deploy per [Creating agents](/agents/creating-agents).