Public API
Smackdab Public API.
Use x-api-key for authentication. Branch and organization context are derived from the API key and should not be sent in request bodies.
Public list endpoints use bounded pagination. Unless an endpoint states otherwise, limit must be between 10 and 100.
Cursor-based list endpoints return items in ascending id order and use last_record_id as the next-page cursor input. Notes and documents also support created_since and updated_since ISO date-time filters for incremental sync.
Activities are available as a first-class v1 resource through /api/v1/activities... endpoints and through the activities sync resource.
When a write or user-list request supports delegated user attribution, send one of id_user, acting_user_id, or delegated_user_id. owner_id remains a resource ownership field and is not the same as the acting user.
Public API access is plan-gated. Free and Kickstarter plans cannot use the public API. Pro allows 100 read requests per second and 25 write requests per second. Unlimited allows 500 read requests per second and 125 write requests per second.
Public API responses include live rate-limit headers: X-RateLimit-Plan, X-RateLimit-Bucket, X-RateLimit-Limit, X-RateLimit-Limit-Read, X-RateLimit-Limit-Write, X-RateLimit-Remaining, and X-RateLimit-Reset. When the limit is exceeded, the API returns HTTP 429 with Retry-After.
Versioned /api/v1/... paths are the preferred stable contract. Existing unversioned public paths remain compatible aliases during the v1 rollout.
Public API errors may use the legacy { data, message, responseType } shape or the v1-compatible { error, status_code, request_id, responseType } envelope. Clients should read error.code when present and fall back to message for legacy responses.
Authentication
- API Key: x-api-key
API Key is a simple and secure authentication method for public APIs. Clients include the key in API requests to verify access, using headers to send the key.
Security Scheme Type: | apiKey |
|---|---|
Header parameter name: | x-api-key |