Growth Chicken / API Docs

API Docs

Manage projects and reusable audiences from agents, internal tools, and automation. Every request is authenticated with a bearer token and returns JSON.

Get started

The examples below are ready to read with placeholder values. Sign in to generate a real key in one click and have it filled in automatically.

Sign in to create a key Create account

Set it up with your coding agent

Paste this into Claude Code (or any coding agent) - no editing needed. It asks you for your product URL, walks you through account and key setup, then creates a project and generates a first image and video ad.

Paste into your coding agent 
Set up Growth Chicken to generate ads for my product. Walk me through it, doing each step for me where you can and pausing when you need something only I can provide.

Growth Chicken turns a product page into on-brand image and video ads through a REST API at https://trygrowthchicken.com. Run this setup interactively: ask me for what you need one thing at a time and wait for my answer before moving on.

1. Ask me for my product URL (the page my ads should be based on). Wait for my reply.
2. Set up my account: open https://trygrowthchicken.com/sign_up, where I'll enter my email to register. Then tell me to check my email and click the confirmation link to finish signing up, and wait until I confirm I've done it.
3. Ask me for an API key - I need to be signed in, then generate one at https://trygrowthchicken.com/docs/api and paste it back to you. Wait for it. Send it on every API request as the header "Authorization: Bearer <my key>".
4. Once you have my product URL and key, finish the rest in one go:
   a. Read the API reference at https://trygrowthchicken.com/docs/openapi.json for the exact endpoints and request bodies.
   b. Create a project from my product page: POST https://trygrowthchicken.com/api/v1/projects/from_url with body {"url": "<my product URL>"}. Save the project "slug" from the response.
   c. Generate two sample ads for that project. Generation is async: each create returns HTTP 202 with a "poll_url"; GET it until "status" is "ready".
      - Image ad: POST https://trygrowthchicken.com/api/v1/projects/<slug>/ads with {"ad": {"requested_output": "image", "placements": ["square"]}}
      - Video ad: POST https://trygrowthchicken.com/api/v1/projects/<slug>/ads with {"ad": {"requested_output": "video", "placements": ["instagram_story"]}}
   d. When each ad is "ready", download its deliverable from the response "files" list: "asset_url" is the .png (image) or .mp4 (video). The first request may return 202 while the asset renders, so retry until 200; "document_url" is the self-contained HTML version and is always available as a fallback.
   e. Show me both ads.

Authentication

Send your key as a bearer token in the Authorization header. Requests without a valid key return 401.

Base URL 
https://trygrowthchicken.com
Authorization header 
Authorization: Bearer $GROWTH_CHICKEN_API_TOKEN

Highlighted values like YOUR_PROJECT_SLUG are placeholders — swap in your own.

Endpoints

Projects

GET /projects

List projects

curl 
curl https://trygrowthchicken.com/api/v1/projects \
  -H "Authorization: Bearer $GROWTH_CHICKEN_API_TOKEN"
Example response
200 OK 
{
  "projects": [
    {
      "id": "00000000-0000-0000-0000-000000000001",
      "slug": "launchpad",
      "name": "LaunchPad",
      "description": "A complete project brief.",
      "tagline": "Launch creative faster.",
      "avatar_url": "/images/avatars/1.png",
      "status": "active",
      "source_url": "https://example.com",
      "brand_kit": {
        "colors": [
          "#111111"
        ],
        "font_preferences": {
          "direction": "Clean sans."
        },
        "logos": [],
        "style_notes": "Bright."
      },
      "created_at": "2026-05-25T12:00:00Z",
      "updated_at": "2026-05-25T12:00:00Z",
      "assets_count": 0,
      "creatives_count": 0
    }
  ]
}
POST /projects

Create project

Request body 
{
  "project": {
    "name": "LaunchPad",
    "description": "A detailed project brief with audience, offer, proof points, visual direction, tone, constraints, claims, channel context, product benefits, objections, conversion goal, and enough substance for generated creative work.",
    "tagline": "Launch creative faster.",
    "source_url": "https://example.com",
    "brand_kit": {
      "colors": [
        "#111111",
        "#ffcc00"
      ],
      "font_preferences": {
        "direction": "Clean geometric sans with expressive display accents."
      },
      "style_notes": "Bright, direct, and product-led."
    }
  }
}
curl 
curl -X POST https://trygrowthchicken.com/api/v1/projects \
  -H "Authorization: Bearer $GROWTH_CHICKEN_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"project":{"name":"LaunchPad","description":"A detailed project brief with audience, offer, proof points, visual direction, tone, constraints, claims, channel context, product benefits, objections, conversion goal, and enough substance for generated creative work.","tagline":"Launch creative faster.","source_url":"https://example.com","brand_kit":{"colors":["#111111","#ffcc00"],"font_preferences":{"direction":"Clean geometric sans with expressive display accents."},"style_notes":"Bright, direct, and product-led."}}}'
