> ## 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.

# Agents Prompt Template Library

> Browse the curated prompt-template catalog, read version history, fill variables, and fork a starter into a draft agent — in the dashboard or over the API.

# Agents Prompt Template Library

The **Prompt Template Library** is a catalog of curated, versioned
system-prompt starters — support triage, sales qualification, scheduling,
collections, technical support, and surveys. Fork one, fill in its variables,
and drop it into a new agent instead of writing the prompt from scratch. The
catalog is the same for every organization, and each template keeps a full
version history so you can pin a known revision or track the latest.

Endpoint paths below are relative; send them against
`https://api.orbit.devotel.io/api/v1`.

## 1. Fork a template or author from a brief?

Both paths produce a draft agent. Pick based on how much you already know
about the prompt:

* **Fork a template** when the use case is a familiar one — a triage queue,
  appointment booking, a payment reminder. You get a rehearsed structure with
  named placeholders for your company details, and each version's changelog
  tells you what the curators changed.
* **Author from a brief** when the use case is specific to your business and
  no template fits. The from-prompt builder generates the draft from a
  plain-English description. See
  [Author an AI Agent from a Prompt](/guides/agent-from-prompt).

You can also do both: fork a template for the skeleton, then rewrite the
sections that need your own voice before activating.

## 2. Browse the catalog in the dashboard

Open **Agents → Prompt templates**
([/agents/prompt-templates](https://orbit.devotel.io/en/agents/prompt-templates)).
The page lists every template as a card with its name, description, category,
agent type, and latest version number.

Narrow the catalog three ways:

* **Search** — matches template id, name, description, and tags.
* **Category** — customer support, sales, scheduling, collections, technical
  support, or survey.
* **Agent type** (API) — voice, chatbot, router, workflow, or custom. This is
  advisory metadata for filtering; a template is text and you can apply it to
  any agent.

An empty search with a category filter selected tells you the filter matched
zero templates rather than that the catalog is empty.

## 3. Read version history

Select a template card to open its detail dialog. The response — and the API —
carries every published version with a release date and a one-line changelog,
so you can compare what changed before choosing. Forking a version you never
read is how stale placeholders ship into production prompts, so check the
changelog lines between the version you pinned previously and the new latest
before upgrading an agent.

Versions are immutable: forking `1.0.0` today returns the same body it
returned when it was curated, and a new curated revision lands as a new
version entry. Forks that pinned an older version keep working.

## 4. Fill variables and fork into a draft agent

In the detail dialog, pick a version, then fill each variable input —
templates declare placeholders like `{{company}}` or `{{businessHours}}` and
substitute your values into the body on fork. Variables with a curated
default fill themselves when you leave the input blank.

Click **Fork** and read the resolved system prompt. If you skipped a
variable, the dialog lists the placeholders left literal so nothing
half-substituted reaches the agent. Either fix the inputs and fork again or
edit the prompt in the agent later.

When the prompt reads right, click **Use in new agent** — the create-agent
dialog opens pre-filled with the resolved prompt, the template's agent type,
and the template name as the starting agent name. The fork itself stores
nothing; the agent is created only when you save that dialog. Every fork is
recorded in your organization's audit log with the template id and version.

## 5. API equivalents

The dashboard page is a thin client over four endpoints. Everything below is
a curl end-to-end: list, read one template, read a pinned version, fork.

List the catalog (all filters optional; empty or unknown values simply list
everything for that dimension):

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

The response echoes the valid `categories` and `agent_types` values alongside
`templates` and `total`, so a client can build its picker from one call.

Read one template with its full version history:

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

Read one version's body — `:version` accepts an exact version string or the
`latest` alias:

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

Fork a chosen version with your variable values:

```bash theme={null}
curl -X POST https://api.orbit.devotel.io/api/v1/agents/prompt-templates/appointment-scheduler/fork \
  -H "X-API-Key: dv_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "version": "latest",
    "variables": {
      "company": "Acme Clinic",
      "businessHours": "Mon-Fri 9:00-17:00"
    }
  }'
```

The response carries the resolved `system_prompt`, the lineage fields
`template_id` and `template_version`, and `unresolved_variables` — any
placeholder left literal because no value or default covered it. Treat a
non-empty `unresolved_variables` list as a warning, not an error.

– `GET /agents/prompt-templates` — list the catalog (`category`, `agentType`,
`tag`, `search` filters).
– `GET /agents/prompt-templates/:id` — one template plus every version.
– `GET /agents/prompt-templates/:id/versions/:version` — one version's body.
– `POST /agents/prompt-templates/:id/fork` — resolve a version into a system
prompt with your variables.

Fork performs no write — the prompt lands on an agent when you save it via
the agent create/update endpoints with `system_prompt` set to the forked
body.

## 6. Roles and scopes

* **Reading the catalog** — any authenticated user. Your API key needs no
  special scope to list or read templates.
* **Forking** — the owner, admin, or developer role, and an API key with the
  `agents:write` scope, because the fork's natural next step is writing the
  prompt to an agent. Viewers can browse but cannot fork.

## Troubleshooting

* **404 on a known template id** — ids are stable kebab-case strings (for
  example `appointment-scheduler`); re-list the catalog and copy the `id`
  field verbatim.
* **404 on a version** — fork or read a version from the template's
  `versions` list, or use the `latest` alias.
* **422 on fork** — the body must be an object; `variables` values must be
  strings. An empty body is valid and forks the latest version with defaults.
* **Empty result list** — a filter is active. Clear the search and category
  filter: unknown or cleared filter values never error, they simply stop
  filtering.