AI assistants

An assistant is an Orbit AI agent: a named system prompt, model, and tool set that you bind to a channel when you deploy it. This page is the worked reference for the assistant lifecycle — create, list, fetch, update, deploy, undeploy, and delete — with one assistant_id carried across the whole sequence. Field-level reference lives in the Agents API; this page walks the sequence end to end. Base path: /api/v1/agents Authentication: API key (X-API-Key) or session JWT. Create, update, deploy, undeploy, and delete require an owner, admin, or developer role; list and fetch are open to any authenticated role. Every response below carries the full { data, meta } envelope — meta.request_id and meta.timestamp on the success path, a labelled error envelope on the failure path — the same floor as SDK sample coverage policy.

Lifecycle worked sequence

Create the assistant once, reuse its assistant_id for everything afterward. Nothing seeds channel binding on create — the agent lands as a draft, and deploy flips it active.

1. Create the assistant

curl -X POST "https://api.orbit.devotel.io/api/v1/agents" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Order support assistant",
    "type": "chatbot",
    "model": "claude-sonnet-4-6",
    "system_prompt": "You answer order-status questions for Acme Kitchens. Cite the order id in every reply.",
    "tools": [
      {
        "name": "lookup_order",
        "description": "Fetch one order by id",
        "parameters": {
          "type": "object",
          "properties": { "order_id": { "type": "string" } },
          "required": ["order_id"]
        }
      }
    ],
    "safety_config": { "pii_redaction": true, "content_filter": true }
  }'

import { Orbit } from "@devotel-orbit/node";

const orbit = new Orbit({ apiKey: process.env.ORBIT_API_KEY });

const created = await orbit.request("POST", "/agents", {
  name: "Order support assistant",
  type: "chatbot",
  model: "claude-sonnet-4-6",
  system_prompt:
    "You answer order-status questions for Acme Kitchens. Cite the order id in every reply.",
  tools: [
    {
      name: "lookup_order",
      description: "Fetch one order by id",
      parameters: {
        type: "object",
        properties: { order_id: { type: "string" } },
        required: ["order_id"],
      },
    },
  ],
  safety_config: { pii_redaction: true, content_filter: true },
});

const assistantId = created.data.id;

import os
import requests

headers = {
    "X-API-Key": os.environ["ORBIT_API_KEY"],
    "Content-Type": "application/json",
}

body = {
    "name": "Order support assistant",
    "type": "chatbot",
    "model": "claude-sonnet-4-6",
    "system_prompt": "You answer order-status questions for Acme Kitchens. Cite the order id in every reply.",
    "tools": [
        {
            "name": "lookup_order",
            "description": "Fetch one order by id",
            "parameters": {
                "type": "object",
                "properties": {"order_id": {"type": "string"}},
                "required": ["order_id"],
            },
        }
    ],
    "safety_config": {"pii_redaction": True, "content_filter": True},
}

res = requests.post(
    "https://api.orbit.devotel.io/api/v1/agents",
    headers=headers,
    json=body,
)
assistant_id = res.json()["data"]["id"]

package main

import (
	"bytes"
	"encoding/json"
	"net/http"
	"os"
)

func main() {
	body := []byte(`{
	  "name": "Order support assistant",
	  "type": "chatbot",
	  "model": "claude-sonnet-4-6",
	  "system_prompt": "You answer order-status questions for Acme Kitchens. Cite the order id in every reply.",
	  "tools": [{
	    "name": "lookup_order",
	    "description": "Fetch one order by id",
	    "parameters": {
	      "type": "object",
	      "properties": { "order_id": { "type": "string" } },
	      "required": ["order_id"]
	    }
	  }],
	  "safety_config": { "pii_redaction": true, "content_filter": true }
	}`)
	req, _ := http.NewRequest("POST", "https://api.orbit.devotel.io/api/v1/agents", bytes.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()
	var out struct {
		Data struct {
			ID string `json:"id"`
		} `json:"data"`
	}
	json.NewDecoder(res.Body).Decode(&out)
	// out.Data.ID is the assistant_id reused below
}

require "net/http"
require "json"

uri = URI("https://api.orbit.devotel.io/api/v1/agents")
req = Net::HTTP::Post.new(uri)
req["X-API-Key"] = ENV["ORBIT_API_KEY"]
req["Content-Type"] = "application/json"
req.body = JSON.dump(
  name: "Order support assistant",
  type: "chatbot",
  model: "claude-sonnet-4-6",
  system_prompt: "You answer order-status questions for Acme Kitchens. Cite the order id in every reply.",
  tools: [{
    name: "lookup_order",
    description: "Fetch one order by id",
    parameters: {
      type: "object",
      properties: { order_id: { type: "string" } },
      required: ["order_id"]
    }
  }],
  safety_config: { pii_redaction: true, content_filter: true }
)
res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |h| h.request(req) }
assistant_id = JSON.parse(res.body).dig("data", "id")

