Greenset API

01Quickstart#

Six calls, from a new key to a stopped campaign.

1. 01

   Step 01: Make a key, then make a call

   Make a key under Developers, then Keys, in Greenset, and set export GREENSET_KEY=<your key>. This call needs the Read scope and changes nothing.

   GET /v1/account

   curlJavaScriptPython

   curl

   curl https://app.greenset.ai/v1/account \
     -H "Authorization: Bearer $GREENSET_KEY"

   JavaScript

   // Node 18 or later. Save as greenset.mjs, then: node greenset.mjs
   
   const res = await fetch("https://app.greenset.ai/v1/account", {
     headers: {
       Authorization: `Bearer ${process.env.GREENSET_KEY}`,
     },
   });
   const data = await res.json();
   if (!res.ok) throw new Error(`${res.status} ${data.error.code}: ${data.error.message}`);
   console.log(data);

   Python

   # Python 3, standard library only.
   import json, os, urllib.request
   from urllib.error import HTTPError
   
   req = urllib.request.Request(
       "https://app.greenset.ai/v1/account",
       headers={
           "Authorization": "Bearer " + os.environ["GREENSET_KEY"],
       },
   )
   try:
       with urllib.request.urlopen(req) as res:
           data = json.load(res)
   except HTTPError as e:
       err = json.load(e)["error"]
       raise SystemExit(f"{e.code} {err['code']}: {err['message']}")
   print(data)

   Answer · 200

   JSON

   {
     "workspace": {
       "name": "Northfield Coffee"
     },
     "ad_account": {
       "id": "biz_LiveChild001",
       "name": "Northfield Coffee",
       "linked_at": "2026-10-01T09:14:02.000Z"
     },
     "setup": [
       {
         "id": "account",
         "status": "pass",
         "fact": "owner@northfieldcoffee.example · confirmed 2026-10-01 09:12 UTC"
       },
       {
         "id": "adaccount",
         "status": "pass",
         "fact": "biz_••d001 · pays from your ad balance · since 2026-10-01 09:14 UTC"
       },
       {
         "id": "facebook",
         "status": "pass",
         "fact": "\"Northfield Coffee\" · sacc••Qp1Z · can advertise"
       },
       {
         "id": "pixel",
         "status": "pass",
         "fact": "Whop confirmed the pixel on northfieldcoffee.example · 2026-10-02 10:30 UTC"
       },
       {
         "id": "balance",
         "status": "pass",
         "fact": "$412.50 available"
       },
       {
         "id": "draft",
         "status": "next",
         "fact": "Draw ads for what you sell in Studio"
       }
     ],
     "balance": {
       "available_usd": 412.5,
       "pending_usd": 0,
       "credits_usd": 0
     },
     "payment_failed": null,
     "caps": {
       "hard_daily_cap_usd": 500,
       "max_single_daily_usd": 238.09,
       "min_daily_budget_usd": 5,
       "overdelivery": 2.1
     },
     "live_writes": {
       "enabled": true
     },
     "quotas": {
       "scrape": {
         "used": 0,
         "limit": 120
       },
       "photos": {
         "used": 0,
         "limit": 40
       },
       "copilot": {
         "used": 0,
         "limit": 200
       },
       "elements": {
         "used": 0,
         "limit": 120
       }
     },
     "key": {
       "id": "key_Ab12Cd34Ef56",
       "name": "Zapier",
       "scopes": [
         "read",
         "stores",
         "studio",
         "drafts",
         "activate",
         "stop"
       ],
       "expires_at": "2026-11-04T13:29:30.000Z"
     },
     "as_of": "2026-10-05T13:31:07.000Z"
   }

   GET /v1/account: every field

2. 02

   Step 02: Connect your store

   Greenset reads the store's public pages and imports its products. It uses one of today's 120 store reads. Needs the Stores scope.

   POST /v1/stores

   curlJavaScriptPython

   curl

   curl -X POST https://app.greenset.ai/v1/stores \
     -H "Authorization: Bearer $GREENSET_KEY" \
     -H "Content-Type: application/json" \
     -H "Idempotency-Key: $(uuidgen)" \
     -d '{
       "url": "https://northfieldcoffee.example"
     }'

   JavaScript

   // Node 18 or later. Save as greenset.mjs, then: node greenset.mjs
   import { randomUUID } from "node:crypto";
   
   const res = await fetch("https://app.greenset.ai/v1/stores", {
     method: "POST",
     headers: {
       Authorization: `Bearer ${process.env.GREENSET_KEY}`,
       "Content-Type": "application/json",
       "Idempotency-Key": randomUUID(),
     },
     body: JSON.stringify({
       "url": "https://northfieldcoffee.example"
     }),
   });
   const data = await res.json();
   if (!res.ok) throw new Error(`${res.status} ${data.error.code}: ${data.error.message}`);
   console.log(data);

   Python

   # Python 3, standard library only.
   import json, os, urllib.request, uuid
   from urllib.error import HTTPError
   
   body = {
       "url": "https://northfieldcoffee.example",
   }
   
   req = urllib.request.Request(
       "https://app.greenset.ai/v1/stores",
       method="POST",
       data=json.dumps(body).encode(),
       headers={
           "Authorization": "Bearer " + os.environ["GREENSET_KEY"],
           "Content-Type": "application/json",
           "Idempotency-Key": str(uuid.uuid4()),
       },
   )
   try:
       with urllib.request.urlopen(req) as res:
           data = json.load(res)
   except HTTPError as e:
       err = json.load(e)["error"]
       raise SystemExit(f"{e.code} {err['code']}: {err['message']}")
   print(data)

   Answer · 201

   JSON

   {
     "store": {
       "id": "conn_9Xk2Lm4Pq7Rs",
       "platform": "shopify",
       "store_url": "https://northfieldcoffee.example",
       "name": "Northfield Coffee",
       "status": "connected",
       "status_detail": null,
       "connected_at": "2026-10-01T09:20:44.000Z",
       "catalog": {
         "count": 38,
         "total": 38,
         "synced_at": "2026-10-01T09:20:47.000Z",
         "source": "shopify-json"
       },
       "conversions": {
         "mode": "pixel",
         "state": "dry_run",
         "last_event_at": null
       },
       "pixel": {
         "installed": true,
         "verified_at": "2026-10-02T10:30:05.000Z",
         "method": null
       }
     },
     "catalog": {
       "count": 38,
       "total": 38,
       "source": "shopify-json",
       "notes": []
     }
   }

   POST /v1/stores: every field

3. 03

   Step 03: Draw ads

   Each ad drawn uses one image from today's image allowance (Free 6, the trial 15; Premium and Agency have no daily count). It takes 20 to 60 seconds. Needs the Studio scope.

   POST /v1/concepts

   curlJavaScriptPython

   curl

   curl -X POST https://app.greenset.ai/v1/concepts \
     -H "Authorization: Bearer $GREENSET_KEY" \
     -H "Content-Type: application/json" \
     -H "Idempotency-Key: $(uuidgen)" \
     -d '{
       "url": "https://northfieldcoffee.example"
     }'

   JavaScript

   // Node 18 or later. Save as greenset.mjs, then: node greenset.mjs
   import { randomUUID } from "node:crypto";
   
   const res = await fetch("https://app.greenset.ai/v1/concepts", {
     method: "POST",
     headers: {
       Authorization: `Bearer ${process.env.GREENSET_KEY}`,
       "Content-Type": "application/json",
       "Idempotency-Key": randomUUID(),
     },
     body: JSON.stringify({
       "url": "https://northfieldcoffee.example"
     }),
   });
   const data = await res.json();
   if (!res.ok) throw new Error(`${res.status} ${data.error.code}: ${data.error.message}`);
   console.log(data);

   Python

   # Python 3, standard library only.
   import json, os, urllib.request, uuid
   from urllib.error import HTTPError
   
   body = {
       "url": "https://northfieldcoffee.example",
   }
   
   req = urllib.request.Request(
       "https://app.greenset.ai/v1/concepts",
       method="POST",
       data=json.dumps(body).encode(),
       headers={
           "Authorization": "Bearer " + os.environ["GREENSET_KEY"],
           "Content-Type": "application/json",
           "Idempotency-Key": str(uuid.uuid4()),
       },
   )
   try:
       with urllib.request.urlopen(req) as res:
           data = json.load(res)
   except HTTPError as e:
       err = json.load(e)["error"]
       raise SystemExit(f"{e.code} {err['code']}: {err['message']}")
   print(data)

   Answer · 201

   JSON

   {
     "batch_id": "bat_4e8a1c2b9d70",
     "brand": {
       "name": "Northfield Coffee",
       "platform": "shopify",
       "colors": [
         "#2B1D14",
         "#E8D9C5"
       ]
     },
     "concepts": [
       {
         "id": "cpt_1a2b3c4d5e6f",
         "batch_id": "bat_4e8a1c2b9d70",
         "rank": 1,
         "brand": "Northfield Coffee",
         "source_url": "https://northfieldcoffee.example",
         "hook": "desire",
         "headline": "Roasted Tuesday, at your door Friday",
         "subline": "Small-batch beans, shipped weekly",
         "cta": "Shop now",
         "call_to_action": "shop_now",
         "score": 8,
         "layout": "hero",
         "copy": {
           "headlines": [
             "Roasted Tuesday, at your door Friday"
           ],
           "primary_texts": [
             "Small-batch coffee from our roastery, shipped the week it's roasted."
           ],
           "descriptions": [
             "House blend, $18"
           ]
         },
         "product": {
           "title": "House blend",
           "price": "$18.00",
           "url": "https://northfieldcoffee.example/products/house-blend"
         },
         "images": {
           "square": "/v1/concepts/cpt_1a2b3c4d5e6f/images/square",
           "vertical": "/v1/concepts/cpt_1a2b3c4d5e6f/images/vertical",
           "horizontal": "/v1/concepts/cpt_1a2b3c4d5e6f/images/horizontal"
         }
       }
     ],
     "warnings": [],
     "images": {
       "tier": "free",
       "used": 6,
       "limit": 6,
       "left": 0,
       "unlimited": false
     }
   }

   POST /v1/concepts: every field

