---
name: topaz5-native-api
description: Use when controlling Topaz5 PBX with its native CLI. Authenticate, inspect account-scoped APIs, mutate owned fixtures with consent, and hand verification/payment to humans.
---

# Topaz5 native API

Read `/llms-full.txt`, `/agents/cli-schema.json` and `/agents/native-catalog.json` from the documentation site before selecting unfamiliar endpoints. Source inspection does not establish runtime authorization. Native account/user permissions are authoritative; do not use master tokens, change account identity in stored files, invent endpoints or implement another PBX/accounting engine.

## Installation and login

Python 3.10+; no runtime dependencies or private repository access needed. Download `https://topaz.tel/downloads/topaz5_cli-0.2.0-py3-none-any.whl`, `/downloads/SHA256SUMS` and `/downloads/manifest.json` from the same documentation site. Verify `sha256sum -c SHA256SUMS` in the download directory before installing. The manifest identifies the package version, pinned build tools, wheel hash and source hashes. No PyPI publication or public service deployment is implied.

If pipx is already installed: `pipx install ./topaz5_cli-0.2.0-py3-none-any.whl` (alternative, not separately exercised). Tested offline alternative:

```sh
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"
```

`topaz5 schema` and `topaz5 capabilities` expose the actual command contract. CLI package version is distinct from JSON schema/workflow versions.

`topaz5 login --base-url https://app.topaz.tel/v2 --realm YOUR-REALM --username YOUR-USERNAME` prompts securely. Human supplies password, never chat/argv/history. Native response binds the account and owner; credentials remain in a private 0600 local file. Do not display session contents. Expiry requires re-login; JWT refresh is unsupported. `topaz5 logout` is only local removal, not native revocation.

## Tested native sequence

1. `topaz5 users` and `topaz5 callflows`: inspect owned objects.
2. Prepare a newly labelled disposable native callflow JSON; native `numbers`, `patterns`, `flow` fields, not an API envelope. Avoid real DIDs, ringing and paid calls.
3. `topaz5 callflows --method PUT --data fixture.json --confirm-mutation`: create. Require response ID and exact readback ID/name.
4. `topaz5 callflows ID`: read before modifying. Save a complete native editable object.
5. `topaz5 callflows ID --method POST --data updated.json --confirm-mutation`: update. Require exact name/ID readback.
6. Only on explicitly owned disposable fixtures: `topaz5 callflows ID --method DELETE --confirm-mutation`. Require `verified_absent`.

PUT is create; POST is native item update, not an invented PATCH default. Native acceptance proved admin read/write, restricted-user write denial, sibling denial, exact create/update readback and delete absence. Account-scoped aliases cover additional resources but those wrappers are not all integration-exercised. `topaz5 api limits` is a literal own-account JSON escape hatch, not permission to address global/master APIs. Use `--query file.json` for native GET filters. Binary media and global/operator endpoints are unsupported.

## Safety and progress

- Read is default. Explicit `--confirm-mutation` for every write; `--accept-costs` also required for generic/financial/account/number/rate/service writes. Acknowledgment is not a quote. Get authoritative prices/human consent first.
- Every successful JSON read is native output; check required fields yourself. Never infer full data preservation from HTTP 200 or `verified_readback` alone.
- Read back exact target after writes. Unknown-write failure requires independent readback, never automatic retry. Action endpoints may not offer same-path GET; use their documented order/ledger/status records.
- `topaz5 await callflows/ID --field data.name --equals '"EXPECTED"' --max-seconds 30` is read-only, bounded. Nonzero errors are sanitized JSON on stderr; do not dump raw server errors or private configs to debug.
- Prefer native SmartPBX and APIs for custom Monster apps; no rewriting PBX controls or prepaid authority.

## Signup and payment

A person creates the account at https://signup.topaz.tel/ and adds credit at https://signup.topaz.tel/topup, paying on Stripe's hosted checkout. An agent may share those links but must never enter, request or handle card details. The CLI's signup and payment commands are not used by the current signup service. After signup the person sets their own password from the welcome email; log in only with credentials they enter themselves.