# Atria AI Documentation

> The docs for Atria AI. Atria AI - The ad engine that keeps you winning Built for performance teams who need creative volume, velocity, and repeatable results.

Append .md to any documentation page URL to get its markdown version.

## Guides
- [Welcome to Atria AI](https://docs.tryatria.com/docs/getting-started.md)
- [Quickstart](https://docs.tryatria.com/docs/mcp-quickstart.md): What the Atria MCP server is, and how to connect your AI client to it.
- [Available Tools](https://docs.tryatria.com/docs/available-tools.md): The tools the Atria MCP server exposes, grouped by domain.
- [Use Cases](https://docs.tryatria.com/docs/mcp-use-cases.md): Short prompts your MCP-connected agent can run end to end.
- [Quickstart](https://docs.tryatria.com/docs/quick-start.md): Get an API key and make your first call to the Atria Open API.
- [API Basics](https://docs.tryatria.com/docs/api-basics.md): Authentication, the response envelope, and rate limits — the conventions shared by every endpoint.
- [Use Cases](https://docs.tryatria.com/docs/api-use-cases.md): Real-world recipes built on the Atria Open API.
- [Competitor Research](https://docs.tryatria.com/docs/competitor-research.md): Search a brand, then pull their newest active video ads in two calls.
- [Daily New-Ad Digest](https://docs.tryatria.com/docs/daily-new-ad-digest.md): Build a cron job that surfaces yesterday's new ads from your followed brands.
- [Keyword Ads Search](https://docs.tryatria.com/docs/keyword-ads-search.md): Find every "Black Friday" ad shipped last November — across all brands.
- [Long-Form Video Research](https://docs.tryatria.com/docs/long-form-video-research.md): Discover which brands are investing in 60s+ video creatives — and what those ads look like.
- [Analyze a Board with Claude](https://docs.tryatria.com/docs/analyze-a-board-with-claude.md): Pull every ad in a board, then send the lot to an LLM for creative analysis, theme clustering, or variant generation.
- [Setup Raya in Slack](https://docs.tryatria.com/docs/setup-raya-in-slack.md)

## API Reference
- [List saved library ads](https://docs.tryatria.com/reference/list_saved_library_ads.md): List ads the calling workspace has saved from the global ad library. Each item carries the standard ad fields plus a `saved_details` block (`saved_at`, `boards`, `tags`).  Scoped to the workspace bound to your API key. Use the response `cursor` to paginate.  Returns: `code=0` success; `code=40001` invalid query parameters.
- [Search ad library](https://docs.tryatria.com/reference/search_library_ads.md): Search Atria's global ad library across all platforms. Returns a paginated list of ads matching the given filters, ordered by the chosen sort order.  Use the returned `cursor` value as the `cursor` query parameter on the next request to fetch the following page. A null `cursor` in the response means there are no more results.  Returns: `code=0` success; `code=40001` invalid query parameters.
- [Get library ad](https://docs.tryatria.com/reference/get_library_ad.md): Fetch the full record for a single ad from Atria's global ad library, including creative assets (images / videos), copy, CTA and brand metadata.  Returns: `code=0` success; `code=40401` when no ad matches the id in the global catalog.
- [List followed library brands](https://docs.tryatria.com/reference/list_followed_library_brands.md): List library brands the calling workspace is following / tracking. These are the catalog brands surfaced in the workspace's competitor view — same data pool as `GET /open/v1/brand-library/search`, filtered to the follow relation.  Scoped to the workspace bound to your API key.  Returns: `code=0` success; `code=40001` workspace context missing.
- [Search brand library](https://docs.tryatria.com/reference/search_library_brands.md): Search Atria's global brand library by name. Results span all ingested sources (Meta and TikTok ad libraries), ordered by ad volume (`ad_num`) descending.  Each result's `id` carries an origin prefix: `m*` for Meta-origin brands and `t*` for TikTok-origin. Use that `id` directly when calling `GET /open/v1/brand-library/{brand_id}` or `GET /open/v1/brand-library/{brand_id}/ads`.  Returns: `code=0` success; `code=40001` invalid query parameters.
- [Get library brand](https://docs.tryatria.com/reference/get_library_brand.md): Fetch full metadata for a single library brand: name, avatar, website, description, industries, ad count and source library.  Returns: `code=0` success; `code=40401` when no brand matches the id in the global catalog.
- [List library brand ads](https://docs.tryatria.com/reference/list_library_brand_ads.md): List ads from Atria's global ad library that belong to a specific library brand. Filters here apply to that brand's ads only.  Returns: `code=0` success; `code=40401` when the brand does not exist in the global catalog.
- [List owned brands](https://docs.tryatria.com/reference/list_owned_brands.md): Return the calling workspace's own brand profiles — the entities you create under Atria's brand-management UI. Each carries the brand id, name, industries, logo, website, color palette and fonts.  Use the returned `id` as `brand_id` for the image generation endpoints. Distinct from `GET /open/v1/brand-library/followed` (catalog brands the workspace tracks) and `GET /open/v1/brand-library/search` (global ad-library catalog).  Returns: `code=0` success; `code=40001` workspace context missing.
- [Create image generation](https://docs.tryatria.com/reference/create_image_generation.md): Submit an image-generation request. The caller's `prompt` is treated as a **creative brief**: Atria expands it into `size` **distinct** concept variants and renders one image per variant. `size > 1` returns real creative variety, not seed-jittered copies of the same prompt.  Treat `prompt` as a directional brief (intent, audience, mood, visual hints), not the final image-model prompt — Atria produces the per-variant prompts internally.  **Async.** Returns immediately with a `generation_id` and (initially empty) `image_ids`. Poll `GET /open/v1/image-generations/{generation_id}` to pick up image ids and track status; see that endpoint for cadence guidance.  **Brand required.** `brand_id` must reference a workspace-owned brand from `GET /open/v1/owned-brands`. The brand's logo / colors / product context grounds the brief — there is no placeholder fallback. Cross-workspace brand ids return `code=40401`.  **Idempotency.** `idempotency_key` deduplicates retries — re-submitting the same key from the same workspace returns the same `generation_id` and never produces a duplicate charge. Pick a stable UUID per attempt; reuse only to recover from a dropped response.  **Credits.** Charged at the same rate as the in-app image generation feature — trigger one image in Atria's web app to see the current per-image credit cost; `size` multiplies it. Credits are reserved on submit; per-image failures are auto-refunded, while credits consumed by successfully rendered images cannot be restored.  Errors: `code=40001` when workspace context is missing from the request; `code=40401` for unknown / cross-workspace `brand_id`; `code=50001` when the upstream image-gen service is unavailable, returns an error envelope, or rejects the submit (including credit-exhaustion at the upstream layer).
- [Get image-generation status](https://docs.tryatria.com/reference/get_image_generation.md): Poll the status of a `POST /open/v1/image-generations` submission. Returns the same `OpenImageGeneration` shape — `status` is `pending` / `processing` / `success` / `partial_success` / `failed`, and `image_ids` populates once the request fans out into per-image tasks.  **Polling cadence**: poll every 2–5 seconds. The fan-out step typically completes in 5–15s; individual images then complete asynchronously over the next 15–60s each.  **Terminal statuses**: `success` (all images done), `partial_success` (some failed), `failed` (no images produced). Stop polling on any terminal state.  Use individual `GET /open/v1/image-generations/{generation_id}/images/{image_id}` calls to fetch each image's generated URL.  Returns: `code=0` success; `code=40001` invalid `generation_id` or workspace context missing; `code=40401` when the generation does not belong to the caller's workspace; `code=50001` when the upstream image-generation service is unavailable.
- [Get image-generation image](https://docs.tryatria.com/reference/get_image_generation_image.md): Fetch a single generated image: prompt, status, aspect ratio, generated image URL (when complete). The image's URL is null until rendering finishes — keep polling until `status` is `success` or `failed`.  `generation_id` in the path is a structural parent reference; ownership is enforced by the caller's workspace, and the lookup is keyed on `image_id`.  Returns: `code=0` success; `code=40001` invalid path parameters or workspace context missing; `code=40401` when the image does not belong to the caller's workspace; `code=50001` when the upstream image-generation service is unavailable.
- [List connected ad accounts](https://docs.tryatria.com/reference/list_ad_accounts.md): List Meta and TikTok ad accounts the calling workspace has connected. Use the returned `id` as `account_id` on the per-account endpoints (`/open/v1/ad-accounts/{account_id}/summary`, `/open/v1/ad-accounts/{account_id}/ads`, `/open/v1/ad-accounts/{account_id}/ads/{platform_ad_id}`).  Scoped to the workspace bound to your API key. No pagination — workspaces rarely connect more than a handful of accounts.  Returns: `code=0` success; `code=40001` workspace context missing.
- [List ad-account ads](https://docs.tryatria.com/reference/list_ad_account_ads.md): The account's own ads with their metrics, ranked by `sort_by` and capped at `limit` rows. Ranking covers every ad in the window, so the top rows are the account's best on that metric — not just the best of an arbitrary page.  Each item carries a preview image URL and the same metric set as `/summary`. Use the returned `platform_ad_id` with `GET /open/v1/ad-accounts/{account_id}/ads/{platform_ad_id}` to drill into a single ad's creative + text copy.  **Window**: `period` accepts `yesterday`, `last_7d`, `last_14d`, `last_30d`, or `custom` with `date_start` / `date_stop` for a specific day or range. Windows are UTC days and the presets end yesterday. The most recent days are still settling — ad platforms keep revising conversion data for a while after a day closes — so figures for a day just ended are the least reliable, and the same day re-read later can differ.  **Metrics**: `metrics` is keyed by metric id, with `metric_names` giving each id's display name. Ids come from `GET /open/v1/ad-accounts/{account_id}/metrics`; pass them in `metrics` to add custom conversions, custom events and Atria custom metrics on top of the default set. `null` means no data for that metric in the window. Figures can differ slightly from the ad platform's own reporting.  Returns: `code=0` success; `code=40001` invalid query / path parameters or workspace context missing; `code=40401` when the account does not exist or belongs to a different workspace; `code=50001` when the upstream platform API is unavailable.
- [Get ad-account ad](https://docs.tryatria.com/reference/get_ad_account_ad.md): Full creative (text copy + image / video assets + CTA) plus per-ad metric values over the requested window — the drill-down for a single ad returned by `GET /open/v1/ad-accounts/{account_id}/ads`.  **Window**: `period` accepts `yesterday`, `last_7d`, `last_14d`, `last_30d`, or `custom` with `date_start` / `date_stop` for a specific day or range. Windows are UTC days and the presets end yesterday. The most recent days are still settling — ad platforms keep revising conversion data for a while after a day closes — so figures for a day just ended are the least reliable, and the same day re-read later can differ.  **Metrics**: `metrics` is keyed by metric id, with `metric_names` giving each id's display name. Ids come from `GET /open/v1/ad-accounts/{account_id}/metrics`; pass them in `metrics` to add custom conversions, custom events and Atria custom metrics on top of the default set. `null` means no data for that metric in the window. Figures can differ slightly from the ad platform's own reporting.  Returns: `code=0` success; `code=40001` invalid path parameters or workspace context missing; `code=40401` when the account or the `platform_ad_id` is not accessible to the caller; `code=50001` when the upstream platform API is unavailable.
- [Get ad-account summary](https://docs.tryatria.com/reference/get_ad_account_summary.md): Account-wide totals for the requested window — one set of metric values covering the whole account.  **Window**: `period` accepts `yesterday`, `last_7d`, `last_14d`, `last_30d`, or `custom` with `date_start` / `date_stop` for a specific day or range. Windows are UTC days and the presets end yesterday. The most recent days are still settling — ad platforms keep revising conversion data for a while after a day closes — so figures for a day just ended are the least reliable, and the same day re-read later can differ.  **Metrics**: `metrics` is keyed by metric id, with `metric_names` giving each id's display name. Ids come from `GET /open/v1/ad-accounts/{account_id}/metrics`; pass them in `metrics` to add custom conversions, custom events and Atria custom metrics on top of the default set. `null` means no data for that metric in the window. Figures can differ slightly from the ad platform's own reporting.  Returns: `code=0` success; `code=40001` invalid `account_id` or workspace context missing; `code=40401` when the account does not exist or belongs to a different workspace; `code=50001` when the upstream platform API is unavailable.
- [Get cached ad-account video transcript](https://docs.tryatria.com/reference/get_ad_account_video_transcript.md): Cache-only lookup. Returns the existing transcript for this video if the workspace has one, or `code=40401` if nothing is cached yet. **Never** triggers a transcription and never costs credits — use this to scan candidates before deciding which to POST and pay to transcribe.  Returns: `code=0` cached transcript; `code=40001` invalid `account_id`; `code=40401` no cached transcript yet / cross-workspace account / unknown video.
- [Transcribe ad-account video](https://docs.tryatria.com/reference/transcribe_ad_account_video.md): Transcribe a workspace-owned ad video to text. Synchronous: blocks until the transcript is ready (~30-60 seconds on a cache miss, near-instant on a hit).  **POST vs GET semantics.** POST on this path triggers transcription; GET on the **same path** is a pure cache lookup that never triggers and never charges. Pick the verb by intent.  **Caching.** Transcripts are cached per workspace + video content-hash, so repeat calls in the same workspace return the cached transcript at 0 credit.  **Credits.** Cache hit: 0 credits. Cache miss: charged at the same rate as the in-app video-transcription feature — trigger it once in Atria's web app to see the current per-call credit cost. A successful charge cannot be reversed; the charge is auto-refunded only if transcription itself fails.  Returns: `code=0` success (status=`success` with transcript, or status=`failure` with `error` populated and credits refunded); `code=40001` invalid `account_id`; `code=40401` cross-workspace / unknown account / video not found on the platform; `code=42900` when the workspace is out of credits for this feature.
- [List ad-account metrics](https://docs.tryatria.com/reference/list_ad_account_metrics.md): List every metric defined on this ad account — Atria's built-in metrics plus everything configured per-account: Meta custom conversions (`fb_cc_*`), Meta custom events (`fb_ce_*`), and Atria custom metrics (user-defined formulas). All of them are returned by default.  This is a **definition catalog, not values** — it tells you which metrics exist on the account and what to call them. Ids returned here are the canonical, stable way to name a metric; display names are user-editable and can collide, so prefer `id`.  The custom entries are account-specific and change whenever they are edited in Meta or in Atria, so re-read the catalog rather than hardcoding ids. Meta custom conversions / events exist on Facebook accounts only.  Scoped to the workspace bound to your API key. Filter with `kind` to fetch one family at a time — accounts can define hundreds of custom conversions.  Returns: `code=0` success; `code=40001` invalid `account_id` or workspace context missing; `code=40401` when the account does not exist or belongs to a different workspace.
- [List boards](https://docs.tryatria.com/reference/list_boards.md): List all boards belonging to the calling workspace as a flat array, depth-first ordered (parent then its descendants then the next sibling). Reconstruct the tree on the client by following `parent_id` links — `children` is always empty on this surface to avoid duplicating the same nodes across the response.  Top-level boards carry `parent_id == workspace_id` as a sentinel.  Page-based pagination — pass `page=2`, `page=3`, ... to walk the list. Each board is returned exactly once across all pages.  Returns: `code=0` success; `code=40001` workspace context missing.
- [Get board](https://docs.tryatria.com/reference/get_board.md): Fetch a single board's metadata. `children` is populated with the direct child boards only (one level deep). To reconstruct deeper subtrees, follow each child's `board_id` recursively or use `GET /open/v1/boards` and rebuild the tree on the client.  Returns: `code=0` success; `code=40001` invalid `board_id` or workspace context missing; `code=40401` when the board does not exist in the caller's workspace.
- [List board ads](https://docs.tryatria.com/reference/list_board_ads.md): List the ads saved into a specific board. Filters here apply only to the ads in that board, not the global ad library.  Returns: `code=0` success; `code=40001` invalid `board_id` or workspace context missing; `code=40401` when the board is not accessible to the caller's workspace.

## Changelog
- [Atria MCP server + documentation refresh](https://docs.tryatria.com/changelog/atria-mcp-and-docs-refresh.md)
- [v0.2.0 — API v1 namespace consolidation](https://docs.tryatria.com/changelog/v020-api-v1-namespace-consolidation.md)