Atria AI

https://docs.tryatria.com
Admin
Atria AI provides an open API, MCP server, and AI coworker designed to let AI agents search public...
Tokens:48,453
Snippets:204
Trust Score:9.8
Update:2 months ago
Show doc for...
Tokens:
Raw
### Fetch brand ads via API

Source: https://docs.tryatria.com/docs/daily-new-ad-digest

Examples for retrieving a brand's ads using cURL, Python, and Node.js. All examples use cursor-based pagination and filter by a specific start date.

```bash
curl -sS \
  -H "X-API-Key: $ATRIA_API_KEY" \
  "https://api.tryatria.com/open/v1/brand-library/m1234567890123456/ads?start_date=2026-05-11&order=newest&page_size=50"
```

```python
import os
import requests

brand_id = "m1234567890123456"
resp = requests.get(
    f"https://api.tryatria.com/open/v1/brand-library/{brand_id}/ads",
    headers={"X-API-Key": os.environ["ATRIA_API_KEY"]},
    params={
        "start_date": "2026-05-11",  # yesterday
        "order": "newest",
        "page_size": 50,
    },
    timeout=30,
)
resp.raise_for_status()
data = resp.json()["data"]
print(f"{len(data['items'])} new ads (cursor={data['cursor']})")
```

```javascript
const brandId = "m1234567890123456";
const url = new URL(
  `https://api.tryatria.com/open/v1/brand-library/${brandId}/ads`,
);
url.searchParams.set("start_date", "2026-05-11"); // yesterday
url.searchParams.set("order", "newest");
url.searchParams.set("page_size", "50");

const resp = await fetch(url, {
  headers: { "X-API-Key": process.env.ATRIA_API_KEY },
});
const { data } = await resp.json();
console.log(`${data.items.length} new ads (cursor=${data.cursor})`);
```

--------------------------------

### GET /open/v1/boards

Source: https://docs.tryatria.com/reference/list_boards

Retrieves a flat, depth-first list of boards.

```APIDOC
## GET /open/v1/boards

### Description
Returns a flat, depth-first array of boards. The children list is always empty for this endpoint; the tree structure should be rebuilt client-side using parent_id links.

### Method
GET

### Endpoint
/open/v1/boards

### Response
#### Success Response (200)
- **code** (integer) - Success code (0 for success)
- **message** (string) - Response message
- **data** (object) - Contains items, total, page, and page_size
```

--------------------------------

### Error Response Example

Source: https://docs.tryatria.com/reference/list_ad_account_ads

Example of a 400 Bad Request response body indicating a validation failure.

```json
{
  "errorMessage": "query.platform.0 - unexpected value; permitted: 'facebook', 'instagram', 'messenger', 'audience_network', 'threads', 'whatsapp', 'tiktok', 'linkedin'"
}
```

--------------------------------

### Search for brands by keyword

Source: https://docs.tryatria.com/docs/daily-new-ad-digest

Use these examples to look up brands by name using the brand-library search endpoint.

```python
import os
import requests

resp = requests.get(
    "https://api.tryatria.com/open/v1/brand-library/search",
    headers={"X-API-Key": os.environ["ATRIA_API_KEY"]},
    params={"keyword": "acme", "page_size": 10},
    timeout=30,
)
resp.raise_for_status()
for brand in resp.json()["data"]["items"]:
    print(brand["id"], brand["name"], f"({brand.get('source_library')})")
```

```javascript
const url = new URL("https://api.tryatria.com/open/v1/brand-library/search");
url.searchParams.set("keyword", "acme");
url.searchParams.set("page_size", "10");

const resp = await fetch(url, {
  headers: { "X-API-Key": process.env.ATRIA_API_KEY },
});
const { data } = await resp.json();
for (const brand of data.items) {
  console.log(brand.id, brand.name, `(${brand.source_library})`);
}
```

--------------------------------

### GET /open/v1/ad-library/saved

Source: https://docs.tryatria.com/reference/list_saved_library_ads

Retrieves a paginated list of saved library ads.

```APIDOC
## GET /open/v1/ad-library/saved

### Description
Retrieves a list of saved library ads with associated metadata. Supports cursor-based pagination.

### Method
GET

