API Basics

The conventions shared by every Atria Open API endpoint. (Pagination is per-endpoint and documented in the API Reference, not here.)

Base URL

https://api.tryatria.com

All endpoints live under /open/v1/.

Authentication

Every request must include your API key in the X-API-Key header:

X-API-Key: atria-sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

API keys start with the atria-sk_ prefix. To create one:

In the Atria web app, click the avatar in the top-left corner.
Go to Settings & members → API Keys.
Click Create API key to issue a new key.

🚧
Copy your key immediately
The full key is shown only once at creation time — store it in a password manager or secrets vault before closing the modal. If you lose it, you'll need to rotate to a new key.

Each workspace can have up to two active keys.

Missing, invalid, disabled, or expired credentials are rejected with HTTP 401. Treat the response message as diagnostic text, not a stable string to match. The API key determines the workspace; callers cannot choose another workspace by supplying identity headers or request fields.

Response envelope

Every successful endpoint returns the same wrapper:

{
  "code": 0,
  "message": "ok",
  "data": { ... }
}

code: 0 means success. A non-zero code indicates a business-level error — read message for context.
Always check HTTP status and then code before reading data. Parameter validation and missing Inspo resources can return HTTP 200 with nonzero codes (40001 and 40401).
Gateway failures may use { error, message, request_id }, while quota, billing, and upstream errors can use { code, message } even with a non-2xx status. Do not assume one universal error shape.
HTTP 402 indicates a billing or plan-allowance rejection. Code 40202 means the plan allowance is exhausted without a fallback; retrying unchanged will not fix it.

Rate limits

Limits depend on your workspace plan. Metered responses can include RateLimit-Policy (allowance/window) and RateLimit (remaining/reset information). On HTTP 429, honor Retry-After when provided and use bounded retries with backoff. A plan without API access can return HTTP 403; waiting does not enable that access.

Followed-brand and manual advertiser-tracking quotas are separate resource limits, reported in endpoint data.quota.