Developers & agents

Start with an account

Most customers never need this page: the Control panel covers everyday setup. Developers and AI agents can also manage an account through the Kazoo REST API behind the Control panel, using the topaz5 command-line tool. First sign up and set your password, then log in with the same username, password and account realm you use for the Control panel. The API base URL is https://app.topaz.tel/v2. This website serves documentation, not an API endpoint.

Install the downloadable CLI

Python 3.10+; no runtime dependencies. The CLI is not published to a public package registry. No private source checkout is needed. Download CLI 0.2.0 wheel · Source/hash manifest · SHA256SUMS. Download the wheel and checksum file into the same directory, verify before installation, then use either pipx (if installed) or a fresh virtualenv. Fresh offline virtualenv installation is tested; pipx is an alternative, not separately exercised.

sha256sum -c SHA256SUMS
# Option A: if pipx is installed
pipx install ./topaz5_cli-0.2.0-py3-none-any.whl
# Option B: Python virtualenv (tested)
python3 -m venv ~/.local/share/topaz5/venv
~/.local/share/topaz5/venv/bin/pip install --no-index --no-deps ./topaz5_cli-0.2.0-py3-none-any.whl
~/.local/share/topaz5/venv/bin/topaz5 --help
export PATH="$HOME/.local/share/topaz5/venv/bin:$PATH"

Authenticate and inspect

Login prompts for the password; never send passwords through chat, command arguments or shared logs. Your account comes from your login, not an account override.

topaz5 login --base-url https://app.topaz.tel/v2 --realm YOUR-ACCOUNT-REALM --username YOUR-USERNAME
topaz5 capabilities
topaz5 users
topaz5 callflows
topaz5 api limits

Login, reading your own user and the callflow create/read/update/delete cycle have been tested. Other resource commands are not all runtime-tested.

Callflow lifecycle

Only use newly labelled test objects in your own account. Prepare an unwrapped Kazoo data object in new-callflow.json, then read the returned ID before updating. PUT creates on the collection; POST updates an item. Send the complete editable object.

topaz5 callflows --method PUT --data new-callflow.json --confirm-mutation
topaz5 callflows RETURNED_ID
topaz5 callflows RETURNED_ID --method POST --data updated-callflow.json --confirm-mutation
topaz5 callflows RETURNED_ID --method DELETE --confirm-mutation

Compare the returned ID and required fields after each write, and confirm a deletion with a separate read. Do not connect an example to real numbers or place paid calls.

JSON results, consent and recovery

Output is structured JSON; sanitized errors go to stderr with exit 2. Reads are the default. Every write requires --confirm-mutation; generic API, financial, account, number, rate, balance, service and payment writes also require --accept-costs. That flag is not a quote: check pricing and get a person’s approval first. Writes are never automatically retried. A timeout may hide a successful write: read the exact target before trying again. verified_readback proves a successful GET of the exact target, not equality of every requested field.

Sessions and transport limits

The local session file is private and tied to one API origin. Do not edit it or import operator tokens. Expired tokens require a new login. logout removes local credentials only, not server-side revocation. JWT refresh, binary media transport and global/operator APIs are not implemented. Account permissions remain authoritative; the callback catalog is source evidence, not proof that every API call works.

Signup and payments

Accounts are created by a person at signup.topaz.tel, and credit is added at signup.topaz.tel/topup. Both use Stripe’s hosted checkout. An agent may share these links with a person but must never enter or handle card details. The CLI’s signup and payment commands are not used by the current signup service.

Machine documentation

LLM index · Full agent API guide · Portable agent skill · Partial OpenAPI · CLI schema · Kazoo callback catalog · Legacy signup contract (not used by the current signup). The skill is a download; nothing is installed into an agent profile automatically. The OpenAPI document is partial. The catalog lists 93 pinned Kazoo module callbacks with source hashes; it does not prove runtime authorization or CLI coverage for every module.