4. 04

   Step 04: Draft one as a dry run

   A dry run (the default) creates nothing in Whop and sends none of the planned requests. Where your workspace has an ad account, it reads that account from Whop and, unless the ad links to a whop.com page, asks Whop whether the pixel is on that page. It is how to try the API without spending. Needs the Drafts scope.

   POST /v1/drafts

   curlJavaScriptPython

   curl

   curl -X POST https://app.greenset.ai/v1/drafts \
     -H "Authorization: Bearer $GREENSET_KEY" \
     -H "Content-Type: application/json" \
     -H "Idempotency-Key: $(uuidgen)" \
     -d '{
       "concept_id": "cpt_1a2b3c4d5e6f",
       "destination_url": "https://northfieldcoffee.example/products/house-blend",
       "daily_budget_usd": 25
     }'

   JavaScript

   // Node 18 or later. Save as greenset.mjs, then: node greenset.mjs
   import { randomUUID } from "node:crypto";
   
   const res = await fetch("https://app.greenset.ai/v1/drafts", {
     method: "POST",
     headers: {
       Authorization: `Bearer ${process.env.GREENSET_KEY}`,
       "Content-Type": "application/json",
       "Idempotency-Key": randomUUID(),
     },
     body: JSON.stringify({
       "concept_id": "cpt_1a2b3c4d5e6f",
       "destination_url": "https://northfieldcoffee.example/products/house-blend",
       "daily_budget_usd": 25
     }),
   });
   const data = await res.json();
   if (!res.ok) throw new Error(`${res.status} ${data.error.code}: ${data.error.message}`);
   console.log(data);

   Python

   # Python 3, standard library only.
   import json, os, urllib.request, uuid
   from urllib.error import HTTPError
   
   body = {
       "concept_id": "cpt_1a2b3c4d5e6f",
       "destination_url": "https://northfieldcoffee.example/products/house-blend",
       "daily_budget_usd": 25,
   }
   
   req = urllib.request.Request(
       "https://app.greenset.ai/v1/drafts",
       method="POST",
       data=json.dumps(body).encode(),
       headers={
           "Authorization": "Bearer " + os.environ["GREENSET_KEY"],
           "Content-Type": "application/json",
           "Idempotency-Key": str(uuid.uuid4()),
       },
   )
   try:
       with urllib.request.urlopen(req) as res:
           data = json.load(res)
   except HTTPError as e:
       err = json.load(e)["error"]
       raise SystemExit(f"{e.code} {err['code']}: {err['message']}")
   print(data)

   Answer · 201

   JSON

   {
     "id": "drf_6f5e4d3c2b1a",
     "mode": "dry_run",
     "gated_reason": null,
     "planned_requests": [
       {
         "step": "create_campaign",
         "method": "POST",
         "path": "/ad_campaigns",
         "body": {
           "title": "House blend · autumn"
         }
       }
     ],
     "checks": [
       {
         "id": "whop_limits",
         "status": "pass",
         "detail": "Within Whop's account limits."
       }
     ],
     "removed_params": [],
     "result": null,
     "placements": {
       "mode": "automatic",
       "preset": "automatic",
       "facebook": null,
       "instagram": null,
       "other": [],
       "count": null,
       "of": 19,
       "label": "Automatic"
     },
     "placements_check": null
   }

   POST /v1/drafts: every field

5. 05

   Step 05: Start a live draft spending Moves money

   Moves money. Only a live draft can start; a dry run can't. Send step 04's body again with live: true and confirm_budget_usd, and start the id that answer gives. Type the daily budget back as confirm_budget_usd. Greenset refuses if the budget's worst day (210% of it) would pass your hard daily cap, if the ad balance can't cover a day, or while live writes are off. Needs the Activate scope; a key with it expires within 90 days.

   POST /v1/drafts/{id}/activate · Moves money

   curlJavaScriptPython

   curl

   curl -X POST https://app.greenset.ai/v1/drafts/drf_0a1b2c3d4e5f/activate \
     -H "Authorization: Bearer $GREENSET_KEY" \
     -H "Content-Type: application/json" \
     -H "Idempotency-Key: $(uuidgen)" \
     -d '{
       "confirm_budget_usd": 25
     }'

   JavaScript

   // Node 18 or later. Save as greenset.mjs, then: node greenset.mjs
   import { randomUUID } from "node:crypto";
   
   const res = await fetch("https://app.greenset.ai/v1/drafts/drf_0a1b2c3d4e5f/activate", {
     method: "POST",
     headers: {
       Authorization: `Bearer ${process.env.GREENSET_KEY}`,
       "Content-Type": "application/json",
       "Idempotency-Key": randomUUID(),
     },
     body: JSON.stringify({
       "confirm_budget_usd": 25
     }),
   });
   const data = await res.json();
   if (!res.ok) throw new Error(`${res.status} ${data.error.code}: ${data.error.message}`);
   console.log(data);

   Python

   # Python 3, standard library only.
   import json, os, urllib.request, uuid
   from urllib.error import HTTPError
   
   body = {
       "confirm_budget_usd": 25,
   }
   
   req = urllib.request.Request(
       "https://app.greenset.ai/v1/drafts/drf_0a1b2c3d4e5f/activate",
       method="POST",
       data=json.dumps(body).encode(),
       headers={
           "Authorization": "Bearer " + os.environ["GREENSET_KEY"],
           "Content-Type": "application/json",
           "Idempotency-Key": str(uuid.uuid4()),
       },
   )
   try:
       with urllib.request.urlopen(req) as res:
           data = json.load(res)
   except HTTPError as e:
       err = json.load(e)["error"]
       raise SystemExit(f"{e.code} {err['code']}: {err['message']}")
   print(data)

   Answer · 200

   JSON

   {
     "activated": true,
     "campaign_id": "adcamp_8Hq2LmN4pR7sTv",
     "verdict": "needs_approval",
     "cap": {
       "day": "2026-10-05",
       "time_zone": "America/New_York",
       "spent_today_usd": 0,
       "committed_usd": 0,
       "after_usd": 25,
       "worst_case_usd": 52.5,
       "cap_usd": 500
     },
     "stopped_again": null
   }

   POST /v1/drafts/{id}/activate: every field

