Agent Runbook

Before writing any code, read https://docs.telzino.com/agent-runbook.md and follow its ground rules. Fetch https://api.telzino.com/api-doc/openapi for exact request and response schemas.

​

Ground rules

1. The OpenAPI spec is the source of truth. Fetch https://api.telzino.com/api-doc/openapi (OpenAPI 3.0 JSON) and use its schemas for every request body and response. A Postman collection generated from the same spec is at https://api.telzino.com/api-doc/postman. Never invent an endpoint, parameter, or field that is not in the spec or in the catalog below.
2. All calls go through your backend — never from the browser. The API does not send CORS headers, and the OAuth client_secret must never ship in client-side code. Build a thin server proxy (pattern below) and have the UI call that.
3. Handle auth failures. Tokens last 24 hours (expires_in: 86400). On a 401, refresh the token once and retry; if it still fails, surface the error.
4. Respect pagination. List endpoints take page and limit (max 100) and return { "data": [...], "pagination": { "page", "limit", "total", "totalPages" } }. Build paging into every list view.
5. Surface API errors. Error responses are { "error": "<message>" } (often with an error_description) and a 4xx/5xx status. Show the message; don’t swallow it.

​

Authentication

curl -X POST https://api.telzino.com/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET",
    "audience": "https://api.telzino.com/",
    "grant_type": "client_credentials"
  }'

​

Required server-side proxy pattern

// server/telzino.ts — cache the token, proxy the calls. Secrets stay server-side.
let token: { value: string; expiresAt: number } | null = null;

async function getToken() {
  if (token && Date.now() < token.expiresAt - 60_000) return token.value;
  const res = await fetch("https://api.telzino.com/oauth/token", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      client_id: process.env.TELZINO_CLIENT_ID,
      client_secret: process.env.TELZINO_CLIENT_SECRET,
      audience: "https://api.telzino.com/",
      grant_type: "client_credentials",
    }),
  });
  if (!res.ok) throw new Error(`token exchange failed: ${res.status}`);
  const data = await res.json();
  token = { value: data.access_token, expiresAt: Date.now() + data.expires_in * 1000 };
  return token.value;
}

export async function telzino(path: string, init: RequestInit = {}) {
  const res = await fetch(`https://api.telzino.com${path}`, {
    ...init,
    headers: {
      ...init.headers,
      Authorization: `Bearer ${await getToken()}`,
      "Content-Type": "application/json",
    },
  });
  if (res.status === 401) token = null; // force refresh on next call
  return res;
}

​

Resource model

account (your credentials)
└── resellers
    └── organizations
        ├── agents            ← the AI phone agents
        │   ├── call logs     → recordings
        │   ├── outbound calls
        │   ├── SIP registration
        │   └── music-on-hold (MOH)
        ├── knowledge bases   → sources → ingestion jobs
        └── guardrails

​

Endpoint catalog

​

UI recipes

1. GET /v1/me → account ID → GET /v1/accounts/{accountId}/resellers → GET /v1/resellers/{resellerId}/organizations to build the org picker.
2. GET /v1/agents?organization_id={id}&page=1&limit=50 for the table.
3. Create: POST /v1/agents. Edit: GET /v1/agents/{agentId} then PUT with changed fields. Enable/disable toggle: PATCH /v1/agents/{agentId}/status (also carries SIP registration state — reflect the response, don’t assume).

1. GET /v1/agents/{agentId}/call-logs?page=… for the table (timestamps, duration, sentiment, summary; filter with startDate/endDate).
2. On row click, GET /v1/call-logs/{callLogId}/recording and feed the result to an <audio> element via your proxy.

1. POST /v1/agents/{agentId}/outbound-calls with the destination number (to_number, E.164). Handle the 429 agent_at_capacity response.
2. Poll GET /v1/agents/{agentId}/outbound-calls/{callId} for status; offer DELETE to remove a finished call’s record.

1. GET /v1/organizations/{organization_id}/knowledge-bases → pick or POST a new one.
2. GET /v1/knowledge-bases/{knowledgeBaseId}/sources; add with POST. For files: PUT the bytes to the returned presignedUrl, then POST /v1/knowledge-sources/{sourceId}/enqueue with the returned jobId.
3. Poll GET /v1/rag/jobs/{jobId} until the job completes; show per-source status.

1. GET /v1/metrics?startDate=…&endDate=… for headline numbers and charts.
2. GET /v1/reports/minutes-by-agent and /minutes-by-organization for breakdown tables; GET /v1/billing-report for the billing view.