Use Topo's OpenAPI and Agent Documentation
Use Topo's interactive API docs, OpenAPI schema, and agent setup instructions safely.
Where to find the docs
Open Staff > Account > API Keys and choose API docs to view the interactive API reference.
Use the OpenAPI schema when building an integration that needs exact endpoints, parameters, and response shapes.
Use the copied agent setup instructions when configuring an AI agent or automation tool to work with Topo's API.
Use the machine-readable query capabilities documentation when building reports or segments through an agent or integration.
First verification call
After creating a key, the first API call should verify the key by calling the API identity endpoint.
The identity response confirms the organization, role, permissions, access level, token status, and expiration.
If the key is read-only, the integration should explain that it can inspect data but cannot perform most business-data writes.
Safe agent setup
The API Keys page can copy setup instructions for Codex, Claude, ChatGPT, or another agent.
The safer option is to copy instructions with a placeholder and put the key into the agent platform's secure credential or connector settings.
If you include the actual key in chat, anyone who can see that chat may be able to use the key until you revoke it.
Ask agents to explain intended write actions and wait for confirmation before changing business data.
Never ask an agent to print, summarize, or reveal the API key.
Operational guidelines
Use the OpenAPI docs as the source of truth for endpoint names and request formats.
Use idempotency keys for write requests so retries do not accidentally duplicate work.
Keep API traffic mostly linear and avoid large parallel bursts. If the API returns a rate-limit response, wait before retrying.
For reports and segments, use Topo's documented query catalogs and allowlisted fields. Do not send raw SQL or arbitrary code.
Review API key last-used timestamps and revoke keys that are idle, expired, or no longer owned.
Common issues and fixes
The docs open but calls fail: check that the request includes Authorization: Bearer followed by the current token.
The agent cannot write: confirm the key is Full access and that the assigned role has the required permission.
The integration sees the wrong data: organization-level keys are pinned to one gym; create a key from the correct organization.
A key was pasted somewhere unsafe: revoke it immediately and create a replacement.