<?php
$ch = curl_init("https://api.orbit.devotel.io/api/v1/agents");
$body = json_encode([
  "name" => "Order support assistant",
  "type" => "chatbot",
  "model" => "claude-sonnet-4-6",
  "system_prompt" => "You answer order-status questions for Acme Kitchens. Cite the order id in every reply.",
  "tools" => [[
    "name" => "lookup_order",
    "description" => "Fetch one order by id",
    "parameters" => [
      "type" => "object",
      "properties" => ["order_id" => ["type" => "string"]],
      "required" => ["order_id"],
    ],
  ]],
  "safety_config" => ["pii_redaction" => true, "content_filter" => true],
]);
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_POST => true,
  CURLOPT_POSTFIELDS => $body,
  CURLOPT_HTTPHEADER => [
    "X-API-Key: " . getenv("ORBIT_API_KEY"),
    "Content-Type: application/json",
  ],
]);
$res = json_decode(curl_exec($ch), true);
$assistantId = $res["data"]["id"];
?>

Response 201:

{
  "data": {
    "id": "agt_8f2e41abcc9d70",
    "name": "Order support assistant",
    "type": "chatbot",
    "model": "claude-sonnet-4-6",
    "status": "draft",
    "created_at": "2026-09-15T13:11:02.418Z"
  },
  "meta": {
    "request_id": "req_agc_9d31ef2",
    "timestamp": "2026-09-15T13:11:02.418Z"
  }
}

Carry the returned assistant_id (agt_8f2e41abcc9d70) through the rest of this page — it is the same id you pass to fetch, update, deploy, undeploy, and delete.

2. Deploy the assistant to a channel

deploy binds a channel and moves the assistant out of draft into active. The channel name is one of webhook, sms, whatsapp, voice, or rcs; webhook_url is required only for webhook channels, and a phone_number is required only for SMS / WhatsApp / voice.

curl -X POST "https://api.orbit.devotel.io/api/v1/agents/agt_8f2e41abcc9d70/deploy" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "channel": "sms", "phone_number": "+14155550100" }'

Response 200 — status is active and config.deployment carries the channel binding:

{
  "data": {
    "id": "agt_8f2e41abcc9d70",
    "status": "active",
    "config": {
      "deployment": {
        "channel": "sms",
        "phone_number": "+14155550100",
        "deployed_at": "2026-09-15T13:14:50.117Z"
      }
    }
  },
  "meta": {
    "request_id": "req_dpl_77a1b2",
    "timestamp": "2026-09-15T13:14:50.117Z"
  }
}

3. List to confirm the assistant is live

curl "https://api.orbit.devotel.io/api/v1/agents?status=active&limit=1" \
  -H "X-API-Key: dv_live_sk_your_key_here"

Response 200 — the envelope’s meta.pagination carries the cursor and has_more pair you use to walk the full list:

{
  "data": [
    {
      "id": "agt_8f2e41abcc9d70",
      "name": "Order support assistant",
      "type": "chatbot",
      "model": "claude-sonnet-4-6",
      "status": "active",
      "created_at": "2026-09-15T13:11:02.418Z",
      "active_conversations": 1,
      "conversation_count": 4,
      "total_tokens": 981,
      "version": 1
    }
  ],
  "meta": {
    "request_id": "req_agl_201d88x",
    "timestamp": "2026-09-15T13:16:22.044Z",
    "pagination": {
      "cursor": "2026-09-15T13:11:02.418Z|agt_8f2e41abcc9d70",
      "has_more": false,
      "total": 1
    }
  }
}

4. Fetch one assistant by id

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

Same envelope as the list, without pagination. Use this form when you already know the id — there is no separate “assistant detail” resource.

5. Update the system prompt, tools, or safety config in place

PATCH rewrites only the fields you send. Bump the prompt or safety configuration without redeploying.

curl -X PATCH "https://api.orbit.devotel.io/api/v1/agents/agt_8f2e41abcc9d70" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "system_prompt": "You answer order-status questions for Acme Kitchens. Cite the order id in every reply, and link the tracking URL from the order record." }'

Response 200:

{
  "data": {
    "id": "agt_8f2e41abcc9d70",
    "version": 2,
    "updated_at": "2026-09-15T13:24:18.508Z"
  },
  "meta": {
    "request_id": "req_agp_31ed47c",
    "timestamp": "2026-09-15T13:24:18.508Z"
  }
}

6. Undeploy, then delete

undeploy drops the channel binding and flips status back to draft. Delete the assistant only when it is no longer needed — conversation history stays on the tenant.

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

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

Undeploy returns 200 with the same envelope. Delete returns 204 No Content with an empty body.

Error envelopes

An unknown id — whether passed to fetch, update, deploy, undeploy, or delete — answers 404 with a labelled error envelope, not a bare status:

404 Error

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Assistant agt_8f2e41abcc9d70 was not found in this organization.",
    "status": 404
  },
  "meta": {
    "request_id": "req_age_41d0b8",
    "timestamp": "2026-09-15T13:30:02.447Z"
  }
}

Validation failures on create come back as 422 VALIDATION_ERROR — one entry per field, with the same meta block. A cross-tenant id returns the same 404 NOT_FOUND as one that never existed, so existence cannot be probed across organizations. If you receive a 403 INSUFFICIENT_PERMISSIONS, the caller’s role is below developer; only owner, admin, and developer may write assistants.

Escape hatches beyond the Node.js and Python samples

Every public SDK ships an untyped request method that reaches any endpoint when a typed helper does not exist yet — the same semantics as the Agents API page’s Python escape hatch. The per-language idiom:

Go — plain net/http; set X-API-Key + Content-Type and decode the { data, meta } envelope directly.
Ruby — Net::HTTP over the host + path pair; JSON.parse the envelope.
PHP — cURL with json_encode bodies; json_decode returns the envelope as an associative array.
Java / C# — client.RequestAsync / client.request per the SDK language policy’s escape-hatch table; the route shape above applies verbatim.

See also Agents API for the full field catalogue and Agent templates for the pre-built-into-assistant flow.

API Reference

All Endpoints

AI assistants: create, deploy, and run the lifecycle

AI assistants

Lifecycle worked sequence

1. Create the assistant

2. Deploy the assistant to a channel

3. List to confirm the assistant is live

4. Fetch one assistant by id

5. Update the system prompt, tools, or safety config in place

6. Undeploy, then delete

Error envelopes

Escape hatches beyond the Node.js and Python samples

​AI assistants

​Lifecycle worked sequence

​1. Create the assistant

​2. Deploy the assistant to a channel

​3. List to confirm the assistant is live

​4. Fetch one assistant by id

​5. Update the system prompt, tools, or safety config in place

​6. Undeploy, then delete

​Error envelopes

​Escape hatches beyond the Node.js and Python samples

AI assistants

Lifecycle worked sequence

1. Create the assistant

2. Deploy the assistant to a channel

3. List to confirm the assistant is live

4. Fetch one assistant by id

5. Update the system prompt, tools, or safety config in place

6. Undeploy, then delete

Error envelopes

Escape hatches beyond the Node.js and Python samples