Quickstart

Create an organization API key, make your first request with curl and run your first koast command.

You'll create an API key, list your brands, read a launch list and run the same calls from the koast CLI. You need an Agency plan and the owner or admin role in your Koast organization.

1. Create an API key

In Koast, open Settings, then API Keys, and select Create key.
Under Name, enter a name you'll recognise later, like Reporting job.
Under Access, tick Read. Add Write or Publish only when your code needs them.
Under Works with, turn on API. New keys have MCP on and API off.
Optionally, limit the key to some Brands and set an Expiry.
Create the key, then copy it from Copy your API key. Koast shows it once. It starts with koast_sk_.

Keep the key in an environment variable, never in source control:

export KOAST_API_KEY=koast_sk_...

Treat the key like a password

A key acts for your whole organization, within its scopes and brands. If it leaks, revoke it in API Keys and create a new one.

2. List your brands

curl https://api.koast.ai/v1/brands \
  -H "Authorization: Bearer $KOAST_API_KEY"

HTTP/1.1 200 OK
Koast-Request-Id: 17acddf7-b970-4490-89fb-3d8d17cac9df
RateLimit-Limit: 300
RateLimit-Remaining: 299
RateLimit-Reset: 18
Content-Type: application/json; charset=utf-8

{
  "accounts": [
    {
      "brandId": 1,
      "brandName": "Vela Supplements",
      "accountId": "act_000000000000001",
      "accountName": "Vela Supplements · US-1",
      "connected": true,
      "active": false,
      "organizationId": 1
    },
    {
      "brandId": 2,
      "brandName": "Nimbus Sleep",
      "accountId": "biz_fixture0000001",
      "accountName": "Nimbus Sleep",
      "connected": true,
      "active": false,
      "organizationId": 1
    }
  ],
  "nextCursor": null
}

Each row is one brand and its ad account. Keep the brandId: every other endpoint takes it in the path.

3. Read the brand's launches

curl "https://api.koast.ai/v1/brands/1/launches?limit=2" \
  -H "Authorization: Bearer $KOAST_API_KEY"

{
  "accountId": null,
  "total": 3,
  "page": 1,
  "limit": 2,
  "batches": [
    {
      "id": "cmv0dbqmv0001vct12clu58vk",
      "title": "2026/09/19 | PUR | Vela Daily Greens | CBO",
      "description": null,
      "status": "DRAFT",
      "createdAt": "2026-10-09T02:50:45.268Z",
      "updatedAt": "2026-10-09T02:50:45.384Z",
      "campaignsCount": 1,
      "adsetsCount": 0,
      "adsCount": 0
    },
    {
      "id": "cmv09p0ny000bvcdsyaeedbj7",
      "title": "2026/09/12 | PUR | Vela Daily Greens | CBO",
      "description": null,
      "status": "DRAFT",
      "createdAt": "2026-10-09T01:09:06.334Z",
      "updatedAt": "2026-10-09T01:09:06.334Z",
      "campaignsCount": 0,
      "adsetsCount": 0,
      "adsCount": 0
    }
  ],
  "nextCursor": "eyJjIjoiMjAyNi0xMC0wOVQwMTowOTowNi4zMzRaIiwiaSI6ImNtdjA5cDBueTAwMGJ2Y2RzeWFlZWRiajcifQ",
  "asOf": "2026-10-09T04:46:47.237Z"
}

nextCursor isn't null, so there's another page. Pass it back as ?cursor= to get it. See Pagination.

4. Run the same calls from the CLI

npm install -g @koast.ai/cli
koast list-my-ad-accounts --output table

brandId  brandName         accountId            accountName              connected  active  organizationId
1        Vela Supplements  act_000000000000001  Vela Supplements · US-1  true       false   1
2        Nimbus Sleep      biz_fixture0000001   Nimbus Sleep             true       false   1

The CLI reads KOAST_API_KEY from the environment. Every endpoint is a command named after its operation id:

koast list-koast-batches --brand 1 --limit 2

See CLI for sign-in, flags and exit codes.

Next steps

Authentication: scopes, brand limits, expiry and the publish ceiling.
Errors: what a failed call looks like, and which codes to handle.
Webhooks: get told when a launch finishes instead of polling.
API reference: every endpoint.