REST API: authentication, rate limits, idempotency and errors
Base URLs, bearer authentication with pt_live_/pt_test_ keys, per-key rate limits and their headers, Idempotency-Key, pagination and the error code vocabulary.
Everything the UI does, the API does. Monitoring resources live on https://api.pulsetrace.app/api/v1/…; organization and identity resources (members, keys, service accounts, environments, credentials, destinations) on https://api.pulsetrace.app/api/v1/auth/…. API access is available from the Team plan.
Authentication
Send an API key as a bearer token. Keys are prefixed pt_live_ or pt_test_ and carry scopes, optional environment and IP restrictions, and an expiry — see API keys. There is no X-API-Key header; Authorization: Bearer is the only form.
curl https://api.pulsetrace.app/api/v1/monitors \ -H "Authorization: Bearer pt_live_…"
Rate limits
Limits are per key, per minute, in three categories: read (GET/HEAD), write (POST/PUT/PATCH) and delete. A key defaults to 300 / 60 / 10 per minute and can be set lower per key; an organization policy caps what any key may be given (defaults 500 / 100 / 20), and an organization-wide aggregate is enforced as well. Every response carries:
X-RateLimit-Limit— the category's limit for this key.X-RateLimit-Remaining— requests left in the window.X-RateLimit-Reset— unix seconds when the window resets.
Exceeding a limit returns 429 with code RATE_LIMITED. Back off until X-RateLimit-Reset.
Idempotency
Send Idempotency-Key: <up to 255 chars> on any POST, PUT, PATCH or DELETE and a retry with the same key returns the original result instead of repeating the action. A key reused with a different body is rejected with 422 IDEMPOTENCY_KEY_CONFLICT; a retry while the first attempt is still running gets 409 IDEMPOTENCY_KEY_IN_PROGRESS.
Pagination
List endpoints take ?page= and ?limit= and return the page plus totals. Sorting and filtering parameters are documented per endpoint in the in-app API reference (Developer API → API docs).
Error codes
| Code | Status | Meaning |
|---|---|---|
VALIDATION_ERROR | 400 | A field is missing or out of range; the body names it. |
INVALID_API_KEY / EXPIRED_API_KEY / REVOKED_API_KEY | 401 | The key is unknown, past its expiry, or revoked. |
IP_NOT_ALLOWED | 403 | The request's source IP is outside the key's IP restrictions. |
FORBIDDEN | 403 | The key lacks the scope, or the plan lacks the feature. |
RESOURCE_NOT_FOUND | 404 | No such object in this organization. |
CONFLICT | 409 | Duplicate slug or name, or a state conflict. |
RATE_LIMITED | 429 | See rate limits. |
INTERNAL_ERROR | 500 | Something failed on our side; retry with the same Idempotency-Key. |
Reference
The full endpoint reference, with request and response schemas, is the in-app API docs page. An OpenAPI document for the PulseTrace API itself is not published yet; POST /api/v1/monitors/openapi/parse is the endpoint that reads *your* OpenAPI spec to create monitors.