6. 06

   Step 06: Stop everything

   Pauses every live campaign of this workspace's Whop ad account. Whop's Ads Terms say a paused campaign may still run for up to 24 hours after Whop receives the pause. Needs the Stop scope.

   POST /v1/stop-all

   curlJavaScriptPython

   curl

   curl -X POST https://app.greenset.ai/v1/stop-all \
     -H "Authorization: Bearer $GREENSET_KEY" \
     -H "Content-Type: application/json" \
     -H "Idempotency-Key: $(uuidgen)" \
     -d '{
       "confirm": "STOP"
     }'

   JavaScript

   // Node 18 or later. Save as greenset.mjs, then: node greenset.mjs
   import { randomUUID } from "node:crypto";
   
   const res = await fetch("https://app.greenset.ai/v1/stop-all", {
     method: "POST",
     headers: {
       Authorization: `Bearer ${process.env.GREENSET_KEY}`,
       "Content-Type": "application/json",
       "Idempotency-Key": randomUUID(),
     },
     body: JSON.stringify({
       "confirm": "STOP"
     }),
   });
   const data = await res.json();
   if (!res.ok) throw new Error(`${res.status} ${data.error.code}: ${data.error.message}`);
   console.log(data);

   Python

   # Python 3, standard library only.
   import json, os, urllib.request, uuid
   from urllib.error import HTTPError
   
   body = {
       "confirm": "STOP",
   }
   
   req = urllib.request.Request(
       "https://app.greenset.ai/v1/stop-all",
       method="POST",
       data=json.dumps(body).encode(),
       headers={
           "Authorization": "Bearer " + os.environ["GREENSET_KEY"],
           "Content-Type": "application/json",
           "Idempotency-Key": str(uuid.uuid4()),
       },
   )
   try:
       with urllib.request.urlopen(req) as res:
           data = json.load(res)
   except HTTPError as e:
       err = json.load(e)["error"]
       raise SystemExit(f"{e.code} {err['code']}: {err['message']}")
   print(data)

   Answer · 200

   JSON

   {
     "dry_run": false,
     "gated_reason": null,
     "account": "biz_••d001",
     "live_found": 1,
     "paused_count": 1,
     "failed_count": 0,
     "results": [
       {
         "campaign_id": "adcamp_8Hq2LmN4pR7sTv",
         "title": "House blend · autumn",
         "status": "active",
         "paused": true,
         "would_pause": false,
         "whop_status": 200,
         "error": null
       }
     ],
     "note": "Whop's Ads Terms say a paused campaign may still run for up to 24 hours after Whop receives the pause, and charges before the pause still apply."
   }

   POST /v1/stop-all: every field

02Keys and scopes#

• Send the key on every call: Authorization: Bearer followed by the key. Keys start gsk_live_ and are made under Developers in Greenset; each is shown once.
• A key acts for the one workspace it was made in, and only with the scopes it was made with. No scope implies another.
• A key with Activate moves money, so it must expire within 90 days. Any other key expires within 365 days or never. A workspace has at most 20 active keys.
• A key stops working when it is revoked, when it expires, and when the person who made it leaves the workspace or is switched off.
• A key in the URL is refused (key_in_url), and so are browser cookies. There is no CORS: call the API from your server, a terminal or an editor.
• When Greenset's Terms change, a key whose maker hasn't accepted them can still read, but every write answers 428 terms_update_required until they accept in Greenset.

03Account#

curl https://app.greenset.ai/v1/account \
  -H "Authorization: Bearer $GREENSET_KEY"

// Node 18 or later. Save as greenset.mjs, then: node greenset.mjs

const res = await fetch("https://app.greenset.ai/v1/account", {
  headers: {
    Authorization: `Bearer ${process.env.GREENSET_KEY}`,
  },
});
const data = await res.json();
if (!res.ok) throw new Error(`${res.status} ${data.error.code}: ${data.error.message}`);
console.log(data);

# Python 3, standard library only.
import json, os, urllib.request
from urllib.error import HTTPError

req = urllib.request.Request(
    "https://app.greenset.ai/v1/account",
    headers={
        "Authorization": "Bearer " + os.environ["GREENSET_KEY"],
    },
)
try:
    with urllib.request.urlopen(req) as res:
        data = json.load(res)
except HTTPError as e:
    err = json.load(e)["error"]
    raise SystemExit(f"{e.code} {err['code']}: {err['message']}")
print(data)

{
  "workspace": {
    "name": "Northfield Coffee"
  },
  "ad_account": {
    "id": "biz_LiveChild001",
    "name": "Northfield Coffee",
    "linked_at": "2026-10-01T09:14:02.000Z"
  },
  "setup": [
    {
      "id": "account",
      "status": "pass",
      "fact": "owner@northfieldcoffee.example · confirmed 2026-10-01 09:12 UTC"
    },
    {
      "id": "adaccount",
      "status": "pass",
      "fact": "biz_••d001 · pays from your ad balance · since 2026-10-01 09:14 UTC"
    },
    {
      "id": "facebook",
      "status": "pass",
      "fact": "\"Northfield Coffee\" · sacc••Qp1Z · can advertise"
    },
    {
      "id": "pixel",
      "status": "pass",
      "fact": "Whop confirmed the pixel on northfieldcoffee.example · 2026-10-02 10:30 UTC"
    },
    {
      "id": "balance",
      "status": "pass",
      "fact": "$412.50 available"
    },
    {
      "id": "draft",
      "status": "next",
      "fact": "Draw ads for what you sell in Studio"
    }
  ],
  "balance": {
    "available_usd": 412.5,
    "pending_usd": 0,
    "credits_usd": 0
  },
  "payment_failed": null,
  "caps": {
    "hard_daily_cap_usd": 500,
    "max_single_daily_usd": 238.09,
    "min_daily_budget_usd": 5,
    "overdelivery": 2.1
  },
  "live_writes": {
    "enabled": true
  },
  "quotas": {
    "scrape": {
      "used": 0,
      "limit": 120
    },
    "photos": {
      "used": 0,
      "limit": 40
    },
    "copilot": {
      "used": 0,
      "limit": 200
    },
    "elements": {
      "used": 0,
      "limit": 120
    }
  },
  "key": {
    "id": "key_Ab12Cd34Ef56",
    "name": "Zapier",
    "scopes": [
      "read",
      "stores",
      "studio",
      "drafts",
      "activate",
      "stop"
    ],
    "expires_at": "2026-11-04T13:29:30.000Z"
  },
  "as_of": "2026-10-05T13:31:07.000Z"
}

04Stores#

curl https://app.greenset.ai/v1/stores \
  -H "Authorization: Bearer $GREENSET_KEY"

// Node 18 or later. Save as greenset.mjs, then: node greenset.mjs

const res = await fetch("https://app.greenset.ai/v1/stores", {
  headers: {
    Authorization: `Bearer ${process.env.GREENSET_KEY}`,
  },
});
const data = await res.json();
if (!res.ok) throw new Error(`${res.status} ${data.error.code}: ${data.error.message}`);
console.log(data);

# Python 3, standard library only.
import json, os, urllib.request
from urllib.error import HTTPError

req = urllib.request.Request(
    "https://app.greenset.ai/v1/stores",
    headers={
        "Authorization": "Bearer " + os.environ["GREENSET_KEY"],
    },
)
try:
    with urllib.request.urlopen(req) as res:
        data = json.load(res)
except HTTPError as e:
    err = json.load(e)["error"]
    raise SystemExit(f"{e.code} {err['code']}: {err['message']}")
print(data)

{
  "data": [
    {
      "id": "conn_9Xk2Lm4Pq7Rs",
      "platform": "shopify",
      "store_url": "https://northfieldcoffee.example",
      "name": "Northfield Coffee",
      "status": "connected",
      "status_detail": null,
      "connected_at": "2026-10-01T09:20:44.000Z",
      "catalog": {
        "count": 38,
        "total": 38,
        "synced_at": "2026-10-01T09:20:47.000Z",
        "source": "shopify-json"
      },
      "conversions": {
        "mode": "pixel",
        "state": "dry_run",
        "last_event_at": null
      },
      "pixel": {
        "installed": true,
        "verified_at": "2026-10-02T10:30:05.000Z",
        "method": null
      }
    }
  ],
  "has_more": false,
  "next_cursor": null
}

curl -X POST https://app.greenset.ai/v1/stores \
  -H "Authorization: Bearer $GREENSET_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "url": "https://northfieldcoffee.example"
  }'

// Node 18 or later. Save as greenset.mjs, then: node greenset.mjs
import { randomUUID } from "node:crypto";

const res = await fetch("https://app.greenset.ai/v1/stores", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.GREENSET_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": randomUUID(),
  },
  body: JSON.stringify({
    "url": "https://northfieldcoffee.example"
  }),
});
const data = await res.json();
if (!res.ok) throw new Error(`${res.status} ${data.error.code}: ${data.error.message}`);
console.log(data);

# Python 3, standard library only.
import json, os, urllib.request, uuid
from urllib.error import HTTPError

body = {
    "url": "https://northfieldcoffee.example",
}

req = urllib.request.Request(
    "https://app.greenset.ai/v1/stores",
    method="POST",
    data=json.dumps(body).encode(),
    headers={
        "Authorization": "Bearer " + os.environ["GREENSET_KEY"],
        "Content-Type": "application/json",
        "Idempotency-Key": str(uuid.uuid4()),
    },
)
try:
    with urllib.request.urlopen(req) as res:
        data = json.load(res)
except HTTPError as e:
    err = json.load(e)["error"]
    raise SystemExit(f"{e.code} {err['code']}: {err['message']}")