Example response
200 OK 
{
  "project": {
    "id": "00000000-0000-0000-0000-000000000001",
    "slug": "launchpad",
    "name": "LaunchPad",
    "description": "A complete project brief.",
    "tagline": "Launch creative faster.",
    "avatar_url": "/images/avatars/1.png",
    "status": "active",
    "source_url": "https://example.com",
    "brand_kit": {
      "colors": [
        "#111111"
      ],
      "font_preferences": {
        "direction": "Clean sans."
      },
      "logos": [],
      "style_notes": "Bright."
    },
    "created_at": "2026-05-25T12:00:00Z",
    "updated_at": "2026-05-25T12:00:00Z",
    "assets_count": 0,
    "creatives_count": 0
  }
}
POST /projects/from_url

Create project from a URL

Request body 
{
  "url": "https://example.com"
}
curl 
curl -X POST https://trygrowthchicken.com/api/v1/projects/from_url \
  -H "Authorization: Bearer $GROWTH_CHICKEN_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com"}'
Example response
200 OK 
{
  "project": {
    "id": "00000000-0000-0000-0000-000000000001",
    "slug": "launchpad",
    "name": "LaunchPad",
    "description": "A complete project brief.",
    "tagline": "Launch creative faster.",
    "avatar_url": "/images/avatars/1.png",
    "status": "active",
    "source_url": "https://example.com",
    "brand_kit": {
      "colors": [
        "#111111"
      ],
      "font_preferences": {
        "direction": "Clean sans."
      },
      "logos": [],
      "style_notes": "Bright."
    },
    "created_at": "2026-05-25T12:00:00Z",
    "updated_at": "2026-05-25T12:00:00Z",
    "assets_count": 0,
    "creatives_count": 0
  }
}
GET /projects/{id}

Get project

curl 
curl https://trygrowthchicken.com/api/v1/projects/YOUR_PROJECT_SLUG \
  -H "Authorization: Bearer $GROWTH_CHICKEN_API_TOKEN"
Example response
200 OK 
{
  "project": {
    "id": "00000000-0000-0000-0000-000000000001",
    "slug": "launchpad",
    "name": "LaunchPad",
    "description": "A complete project brief.",
    "tagline": "Launch creative faster.",
    "avatar_url": "/images/avatars/1.png",
    "status": "active",
    "source_url": "https://example.com",
    "brand_kit": {
      "colors": [
        "#111111"
      ],
      "font_preferences": {
        "direction": "Clean sans."
      },
      "logos": [],
      "style_notes": "Bright."
    },
    "created_at": "2026-05-25T12:00:00Z",
    "updated_at": "2026-05-25T12:00:00Z",
    "assets_count": 0,
    "creatives_count": 0
  }
}
PATCH /projects/{id}

Update project

Request body 
{
  "project": {
    "name": "LaunchPad",
    "description": "A detailed project brief with audience, offer, proof points, visual direction, tone, constraints, claims, channel context, product benefits, objections, conversion goal, and enough substance for generated creative work.",
    "tagline": "Launch creative faster.",
    "source_url": "https://example.com",
    "brand_kit": {
      "colors": [
        "#111111",
        "#ffcc00"
      ],
      "font_preferences": {
        "direction": "Clean geometric sans with expressive display accents."
      },
      "style_notes": "Bright, direct, and product-led."
    }
  }
}
curl 
curl -X PATCH https://trygrowthchicken.com/api/v1/projects/YOUR_PROJECT_SLUG \
  -H "Authorization: Bearer $GROWTH_CHICKEN_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"project":{"name":"LaunchPad","description":"A detailed project brief with audience, offer, proof points, visual direction, tone, constraints, claims, channel context, product benefits, objections, conversion goal, and enough substance for generated creative work.","tagline":"Launch creative faster.","source_url":"https://example.com","brand_kit":{"colors":["#111111","#ffcc00"],"font_preferences":{"direction":"Clean geometric sans with expressive display accents."},"style_notes":"Bright, direct, and product-led."}}}'