### Endpoint
/open/v1/ad-library/saved

### Response
#### Success Response (200)
- **code** (integer) - Status code (0 for success)
- **message** (string) - Response message
- **data** (object) - The paginated list of saved ads
  - **items** (array) - List of saved ads
  - **total** (integer) - Total number of matching ads
  - **cursor** (string) - Cursor for pagination
  - **page_size** (integer) - Number of items returned on this page
```

--------------------------------

### Fetch all ads from a board

Source: https://docs.tryatria.com/docs/analyze-a-board-with-claude

Use these examples to iterate through board ads using cursor-based pagination to handle large datasets.

```python
import os
import requests

API_KEY = os.environ["ATRIA_API_KEY"]
BOARD_ID = "board_abc123"  # from Step 1

def all_ads_in_board(board_id: str):
    params = {"page_size": 100, "order": "saved_newest"}
    cursor = None
    while True:
        if cursor:
            params["cursor"] = cursor
        resp = requests.get(
            f"https://api.tryatria.com/open/v1/boards/{board_id}/ads",
            headers={"X-API-Key": API_KEY},
            params=params,
            timeout=30,
        )
        resp.raise_for_status()
        data = resp.json()["data"]
        yield from data["items"]
        cursor = data.get("cursor")
        if not cursor:
            return

ads = list(all_ads_in_board(BOARD_ID))
print(f"loaded {len(ads)} ads from board {BOARD_ID}")
```

```javascript
const API_KEY = process.env.ATRIA_API_KEY;
const BOARD_ID = "board_abc123"; // from Step 1

async function* allAdsInBoard(boardId) {
  let cursor = null;
  while (true) {
    const url = new URL(
      `https://api.tryatria.com/open/v1/boards/${boardId}/ads`,
    );
    url.searchParams.set("page_size", "100");
    url.searchParams.set("order", "saved_newest");
    if (cursor) url.searchParams.set("cursor", cursor);

    const resp = await fetch(url, { headers: { "X-API-Key": API_KEY } });
    const { data } = await resp.json();
    for (const ad of data.items) yield ad;
    cursor = data.cursor;
    if (!cursor) return;
  }
}

const ads = [];
for await (const ad of allAdsInBoard(BOARD_ID)) ads.push(ad);
console.log(`loaded ${ads.length} ads from board ${BOARD_ID}`);
```

--------------------------------

### GET /brand-library/followed

Source: https://docs.tryatria.com/docs/daily-new-ad-digest

Retrieve a list of followed brands using page-based pagination.

```APIDOC
## GET /brand-library/followed

### Description
Retrieves brands that the user is currently following. Uses page-based pagination.

### Method
GET

### Endpoint
/brand-library/followed

### Parameters
#### Query Parameters
- **page** (integer) - Optional - The page number to retrieve.
- **page_size** (integer) - Optional - Number of items per page (max 100).
```

--------------------------------

### List boards cURL request

Source: https://docs.tryatria.com/reference

Retrieves all boards for the workspace using a GET request to the boards endpoint.

```Shell
curl --request GET \
     --url https://api.tryatria.com/open/v1/boards \
     --header 'accept: application/json'
```

--------------------------------

### GET /open/v1/brand-library/owned

Source: https://docs.tryatria.com/reference/list_owned_brands

Retrieves the list of brand profiles owned by the current workspace.

```APIDOC
## GET /open/v1/brand-library/owned

### Description
Returns the calling workspace's own brand profiles, which are the entities created under Atria's brand-management UI. Each brand profile includes the brand id, name, industries, logo, website, color palette, and fonts.

### Method
GET

### Endpoint
/open/v1/brand-library/owned

### Response
#### Success Response (200)
- **code** (integer) - Returns 0 on success.
- **data** (array) - List of brand objects containing id, name, industries, logo, website, color palette, and fonts.

#### Error Response (40001)
- **code** (integer) - Returns 40001 if the workspace context is missing.
```

--------------------------------

### GET /open/v1/ad-library/{ad_id}

Source: https://docs.tryatria.com/docs/long-form-video-research

Fetches the full detail for a single advertisement using its unique identifier.

```APIDOC
## GET /open/v1/ad-library/{ad_id}

