Languages: every operation supports cURL, Node.js (TypeScript), Python, Go, Ruby, and PHP. The first 15 operations on this page show all six languages; the remaining 10 show cURL and TypeScript — the two most-used.

AI API

AI endpoints exposed by the Devotel CPaaS API Base path: /api/v1/ai Endpoint count: 25

title: “AI Knowledge Base endpoints (ingest, refresh, search)” description: “Curated note covering the embedded org-wide knowledge base in the AI API, with endpoints for document ingest, staleness scoring, and grounded search.”

The AI API also includes an embedded, org-wide Knowledge Base — not shown in the auto-generated endpoint list below. Ingest documents by upload, URL, markdown, or bulk help-center import (POST /api/v1/ai/kb/documents, POST /api/v1/ai/kb/import/help-center), keep them fresh with a staleness scorecard and per-document verification (GET /api/v1/ai/kb/staleness, POST /api/v1/ai/kb/documents/{id}/verify), and query them with raw semantic search (POST /api/v1/ai/kb/search) or a grounded answer with citations (POST /api/v1/ai/kb/answers). See the full AI Knowledge Base reference. For a separately provisioned, per-knowledge-base store, use the Knowledge Bases API.

Worked session/memory + budget envelopes

The auto-generated response examples below show the OpenAPI schema shape. The worked envelopes in this section show the exact fields your integration sees, with real values, across the three AI chains the reference below only half-covers: the per-contact session-memory read/write pair, the per-agent token-budget precheck, and the chat response the whole flow ends in. Together with the worked agent samples they give you a body you can branch on for every call an agent build makes first. Both the memory round trip and the budget precheck are tenant-owned controls: memory facts are scoped to one contact (and deleted with the contact’s GDPR erasure), and the token budget is a per-agent cap your workspace sets. The session-memory pair has its four statuses — 201 write, 200 read, 409 opt-out or per-contact fact cap, 422 validation.

1. Session memory round trip

Teach the agent a fact about a contact, then read the same contact’s facts back. The write returns 201 with the stored item; the read returns the newest facts with PII in the fact bodies masked unless your role is in the unmask allowlist and you pass ?reveal=true. When the contact has opted out of memory the write returns 409 MEMORY_DISABLED_FOR_CONTACT and the read returns an empty list with memory_enabled: false.

POST /api/v1/agents/{agentId}/memory

Manual teach. contact_id and fact are required; source is manual (default) or conversation, and importance (0–1) overrides the default 0.9 for manual teaches. The fact body is sanitised, capped to your tenant’s content limit, and stored with an embedding so the agent can retrieve it in later turns. Request

{
  "contact_id": "ctt_4f2a9c1e",
  "fact": "Prefers SMS over calls; contract renews 2026-10-01.",
  "source": "manual",
  "importance": 0.9
}

{
  "data": {
    "item": {
      "id": "memory_7b2d4f6a",
      "tenantId": "tnt_9c1e3a5b",
      "contactId": "ctt_4f2a9c1e",
      "agentId": "agt_7e3b9c1f",
      "memoryType": "fact",
      "content": "Prefers SMS over calls; contract renews 2026-10-01.",
      "importance": 0.9,
      "createdAt": "2026-08-01T12:00:00.000Z",
      "expiresAt": "2026-10-30T12:00:00.000Z"
    }
  },
  "meta": {
    "request_id": "req_mem_teach",
    "timestamp": "2026-08-01T12:00:00.000Z"
  }
}

GET /api/v1/agents/{agentId}/memory?contact_id=ctt_4f2a9c1e

Read back the same contact’s facts. By default only fact-type entries are returned and phone/email tokens in the bodies are PII-masked; owner, admin, and developer roles can pass reveal=true to unmask (each reveal is audit-logged). A contact that has opted out returns an empty items list with memory_enabled: false.

{
  "data": {
    "items": [
      {
        "id": "memory_7b2d4f6a",
        "tenantId": "tnt_9c1e3a5b",
        "contactId": "ctt_4f2a9c1e",
        "agentId": "agt_7e3b9c1f",
        "memoryType": "fact",
        "content": "Prefers SMS over calls; contract renews 2026-10-01.",
        "importance": 0.9,
        "createdAt": "2026-08-01T12:00:00.000Z",
        "expiresAt": "2026-10-30T12:00:00.000Z"
      }
    ],
    "memory_enabled": true,
    "agent_id": "agt_7e3b9c1f",
    "contact_id": "ctt_4f2a9c1e",
    "facts_only": true
  },
  "meta": {
    "request_id": "req_mem_read",
    "timestamp": "2026-08-01T12:00:00.000Z"
  }
}

The 409 the write returns when the contact has opted out — branch on this before you surface “teach the agent” in your UI:

409

{
  "error": {
    "code": "MEMORY_DISABLED_FOR_CONTACT",
    "status": 409,
    "message": "This contact has opted out of memory storage (memory_enabled = false)."
  },
  "meta": {
    "request_id": "req_...",
    "timestamp": "2026-08-01T12:00:00.000Z"
  }
}

2. Token-budget precheck

Evaluate an action against your agent’s governance policies before the send, so a long turn never starts when it would be denied. Pass the intended model, the tool id (if the action invokes a tool), and the tokens the agent has already consumed this UTC month. The response merges every enabled policy that applies to the agent and returns a single allow/deny verdict with the effective caps it resolved — the monthly token budget is the strictest (minimum) across applying policies, and the model allowlist is the intersection. Gate on allowed: true/false; when the gate denies, reason is one of model_not_allowed, budget_exceeded, or sod_approval_required. Both fields you need to gate the send are on the envelope below.

GET /api/v1/agents/governance-internal/resolve?agent_id=agt_7e3b9c1f&model=claude-sonnet-4-6&monthly_tokens_used=84129

{
  "data": {
    "agent_id": "agt_7e3b9c1f",
    "applies": true,
    "allowed": true,
    "reason": "ok",
    "effective": {
      "applies": true,
      "policy_ids": ["gov_2b4d6f8a"],
      "prompt_guardrail": {
        "pii_redaction": true,
        "prompt_injection": true
      },
      "monthly_token_budget": 250000,
      "model_allowlist": ["claude-sonnet-4-6", "claude-haiku-4-5"],
      "sod_required": false,
      "sod_tools": []
    }
  },
  "meta": {
    "request_id": "req_gov_resolve",
    "timestamp": "2026-08-01T12:00:00.000Z"
  }
}

When the same call with monthly_tokens_used=250000 (already at the budget) the verdict flips — gate on it before you send:

200

{
  "data": {
    "agent_id": "agt_7e3b9c1f",
    "applies": true,
    "allowed": false,
    "reason": "budget_exceeded",
    "monthly_tokens_used": 250000
  },
  "meta": {
    "request_id": "req_gov_deny",
    "timestamp": "2026-08-01T12:00:00.000Z"
  }
}

Once the precheck clears, the turn itself is the chat call — the response carries the token split you add to your own usage accounting:

POST /api/v1/agents/{agentId}/chat

200

{
  "conversationId": "conv_8b2c4d6e1f",
  "response": "Open Settings > Security, then choose Reset password.",
  "tokens_used": 412,
  "prompt_tokens": 301,
  "completion_tokens": 111,
  "conversation_persisted": true
}

3. Errors-as-decision-table

Every /ai and /agents failure returns the same { error, meta } envelope. The error.code and status tell you which of the three decisions to take; don’t treat 4xx as one class.

Decision	Status + code	What it means	Response
Retry	`429 RATE_LIMITED` with `error.retry_after` (and a `Retry-After` header)	The AI rate bucket is exhausted for the window.	Wait `error.retry_after` seconds, then retry the identical request.
Retry	`502 BILLING_PROVIDER_ERROR`	Credits could not be debited for this call (a transient wallet/ledger hiccup) — nothing was charged.	Back off and retry; the request is safe to replay.
Retry	`503 SERVICE_UNAVAILABLE`	The upstream AI provider is unavailable.	Back off and retry; the platform marks it self-healing.
Reframe	`422 VALIDATION_ERROR` with `error.details`	The body/query failed schema validation.	Fix the named field and resend — retrying the same body will never succeed.
Reframe	`402 INSUFFICIENT_BALANCE`	Your wallet is out of credits for this metered AI call.	Top up, then resend.
Reframe	`409 MEMORY_DISABLED_FOR_CONTACT` / `409 MEMORY_FACTS_CAP_EXCEEDED`	The memory write is blocked by consent (opt-out) or the per-contact fact cap.	Respect the opt-out (never retry); on the cap, forget one fact before teaching another.
Escalate	`500 CREATE_FAILED` / `DELETE_FAILED`	The memory store rejected the write.	Retry once; if it persists, escalate with `meta.request_id`.

