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

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.

curl "https://api.orbit.devotel.io/api/v1/agents/templates" \
  -H "X-API-Key: dv_live_sk_your_key_here"

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",
);

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"]

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)

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
$ch = curl_init("https://api.orbit.devotel.io/api/v1/agents/templates");
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ["X-API-Key: " . getenv("ORBIT_API_KEY")],
]);
$res = json_decode(curl_exec($ch), true);
$templates = $res["data"]["templates"];
?>

Response 200:

{
  "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:

curl "https://api.orbit.devotel.io/api/v1/agents/templates/tpl_voice_afterhours" \
  -H "X-API-Key: dv_live_sk_your_key_here"

404 Error

{
  "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.

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" }'

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;

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:

{
  "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 — 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

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. Send one initial message and read the reply.

curl -X POST "https://api.orbit.devotel.io/api/v1/agents/agt_a41c829e77d902/conversations" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "What are your store hours this Saturday?"
  }'

const res = await orbit.request(
  "POST",
  "/agents/agt_a41c829e77d902/conversations",
  { message: "What are your store hours this Saturday?" },
);
console.log(res.data.conversation_id, res.data.reply);

res = requests.post(
    "https://api.orbit.devotel.io/api/v1/agents/agt_a41c829e77d902/conversations",
    headers={
        "X-API-Key": os.environ["ORBIT_API_KEY"],
        "Content-Type": "application/json",
    },
    json={"message": "What are your store hours this Saturday?"},
)
body = res.json()
print(body["data"]["conversation_id"], body["data"]["reply"])

body := `{"message":"What are your store hours this Saturday?"}`
req, _ := http.NewRequest("POST", "https://api.orbit.devotel.io/api/v1/agents/agt_a41c829e77d902/conversations", strings.NewReader(body))
req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
req.Header.Set("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()

uri = URI("https://api.orbit.devotel.io/api/v1/agents/agt_a41c829e77d902/conversations")
res = Net::HTTP.post(uri,
  '{"message":"What are your store hours this Saturday?"}',
  "Content-Type" => "application/json",
  "X-API-Key" => ENV["ORBIT_API_KEY"])

<?php
$ch = curl_init("https://api.orbit.devotel.io/api/v1/agents/agt_a41c829e77d902/conversations");
curl_setopt_array($ch, [
  CURLOPT_POST => true,
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-API-Key: " . getenv("ORBIT_API_KEY"),
  ],
  CURLOPT_POSTFIELDS => '{"message":"What are your store hours this Saturday?"}',
]);
$res = json_decode(curl_exec($ch), true);
echo $res["data"]["conversation_id"] . " " . $res["data"]["reply"];
?>

Response 200:

{
  "data": {
    "conversation_id": "cnv_7f2b10c893a1e4",
    "reply": "Our store is open 10 AM to 6 PM on Saturdays. Anything else I can help with?",
    "turn": 1,
    "status": "active"
  },
  "meta": {
    "request_id": "req_cnv_d8301fa",
    "timestamp": "2026-09-15T14:05:22.118Z"
  }
}

404 Error — invalid assistant id

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Agent agt_a41c829e77d902 not found in this tenant.",
    "status": 404
  },
  "meta": {
    "request_id": "req_cnv_e9402fb",
    "timestamp": "2026-09-15T14:05:23.442Z"
  }
}

The reply carries the first turn; step through further turns by posting with the same conversation_id. The full conversation shape — turns, tool calls, handoffs, CSAT — is covered on the Agents API reference.

API Reference

All Endpoints

Assistant templates: instantiate, preview, and test

Assistant templates

Worked sequence: browse, read, instantiate, test

1. List the catalog

2. Read one template detail

3. Instantiate the template into your tenant

4. Test the instantiated assistant end to end

See also

​Assistant templates

​Worked sequence: browse, read, instantiate, test

​1. List the catalog

​2. Read one template detail

​3. Instantiate the template into your tenant

​4. Test the instantiated assistant end to end

​See also

Assistant templates

Worked sequence: browse, read, instantiate, test

1. List the catalog

2. Read one template detail

3. Instantiate the template into your tenant

4. Test the instantiated assistant end to end

See also