print(data)

{
  "store": {
    "id": "conn_9Xk2Lm4Pq7Rs",
    "platform": "shopify",
    "store_url": "https://northfieldcoffee.example",
    "name": "Northfield Coffee",
    "status": "connected",
    "status_detail": null,
    "connected_at": "2026-10-01T09:20:44.000Z",
    "catalog": {
      "count": 38,
      "total": 38,
      "synced_at": "2026-10-01T09:20:47.000Z",
      "source": "shopify-json"
    },
    "conversions": {
      "mode": "pixel",
      "state": "dry_run",
      "last_event_at": null
    },
    "pixel": {
      "installed": true,
      "verified_at": "2026-10-02T10:30:05.000Z",
      "method": null
    }
  },
  "catalog": {
    "count": 38,
    "total": 38,
    "source": "shopify-json",
    "notes": []
  }
}

05Studio#

curl -X POST https://app.greenset.ai/v1/concepts \
  -H "Authorization: Bearer $GREENSET_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "url": "https://northfieldcoffee.example"
  }'

// Node 18 or later. Save as greenset.mjs, then: node greenset.mjs
import { randomUUID } from "node:crypto";

const res = await fetch("https://app.greenset.ai/v1/concepts", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.GREENSET_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": randomUUID(),
  },
  body: JSON.stringify({
    "url": "https://northfieldcoffee.example"
  }),
});
const data = await res.json();
if (!res.ok) throw new Error(`${res.status} ${data.error.code}: ${data.error.message}`);
console.log(data);

# Python 3, standard library only.
import json, os, urllib.request, uuid
from urllib.error import HTTPError

body = {
    "url": "https://northfieldcoffee.example",
}

req = urllib.request.Request(
    "https://app.greenset.ai/v1/concepts",
    method="POST",
    data=json.dumps(body).encode(),
    headers={
        "Authorization": "Bearer " + os.environ["GREENSET_KEY"],
        "Content-Type": "application/json",
        "Idempotency-Key": str(uuid.uuid4()),
    },
)
try:
    with urllib.request.urlopen(req) as res:
        data = json.load(res)
except HTTPError as e:
    err = json.load(e)["error"]
    raise SystemExit(f"{e.code} {err['code']}: {err['message']}")
print(data)

{
  "batch_id": "bat_4e8a1c2b9d70",
  "brand": {
    "name": "Northfield Coffee",
    "platform": "shopify",
    "colors": [
      "#2B1D14",
      "#E8D9C5"
    ]
  },
  "concepts": [
    {
      "id": "cpt_1a2b3c4d5e6f",
      "batch_id": "bat_4e8a1c2b9d70",
      "rank": 1,
      "brand": "Northfield Coffee",
      "source_url": "https://northfieldcoffee.example",
      "hook": "desire",
      "headline": "Roasted Tuesday, at your door Friday",
      "subline": "Small-batch beans, shipped weekly",
      "cta": "Shop now",
      "call_to_action": "shop_now",
      "score": 8,
      "layout": "hero",
      "copy": {
        "headlines": [
          "Roasted Tuesday, at your door Friday"
        ],
        "primary_texts": [
          "Small-batch coffee from our roastery, shipped the week it's roasted."
        ],
        "descriptions": [
          "House blend, $18"
        ]
      },
      "product": {
        "title": "House blend",
        "price": "$18.00",
        "url": "https://northfieldcoffee.example/products/house-blend"
      },
      "images": {
        "square": "/v1/concepts/cpt_1a2b3c4d5e6f/images/square",
        "vertical": "/v1/concepts/cpt_1a2b3c4d5e6f/images/vertical",
        "horizontal": "/v1/concepts/cpt_1a2b3c4d5e6f/images/horizontal"
      }
    }
  ],
  "warnings": [],
  "images": {
    "tier": "free",
    "used": 6,
    "limit": 6,
    "left": 0,
    "unlimited": false
  }
}

curl https://app.greenset.ai/v1/concepts/cpt_1a2b3c4d5e6f \
  -H "Authorization: Bearer $GREENSET_KEY"

// Node 18 or later. Save as greenset.mjs, then: node greenset.mjs

const res = await fetch("https://app.greenset.ai/v1/concepts/cpt_1a2b3c4d5e6f", {
  headers: {
    Authorization: `Bearer ${process.env.GREENSET_KEY}`,
  },
});
const data = await res.json();
if (!res.ok) throw new Error(`${res.status} ${data.error.code}: ${data.error.message}`);
console.log(data);

# Python 3, standard library only.
import json, os, urllib.request
from urllib.error import HTTPError

req = urllib.request.Request(
    "https://app.greenset.ai/v1/concepts/cpt_1a2b3c4d5e6f",
    headers={
        "Authorization": "Bearer " + os.environ["GREENSET_KEY"],
    },
)
try:
    with urllib.request.urlopen(req) as res:
        data = json.load(res)
except HTTPError as e:
    err = json.load(e)["error"]
    raise SystemExit(f"{e.code} {err['code']}: {err['message']}")
print(data)

{
  "id": "cpt_1a2b3c4d5e6f",
  "batch_id": "bat_4e8a1c2b9d70",
  "rank": 1,
  "brand": "Northfield Coffee",
  "source_url": "https://northfieldcoffee.example",
  "hook": "desire",
  "headline": "Roasted Tuesday, at your door Friday",
  "subline": "Small-batch beans, shipped weekly",
  "cta": "Shop now",
  "call_to_action": "shop_now",
  "score": 8,
  "layout": "hero",
  "copy": {
    "headlines": [
      "Roasted Tuesday, at your door Friday"
    ],
    "primary_texts": [
      "Small-batch coffee from our roastery, shipped the week it's roasted."
    ],
    "descriptions": [
      "House blend, $18"
    ]
  },
  "product": {
    "title": "House blend",
    "price": "$18.00",
    "url": "https://northfieldcoffee.example/products/house-blend"
  },
  "images": {
    "square": "/v1/concepts/cpt_1a2b3c4d5e6f/images/square",
    "vertical": "/v1/concepts/cpt_1a2b3c4d5e6f/images/vertical",
    "horizontal": "/v1/concepts/cpt_1a2b3c4d5e6f/images/horizontal"
  }
}

curl https://app.greenset.ai/v1/concepts/cpt_1a2b3c4d5e6f/images/square \
  -H "Authorization: Bearer $GREENSET_KEY" \
  -o greenset-square.png

// Node 18 or later. Save as greenset.mjs, then: node greenset.mjs
import { writeFile } from "node:fs/promises";

const res = await fetch("https://app.greenset.ai/v1/concepts/cpt_1a2b3c4d5e6f/images/square", {
  headers: {
    Authorization: `Bearer ${process.env.GREENSET_KEY}`,
  },
});
if (!res.ok) {
  const { error } = await res.json();
  throw new Error(`${res.status} ${error.code}: ${error.message}`);
}
await writeFile("greenset-square.png", Buffer.from(await res.arrayBuffer()));

# Python 3, standard library only.
import json, os, urllib.request
from urllib.error import HTTPError

req = urllib.request.Request(
    "https://app.greenset.ai/v1/concepts/cpt_1a2b3c4d5e6f/images/square",
    headers={
        "Authorization": "Bearer " + os.environ["GREENSET_KEY"],
    },
)
try:
    with urllib.request.urlopen(req) as res, open("greenset-square.png", "wb") as f:
        f.write(res.read())
except HTTPError as e:
    err = json.load(e)["error"]
    raise SystemExit(f"{e.code} {err['code']}: {err['message']}")

06Drafts#

curl https://app.greenset.ai/v1/drafts \
  -H "Authorization: Bearer $GREENSET_KEY"

// Node 18 or later. Save as greenset.mjs, then: node greenset.mjs

const res = await fetch("https://app.greenset.ai/v1/drafts", {
  headers: {
    Authorization: `Bearer ${process.env.GREENSET_KEY}`,
  },
});
const data = await res.json();
if (!res.ok) throw new Error(`${res.status} ${data.error.code}: ${data.error.message}`);
console.log(data);

# Python 3, standard library only.
import json, os, urllib.request
from urllib.error import HTTPError

req = urllib.request.Request(
    "https://app.greenset.ai/v1/drafts",
    headers={
        "Authorization": "Bearer " + os.environ["GREENSET_KEY"],
    },
)
try:
    with urllib.request.urlopen(req) as res:
        data = json.load(res)
except HTTPError as e:
    err = json.load(e)["error"]
    raise SystemExit(f"{e.code} {err['code']}: {err['message']}")
print(data)