429

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded. Retry in 17 seconds.",
    "status": 429,
    "retry_after": 17
  },
  "meta": {
    "request_id": "req_...",
    "timestamp": "2026-08-01T12:00:00.000Z",
    "docs_url": "https://docs.orbit.devotel.io/errors/RATE_LIMITED"
  }
}

Retry buckets (429, 502, 503) are the only safe replay: they mean nothing was committed, so the same request can be resent after the wait. Reframe statuses (402, 409, 422) will fail identically every time until you change the request — and 409 MEMORY_DISABLED_FOR_CONTACT specifically means stop, because the contact revoked consent.

List knowledge-source connectors

GET /api/v1/ai/kb/connectors

Browse the knowledge-connector catalog — the discovery surface for first-class living-docs sources (Zendesk Help Center live today; Confluence / Notion / SharePoint / Google Drive catalogued). Static product metadata (no tenant data, no secrets), filterable by category, status, and a free-text search. Also returns per-category facet counts for the picker sidebar.

string

Filter by connector category. Validated against the catalog’s category enum by the controller (unknown value → 422).

string

Filter by availability status (e.g. ga, coming_soon). Validated against the catalog’s status enum by the controller (unknown value → 422).

string

Case-insensitive substring over connector id / name / description / objects.

string (enum: true|false)

Sandbox opt-in for Clerk-session-authenticated requests. Set to true to route the call through the test-mode pipeline: no real provider delivery, no credits deducted, response meta.test_mode: true. Ignored for live API keys (dv_live_sk_*) — server-to-server clients must use a test-prefixed key (dv_test_sk_*) to exercise sandbox. Test-prefixed keys unconditionally enable sandbox regardless of this header.

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/ai/kb/connectors" \
  -H "X-API-Key: dv_live_sk_your_key_here" 

Node.js

import { Orbit } from '@devotel-orbit/node'

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/ai/kb/connectors', {
  method: 'GET',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
  },
})
console.log(await res.json())

Python

import os, requests

headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
r = requests.get("https://api.orbit.devotel.io/api/v1/ai/kb/connectors", headers=headers)
print(r.json())

package main

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

func main() {
	req, _ := http.NewRequest("GET", "https://api.orbit.devotel.io/api/v1/ai/kb/connectors", nil)
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))

	http.DefaultClient.Do(req)
}

Ruby

require 'net/http'
require 'json'

uri = URI('https://api.orbit.devotel.io/api/v1/ai/kb/connectors')
req = Net::HTTP::Get.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']


res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.body

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/ai/kb/connectors');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),

]);

echo curl_exec($ch);

{
  "data": {
    "items": [
      {
        "id": "memory_7b2d4f6a",
        "tenantId": "tnt_9c1e3a5b",
        "contactId": "ctt_4f2a9c1e",
        "agentId": "agt_7e3b9c1f",
        "memoryType": "fact",
        "content": "Prefers SMS over calls; contract renews 2026-10-01.",
        "importance": 0.9,
        "createdAt": "2026-08-01T12:00:00.000Z",
        "expiresAt": "2026-10-30T12:00:00.000Z"
      }
    ],
    "memory_enabled": true,
    "agent_id": "agt_7e3b9c1f",
    "contact_id": "ctt_4f2a9c1e",
    "facts_only": true
  },
  "meta": {
    "request_id": "req_mem_read",
    "timestamp": "2026-08-01T12:00:00.000Z"
  }
}

Get a knowledge-source connector

GET /api/v1/ai/kb/connectors/{id}

Fetch one connector’s full metadata plus its activation descriptor — whether it can be connected today, via which import / re-sync backend, and which advertised objects are live now versus still on the roadmap. Returns 404 for an unknown slug.

string

required

The catalog connector slug, e.g. zendesk_help_center (lowercase letters, digits, underscores). 404 for an unknown slug.

string (enum: true|false)

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/ai/kb/connectors/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3" \
  -H "X-API-Key: dv_live_sk_your_key_here" 

Node.js

import { Orbit } from '@devotel-orbit/node'

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/ai/kb/connectors/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3', {
  method: 'GET',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
  },
})
console.log(await res.json())

Python

import os, requests

headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
r = requests.get("https://api.orbit.devotel.io/api/v1/ai/kb/connectors/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3", headers=headers)
print(r.json())

package main

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

func main() {
	req, _ := http.NewRequest("GET", "https://api.orbit.devotel.io/api/v1/ai/kb/connectors/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3", nil)
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))

	http.DefaultClient.Do(req)
}

Ruby

require 'net/http'
require 'json'

uri = URI('https://api.orbit.devotel.io/api/v1/ai/kb/connectors/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3')
req = Net::HTTP::Get.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']


res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.body

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/ai/kb/connectors/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),

]);

echo curl_exec($ch);

{
  "data": {
    "items": [
      {
        "id": "memory_7b2d4f6a",
        "tenantId": "tnt_9c1e3a5b",
        "contactId": "ctt_4f2a9c1e",
        "agentId": "agt_7e3b9c1f",
        "memoryType": "fact",
        "content": "Prefers SMS over calls; contract renews 2026-10-01.",
        "importance": 0.9,
        "createdAt": "2026-08-01T12:00:00.000Z",
        "expiresAt": "2026-10-30T12:00:00.000Z"
      }
    ],
    "memory_enabled": true,
    "agent_id": "agt_7e3b9c1f",
    "contact_id": "ctt_4f2a9c1e",
    "facts_only": true
  },
  "meta": {
    "request_id": "req_mem_read",
    "timestamp": "2026-08-01T12:00:00.000Z"
  }
}

List knowledge-base documents

GET /api/v1/ai/kb/documents

List the knowledge-base documents in the caller’s workspace, newest first, with keyset pagination. Each row carries the ingest status, chunk count, token total, byte size, and any last-error message — use it to render the KB management table and to poll a freshly-added document until its status flips from processing to ready. Page through large libraries with the previous page’s next_cursor.

string

Opaque keyset cursor from a prior page’s next_cursor. Omit for the first page.

integer

Page size (1-100). Defaults to 100.

string (enum: true|false)

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/ai/kb/documents" \
  -H "X-API-Key: dv_live_sk_your_key_here" 

Node.js

import { Orbit } from '@devotel-orbit/node'

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/ai/kb/documents', {
  method: 'GET',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
  },
})
console.log(await res.json())

Python

import os, requests

headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
r = requests.get("https://api.orbit.devotel.io/api/v1/ai/kb/documents", headers=headers)
print(r.json())

package main

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

func main() {
	req, _ := http.NewRequest("GET", "https://api.orbit.devotel.io/api/v1/ai/kb/documents", nil)
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))

	http.DefaultClient.Do(req)
}

Ruby

require 'net/http'
require 'json'

uri = URI('https://api.orbit.devotel.io/api/v1/ai/kb/documents')
req = Net::HTTP::Get.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']


res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.body

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/ai/kb/documents');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),

]);

echo curl_exec($ch);

{
  "data": {
    "items": [
      {
        "id": "memory_7b2d4f6a",
        "tenantId": "tnt_9c1e3a5b",
        "contactId": "ctt_4f2a9c1e",
        "agentId": "agt_7e3b9c1f",
        "memoryType": "fact",
        "content": "Prefers SMS over calls; contract renews 2026-10-01.",
        "importance": 0.9,
        "createdAt": "2026-08-01T12:00:00.000Z",
        "expiresAt": "2026-10-30T12:00:00.000Z"
      }
    ],
    "memory_enabled": true,
    "agent_id": "agt_7e3b9c1f",
    "contact_id": "ctt_4f2a9c1e",
    "facts_only": true
  },
  "meta": {
    "request_id": "req_mem_read",
    "timestamp": "2026-08-01T12:00:00.000Z"
  }
}

Get a knowledge-base document

