> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ancha.io/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> These docs describe the Ancha CLI, npm package @ancha-labs/cli version 0.1.4, and the hosted workspace at app.ancha.io. Coding agents should start at https://docs.ancha.io/coding-agents. Run the CLI as `ancha` after `npm install -g @ancha-labs/cli`, or as `npx -y @ancha-labs/cli@0.1.4` without installing. Pass --json for machine-readable output, or set ANCHA_JSON=1. Every command ends with a `next:` line naming the next command. Exit codes: 0 pass, 1 a check failed or a comparison regressed, 2 usage, config or authentication error, 3 infrastructure error, 4 unimplemented endpoint with --strict.

# ChatGPT Ads

> A stateful replica of the ChatGPT Ads Advertiser API v1: the ad account, campaigns, ad groups, ads with creative review, status changes and delivery insights.

The ChatGPT Ads replica implements 26 endpoints of the Advertiser API v1. It is the advertising API, not the OpenAI model API. Its key is `chatgpt-ads`.

## Connect

| Variable | Value |
| - | - |
| `OPENAI_ADS_API_URL` | Base URL. Paths start with `/v1/`. |
| `OPENAI_ADS_API_KEY` | Fake advertiser key for one ad account. Send `Authorization: Bearer <key>`. It is not an OpenAI model key. |

```js Node theme={null}
const response = await fetch(process.env.OPENAI_ADS_API_URL + '/v1/campaigns', {headers:{Authorization:'Bearer '+process.env.OPENAI_ADS_API_KEY}});
const campaigns = await response.json();
```

This is what `ancha connect chatgpt-ads --lang ts` prints. Creates accept an `idempotency-key` header.

## Endpoints

All endpoints are partial. Unsupported methods, routes and fields return HTTP 501 with `x-ancha-gap: 1`.

### Ad account

| Method | Path |
| - | - |
| `GET` | `/v1/ad_account` |

### Campaigns

| Method | Path |
| - | - |
| `GET` | `/v1/campaigns` |
| `POST` | `/v1/campaigns` |
| `GET` | `/v1/campaigns/:id` |
| `POST` | `/v1/campaigns/:id` |
| `POST` | `/v1/campaigns/:id/activate` |
| `POST` | `/v1/campaigns/:id/pause` |
| `POST` | `/v1/campaigns/:id/archive` |

### Ad groups

| Method | Path |
| - | - |
| `GET` | `/v1/ad_groups` |
| `POST` | `/v1/ad_groups` |
| `GET` | `/v1/ad_groups/:id` |
| `POST` | `/v1/ad_groups/:id` |
| `POST` | `/v1/ad_groups/:id/activate` |
| `POST` | `/v1/ad_groups/:id/pause` |
| `POST` | `/v1/ad_groups/:id/archive` |

### Ads

| Method | Path |
| - | - |
| `GET` | `/v1/ads` |
| `POST` | `/v1/ads` |
| `GET` | `/v1/ads/:id` |
| `POST` | `/v1/ads/:id` |
| `POST` | `/v1/ads/:id/activate` |
| `POST` | `/v1/ads/:id/pause` |
| `POST` | `/v1/ads/:id/archive` |

### Insights

| Method | Path |
| - | - |
| `GET` | `/v1/ad_account/insights` |
| `GET` | `/v1/campaigns/:id/insights` |
| `GET` | `/v1/ad_groups/:id/insights` |
| `GET` | `/v1/ads/:id/insights` |

## Behavior

* **Lists** are scoped to the account, with an exact name filter and forward and backward ID cursors.
* **Updates** replace budgets; archiving is permanent and archived objects cannot change.
* **Review.** New ads are reviewed by a local rule and approved 60 simulated seconds after creation.
* **Insights** are historical hourly delivery, grouped by none or by day in the account's time zone.
* **Rate limits.** 600 requests a minute per endpoint and 1,200 per account, in simulated time.

## Starter data

The `chatgpt-ads-starter` dataset is the ad account **Acme** (`adacct_acme`, USD, America/Los\_Angeles).

| Record | ID | Detail |
| - | - | - |
| Campaign | `cmpn_acme_pilot` | "Ridgeway Robotics Q4 pilot", active, 50 USD a day. |
| Ad group | `adgrp_acme_revenue` | "Revenue operations", active. |
| Ad | `ad_acme_reporting` | "Pipeline clarity", active, approved. |
| Ad | `ad_acme_pending` | "Pilot invitation", active, in review. |

Hourly insights exist for "Pipeline clarity", for example 1,200 impressions and 36 clicks in one hour. A second account, Helix Manufacturing (`adacct_helix`), with a paused campaign, exists to test that the key stays inside its own account.

## Checks

ChatGPT Ads has no state checks. Use trace checks, for example `{ called: "POST /v1/campaigns/cmpn_acme_pilot/pause" }`.

## Limits

* Single-image chat cards only; no file uploads.
* No auction, spend, destination crawling or conversion attribution.


## Related topics

- [Worlds](https://docs.ancha.io/concepts/worlds.md)
- [Tools](https://docs.ancha.io/tools/overview.md)
- [Introduction](https://docs.ancha.io/index.md)
- [Changelog](https://docs.ancha.io/changelog.md)
- [Environment variables](https://docs.ancha.io/reference/environment-variables.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.