{
  "data": [
    {
      "id": "drf_0a1b2c3d4e5f",
      "concept_id": "cpt_1a2b3c4d5e6f",
      "mode": "live",
      "status": "created",
      "title": "House blend · autumn",
      "daily_budget_usd": 25,
      "countries": [
        "US"
      ],
      "destination_url": "https://northfieldcoffee.example/products/house-blend",
      "campaign_id": "adcamp_8Hq2LmN4pR7sTv",
      "error": null,
      "created_at": "2026-10-05T13:40:00.000Z",
      "updated_at": "2026-10-05T13:40:09.000Z",
      "placements": {
        "mode": "automatic",
        "preset": "automatic",
        "facebook": null,
        "instagram": null,
        "other": [],
        "count": null,
        "of": 19,
        "label": "Automatic"
      }
    }
  ],
  "has_more": false,
  "next_cursor": null
}

curl https://app.greenset.ai/v1/drafts/drf_0a1b2c3d4e5f \
  -H "Authorization: Bearer $GREENSET_KEY"

// Node 18 or later. Save as greenset.mjs, then: node greenset.mjs

const res = await fetch("https://app.greenset.ai/v1/drafts/drf_0a1b2c3d4e5f", {
  headers: {
    Authorization: `Bearer ${process.env.GREENSET_KEY}`,
  },
});
const data = await res.json();
if (!res.ok) throw new Error(`${res.status} ${data.error.code}: ${data.error.message}`);
console.log(data);

# Python 3, standard library only.
import json, os, urllib.request
from urllib.error import HTTPError

req = urllib.request.Request(
    "https://app.greenset.ai/v1/drafts/drf_0a1b2c3d4e5f",
    headers={
        "Authorization": "Bearer " + os.environ["GREENSET_KEY"],
    },
)
try:
    with urllib.request.urlopen(req) as res:
        data = json.load(res)
except HTTPError as e:
    err = json.load(e)["error"]
    raise SystemExit(f"{e.code} {err['code']}: {err['message']}")
print(data)

{
  "id": "drf_0a1b2c3d4e5f",
  "concept_id": "cpt_1a2b3c4d5e6f",
  "mode": "live",
  "status": "created",
  "title": "House blend · autumn",
  "daily_budget_usd": 25,
  "countries": [
    "US"
  ],
  "destination_url": "https://northfieldcoffee.example/products/house-blend",
  "campaign_id": "adcamp_8Hq2LmN4pR7sTv",
  "error": null,
  "created_at": "2026-10-05T13:40:00.000Z",
  "updated_at": "2026-10-05T13:40:09.000Z",
  "placements": {
    "mode": "automatic",
    "preset": "automatic",
    "facebook": null,
    "instagram": null,
    "other": [],
    "count": null,
    "of": 19,
    "label": "Automatic"
  },
  "planned_requests": [
    {
      "step": "create_campaign",
      "method": "POST",
      "path": "/ad_campaigns",
      "body": {
        "title": "House blend · autumn"
      }
    }
  ]
}

curl -X POST https://app.greenset.ai/v1/drafts \
  -H "Authorization: Bearer $GREENSET_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "concept_id": "cpt_1a2b3c4d5e6f",
    "destination_url": "https://northfieldcoffee.example/products/house-blend",
    "daily_budget_usd": 25
  }'

// Node 18 or later. Save as greenset.mjs, then: node greenset.mjs
import { randomUUID } from "node:crypto";

const res = await fetch("https://app.greenset.ai/v1/drafts", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.GREENSET_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": randomUUID(),
  },
  body: JSON.stringify({
    "concept_id": "cpt_1a2b3c4d5e6f",
    "destination_url": "https://northfieldcoffee.example/products/house-blend",
    "daily_budget_usd": 25
  }),
});
const data = await res.json();
if (!res.ok) throw new Error(`${res.status} ${data.error.code}: ${data.error.message}`);
console.log(data);

# Python 3, standard library only.
import json, os, urllib.request, uuid
from urllib.error import HTTPError

body = {
    "concept_id": "cpt_1a2b3c4d5e6f",
    "destination_url": "https://northfieldcoffee.example/products/house-blend",
    "daily_budget_usd": 25,
}

req = urllib.request.Request(
    "https://app.greenset.ai/v1/drafts",
    method="POST",
    data=json.dumps(body).encode(),
    headers={
        "Authorization": "Bearer " + os.environ["GREENSET_KEY"],
        "Content-Type": "application/json",
        "Idempotency-Key": str(uuid.uuid4()),
    },
)
try:
    with urllib.request.urlopen(req) as res:
        data = json.load(res)
except HTTPError as e:
    err = json.load(e)["error"]
    raise SystemExit(f"{e.code} {err['code']}: {err['message']}")
print(data)

{
  "id": "drf_6f5e4d3c2b1a",
  "mode": "dry_run",
  "gated_reason": null,
  "planned_requests": [
    {
      "step": "create_campaign",
      "method": "POST",
      "path": "/ad_campaigns",
      "body": {
        "title": "House blend · autumn"
      }
    }
  ],
  "checks": [
    {
      "id": "whop_limits",
      "status": "pass",
      "detail": "Within Whop's account limits."
    }
  ],
  "removed_params": [],
  "result": null,
  "placements": {
    "mode": "automatic",
    "preset": "automatic",
    "facebook": null,
    "instagram": null,
    "other": [],
    "count": null,
    "of": 19,
    "label": "Automatic"
  },
  "placements_check": null
}

curl -X POST https://app.greenset.ai/v1/drafts/drf_0a1b2c3d4e5f/activate \
  -H "Authorization: Bearer $GREENSET_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "confirm_budget_usd": 25
  }'

// Node 18 or later. Save as greenset.mjs, then: node greenset.mjs
import { randomUUID } from "node:crypto";

const res = await fetch("https://app.greenset.ai/v1/drafts/drf_0a1b2c3d4e5f/activate", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.GREENSET_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": randomUUID(),
  },
  body: JSON.stringify({
    "confirm_budget_usd": 25
  }),
});
const data = await res.json();
if (!res.ok) throw new Error(`${res.status} ${data.error.code}: ${data.error.message}`);
console.log(data);

# Python 3, standard library only.
import json, os, urllib.request, uuid
from urllib.error import HTTPError

body = {
    "confirm_budget_usd": 25,
}

req = urllib.request.Request(
    "https://app.greenset.ai/v1/drafts/drf_0a1b2c3d4e5f/activate",
    method="POST",
    data=json.dumps(body).encode(),
    headers={
        "Authorization": "Bearer " + os.environ["GREENSET_KEY"],
        "Content-Type": "application/json",
        "Idempotency-Key": str(uuid.uuid4()),
    },
)
try:
    with urllib.request.urlopen(req) as res:
        data = json.load(res)
except HTTPError as e:
    err = json.load(e)["error"]
    raise SystemExit(f"{e.code} {err['code']}: {err['message']}")
print(data)

{
  "activated": true,
  "campaign_id": "adcamp_8Hq2LmN4pR7sTv",
  "verdict": "needs_approval",
  "cap": {
    "day": "2026-10-05",
    "time_zone": "America/New_York",
    "spent_today_usd": 0,
    "committed_usd": 0,
    "after_usd": 25,
    "worst_case_usd": 52.5,
    "cap_usd": 500
  },
  "stopped_again": null
}

07Campaigns#

curl https://app.greenset.ai/v1/campaigns \
  -H "Authorization: Bearer $GREENSET_KEY"

// Node 18 or later. Save as greenset.mjs, then: node greenset.mjs

const res = await fetch("https://app.greenset.ai/v1/campaigns", {
  headers: {
    Authorization: `Bearer ${process.env.GREENSET_KEY}`,
  },
});
const data = await res.json();
if (!res.ok) throw new Error(`${res.status} ${data.error.code}: ${data.error.message}`);
console.log(data);

# Python 3, standard library only.
import json, os, urllib.request
from urllib.error import HTTPError

req = urllib.request.Request(
    "https://app.greenset.ai/v1/campaigns",
    headers={
        "Authorization": "Bearer " + os.environ["GREENSET_KEY"],
    },
)
try:
    with urllib.request.urlopen(req) as res:
        data = json.load(res)
except HTTPError as e:
    err = json.load(e)["error"]
    raise SystemExit(f"{e.code} {err['code']}: {err['message']}")
print(data)