Example response
200 OK 
{
  "project": {
    "id": "00000000-0000-0000-0000-000000000001",
    "slug": "launchpad",
    "name": "LaunchPad",
    "description": "A complete project brief.",
    "tagline": "Launch creative faster.",
    "avatar_url": "/images/avatars/1.png",
    "status": "active",
    "source_url": "https://example.com",
    "brand_kit": {
      "colors": [
        "#111111"
      ],
      "font_preferences": {
        "direction": "Clean sans."
      },
      "logos": [],
      "style_notes": "Bright."
    },
    "created_at": "2026-05-25T12:00:00Z",
    "updated_at": "2026-05-25T12:00:00Z",
    "assets_count": 0,
    "creatives_count": 0
  }
}
DELETE /projects/{id}

Delete project

curl 
curl -X DELETE https://trygrowthchicken.com/api/v1/projects/YOUR_PROJECT_SLUG \
  -H "Authorization: Bearer $GROWTH_CHICKEN_API_TOKEN"
GET /projects/{project_id}/ads

List ads

curl 
curl https://trygrowthchicken.com/api/v1/projects/YOUR_PROJECT_SLUG/ads \
  -H "Authorization: Bearer $GROWTH_CHICKEN_API_TOKEN"
Example response
200 OK 
{
  "ads": [
    {
      "id": "00000000-0000-0000-0000-000000000401",
      "slug": "summer-sale",
      "project_id": "00000000-0000-0000-0000-000000000001",
      "name": "LaunchPad - Ship campaigns in minutes",
      "status": "generating",
      "ready": false,
      "generating": true,
      "failed": false,
      "requested_output": "video",
      "video_style": "live_scene",
      "video_style_label": "Live scene",
      "audience_id": "00000000-0000-0000-0000-000000000101",
      "platform_aspect": "9:16",
      "placements": [
        "instagram_story",
        "square"
      ],
      "token_cost": 163,
      "created_at": "2026-06-20T12:00:00Z",
      "updated_at": "2026-06-20T12:00:00Z",
      "url": "http://localhost:3000/projects/launchpad/creative_compositions/summer-sale",
      "poll_url": "http://localhost:3000/api/v1/projects/launchpad/ads/summer-sale",
      "files": [
        {
          "placement": "square",
          "label": "Square (1:1)",
          "width": 1080,
          "height": 1080,
          "document_url": "http://localhost:3000/api/v1/projects/launchpad/ads/summer-sale/file.html?placement=square",
          "asset_url": "http://localhost:3000/api/v1/projects/launchpad/ads/summer-sale/file.mp4?placement=square"
        }
      ],
      "snapshots": []
    }
  ]
}
POST /projects/{project_id}/ads

Generate an ad

Request body 
{
  "ad": {
    "requested_output": "video",
    "video_style": "live_scene",
    "prompt": "Bold launch ad highlighting the new dashboard.",
    "copy": "Ship campaigns in minutes",
    "cta": "Start free",
    "audience_id": "00000000-0000-0000-0000-000000000101",
    "placements": [
      "instagram_story",
      "square"
    ],
    "variant_count": 1
  }
}
curl 
curl -X POST https://trygrowthchicken.com/api/v1/projects/YOUR_PROJECT_SLUG/ads \
  -H "Authorization: Bearer $GROWTH_CHICKEN_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"ad":{"requested_output":"video","video_style":"live_scene","prompt":"Bold launch ad highlighting the new dashboard.","copy":"Ship campaigns in minutes","cta":"Start free","audience_id":"00000000-0000-0000-0000-000000000101","placements":["instagram_story","square"],"variant_count":1}}'