GET /api/v1/ai/kb/documents/{id}

Fetch a single knowledge-base document by id, including its ingest status, chunk count, token total, byte size, and any last-error message so the UI can show failure context without another round-trip.

string

required

The knowledge-base document id (UUID).

string (enum: true|false)

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/ai/kb/documents/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3" \
  -H "X-API-Key: dv_live_sk_your_key_here" 

Node.js

import { Orbit } from '@devotel-orbit/node'

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/ai/kb/documents/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3', {
  method: 'GET',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
  },
})
console.log(await res.json())

Python

import os, requests

headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
r = requests.get("https://api.orbit.devotel.io/api/v1/ai/kb/documents/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3", headers=headers)
print(r.json())

package main

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

func main() {
	req, _ := http.NewRequest("GET", "https://api.orbit.devotel.io/api/v1/ai/kb/documents/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3", nil)
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))

	http.DefaultClient.Do(req)
}

Ruby

require 'net/http'
require 'json'

uri = URI('https://api.orbit.devotel.io/api/v1/ai/kb/documents/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3')
req = Net::HTTP::Get.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']


res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.body

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/ai/kb/documents/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),

]);

echo curl_exec($ch);

{
  "data": {
    "items": [
      {
        "id": "memory_7b2d4f6a",
        "tenantId": "tnt_9c1e3a5b",
        "contactId": "ctt_4f2a9c1e",
        "agentId": "agt_7e3b9c1f",
        "memoryType": "fact",
        "content": "Prefers SMS over calls; contract renews 2026-10-01.",
        "importance": 0.9,
        "createdAt": "2026-08-01T12:00:00.000Z",
        "expiresAt": "2026-10-30T12:00:00.000Z"
      }
    ],
    "memory_enabled": true,
    "agent_id": "agt_7e3b9c1f",
    "contact_id": "ctt_4f2a9c1e",
    "facts_only": true
  },
  "meta": {
    "request_id": "req_mem_read",
    "timestamp": "2026-08-01T12:00:00.000Z"
  }
}

Scan the knowledge base for stale documents

GET /api/v1/ai/kb/staleness

Scan the workspace knowledge base for documents that are out of date — never verified, verified long ago, or failed to ingest — and return a worst-first report the dashboard polls. The header aggregates (stale_count, total_documents, by_reason) are tallied over the full scan; limit pages only the returned per-document verdict rows.

integer

Page size for the returned per-document verdict rows (1-1000). Defaults to 25. The header aggregates (stale_count, total_documents, by_reason) are always tallied over the full scan.

string (enum: true|false)

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/ai/kb/staleness" \
  -H "X-API-Key: dv_live_sk_your_key_here" 

Node.js

import { Orbit } from '@devotel-orbit/node'

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/ai/kb/staleness', {
  method: 'GET',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
  },
})
console.log(await res.json())

Python

import os, requests

headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
r = requests.get("https://api.orbit.devotel.io/api/v1/ai/kb/staleness", headers=headers)
print(r.json())

package main

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

func main() {
	req, _ := http.NewRequest("GET", "https://api.orbit.devotel.io/api/v1/ai/kb/staleness", nil)
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))

	http.DefaultClient.Do(req)
}

Ruby

require 'net/http'
require 'json'

uri = URI('https://api.orbit.devotel.io/api/v1/ai/kb/staleness')
req = Net::HTTP::Get.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']


res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.body

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/ai/kb/staleness');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),

]);

echo curl_exec($ch);

{
  "data": {
    "items": [
      {
        "id": "memory_7b2d4f6a",
        "tenantId": "tnt_9c1e3a5b",
        "contactId": "ctt_4f2a9c1e",
        "agentId": "agt_7e3b9c1f",
        "memoryType": "fact",
        "content": "Prefers SMS over calls; contract renews 2026-10-01.",
        "importance": 0.9,
        "createdAt": "2026-08-01T12:00:00.000Z",
        "expiresAt": "2026-10-30T12:00:00.000Z"
      }
    ],
    "memory_enabled": true,
    "agent_id": "agt_7e3b9c1f",
    "contact_id": "ctt_4f2a9c1e",
    "facts_only": true
  },
  "meta": {
    "request_id": "req_mem_read",
    "timestamp": "2026-08-01T12:00:00.000Z"
  }
}

Analyze text (sentiment / intent / language / topics)

POST /api/v1/ai/analyze

Run the platform LLM over a block of text to extract its sentiment, intent, detected language, and key topics in a single call. Use it to triage an inbound message or enrich a contact record before routing. Like every /ai endpoint it counts against the AI rate limit and deducts credits per call.

string

Stripe-style idempotency token. Pass a stable, client-generated value (1-255 chars) to dedupe retries on transient timeouts. The same key+credential+path replays the original response for 24h on 2xx (5min on 4xx, 30s on 5xx). Returns 409 if a concurrent request with the same key is already in flight; replayed responses include the Idempotency-Replay: true response header.

string (enum: true|false)

string

required

Text to analyze (1-10,000 chars).

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/ai/analyze" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "text": "string"
}'

Node.js

import { Orbit } from '@devotel-orbit/node'

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/ai/analyze', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "text": "string"
}),
})
console.log(await res.json())

Python

import os, requests

headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
headers["Content-Type"] = "application/json"
r = requests.post("https://api.orbit.devotel.io/api/v1/ai/analyze", headers=headers, json={
  "text": "string"
})
print(r.json())

package main

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

func main() {
	req, _ := http.NewRequest("POST", "https://api.orbit.devotel.io/api/v1/ai/analyze", bytes.NewBuffer([]byte(`{
  "text": "string"
}`)))
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	req.Header.Set("Content-Type", "application/json")
	http.DefaultClient.Do(req)
}

Ruby

require 'net/http'
require 'json'

uri = URI('https://api.orbit.devotel.io/api/v1/ai/analyze')
req = Net::HTTP::Post.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']
req['Content-Type'] = 'application/json'
req.body = {
  "text": "string"
}.to_json
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.body

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/ai/analyze');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),
  'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, <<<JSON
{
  "text": "string"
}
JSON);
echo curl_exec($ch);

{
  "data": {
    "items": [
      {
        "id": "memory_7b2d4f6a",
        "tenantId": "tnt_9c1e3a5b",
        "contactId": "ctt_4f2a9c1e",
        "agentId": "agt_7e3b9c1f",
        "memoryType": "fact",
        "content": "Prefers SMS over calls; contract renews 2026-10-01.",
        "importance": 0.9,
        "createdAt": "2026-08-01T12:00:00.000Z",
        "expiresAt": "2026-10-30T12:00:00.000Z"
      }
    ],
    "memory_enabled": true,
    "agent_id": "agt_7e3b9c1f",
    "contact_id": "ctt_4f2a9c1e",
    "facts_only": true
  },
  "meta": {
    "request_id": "req_mem_read",
    "timestamp": "2026-08-01T12:00:00.000Z"
  }
}

{
  "error": {},
  "meta": {
    "request_id": "req_sample",
    "timestamp": "1970-01-01T00:00:00.000Z"
  }
}

Analyze a stored message by ID and persist the analysis

POST /api/v1/ai/analyze-message/{id}

Analyze a stored message by its ID — sentiment, intent, language, and topics — and persist the result on the message so downstream automations and reporting can read it. Use it to enrich messages already in the inbox. Like every /ai endpoint it counts against the AI rate limit and deducts credits per call.

string

required

The stored message id to analyze.

string

string (enum: true|false)

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/ai/analyze-message/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{}'

Node.js

import { Orbit } from '@devotel-orbit/node'

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/ai/analyze-message/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
})
console.log(await res.json())

Python

import os, requests

headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
headers["Content-Type"] = "application/json"
r = requests.post("https://api.orbit.devotel.io/api/v1/ai/analyze-message/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3", headers=headers, json={})
print(r.json())

package main

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

func main() {
	req, _ := http.NewRequest("POST", "https://api.orbit.devotel.io/api/v1/ai/analyze-message/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3", bytes.NewBuffer([]byte(`{}`)))
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	req.Header.Set("Content-Type", "application/json")
	http.DefaultClient.Do(req)
}

Ruby

require 'net/http'
require 'json'