### Description
Fetches the full detail for a single advertisement using its unique identifier.

### Method
GET

### Endpoint
https://api.tryatria.com/open/v1/ad-library/{ad_id}

### Parameters
#### Path Parameters
- **ad_id** (string) - Required - The unique identifier for the ad (e.g., an 'm...' or 't...' identifier).
```

--------------------------------

### Brand search response structure

Source: https://docs.tryatria.com/docs/competitor-research

Example JSON response returned by the brand search endpoint.

```json
{
  "code": 0,
  "message": "ok",
  "data": {
    "items": [
      {
        "id": "m1234567890123456",
        "name": "Acme Co.",
        "avatar_url": "https://cdn.example.com/acme.png",
        "website_url": "https://acme.example",
        "industries": ["shopping"],
        "ad_num": 142,
        "source_library": "meta_ad_library"
      }
    ],
    "total": 1,
    "page": 1,
    "page_size": 5
  }
}
```

--------------------------------

### GET /open/v1/brand-library/{brand_id}

Source: https://docs.tryatria.com/reference/get_library_brand

Fetch full metadata for a single library brand by its unique Atria-prefixed identifier.

```APIDOC
## GET /open/v1/brand-library/{brand_id}

### Description
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.

### Method
GET

### Endpoint
/open/v1/brand-library/{brand_id}

### Parameters
#### Path Parameters
- **brand_id** (string) - Required - Atria-prefixed library-brand identifier. Format `m*` (Meta-origin) or `t*` (TikTok-origin). Obtain it from `GET /open/v1/brand-library/search` or `GET /open/v1/brand-library/followed` (`items[].id`). Do **not** pass the raw platform page id.

### Response
#### Success Response (200)
- **id** (string) - Atria-prefixed stable brand identifier.
- **name** (string) - Brand display name.
- **avatar_url** (string) - Brand logo URL.
- **website_url** (string) - Brand homepage URL if known.
- **description** (string) - Brand mission / about-us blurb.
- **industries** (array) - Industry tags inferred from the brand's catalog presence.
- **ad_num** (integer) - Approximate count of ads from this brand in Atria's library.
- **source_library** (string) - Source library the brand was indexed from: `meta_ad_library` or `tiktok_ad_library`.
```

--------------------------------

### GET /open/v1/brand-library/followed

Source: https://docs.tryatria.com/reference/list_followed_library_brands

Retrieves a list of library brands that the calling workspace is following. This data is scoped to the workspace bound to the provided API key.

```APIDOC
## GET /open/v1/brand-library/followed

### Description
List library brands the calling workspace is following or tracking. These are the catalog brands surfaced in the workspace's competitor view.

### Method
GET

### Endpoint
/open/v1/brand-library/followed

### Parameters
#### Query Parameters
- **page** (integer) - Optional - 1-based page number (default 1).
- **page_size** (integer) - Optional - Items per page (1-100, default 20).

### Response
#### Success Response (200)
- **OpenLibraryBrandListResponse** (object) - A list of followed library brands.

#### Error Response (400)
- **errorMessage** (string) - Human-readable description of the validation failure.
```

--------------------------------

### GET /open/v1/ad-accounts/{account_id}/summary

Source: https://docs.tryatria.com/reference/get_ad_account_summary

Retrieves account-wide KPI totals for the requested window, aggregated by the ad platform.

```APIDOC
## GET /open/v1/ad-accounts/{account_id}/summary

### Description
Account-wide KPI total for the requested window. One row of metrics (spend / impressions / clicks / ctr / cpm / cpc / conversions / cost_per_conversion / roas), aggregated by the ad platform.

### Method
GET

### Endpoint
/open/v1/ad-accounts/{account_id}/summary

### Parameters
#### Path Parameters
- **account_id** (string) - Required - Internal Atria ad-account id (UUID; dashed or 32-char hex both parse). Obtain it from GET /open/v1/ad-accounts (items[].id).

#### Query Parameters
- **period** (string) - Optional - Date window. Defaults to last_7d.