{
  "data": [
    {
      "id": "adcamp_8Hq2LmN4pR7sTv",
      "title": "House blend · autumn",
      "status": "active",
      "delivery_status": "active",
      "platform": "meta",
      "objective": "sales",
      "budget_amount": 25,
      "budget_type": "daily",
      "spend": 18.2,
      "spend_currency": "usd",
      "impressions": 2140,
      "clicks": 61,
      "results": null,
      "result_event": null,
      "cost_per_result": null,
      "purchases": null,
      "purchase_value": null,
      "return_on_ad_spend": 0,
      "created_at": "2026-10-05T13:40:00.000Z",
      "updated_at": "2026-10-05T14:00:00.000Z"
    }
  ],
  "has_more": false,
  "next_cursor": null,
  "window": {
    "from": "2026-10-05",
    "to": "2026-10-05",
    "time_zone": "America/New_York",
    "time_zone_note": "Day boundaries use America/New_York, your Whop account's reporting time zone.",
    "attribution_model": "last_touch"
  },
  "roas_label": "Whop-checkout ROAS, last-touch",
  "as_of": "2026-10-05T14:02:11.000Z"
}

curl https://app.greenset.ai/v1/events \
  -H "Authorization: Bearer $GREENSET_KEY"

// Node 18 or later. Save as greenset.mjs, then: node greenset.mjs

const res = await fetch("https://app.greenset.ai/v1/events", {
  headers: {
    Authorization: `Bearer ${process.env.GREENSET_KEY}`,
  },
});
const data = await res.json();
if (!res.ok) throw new Error(`${res.status} ${data.error.code}: ${data.error.message}`);
console.log(data);

# Python 3, standard library only.
import json, os, urllib.request
from urllib.error import HTTPError

req = urllib.request.Request(
    "https://app.greenset.ai/v1/events",
    headers={
        "Authorization": "Bearer " + os.environ["GREENSET_KEY"],
    },
)
try:
    with urllib.request.urlopen(req) as res:
        data = json.load(res)
except HTTPError as e:
    err = json.load(e)["error"]
    raise SystemExit(f"{e.code} {err['code']}: {err['message']}")
print(data)

{
  "data": [
    {
      "id": "pev_Qm3Xr8Tz1Kp5",
      "type": "deposit.succeeded",
      "resource_id": null,
      "summary": "Deposit $500.00 reached the ad balance",
      "created_at": "2026-10-05T13:58:02.000Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

08Safety#

curl -X POST https://app.greenset.ai/v1/stop-all \
  -H "Authorization: Bearer $GREENSET_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "confirm": "STOP"
  }'

// Node 18 or later. Save as greenset.mjs, then: node greenset.mjs
import { randomUUID } from "node:crypto";

const res = await fetch("https://app.greenset.ai/v1/stop-all", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.GREENSET_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": randomUUID(),
  },
  body: JSON.stringify({
    "confirm": "STOP"
  }),
});
const data = await res.json();
if (!res.ok) throw new Error(`${res.status} ${data.error.code}: ${data.error.message}`);
console.log(data);

# Python 3, standard library only.
import json, os, urllib.request, uuid
from urllib.error import HTTPError

body = {
    "confirm": "STOP",
}

req = urllib.request.Request(
    "https://app.greenset.ai/v1/stop-all",
    method="POST",
    data=json.dumps(body).encode(),
    headers={
        "Authorization": "Bearer " + os.environ["GREENSET_KEY"],
        "Content-Type": "application/json",
        "Idempotency-Key": str(uuid.uuid4()),
    },
)
try:
    with urllib.request.urlopen(req) as res:
        data = json.load(res)
except HTTPError as e:
    err = json.load(e)["error"]
    raise SystemExit(f"{e.code} {err['code']}: {err['message']}")
print(data)

{
  "dry_run": false,
  "gated_reason": null,
  "account": "biz_••d001",
  "live_found": 1,
  "paused_count": 1,
  "failed_count": 0,
  "results": [
    {
      "campaign_id": "adcamp_8Hq2LmN4pR7sTv",
      "title": "House blend · autumn",
      "status": "active",
      "paused": true,
      "would_pause": false,
      "whop_status": 200,
      "error": null
    }
  ],
  "note": "Whop's Ads Terms say a paused campaign may still run for up to 24 hours after Whop receives the pause, and charges before the pause still apply."
}

09Autopilot#

curl https://app.greenset.ai/v1/guardrails \
  -H "Authorization: Bearer $GREENSET_KEY"

// Node 18 or later. Save as greenset.mjs, then: node greenset.mjs

const res = await fetch("https://app.greenset.ai/v1/guardrails", {
  headers: {
    Authorization: `Bearer ${process.env.GREENSET_KEY}`,
  },
});
const data = await res.json();
if (!res.ok) throw new Error(`${res.status} ${data.error.code}: ${data.error.message}`);
console.log(data);

# Python 3, standard library only.
import json, os, urllib.request
from urllib.error import HTTPError

req = urllib.request.Request(
    "https://app.greenset.ai/v1/guardrails",
    headers={
        "Authorization": "Bearer " + os.environ["GREENSET_KEY"],
    },
)
try:
    with urllib.request.urlopen(req) as res:
        data = json.load(res)
except HTTPError as e:
    err = json.load(e)["error"]
    raise SystemExit(f"{e.code} {err['code']}: {err['message']}")
print(data)

{
  "autonomy": {
    "read": "Auto",
    "pause": "Confirm",
    "budget": "Suggest",
    "creative": "Suggest",
    "launch": "Confirm",
    "billing": "Notify",
    "destination": "Notify"
  },
  "hard_daily_cap_usd": 500,
  "roas_floor": 3,
  "cpa_target_usd": null
}

curl -X PUT https://app.greenset.ai/v1/guardrails \
  -H "Authorization: Bearer $GREENSET_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "hard_daily_cap_usd": 250,
    "autonomy": {
      "budget": "Notify"
    }
  }'

// Node 18 or later. Save as greenset.mjs, then: node greenset.mjs
import { randomUUID } from "node:crypto";