uri = URI('https://api.orbit.devotel.io/api/v1/ai/analyze-message/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3')
req = Net::HTTP::Post.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']
req['Content-Type'] = 'application/json'
req.body = {}.to_json
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.body

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/ai/analyze-message/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),
  'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, <<<JSON
{}
JSON);
echo curl_exec($ch);

{
  "data": {
    "items": [
      {
        "id": "memory_7b2d4f6a",
        "tenantId": "tnt_9c1e3a5b",
        "contactId": "ctt_4f2a9c1e",
        "agentId": "agt_7e3b9c1f",
        "memoryType": "fact",
        "content": "Prefers SMS over calls; contract renews 2026-10-01.",
        "importance": 0.9,
        "createdAt": "2026-08-01T12:00:00.000Z",
        "expiresAt": "2026-10-30T12:00:00.000Z"
      }
    ],
    "memory_enabled": true,
    "agent_id": "agt_7e3b9c1f",
    "contact_id": "ctt_4f2a9c1e",
    "facts_only": true
  },
  "meta": {
    "request_id": "req_mem_read",
    "timestamp": "2026-08-01T12:00:00.000Z"
  }
}

{
  "error": {},
  "meta": {
    "request_id": "req_sample",
    "timestamp": "1970-01-01T00:00:00.000Z"
  }
}

OpenAI-compatible chat completion (general inference)

POST /api/v1/ai/chat/completions

Run an OpenAI-compatible chat completion for general-purpose inference over a list of conversation turns. Use it as a drop-in building block for custom AI features; supports temperature, max_tokens, and JSON response formatting. Like every /ai endpoint it counts against the AI rate limit and deducts credits per call.

string

string (enum: true|false)

string

Optional model id. OpenAI ids are remapped to the platform fast tier.

object[]

required

Conversation turns (1-50).

number

—

integer

—

object

—

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/ai/chat/completions" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "messages": []
}'

Node.js

import { Orbit } from '@devotel-orbit/node'

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/ai/chat/completions', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "messages": []
}),
})
console.log(await res.json())

Python

import os, requests

headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
headers["Content-Type"] = "application/json"
r = requests.post("https://api.orbit.devotel.io/api/v1/ai/chat/completions", headers=headers, json={
  "messages": []
})
print(r.json())

package main

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

func main() {
	req, _ := http.NewRequest("POST", "https://api.orbit.devotel.io/api/v1/ai/chat/completions", bytes.NewBuffer([]byte(`{
  "messages": []
}`)))
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	req.Header.Set("Content-Type", "application/json")
	http.DefaultClient.Do(req)
}

Ruby

require 'net/http'
require 'json'

uri = URI('https://api.orbit.devotel.io/api/v1/ai/chat/completions')
req = Net::HTTP::Post.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']
req['Content-Type'] = 'application/json'
req.body = {
  "messages": []
}.to_json
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.body

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/ai/chat/completions');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),
  'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, <<<JSON
{
  "messages": []
}
JSON);
echo curl_exec($ch);

{
  "data": {
    "items": [
      {
        "id": "memory_7b2d4f6a",
        "tenantId": "tnt_9c1e3a5b",
        "contactId": "ctt_4f2a9c1e",
        "agentId": "agt_7e3b9c1f",
        "memoryType": "fact",
        "content": "Prefers SMS over calls; contract renews 2026-10-01.",
        "importance": 0.9,
        "createdAt": "2026-08-01T12:00:00.000Z",
        "expiresAt": "2026-10-30T12:00:00.000Z"
      }
    ],
    "memory_enabled": true,
    "agent_id": "agt_7e3b9c1f",
    "contact_id": "ctt_4f2a9c1e",
    "facts_only": true
  },
  "meta": {
    "request_id": "req_mem_read",
    "timestamp": "2026-08-01T12:00:00.000Z"
  }
}

{
  "error": {},
  "meta": {
    "request_id": "req_sample",
    "timestamp": "1970-01-01T00:00:00.000Z"
  }
}

Classify the customer’s intent from a conversation

POST /api/v1/ai/classify-intent

Classify the customer’s primary intent from a conversation — for example sales, support, billing, or cancellation — so you can route or automate on it. Use it to drive inbox triage or workflow branching. Like every /ai endpoint it counts against the AI rate limit and deducts credits per call.

string

string (enum: true|false)

string

required

Conversation ID to analyze.

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/ai/classify-intent" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "conversation_id": "string"
}'

Node.js

import { Orbit } from '@devotel-orbit/node'

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/ai/classify-intent', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "conversation_id": "string"
}),
})
console.log(await res.json())

Python

import os, requests

headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
headers["Content-Type"] = "application/json"
r = requests.post("https://api.orbit.devotel.io/api/v1/ai/classify-intent", headers=headers, json={
  "conversation_id": "string"
})
print(r.json())

package main

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

func main() {
	req, _ := http.NewRequest("POST", "https://api.orbit.devotel.io/api/v1/ai/classify-intent", bytes.NewBuffer([]byte(`{
  "conversation_id": "string"
}`)))
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	req.Header.Set("Content-Type", "application/json")
	http.DefaultClient.Do(req)
}

Ruby

require 'net/http'
require 'json'

uri = URI('https://api.orbit.devotel.io/api/v1/ai/classify-intent')
req = Net::HTTP::Post.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']
req['Content-Type'] = 'application/json'
req.body = {
  "conversation_id": "string"
}.to_json
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.body

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/ai/classify-intent');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),
  'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, <<<JSON
{
  "conversation_id": "string"
}
JSON);
echo curl_exec($ch);

{
  "data": {
    "items": [
      {
        "id": "memory_7b2d4f6a",
        "tenantId": "tnt_9c1e3a5b",
        "contactId": "ctt_4f2a9c1e",
        "agentId": "agt_7e3b9c1f",
        "memoryType": "fact",
        "content": "Prefers SMS over calls; contract renews 2026-10-01.",
        "importance": 0.9,
        "createdAt": "2026-08-01T12:00:00.000Z",
        "expiresAt": "2026-10-30T12:00:00.000Z"
      }
    ],
    "memory_enabled": true,
    "agent_id": "agt_7e3b9c1f",
    "contact_id": "ctt_4f2a9c1e",
    "facts_only": true
  },
  "meta": {
    "request_id": "req_mem_read",
    "timestamp": "2026-08-01T12:00:00.000Z"
  }
}

{
  "error": {},
  "meta": {
    "request_id": "req_sample",
    "timestamp": "1970-01-01T00:00:00.000Z"
  }
}

Draft a full campaign blueprint from a plain-English goal

POST /api/v1/ai/compose-campaign

Draft a full multi-channel campaign blueprint — audience, channels, tone, and per-channel copy — from a plain-English goal. Use it to bootstrap a campaign in the create wizard. Like every /ai endpoint it counts against the AI rate limit and deducts credits per call.

string

string (enum: true|false)

string

required

Plain-English campaign goal (5-2,000 chars).

—

string

—

string (enum: sms|whatsapp|email|voice)[]

—

string (enum: professional|casual|urgent|friendly|empathetic)

—

string

—

string

—

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/ai/compose-campaign" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "goal": "string"
}'

Node.js

import { Orbit } from '@devotel-orbit/node'

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/ai/compose-campaign', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "goal": "string"
}),
})
console.log(await res.json())

Python

import os, requests

headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
headers["Content-Type"] = "application/json"
r = requests.post("https://api.orbit.devotel.io/api/v1/ai/compose-campaign", headers=headers, json={
  "goal": "string"
})
print(r.json())

package main

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

func main() {
	req, _ := http.NewRequest("POST", "https://api.orbit.devotel.io/api/v1/ai/compose-campaign", bytes.NewBuffer([]byte(`{
  "goal": "string"
}`)))
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	req.Header.Set("Content-Type", "application/json")
	http.DefaultClient.Do(req)
}

Ruby

require 'net/http'
require 'json'

uri = URI('https://api.orbit.devotel.io/api/v1/ai/compose-campaign')
req = Net::HTTP::Post.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']
req['Content-Type'] = 'application/json'
req.body = {
  "goal": "string"
}.to_json
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.body

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/ai/compose-campaign');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),
  'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, <<<JSON
{
  "goal": "string"
}
JSON);
echo curl_exec($ch);

