Use the API safely: keys, requests and errors
Authenticate server-side, select scopes and build against the current OpenAPI contract.
3 min read
Screenshots show the real application in an isolated demo environment with fictional example data. Setup notices and controls may differ by environment, plan and role. Click an image to view it full-size, and always use the values generated in your own workspace.
Create a key with the smallest useful scope
- 1The workspace owner opens API & webhooks when the plan includes the capability.
- 2Create a named key so its purpose is recognizable later. Select Read for reporting or Read and write only when your integration must change records.
- 3Copy the newly shown token into your server’s secure secret storage. Keys are stored as hashes; keep your own secure copy rather than expecting to recover the original token later.
- 4Use a separate key per integration and revoke it when it is no longer needed.
Authentication and workspace isolation
Send the key as an Authorization: Bearer header over HTTPS. Do not put it in a browser embed, URL query string or public repository. API requests act as the member who created the key, and their current workspace membership and role are checked on every call.
The settings screen displays the API base URL. Both /app/api/v1 and the canonical /api/v1 routes are supported by the current app. Use the displayed base for your environment and the public OpenAPI document at /app/api/v1/openapi.json for exact schemas.
curl --request GET \
"https://YOUR_DOMAIN/app/api/v1/campaigns" \
--header "Accept: application/json" \
--header "Authorization: Bearer YOUR_SERVER_SIDE_API_KEY"
Your browser blocked clipboard access. Select the text and copy it manually.
What you can automate
- List, create, read, update and delete permitted campaigns using the documented endpoints.
- Publish, pause, resume or duplicate through the documented campaign action routes.
- Read campaign analytics and manage supported phase/behavior configuration.
- List or create supported landing pages according to the schema.
- Use explicit timezone offsets for timestamps and the exact enum values shown in OpenAPI.
Handling errors and rate limits
Use the response status and validation body, not a guessed success based on an HTTP redirect. Common cases are unauthenticated credentials, forbidden membership/scope/feature access, a missing or inaccessible record, invalid input and throttling.
The current key limit is 120 requests per minute per key; additional inbound protection can also apply. On HTTP 429, honor retry guidance and use backoff. Do not create more keys simply to bypass an allowance.
Read the current schema before sending updates. A replacement list can remove earlier values; an empty phase list deletes phases and should be paired with the intended enabled state. Treat DELETE and publication actions as real changes, and test against separate test campaigns first.