> For the complete documentation index, see [llms.txt](https://docs.avastudio.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.avastudio.com/api-and-mcp/quickstart.md).

# Quickstart

Make your first REST API call in about two minutes. For application code, use the [JavaScript and TypeScript SDK](https://docs.avastudio.com/api-and-mcp/sdk.md); for terminal commands, use the [CLI](https://docs.avastudio.com/api-and-mcp/cli.md). To use Ava from ChatGPT or Claude, skip to [Connect your AI app](https://docs.avastudio.com/api-and-mcp/connect.md): no key needed.

#### Choose what Ava should plan

* **A campaign:** reuse or create the campaign with its brief/objectives, then `plan_get` → `plan_run` → `concept_list` → approval → `creative_produce`. Keep the same campaign id. Creating a campaign alone does not run its planner.
* **One complete video:** `project_create` → `project_ask` uses Studio's content-planning agent for original videos and clones. Plan with `generate:false, media_credit_limit:0` (AI usage is charged), then continue in the same project with approved generation and export.
* **Written briefs only:** `draft_briefs` saves into the separate “From your agent” draft container. It does not plan the selected campaign, and its briefs cannot be produced with `creative_produce`.

The REST walkthrough below demonstrates standalone research and written briefs. Campaign planning and media generation need their corresponding permissions and spending approval; the walkthrough's key and budget cover only its listed calls.

#### 1. Create an API key

No paid Ava plan is needed. The account check is free; research and drafting spend your available credits, including any active [starter credits](https://docs.avastudio.com/api-and-mcp/credits-and-pricing.md#free-accounts-and-starter-credits).

1. In Ava Studio, open **Settings > Developers**.
2. Click **Create key** and give it a name (for example "My script"). Keys start with **Read only**. Choose **Custom** and enable **Research** and **Write drafts** for this walkthrough. Also enable **Edit brands** if you need to create a brand.
3. Optionally set a monthly credit limit for the key, for example 250 credits for this walkthrough.
4. Copy the key. It starts with `ava_live_` and is shown only once.

Keep the key secret: anyone who has it can spend your credits. Store it in an environment variable rather than in your code:

```bash
read -rs AVA_API_KEY && export AVA_API_KEY   # paste the key, press Enter
```

#### 2. Check the key

```bash
curl -X POST https://mcp.avastudio.com/v1/whoami \
  -H "x-api-key: $AVA_API_KEY"
```

You get your account, credit balance and brands:

```json
{
  "user_id": "…",
  "email": "you@example.com",
  "credits_balance": 2450,
  "brands": [{ "brand_id": "…", "name": "Your brand", "is_primary": true }],
  "next_steps": ["…"]
}
```

If `brands` is empty, save your supplied details without a website using `brand_create { "profile": { "name": "Acme", "brief": "Coffee for offices" } }` (free; only the name is required). A website is optional inside `profile`. Or use `brand_create { "url": "https://example.com" }` for website research (40 credits, eligible first-brand allowance applies).

Both return a `job_id`: poll `jobs_get` until `succeeded`, then use the saved `result.brand_id`. There is no separate save step. `brand_update` saves later edits immediately; `brand_export` only makes a portable copy.

#### 3. Ask for research

Every tool is a `POST` to `/v1/<tool>` with its input as JSON:

```bash
curl -X POST https://mcp.avastudio.com/v1/research_trends \
  -H "x-api-key: $AVA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"niche": "protein snacks", "limit": 5}'
```

The answer lists what is trending, with example videos and `credits_charged: 1`.

#### 4. Run a longer task

Drafting briefs takes a little while, so `draft_briefs` returns a job instead of waiting:

```bash
curl -X POST https://mcp.avastudio.com/v1/draft_briefs \
  -H "x-api-key: $AVA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"brand_id": "YOUR_BRAND_ID", "count": 2, "idempotency_key": "first-briefs-001"}'
```

```json
{ "job_id": "…", "kind": "draft_briefs", "status": "queued", "credits_held": 100 }
```

`credits_held` is the most the job can cost. You are charged what it actually uses (typically about 25 credits per brief) and the rest is released.

Check it every few seconds until `status` is `succeeded` or `failed`:

```bash
curl -X POST https://mcp.avastudio.com/v1/jobs_get \
  -H "x-api-key: $AVA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"job_id": "JOB_ID"}'
```

When it succeeds, `result` holds the briefs, and they also appear in Ava Studio in your brand's "From your agent" campaign.

The `idempotency_key` makes retries safe: sending the same request again returns the same job instead of drafting (and charging) twice. See [Jobs, retries and errors](https://docs.avastudio.com/api-and-mcp/jobs-retries-and-errors.md).

#### Next

* Use the [SDK](https://docs.avastudio.com/api-and-mcp/sdk.md) for typed calls and automatic job polling, or the [CLI](https://docs.avastudio.com/api-and-mcp/cli.md) for terminal commands and scripts.
* [Connect your AI app](https://docs.avastudio.com/api-and-mcp/connect.md) to let an assistant use all the tools for you.
* Browse the [tool reference](https://docs.avastudio.com/api-and-mcp/tools.md).
* `GET https://mcp.avastudio.com/v1/tools` lists the tools your key can call, with their input schemas.