### Response
#### Success Response (200)
- **account_id** (string) - Atria-internal ad-account UUID (no dashes).
- **platform** (string) - facebook or tiktok.
- **currency** (string) - ISO-4217 currency code for all monetary fields.
- **period** (string) - Requested date window.
- **date_start** (string) - Window start, ISO-8601 YYYY-MM-DD.
- **date_stop** (string) - Window stop, ISO-8601 YYYY-MM-DD.
```

--------------------------------

### GET /open/v1/ad-library/{ad_id}

Source: https://docs.tryatria.com/docs/long-form-video-research

Retrieves the complete record for a specific advertisement, including media assets, CTA, and copy.

```APIDOC
## GET /open/v1/ad-library/{ad_id}

### Description
Retrieves the complete record for a specific advertisement, including full media URLs, dimensions, dates, CTA, and copy.

### Method
GET

### Endpoint
https://api.tryatria.com/open/v1/ad-library/{ad_id}

### Parameters
#### Path Parameters
- **ad_id** (string) - Required - The unique identifier of the advertisement to retrieve.

### Response
#### Success Response (200)
- **data** (object) - The advertisement record containing brand_name, title, start_date, cta_text, link_url, body, videos, and images.
```

--------------------------------

### Search Active Facebook Ads

Source: https://docs.tryatria.com/docs/quick-start

Examples for querying the ad library using different programming environments. Ensure the ATRIA_API_KEY environment variable is set before execution.

```bash
curl -sS \
  -H "X-API-Key: $ATRIA_API_KEY" \
  "https://api.tryatria.com/open/v1/ad-library/search?platform=facebook&status=active&order=newest&page_size=10"
```

```python
import os
import requests

resp = requests.get(
    "https://api.tryatria.com/open/v1/ad-library/search",
    headers={"X-API-Key": os.environ["ATRIA_API_KEY"]},
    params={"platform": "facebook", "status": "active", "order": "newest", "page_size": 10},
    timeout=30,
)
resp.raise_for_status()
for ad in resp.json()["data"]["items"]:
    print(ad["id"], ad["brand_name"], ad["title"])
```

```node
const url = new URL("https://api.tryatria.com/open/v1/ad-library/search");
url.searchParams.set("platform", "facebook");
url.searchParams.set("status", "active");
url.searchParams.set("order", "newest");
url.searchParams.set("page_size", "10");

const resp = await fetch(url, { headers: { "X-API-Key": process.env.ATRIA_API_KEY } });
const { data } = await resp.json();
for (const ad of data.items) console.log(ad.id, ad.brand_name, ad.title);
```

--------------------------------

### GET /open/v1/image-generations/{generation_id}

Source: https://docs.tryatria.com/reference/get_image_generation

Poll the status of an image generation submission.

```APIDOC
## GET /open/v1/image-generations/{generation_id}

### Description
Poll the status of a `POST /open/v1/image-generations` submission. Returns the status of the generation and populates image IDs once the request fans out into per-image tasks.

### Method
GET

### Endpoint
/open/v1/image-generations/{generation_id}

### Parameters
#### Path Parameters
- **generation_id** (string) - Required - Image-generation UUID. Returned by `POST /open/v1/image-generations` as `data.generation_id`.

### Response
#### Success Response (200)
- **OpenImageGenerationResponse** (object) - The status and details of the image generation request.
```

--------------------------------

### Search for ads by keyword and date range

Source: https://docs.tryatria.com/docs/keyword-ads-search

Examples of querying the ad library using cURL, Python, and Node.js to retrieve ads matching specific criteria.

```bash
curl -sS \
  -H "X-API-Key: $ATRIA_API_KEY" \
  "https://api.tryatria.com/open/v1/ad-library/search?query=black+friday&language=en&start_date=2025-11-01&end_date=2025-11-30&order=most_active&page_size=50"
```

```python
import os
import requests

resp = requests.get(
    "https://api.tryatria.com/open/v1/ad-library/search",
    headers={"X-API-Key": os.environ["ATRIA_API_KEY"]},
    params={
        "query": "black friday",
        "language": "en",
        "start_date": "2025-11-01",
        "end_date": "2025-11-30",
        "order": "most_active",
        "page_size": 50,
    },
    timeout=30,
)
resp.raise_for_status()
for ad in resp.json()["data"]["items"]:
    print(f"[{(ad.get('cta_text') or ''):<15}] {ad['brand_name']:<25} — {ad['title']}")