Example response
200 OK 
{
  "ad": {
    "id": "00000000-0000-0000-0000-000000000401",
    "slug": "summer-sale",
    "project_id": "00000000-0000-0000-0000-000000000001",
    "name": "LaunchPad - Ship campaigns in minutes",
    "status": "generating",
    "ready": false,
    "generating": true,
    "failed": false,
    "requested_output": "video",
    "video_style": "live_scene",
    "video_style_label": "Live scene",
    "audience_id": "00000000-0000-0000-0000-000000000101",
    "platform_aspect": "9:16",
    "placements": [
      "instagram_story",
      "square"
    ],
    "token_cost": 163,
    "created_at": "2026-06-20T12:00:00Z",
    "updated_at": "2026-06-20T12:00:00Z",
    "url": "http://localhost:3000/projects/launchpad/creative_compositions/summer-sale",
    "poll_url": "http://localhost:3000/api/v1/projects/launchpad/ads/summer-sale",
    "files": [
      {
        "placement": "square",
        "label": "Square (1:1)",
        "width": 1080,
        "height": 1080,
        "document_url": "http://localhost:3000/api/v1/projects/launchpad/ads/summer-sale/file.html?placement=square",
        "asset_url": "http://localhost:3000/api/v1/projects/launchpad/ads/summer-sale/file.mp4?placement=square"
      }
    ],
    "snapshots": []
  }
}
GET /projects/{project_id}/ads/{id}

Get ad (poll status and asset URLs)

curl 
curl https://trygrowthchicken.com/api/v1/projects/YOUR_PROJECT_SLUG/ads/YOUR_PROJECT_SLUG \
  -H "Authorization: Bearer $GROWTH_CHICKEN_API_TOKEN"
Example response
200 OK 
{
  "ad": {
    "id": "00000000-0000-0000-0000-000000000401",
    "slug": "summer-sale",
    "project_id": "00000000-0000-0000-0000-000000000001",
    "name": "LaunchPad - Ship campaigns in minutes",
    "status": "generating",
    "ready": false,
    "generating": true,
    "failed": false,
    "requested_output": "video",
    "video_style": "live_scene",
    "video_style_label": "Live scene",
    "audience_id": "00000000-0000-0000-0000-000000000101",
    "platform_aspect": "9:16",
    "placements": [
      "instagram_story",
      "square"
    ],
    "token_cost": 163,
    "created_at": "2026-06-20T12:00:00Z",
    "updated_at": "2026-06-20T12:00:00Z",
    "url": "http://localhost:3000/projects/launchpad/creative_compositions/summer-sale",
    "poll_url": "http://localhost:3000/api/v1/projects/launchpad/ads/summer-sale",
    "files": [
      {
        "placement": "square",
        "label": "Square (1:1)",
        "width": 1080,
        "height": 1080,
        "document_url": "http://localhost:3000/api/v1/projects/launchpad/ads/summer-sale/file.html?placement=square",
        "asset_url": "http://localhost:3000/api/v1/projects/launchpad/ads/summer-sale/file.mp4?placement=square"
      }
    ],
    "snapshots": []
  }
}
GET /projects/{project_id}/ads/{id}/file

Download the rendered asset (mp4/png/jpg) or the composed HTML document

curl 
curl https://trygrowthchicken.com/api/v1/projects/YOUR_PROJECT_SLUG/ads/YOUR_PROJECT_SLUG/file \
  -H "Authorization: Bearer $GROWTH_CHICKEN_API_TOKEN"

Audiences

GET /projects/{project_id}/audiences

List audiences

curl 
curl https://trygrowthchicken.com/api/v1/projects/YOUR_PROJECT_SLUG/audiences \
  -H "Authorization: Bearer $GROWTH_CHICKEN_API_TOKEN"
Example response
200 OK 
{
  "audiences": [
    {
      "id": "00000000-0000-0000-0000-000000000101",
      "slug": "finance_operators",
      "project_id": "00000000-0000-0000-0000-000000000001",
      "organization_id": "00000000-0000-0000-0000-000000000201",
      "creator_user_id": "00000000-0000-0000-0000-000000000301",
      "name": "Finance operators",
      "description": "Operations and finance leaders who need audit-ready campaign workflows.",
      "rules": "Avoid hype. Mention controls, approvals, and reliable reporting.",
      "metadata": {
        "segment": "finance"
      },
      "used_by_ads": false,
      "created_at": "2026-06-18T12:00:00Z",
      "updated_at": "2026-06-18T12:00:00Z"
    }
  ]
}
POST /projects/{project_id}/audiences

Create audience