{
  "data": {
    "items": [
      {
        "id": "memory_7b2d4f6a",
        "tenantId": "tnt_9c1e3a5b",
        "contactId": "ctt_4f2a9c1e",
        "agentId": "agt_7e3b9c1f",
        "memoryType": "fact",
        "content": "Prefers SMS over calls; contract renews 2026-10-01.",
        "importance": 0.9,
        "createdAt": "2026-08-01T12:00:00.000Z",
        "expiresAt": "2026-10-30T12:00:00.000Z"
      }
    ],
    "memory_enabled": true,
    "agent_id": "agt_7e3b9c1f",
    "contact_id": "ctt_4f2a9c1e",
    "facts_only": true
  },
  "meta": {
    "request_id": "req_mem_read",
    "timestamp": "2026-08-01T12:00:00.000Z"
  }
}

{
  "error": {},
  "meta": {
    "request_id": "req_sample",
    "timestamp": "1970-01-01T00:00:00.000Z"
  }
}

Generate AI-powered dashboard insights from stats

POST /api/v1/ai/dashboard-insights

Turn a blob of dashboard stats into a short set of AI-written insights and recommended next actions. Use it to surface a plain-English summary of account performance on the dashboard. Like every /ai endpoint it counts against the AI rate limit and deducts credits per call.

string

string (enum: true|false)

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/ai/dashboard-insights" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{}'

Node.js

import { Orbit } from '@devotel-orbit/node'

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/ai/dashboard-insights', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
})
console.log(await res.json())

Python

import os, requests

headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
headers["Content-Type"] = "application/json"
r = requests.post("https://api.orbit.devotel.io/api/v1/ai/dashboard-insights", headers=headers, json={})
print(r.json())

package main

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

func main() {
	req, _ := http.NewRequest("POST", "https://api.orbit.devotel.io/api/v1/ai/dashboard-insights", bytes.NewBuffer([]byte(`{}`)))
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	req.Header.Set("Content-Type", "application/json")
	http.DefaultClient.Do(req)
}

Ruby

require 'net/http'
require 'json'

uri = URI('https://api.orbit.devotel.io/api/v1/ai/dashboard-insights')
req = Net::HTTP::Post.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']
req['Content-Type'] = 'application/json'
req.body = {}.to_json
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.body

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/ai/dashboard-insights');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),
  'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, <<<JSON
{}
JSON);
echo curl_exec($ch);

{
  "data": {
    "items": [
      {
        "id": "memory_7b2d4f6a",
        "tenantId": "tnt_9c1e3a5b",
        "contactId": "ctt_4f2a9c1e",
        "agentId": "agt_7e3b9c1f",
        "memoryType": "fact",
        "content": "Prefers SMS over calls; contract renews 2026-10-01.",
        "importance": 0.9,
        "createdAt": "2026-08-01T12:00:00.000Z",
        "expiresAt": "2026-10-30T12:00:00.000Z"
      }
    ],
    "memory_enabled": true,
    "agent_id": "agt_7e3b9c1f",
    "contact_id": "ctt_4f2a9c1e",
    "facts_only": true
  },
  "meta": {
    "request_id": "req_mem_read",
    "timestamp": "2026-08-01T12:00:00.000Z"
  }
}

{
  "error": {},
  "meta": {
    "request_id": "req_sample",
    "timestamp": "1970-01-01T00:00:00.000Z"
  }
}

Generate embedding vectors for one or more input strings

POST /api/v1/ai/embeddings

Generate embedding vectors for a single string or a batch of up to 96 strings, for semantic search, clustering, or retrieval-augmented generation. The OpenAI-style request shape lets existing SDKs drop in unchanged. Like every /ai endpoint it counts against the AI rate limit and deducts credits per call.

string

string (enum: true|false)

any

required

Text (or array of texts) to embed.

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/ai/embeddings" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "input": "string"
}'

Node.js

import { Orbit } from '@devotel-orbit/node'

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/ai/embeddings', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "input": "string"
}),
})
console.log(await res.json())

Python

import os, requests

headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
headers["Content-Type"] = "application/json"
r = requests.post("https://api.orbit.devotel.io/api/v1/ai/embeddings", headers=headers, json={
  "input": "string"
})
print(r.json())

package main

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

func main() {
	req, _ := http.NewRequest("POST", "https://api.orbit.devotel.io/api/v1/ai/embeddings", bytes.NewBuffer([]byte(`{
  "input": "string"
}`)))
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	req.Header.Set("Content-Type", "application/json")
	http.DefaultClient.Do(req)
}

Ruby

require 'net/http'
require 'json'

uri = URI('https://api.orbit.devotel.io/api/v1/ai/embeddings')
req = Net::HTTP::Post.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']
req['Content-Type'] = 'application/json'
req.body = {
  "input": "string"
}.to_json
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.body

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/ai/embeddings');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),
  'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, <<<JSON
{
  "input": "string"
}
JSON);
echo curl_exec($ch);

{
  "data": {
    "items": [
      {
        "id": "memory_7b2d4f6a",
        "tenantId": "tnt_9c1e3a5b",
        "contactId": "ctt_4f2a9c1e",
        "agentId": "agt_7e3b9c1f",
        "memoryType": "fact",
        "content": "Prefers SMS over calls; contract renews 2026-10-01.",
        "importance": 0.9,
        "createdAt": "2026-08-01T12:00:00.000Z",
        "expiresAt": "2026-10-30T12:00:00.000Z"
      }
    ],
    "memory_enabled": true,
    "agent_id": "agt_7e3b9c1f",
    "contact_id": "ctt_4f2a9c1e",
    "facts_only": true
  },
  "meta": {
    "request_id": "req_mem_read",
    "timestamp": "2026-08-01T12:00:00.000Z"
  }
}

{
  "error": {},
  "meta": {
    "request_id": "req_sample",
    "timestamp": "1970-01-01T00:00:00.000Z"
  }
}

Generate channel-appropriate message content from a prompt

POST /api/v1/ai/generate-content

Generate channel-appropriate message copy from a plain-English prompt, honoring an optional tone and target channel. Use it to draft SMS, WhatsApp, or email content in the campaign composer. Like every /ai endpoint it counts against the AI rate limit and deducts credits per call.

string

string (enum: true|false)

string

required

Plain-English prompt (1-2,000 chars).

string (enum: professional|casual|urgent|friendly)

—

string

—

string

—

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/ai/generate-content" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "prompt": "string"
}'

Node.js

import { Orbit } from '@devotel-orbit/node'

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/ai/generate-content', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "prompt": "string"
}),
})
console.log(await res.json())

Python

import os, requests

headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
headers["Content-Type"] = "application/json"
r = requests.post("https://api.orbit.devotel.io/api/v1/ai/generate-content", headers=headers, json={
  "prompt": "string"
})
print(r.json())

package main

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

func main() {
	req, _ := http.NewRequest("POST", "https://api.orbit.devotel.io/api/v1/ai/generate-content", bytes.NewBuffer([]byte(`{
  "prompt": "string"
}`)))
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	req.Header.Set("Content-Type", "application/json")
	http.DefaultClient.Do(req)
}

Ruby

require 'net/http'
require 'json'

uri = URI('https://api.orbit.devotel.io/api/v1/ai/generate-content')
req = Net::HTTP::Post.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']
req['Content-Type'] = 'application/json'
req.body = {
  "prompt": "string"
}.to_json
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.body

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/ai/generate-content');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),
  'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, <<<JSON
{
  "prompt": "string"
}
JSON);
echo curl_exec($ch);

{
  "data": {
    "items": [
      {
        "id": "memory_7b2d4f6a",
        "tenantId": "tnt_9c1e3a5b",
        "contactId": "ctt_4f2a9c1e",
        "agentId": "agt_7e3b9c1f",
        "memoryType": "fact",
        "content": "Prefers SMS over calls; contract renews 2026-10-01.",
        "importance": 0.9,
        "createdAt": "2026-08-01T12:00:00.000Z",
        "expiresAt": "2026-10-30T12:00:00.000Z"
      }
    ],
    "memory_enabled": true,
    "agent_id": "agt_7e3b9c1f",
    "contact_id": "ctt_4f2a9c1e",
    "facts_only": true
  },
  "meta": {
    "request_id": "req_mem_read",
    "timestamp": "2026-08-01T12:00:00.000Z"
  }
}