```

```javascript
const url = new URL("https://api.tryatria.com/open/v1/ad-library/search");
url.searchParams.set("query", "black friday");
url.searchParams.set("language", "en");
url.searchParams.set("start_date", "2025-11-01");
url.searchParams.set("end_date", "2025-11-30");
url.searchParams.set("order", "most_active");
url.searchParams.set("page_size", "50");

const resp = await fetch(url, {
  headers: { "X-API-Key": process.env.ATRIA_API_KEY },
});
const { data } = await resp.json();
for (const ad of data.items) {
  console.log(
    `[${(ad.cta_text ?? "").padEnd(15)}] ${(ad.brand_name ?? "").padEnd(25)} — ${ad.title ?? ""}`,
  );
}
```

--------------------------------

### Atria MCP Tools Reference

Source: https://docs.tryatria.com/docs/available-tools

A comprehensive list of available tools exposed by the Atria MCP server, categorized by domain.

```APIDOC
## Ad Library
- `search_library_ads`: Search the public ad library.
- `get_library_ad`: Get a single library ad.
- `list_saved_library_ads`: List ads saved to your workspace.

## Brand Library
- `search_library_brands`: Search the brand library.
- `get_library_brand`: Get a single library brand.
- `list_library_brand_ads`: List ads for a brand.
- `list_followed_library_brands`: List brands your workspace follows.

## Boards
- `list_boards`: List your boards.
- `get_board`: Get a single board.
- `list_board_ads`: List ads inside a board.

## Ad Accounts
- `list_ad_accounts`: List connected ad accounts.
- `list_ad_account_ads`: List an ad account's ads by KPI.
- `get_ad_account_ad`: Get a single ad-account ad.
- `get_ad_account_summary`: Get an ad account's performance summary.
- `get_ad_account_video_transcript`: Get a cached ad-account video transcript.
- `transcribe_ad_account_video`: Transcribe an ad-account video.

## Owned Brands
- `list_owned_brands`: List brands your workspace owns.

## Image Generations
- `create_image_generation`: Start an image generation.
- `get_image_generation`: Get image-generation status.
- `get_image_generation_image`: Get a generated image.

## Diagnostics
- `ping`: Connection health check.
- `discover_apis`: List every tool.
```

--------------------------------

### Aggregate new ads into a daily digest

Source: https://docs.tryatria.com/docs/daily-new-ad-digest

Uses pagination and cursor-based fetching to retrieve new ads for all followed brands. Requires the ATRIA_API_KEY environment variable to be set.

```python
import datetime
import os
from typing import Iterator

import requests

API_KEY = os.environ["ATRIA_API_KEY"]
BASE = "https://api.tryatria.com/open/v1"


def followed_brands() -> Iterator[dict]:
    """Yield every brand the workspace follows, across pagination."""
    page = 1
    while True:
        resp = requests.get(
            f"{BASE}/brand-library/followed",
            headers={"X-API-Key": API_KEY},
            params={"page": page, "page_size": 100},
            timeout=30,
        )
        resp.raise_for_status()
        items = resp.json()["data"]["items"]
        yield from items
        if len(items) < 100:
            return
        page += 1


def fetch_new_ads(brand_id: str, since: str) -> Iterator[dict]:
    """Yield every ad for `brand_id` whose start_date >= since."""
    params = {"start_date": since, "order": "newest", "page_size": 50}
    cursor = None
    while True:
        if cursor:
            params["cursor"] = cursor
        resp = requests.get(
            f"{BASE}/brand-library/{brand_id}/ads",
            headers={"X-API-Key": API_KEY},
            params=params,
            timeout=30,
        )
        resp.raise_for_status()
        data = resp.json()["data"]
        yield from data["items"]
        cursor = data.get("cursor")
        if not cursor:
            return


def build_digest():
    yesterday = (datetime.date.today() - datetime.timedelta(days=1)).isoformat()
    digest = []  # list of (brand, ads) pairs
    for brand in followed_brands():
        ads = list(fetch_new_ads(brand["id"], since=yesterday))
        if ads:
            digest.append((brand, ads))
    return digest


