# AdsCreator — Full API Reference

> AI-powered ad creative generator. Paste any URL, extract brand DNA, and generate on-brand ad creatives in seconds.

## Authentication

All API requests require a Bearer token in the Authorization header:

```
Authorization: Bearer ac_sk_your_api_key_here
```

API keys can be created in the AdsCreator dashboard at Settings > API Keys.

---

## Endpoints

### POST /api/brands — Extract Brand from URL

Extract brand identity (colors, logos, fonts, tone) from any website URL. Returns cached data if the brand was previously imported.

**Request body:**
```json
{
  "domain": "stripe.com"
}
```

**Response:**
```json
{
  "brand": {
    "id": "abc123",
    "domain": "stripe.com",
    "name": "Stripe",
    "description": "Financial infrastructure for the internet",
    "slogan": "...",
    "colors": [{"hex": "#635bff", "type": "primary"}],
    "logos": [{"url": "https://...", "mode": "light", "type": "logo"}],
    "fonts": [{"font": "Inter", "uses": "body"}]
  },
  "cached": false
}
```

### GET /api/brands — List Brands

Returns all brands in your organization.

**Response:**
```json
{
  "brands": [
    {
      "id": "abc123",
      "domain": "stripe.com",
      "name": "Stripe",
      "description": "...",
      "colors": [...],
      "logos": [...],
      "created_at": "2024-01-15T10:30:00Z"
    }
  ]
}
```

### GET /api/brands/{id} — Get Brand Details

Returns full brand details including all extracted data.

### POST /api/generate — Generate Ad Creatives

Generate AI ad creatives for a brand. Returns an NDJSON stream by default, or a JSON response with `?sync=true`.

**Credits:** count x number of formats (e.g., 3 ads x 2 formats = 6 credits)

**Request body:**
```json
{
  "brandId": "abc123",
  "count": 3,
  "formats": ["square", "landscape"],
  "objective": "leads",
  "targetNetworks": ["meta", "google"],
  "adStyle": "text-overlay",
  "audience": "SaaS founders aged 25-45",
  "product": "AI ad generator",
  "offer": "Free trial, no credit card required",
  "tone": "confident and direct",
  "extraInstructions": "Focus on speed and ease of use"
}
```

**Parameters:**

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| brandId | string | Yes | The brand ID from /api/brands |
| count | integer | No | Number of ad concepts (1-10, default: 3) |
| formats | string[] | No | Output formats. Values: `square`, `landscape`, `portrait`, `portrait_meta`, `story`. Default: `["square"]` |
| objective | string | No | Campaign objective. Values: `awareness`, `leads`, `launch`, `sales`, `retargeting`, `event`. Default: `awareness` |
| targetNetworks | string[] | No | Ad networks. Values: `meta`, `google`, `linkedin`, `x`, `tiktok`. Default: `["meta"]` |
| adStyle | string | No | Creative style. Values: `product-hero`, `text-overlay`, `offer-promo`, `testimonial-proof`, `feature-explainer`, `lifestyle-scene`, `stat-callout`. Default: `text-overlay` |
| templateProfile | string | No | Layout template. Values: `meta-direct-response`, `google-display-offer`, `canva-promo`, `competitor-refresh`. Default: `meta-direct-response` |
| audience | string | No | Target audience description |
| product | string | No | Product or service being advertised |
| offer | string | No | Promotional offer or value proposition |
| tone | string | No | Desired tone of voice |
| campaignBrief | string | No | Campaign brief or goal description |
| campaignAngle | string | No | Specific campaign angle or hook |
| keyPoints | string[] | No | Key points to include (max 6) |
| extraInstructions | string | No | Additional creative direction |
| useBrandColors | boolean | No | Whether to use brand colors (default: true) |
| customColors | string[] | No | Custom hex colors to override brand colors (max 5) |
| userReferenceImageUrls | string[] | No | Reference image URLs for style guidance (max 4) |

