Skip to main content
All API requests are authenticated with an API key sent in the x-api-key header:

​
API keys

  • Create a key in Settings → API Keys. Organization Admins and Members can create keys; Viewers cannot. Copy the full key when it is created, because it is only shown once.
  • API keys are scoped to your organization and grant access to all of its agents.
  • Store keys securely and never expose them in client-side code.
Requests with a missing or invalid key return 401 with an UNAUTHORIZED or INVALID_API_KEY error code. Requests for an agent that doesn’t belong to your organization return 401/404.

​
Validating your key

To check that your API key works, call a read-only endpoint. Credit usage authenticates the key at the organization level:
To also verify access to a specific agent, list its outcomes:
A 200 from both means your key is valid and the agent is reachable. Both calls are pure reads — they can’t schedule or modify anything, regardless of how they’re invoked.
The single-contact scheduling endpoint also accepts HEAD requests for connectivity checks without scheduling.

​
Request signing

Agents with request signing enabled require two additional headers on POST /agents/{agentId}/schedule/sequences. The x-api-key header is still required. That is the only scheduling endpoint that accepts signed requests: for these agents, POST /agents/{agentId}/schedule/sequence returns 403 with REQUEST_SIGNING_REQUIRED and retryable: false.
  • X-HMAC-Timestamp — current Unix time in seconds.
  • X-HMAC-Signature — Base64-encoded HMAC-SHA256 using the agent’s configured signing secret.
The signed value is the uppercase HTTP method, a newline, the timestamp header, a newline, and the exact request body. For bulk scheduling, this is POST + "\n" + timestamp + "\n" + rawBody. Sign the body exactly as sent; changing whitespace after signing invalidates the signature. The URL path is excluded from the signature. The timestamp must fall within the agent’s configured tolerance, which defaults to ±300 seconds. Signing is checked before JSON parsing. A request that fails signing returns 401 with retryable: false:

​
Rate limiting

  • The bulk scheduling endpoint defaults to 600 requests per minute per agent. The agent can have a different configured limit. API keys for the same organization share this per-agent budget.
  • Exceeding the limit returns HTTP 429 with error: "RATE_LIMITED" and retryable: true.
  • Wait the number of seconds in Retry-After before retrying. The response also includes X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset (Unix seconds).

​
Error format

Structured API errors contain a machine-readable error and a human-readable message:
Each endpoint’s reference page lists its specific error codes and additional fields. For example, bulk scheduling uses retryable to distinguish requests that may succeed later from requests that need correction, and includes per-contact rejection details when every contact fails validation. Clients should also handle server failures whose response body is not JSON. When retrying an unchanged bulk request after a timeout or server failure, reuse its Idempotency-Key: if the first attempt returned 202, the retry gets that response back with Idempotent-Replayed: true and nothing is scheduled twice. Only a 202 records the key, so a request that failed can be corrected and resent with the same key. Use a new key for each new batch.