if __name__ == "__main__":
    report = build_digest()
    if not report:
        print("No new ads since yesterday.")
    for brand, ads in report:
        print(f"\n{brand['name']} ({brand['id']}) — {len(ads)} new ad(s)")
        for ad in ads:
            print(f"  [{ad['display_format']}] {ad['title']}")
```

```javascript
const API_KEY = process.env.ATRIA_API_KEY;
const BASE = "https://api.tryatria.com/open/v1";

async function* followedBrands() {
  let page = 1;
  while (true) {
    const url = new URL(`${BASE}/brand-library/followed`);
    url.searchParams.set("page", String(page));
    url.searchParams.set("page_size", "100");

    const resp = await fetch(url, { headers: { "X-API-Key": API_KEY } });
    const items = (await resp.json()).data.items;
    for (const brand of items) yield brand;
    if (items.length < 100) return;
    page++;
  }
}

async function* fetchNewAds(brandId, since) {
  let cursor = null;
  while (true) {
    const url = new URL(`${BASE}/brand-library/${brandId}/ads`);
    url.searchParams.set("start_date", since);
    url.searchParams.set("order", "newest");
    url.searchParams.set("page_size", "50");
    if (cursor) url.searchParams.set("cursor", cursor);

    const resp = await fetch(url, { headers: { "X-API-Key": API_KEY } });
    const { data } = await resp.json();
    for (const ad of data.items) yield ad;
    cursor = data.cursor;
    if (!cursor) return;
  }
}

async function buildDigest() {
  const yesterday = new Date(Date.now() - 86_400_000).toISOString().slice(0, 10);
  const digest = []; // [{ brand, ads }, ...]
  for await (const brand of followedBrands()) {
    const ads = [];
    for await (const ad of fetchNewAds(brand.id, yesterday)) ads.push(ad);
    if (ads.length) digest.push({ brand, ads });
  }
  return digest;
}

const report = await buildDigest();
if (report.length === 0) console.log("No new ads since yesterday.");
for (const { brand, ads } of report) {
  console.log(`\n${brand.name} (${brand.id}) — ${ads.length} new ad(s)`);
  for (const ad of ads) console.log(`  [${ad.display_format}] ${ad.title}`);
}
```

--------------------------------

### GET /ads

Source: https://docs.tryatria.com/reference/search_library_ads

Retrieves a list of ads based on the provided query parameters.

```APIDOC
## GET /ads

### Description
Retrieves a list of advertisements from the library. Supports filtering by industry and video length, as well as sorting and pagination.

### Method
GET

### Endpoint
/ads

### Parameters
#### Query Parameters
- **industry** (array) - Optional - Filter by brand industry tag (e.g., apparel, sportswear).
- **video_length** (array) - Optional - Filter video ads by duration buckets (0-15, 15-30, 30-60, 60-120, 120-).
- **order** (string) - Optional - Sort order: newest (default), most_active, or best_match.
- **page_size** (integer) - Optional - Items per page (1-50, default 20).
- **cursor** (string) - Optional - Opaque pagination cursor from the previous response.

### Response
#### Success Response (200)
- **OpenLibraryAdListResponse** (object) - A list of ads matching the criteria.

#### Error Response (400)
- **errorMessage** (string) - Human-readable description of the validation failure.
```

--------------------------------

### GET /open/v1/saved_ads

Source: https://docs.tryatria.com/reference/list_saved_library_ads

Retrieves a list of saved ads based on the provided query parameters.

```APIDOC
## GET /open/v1/saved_ads

### Description
Retrieves a list of saved ads from the library. Supports filtering by boards and tags, sorting, and pagination.

### Method
GET

### Endpoint
/open/v1/saved_ads

### Parameters
#### Query Parameters
- **boards** (array) - Optional - Restrict to ads saved in the given board(s). Pass `board_id` values from `GET /open/v1/boards`.
- **tags** (array) - Optional - Restrict to ads tagged with any of the given tag names.
- **order** (string) - Optional - Sort order. Options: `saved_newest`, `saved_oldest`, `newest`, `oldest`, `most_active`. Default: `saved_newest`.
- **page_size** (integer) - Optional - Items per page (1-50, default 20).
- **cursor** (string) - Optional - Opaque pagination cursor from the previous response.