**Sync response** (`?sync=true`):
```json
{
  "ads": [
    {
      "id": "ad_xyz",
      "headline": "Create Ads in Seconds",
      "subheadline": "No design skills needed",
      "body_copy": "Paste any URL and get...",
      "cta": "Start Free Trial",
      "tone": "confident",
      "format": "square",
      "image_url": "https://fal.media/...",
      "status": "complete",
      "created_at": "2024-01-15T10:30:00Z"
    }
  ],
  "completed": 3,
  "total": 3
}
```

**Streaming response** (default, NDJSON):

Each line is a JSON object with an `event` field:

| Event | Description |
|-------|-------------|
| `start` | Generation started, includes total count |
| `status` | Progress update with label, detail, and progress (0-1) |
| `ad_created` | Ad concept created, image generation starting |
| `ad_complete` | Ad fully rendered with image_url |
| `ad_failed` | Ad generation failed (credit refunded) |
| `done` | All ads complete, includes full `ads` array |
| `error` | Fatal error, includes message |

### GET /api/creatives — List Created Ads

Returns paginated list of completed ad creatives.

**Query parameters:**

| Parameter | Type | Description |
|-----------|------|-------------|
| search | string | Search by headline or brand name |
| cursor | string | Pagination cursor (created_at of last item) |
| limit | integer | Results per page (default: 24, max: 100) |

**Response:**
```json
{
  "creatives": [
    {
      "id": "ad_xyz",
      "headline": "Create Ads in Seconds",
      "body_copy": "...",
      "cta": "Start Free Trial",
      "tone": "confident",
      "format": "square",
      "image_url": "https://fal.media/...",
      "status": "complete",
      "created_at": "2024-01-15T10:30:00Z",
      "brand_id": "abc123",
      "brand_name": "AdsCreator",
      "brand_domain": "adscreator.com"
    }
  ],
  "nextCursor": "2024-01-14T10:30:00Z",
  "total": 42
}
```

### DELETE /api/ads/{id} — Delete Ad

Delete an ad creative by ID.

**Response:**
```json
{ "success": true }
```

### POST /api/ads/{id}/edit — Edit Ad Creative

Edit an existing ad with a text prompt. Costs 1 credit.

**Request body:**
```json
{
  "prompt": "Change the headline to emphasize speed"
}
```

### POST /api/ads/{id}/resize — Resize Ad

Resize an ad to different formats. Costs 1 credit per new format.

**Request body:**
```json
{
  "formats": ["landscape", "story"]
}
```

### GET /api/credits — Check Credit Balance

**Response:**
```json
{
  "remaining": 47,
  "used": 53,
  "total": 100,
  "isTrialing": false,
  "fullPlanCredits": null
}
```

---

## Workflow Example

Here is a complete workflow for generating ad creatives:

```bash
# 1. Extract brand identity from a URL
curl -X POST https://www.adscreator.com/api/brands \
  -H "Authorization: Bearer ac_sk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"domain": "stripe.com"}'

# 2. Generate 3 ad creatives (sync mode for simple JSON response)
curl -X POST "https://www.adscreator.com/api/generate?sync=true" \
  -H "Authorization: Bearer ac_sk_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "brandId": "BRAND_ID_FROM_STEP_1",
    "count": 3,
    "formats": ["square", "landscape"],
    "objective": "leads",
    "targetNetworks": ["meta", "linkedin"],
    "adStyle": "text-overlay",
    "audience": "B2B SaaS decision makers"
  }'

# 3. List all your creatives
curl https://www.adscreator.com/api/creatives \
  -H "Authorization: Bearer ac_sk_your_key"

# 4. Check remaining credits
curl https://www.adscreator.com/api/credits \
  -H "Authorization: Bearer ac_sk_your_key"
```

## Error Codes

| Status | Meaning |
|--------|---------|
| 400 | Bad request — missing or invalid parameters |
| 401 | Unauthorized — missing or invalid API key |
| 402 | Insufficient credits — purchase more or upgrade plan |
| 404 | Resource not found |
| 500 | Server error |

## Rate Limits

API requests are rate-limited per organization. If you receive a 429 response, wait and retry.

## Support

For API support, contact us at the AdsCreator dashboard help page.