{
  "error": {},
  "meta": {
    "request_id": "req_sample",
    "timestamp": "1970-01-01T00:00:00.000Z"
  }
}

Improve, shorten, lengthen, or rephrase existing text

POST /api/v1/ai/improve-text

Rewrite existing text to improve it, make it shorter or longer, change its tone, fix grammar, or rephrase it. Use it to polish a draft reply or campaign copy before sending on any channel. Like every /ai endpoint it counts against the AI rate limit and deducts credits per call.

string

string (enum: true|false)

string

required

Text to improve (1-10,000 chars).

required

—

string

—

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/ai/improve-text" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "text": "string",
  "action": "improve"
}'

Node.js

import { Orbit } from '@devotel-orbit/node'

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/ai/improve-text', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "text": "string",
  "action": "improve"
}),
})
console.log(await res.json())

Python

import os, requests

headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
headers["Content-Type"] = "application/json"
r = requests.post("https://api.orbit.devotel.io/api/v1/ai/improve-text", headers=headers, json={
  "text": "string",
  "action": "improve"
})
print(r.json())

package main

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

func main() {
	req, _ := http.NewRequest("POST", "https://api.orbit.devotel.io/api/v1/ai/improve-text", bytes.NewBuffer([]byte(`{
  "text": "string",
  "action": "improve"
}`)))
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	req.Header.Set("Content-Type", "application/json")
	http.DefaultClient.Do(req)
}

Ruby

require 'net/http'
require 'json'

uri = URI('https://api.orbit.devotel.io/api/v1/ai/improve-text')
req = Net::HTTP::Post.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']
req['Content-Type'] = 'application/json'
req.body = {
  "text": "string",
  "action": "improve"
}.to_json
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.body

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/ai/improve-text');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),
  'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, <<<JSON
{
  "text": "string",
  "action": "improve"
}
JSON);
echo curl_exec($ch);

{
  "data": {
    "items": [
      {
        "id": "memory_7b2d4f6a",
        "tenantId": "tnt_9c1e3a5b",
        "contactId": "ctt_4f2a9c1e",
        "agentId": "agt_7e3b9c1f",
        "memoryType": "fact",
        "content": "Prefers SMS over calls; contract renews 2026-10-01.",
        "importance": 0.9,
        "createdAt": "2026-08-01T12:00:00.000Z",
        "expiresAt": "2026-10-30T12:00:00.000Z"
      }
    ],
    "memory_enabled": true,
    "agent_id": "agt_7e3b9c1f",
    "contact_id": "ctt_4f2a9c1e",
    "facts_only": true
  },
  "meta": {
    "request_id": "req_mem_read",
    "timestamp": "2026-08-01T12:00:00.000Z"
  }
}

{
  "error": {},
  "meta": {
    "request_id": "req_sample",
    "timestamp": "1970-01-01T00:00:00.000Z"
  }
}

Answer a question from the knowledge base

POST /api/v1/ai/kb/answers

Customer-facing grounded Answers API: take an end-user question, run hybrid knowledge-base retrieval plus a single grounded-answer LLM call, and return the answer with citations and a confidence score. Enforces per-document audience access control via audiences, and meters one billable resolution per answered query above the confidence floor. Each call is one LLM round-trip, so it counts against the AI spend cap. For raw ranked chunks without an answer, use POST /ai/kb/search instead.

string

string (enum: true|false)

string

required

The end-user question to answer (1-2000 chars).

string[]

Optional knowledge-base allowlist. When present, retrieval is scoped to these KBs only; when omitted, the whole workspace knowledge base is searched. Max 20 ids.

integer

Max chunks retrieved to ground the answer (1-10). Defaults to 8.

number

Optional retrieval similarity floor (0-1) passed through to the vector search.

number

Confidence floor (0-1) above which an answer is charged as a billable resolution. Defaults to the platform bar (0.75); a lower-confidence answer is still returned but not billed.

string

Optional language tag (e.g. en, pt-BR) — the answer is written in this language.

string[]

The audience tokens (roles / segments) the end-user belongs to, used to enforce per-document access control. Omit / empty = anonymous requester → only unrestricted documents are eligible. Max 50.

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/ai/kb/answers" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "question": "string"
}'

Node.js

import { Orbit } from '@devotel-orbit/node'

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/ai/kb/answers', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "question": "string"
}),
})
console.log(await res.json())

Python

import os, requests

headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
headers["Content-Type"] = "application/json"
r = requests.post("https://api.orbit.devotel.io/api/v1/ai/kb/answers", headers=headers, json={
  "question": "string"
})
print(r.json())

package main

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

func main() {
	req, _ := http.NewRequest("POST", "https://api.orbit.devotel.io/api/v1/ai/kb/answers", bytes.NewBuffer([]byte(`{
  "question": "string"
}`)))
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	req.Header.Set("Content-Type", "application/json")
	http.DefaultClient.Do(req)
}

Ruby

require 'net/http'
require 'json'

uri = URI('https://api.orbit.devotel.io/api/v1/ai/kb/answers')
req = Net::HTTP::Post.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']
req['Content-Type'] = 'application/json'
req.body = {
  "question": "string"
}.to_json
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.body

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/ai/kb/answers');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),
  'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, <<<JSON
{
  "question": "string"
}
JSON);
echo curl_exec($ch);

{
  "data": {
    "items": [
      {
        "id": "memory_7b2d4f6a",
        "tenantId": "tnt_9c1e3a5b",
        "contactId": "ctt_4f2a9c1e",
        "agentId": "agt_7e3b9c1f",
        "memoryType": "fact",
        "content": "Prefers SMS over calls; contract renews 2026-10-01.",
        "importance": 0.9,
        "createdAt": "2026-08-01T12:00:00.000Z",
        "expiresAt": "2026-10-30T12:00:00.000Z"
      }
    ],
    "memory_enabled": true,
    "agent_id": "agt_7e3b9c1f",
    "contact_id": "ctt_4f2a9c1e",
    "facts_only": true
  },
  "meta": {
    "request_id": "req_mem_read",
    "timestamp": "2026-08-01T12:00:00.000Z"
  }
}

Add a knowledge-base document

POST /api/v1/ai/kb/documents

Add a document to the knowledge base from a URL (optionally crawling same-domain links), pasted markdown/plain text, or a file upload (PDF, DOCX, TXT, CSV, Markdown via multipart/form-data). The document is stored with status processing and returned immediately; ingestion — text extraction, chunking, and embedding — runs on the worker, so poll the list or detail endpoint until status is ready.

string

string (enum: true|false)

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/ai/kb/documents" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{}'

Node.js

import { Orbit } from '@devotel-orbit/node'

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/ai/kb/documents', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
})
console.log(await res.json())

{
  "data": {
    "item": {
      "id": "memory_7b2d4f6a",
      "tenantId": "tnt_9c1e3a5b",
      "contactId": "ctt_4f2a9c1e",
      "agentId": "agt_7e3b9c1f",
      "memoryType": "fact",
      "content": "Prefers SMS over calls; contract renews 2026-10-01.",
      "importance": 0.9,
      "createdAt": "2026-08-01T12:00:00.000Z",
      "expiresAt": "2026-10-30T12:00:00.000Z"
    }
  },
  "meta": {
    "request_id": "req_mem_teach",
    "timestamp": "2026-08-01T12:00:00.000Z"
  }
}

Reindex a knowledge-base document

POST /api/v1/ai/kb/documents/{id}/reindex

Re-run ingestion on a stored document — re-fetching the original URL or re-embedding the stored content — and return the ingest result synchronously so the operator can confirm it worked. The scheduler also picks up processing rows as a safety net.

string

required

The knowledge-base document id (UUID).

string

string (enum: true|false)

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/ai/kb/documents/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3/reindex" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{}'

Node.js

import { Orbit } from '@devotel-orbit/node'

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/ai/kb/documents/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3/reindex', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
})
console.log(await res.json())

{
  "data": {
    "items": [
      {
        "id": "memory_7b2d4f6a",
        "tenantId": "tnt_9c1e3a5b",
        "contactId": "ctt_4f2a9c1e",
        "agentId": "agt_7e3b9c1f",
        "memoryType": "fact",
        "content": "Prefers SMS over calls; contract renews 2026-10-01.",
        "importance": 0.9,
        "createdAt": "2026-08-01T12:00:00.000Z",
        "expiresAt": "2026-10-30T12:00:00.000Z"
      }
    ],
    "memory_enabled": true,
    "agent_id": "agt_7e3b9c1f",
    "contact_id": "ctt_4f2a9c1e",
    "facts_only": true
  },
  "meta": {
    "request_id": "req_mem_read",
    "timestamp": "2026-08-01T12:00:00.000Z"
  }
}

