> ## Documentation Index
> Fetch the complete documentation index at: https://docs.telzino.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Runbook for AI Assistants

> The steps an AI assistant follows to read, change, verify and undo changes to a Telzino AI agent

Give this page to your AI assistant. It's written for the assistant, and every step links to the API reference page with the exact request and response.

> Before changing any Telzino AI agent, read [https://docs.telzino.com/configure-with-ai/runbook.md](https://docs.telzino.com/configure-with-ai/runbook.md) and follow it step by step.

## Ground rules

1. **Only use documented endpoints and fields.** The [API reference](https://docs.telzino.com/api-reference/overview.md) and the OpenAPI spec at `https://api.telzino.com/api-doc/openapi` are the source of truth. Never guess an endpoint, field or value.
2. **Propose before you change.** Show the user every field you will change, with the old and new values, and wait for their approval before any `POST`, `PUT`, `PATCH` or `DELETE`.
3. **Change one agent at a time**, and read it again after each change.
4. **Never delete** an agent, knowledge base, source or other resource, and never place an outbound call, unless the user asks for that specific action.
5. **Keep secrets out of the chat.** Read the client ID and secret from the environment. Never print them, a token or any credential stored on an agent.

## Step 1: Get a token

Exchange the client ID and secret for a bearer token with [`POST /oauth/token`](https://docs.telzino.com/api-reference/authentication). Send `Authorization: Bearer <access_token>` on every request. Tokens last 24 hours. On a `401`, get a new token once and retry.

Then call [`GET /v1/me`](https://docs.telzino.com/api-reference/me) to see the account and the key's scope. If the key is limited to one reseller or organization, stay inside it. A request outside it returns `403`.

## Step 2: Find the agent

Call [`GET /v1/agents`](https://docs.telzino.com/api-reference/agents/list) with `organization_id` to list agents. Use `page` and `limit` (max 100) and keep paging until you've seen them all. Match the agent the user named by `name`, and confirm with the user if more than one matches.

## Step 3: Read the agent

Call [`GET /v1/agents/{agentId}`](https://docs.telzino.com/api-reference/agents/get) and keep the full response. This is your "before" copy.

## Step 4: Propose the change

Build the update body from the [Update Agent](https://docs.telzino.com/api-reference/agents/update.md) reference. Watch for these rules:

* **Reads and writes use different names.** Get Agent returns snake\_case top-level keys (`system_prompt`). Update Agent takes camelCase (`systemPrompt`) and rejects keys it doesn't recognise. Keys inside nested objects such as `config` and `voiceSettings` stay snake\_case.
* **Send only the fields you change.** Fields you leave out stay as they are.
* **Many objects are replaced whole, not merged**, for example `extensions`, `voiceSettings`, `pronunciations` and `interpreterConfig`. Start from the current value, apply the change and send the whole object back.
* **`email`** is returned as a string but must be sent as an array of addresses.

Show the user a before and after table of the changed fields and wait for approval.

## Step 5: Apply the change

Call [`PUT /v1/agents/{agentId}`](https://docs.telzino.com/api-reference/agents/update). Include `organizationId` so the request is refused if the agent isn't in the organization you expect. If the API returns `400`, show the user the error and its `details`. Don't retry with guessed values.

To turn an agent on or off, set `billing_state` to `live` or `off` with the same [`PUT /v1/agents/{agentId}`](https://docs.telzino.com/api-reference/agents/update) call.

## Step 6: Verify

Call Get Agent again and compare it with your "before" copy. Confirm that only the approved fields changed. Then call [`GET /v1/agents/{agentId}/history`](https://docs.telzino.com/api-reference/agents/history): the newest entry should list your changes. Note its `id`.

## Step 7: Undo if needed

If the user wants to undo, find the version from before your change in the history and call [`POST /v1/agents/{agentId}/history/{versionId}/revert`](https://docs.telzino.com/api-reference/agents/revert). Use the entry's `id`, not its `version` number. A revert is saved as a new version, so it can be undone the same way.

## Reading calls

To review how an agent is doing, call [`GET /v1/agents/{agentId}/call-logs`](https://docs.telzino.com/api-reference/call-logs). Each call log has a summary and the transcript. Call logs contain caller details: only quote what the user needs, and don't copy transcripts into other tools.

## More endpoints

The [Agent Runbook](https://docs.telzino.com/agent-runbook.md) for developers lists every endpoint, from knowledge bases to guardrails and retry policies.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.