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

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.

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