Mark a knowledge-base document as verified

POST /api/v1/ai/kb/documents/{id}/verify

Stamp a document as “still accurate”, setting its last_verified_at timestamp to now. Used by the staleness workflow so freshly-reviewed documents drop off the stale list. Idempotent — re-verifying just refreshes the timestamp.

string

required

The knowledge-base document id (UUID).

string

string (enum: true|false)

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/ai/kb/documents/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3/verify" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{}'

Node.js

import { Orbit } from '@devotel-orbit/node'

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/ai/kb/documents/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3/verify', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
})
console.log(await res.json())

{
  "data": {
    "items": [
      {
        "id": "memory_7b2d4f6a",
        "tenantId": "tnt_9c1e3a5b",
        "contactId": "ctt_4f2a9c1e",
        "agentId": "agt_7e3b9c1f",
        "memoryType": "fact",
        "content": "Prefers SMS over calls; contract renews 2026-10-01.",
        "importance": 0.9,
        "createdAt": "2026-08-01T12:00:00.000Z",
        "expiresAt": "2026-10-30T12:00:00.000Z"
      }
    ],
    "memory_enabled": true,
    "agent_id": "agt_7e3b9c1f",
    "contact_id": "ctt_4f2a9c1e",
    "facts_only": true
  },
  "meta": {
    "request_id": "req_mem_read",
    "timestamp": "2026-08-01T12:00:00.000Z"
  }
}

Import a help center into the knowledge base

POST /api/v1/ai/kb/import/help-center

Bulk-import an existing help center: enumerate a provider’s published articles (Zendesk Guide’s public Help Center API — no OAuth) and queue one URL-sourced document per article through the standard ingest pipeline. subdomain is a strict DNS label, so the only host the connector can fetch is <subdomain>.zendesk.com. Returns 201 with the queued document rows. If the help center reports no published articles nothing is created, so the call succeeds with 200 instead — same envelope, plus queued: 0, an empty documents array, and a message naming what to check. Treat BOTH 200 and 201 as success.

string

string (enum: true|false)

string (enum: zendesk_guide)

Help-center provider to enumerate. Only Zendesk Guide is importable without OAuth today.

string

required

The lowercase DNS label in <subdomain>.zendesk.com (letters, digits, hyphens; max 63 chars). This is the only host the connector can ever fetch.

string

Help-center locale segment, e.g. en or en-us. Defaults to en-us.

string

Optional prefix prepended to each imported document’s name (max 80 chars).

integer

Upper bound on the number of articles queued in one import (1-1000). Defaults to 250.

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/ai/kb/import/help-center" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "subdomain": "string"
}'

Node.js

import { Orbit } from '@devotel-orbit/node'

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/ai/kb/import/help-center', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "subdomain": "string"
}),
})
console.log(await res.json())

{
  "data": {
    "items": [
      {
        "id": "memory_7b2d4f6a",
        "tenantId": "tnt_9c1e3a5b",
        "contactId": "ctt_4f2a9c1e",
        "agentId": "agt_7e3b9c1f",
        "memoryType": "fact",
        "content": "Prefers SMS over calls; contract renews 2026-10-01.",
        "importance": 0.9,
        "createdAt": "2026-08-01T12:00:00.000Z",
        "expiresAt": "2026-10-30T12:00:00.000Z"
      }
    ],
    "memory_enabled": true,
    "agent_id": "agt_7e3b9c1f",
    "contact_id": "ctt_4f2a9c1e",
    "facts_only": true
  },
  "meta": {
    "request_id": "req_mem_read",
    "timestamp": "2026-08-01T12:00:00.000Z"
  }
}

Search the knowledge base

POST /api/v1/ai/kb/search

Run a semantic search over the workspace knowledge base and return the most relevant chunks with their similarity scores — the operator test-panel query behind the KB dashboard. Each query embeds the search text, so it counts against the AI spend cap. For a single grounded answer with citations, use POST /ai/kb/answers instead.

string

string (enum: true|false)

string

required

The search query text (1-2000 chars).

integer

Max chunks to return (1-20). Defaults to 5.

number

Optional similarity floor (0-1) passed through to the vector search.

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/ai/kb/search" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "query": "string"
}'

Node.js

import { Orbit } from '@devotel-orbit/node'

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/ai/kb/search', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "query": "string"
}),
})
console.log(await res.json())

{
  "data": {
    "items": [
      {
        "id": "memory_7b2d4f6a",
        "tenantId": "tnt_9c1e3a5b",
        "contactId": "ctt_4f2a9c1e",
        "agentId": "agt_7e3b9c1f",
        "memoryType": "fact",
        "content": "Prefers SMS over calls; contract renews 2026-10-01.",
        "importance": 0.9,
        "createdAt": "2026-08-01T12:00:00.000Z",
        "expiresAt": "2026-10-30T12:00:00.000Z"
      }
    ],
    "memory_enabled": true,
    "agent_id": "agt_7e3b9c1f",
    "contact_id": "ctt_4f2a9c1e",
    "facts_only": true
  },
  "meta": {
    "request_id": "req_mem_read",
    "timestamp": "2026-08-01T12:00:00.000Z"
  }
}

POST /api/v1/ai/optimize-channel

Recommend the best channel and fallbacks for reaching a recipient given the message type and your goal — cheapest, fastest, highest engagement, or balanced. Use it to route a single send to the optimal channel. Like every /ai endpoint it counts against the AI rate limit and deducts credits per call.

string

string (enum: true|false)

string

required

Recipient identifier (E.164 phone or email).

string (enum: marketing|transactional|otp)

—

string (enum: cheapest|fastest|highest_engagement|balanced)

—

string[]

—

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/ai/optimize-channel" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "to": "+14155552671"
}'

Node.js

import { Orbit } from '@devotel-orbit/node'

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/ai/optimize-channel', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "to": "+14155552671"
}),
})
console.log(await res.json())

{
  "data": {
    "items": [
      {
        "id": "memory_7b2d4f6a",
        "tenantId": "tnt_9c1e3a5b",
        "contactId": "ctt_4f2a9c1e",
        "agentId": "agt_7e3b9c1f",
        "memoryType": "fact",
        "content": "Prefers SMS over calls; contract renews 2026-10-01.",
        "importance": 0.9,
        "createdAt": "2026-08-01T12:00:00.000Z",
        "expiresAt": "2026-10-30T12:00:00.000Z"
      }
    ],
    "memory_enabled": true,
    "agent_id": "agt_7e3b9c1f",
    "contact_id": "ctt_4f2a9c1e",
    "facts_only": true
  },
  "meta": {
    "request_id": "req_mem_read",
    "timestamp": "2026-08-01T12:00:00.000Z"
  }
}

{
  "error": {},
  "meta": {
    "request_id": "req_sample",
    "timestamp": "1970-01-01T00:00:00.000Z"
  }
}

Generate AI-suggested replies for a conversation

POST /api/v1/ai/suggest-reply

Generate AI-suggested agent replies for an open conversation, grounded in the thread history and your knowledge base. Use it to power a Copilot reply picker in the inbox. Like every /ai endpoint it counts against the AI rate limit and deducts credits per call.

string

string (enum: true|false)

string

required

Conversation ID to analyze.

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/ai/suggest-reply" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "conversation_id": "string"
}'

Node.js

import { Orbit } from '@devotel-orbit/node'

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/ai/suggest-reply', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "conversation_id": "string"
}),
})
console.log(await res.json())

{
  "data": {
    "items": [
      {
        "id": "memory_7b2d4f6a",
        "tenantId": "tnt_9c1e3a5b",
        "contactId": "ctt_4f2a9c1e",
        "agentId": "agt_7e3b9c1f",
        "memoryType": "fact",
        "content": "Prefers SMS over calls; contract renews 2026-10-01.",
        "importance": 0.9,
        "createdAt": "2026-08-01T12:00:00.000Z",
        "expiresAt": "2026-10-30T12:00:00.000Z"
      }
    ],
    "memory_enabled": true,
    "agent_id": "agt_7e3b9c1f",
    "contact_id": "ctt_4f2a9c1e",
    "facts_only": true
  },
  "meta": {
    "request_id": "req_mem_read",
    "timestamp": "2026-08-01T12:00:00.000Z"
  }
}

