Access and keys
How do I get a key?
An administrator of your Totem team creates an integration in Settings → Developers and copies its secret key into your server's secret store. The API is in Beta, with no invitation required. The administrator needs a verified email address, your organization needs Pro or a higher plan, or an agreed API entitlement, and the team must have completed its legal setup; the Quickstart lists every requirement and what to check when Create API key does not appear. It then takes you through your first requests.
Can one key read several teams?
Yes, when the teams belong to the same organization, and only a family administrator can create such a key. An integration covers an explicit list of up to 30 teams. Requests for one team's collections then name the team in the Totem-Team header, and you keep one changes-feed cursor per team. See Authentication.
Can I limit a key to my servers' IP addresses?
Yes. An integration can carry an allowlist of up to 20 IP addresses or CIDR ranges, set in Settings → Developers. The API is reachable over IPv4 only, so list the public IPv4 addresses your requests leave from. A request from any other address gets 403 ip_not_allowed. Authentication explains how to set it up.
Can I call the API from a browser or a mobile app?
No. A key reads administrator-level data, so it must stay on your server. The API sends no CORS headers, and it answers 400 secret_key_in_browser to a request that carries a key and an Origin header. Call the API from your backend, and send your app only the data it needs.
Data
Can I write data through the API?
No. Version 1.0a is read-only: no endpoint creates or changes anything in Totem. The changelog announces any new capability.
Can I read message text, call transcripts or recordings?
No. Version 1.0a returns contact details, such as names, email addresses and phone numbers, and metadata, but no message text, call transcripts, summaries, recordings, notes, free-text answers or custom form fields. A conversation tells you its channel, its status and when the last messages came and went. A call tells you its direction, its duration and its outcome.
How do I find a lead by phone number or email?
Send the phone number or the email address in the JSON body of POST /v1/leads/search, never in a URL. Send exactly one of the two. Search matches exactly, returns at most 10 leads and never pages, so when many records share the same phone number or email address, it may not return them all.
Sync and freshness
Are there webhooks?
No. The Totem API has no webhooks: read the changes feed with your stored cursor every 1 to 5 minutes. The webhooks that Totem's plans list are a separate feature of the product, set up in Totem, not with an API key. A poll that finds nothing new returns an empty page that still moves your cursor forward, so store its next_cursor too. See Keep a copy in sync.
How fast do changes appear?
Shortly after they happen in Totem. The changes feed holds back its last 10 seconds, so that a change still being written is never skipped. If you poll every 1 to 5 minutes, your copy stays about that close to Totem.
Why does a new record answer 404 for a moment?
Totem prepares each record for the API shortly after it changes. Until then, lists and search skip a new record, and GET on its id answers 404 resource_missing. The changes feed delivers the record as soon as it is ready. See Lists and pagination.
Testing and tools
Is there a sandbox?
Not yet. Version 1.0a has no test environment and no test keys: every key reads a real team. Use a dedicated team containing only fictitious contacts. The kit's fixtures.json holds example data for your unit tests. See Testing and go-live.
Is there an SDK?
Yes. The official TypeScript SDK, @totemstudioai/sdk, covers every endpoint and provides typed responses, pagination and API errors. It runs on your server, on the Node.js versions its page lists. To keep a copy of a team, start from the tested reference client of the sync guide. The OpenAPI document remains available for other languages.
Limits
What are the limits?
A key reads up to 2,000 items a minute, with bursts of up to 10,000. Each UTC day, list endpoints and the changes feed return it up to 250,000 items, or 3 times the number of records in its teams if that is more; requests for one record, search and GET /v1/me do not count toward that quota. A page holds up to 100 items. Past a limit, the API answers 429 with Retry-After: wait that many seconds, then continue with the same cursor. During the Beta these numbers are approximate, and an organization can hold up to 10 active integrations. See Rate limits.
Privacy
How do I honor erasure requests?
When a record is erased in Totem, the changes feed delivers a removal with reason: "erased". Erasing a lead also erases its calls, its conversations and the archived leads merged into it, and each arrives as a removal of its own; its bookings stay, with lead set to null. Delete the record from your copy and from every system you fed from it, and keep only its tombstone: its kind, id and version. Removals stay in the feed for 45 days, longer than a cursor lives, so a sync that keeps polling successfully never misses one. While the API refuses a team, no removals arrive for it, and when access returns after its cursor has expired, the full resync deletes what was removed meanwhile. A team in an excluded sector (sector_restricted) gets no removals until Totem changes its sector policy, so keep its copy only as long as your retention policy allows. See Keep a copy in sync.
Where does the API run, and who protects the data I copy?
The API runs on Google Cloud in the European Union and answers only over HTTPS. Once you copy data, protecting it is up to you and the customer whose data it is. Security and personal data explains both, and how to report a vulnerability.