const res = await fetch("https://app.greenset.ai/v1/guardrails", {
  method: "PUT",
  headers: {
    Authorization: `Bearer ${process.env.GREENSET_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": randomUUID(),
  },
  body: JSON.stringify({
    "hard_daily_cap_usd": 250,
    "autonomy": {
      "budget": "Notify"
    }
  }),
});
const data = await res.json();
if (!res.ok) throw new Error(`${res.status} ${data.error.code}: ${data.error.message}`);
console.log(data);

# Python 3, standard library only.
import json, os, urllib.request, uuid
from urllib.error import HTTPError

body = {
    "hard_daily_cap_usd": 250,
    "autonomy": {
        "budget": "Notify",
    },
}

req = urllib.request.Request(
    "https://app.greenset.ai/v1/guardrails",
    method="PUT",
    data=json.dumps(body).encode(),
    headers={
        "Authorization": "Bearer " + os.environ["GREENSET_KEY"],
        "Content-Type": "application/json",
        "Idempotency-Key": str(uuid.uuid4()),
    },
)
try:
    with urllib.request.urlopen(req) as res:
        data = json.load(res)
except HTTPError as e:
    err = json.load(e)["error"]
    raise SystemExit(f"{e.code} {err['code']}: {err['message']}")
print(data)

{
  "autonomy": {
    "read": "Auto",
    "pause": "Confirm",
    "budget": "Notify",
    "creative": "Suggest",
    "launch": "Confirm",
    "billing": "Notify",
    "destination": "Notify"
  },
  "hard_daily_cap_usd": 250,
  "roas_floor": 3,
  "cpa_target_usd": null
}

10Webhooks#

curl https://app.greenset.ai/v1/webhooks \
  -H "Authorization: Bearer $GREENSET_KEY"

// Node 18 or later. Save as greenset.mjs, then: node greenset.mjs

const res = await fetch("https://app.greenset.ai/v1/webhooks", {
  headers: {
    Authorization: `Bearer ${process.env.GREENSET_KEY}`,
  },
});
const data = await res.json();
if (!res.ok) throw new Error(`${res.status} ${data.error.code}: ${data.error.message}`);
console.log(data);

# Python 3, standard library only.
import json, os, urllib.request
from urllib.error import HTTPError

req = urllib.request.Request(
    "https://app.greenset.ai/v1/webhooks",
    headers={
        "Authorization": "Bearer " + os.environ["GREENSET_KEY"],
    },
)
try:
    with urllib.request.urlopen(req) as res:
        data = json.load(res)
except HTTPError as e:
    err = json.load(e)["error"]
    raise SystemExit(f"{e.code} {err['code']}: {err['message']}")
print(data)

{
  "data": [
    {
      "id": "we_Rk7Lq2Xm9Pz4Tn6V",
      "url": "https://hooks.example.com/greenset",
      "description": "Slack relay",
      "events": [
        "campaign.live",
        "payment.failed",
        "balance.low"
      ],
      "enabled": true,
      "disabled_reason": null,
      "disabled_at": null,
      "consecutive_failures": 0,
      "created_at": "2026-10-03T08:00:00.000Z",
      "last_success_at": "2026-10-05T13:41:02.000Z",
      "last_failure_at": null
    }
  ],
  "has_more": false,
  "next_cursor": null
}

curl -X POST https://app.greenset.ai/v1/webhooks \
  -H "Authorization: Bearer $GREENSET_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "url": "https://hooks.example.com/greenset",
    "events": [
      "campaign.live",
      "payment.failed",
      "balance.low"
    ]
  }'

// Node 18 or later. Save as greenset.mjs, then: node greenset.mjs
import { randomUUID } from "node:crypto";

const res = await fetch("https://app.greenset.ai/v1/webhooks", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.GREENSET_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": randomUUID(),
  },
  body: JSON.stringify({
    "url": "https://hooks.example.com/greenset",
    "events": [
      "campaign.live",
      "payment.failed",
      "balance.low"
    ]
  }),
});
const data = await res.json();
if (!res.ok) throw new Error(`${res.status} ${data.error.code}: ${data.error.message}`);
console.log(data);

# Python 3, standard library only.
import json, os, urllib.request, uuid
from urllib.error import HTTPError

body = {
    "url": "https://hooks.example.com/greenset",
    "events": ["campaign.live", "payment.failed", "balance.low"],
}

req = urllib.request.Request(
    "https://app.greenset.ai/v1/webhooks",
    method="POST",
    data=json.dumps(body).encode(),
    headers={
        "Authorization": "Bearer " + os.environ["GREENSET_KEY"],
        "Content-Type": "application/json",
        "Idempotency-Key": str(uuid.uuid4()),
    },
)
try:
    with urllib.request.urlopen(req) as res:
        data = json.load(res)
except HTTPError as e:
    err = json.load(e)["error"]
    raise SystemExit(f"{e.code} {err['code']}: {err['message']}")
print(data)

{
  "endpoint": {
    "id": "we_Rk7Lq2Xm9Pz4Tn6V",
    "url": "https://hooks.example.com/greenset",
    "description": "Slack relay",
    "events": [
      "campaign.live",
      "payment.failed",
      "balance.low"
    ],
    "enabled": true,
    "disabled_reason": null,
    "disabled_at": null,
    "consecutive_failures": 0,
    "created_at": "2026-10-03T08:00:00.000Z",
    "last_success_at": null,
    "last_failure_at": null
  },
  "secret": "whsec_(shown once)"
}

curl -X DELETE https://app.greenset.ai/v1/webhooks/we_Rk7Lq2Xm9Pz4Tn6V \
  -H "Authorization: Bearer $GREENSET_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

// Node 18 or later. Save as greenset.mjs, then: node greenset.mjs
import { randomUUID } from "node:crypto";

const res = await fetch("https://app.greenset.ai/v1/webhooks/we_Rk7Lq2Xm9Pz4Tn6V", {
  method: "DELETE",
  headers: {
    Authorization: `Bearer ${process.env.GREENSET_KEY}`,
    "Idempotency-Key": randomUUID(),
  },
});
const data = await res.json();
if (!res.ok) throw new Error(`${res.status} ${data.error.code}: ${data.error.message}`);
console.log(data);

# Python 3, standard library only.
import json, os, urllib.request, uuid
from urllib.error import HTTPError

req = urllib.request.Request(
    "https://app.greenset.ai/v1/webhooks/we_Rk7Lq2Xm9Pz4Tn6V",
    method="DELETE",
    headers={
        "Authorization": "Bearer " + os.environ["GREENSET_KEY"],
        "Idempotency-Key": str(uuid.uuid4()),
    },
)
try:
    with urllib.request.urlopen(req) as res:
        data = json.load(res)
except HTTPError as e:
    err = json.load(e)["error"]
    raise SystemExit(f"{e.code} {err['code']}: {err['message']}")
print(data)

{
  "deleted": true,
  "id": "we_Rk7Lq2Xm9Pz4Tn6V"
}

curl -X POST https://app.greenset.ai/v1/webhooks/we_Rk7Lq2Xm9Pz4Tn6V/test \
  -H "Authorization: Bearer $GREENSET_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

// Node 18 or later. Save as greenset.mjs, then: node greenset.mjs
import { randomUUID } from "node:crypto";

const res = await fetch("https://app.greenset.ai/v1/webhooks/we_Rk7Lq2Xm9Pz4Tn6V/test", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.GREENSET_KEY}`,
    "Idempotency-Key": randomUUID(),
  },
});
const data = await res.json();
if (!res.ok) throw new Error(`${res.status} ${data.error.code}: ${data.error.message}`);
console.log(data);

# Python 3, standard library only.
import json, os, urllib.request, uuid
from urllib.error import HTTPError

req = urllib.request.Request(
    "https://app.greenset.ai/v1/webhooks/we_Rk7Lq2Xm9Pz4Tn6V/test",
    method="POST",
    data=b"",
    headers={
        "Authorization": "Bearer " + os.environ["GREENSET_KEY"],
        "Idempotency-Key": str(uuid.uuid4()),
    },
)
try:
    with urllib.request.urlopen(req) as res:
        data = json.load(res)
except HTTPError as e:
    err = json.load(e)["error"]
    raise SystemExit(f"{e.code} {err['code']}: {err['message']}")
print(data)

{
  "delivery_id": "dlv_Hn4Wq8Zr2Lm6Pk1S",
  "event_id": "msg_Vb5Nc9Xe3Rt7Yu2I",
  "ok": true,
  "status": 204,
  "error": null,
  "ms": 182
}

curl https://app.greenset.ai/v1/webhooks/we_Rk7Lq2Xm9Pz4Tn6V/deliveries \
  -H "Authorization: Bearer $GREENSET_KEY"

// Node 18 or later. Save as greenset.mjs, then: node greenset.mjs

const res = await fetch("https://app.greenset.ai/v1/webhooks/we_Rk7Lq2Xm9Pz4Tn6V/deliveries", {
  headers: {
    Authorization: `Bearer ${process.env.GREENSET_KEY}`,
  },
});
const data = await res.json();
if (!res.ok) throw new Error(`${res.status} ${data.error.code}: ${data.error.message}`);
console.log(data);

# Python 3, standard library only.
import json, os, urllib.request
from urllib.error import HTTPError

req = urllib.request.Request(
    "https://app.greenset.ai/v1/webhooks/we_Rk7Lq2Xm9Pz4Tn6V/deliveries",
    headers={
        "Authorization": "Bearer " + os.environ["GREENSET_KEY"],
    },
)
try:
    with urllib.request.urlopen(req) as res:
        data = json.load(res)
except HTTPError as e:
    err = json.load(e)["error"]
    raise SystemExit(f"{e.code} {err['code']}: {err['message']}")
print(data)

{
  "data": [
    {
      "id": "dlv_Hn4Wq8Zr2Lm6Pk1S",
      "event_id": "msg_Vb5Nc9Xe3Rt7Yu2I",
      "type": "campaign.live",
      "status": "succeeded",
      "attempts": 1,
      "last_status": 200,
      "last_error": null,
      "next_attempt_at": null,
      "created_at": "2026-10-05T13:41:01.000Z",
      "tries": [
        {
          "attempt": 1,
          "status": 200,
          "error": null,
          "ms": 140,
          "at": "2026-10-05T13:41:02.000Z"
        }
      ]
    }
  ],
  "has_more": false,
  "next_cursor": null
}

11Reference#

curl https://app.greenset.ai/v1/openapi.json

// Node 18 or later. Save as greenset.mjs, then: node greenset.mjs

const res = await fetch("https://app.greenset.ai/v1/openapi.json", {
});
const data = await res.json();
if (!res.ok) throw new Error(`${res.status} ${data.error.code}: ${data.error.message}`);
console.log(data);

# Python 3, standard library only.
import json, os, urllib.request
from urllib.error import HTTPError

req = urllib.request.Request(
    "https://app.greenset.ai/v1/openapi.json",
)
try:
    with urllib.request.urlopen(req) as res:
        data = json.load(res)
except HTTPError as e:
    err = json.load(e)["error"]
    raise SystemExit(f"{e.code} {err['code']}: {err['message']}")
print(data)

{
  "openapi": "3.1.0",
  "info": {
    "title": "Greenset API",
    "version": "1.0.0"
  },
  "paths": {}
}

12Errors#

Every refusal is {"error": {"code", "message", "request_id"}}. Branch on the code; the message is for a person. Some codes add a field at the top level: field, required_scope, quota, images, checks, cap, activated.

13Limits#