### Response
#### Success Response (200)
- **OpenSavedAdListResponse** (object) - The list of saved ads.

#### Error Response (400)
- **errorMessage** (string) - Human-readable description of the validation failure.
```

--------------------------------

### GET /brand-library/{id}/ads

Source: https://docs.tryatria.com/docs/daily-new-ad-digest

Retrieve ads for a specific brand using cursor-based pagination.

```APIDOC
## GET /brand-library/{id}/ads

### Description
Retrieves ads for a specific brand ID. Uses cursor-based pagination.

### Method
GET

### Endpoint
/brand-library/{id}/ads

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the brand.

#### Query Parameters
- **start_date** (string) - Optional - Inclusive start date for ad launch date filtering.
- **page_size** (integer) - Optional - Number of items per page (default 50, max 250).
```

--------------------------------

### GET /open/v1/boards

Source: https://docs.tryatria.com/reference

Retrieves a flat list of all boards in the calling workspace, ordered depth-first. Clients should reconstruct the tree structure using the parent_id field.

```APIDOC
## GET https://api.tryatria.com/open/v1/boards

### Description
List all boards belonging to the calling workspace as a flat array, depth-first ordered. Reconstruct the tree on the client by following parent_id links.

### Method
GET

### Endpoint
https://api.tryatria.com/open/v1/boards

### Parameters
#### Query Parameters
- **page** (integer) - Optional - 1-based page number (default 1).
- **page_size** (integer) - Optional - Items per page (1-100, default 20).

### Response
#### Success Response (200)
- Returns a list of board objects.

#### Error Response (400)
- Invalid request — a query parameter, path parameter, or body field failed validation.
```

--------------------------------

### GET /open/v1/image-generations/{generation_id}/images/{image_id}

Source: https://docs.tryatria.com/reference/get_image_generation_image

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.

```APIDOC
## GET /open/v1/image-generations/{generation_id}/images/{image_id}

### Description
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`.

### Method
GET

### Endpoint
/open/v1/image-generations/{generation_id}/images/{image_id}

### Parameters
#### Path Parameters
- **generation_id** (string) - Required - Parent image-generation UUID. Returned by `POST /open/v1/image-generations` as `data.generation_id`.
- **image_id** (string) - Required - Image UUID. Obtain it from the parent `OpenImageGeneration.image_ids` array.

### Response
#### Success Response (200)
- **OpenGeneratedImageResponse** (object) - Successful Response containing image details.
```

--------------------------------

### GET /ad_account/ads

Source: https://docs.tryatria.com/reference/list_ad_account_ads

Retrieves a list of ads for the specified ad account with optional sorting and pagination.

```APIDOC
## GET /ad_account/ads

### Description
Retrieves a list of ads for the specified ad account. Supports sorting by various metrics and pagination via limit parameters.

### Method
GET

### Endpoint
/ad_account/ads

### Parameters
#### Query Parameters
- **sort_order** (string) - Optional - Sort direction. Defaults to `desc`. Permitted values: `desc`, `asc`.
- **limit** (integer) - Optional - Max rows to return (1-50). Defaults to 10. Callers passing `limit > 10` should expect occasional `code=50001` errors.

### Response
#### Success Response (200)
- **response** (object) - Returns an `OpenOwnAdListResponse` object.

#### Error Response (400)
- **errorMessage** (string) - Human-readable description of the validation failure.
```

--------------------------------

### GET /brand-library/search

Source: https://docs.tryatria.com/docs/daily-new-ad-digest

Search for brands across public ad libraries by name using a keyword.

```APIDOC
## GET /brand-library/search

### Description
Look up brands by name across public ad libraries. The endpoint takes a keyword (case-insensitive substring) and returns matching brands.

### Method
GET

### Endpoint
https://api.tryatria.com/open/v1/brand-library/search

### Parameters
#### Query Parameters
- **keyword** (string) - Required - Case-insensitive substring to search for brands.
- **page_size** (integer) - Optional - Number of items per page.
```

--------------------------------

### Format and prompt Claude with ad data

Source: https://docs.tryatria.com/docs/analyze-a-board-with-claude

Uses the Anthropic SDK to format ad dictionaries into a text prompt for creative analysis.

