> ## 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.
# Assistant templates: instantiate, preview, and test
> Find a pre-built assistant template, instantiate it into a live agent in your organization, preview the rendered prompt, and run the agent-API test conversation — with one template_id reused across the sequence and a full envelope on every call.
# Assistant templates
A **template** is a curated pre-built assistant — a system prompt, model pick, voice configuration, and channel compatibility set that the agent wizard applies in one click. Templates are read-only catalog entries; the only write on this surface is `instantiate`, which clones a template into a new assistant in your organization. Field-level reference lives in the [Agents templates endpoints](/api-reference/endpoints/agents); this page walks the flow end to end.
**Base path:** `/api/v1/agents/templates`
**Authentication:** API key (`X-API-Key`) or session JWT. Reads are open to any authenticated role; instantiate requires `owner`, `admin`, or `developer`.
Every response below carries the full `{ data, meta }` envelope and at least one labelled error envelope — the same floor as the [SDK sample coverage policy](/api-reference/sdk-language-policy).
## Worked sequence: browse, read, instantiate, test
### 1. List the catalog
The catalog's `templates` array is the plain pre-rendered list; there is no server-side filter — filter by `agent_type` on your side when you only want, say, `voice`.
```bash cURL theme={null}
curl "https://api.orbit.devotel.io/api/v1/agents/templates" \
-H "X-API-Key: dv_live_sk_your_key_here"
```
```typescript Node.js theme={null}
import { Orbit } from "@devotel-orbit/node";
const orbit = new Orbit({ apiKey: process.env.ORBIT_API_KEY });
const res = await orbit.request("GET", "/agents/templates");
const voiceTemplates = res.data.templates.filter(
(t) => t.agent_type === "voice",
);
```
```python Python theme={null}
import os
import requests
res = requests.get(
"https://api.orbit.devotel.io/api/v1/agents/templates",
headers={"X-API-Key": os.environ["ORBIT_API_KEY"]},
)
templates = res.json()["data"]["templates"]
voice_templates = [t for t in templates if t["agent_type"] == "voice"]
```
```go Go theme={null}
req, _ := http.NewRequest("GET", "https://api.orbit.devotel.io/api/v1/agents/templates", nil)
req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
var out struct {
Data struct {
Templates []struct {
ID string `json:"id"`
Name string `json:"name"`
AgentType string `json:"agent_type"`
} `json:"templates"`
} `json:"data"`
}
json.NewDecoder(res.Body).Decode(&out)
```
```ruby Ruby theme={null}
uri = URI("https://api.orbit.devotel.io/api/v1/agents/templates")
res = Net::HTTP.get_response(uri) do |req|
req["X-API-Key"] = ENV["ORBIT_API_KEY"]
end
templates = JSON.parse(res.body).dig("data", "templates")
```
```php PHP theme={null}
true,
CURLOPT_HTTPHEADER => ["X-API-Key: " . getenv("ORBIT_API_KEY")],
]);
$res = json_decode(curl_exec($ch), true);
$templates = $res["data"]["templates"];
?>
```
Response `200`:
```json theme={null}
{
"data": {
"templates": [
{
"id": "tpl_voice_afterhours",
"name": "After-hours support",
"description": "Answers store-hours and order-status questions when the call goes to voicemail.",
"agent_type": "voice",
"channels": ["voice"],
"model": "claude-sonnet-4-6",
"test_call_script": "Thank you for calling Acme Kitchens after hours. How can I help?"
},
{
"id": "tpl_chat_orderstatus",
"name": "Order-status chatbot",
"description": "Handles order-tracking questions over SMS / WhatsApp with a lookup tool pre-wired.",
"agent_type": "chatbot",
"channels": ["sms", "whatsapp"],
"model": "claude-haiku-4-5-20251001",
"test_call_script": "Hi — what can I help you with?"
}
],
"total": 2
},
"meta": {
"request_id": "req_tpc_2981acf",
"timestamp": "2026-09-15T14:02:11.531Z"
}
}
```
### 2. Read one template detail
Before instantiating, fetch the template's id so the call can surface its prompt fields. Unknown ids answer `404` with a labelled error envelope:
```bash theme={null}
curl "https://api.orbit.devotel.io/api/v1/agents/templates/tpl_voice_afterhours" \
-H "X-API-Key: dv_live_sk_your_key_here"
```
```json 404 Error theme={null}
{
"error": {
"code": "NOT_FOUND",
"message": "Template tpl_voice_afterhours not in the curated catalog.",
"status": 404
},
"meta": {
"request_id": "req_tpg_4be2c01",
"timestamp": "2026-09-15T14:03:18.007Z"
}
}
```
### 3. Instantiate the template into your tenant
`POST instantiate` clones the template into a new assistant row, renders the prompt against your organization's jurisdiction, and returns the new assistant record. Repeat `instantiate` with a stable `Idempotency-Key` header to dedupe lobby-level retries.
```bash cURL theme={null}
curl -X POST "https://api.orbit.devotel.io/api/v1/agents/templates/tpl_voice_afterhours/instantiate" \
-H "X-API-Key: dv_live_sk_your_key_here" \
-H "Idempotency-Key: instantiate-2026-09-15-1" \
-H "Content-Type: application/json" \
-d '{ "name": "After-hours support — storefront", "description": "Voice assistant for storefront callers" }'
```
```typescript Node.js theme={null}
const res = await orbit.request(
"POST",
"/agents/templates/tpl_voice_afterhours/instantiate",
{
name: "After-hours support — storefront",
description: "Voice assistant for storefront callers",
},
);
const assistantId = res.data.id;
```
```python Python theme={null}
res = requests.post(
"https://api.orbit.devotel.io/api/v1/agents/templates/tpl_voice_afterhours/instantiate",
headers={
"X-API-Key": os.environ["ORBIT_API_KEY"],
"Idempotency-Key": "instantiate-2026-09-15-1",
"Content-Type": "application/json",
},
json={
"name": "After-hours support — storefront",
"description": "Voice assistant for storefront callers",
},
)
assistant_id = res.json()["data"]["id"]
```
Response `200`:
```json theme={null}
{
"data": {
"id": "agt_a41c829e77d902",
"name": "After-hours support — storefront",
"type": "voice",
"status": "draft",
"model": "claude-sonnet-4-6",
"config": {
"template_id": "tpl_voice_afterhours",
"rendered_prompt": "You answer after-hours calls for Acme Kitchens (IN jurisdiction). Where jurisdiction requires, greet with the call-recording disclosure. Route emergencies to the on-call line."
},
"created_at": "2026-09-15T14:04:19.212Z"
},
"meta": {
"request_id": "req_tpi_b71c884",
"timestamp": "2026-09-15T14:04:19.212Z"
}
}
```
The new assistant id (`agt_a41c829e77d902`) goes straight into the [Assistant lifecycle](/api-reference/assistants) — create, deploy, list, fetch, update, delete. The `config.template_id` back-pointer lets you trace the instance to the curated source during support.
### 4. Test the instantiated assistant end to end
Send one message against the new assistant id over the conversation API — `POST /api/v1/agents/{id}/conversations` opens a conversation you can step through turn by turn. The conversation path only exists once `instantiate` returned `200`. An invalid id answers the same `404 NOT_FOUND` envelope shown in step 2.
## See also
* [AI assistants](/api-reference/assistants) — the lifecycle for the instantiated agent
* [Agents API](/api-reference/agents) — field-level reference
* [Agent model presets](/guides/agents-model-presets) — the curated STT+LLM+TTS bundles for voice agents