{"title":"Growth Chicken API","description":"Manage projects and reusable audiences from agents, internal tools, and automation. Every request is authenticated with a bearer token and returns JSON.","base_url":"https://trygrowthchicken.com","authentication":{"type":"bearer","header":"Authorization: Bearer $GROWTH_CHICKEN_API_TOKEN","summary":"Send your key as a bearer token in the Authorization header. Requests without a valid key return 401."},"placeholders":["$GROWTH_CHICKEN_API_TOKEN","YOUR_PROJECT_SLUG","YOUR_AD_ID_OR_SLUG","YOUR_AD_RUN_ID","YOUR_OBSERVATION_ID","YOUR_AUDIENCE_SLUG","YOUR_ASSET_ID","YOUR_HYPOTHESIS_ID","YOUR_FINDING_ID","YOUR_EXPERIMENT_ID","YOUR_EXPERIMENT_SUBJECT_ID"],"resources":[{"name":"Account","description":"Inspect the authenticated account and create API access for a confirmed user."},{"name":"Projects","description":"Create and manage product briefs. Projects own audiences, assets, generated ads, and the distribution records below."},{"name":"Styles","description":"Discover customer-selectable regular templates and meme formats, their supported outputs, and semantic roles."},{"name":"Audiences","description":"Reusable audience definitions and creative rules scoped to a project."},{"name":"Hypotheses","description":"Durable directional beliefs and the generation brief that summarizes current learning and ongoing attempts."},{"name":"Findings","description":"Authored positive, negative, or neutral observations. Findings may stand alone, attach to an existing Experiment, or imply one from supplied subjects."},{"name":"Experiments","description":"Optional lightweight bundles of attempts and subjects under a Hypothesis. They provide context without asserting statistical certainty."},{"name":"Assets","description":"Uploaded brand, product, and media files that generated or composed ads can use."},{"name":"Ads","description":"Generated creative outputs. Ads can have many external runs when the same creative is distributed in different platforms, campaigns, or ad sets."},{"name":"External Identifiers","description":"User-declared key-value pairs (e.g. meta_ad_account, google_customer, product_key) that anchor a project or an ad to the outside platforms it runs in, so performance data resolves back deterministically."},{"name":"Ad Runs","description":"Distribution instances for an ad outside Growth Chicken. A run identifies the platform, channel, objective, external campaign/ad ids, current projected status, and rolled-up performance."},{"name":"Observations","description":"Append-style facts about a run. Lifecycle observations project run status and dates; metric observations roll up performance; notes and platform snapshots preserve source context."}],"endpoints":[{"group":"Account","method":"POST","path":"/api/v1/accounts","summary":"Set up an account (sends a confirmation email)","description":"Public and unauthenticated. Creates an account for the given email and sends a confirmation link; the account cannot be used and no API key can be made until that link is clicked. Heavily rate limited (per IP and per email). Optionally include a Cloudflare Turnstile token as \"cf-turnstile-response\" to prove you are human.","curl":"curl -X POST https://trygrowthchicken.com/api/v1/accounts \\\n  -H \"Authorization: Bearer $GROWTH_CHICKEN_API_TOKEN\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"email\":\"you@example.com\"}'","request_example":{"email":"you@example.com"}},{"group":"Account","method":"GET","path":"/api/v1/account","summary":"Get account token balance","description":"Returns the authenticated account and its current token balance. This is the same token pool used by the web app and API generation requests.","curl":"curl https://trygrowthchicken.com/api/v1/account \\\n  -H \"Authorization: Bearer $GROWTH_CHICKEN_API_TOKEN\"","response_example":{"account":{"user_id":"00000000-0000-0000-0000-000000000301","email":"user@example.com","token_balance":1234,"output_options":[{"id":"image","label":"Still ad","description":"Create an editable still using any compatible ad layout or meme format.","token_cost":25,"cost_basis":"per_variant"},{"id":"video","label":"Video ad","description":"Generate a moving scene using a compatible ad layout.","token_cost":163,"cost_basis":"per_variant"}]}}},{"group":"Projects","method":"GET","path":"/api/v1/projects","summary":"List projects","curl":"curl https://trygrowthchicken.com/api/v1/projects \\\n  -H \"Authorization: Bearer $GROWTH_CHICKEN_API_TOKEN\"","response_example":{"projects":[{"id":"00000000-0000-0000-0000-000000000001","slug":"launchpad","name":"LaunchPad","description":"A complete project brief.","tagline":"Launch creative faster.","visual_direction":"Bright product-led scenes with crisp UI moments and clean negative space.","avatar_url":"https://cdn.example.com/brand-mark.png","status":"active","source_url":"https://example.com","external_identifiers":{"meta_ad_account":"act_1234567890","product_key":"launchpad"},"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}]}},{"group":"Projects","method":"POST","path":"/api/v1/projects","summary":"Create project","curl":"curl -X POST https://trygrowthchicken.com/api/v1/projects \\\n  -H \"Authorization: Bearer $GROWTH_CHICKEN_API_TOKEN\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"project\":{\"name\":\"LaunchPad\",\"description\":\"A detailed product brief with audience, offer, proof points, tone, constraints, claims, channel context, product benefits, objections, conversion goal, and enough substance for generated creative work.\",\"tagline\":\"Launch creative faster.\",\"visual_direction\":\"Bright product-led scenes with crisp UI moments, confident lighting, clean negative space, and occasional high-contrast accent shapes.\",\"source_url\":\"https://example.com\",\"ad_health_monitored\":true,\"target_cpa\":\"24.50\",\"target_cpa_currency\":\"USD\",\"brand_kit\":{\"colors\":[\"#111111\",\"#ffcc00\"],\"font_preferences\":{\"direction\":\"Clean geometric sans with expressive display accents.\"},\"style_notes\":\"Bright, direct, and product-led.\"}}}'","request_example":{"project":{"name":"LaunchPad","description":"A detailed product brief with audience, offer, proof points, tone, constraints, claims, channel context, product benefits, objections, conversion goal, and enough substance for generated creative work.","tagline":"Launch creative faster.","visual_direction":"Bright product-led scenes with crisp UI moments, confident lighting, clean negative space, and occasional high-contrast accent shapes.","source_url":"https://example.com","ad_health_monitored":true,"target_cpa":"24.50","target_cpa_currency":"USD","brand_kit":{"colors":["#111111","#ffcc00"],"font_preferences":{"direction":"Clean geometric sans with expressive display accents."},"style_notes":"Bright, direct, and product-led."}}},"response_example":{"project":{"id":"00000000-0000-0000-0000-000000000001","slug":"launchpad","name":"LaunchPad","description":"A complete project brief.","tagline":"Launch creative faster.","visual_direction":"Bright product-led scenes with crisp UI moments and clean negative space.","avatar_url":"https://cdn.example.com/brand-mark.png","status":"active","source_url":"https://example.com","external_identifiers":{"meta_ad_account":"act_1234567890","product_key":"launchpad"},"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}}},{"group":"Projects","method":"POST","path":"/api/v1/projects/from_url","summary":"Create project from a URL","curl":"curl -X POST https://trygrowthchicken.com/api/v1/projects/from_url \\\n  -H \"Authorization: Bearer $GROWTH_CHICKEN_API_TOKEN\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"url\":\"https://example.com\"}'","request_example":{"url":"https://example.com"},"response_example":{"project":{"id":"00000000-0000-0000-0000-000000000001","slug":"launchpad","name":"LaunchPad","description":"A complete project brief.","tagline":"Launch creative faster.","visual_direction":"Bright product-led scenes with crisp UI moments and clean negative space.","avatar_url":"https://cdn.example.com/brand-mark.png","status":"active","source_url":"https://example.com","external_identifiers":{"meta_ad_account":"act_1234567890","product_key":"launchpad"},"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}}},{"group":"Projects","method":"GET","path":"/api/v1/projects/{id}","summary":"Get project","curl":"curl https://trygrowthchicken.com/api/v1/projects/YOUR_PROJECT_SLUG \\\n  -H \"Authorization: Bearer $GROWTH_CHICKEN_API_TOKEN\"","response_example":{"project":{"id":"00000000-0000-0000-0000-000000000001","slug":"launchpad","name":"LaunchPad","description":"A complete project brief.","tagline":"Launch creative faster.","visual_direction":"Bright product-led scenes with crisp UI moments and clean negative space.","avatar_url":"https://cdn.example.com/brand-mark.png","status":"active","source_url":"https://example.com","external_identifiers":{"meta_ad_account":"act_1234567890","product_key":"launchpad"},"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}}},{"group":"Projects","method":"PATCH","path":"/api/v1/projects/{id}","summary":"Update project","curl":"curl -X PATCH https://trygrowthchicken.com/api/v1/projects/YOUR_PROJECT_SLUG \\\n  -H \"Authorization: Bearer $GROWTH_CHICKEN_API_TOKEN\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"project\":{\"name\":\"LaunchPad\",\"description\":\"A detailed product brief with audience, offer, proof points, tone, constraints, claims, channel context, product benefits, objections, conversion goal, and enough substance for generated creative work.\",\"tagline\":\"Launch creative faster.\",\"visual_direction\":\"Bright product-led scenes with crisp UI moments, confident lighting, clean negative space, and occasional high-contrast accent shapes.\",\"source_url\":\"https://example.com\",\"ad_health_monitored\":true,\"target_cpa\":\"24.50\",\"target_cpa_currency\":\"USD\",\"brand_kit\":{\"colors\":[\"#111111\",\"#ffcc00\"],\"font_preferences\":{\"direction\":\"Clean geometric sans with expressive display accents.\"},\"style_notes\":\"Bright, direct, and product-led.\"}}}'","request_example":{"project":{"name":"LaunchPad","description":"A detailed product brief with audience, offer, proof points, tone, constraints, claims, channel context, product benefits, objections, conversion goal, and enough substance for generated creative work.","tagline":"Launch creative faster.","visual_direction":"Bright product-led scenes with crisp UI moments, confident lighting, clean negative space, and occasional high-contrast accent shapes.","source_url":"https://example.com","ad_health_monitored":true,"target_cpa":"24.50","target_cpa_currency":"USD","brand_kit":{"colors":["#111111","#ffcc00"],"font_preferences":{"direction":"Clean geometric sans with expressive display accents."},"style_notes":"Bright, direct, and product-led."}}},"response_example":{"project":{"id":"00000000-0000-0000-0000-000000000001","slug":"launchpad","name":"LaunchPad","description":"A complete project brief.","tagline":"Launch creative faster.","visual_direction":"Bright product-led scenes with crisp UI moments and clean negative space.","avatar_url":"https://cdn.example.com/brand-mark.png","status":"active","source_url":"https://example.com","external_identifiers":{"meta_ad_account":"act_1234567890","product_key":"launchpad"},"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}}},{"group":"Projects","method":"DELETE","path":"/api/v1/projects/{id}","summary":"Delete project","curl":"curl -X DELETE https://trygrowthchicken.com/api/v1/projects/YOUR_PROJECT_SLUG \\\n  -H \"Authorization: Bearer $GROWTH_CHICKEN_API_TOKEN\""},{"group":"Styles","method":"GET","path":"/api/v1/styles","summary":"List global ad styles","description":"A cacheable global catalog of regular templates and customer-selectable meme bases. Filter each entry's outputs before pinning it.","curl":"curl https://trygrowthchicken.com/api/v1/styles \\\n  -H \"Authorization: Bearer $GROWTH_CHICKEN_API_TOKEN\"","response_example":{"styles":[{"id":"meme:impossible-choice","category":"meme","name":"Impossible Choice","description":"Two competing options that make the hesitation instantly recognizable.","tags":["decision","dilemma","conflict"],"outputs":["image"],"template_key":"meme_panel","meme_base":"impossible-choice","editable_slots":[{"name":"option_left","role":"first_option","budget":22,"max_lines":2,"max_words":4},{"name":"option_right","role":"second_option","budget":22,"max_lines":2,"max_words":4}],"character_roles":[{"name":"decider","guidance":"The person, creature, product, or team forced to choose."}]}]}},{"group":"Audiences","method":"GET","path":"/api/v1/projects/{project_id}/audiences","summary":"List audiences","curl":"curl https://trygrowthchicken.com/api/v1/projects/YOUR_PROJECT_SLUG/audiences \\\n  -H \"Authorization: Bearer $GROWTH_CHICKEN_API_TOKEN\"","response_example":{"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"}]}},{"group":"Audiences","method":"POST","path":"/api/v1/projects/{project_id}/audiences","summary":"Create audience","curl":"curl -X POST https://trygrowthchicken.com/api/v1/projects/YOUR_PROJECT_SLUG/audiences \\\n  -H \"Authorization: Bearer $GROWTH_CHICKEN_API_TOKEN\" \\\n  -H \"Content-Type: application/json\" \\\n  -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\"}}}'","request_example":{"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"}}},"response_example":{"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"}}},{"group":"Audiences","method":"GET","path":"/api/v1/projects/{project_id}/audiences/{id}","summary":"Get audience","curl":"curl https://trygrowthchicken.com/api/v1/projects/YOUR_PROJECT_SLUG/audiences/YOUR_AUDIENCE_SLUG \\\n  -H \"Authorization: Bearer $GROWTH_CHICKEN_API_TOKEN\"","response_example":{"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"}}},{"group":"Audiences","method":"PATCH","path":"/api/v1/projects/{project_id}/audiences/{id}","summary":"Update audience","curl":"curl -X PATCH https://trygrowthchicken.com/api/v1/projects/YOUR_PROJECT_SLUG/audiences/YOUR_AUDIENCE_SLUG \\\n  -H \"Authorization: Bearer $GROWTH_CHICKEN_API_TOKEN\" \\\n  -H \"Content-Type: application/json\" \\\n  -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\"}}}'","request_example":{"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"}}},"response_example":{"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"}}},{"group":"Audiences","method":"DELETE","path":"/api/v1/projects/{project_id}/audiences/{id}","summary":"Delete audience","curl":"curl -X DELETE https://trygrowthchicken.com/api/v1/projects/YOUR_PROJECT_SLUG/audiences/YOUR_AUDIENCE_SLUG \\\n  -H \"Authorization: Bearer $GROWTH_CHICKEN_API_TOKEN\""},{"group":"Hypotheses","method":"GET","path":"/api/v1/projects/{project_id}/hypotheses","summary":"List hypotheses","curl":"curl https://trygrowthchicken.com/api/v1/projects/YOUR_PROJECT_SLUG/hypotheses \\\n  -H \"Authorization: Bearer $GROWTH_CHICKEN_API_TOKEN\"","response_example":{"hypotheses":[{"id":"00000000-0000-0000-0000-000000000801","project_id":"00000000-0000-0000-0000-000000000001","organization_id":"00000000-0000-0000-0000-000000000201","statement":"Founder-led voice improves cold-traffic recall","audience_id":"00000000-0000-0000-0000-000000000101","audience_label":"Finance operators","author":"agent:weekly-reviewer","agent_authored":true,"created_at":"2026-07-20T09:00:00Z","updated_at":"2026-07-20T09:00:00Z"}]}},{"group":"Hypotheses","method":"POST","path":"/api/v1/projects/{project_id}/hypotheses","summary":"Create hypothesis","description":"Creates one durable, directional belief. Audience scope is optional and fixed at creation.","curl":"curl -X POST https://trygrowthchicken.com/api/v1/projects/YOUR_PROJECT_SLUG/hypotheses \\\n  -H \"Authorization: Bearer $GROWTH_CHICKEN_API_TOKEN\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"hypothesis\":{\"statement\":\"Founder-led voice improves cold-traffic recall\",\"audience_id\":\"00000000-0000-0000-0000-000000000101\"}}'","request_example":{"hypothesis":{"statement":"Founder-led voice improves cold-traffic recall","audience_id":"00000000-0000-0000-0000-000000000101"}},"response_example":{"hypothesis":{"id":"00000000-0000-0000-0000-000000000801","project_id":"00000000-0000-0000-0000-000000000001","organization_id":"00000000-0000-0000-0000-000000000201","statement":"Founder-led voice improves cold-traffic recall","audience_id":"00000000-0000-0000-0000-000000000101","audience_label":"Finance operators","author":"agent:weekly-reviewer","agent_authored":true,"created_at":"2026-07-20T09:00:00Z","updated_at":"2026-07-20T09:00:00Z"}}},{"group":"Hypotheses","method":"GET","path":"/api/v1/projects/{project_id}/hypotheses/brief","summary":"Get the hypothesis brief for ad generation","description":"The durable learning state to read before generating ads: current directional findings, untested or contested beliefs, related precedent, and ongoing experiments with their subjects.","curl":"curl https://trygrowthchicken.com/api/v1/projects/YOUR_PROJECT_SLUG/hypotheses/brief \\\n  -H \"Authorization: Bearer $GROWTH_CHICKEN_API_TOKEN\"","response_example":{"brief":{"project_id":"00000000-0000-0000-0000-000000000001","scope":{"audience_id":"00000000-0000-0000-0000-000000000101","audience":"Finance operators"},"hypotheses":[{"id":"00000000-0000-0000-0000-000000000801","statement":"Founder-led voice improves cold-traffic recall","audience_label":"Finance operators","findings_count":2,"signal_counts":{"positive":1,"neutral":1},"untested":false,"contested":false,"latest_signal":"positive","latest_finding_at":"2026-07-18T17:00:00Z","ongoing_experiments":[{"id":"00000000-0000-0000-0000-000000000901","context":"Founder narration with the offer in the first two seconds","window_start":"2026-07-20T09:00:00Z","window_end":null,"subjects":[{"id":"00000000-0000-0000-0000-000000000a01","name":"Founder opening","kind":"internal","creative_composition_id":"00000000-0000-0000-0000-000000000401","ad_run_id":null,"external_ref":null}]}]}],"precedent":[{"id":"00000000-0000-0000-0000-000000000802","statement":"Human narration improves product comprehension","audience_label":"all audiences"}]}}},{"group":"Hypotheses","method":"GET","path":"/api/v1/projects/{project_id}/hypotheses/{id}","summary":"Get hypothesis","curl":"curl https://trygrowthchicken.com/api/v1/projects/YOUR_PROJECT_SLUG/hypotheses/YOUR_HYPOTHESIS_ID \\\n  -H \"Authorization: Bearer $GROWTH_CHICKEN_API_TOKEN\"","response_example":{"hypothesis":{"id":"00000000-0000-0000-0000-000000000801","project_id":"00000000-0000-0000-0000-000000000001","organization_id":"00000000-0000-0000-0000-000000000201","statement":"Founder-led voice improves cold-traffic recall","audience_id":"00000000-0000-0000-0000-000000000101","audience_label":"Finance operators","author":"agent:weekly-reviewer","agent_authored":true,"created_at":"2026-07-20T09:00:00Z","updated_at":"2026-07-20T09:00:00Z"}}},{"group":"Hypotheses","method":"PATCH","path":"/api/v1/projects/{project_id}/hypotheses/{id}","summary":"Update hypothesis statement","curl":"curl -X PATCH https://trygrowthchicken.com/api/v1/projects/YOUR_PROJECT_SLUG/hypotheses/YOUR_HYPOTHESIS_ID \\\n  -H \"Authorization: Bearer $GROWTH_CHICKEN_API_TOKEN\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"hypothesis\":{\"statement\":\"Founder-led voice improves cold-traffic recall\",\"audience_id\":\"00000000-0000-0000-0000-000000000101\"}}'","request_example":{"hypothesis":{"statement":"Founder-led voice improves cold-traffic recall","audience_id":"00000000-0000-0000-0000-000000000101"}},"response_example":{"hypothesis":{"id":"00000000-0000-0000-0000-000000000801","project_id":"00000000-0000-0000-0000-000000000001","organization_id":"00000000-0000-0000-0000-000000000201","statement":"Founder-led voice improves cold-traffic recall","audience_id":"00000000-0000-0000-0000-000000000101","audience_label":"Finance operators","author":"agent:weekly-reviewer","agent_authored":true,"created_at":"2026-07-20T09:00:00Z","updated_at":"2026-07-20T09:00:00Z"}}},{"group":"Hypotheses","method":"DELETE","path":"/api/v1/projects/{project_id}/hypotheses/{id}","summary":"Delete hypothesis","description":"Deletes an untested hypothesis. Hypotheses with findings are retained as part of the learning record.","curl":"curl -X DELETE https://trygrowthchicken.com/api/v1/projects/YOUR_PROJECT_SLUG/hypotheses/YOUR_HYPOTHESIS_ID \\\n  -H \"Authorization: Bearer $GROWTH_CHICKEN_API_TOKEN\""},{"group":"Findings","method":"GET","path":"/api/v1/projects/{project_id}/hypotheses/{hypothesis_id}/findings","summary":"List findings","curl":"curl https://trygrowthchicken.com/api/v1/projects/YOUR_PROJECT_SLUG/hypotheses/YOUR_HYPOTHESIS_ID/findings \\\n  -H \"Authorization: Bearer $GROWTH_CHICKEN_API_TOKEN\"","response_example":{"findings":[{"id":"00000000-0000-0000-0000-000000000b01","hypothesis_id":"00000000-0000-0000-0000-000000000801","experiment_id":"00000000-0000-0000-0000-000000000901","body":"The faster founder opening improved click-through.","signal":"positive","finding_at":"2026-07-23T17:00:00Z","supersedes_finding_id":null,"superseded":false,"author":"agent:weekly-reviewer","agent_authored":true,"created_at":"2026-07-23T17:00:00Z","updated_at":"2026-07-23T17:00:00Z"}]}},{"group":"Findings","method":"POST","path":"/api/v1/projects/{project_id}/hypotheses/{hypothesis_id}/findings","summary":"Create finding","description":"Writes authored directional prose without computing a statistical verdict. To conclude a previously opened attempt, send its experiment_id and optional window_end. The Experiment must belong to this Hypothesis. Alternatively, omit experiment_id and supply subjects to imply a new Experiment in the same write. Do not send both experiment_id and subjects. Omit both for a Finding with no Experiment.","curl":"curl -X POST https://trygrowthchicken.com/api/v1/projects/YOUR_PROJECT_SLUG/hypotheses/YOUR_HYPOTHESIS_ID/findings \\\n  -H \"Authorization: Bearer $GROWTH_CHICKEN_API_TOKEN\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"finding\":{\"body\":\"The faster founder opening improved click-through.\",\"signal\":\"positive\",\"experiment_id\":\"00000000-0000-0000-0000-000000000901\",\"window_end\":\"2026-07-23T17:00:00Z\"}}'","request_example":{"finding":{"body":"The faster founder opening improved click-through.","signal":"positive","experiment_id":"00000000-0000-0000-0000-000000000901","window_end":"2026-07-23T17:00:00Z"}},"response_example":{"finding":{"id":"00000000-0000-0000-0000-000000000b01","hypothesis_id":"00000000-0000-0000-0000-000000000801","experiment_id":"00000000-0000-0000-0000-000000000901","body":"The faster founder opening improved click-through.","signal":"positive","finding_at":"2026-07-23T17:00:00Z","supersedes_finding_id":null,"superseded":false,"author":"agent:weekly-reviewer","agent_authored":true,"created_at":"2026-07-23T17:00:00Z","updated_at":"2026-07-23T17:00:00Z"}}},{"group":"Findings","method":"GET","path":"/api/v1/projects/{project_id}/hypotheses/{hypothesis_id}/findings/{id}","summary":"Get finding","curl":"curl https://trygrowthchicken.com/api/v1/projects/YOUR_PROJECT_SLUG/hypotheses/YOUR_HYPOTHESIS_ID/findings/YOUR_FINDING_ID \\\n  -H \"Authorization: Bearer $GROWTH_CHICKEN_API_TOKEN\"","response_example":{"finding":{"id":"00000000-0000-0000-0000-000000000b01","hypothesis_id":"00000000-0000-0000-0000-000000000801","experiment_id":"00000000-0000-0000-0000-000000000901","body":"The faster founder opening improved click-through.","signal":"positive","finding_at":"2026-07-23T17:00:00Z","supersedes_finding_id":null,"superseded":false,"author":"agent:weekly-reviewer","agent_authored":true,"created_at":"2026-07-23T17:00:00Z","updated_at":"2026-07-23T17:00:00Z"}}},{"group":"Findings","method":"PATCH","path":"/api/v1/projects/{project_id}/hypotheses/{hypothesis_id}/findings/{id}","summary":"Update inferred finding signal","description":"Findings are append-only. This endpoint only updates signal after inference; corrections should create a new Finding with supersedes_finding_id.","curl":"curl -X PATCH https://trygrowthchicken.com/api/v1/projects/YOUR_PROJECT_SLUG/hypotheses/YOUR_HYPOTHESIS_ID/findings/YOUR_FINDING_ID \\\n  -H \"Authorization: Bearer $GROWTH_CHICKEN_API_TOKEN\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"finding\":{\"signal\":\"positive\"}}'","request_example":{"finding":{"signal":"positive"}},"response_example":{"finding":{"id":"00000000-0000-0000-0000-000000000b01","hypothesis_id":"00000000-0000-0000-0000-000000000801","experiment_id":"00000000-0000-0000-0000-000000000901","body":"The faster founder opening improved click-through.","signal":"positive","finding_at":"2026-07-23T17:00:00Z","supersedes_finding_id":null,"superseded":false,"author":"agent:weekly-reviewer","agent_authored":true,"created_at":"2026-07-23T17:00:00Z","updated_at":"2026-07-23T17:00:00Z"}}},{"group":"Experiments","method":"GET","path":"/api/v1/projects/{project_id}/hypotheses/{hypothesis_id}/experiments","summary":"List experiments","curl":"curl https://trygrowthchicken.com/api/v1/projects/YOUR_PROJECT_SLUG/hypotheses/YOUR_HYPOTHESIS_ID/experiments \\\n  -H \"Authorization: Bearer $GROWTH_CHICKEN_API_TOKEN\"","response_example":{"experiments":[{"id":"00000000-0000-0000-0000-000000000901","hypothesis_id":"00000000-0000-0000-0000-000000000801","context":"Founder narration with the offer in the first two seconds","state":"ongoing","window_start":"2026-07-20T09:00:00Z","window_end":null,"author":"agent:weekly-reviewer","agent_authored":true,"subjects":[{"id":"00000000-0000-0000-0000-000000000a01","experiment_id":"00000000-0000-0000-0000-000000000901","name":"Founder opening","kind":"internal","creative_composition_id":"00000000-0000-0000-0000-000000000401","ad_run_id":null,"external_ref":null,"created_at":"2026-07-20T09:05:00Z","updated_at":"2026-07-20T09:05:00Z"}],"created_at":"2026-07-20T09:00:00Z","updated_at":"2026-07-20T09:05:00Z"}]}},{"group":"Experiments","method":"POST","path":"/api/v1/projects/{project_id}/hypotheses/{hypothesis_id}/experiments","summary":"Open experiment","description":"Opens a lightweight attempt under the Hypothesis. Add subjects through the subjects endpoint, then attach a later Finding with experiment_id.","curl":"curl -X POST https://trygrowthchicken.com/api/v1/projects/YOUR_PROJECT_SLUG/hypotheses/YOUR_HYPOTHESIS_ID/experiments \\\n  -H \"Authorization: Bearer $GROWTH_CHICKEN_API_TOKEN\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"experiment\":{\"context\":\"Founder narration with the offer in the first two seconds\",\"window_start\":\"2026-07-20T09:00:00Z\",\"window_end\":null}}'","request_example":{"experiment":{"context":"Founder narration with the offer in the first two seconds","window_start":"2026-07-20T09:00:00Z","window_end":null}},"response_example":{"experiment":{"id":"00000000-0000-0000-0000-000000000901","hypothesis_id":"00000000-0000-0000-0000-000000000801","context":"Founder narration with the offer in the first two seconds","state":"ongoing","window_start":"2026-07-20T09:00:00Z","window_end":null,"author":"agent:weekly-reviewer","agent_authored":true,"subjects":[{"id":"00000000-0000-0000-0000-000000000a01","experiment_id":"00000000-0000-0000-0000-000000000901","name":"Founder opening","kind":"internal","creative_composition_id":"00000000-0000-0000-0000-000000000401","ad_run_id":null,"external_ref":null,"created_at":"2026-07-20T09:05:00Z","updated_at":"2026-07-20T09:05:00Z"}],"created_at":"2026-07-20T09:00:00Z","updated_at":"2026-07-20T09:05:00Z"}}},{"group":"Experiments","method":"GET","path":"/api/v1/projects/{project_id}/hypotheses/{hypothesis_id}/experiments/{id}","summary":"Get experiment","curl":"curl https://trygrowthchicken.com/api/v1/projects/YOUR_PROJECT_SLUG/hypotheses/YOUR_HYPOTHESIS_ID/experiments/YOUR_EXPERIMENT_ID \\\n  -H \"Authorization: Bearer $GROWTH_CHICKEN_API_TOKEN\"","response_example":{"experiment":{"id":"00000000-0000-0000-0000-000000000901","hypothesis_id":"00000000-0000-0000-0000-000000000801","context":"Founder narration with the offer in the first two seconds","state":"ongoing","window_start":"2026-07-20T09:00:00Z","window_end":null,"author":"agent:weekly-reviewer","agent_authored":true,"subjects":[{"id":"00000000-0000-0000-0000-000000000a01","experiment_id":"00000000-0000-0000-0000-000000000901","name":"Founder opening","kind":"internal","creative_composition_id":"00000000-0000-0000-0000-000000000401","ad_run_id":null,"external_ref":null,"created_at":"2026-07-20T09:05:00Z","updated_at":"2026-07-20T09:05:00Z"}],"created_at":"2026-07-20T09:00:00Z","updated_at":"2026-07-20T09:05:00Z"}}},{"group":"Experiments","method":"PATCH","path":"/api/v1/projects/{project_id}/hypotheses/{hypothesis_id}/experiments/{id}","summary":"Update experiment context or window","description":"Set window_end to conclude the attempt. A Finding that supplies this experiment_id may also set window_end atomically.","curl":"curl -X PATCH https://trygrowthchicken.com/api/v1/projects/YOUR_PROJECT_SLUG/hypotheses/YOUR_HYPOTHESIS_ID/experiments/YOUR_EXPERIMENT_ID \\\n  -H \"Authorization: Bearer $GROWTH_CHICKEN_API_TOKEN\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"experiment\":{\"context\":\"Founder narration with the offer in the first two seconds\",\"window_start\":\"2026-07-20T09:00:00Z\",\"window_end\":null}}'","request_example":{"experiment":{"context":"Founder narration with the offer in the first two seconds","window_start":"2026-07-20T09:00:00Z","window_end":null}},"response_example":{"experiment":{"id":"00000000-0000-0000-0000-000000000901","hypothesis_id":"00000000-0000-0000-0000-000000000801","context":"Founder narration with the offer in the first two seconds","state":"ongoing","window_start":"2026-07-20T09:00:00Z","window_end":null,"author":"agent:weekly-reviewer","agent_authored":true,"subjects":[{"id":"00000000-0000-0000-0000-000000000a01","experiment_id":"00000000-0000-0000-0000-000000000901","name":"Founder opening","kind":"internal","creative_composition_id":"00000000-0000-0000-0000-000000000401","ad_run_id":null,"external_ref":null,"created_at":"2026-07-20T09:05:00Z","updated_at":"2026-07-20T09:05:00Z"}],"created_at":"2026-07-20T09:00:00Z","updated_at":"2026-07-20T09:05:00Z"}}},{"group":"Experiments","method":"DELETE","path":"/api/v1/projects/{project_id}/hypotheses/{hypothesis_id}/experiments/{id}","summary":"Delete experiment","curl":"curl -X DELETE https://trygrowthchicken.com/api/v1/projects/YOUR_PROJECT_SLUG/hypotheses/YOUR_HYPOTHESIS_ID/experiments/YOUR_EXPERIMENT_ID \\\n  -H \"Authorization: Bearer $GROWTH_CHICKEN_API_TOKEN\""},{"group":"Experiments","method":"GET","path":"/api/v1/projects/{project_id}/hypotheses/{hypothesis_id}/experiments/{experiment_id}/subjects","summary":"List experiment subjects","curl":"curl https://trygrowthchicken.com/api/v1/projects/YOUR_PROJECT_SLUG/hypotheses/YOUR_HYPOTHESIS_ID/experiments/YOUR_EXPERIMENT_ID/subjects \\\n  -H \"Authorization: Bearer $GROWTH_CHICKEN_API_TOKEN\"","response_example":{"subjects":[{"id":"00000000-0000-0000-0000-000000000a01","experiment_id":"00000000-0000-0000-0000-000000000901","name":"Founder opening","kind":"internal","creative_composition_id":"00000000-0000-0000-0000-000000000401","ad_run_id":null,"external_ref":null,"created_at":"2026-07-20T09:05:00Z","updated_at":"2026-07-20T09:05:00Z"}]}},{"group":"Experiments","method":"POST","path":"/api/v1/projects/{project_id}/hypotheses/{hypothesis_id}/experiments/{experiment_id}/subjects","summary":"Add experiment subject","description":"Adds exactly one internal composition, internal ad run, or external reference to the attempt.","curl":"curl -X POST https://trygrowthchicken.com/api/v1/projects/YOUR_PROJECT_SLUG/hypotheses/YOUR_HYPOTHESIS_ID/experiments/YOUR_EXPERIMENT_ID/subjects \\\n  -H \"Authorization: Bearer $GROWTH_CHICKEN_API_TOKEN\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"subject\":{\"name\":\"Founder opening\",\"creative_composition_id\":\"00000000-0000-0000-0000-000000000401\"}}'","request_example":{"subject":{"name":"Founder opening","creative_composition_id":"00000000-0000-0000-0000-000000000401"}},"response_example":{"subject":{"id":"00000000-0000-0000-0000-000000000a01","experiment_id":"00000000-0000-0000-0000-000000000901","name":"Founder opening","kind":"internal","creative_composition_id":"00000000-0000-0000-0000-000000000401","ad_run_id":null,"external_ref":null,"created_at":"2026-07-20T09:05:00Z","updated_at":"2026-07-20T09:05:00Z"}}},{"group":"Experiments","method":"DELETE","path":"/api/v1/projects/{project_id}/hypotheses/{hypothesis_id}/experiments/{experiment_id}/subjects/{id}","summary":"Remove experiment subject","curl":"curl -X DELETE https://trygrowthchicken.com/api/v1/projects/YOUR_PROJECT_SLUG/hypotheses/YOUR_HYPOTHESIS_ID/experiments/YOUR_EXPERIMENT_ID/subjects/YOUR_EXPERIMENT_SUBJECT_ID \\\n  -H \"Authorization: Bearer $GROWTH_CHICKEN_API_TOKEN\""},{"group":"Assets","method":"GET","path":"/api/v1/projects/{project_id}/assets","summary":"List assets","curl":"curl https://trygrowthchicken.com/api/v1/projects/YOUR_PROJECT_SLUG/assets \\\n  -H \"Authorization: Bearer $GROWTH_CHICKEN_API_TOKEN\"","response_example":{"assets":[{"id":"00000000-0000-0000-0000-000000000501","project_id":"00000000-0000-0000-0000-000000000001","user_id":"00000000-0000-0000-0000-000000000301","asset_type":"logo","source":"upload","status":"ready","filename":"launchpad-logo.png","content_type":"image/png","byte_size":34721,"width":1024,"height":1024,"duration_seconds":null,"description":"Primary product logo","metadata":{"source":"brand kit"},"license_metadata":{"usage":"owned"},"created_at":"2026-06-19T12:00:00Z","updated_at":"2026-06-19T12:00:00Z","file_url":"http://localhost:3000/api/v1/projects/launchpad/assets/00000000-0000-0000-0000-000000000501/file"}]}},{"group":"Assets","method":"POST","path":"/api/v1/projects/{project_id}/assets","summary":"Upload an asset","description":"Upload one image as multipart/form-data using asset[file]. Supported file content types: image/png, image/jpeg, image/gif, image/webp. Max file size: 10 MB. The upload endpoint also has a lower per-token/IP rate limit than ordinary API reads.","curl":"curl -X POST https://trygrowthchicken.com/api/v1/projects/YOUR_PROJECT_SLUG/assets \\\n  -H \"Authorization: Bearer $GROWTH_CHICKEN_API_TOKEN\" \\\n  -F \"asset[file]=@./logo.png\" \\\n  -F \"asset[asset_type]=logo\" \\\n  -F \"asset[description]=Primary product logo\" \\\n  -F \"asset[metadata][source]=brand kit\" \\\n  -F \"asset[license_metadata][usage]=owned\"","request_example":{"asset":{"file":"@./logo.png","asset_type":"logo","description":"Primary product logo","metadata":{"source":"brand kit"},"license_metadata":{"usage":"owned"}}},"response_example":{"asset":{"id":"00000000-0000-0000-0000-000000000501","project_id":"00000000-0000-0000-0000-000000000001","user_id":"00000000-0000-0000-0000-000000000301","asset_type":"logo","source":"upload","status":"ready","filename":"launchpad-logo.png","content_type":"image/png","byte_size":34721,"width":1024,"height":1024,"duration_seconds":null,"description":"Primary product logo","metadata":{"source":"brand kit"},"license_metadata":{"usage":"owned"},"created_at":"2026-06-19T12:00:00Z","updated_at":"2026-06-19T12:00:00Z","file_url":"http://localhost:3000/api/v1/projects/launchpad/assets/00000000-0000-0000-0000-000000000501/file"}}},{"group":"Assets","method":"GET","path":"/api/v1/projects/{project_id}/assets/{id}","summary":"Get asset","curl":"curl https://trygrowthchicken.com/api/v1/projects/YOUR_PROJECT_SLUG/assets/YOUR_ASSET_ID \\\n  -H \"Authorization: Bearer $GROWTH_CHICKEN_API_TOKEN\"","response_example":{"asset":{"id":"00000000-0000-0000-0000-000000000501","project_id":"00000000-0000-0000-0000-000000000001","user_id":"00000000-0000-0000-0000-000000000301","asset_type":"logo","source":"upload","status":"ready","filename":"launchpad-logo.png","content_type":"image/png","byte_size":34721,"width":1024,"height":1024,"duration_seconds":null,"description":"Primary product logo","metadata":{"source":"brand kit"},"license_metadata":{"usage":"owned"},"created_at":"2026-06-19T12:00:00Z","updated_at":"2026-06-19T12:00:00Z","file_url":"http://localhost:3000/api/v1/projects/launchpad/assets/00000000-0000-0000-0000-000000000501/file"}}},{"group":"Assets","method":"PATCH","path":"/api/v1/projects/{project_id}/assets/{id}","summary":"Update asset metadata","curl":"curl -X PATCH https://trygrowthchicken.com/api/v1/projects/YOUR_PROJECT_SLUG/assets/YOUR_ASSET_ID \\\n  -H \"Authorization: Bearer $GROWTH_CHICKEN_API_TOKEN\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"asset\":{\"asset_type\":\"logo\",\"filename\":\"launchpad-logo.png\",\"description\":\"Primary product logo\",\"metadata\":{\"source\":\"brand kit\"},\"license_metadata\":{\"usage\":\"owned\"}}}'","request_example":{"asset":{"asset_type":"logo","filename":"launchpad-logo.png","description":"Primary product logo","metadata":{"source":"brand kit"},"license_metadata":{"usage":"owned"}}},"response_example":{"asset":{"id":"00000000-0000-0000-0000-000000000501","project_id":"00000000-0000-0000-0000-000000000001","user_id":"00000000-0000-0000-0000-000000000301","asset_type":"logo","source":"upload","status":"ready","filename":"launchpad-logo.png","content_type":"image/png","byte_size":34721,"width":1024,"height":1024,"duration_seconds":null,"description":"Primary product logo","metadata":{"source":"brand kit"},"license_metadata":{"usage":"owned"},"created_at":"2026-06-19T12:00:00Z","updated_at":"2026-06-19T12:00:00Z","file_url":"http://localhost:3000/api/v1/projects/launchpad/assets/00000000-0000-0000-0000-000000000501/file"}}},{"group":"Assets","method":"DELETE","path":"/api/v1/projects/{project_id}/assets/{id}","summary":"Delete asset","curl":"curl -X DELETE https://trygrowthchicken.com/api/v1/projects/YOUR_PROJECT_SLUG/assets/YOUR_ASSET_ID \\\n  -H \"Authorization: Bearer $GROWTH_CHICKEN_API_TOKEN\""},{"group":"Assets","method":"GET","path":"/api/v1/projects/{project_id}/assets/{id}/file","summary":"Download raw asset file","description":"Bearer-authenticated raw download for the stored asset bytes. Content-Type matches the stored upload.","curl":"curl https://trygrowthchicken.com/api/v1/projects/YOUR_PROJECT_SLUG/assets/YOUR_ASSET_ID/file \\\n  -H \"Authorization: Bearer $GROWTH_CHICKEN_API_TOKEN\""},{"group":"Ads","method":"GET","path":"/api/v1/ads","summary":"List ads across the account","curl":"curl https://trygrowthchicken.com/api/v1/ads \\\n  -H \"Authorization: Bearer $GROWTH_CHICKEN_API_TOKEN\"","response_example":{"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,"output":"video","output_label":"Video ad","style":{"category":"template","template_key":"poster_hero"},"editable_copy":{"headline":"Ship campaigns in minutes"},"remix":{"available":false,"targets":[],"elements":[]},"audience_id":"00000000-0000-0000-0000-000000000101","platform_aspect":"9:16","placements":["instagram_story","feed_portrait","square","landscape"],"music":{"asset_id":"00000000-0000-0000-0000-000000000501","filename":"launchpad-music-1.mp3","provider":"suno","duration_seconds":5.0},"tags":["launch","winner"],"external_identifiers":{"meta_ad_id":"23851234567890123"},"distribution":{"current_status":"live","total_runs_count":1,"active_runs_count":1,"platforms":["meta"],"metrics_summary":{"spend":"42.50","currency":"USD","impressions":12000,"clicks":188,"ctr":"1.57","cpc":"0.23","cpm":"3.54","conversions":7.0,"cpa":"6.07","revenue":"210.00","roas":"4.94"}},"ad_runs":[{"id":"00000000-0000-0000-0000-000000000601","creative_composition_id":"00000000-0000-0000-0000-000000000401","project_id":"00000000-0000-0000-0000-000000000001","user_id":"00000000-0000-0000-0000-000000000301","platform":"meta","channel":"paid_social","objective":"traffic","current_status":"live","first_live_at":"2026-07-03T09:00:00Z","last_live_at":"2026-07-03T09:00:00Z","ended_at":null,"last_observed_at":"2026-07-06T12:00:00Z","source":"agent","external_account_id":"act_123","external_campaign_id":"cmp_123","external_ad_group_id":"set_123","external_ad_id":"ad_123","external_url":"https://ads.example.test/ad_123","metrics_summary":{"spend":"42.50","currency":"USD","impressions":12000,"clicks":188,"ctr":"1.57","cpc":"0.23","cpm":"3.54"},"health":{"trend":"steady","recent_ctr":"1.57","previous_ctr":"1.50","change_pct":4.7,"z_score":0.82,"statistically_significant":false,"recent_impressions":12000,"previous_impressions":11000,"as_of":"2026-07-05","availability":{"frequency":false}},"cost":{"cpc":"0.23","cpm":"3.54","currency":"USD"},"delivery":{"status":"healthy","share_pct":62.5,"impressions":12000,"ad_group_impressions":19200,"as_of":"2026-07-05","window_start":"2026-07-03","window_end":"2026-07-05","availability":{"available":true}},"rank":{"metric":"cpa","position":1,"group_size":2,"percentile":100},"metadata":{"owner":"agent"},"observations_count":2,"created_at":"2026-07-06T12:00:00Z","updated_at":"2026-07-06T12:00:00Z"}],"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","video_url":"http://localhost:3000/api/v1/projects/launchpad/ads/summer-sale/file.mp4?placement=instagram_story","still_url":"http://localhost:3000/api/v1/projects/launchpad/ads/summer-sale/file.png?placement=instagram_story","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","video_url":"http://localhost:3000/api/v1/projects/launchpad/ads/summer-sale/file.mp4?placement=square","still_url":"http://localhost:3000/api/v1/projects/launchpad/ads/summer-sale/file.png?placement=square"}],"snapshots":[]}]}},{"group":"Ads","method":"GET","path":"/api/v1/projects/{project_id}/ads","summary":"List ads","curl":"curl https://trygrowthchicken.com/api/v1/projects/YOUR_PROJECT_SLUG/ads \\\n  -H \"Authorization: Bearer $GROWTH_CHICKEN_API_TOKEN\"","response_example":{"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,"output":"video","output_label":"Video ad","style":{"category":"template","template_key":"poster_hero"},"editable_copy":{"headline":"Ship campaigns in minutes"},"remix":{"available":false,"targets":[],"elements":[]},"audience_id":"00000000-0000-0000-0000-000000000101","platform_aspect":"9:16","placements":["instagram_story","feed_portrait","square","landscape"],"music":{"asset_id":"00000000-0000-0000-0000-000000000501","filename":"launchpad-music-1.mp3","provider":"suno","duration_seconds":5.0},"tags":["launch","winner"],"external_identifiers":{"meta_ad_id":"23851234567890123"},"distribution":{"current_status":"live","total_runs_count":1,"active_runs_count":1,"platforms":["meta"],"metrics_summary":{"spend":"42.50","currency":"USD","impressions":12000,"clicks":188,"ctr":"1.57","cpc":"0.23","cpm":"3.54","conversions":7.0,"cpa":"6.07","revenue":"210.00","roas":"4.94"}},"ad_runs":[{"id":"00000000-0000-0000-0000-000000000601","creative_composition_id":"00000000-0000-0000-0000-000000000401","project_id":"00000000-0000-0000-0000-000000000001","user_id":"00000000-0000-0000-0000-000000000301","platform":"meta","channel":"paid_social","objective":"traffic","current_status":"live","first_live_at":"2026-07-03T09:00:00Z","last_live_at":"2026-07-03T09:00:00Z","ended_at":null,"last_observed_at":"2026-07-06T12:00:00Z","source":"agent","external_account_id":"act_123","external_campaign_id":"cmp_123","external_ad_group_id":"set_123","external_ad_id":"ad_123","external_url":"https://ads.example.test/ad_123","metrics_summary":{"spend":"42.50","currency":"USD","impressions":12000,"clicks":188,"ctr":"1.57","cpc":"0.23","cpm":"3.54"},"health":{"trend":"steady","recent_ctr":"1.57","previous_ctr":"1.50","change_pct":4.7,"z_score":0.82,"statistically_significant":false,"recent_impressions":12000,"previous_impressions":11000,"as_of":"2026-07-05","availability":{"frequency":false}},"cost":{"cpc":"0.23","cpm":"3.54","currency":"USD"},"delivery":{"status":"healthy","share_pct":62.5,"impressions":12000,"ad_group_impressions":19200,"as_of":"2026-07-05","window_start":"2026-07-03","window_end":"2026-07-05","availability":{"available":true}},"rank":{"metric":"cpa","position":1,"group_size":2,"percentile":100},"metadata":{"owner":"agent"},"observations_count":2,"created_at":"2026-07-06T12:00:00Z","updated_at":"2026-07-06T12:00:00Z"}],"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","video_url":"http://localhost:3000/api/v1/projects/launchpad/ads/summer-sale/file.mp4?placement=instagram_story","still_url":"http://localhost:3000/api/v1/projects/launchpad/ads/summer-sale/file.png?placement=instagram_story","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","video_url":"http://localhost:3000/api/v1/projects/launchpad/ads/summer-sale/file.mp4?placement=square","still_url":"http://localhost:3000/api/v1/projects/launchpad/ads/summer-sale/file.png?placement=square"}],"snapshots":[]}]}},{"group":"Ads","method":"POST","path":"/api/v1/projects/{project_id}/ads","summary":"Generate an ad","description":"Generates one or more ads asynchronously (returns 202 with the generating ads and their poll_urls). Every choice the New Ad form offers is available here and runs through the same validation: pick the deliverable with output (image = Still ad, video = Video ad), let selection choose a style with style_scope (any/templates/memes) or pin one with template_key or meme_base, and steer the cast with character_direction. Incompatible combinations are rejected with 422 validation_failed before any tokens are spent - notably memes are still-only (no video), and template_key and meme_base are mutually exclusive.","curl":"curl -X POST https://trygrowthchicken.com/api/v1/projects/YOUR_PROJECT_SLUG/ads \\\n  -H \"Authorization: Bearer $GROWTH_CHICKEN_API_TOKEN\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"ad\":{\"output\":\"image\",\"style_scope\":\"any\",\"template_key\":\"poster_hero\",\"meme_base\":null,\"character_direction\":null,\"prompt\":\"Bold launch ad highlighting the new dashboard.\",\"copy\":\"Ship campaigns in minutes\",\"copy_mode\":\"exact\",\"audience_id\":\"00000000-0000-0000-0000-000000000101\",\"tags\":[\"launch\",\"winner\"],\"variant_count\":1}}'","request_example":{"ad":{"output":"image","style_scope":"any","template_key":"poster_hero","meme_base":null,"character_direction":null,"prompt":"Bold launch ad highlighting the new dashboard.","copy":"Ship campaigns in minutes","copy_mode":"exact","audience_id":"00000000-0000-0000-0000-000000000101","tags":["launch","winner"],"variant_count":1}},"response_example":{"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,"output":"video","output_label":"Video ad","style":{"category":"template","template_key":"poster_hero"},"editable_copy":{"headline":"Ship campaigns in minutes"},"remix":{"available":false,"targets":[],"elements":[]},"audience_id":"00000000-0000-0000-0000-000000000101","platform_aspect":"9:16","placements":["instagram_story","feed_portrait","square","landscape"],"music":{"asset_id":"00000000-0000-0000-0000-000000000501","filename":"launchpad-music-1.mp3","provider":"suno","duration_seconds":5.0},"tags":["launch","winner"],"external_identifiers":{"meta_ad_id":"23851234567890123"},"distribution":{"current_status":"live","total_runs_count":1,"active_runs_count":1,"platforms":["meta"],"metrics_summary":{"spend":"42.50","currency":"USD","impressions":12000,"clicks":188,"ctr":"1.57","cpc":"0.23","cpm":"3.54","conversions":7.0,"cpa":"6.07","revenue":"210.00","roas":"4.94"}},"ad_runs":[{"id":"00000000-0000-0000-0000-000000000601","creative_composition_id":"00000000-0000-0000-0000-000000000401","project_id":"00000000-0000-0000-0000-000000000001","user_id":"00000000-0000-0000-0000-000000000301","platform":"meta","channel":"paid_social","objective":"traffic","current_status":"live","first_live_at":"2026-07-03T09:00:00Z","last_live_at":"2026-07-03T09:00:00Z","ended_at":null,"last_observed_at":"2026-07-06T12:00:00Z","source":"agent","external_account_id":"act_123","external_campaign_id":"cmp_123","external_ad_group_id":"set_123","external_ad_id":"ad_123","external_url":"https://ads.example.test/ad_123","metrics_summary":{"spend":"42.50","currency":"USD","impressions":12000,"clicks":188,"ctr":"1.57","cpc":"0.23","cpm":"3.54"},"health":{"trend":"steady","recent_ctr":"1.57","previous_ctr":"1.50","change_pct":4.7,"z_score":0.82,"statistically_significant":false,"recent_impressions":12000,"previous_impressions":11000,"as_of":"2026-07-05","availability":{"frequency":false}},"cost":{"cpc":"0.23","cpm":"3.54","currency":"USD"},"delivery":{"status":"healthy","share_pct":62.5,"impressions":12000,"ad_group_impressions":19200,"as_of":"2026-07-05","window_start":"2026-07-03","window_end":"2026-07-05","availability":{"available":true}},"rank":{"metric":"cpa","position":1,"group_size":2,"percentile":100},"metadata":{"owner":"agent"},"observations_count":2,"created_at":"2026-07-06T12:00:00Z","updated_at":"2026-07-06T12:00:00Z"}],"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","video_url":"http://localhost:3000/api/v1/projects/launchpad/ads/summer-sale/file.mp4?placement=instagram_story","still_url":"http://localhost:3000/api/v1/projects/launchpad/ads/summer-sale/file.png?placement=instagram_story","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","video_url":"http://localhost:3000/api/v1/projects/launchpad/ads/summer-sale/file.mp4?placement=square","still_url":"http://localhost:3000/api/v1/projects/launchpad/ads/summer-sale/file.png?placement=square"}],"snapshots":[]}}},{"group":"Ads","method":"GET","path":"/api/v1/projects/{project_id}/ads/{id}","summary":"Get ad (poll status and asset URLs)","curl":"curl https://trygrowthchicken.com/api/v1/projects/YOUR_PROJECT_SLUG/ads/YOUR_AD_ID_OR_SLUG \\\n  -H \"Authorization: Bearer $GROWTH_CHICKEN_API_TOKEN\"","response_example":{"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,"output":"video","output_label":"Video ad","style":{"category":"template","template_key":"poster_hero"},"editable_copy":{"headline":"Ship campaigns in minutes"},"remix":{"available":false,"targets":[],"elements":[]},"audience_id":"00000000-0000-0000-0000-000000000101","platform_aspect":"9:16","placements":["instagram_story","feed_portrait","square","landscape"],"music":{"asset_id":"00000000-0000-0000-0000-000000000501","filename":"launchpad-music-1.mp3","provider":"suno","duration_seconds":5.0},"tags":["launch","winner"],"external_identifiers":{"meta_ad_id":"23851234567890123"},"distribution":{"current_status":"live","total_runs_count":1,"active_runs_count":1,"platforms":["meta"],"metrics_summary":{"spend":"42.50","currency":"USD","impressions":12000,"clicks":188,"ctr":"1.57","cpc":"0.23","cpm":"3.54","conversions":7.0,"cpa":"6.07","revenue":"210.00","roas":"4.94"}},"ad_runs":[{"id":"00000000-0000-0000-0000-000000000601","creative_composition_id":"00000000-0000-0000-0000-000000000401","project_id":"00000000-0000-0000-0000-000000000001","user_id":"00000000-0000-0000-0000-000000000301","platform":"meta","channel":"paid_social","objective":"traffic","current_status":"live","first_live_at":"2026-07-03T09:00:00Z","last_live_at":"2026-07-03T09:00:00Z","ended_at":null,"last_observed_at":"2026-07-06T12:00:00Z","source":"agent","external_account_id":"act_123","external_campaign_id":"cmp_123","external_ad_group_id":"set_123","external_ad_id":"ad_123","external_url":"https://ads.example.test/ad_123","metrics_summary":{"spend":"42.50","currency":"USD","impressions":12000,"clicks":188,"ctr":"1.57","cpc":"0.23","cpm":"3.54"},"health":{"trend":"steady","recent_ctr":"1.57","previous_ctr":"1.50","change_pct":4.7,"z_score":0.82,"statistically_significant":false,"recent_impressions":12000,"previous_impressions":11000,"as_of":"2026-07-05","availability":{"frequency":false}},"cost":{"cpc":"0.23","cpm":"3.54","currency":"USD"},"delivery":{"status":"healthy","share_pct":62.5,"impressions":12000,"ad_group_impressions":19200,"as_of":"2026-07-05","window_start":"2026-07-03","window_end":"2026-07-05","availability":{"available":true}},"rank":{"metric":"cpa","position":1,"group_size":2,"percentile":100},"metadata":{"owner":"agent"},"observations_count":2,"created_at":"2026-07-06T12:00:00Z","updated_at":"2026-07-06T12:00:00Z"}],"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","video_url":"http://localhost:3000/api/v1/projects/launchpad/ads/summer-sale/file.mp4?placement=instagram_story","still_url":"http://localhost:3000/api/v1/projects/launchpad/ads/summer-sale/file.png?placement=instagram_story","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","video_url":"http://localhost:3000/api/v1/projects/launchpad/ads/summer-sale/file.mp4?placement=square","still_url":"http://localhost:3000/api/v1/projects/launchpad/ads/summer-sale/file.png?placement=square"}],"snapshots":[]}}},{"group":"Ads","method":"PATCH","path":"/api/v1/projects/{project_id}/ads/{id}","summary":"Edit ad captions or replace tags","curl":"curl -X PATCH https://trygrowthchicken.com/api/v1/projects/YOUR_PROJECT_SLUG/ads/YOUR_AD_ID_OR_SLUG \\\n  -H \"Authorization: Bearer $GROWTH_CHICKEN_API_TOKEN\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"ad\":{\"tags\":[\"launch\",\"winner\"],\"copy\":{\"setup\":\"Campaign chaos\",\"payoff\":\"Meet one clean dashboard\"}}}'","request_example":{"ad":{"tags":["launch","winner"],"copy":{"setup":"Campaign chaos","payoff":"Meet one clean dashboard"}}},"response_example":{"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,"output":"video","output_label":"Video ad","style":{"category":"template","template_key":"poster_hero"},"editable_copy":{"headline":"Ship campaigns in minutes"},"remix":{"available":false,"targets":[],"elements":[]},"audience_id":"00000000-0000-0000-0000-000000000101","platform_aspect":"9:16","placements":["instagram_story","feed_portrait","square","landscape"],"music":{"asset_id":"00000000-0000-0000-0000-000000000501","filename":"launchpad-music-1.mp3","provider":"suno","duration_seconds":5.0},"tags":["launch","winner"],"external_identifiers":{"meta_ad_id":"23851234567890123"},"distribution":{"current_status":"live","total_runs_count":1,"active_runs_count":1,"platforms":["meta"],"metrics_summary":{"spend":"42.50","currency":"USD","impressions":12000,"clicks":188,"ctr":"1.57","cpc":"0.23","cpm":"3.54","conversions":7.0,"cpa":"6.07","revenue":"210.00","roas":"4.94"}},"ad_runs":[{"id":"00000000-0000-0000-0000-000000000601","creative_composition_id":"00000000-0000-0000-0000-000000000401","project_id":"00000000-0000-0000-0000-000000000001","user_id":"00000000-0000-0000-0000-000000000301","platform":"meta","channel":"paid_social","objective":"traffic","current_status":"live","first_live_at":"2026-07-03T09:00:00Z","last_live_at":"2026-07-03T09:00:00Z","ended_at":null,"last_observed_at":"2026-07-06T12:00:00Z","source":"agent","external_account_id":"act_123","external_campaign_id":"cmp_123","external_ad_group_id":"set_123","external_ad_id":"ad_123","external_url":"https://ads.example.test/ad_123","metrics_summary":{"spend":"42.50","currency":"USD","impressions":12000,"clicks":188,"ctr":"1.57","cpc":"0.23","cpm":"3.54"},"health":{"trend":"steady","recent_ctr":"1.57","previous_ctr":"1.50","change_pct":4.7,"z_score":0.82,"statistically_significant":false,"recent_impressions":12000,"previous_impressions":11000,"as_of":"2026-07-05","availability":{"frequency":false}},"cost":{"cpc":"0.23","cpm":"3.54","currency":"USD"},"delivery":{"status":"healthy","share_pct":62.5,"impressions":12000,"ad_group_impressions":19200,"as_of":"2026-07-05","window_start":"2026-07-03","window_end":"2026-07-05","availability":{"available":true}},"rank":{"metric":"cpa","position":1,"group_size":2,"percentile":100},"metadata":{"owner":"agent"},"observations_count":2,"created_at":"2026-07-06T12:00:00Z","updated_at":"2026-07-06T12:00:00Z"}],"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","video_url":"http://localhost:3000/api/v1/projects/launchpad/ads/summer-sale/file.mp4?placement=instagram_story","still_url":"http://localhost:3000/api/v1/projects/launchpad/ads/summer-sale/file.png?placement=instagram_story","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","video_url":"http://localhost:3000/api/v1/projects/launchpad/ads/summer-sale/file.mp4?placement=square","still_url":"http://localhost:3000/api/v1/projects/launchpad/ads/summer-sale/file.png?placement=square"}],"snapshots":[]}}},{"group":"Ads","method":"DELETE","path":"/api/v1/projects/{project_id}/ads/{id}","summary":"Delete ad","curl":"curl -X DELETE https://trygrowthchicken.com/api/v1/projects/YOUR_PROJECT_SLUG/ads/YOUR_AD_ID_OR_SLUG \\\n  -H \"Authorization: Bearer $GROWTH_CHICKEN_API_TOKEN\""},{"group":"Ads","method":"POST","path":"/api/v1/projects/{project_id}/ads/{id}/remix","summary":"Remix an ad","description":"Creates a new variation at the full target-job cost. Keep the elements you want via `locks` (the ad's background, subject, logo, and each `text:<slot>` line); everything else is regenerated. The template is always kept. Meme sources are just still templates and expose the still output only - never motion or video.","curl":"curl -X POST https://trygrowthchicken.com/api/v1/projects/YOUR_PROJECT_SLUG/ads/YOUR_AD_ID_OR_SLUG/remix \\\n  -H \"Authorization: Bearer $GROWTH_CHICKEN_API_TOKEN\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"remix\":{\"target\":\"still\",\"locks\":[\"background\",\"text:headline\"]}}'","request_example":{"remix":{"target":"still","locks":["background","text:headline"]}},"response_example":{"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,"output":"video","output_label":"Video ad","style":{"category":"template","template_key":"poster_hero"},"editable_copy":{"headline":"Ship campaigns in minutes"},"remix":{"available":false,"targets":[],"elements":[]},"audience_id":"00000000-0000-0000-0000-000000000101","platform_aspect":"9:16","placements":["instagram_story","feed_portrait","square","landscape"],"music":{"asset_id":"00000000-0000-0000-0000-000000000501","filename":"launchpad-music-1.mp3","provider":"suno","duration_seconds":5.0},"tags":["launch","winner"],"external_identifiers":{"meta_ad_id":"23851234567890123"},"distribution":{"current_status":"live","total_runs_count":1,"active_runs_count":1,"platforms":["meta"],"metrics_summary":{"spend":"42.50","currency":"USD","impressions":12000,"clicks":188,"ctr":"1.57","cpc":"0.23","cpm":"3.54","conversions":7.0,"cpa":"6.07","revenue":"210.00","roas":"4.94"}},"ad_runs":[{"id":"00000000-0000-0000-0000-000000000601","creative_composition_id":"00000000-0000-0000-0000-000000000401","project_id":"00000000-0000-0000-0000-000000000001","user_id":"00000000-0000-0000-0000-000000000301","platform":"meta","channel":"paid_social","objective":"traffic","current_status":"live","first_live_at":"2026-07-03T09:00:00Z","last_live_at":"2026-07-03T09:00:00Z","ended_at":null,"last_observed_at":"2026-07-06T12:00:00Z","source":"agent","external_account_id":"act_123","external_campaign_id":"cmp_123","external_ad_group_id":"set_123","external_ad_id":"ad_123","external_url":"https://ads.example.test/ad_123","metrics_summary":{"spend":"42.50","currency":"USD","impressions":12000,"clicks":188,"ctr":"1.57","cpc":"0.23","cpm":"3.54"},"health":{"trend":"steady","recent_ctr":"1.57","previous_ctr":"1.50","change_pct":4.7,"z_score":0.82,"statistically_significant":false,"recent_impressions":12000,"previous_impressions":11000,"as_of":"2026-07-05","availability":{"frequency":false}},"cost":{"cpc":"0.23","cpm":"3.54","currency":"USD"},"delivery":{"status":"healthy","share_pct":62.5,"impressions":12000,"ad_group_impressions":19200,"as_of":"2026-07-05","window_start":"2026-07-03","window_end":"2026-07-05","availability":{"available":true}},"rank":{"metric":"cpa","position":1,"group_size":2,"percentile":100},"metadata":{"owner":"agent"},"observations_count":2,"created_at":"2026-07-06T12:00:00Z","updated_at":"2026-07-06T12:00:00Z"}],"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","video_url":"http://localhost:3000/api/v1/projects/launchpad/ads/summer-sale/file.mp4?placement=instagram_story","still_url":"http://localhost:3000/api/v1/projects/launchpad/ads/summer-sale/file.png?placement=instagram_story","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","video_url":"http://localhost:3000/api/v1/projects/launchpad/ads/summer-sale/file.mp4?placement=square","still_url":"http://localhost:3000/api/v1/projects/launchpad/ads/summer-sale/file.png?placement=square"}],"snapshots":[]}}},{"group":"Ads","method":"GET","path":"/api/v1/projects/{project_id}/ads/{ad_id}/tags","summary":"List tags on an ad","curl":"curl https://trygrowthchicken.com/api/v1/projects/YOUR_PROJECT_SLUG/ads/YOUR_AD_ID_OR_SLUG/tags \\\n  -H \"Authorization: Bearer $GROWTH_CHICKEN_API_TOKEN\"","response_example":{"tags":["launch","winner"]}},{"group":"Ads","method":"POST","path":"/api/v1/projects/{project_id}/ads/{ad_id}/tags","summary":"Add a tag to an ad","curl":"curl -X POST https://trygrowthchicken.com/api/v1/projects/YOUR_PROJECT_SLUG/ads/YOUR_AD_ID_OR_SLUG/tags \\\n  -H \"Authorization: Bearer $GROWTH_CHICKEN_API_TOKEN\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"tag\":\"winner\"}'","request_example":{"tag":"winner"},"response_example":{"tag":"winner","tags":["launch","winner"]}},{"group":"Ads","method":"DELETE","path":"/api/v1/projects/{project_id}/ads/{ad_id}/tags/{id}","summary":"Remove a tag from an ad","curl":"curl -X DELETE https://trygrowthchicken.com/api/v1/projects/YOUR_PROJECT_SLUG/ads/YOUR_AD_ID_OR_SLUG/tags/YOUR_AD_ID_OR_SLUG \\\n  -H \"Authorization: Bearer $GROWTH_CHICKEN_API_TOKEN\""},{"group":"Ads","method":"GET","path":"/api/v1/projects/{project_id}/ads/{id}/file","summary":"Download the rendered asset (mp4/png/jpg) or the editable HTML document","curl":"curl https://trygrowthchicken.com/api/v1/projects/YOUR_PROJECT_SLUG/ads/YOUR_AD_ID_OR_SLUG/file \\\n  -H \"Authorization: Bearer $GROWTH_CHICKEN_API_TOKEN\""},{"group":"External Identifiers","method":"GET","path":"/api/v1/projects/{project_id}/external_identifiers","summary":"List project external identifiers","description":"The project's declared external identity: the key-value pairs (e.g. meta_ad_account, google_customer, product_key) that anchor performance reconciliation to this project.","curl":"curl https://trygrowthchicken.com/api/v1/projects/YOUR_PROJECT_SLUG/external_identifiers \\\n  -H \"Authorization: Bearer $GROWTH_CHICKEN_API_TOKEN\"","response_example":{"external_identifiers":[{"id":"00000000-0000-0000-0000-000000000601","owner":{"type":"project","id":"00000000-0000-0000-0000-000000000001"},"key":"meta_ad_account","value":"act_1234567890","created_at":"2026-06-20T12:00:00Z","updated_at":"2026-06-20T12:00:00Z"}]}},{"group":"External Identifiers","method":"POST","path":"/api/v1/projects/{project_id}/external_identifiers","summary":"Set a project external identifier","description":"Declares one key-value pair. A pair resolves to a single project, so claiming an account already declared elsewhere fails validation.","curl":"curl -X POST https://trygrowthchicken.com/api/v1/projects/YOUR_PROJECT_SLUG/external_identifiers \\\n  -H \"Authorization: Bearer $GROWTH_CHICKEN_API_TOKEN\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"external_identifier\":{\"key\":\"meta_ad_account\",\"value\":\"act_1234567890\"}}'","request_example":{"external_identifier":{"key":"meta_ad_account","value":"act_1234567890"}},"response_example":{"external_identifier":{"id":"00000000-0000-0000-0000-000000000601","owner":{"type":"project","id":"00000000-0000-0000-0000-000000000001"},"key":"meta_ad_account","value":"act_1234567890","created_at":"2026-06-20T12:00:00Z","updated_at":"2026-06-20T12:00:00Z"}}},{"group":"External Identifiers","method":"GET","path":"/api/v1/projects/{project_id}/external_identifiers/{id}","summary":"Get project external identifier","curl":"curl https://trygrowthchicken.com/api/v1/projects/YOUR_PROJECT_SLUG/external_identifiers/YOUR_PROJECT_SLUG \\\n  -H \"Authorization: Bearer $GROWTH_CHICKEN_API_TOKEN\"","response_example":{"external_identifier":{"id":"00000000-0000-0000-0000-000000000601","owner":{"type":"project","id":"00000000-0000-0000-0000-000000000001"},"key":"meta_ad_account","value":"act_1234567890","created_at":"2026-06-20T12:00:00Z","updated_at":"2026-06-20T12:00:00Z"}}},{"group":"External Identifiers","method":"PATCH","path":"/api/v1/projects/{project_id}/external_identifiers/{id}","summary":"Update project external identifier","curl":"curl -X PATCH https://trygrowthchicken.com/api/v1/projects/YOUR_PROJECT_SLUG/external_identifiers/YOUR_PROJECT_SLUG \\\n  -H \"Authorization: Bearer $GROWTH_CHICKEN_API_TOKEN\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"external_identifier\":{\"key\":\"meta_ad_account\",\"value\":\"act_1234567890\"}}'","request_example":{"external_identifier":{"key":"meta_ad_account","value":"act_1234567890"}},"response_example":{"external_identifier":{"id":"00000000-0000-0000-0000-000000000601","owner":{"type":"project","id":"00000000-0000-0000-0000-000000000001"},"key":"meta_ad_account","value":"act_1234567890","created_at":"2026-06-20T12:00:00Z","updated_at":"2026-06-20T12:00:00Z"}}},{"group":"External Identifiers","method":"DELETE","path":"/api/v1/projects/{project_id}/external_identifiers/{id}","summary":"Delete project external identifier","curl":"curl -X DELETE https://trygrowthchicken.com/api/v1/projects/YOUR_PROJECT_SLUG/external_identifiers/YOUR_PROJECT_SLUG \\\n  -H \"Authorization: Bearer $GROWTH_CHICKEN_API_TOKEN\""},{"group":"External Identifiers","method":"GET","path":"/api/v1/projects/{project_id}/ads/{ad_id}/external_identifiers","summary":"List ad external identifiers","description":"The ad's declared external identity: key-value pairs recording the platform ad's identifiers once known.","curl":"curl https://trygrowthchicken.com/api/v1/projects/YOUR_PROJECT_SLUG/ads/YOUR_AD_ID_OR_SLUG/external_identifiers \\\n  -H \"Authorization: Bearer $GROWTH_CHICKEN_API_TOKEN\"","response_example":{"external_identifiers":[{"id":"00000000-0000-0000-0000-000000000601","owner":{"type":"ad","id":"00000000-0000-0000-0000-000000000401"},"key":"meta_ad_id","value":"23851234567890123","created_at":"2026-06-20T12:00:00Z","updated_at":"2026-06-20T12:00:00Z"}]}},{"group":"External Identifiers","method":"POST","path":"/api/v1/projects/{project_id}/ads/{ad_id}/external_identifiers","summary":"Set an ad external identifier","curl":"curl -X POST https://trygrowthchicken.com/api/v1/projects/YOUR_PROJECT_SLUG/ads/YOUR_AD_ID_OR_SLUG/external_identifiers \\\n  -H \"Authorization: Bearer $GROWTH_CHICKEN_API_TOKEN\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"external_identifier\":{\"key\":\"meta_ad_account\",\"value\":\"act_1234567890\"}}'","request_example":{"external_identifier":{"key":"meta_ad_account","value":"act_1234567890"}},"response_example":{"external_identifier":{"id":"00000000-0000-0000-0000-000000000601","owner":{"type":"ad","id":"00000000-0000-0000-0000-000000000401"},"key":"meta_ad_id","value":"23851234567890123","created_at":"2026-06-20T12:00:00Z","updated_at":"2026-06-20T12:00:00Z"}}},{"group":"External Identifiers","method":"GET","path":"/api/v1/projects/{project_id}/ads/{ad_id}/external_identifiers/{id}","summary":"Get ad external identifier","curl":"curl https://trygrowthchicken.com/api/v1/projects/YOUR_PROJECT_SLUG/ads/YOUR_AD_ID_OR_SLUG/external_identifiers/YOUR_AD_ID_OR_SLUG \\\n  -H \"Authorization: Bearer $GROWTH_CHICKEN_API_TOKEN\"","response_example":{"external_identifier":{"id":"00000000-0000-0000-0000-000000000601","owner":{"type":"ad","id":"00000000-0000-0000-0000-000000000401"},"key":"meta_ad_id","value":"23851234567890123","created_at":"2026-06-20T12:00:00Z","updated_at":"2026-06-20T12:00:00Z"}}},{"group":"External Identifiers","method":"PATCH","path":"/api/v1/projects/{project_id}/ads/{ad_id}/external_identifiers/{id}","summary":"Update ad external identifier","curl":"curl -X PATCH https://trygrowthchicken.com/api/v1/projects/YOUR_PROJECT_SLUG/ads/YOUR_AD_ID_OR_SLUG/external_identifiers/YOUR_AD_ID_OR_SLUG \\\n  -H \"Authorization: Bearer $GROWTH_CHICKEN_API_TOKEN\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"external_identifier\":{\"key\":\"meta_ad_account\",\"value\":\"act_1234567890\"}}'","request_example":{"external_identifier":{"key":"meta_ad_account","value":"act_1234567890"}},"response_example":{"external_identifier":{"id":"00000000-0000-0000-0000-000000000601","owner":{"type":"ad","id":"00000000-0000-0000-0000-000000000401"},"key":"meta_ad_id","value":"23851234567890123","created_at":"2026-06-20T12:00:00Z","updated_at":"2026-06-20T12:00:00Z"}}},{"group":"External Identifiers","method":"DELETE","path":"/api/v1/projects/{project_id}/ads/{ad_id}/external_identifiers/{id}","summary":"Delete ad external identifier","curl":"curl -X DELETE https://trygrowthchicken.com/api/v1/projects/YOUR_PROJECT_SLUG/ads/YOUR_AD_ID_OR_SLUG/external_identifiers/YOUR_AD_ID_OR_SLUG \\\n  -H \"Authorization: Bearer $GROWTH_CHICKEN_API_TOKEN\""},{"group":"Ad Runs","method":"GET","path":"/api/v1/projects/{project_id}/ads/{ad_id}/runs","summary":"List ad runs","description":"Returns external distribution runs for one ad. Each run is one platform or campaign placement for the creative, with projected status and rolled-up metrics from observations.","curl":"curl https://trygrowthchicken.com/api/v1/projects/YOUR_PROJECT_SLUG/ads/YOUR_AD_ID_OR_SLUG/runs \\\n  -H \"Authorization: Bearer $GROWTH_CHICKEN_API_TOKEN\"","response_example":{"ad_runs":[{"id":"00000000-0000-0000-0000-000000000601","creative_composition_id":"00000000-0000-0000-0000-000000000401","project_id":"00000000-0000-0000-0000-000000000001","user_id":"00000000-0000-0000-0000-000000000301","platform":"meta","channel":"paid_social","objective":"traffic","current_status":"live","first_live_at":"2026-07-03T09:00:00Z","last_live_at":"2026-07-03T09:00:00Z","ended_at":null,"last_observed_at":"2026-07-06T12:00:00Z","source":"agent","external_account_id":"act_123","external_campaign_id":"cmp_123","external_ad_group_id":"set_123","external_ad_id":"ad_123","external_url":"https://ads.example.test/ad_123","metrics_summary":{"spend":"42.50","currency":"USD","impressions":12000,"clicks":188,"ctr":"1.57","cpc":"0.23","cpm":"3.54"},"health":{"trend":"steady","recent_ctr":"1.57","previous_ctr":"1.50","change_pct":4.7,"z_score":0.82,"statistically_significant":false,"recent_impressions":12000,"previous_impressions":11000,"as_of":"2026-07-05","availability":{"frequency":false}},"cost":{"cpc":"0.23","cpm":"3.54","currency":"USD"},"delivery":{"status":"healthy","share_pct":62.5,"impressions":12000,"ad_group_impressions":19200,"as_of":"2026-07-05","window_start":"2026-07-03","window_end":"2026-07-05","availability":{"available":true}},"rank":{"metric":"cpa","position":1,"group_size":2,"percentile":100},"metadata":{"owner":"agent"},"observations_count":2,"created_at":"2026-07-06T12:00:00Z","updated_at":"2026-07-06T12:00:00Z"}]}},{"group":"Ad Runs","method":"POST","path":"/api/v1/projects/{project_id}/ads/{ad_id}/runs","summary":"Create ad run","description":"Creates the external distribution identity for an ad. Use observations to report lifecycle changes, timeline facts, platform snapshots, and metrics after the run exists.","curl":"curl -X POST https://trygrowthchicken.com/api/v1/projects/YOUR_PROJECT_SLUG/ads/YOUR_AD_ID_OR_SLUG/runs \\\n  -H \"Authorization: Bearer $GROWTH_CHICKEN_API_TOKEN\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"ad_run\":{\"platform\":\"meta\",\"channel\":\"paid_social\",\"objective\":\"traffic\",\"external_account_id\":\"act_123\",\"external_campaign_id\":\"cmp_123\",\"external_ad_group_id\":\"set_123\",\"external_ad_id\":\"ad_123\",\"external_url\":\"https://ads.example.test/ad_123\",\"metadata\":{\"owner\":\"agent\"}}}'","request_example":{"ad_run":{"platform":"meta","channel":"paid_social","objective":"traffic","external_account_id":"act_123","external_campaign_id":"cmp_123","external_ad_group_id":"set_123","external_ad_id":"ad_123","external_url":"https://ads.example.test/ad_123","metadata":{"owner":"agent"}}},"response_example":{"ad_run":{"id":"00000000-0000-0000-0000-000000000601","creative_composition_id":"00000000-0000-0000-0000-000000000401","project_id":"00000000-0000-0000-0000-000000000001","user_id":"00000000-0000-0000-0000-000000000301","platform":"meta","channel":"paid_social","objective":"traffic","current_status":"live","first_live_at":"2026-07-03T09:00:00Z","last_live_at":"2026-07-03T09:00:00Z","ended_at":null,"last_observed_at":"2026-07-06T12:00:00Z","source":"agent","external_account_id":"act_123","external_campaign_id":"cmp_123","external_ad_group_id":"set_123","external_ad_id":"ad_123","external_url":"https://ads.example.test/ad_123","metrics_summary":{"spend":"42.50","currency":"USD","impressions":12000,"clicks":188,"ctr":"1.57","cpc":"0.23","cpm":"3.54"},"health":{"trend":"steady","recent_ctr":"1.57","previous_ctr":"1.50","change_pct":4.7,"z_score":0.82,"statistically_significant":false,"recent_impressions":12000,"previous_impressions":11000,"as_of":"2026-07-05","availability":{"frequency":false}},"cost":{"cpc":"0.23","cpm":"3.54","currency":"USD"},"delivery":{"status":"healthy","share_pct":62.5,"impressions":12000,"ad_group_impressions":19200,"as_of":"2026-07-05","window_start":"2026-07-03","window_end":"2026-07-05","availability":{"available":true}},"rank":{"metric":"cpa","position":1,"group_size":2,"percentile":100},"metadata":{"owner":"agent"},"observations_count":2,"created_at":"2026-07-06T12:00:00Z","updated_at":"2026-07-06T12:00:00Z"}}},{"group":"Ad Runs","method":"GET","path":"/api/v1/projects/{project_id}/ads/{ad_id}/runs/{id}","summary":"Get ad run","description":"Returns the distribution identity plus current projected status, timeline, and metric summary for one run.","curl":"curl https://trygrowthchicken.com/api/v1/projects/YOUR_PROJECT_SLUG/ads/YOUR_AD_ID_OR_SLUG/runs/YOUR_AD_RUN_ID \\\n  -H \"Authorization: Bearer $GROWTH_CHICKEN_API_TOKEN\"","response_example":{"ad_run":{"id":"00000000-0000-0000-0000-000000000601","creative_composition_id":"00000000-0000-0000-0000-000000000401","project_id":"00000000-0000-0000-0000-000000000001","user_id":"00000000-0000-0000-0000-000000000301","platform":"meta","channel":"paid_social","objective":"traffic","current_status":"live","first_live_at":"2026-07-03T09:00:00Z","last_live_at":"2026-07-03T09:00:00Z","ended_at":null,"last_observed_at":"2026-07-06T12:00:00Z","source":"agent","external_account_id":"act_123","external_campaign_id":"cmp_123","external_ad_group_id":"set_123","external_ad_id":"ad_123","external_url":"https://ads.example.test/ad_123","metrics_summary":{"spend":"42.50","currency":"USD","impressions":12000,"clicks":188,"ctr":"1.57","cpc":"0.23","cpm":"3.54"},"health":{"trend":"steady","recent_ctr":"1.57","previous_ctr":"1.50","change_pct":4.7,"z_score":0.82,"statistically_significant":false,"recent_impressions":12000,"previous_impressions":11000,"as_of":"2026-07-05","availability":{"frequency":false}},"cost":{"cpc":"0.23","cpm":"3.54","currency":"USD"},"delivery":{"status":"healthy","share_pct":62.5,"impressions":12000,"ad_group_impressions":19200,"as_of":"2026-07-05","window_start":"2026-07-03","window_end":"2026-07-05","availability":{"available":true}},"rank":{"metric":"cpa","position":1,"group_size":2,"percentile":100},"metadata":{"owner":"agent"},"observations_count":2,"created_at":"2026-07-06T12:00:00Z","updated_at":"2026-07-06T12:00:00Z"}}},{"group":"Ad Runs","method":"PATCH","path":"/api/v1/projects/{project_id}/ads/{ad_id}/runs/{id}","summary":"Update ad run","description":"Updates stable run identity fields such as platform, channel, external ids, and metadata. Timeline projections are recomputed from observations.","curl":"curl -X PATCH https://trygrowthchicken.com/api/v1/projects/YOUR_PROJECT_SLUG/ads/YOUR_AD_ID_OR_SLUG/runs/YOUR_AD_RUN_ID \\\n  -H \"Authorization: Bearer $GROWTH_CHICKEN_API_TOKEN\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"ad_run\":{\"platform\":\"meta\",\"channel\":\"paid_social\",\"objective\":\"traffic\",\"external_account_id\":\"act_123\",\"external_campaign_id\":\"cmp_123\",\"external_ad_group_id\":\"set_123\",\"external_ad_id\":\"ad_123\",\"external_url\":\"https://ads.example.test/ad_123\",\"metadata\":{\"owner\":\"agent\"}}}'","request_example":{"ad_run":{"platform":"meta","channel":"paid_social","objective":"traffic","external_account_id":"act_123","external_campaign_id":"cmp_123","external_ad_group_id":"set_123","external_ad_id":"ad_123","external_url":"https://ads.example.test/ad_123","metadata":{"owner":"agent"}}},"response_example":{"ad_run":{"id":"00000000-0000-0000-0000-000000000601","creative_composition_id":"00000000-0000-0000-0000-000000000401","project_id":"00000000-0000-0000-0000-000000000001","user_id":"00000000-0000-0000-0000-000000000301","platform":"meta","channel":"paid_social","objective":"traffic","current_status":"live","first_live_at":"2026-07-03T09:00:00Z","last_live_at":"2026-07-03T09:00:00Z","ended_at":null,"last_observed_at":"2026-07-06T12:00:00Z","source":"agent","external_account_id":"act_123","external_campaign_id":"cmp_123","external_ad_group_id":"set_123","external_ad_id":"ad_123","external_url":"https://ads.example.test/ad_123","metrics_summary":{"spend":"42.50","currency":"USD","impressions":12000,"clicks":188,"ctr":"1.57","cpc":"0.23","cpm":"3.54"},"health":{"trend":"steady","recent_ctr":"1.57","previous_ctr":"1.50","change_pct":4.7,"z_score":0.82,"statistically_significant":false,"recent_impressions":12000,"previous_impressions":11000,"as_of":"2026-07-05","availability":{"frequency":false}},"cost":{"cpc":"0.23","cpm":"3.54","currency":"USD"},"delivery":{"status":"healthy","share_pct":62.5,"impressions":12000,"ad_group_impressions":19200,"as_of":"2026-07-05","window_start":"2026-07-03","window_end":"2026-07-05","availability":{"available":true}},"rank":{"metric":"cpa","position":1,"group_size":2,"percentile":100},"metadata":{"owner":"agent"},"observations_count":2,"created_at":"2026-07-06T12:00:00Z","updated_at":"2026-07-06T12:00:00Z"}}},{"group":"Ad Runs","method":"DELETE","path":"/api/v1/projects/{project_id}/ads/{ad_id}/runs/{id}","summary":"Delete ad run","description":"Deletes the run and its observations.","curl":"curl -X DELETE https://trygrowthchicken.com/api/v1/projects/YOUR_PROJECT_SLUG/ads/YOUR_AD_ID_OR_SLUG/runs/YOUR_AD_RUN_ID \\\n  -H \"Authorization: Bearer $GROWTH_CHICKEN_API_TOKEN\""},{"group":"Observations","method":"GET","path":"/api/v1/ad_runs/{ad_run_id}/observations","summary":"List ad run observations","curl":"curl https://trygrowthchicken.com/api/v1/ad_runs/YOUR_AD_RUN_ID/observations \\\n  -H \"Authorization: Bearer $GROWTH_CHICKEN_API_TOKEN\"","response_example":{"ad_observations":[{"id":"00000000-0000-0000-0000-000000000701","ad_run_id":"00000000-0000-0000-0000-000000000601","creative_composition_id":"00000000-0000-0000-0000-000000000401","project_id":"00000000-0000-0000-0000-000000000001","user_id":"00000000-0000-0000-0000-000000000301","kind":"lifecycle","source":"agent","observed_at":"2026-07-06T12:00:00Z","effective_at":"2026-07-03T09:00:00Z","interval_start":null,"interval_end":null,"grain":null,"currency":null,"conversion_event":null,"attribution":null,"attribution_window":null,"lifecycle_event":"activated","note":null,"metrics":{},"metadata":{"reported_by":"agent"},"idempotency_key":"agent-activation-123","created_at":"2026-07-06T12:00:00Z","updated_at":"2026-07-06T12:00:00Z"}]}},{"group":"Observations","method":"POST","path":"/api/v1/ad_runs/{ad_run_id}/observations","summary":"Create ad run observation","description":"Synchronously validates and stores one canonical fact. Returns 201 when created, 200 for an identical replay, 409 when the same source and idempotency_key carry different canonical content, and 422 for malformed input. observed_at is the provider snapshot or version time; created_at is Growth Chicken receipt time. Metric observations roll up only across compatible intervals, conversion identities, and currencies. A corrected interval uses a new versioned key and later observed_at. Delayed older snapshots never supersede newer ones. Conversion facts require a stable conversion_event and canonical attribution. Spend and revenue require an explicit ISO 4217 currency. Provider action arrays and raw response blobs are rejected: producers must select one intended outcome and send its normalized scalar value. Recommended idempotency keys use the provider event/version ID; otherwise use a canonical content fingerprint.","curl":"curl -X POST https://trygrowthchicken.com/api/v1/ad_runs/YOUR_AD_RUN_ID/observations \\\n  -H \"Authorization: Bearer $GROWTH_CHICKEN_API_TOKEN\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"ad_observation\":{\"kind\":\"lifecycle\",\"source\":\"agent\",\"observed_at\":\"2026-07-06T12:00:00Z\",\"effective_at\":\"2026-07-03T09:00:00Z\",\"lifecycle_event\":\"activated\",\"idempotency_key\":\"meta:event:activate-123\"}}'","request_example":{"ad_observation":{"kind":"lifecycle","source":"agent","observed_at":"2026-07-06T12:00:00Z","effective_at":"2026-07-03T09:00:00Z","lifecycle_event":"activated","idempotency_key":"meta:event:activate-123"}},"response_example":{"ad_observation":{"id":"00000000-0000-0000-0000-000000000701","ad_run_id":"00000000-0000-0000-0000-000000000601","creative_composition_id":"00000000-0000-0000-0000-000000000401","project_id":"00000000-0000-0000-0000-000000000001","user_id":"00000000-0000-0000-0000-000000000301","kind":"lifecycle","source":"agent","observed_at":"2026-07-06T12:00:00Z","effective_at":"2026-07-03T09:00:00Z","interval_start":null,"interval_end":null,"grain":null,"currency":null,"conversion_event":null,"attribution":null,"attribution_window":null,"lifecycle_event":"activated","note":null,"metrics":{},"metadata":{"reported_by":"agent"},"idempotency_key":"agent-activation-123","created_at":"2026-07-06T12:00:00Z","updated_at":"2026-07-06T12:00:00Z"},"ad_run":{"id":"00000000-0000-0000-0000-000000000601","creative_composition_id":"00000000-0000-0000-0000-000000000401","project_id":"00000000-0000-0000-0000-000000000001","user_id":"00000000-0000-0000-0000-000000000301","platform":"meta","channel":"paid_social","objective":"traffic","current_status":"live","first_live_at":"2026-07-03T09:00:00Z","last_live_at":"2026-07-03T09:00:00Z","ended_at":null,"last_observed_at":"2026-07-06T12:00:00Z","source":"agent","external_account_id":"act_123","external_campaign_id":"cmp_123","external_ad_group_id":"set_123","external_ad_id":"ad_123","external_url":"https://ads.example.test/ad_123","metrics_summary":{"spend":"42.50","currency":"USD","impressions":12000,"clicks":188,"ctr":"1.57","cpc":"0.23","cpm":"3.54"},"health":{"trend":"steady","recent_ctr":"1.57","previous_ctr":"1.50","change_pct":4.7,"z_score":0.82,"statistically_significant":false,"recent_impressions":12000,"previous_impressions":11000,"as_of":"2026-07-05","availability":{"frequency":false}},"cost":{"cpc":"0.23","cpm":"3.54","currency":"USD"},"delivery":{"status":"healthy","share_pct":62.5,"impressions":12000,"ad_group_impressions":19200,"as_of":"2026-07-05","window_start":"2026-07-03","window_end":"2026-07-05","availability":{"available":true}},"rank":{"metric":"cpa","position":1,"group_size":2,"percentile":100},"metadata":{"owner":"agent"},"observations_count":2,"created_at":"2026-07-06T12:00:00Z","updated_at":"2026-07-06T12:00:00Z"}}},{"group":"Observations","method":"GET","path":"/api/v1/ad_runs/{ad_run_id}/observations/{id}","summary":"Get ad run observation","description":"Returns one observation and the parent run after applying the observation projection.","curl":"curl https://trygrowthchicken.com/api/v1/ad_runs/YOUR_AD_RUN_ID/observations/YOUR_OBSERVATION_ID \\\n  -H \"Authorization: Bearer $GROWTH_CHICKEN_API_TOKEN\"","response_example":{"ad_observation":{"id":"00000000-0000-0000-0000-000000000701","ad_run_id":"00000000-0000-0000-0000-000000000601","creative_composition_id":"00000000-0000-0000-0000-000000000401","project_id":"00000000-0000-0000-0000-000000000001","user_id":"00000000-0000-0000-0000-000000000301","kind":"lifecycle","source":"agent","observed_at":"2026-07-06T12:00:00Z","effective_at":"2026-07-03T09:00:00Z","interval_start":null,"interval_end":null,"grain":null,"currency":null,"conversion_event":null,"attribution":null,"attribution_window":null,"lifecycle_event":"activated","note":null,"metrics":{},"metadata":{"reported_by":"agent"},"idempotency_key":"agent-activation-123","created_at":"2026-07-06T12:00:00Z","updated_at":"2026-07-06T12:00:00Z"},"ad_run":{"id":"00000000-0000-0000-0000-000000000601","creative_composition_id":"00000000-0000-0000-0000-000000000401","project_id":"00000000-0000-0000-0000-000000000001","user_id":"00000000-0000-0000-0000-000000000301","platform":"meta","channel":"paid_social","objective":"traffic","current_status":"live","first_live_at":"2026-07-03T09:00:00Z","last_live_at":"2026-07-03T09:00:00Z","ended_at":null,"last_observed_at":"2026-07-06T12:00:00Z","source":"agent","external_account_id":"act_123","external_campaign_id":"cmp_123","external_ad_group_id":"set_123","external_ad_id":"ad_123","external_url":"https://ads.example.test/ad_123","metrics_summary":{"spend":"42.50","currency":"USD","impressions":12000,"clicks":188,"ctr":"1.57","cpc":"0.23","cpm":"3.54"},"health":{"trend":"steady","recent_ctr":"1.57","previous_ctr":"1.50","change_pct":4.7,"z_score":0.82,"statistically_significant":false,"recent_impressions":12000,"previous_impressions":11000,"as_of":"2026-07-05","availability":{"frequency":false}},"cost":{"cpc":"0.23","cpm":"3.54","currency":"USD"},"delivery":{"status":"healthy","share_pct":62.5,"impressions":12000,"ad_group_impressions":19200,"as_of":"2026-07-05","window_start":"2026-07-03","window_end":"2026-07-05","availability":{"available":true}},"rank":{"metric":"cpa","position":1,"group_size":2,"percentile":100},"metadata":{"owner":"agent"},"observations_count":2,"created_at":"2026-07-06T12:00:00Z","updated_at":"2026-07-06T12:00:00Z"}}},{"group":"Observations","method":"PATCH","path":"/api/v1/ad_runs/{ad_run_id}/observations/{id}","summary":"Update ad run observation","description":"Synchronously validates and stores one canonical fact. Returns 201 when created, 200 for an identical replay, 409 when the same source and idempotency_key carry different canonical content, and 422 for malformed input. observed_at is the provider snapshot or version time; created_at is Growth Chicken receipt time. Metric observations roll up only across compatible intervals, conversion identities, and currencies. A corrected interval uses a new versioned key and later observed_at. Delayed older snapshots never supersede newer ones. Conversion facts require a stable conversion_event and canonical attribution. Spend and revenue require an explicit ISO 4217 currency. Provider action arrays and raw response blobs are rejected: producers must select one intended outcome and send its normalized scalar value. Recommended idempotency keys use the provider event/version ID; otherwise use a canonical content fingerprint.","curl":"curl -X PATCH https://trygrowthchicken.com/api/v1/ad_runs/YOUR_AD_RUN_ID/observations/YOUR_OBSERVATION_ID \\\n  -H \"Authorization: Bearer $GROWTH_CHICKEN_API_TOKEN\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"ad_observation\":{\"kind\":\"lifecycle\",\"source\":\"agent\",\"observed_at\":\"2026-07-06T12:00:00Z\",\"effective_at\":\"2026-07-03T09:00:00Z\",\"lifecycle_event\":\"activated\",\"idempotency_key\":\"meta:event:activate-123\"}}'","request_example":{"ad_observation":{"kind":"lifecycle","source":"agent","observed_at":"2026-07-06T12:00:00Z","effective_at":"2026-07-03T09:00:00Z","lifecycle_event":"activated","idempotency_key":"meta:event:activate-123"}},"response_example":{"ad_observation":{"id":"00000000-0000-0000-0000-000000000701","ad_run_id":"00000000-0000-0000-0000-000000000601","creative_composition_id":"00000000-0000-0000-0000-000000000401","project_id":"00000000-0000-0000-0000-000000000001","user_id":"00000000-0000-0000-0000-000000000301","kind":"lifecycle","source":"agent","observed_at":"2026-07-06T12:00:00Z","effective_at":"2026-07-03T09:00:00Z","interval_start":null,"interval_end":null,"grain":null,"currency":null,"conversion_event":null,"attribution":null,"attribution_window":null,"lifecycle_event":"activated","note":null,"metrics":{},"metadata":{"reported_by":"agent"},"idempotency_key":"agent-activation-123","created_at":"2026-07-06T12:00:00Z","updated_at":"2026-07-06T12:00:00Z"},"ad_run":{"id":"00000000-0000-0000-0000-000000000601","creative_composition_id":"00000000-0000-0000-0000-000000000401","project_id":"00000000-0000-0000-0000-000000000001","user_id":"00000000-0000-0000-0000-000000000301","platform":"meta","channel":"paid_social","objective":"traffic","current_status":"live","first_live_at":"2026-07-03T09:00:00Z","last_live_at":"2026-07-03T09:00:00Z","ended_at":null,"last_observed_at":"2026-07-06T12:00:00Z","source":"agent","external_account_id":"act_123","external_campaign_id":"cmp_123","external_ad_group_id":"set_123","external_ad_id":"ad_123","external_url":"https://ads.example.test/ad_123","metrics_summary":{"spend":"42.50","currency":"USD","impressions":12000,"clicks":188,"ctr":"1.57","cpc":"0.23","cpm":"3.54"},"health":{"trend":"steady","recent_ctr":"1.57","previous_ctr":"1.50","change_pct":4.7,"z_score":0.82,"statistically_significant":false,"recent_impressions":12000,"previous_impressions":11000,"as_of":"2026-07-05","availability":{"frequency":false}},"cost":{"cpc":"0.23","cpm":"3.54","currency":"USD"},"delivery":{"status":"healthy","share_pct":62.5,"impressions":12000,"ad_group_impressions":19200,"as_of":"2026-07-05","window_start":"2026-07-03","window_end":"2026-07-05","availability":{"available":true}},"rank":{"metric":"cpa","position":1,"group_size":2,"percentile":100},"metadata":{"owner":"agent"},"observations_count":2,"created_at":"2026-07-06T12:00:00Z","updated_at":"2026-07-06T12:00:00Z"}}},{"group":"Observations","method":"DELETE","path":"/api/v1/ad_runs/{ad_run_id}/observations/{id}","summary":"Delete ad run observation","description":"Deletes an observation. The parent run immediately recomputes projected status, dates, and metric summary from the remaining observations.","curl":"curl -X DELETE https://trygrowthchicken.com/api/v1/ad_runs/YOUR_AD_RUN_ID/observations/YOUR_OBSERVATION_ID \\\n  -H \"Authorization: Bearer $GROWTH_CHICKEN_API_TOKEN\""},{"group":"Observations","method":"POST","path":"/api/v1/projects/{project_id}/ads/{ad_id}/observations","summary":"Create observation and find or create its run","description":"Synchronously validates and stores one canonical fact. Returns 201 when created, 200 for an identical replay, 409 when the same source and idempotency_key carry different canonical content, and 422 for malformed input. observed_at is the provider snapshot or version time; created_at is Growth Chicken receipt time. Metric observations roll up only across compatible intervals, conversion identities, and currencies. A corrected interval uses a new versioned key and later observed_at. Delayed older snapshots never supersede newer ones. Conversion facts require a stable conversion_event and canonical attribution. Spend and revenue require an explicit ISO 4217 currency. Provider action arrays and raw response blobs are rejected: producers must select one intended outcome and send its normalized scalar value. Recommended idempotency keys use the provider event/version ID; otherwise use a canonical content fingerprint.","curl":"curl -X POST https://trygrowthchicken.com/api/v1/projects/YOUR_PROJECT_SLUG/ads/YOUR_AD_ID_OR_SLUG/observations \\\n  -H \"Authorization: Bearer $GROWTH_CHICKEN_API_TOKEN\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"ad_observation\":{\"platform\":\"meta\",\"channel\":\"paid_social\",\"external_account_id\":\"account_123\",\"external_ad_id\":\"ad_123\",\"kind\":\"lifecycle\",\"source\":\"agent\",\"observed_at\":\"2026-07-06T12:00:00Z\",\"effective_at\":\"2026-07-03T09:00:00Z\",\"lifecycle_event\":\"activated\",\"idempotency_key\":\"meta:event:activate-123\"}}'","request_example":{"ad_observation":{"platform":"meta","channel":"paid_social","external_account_id":"account_123","external_ad_id":"ad_123","kind":"lifecycle","source":"agent","observed_at":"2026-07-06T12:00:00Z","effective_at":"2026-07-03T09:00:00Z","lifecycle_event":"activated","idempotency_key":"meta:event:activate-123"}},"response_example":{"ad_observation":{"id":"00000000-0000-0000-0000-000000000701","ad_run_id":"00000000-0000-0000-0000-000000000601","creative_composition_id":"00000000-0000-0000-0000-000000000401","project_id":"00000000-0000-0000-0000-000000000001","user_id":"00000000-0000-0000-0000-000000000301","kind":"lifecycle","source":"agent","observed_at":"2026-07-06T12:00:00Z","effective_at":"2026-07-03T09:00:00Z","interval_start":null,"interval_end":null,"grain":null,"currency":null,"conversion_event":null,"attribution":null,"attribution_window":null,"lifecycle_event":"activated","note":null,"metrics":{},"metadata":{"reported_by":"agent"},"idempotency_key":"agent-activation-123","created_at":"2026-07-06T12:00:00Z","updated_at":"2026-07-06T12:00:00Z"},"ad_run":{"id":"00000000-0000-0000-0000-000000000601","creative_composition_id":"00000000-0000-0000-0000-000000000401","project_id":"00000000-0000-0000-0000-000000000001","user_id":"00000000-0000-0000-0000-000000000301","platform":"meta","channel":"paid_social","objective":"traffic","current_status":"live","first_live_at":"2026-07-03T09:00:00Z","last_live_at":"2026-07-03T09:00:00Z","ended_at":null,"last_observed_at":"2026-07-06T12:00:00Z","source":"agent","external_account_id":"act_123","external_campaign_id":"cmp_123","external_ad_group_id":"set_123","external_ad_id":"ad_123","external_url":"https://ads.example.test/ad_123","metrics_summary":{"spend":"42.50","currency":"USD","impressions":12000,"clicks":188,"ctr":"1.57","cpc":"0.23","cpm":"3.54"},"health":{"trend":"steady","recent_ctr":"1.57","previous_ctr":"1.50","change_pct":4.7,"z_score":0.82,"statistically_significant":false,"recent_impressions":12000,"previous_impressions":11000,"as_of":"2026-07-05","availability":{"frequency":false}},"cost":{"cpc":"0.23","cpm":"3.54","currency":"USD"},"delivery":{"status":"healthy","share_pct":62.5,"impressions":12000,"ad_group_impressions":19200,"as_of":"2026-07-05","window_start":"2026-07-03","window_end":"2026-07-05","availability":{"available":true}},"rank":{"metric":"cpa","position":1,"group_size":2,"percentile":100},"metadata":{"owner":"agent"},"observations_count":2,"created_at":"2026-07-06T12:00:00Z","updated_at":"2026-07-06T12:00:00Z"}}}],"specifications":{"html":"https://trygrowthchicken.com/docs/api","openapi_json":"https://trygrowthchicken.com/docs/openapi.json","openapi_yaml":"https://trygrowthchicken.com/docs/openapi.yaml"}}