```python
import os
import anthropic

client = anthropic.Anthropic(api_key=os.environ["ANTHROPIC_API_KEY"])

def fmt(ad: dict) -> str:
    saved = ad.get("saved_details") or {}
    return (
        f"- [{ad['display_format']}] {ad['brand_name']} — {ad['title']}\n"
        f"  copy:   {ad.get('body') or ''}\n"
        f"  cta:    {ad.get('cta_text') or ''} → {ad.get('link_url') or ''}\n"
        f"  tags:   {', '.join(saved.get('tags') or [])}\n"
        f"  saved:  {saved.get('saved_at')}"
    )

prompt = (
    "Below are ads my team has saved for inspiration. "
    "Identify the top 3 creative themes and the CTA patterns each theme uses. "
    "Be specific and quote ad copy where helpful.\n\n"
    + "\n\n".join(fmt(ad) for ad in ads)
)

resp = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=2048,
    messages=[{"role": "user", "content": prompt}],
)
print(resp.content[0].text)
```

--------------------------------

### GET /ads

Source: https://docs.tryatria.com/reference/list_board_ads

Retrieves a paginated list of board ads based on provided query filters.

```APIDOC
## GET /ads

### Description
Retrieves a list of advertisements from a board. Supports filtering by status and ordering, with pagination via cursor.

### Method
GET

### Endpoint
/ads

### Parameters
#### Query Parameters
- **status** (string) - Optional - Filter by ad status.
- **order** (string) - Optional - Sort order (default: newest). Options: newest, oldest.
- **page_size** (integer) - Optional - Items per page (1-50, default 20).
- **cursor** (string) - Optional - Opaque pagination cursor from the previous response.

### Response
#### Success Response (200)
- **OpenLibraryAdListResponse** (object) - The list of ads matching the criteria.

#### Error Response (400)
- **errorMessage** (string) - Human-readable description of the validation failure.
```

--------------------------------

### POST /open/v1/image-generations

Source: https://docs.tryatria.com/reference/create_image_generation

Submit a new image generation request based on a creative brief.

```APIDOC
## POST /open/v1/image-generations

### Description
Submit an image-generation request. The prompt is treated as a creative brief which Atria expands into multiple distinct concept variants.

### Method
POST

### Endpoint
/open/v1/image-generations

### Request Body
- **prompt** (string) - Required - The creative brief describing intent, audience, mood, and visual hints.
- **size** (integer) - Required - The number of distinct concept variants to generate.
- **brand_id** (string) - Required - The workspace-owned brand ID used to ground the brief.
- **idempotency_key** (string) - Required - A stable UUID used to deduplicate retries.

### Response
#### Success Response (202)
- **generation_id** (string) - The unique identifier for the generation request.
- **image_ids** (array) - Initially empty list of image identifiers.

### Error Handling
- **40001**: Workspace context missing.
- **40401**: Unknown or cross-workspace brand_id.
- **50001**: Upstream image-gen service unavailable or request rejected.
```

--------------------------------

### GET /open/v1/ad-library/search

Source: https://docs.tryatria.com/docs/keyword-ads-search

Searches the ad library for ads matching a specific keyword, language, and date range.

```APIDOC
## GET /open/v1/ad-library/search

### Description
Searches for ads whose copy, title, or brand name matches a given keyword within a specified date window.

### Method
GET

### Endpoint
https://api.tryatria.com/open/v1/ad-library/search

### Parameters
#### Query Parameters
- **query** (string) - Required - The free-text search term to match against ad title, body, or brand name.
- **language** (string) - Optional - ISO 639-1 code to filter by detected ad language.
- **start_date** (string) - Optional - Inclusive lower bound on the ad's launch date (YYYY-MM-DD).
- **end_date** (string) - Optional - Inclusive upper bound on the ad's launch date (YYYY-MM-DD).
- **order** (string) - Optional - Sorting criteria, such as 'most_active'.
- **page_size** (integer) - Optional - Number of results to return per page.

### Request Example
GET https://api.tryatria.com/open/v1/ad-library/search?query=black+friday&language=en&start_date=2025-11-01&end_date=2025-11-30&order=most_active&page_size=50
```
Tokens:
Raw