{
  "error": {},
  "meta": {
    "request_id": "req_sample",
    "timestamp": "1970-01-01T00:00:00.000Z"
  }
}

Summarize a conversation thread

POST /api/v1/ai/summarize-conversation

Summarize a conversation thread into a short recap of what the customer needs and what has happened so far. Use it to brief an agent on handoff or to store a wrap-up note. Like every /ai endpoint it counts against the AI rate limit and deducts credits per call.

string

string (enum: true|false)

string

required

Conversation ID to analyze.

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/ai/summarize-conversation" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "conversation_id": "string"
}'

Node.js

import { Orbit } from '@devotel-orbit/node'

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/ai/summarize-conversation', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "conversation_id": "string"
}),
})
console.log(await res.json())

{
  "data": {
    "items": [
      {
        "id": "memory_7b2d4f6a",
        "tenantId": "tnt_9c1e3a5b",
        "contactId": "ctt_4f2a9c1e",
        "agentId": "agt_7e3b9c1f",
        "memoryType": "fact",
        "content": "Prefers SMS over calls; contract renews 2026-10-01.",
        "importance": 0.9,
        "createdAt": "2026-08-01T12:00:00.000Z",
        "expiresAt": "2026-10-30T12:00:00.000Z"
      }
    ],
    "memory_enabled": true,
    "agent_id": "agt_7e3b9c1f",
    "contact_id": "ctt_4f2a9c1e",
    "facts_only": true
  },
  "meta": {
    "request_id": "req_mem_read",
    "timestamp": "2026-08-01T12:00:00.000Z"
  }
}

{
  "error": {},
  "meta": {
    "request_id": "req_sample",
    "timestamp": "1970-01-01T00:00:00.000Z"
  }
}

Translate text to a target language

POST /api/v1/ai/translate

Translate a block of text into a target language using the platform LLM, returning the translated text plus the detected source language. Use it to localize a draft reply, an inbound message, or campaign copy before sending on any channel. Set target_language to an ISO 639-1 code (es, fr, pt-BR) or a language name (Spanish). Like every /ai endpoint it counts against the AI rate limit and deducts credits per call.

string

string (enum: true|false)

string

required

Text to translate (1-10,000 chars).

string

required

Target language name or ISO 639-1 code.

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/ai/translate" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "text": "string",
  "target_language": "string"
}'

Node.js

import { Orbit } from '@devotel-orbit/node'

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/ai/translate', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "text": "string",
  "target_language": "string"
}),
})
console.log(await res.json())

{
  "data": {
    "items": [
      {
        "id": "memory_7b2d4f6a",
        "tenantId": "tnt_9c1e3a5b",
        "contactId": "ctt_4f2a9c1e",
        "agentId": "agt_7e3b9c1f",
        "memoryType": "fact",
        "content": "Prefers SMS over calls; contract renews 2026-10-01.",
        "importance": 0.9,
        "createdAt": "2026-08-01T12:00:00.000Z",
        "expiresAt": "2026-10-30T12:00:00.000Z"
      }
    ],
    "memory_enabled": true,
    "agent_id": "agt_7e3b9c1f",
    "contact_id": "ctt_4f2a9c1e",
    "facts_only": true
  },
  "meta": {
    "request_id": "req_mem_read",
    "timestamp": "2026-08-01T12:00:00.000Z"
  }
}

{
  "error": {},
  "meta": {
    "request_id": "req_sample",
    "timestamp": "1970-01-01T00:00:00.000Z"
  }
}

Delete a knowledge-base document

DELETE /api/v1/ai/kb/documents/{id}

Delete a knowledge-base document: its vector embeddings are removed first, then the document row is cascade-deleted. Idempotent — safe to retry; returns 204 No Content on success.

string

required

The knowledge-base document id (UUID).

string (enum: true|false)

cURL

curl -X DELETE "https://api.orbit.devotel.io/api/v1/ai/kb/documents/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{}'

Node.js

import { Orbit } from '@devotel-orbit/node'

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/ai/kb/documents/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3', {
  method: 'DELETE',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
})
console.log(await res.json())

Response: 204 No Content

API Reference

All Endpoints

AI API

AI API

title: “AI Knowledge Base endpoints (ingest, refresh, search)” description: “Curated note covering the embedded org-wide knowledge base in the AI API, with endpoints for document ingest, staleness scoring, and grounded search.”

Worked session/memory + budget envelopes

1. Session memory round trip

2. Token-budget precheck

3. Errors-as-decision-table

List knowledge-source connectors

Get a knowledge-source connector

List knowledge-base documents

Get a knowledge-base document

Scan the knowledge base for stale documents

Analyze text (sentiment / intent / language / topics)

Analyze a stored message by ID and persist the analysis

OpenAI-compatible chat completion (general inference)

Classify the customer’s intent from a conversation

Draft a full campaign blueprint from a plain-English goal

Generate AI-powered dashboard insights from stats

Generate embedding vectors for one or more input strings

Generate channel-appropriate message content from a prompt

Improve, shorten, lengthen, or rephrase existing text

Answer a question from the knowledge base

Add a knowledge-base document

Reindex a knowledge-base document

Mark a knowledge-base document as verified

Import a help center into the knowledge base

Search the knowledge base

Generate AI-suggested replies for a conversation

Summarize a conversation thread

Translate text to a target language

Delete a knowledge-base document

​AI API

​title: “AI Knowledge Base endpoints (ingest, refresh, search)” description: “Curated note covering the embedded org-wide knowledge base in the AI API, with endpoints for document ingest, staleness scoring, and grounded search.”

​Worked session/memory + budget envelopes

​1. Session memory round trip

​2. Token-budget precheck

​3. Errors-as-decision-table

​List knowledge-source connectors

​Get a knowledge-source connector

​List knowledge-base documents

​Get a knowledge-base document

​Scan the knowledge base for stale documents

​Analyze text (sentiment / intent / language / topics)

​Analyze a stored message by ID and persist the analysis

​OpenAI-compatible chat completion (general inference)

​Classify the customer’s intent from a conversation

​Draft a full campaign blueprint from a plain-English goal

​Generate AI-powered dashboard insights from stats

​Generate embedding vectors for one or more input strings

​Generate channel-appropriate message content from a prompt

​Improve, shorten, lengthen, or rephrase existing text

​Answer a question from the knowledge base

​Add a knowledge-base document

​Reindex a knowledge-base document

​Mark a knowledge-base document as verified

​Import a help center into the knowledge base

​Search the knowledge base

​Recommend the optimal channel + fallbacks for a recipient

​Generate AI-suggested replies for a conversation

​Summarize a conversation thread

​Translate text to a target language

​Delete a knowledge-base document

AI API

title: “AI Knowledge Base endpoints (ingest, refresh, search)” description: “Curated note covering the embedded org-wide knowledge base in the AI API, with endpoints for document ingest, staleness scoring, and grounded search.”

Worked session/memory + budget envelopes

1. Session memory round trip

2. Token-budget precheck

3. Errors-as-decision-table

List knowledge-source connectors

Get a knowledge-source connector

List knowledge-base documents

Get a knowledge-base document

Scan the knowledge base for stale documents

Analyze text (sentiment / intent / language / topics)

Analyze a stored message by ID and persist the analysis

OpenAI-compatible chat completion (general inference)

Classify the customer’s intent from a conversation

Draft a full campaign blueprint from a plain-English goal

Generate AI-powered dashboard insights from stats

Generate embedding vectors for one or more input strings

Generate channel-appropriate message content from a prompt

Improve, shorten, lengthen, or rephrase existing text

Answer a question from the knowledge base

Add a knowledge-base document

Reindex a knowledge-base document

Mark a knowledge-base document as verified

Import a help center into the knowledge base

Search the knowledge base

Recommend the optimal channel + fallbacks for a recipient

Generate AI-suggested replies for a conversation

Summarize a conversation thread

Translate text to a target language

Delete a knowledge-base document