Request body 
{
  "audience": {
    "name": "Finance operators",
    "description": "Operations and finance leaders who need audit-ready campaign workflows.",
    "rules": "Avoid hype. Mention controls, approvals, and reliable reporting.",
    "metadata": {
      "segment": "finance"
    }
  }
}
curl 
curl -X POST https://trygrowthchicken.com/api/v1/projects/YOUR_PROJECT_SLUG/audiences \
  -H "Authorization: Bearer $GROWTH_CHICKEN_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"audience":{"name":"Finance operators","description":"Operations and finance leaders who need audit-ready campaign workflows.","rules":"Avoid hype. Mention controls, approvals, and reliable reporting.","metadata":{"segment":"finance"}}}'
Example response
200 OK 
{
  "audience": {
    "id": "00000000-0000-0000-0000-000000000101",
    "slug": "finance_operators",
    "project_id": "00000000-0000-0000-0000-000000000001",
    "organization_id": "00000000-0000-0000-0000-000000000201",
    "creator_user_id": "00000000-0000-0000-0000-000000000301",
    "name": "Finance operators",
    "description": "Operations and finance leaders who need audit-ready campaign workflows.",
    "rules": "Avoid hype. Mention controls, approvals, and reliable reporting.",
    "metadata": {
      "segment": "finance"
    },
    "used_by_ads": false,
    "created_at": "2026-06-18T12:00:00Z",
    "updated_at": "2026-06-18T12:00:00Z"
  }
}
GET /projects/{project_id}/audiences/{id}

Get audience

curl 
curl https://trygrowthchicken.com/api/v1/projects/YOUR_PROJECT_SLUG/audiences/YOUR_AUDIENCE_SLUG \
  -H "Authorization: Bearer $GROWTH_CHICKEN_API_TOKEN"
Example response
200 OK 
{
  "audience": {
    "id": "00000000-0000-0000-0000-000000000101",
    "slug": "finance_operators",
    "project_id": "00000000-0000-0000-0000-000000000001",
    "organization_id": "00000000-0000-0000-0000-000000000201",
    "creator_user_id": "00000000-0000-0000-0000-000000000301",
    "name": "Finance operators",
    "description": "Operations and finance leaders who need audit-ready campaign workflows.",
    "rules": "Avoid hype. Mention controls, approvals, and reliable reporting.",
    "metadata": {
      "segment": "finance"
    },
    "used_by_ads": false,
    "created_at": "2026-06-18T12:00:00Z",
    "updated_at": "2026-06-18T12:00:00Z"
  }
}
PATCH /projects/{project_id}/audiences/{id}

Update audience

Request body 
{
  "audience": {
    "name": "Finance operators",
    "description": "Operations and finance leaders who need audit-ready campaign workflows.",
    "rules": "Avoid hype. Mention controls, approvals, and reliable reporting.",
    "metadata": {
      "segment": "finance"
    }
  }
}
curl 
curl -X PATCH https://trygrowthchicken.com/api/v1/projects/YOUR_PROJECT_SLUG/audiences/YOUR_AUDIENCE_SLUG \
  -H "Authorization: Bearer $GROWTH_CHICKEN_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"audience":{"name":"Finance operators","description":"Operations and finance leaders who need audit-ready campaign workflows.","rules":"Avoid hype. Mention controls, approvals, and reliable reporting.","metadata":{"segment":"finance"}}}'
Example response
200 OK 
{
  "audience": {
    "id": "00000000-0000-0000-0000-000000000101",
    "slug": "finance_operators",
    "project_id": "00000000-0000-0000-0000-000000000001",
    "organization_id": "00000000-0000-0000-0000-000000000201",
    "creator_user_id": "00000000-0000-0000-0000-000000000301",
    "name": "Finance operators",
    "description": "Operations and finance leaders who need audit-ready campaign workflows.",
    "rules": "Avoid hype. Mention controls, approvals, and reliable reporting.",
    "metadata": {
      "segment": "finance"
    },
    "used_by_ads": false,
    "created_at": "2026-06-18T12:00:00Z",
    "updated_at": "2026-06-18T12:00:00Z"
  }
}
DELETE /projects/{project_id}/audiences/{id}

Delete audience

curl 
curl -X DELETE https://trygrowthchicken.com/api/v1/projects/YOUR_PROJECT_SLUG/audiences/YOUR_AUDIENCE_SLUG \
  -H "Authorization: Bearer $GROWTH_CHICKEN_API_TOKEN"