Read from the code that enforces them when this page was made. Answers carry RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset; a 429 carries Retry-After.

Store reads: 120 a day, shared with the console (POST /v1/stores, and POST /v1/concepts with render: false). Days are UTC. GET /v1/account lists the daily allowances with what is used; store reads are scrape. Images are not in that list: POST /v1/concepts answers today's count as images.

14Pages#

• Lists answer {data, has_more, next_cursor}. Pass limit (1 to 100, default 20) and, for the next page, cursor set to the next_cursor you were given. A cursor this API didn't return is 400 invalid_cursor.
• Newest first. When has_more is false, next_cursor is null and there is nothing more.

Paged: GET /v1/drafts, GET /v1/campaigns, GET /v1/events, GET /v1/webhooks/{id}/deliveries. One page, always has_more: false: GET /v1/stores, GET /v1/webhooks.

15Retrying safely#

• Every write (POST, PUT, DELETE) takes an optional Idempotency-Key header: 1 to 255 printable characters.
• The first answer is stored for 24 hours. A retry with the same key and the same request gets that answer back with Idempotent-Replayed: true, instead of running twice.
• The same key on a different request is 422 idempotency_key_reused; while the first request is still running, a retry is 409 idempotency_in_progress.
• A 5xx answer is not stored, so a retry with the same key runs again.
• POST /v1/webhooks answers its signing secret only the first time: a replay carries secret: null and a note.
• Over MCP, a write tool takes the same value as its idempotency_key argument.

16Webhook events#

• Add up to 10 endpoints per workspace: https, port 443, a public host (no IP addresses, nothing that resolves to a private network). Redirects are never followed.
• Each delivery is a POST with webhook-id (the same on every retry, so you can drop repeats), webhook-timestamp (Unix seconds) and webhook-signature: v1, and the base64 HMAC-SHA256 of {webhook-id}.{webhook-timestamp}.{body}, keyed with the base64-decoded part of your whsec_ secret after the prefix (Standard Webhooks).
• Answer any 2xx within 10 seconds. Anything else, or no answer, is a failure.
• The body is {type, timestamp, data}. Payloads carry ids, amounts and plain words: never a key, token, secret or email address.
• GET /v1/events lists what Whop told Greenset under Whop's own names: a deposit Whop reports as deposit.succeeded is listed there as deposit.succeeded and sent to your endpoints as deposit.received.
• Switching an endpoint off or on, sending a delivery again and reading every delivery are in Greenset (Developers, then Webhooks); a new secret means deleting the endpoint and adding it again.
• Up to 8 attempts: the first right away, then retries after 10 s, 1 min, 5 min, 30 min, 2 h, 6 h and 12 h, each wait counted from the attempt before, so the last is about 20.6 hours after the first; nothing is sent once 24 hours have passed. 20 failed attempts in a row switch the endpoint off, and the workspace's owners get one email.

import crypto from "node:crypto";

// raw: the body exactly as received (a string). headers: lower-case names.
export function verifyGreenset(raw, headers, secret) {
  const id = headers["webhook-id"], ts = headers["webhook-timestamp"];
  if (!id || !ts || Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false;
  const key = Buffer.from(secret.slice("whsec_".length), "base64");
  const want = crypto.createHmac("sha256", key).update(id + "." + ts + "." + raw).digest();
  return (headers["webhook-signature"] || "").split(" ").some((part) => {
    const [v, sig] = part.split(",");
    const got = Buffer.from(sig || "", "base64");
    return v === "v1" && got.length === want.length && crypto.timingSafeEqual(got, want);
  });
}

import base64, hashlib, hmac, time


def verify_greenset(raw: bytes, headers: dict, secret: str) -> bool:
    """raw: the body exactly as received (bytes). headers: lower-case names."""
    msg_id = headers.get("webhook-id")
    ts = headers.get("webhook-timestamp", "")
    if not msg_id or not ts.isdigit() or abs(time.time() - int(ts)) > 300:
        return False
    key = base64.b64decode(secret[len("whsec_"):])
    signed = msg_id.encode() + b"." + ts.encode() + b"." + raw
    want = base64.b64encode(hmac.new(key, signed, hashlib.sha256).digest()).decode()
    for part in headers.get("webhook-signature", "").split(" "):
        version, _, sig = part.partition(",")
        if version == "v1" and hmac.compare_digest(sig, want):
            return True
    return False

17MCP and AI tools#

• The MCP server serves the same operations as tools over Streamable HTTP, one tool per scoped operation (20 tools), named from the operationId (getAccount is get_account). tools/list shows only the tools the key's scopes allow.
• Protocol versions 2026-07-28 (stateless) and 2025-11-25, 2025-06-18, 2025-03-26 (start with initialize). POST one JSON-RPC message per request; GET and DELETE answer 405.
• Authentication is the same key, as Authorization: Bearer on every request. OAuth sign-in for MCP is not offered.
• A tool call runs the /v1 operation itself with the caller's key: the same scope check, rate limits, validation, idempotency, audit and spend checks. Failures come back as a tool result with isError and the /v1 error body.
• A browser request from another site's Origin is refused (403 forbidden_origin). A request with no Origin header, as a terminal, an editor or a server-side client sends, is accepted.

Name                   Greenset
Remote MCP server URL  https://app.greenset.ai/mcp
Authentication         No sign in
Request headers        Authorization: Bearer <paste your Greenset key here>

Name                   Greenset
Remote MCP server URL  https://app.greenset.ai/mcp
Authentication         No sign in
Request headers        Authorization: Bearer <paste your Greenset key here>

claude mcp add --transport http greenset --scope user https://app.greenset.ai/mcp \
  --header "Authorization: Bearer $GREENSET_KEY"

{
  "mcpServers": {
    "greenset": {
      "type": "http",
      "url": "https://app.greenset.ai/mcp",
      "headers": {
        "Authorization": "Bearer ${GREENSET_KEY}"
      }
    }
  }
}

{
  "mcpServers": {
    "greenset": {
      "url": "https://app.greenset.ai/mcp",
      "headers": {
        "Authorization": "Bearer ${env:GREENSET_KEY}"
      }
    }
  }
}

codex mcp add greenset --url https://app.greenset.ai/mcp --bearer-token-env-var GREENSET_KEY

[mcp_servers.greenset]
url = "https://app.greenset.ai/mcp"
bearer_token_env_var = "GREENSET_KEY"
tool_timeout_sec = 120

{
  "greenset": {
    "url": "https://app.greenset.ai/mcp",
    "headers": {
      "Authorization": "Bearer <paste your Greenset key here>"
    }
  }
}

{
  "mcpServers": {
    "greenset": {
      "url": "https://app.greenset.ai/mcp",
      "headers": {
        "Authorization": "Bearer <paste your Greenset key here>"
      }
    }
  }
}

{
  "inputs": [
    {
      "type": "promptString",
      "id": "greenset-key",
      "description": "Greenset API key",
      "password": true
    }
  ],
  "servers": {
    "greenset": {
      "type": "http",
      "url": "https://app.greenset.ai/mcp",
      "headers": {
        "Authorization": "Bearer ${input:greenset-key}"
      }
    }
  }
}

gemini mcp add --scope user --transport http \
  --header "Authorization: Bearer $GREENSET_KEY" greenset https://app.greenset.ai/mcp

URL         https://app.greenset.ai/mcp
Transport   Streamable HTTP
Header      Authorization: Bearer $GREENSET_KEY

18Versions and support#

• Every route is under /v1. This is API version 1.0.0 (info.version in /v1/openapi.json).
• No /v1 route has been removed. Routes, fields and error codes that change are listed in the changelog below; the wording of a fact or a message can change without a row.
• The machine-readable reference is https://app.greenset.ai/v1/openapi.json (OpenAPI 3.1, public). AI agents read https://app.greenset.ai/llms.txt and https://app.greenset.ai/llms-full.txt.
• Every answer carries an X-Request-Id header (req_ and 16 characters), and error bodies repeat it as error.request_id. Quote it when you write to hello@greenset.ai: it finds the call in your workspace's audit log.

What the API doesn't do

• Switching a webhook endpoint off or on, sending a delivery again and rotating its secret over the API: they are in Greenset only.
• Pages on GET /v1/stores and GET /v1/webhooks: each answers one page (a workspace has at most 10 endpoints; stores are capped at 100 per answer).
• Test keys: there is one kind of key, gsk_live_. Use dry-run drafts to try the API without spending.
• OAuth sign-in for MCP: connect with a key in a header.
• Stop-all while Terms are outdated: like every write, POST /v1/stop-all answers 428 until the key's maker accepts the new Terms in Greenset.

19Changelog#

Dated when each change was made (UTC).