API reference
API reference
The Koast REST API. Every brand-scoped resource lives under /v1/brands/{brandId}. Lists are cursor-paginated, errors share one envelope, and every response carries a Koast-Request-Id header.
The Koast REST API. Every brand-scoped resource lives under /v1/brands/{brandId}. Lists are cursor-paginated, errors share one envelope, and every response carries a Koast-Request-Id header.
Generated from the OpenAPI document of Koast API version 1.0.0.
Conventions
Base URL
Send every request to https://api.koast.ai/v1. The paths on these pages include the /v1 prefix.
Authentication
Send Authorization: Bearer <token> on every request.
An organization API key (koast_sk_…) with the API surface enabled, or an OAuth access token issued by Koast (koast_at_…) whose audience covers this API. REST access requires an active Agency plan.
Request headers
| Header | Description |
|---|---|
Idempotency-Key | Retrying with the same key within 24 hours returns the first response without acting again. Required on edit-live-campaign, launch-campaign, optional on 32 other operations. |
Response headers
| Header | Type | Description |
|---|---|---|
Koast-Request-Id | string | Unique id of this request; quote it to support. |
RateLimit-Limit | integer | Requests allowed per minute for this organization in this bucket (read or write). |
RateLimit-Remaining | integer | Requests left in the current window. |
RateLimit-Reset | integer | Seconds until the window resets. |
Retry-After | integer | Seconds to wait before retrying. |
Errors
Every error response has the same JSON body.
| Field | Type | Required | Description |
|---|---|---|---|
error | object | Yes | |
error.code | string | Yes | Stable machine-readable code. One of unauthenticated, plan_required, surface_disabled, audience_mismatch, insufficient_scope, brand_not_allowed, validation_failed, not_found, capability_unsupported, spend_ceiling_exceeded, spend_ceiling_required, forbidden, rate_limited, idempotency_conflict, idempotency_key_required, stale_read, conflict, unprocessable, account_ambiguous, unavailable, webhooks_unavailable, timeout, internal_error. |
error.message | string | Yes | |
error.details | object[] | object | null | Yes | Field-level issues for validation_failed; otherwise extra context or null. |
error.requestId | string | Yes | Same value as the Koast-Request-Id header. |
{
"error": {
"code": "unauthenticated",
"message": "string",
"details": [
{
"field": "string",
"message": "string",
"code": "string"
}
],
"requestId": "string"
}
}| Status | Meaning |
|---|---|
400 | The input failed validation (validation_failed) or a required header is missing (idempotency_key_required). |
401 | Missing, unknown, revoked or expired credential. |
403 | The credential is not allowed to do this: insufficient_scope (missing read/write/publish scope), brand_not_allowed (outside the key's brand list), forbidden (no access to the brand, launch or account), plan_required, surface_disabled, spend_ceiling_required, spend_ceiling_exceeded. |
404 | The resource does not exist or is not visible to this credential. |
409 | idempotency_conflict (the Idempotency-Key was reused with a different request or is still in flight), stale_read (the resource changed since it was read) or conflict (the request conflicts with the resource's current state, such as a live node, a concurrent edit or a racing secret rotation). |
422 | The request is valid but cannot be carried out (capability_unsupported, account_ambiguous). |
429 | Rate limit or concurrency limit reached. |
500 | Unexpected failure. |
503 | A dependency is not available right now (unavailable), or webhooks are not available in this environment (webhooks_unavailable). |
504 | The request did not finish in time. A write may still complete; retry with the same Idempotency-Key. |
Pagination
12 list operations are cursor-paginated and take these query parameters.
| Parameter | Type | Description |
|---|---|---|
cursor | string | Opaque cursor from the previous page's nextCursor. Omit for the first page. |
limit | integer | Page size. Default 50. Minimum 1, maximum 100. |
The response carries nextCursor. Pass as cursor to read the next page. Null when there is no next page.
Operations
Activity
| Operation | Method | Path |
|---|---|---|
| Get team activity log | GET | /v1/brands/{brandId}/activity |
Ad Accounts
| Operation | Method | Path |
|---|---|---|
| List ad account campaigns | GET | /v1/brands/{brandId}/ad-accounts/{accountId}/campaigns |
| List lead forms | GET | /v1/brands/{brandId}/ad-accounts/{accountId}/lead-forms |
| Get account naming convention | GET | /v1/brands/{brandId}/ad-accounts/{accountId}/naming-convention |
| Get asset and targeting options | GET | /v1/brands/{brandId}/ad-accounts/{accountId}/options |
| Get account overview | GET | /v1/brands/{brandId}/ad-accounts/{accountId}/overview |
Automations
| Operation | Method | Path |
|---|---|---|
| List automations | GET | /v1/brands/{brandId}/automations |
| Save automation | POST | /v1/brands/{brandId}/automations |
| Get automation | GET | /v1/brands/{brandId}/automations/{automationId} |
| Delete automation | DELETE | /v1/brands/{brandId}/automations/{automationId} |
| Set automation status | PATCH | /v1/brands/{brandId}/automations/{automationId}/status |
Brands
| Operation | Method | Path |
|---|---|---|
| List my ad accounts | GET | /v1/brands |
Copies
| Operation | Method | Path |
|---|---|---|
| Generate ad copy | POST | /v1/brands/{brandId}/copies |
| Get generated ad copy | GET | /v1/brands/{brandId}/copies/{copyId} |
Creatives
| Operation | Method | Path |
|---|---|---|
| List creatives | GET | /v1/brands/{brandId}/creatives |
| Upload creative | POST | /v1/brands/{brandId}/creatives |
Integrations
| Operation | Method | Path |
|---|---|---|
| Connect ClickFlare | POST | /v1/brands/{brandId}/integrations/clickflare |
| Disconnect ClickFlare | DELETE | /v1/brands/{brandId}/integrations/clickflare |
| List ClickFlare campaign mappings | GET | /v1/brands/{brandId}/integrations/clickflare/mappings |
| Update ClickFlare campaign mapping | PUT | /v1/brands/{brandId}/integrations/clickflare/mappings/{providerCampaignId} |
| Get ClickFlare spend push | GET | /v1/brands/{brandId}/integrations/clickflare/push |
| Update ClickFlare spend push | PUT | /v1/brands/{brandId}/integrations/clickflare/push |
| Get ClickFlare settings | GET | /v1/brands/{brandId}/integrations/clickflare/settings |
| Update ClickFlare settings | PATCH | /v1/brands/{brandId}/integrations/clickflare/settings |
| List RedTrack campaign mappings | GET | /v1/brands/{brandId}/integrations/redtrack/mappings |
| Update RedTrack campaign mapping | PUT | /v1/brands/{brandId}/integrations/redtrack/mappings/{providerCampaignId} |
| Get RedTrack spend push | GET | /v1/brands/{brandId}/integrations/redtrack/push |
| Update RedTrack spend push | PUT | /v1/brands/{brandId}/integrations/redtrack/push |
Launches
| Operation | Method | Path |
|---|---|---|
| List Koast batches | GET | /v1/brands/{brandId}/launches |
| Create campaign launch | POST | /v1/brands/{brandId}/launches |
| Clone live campaign | POST | /v1/brands/{brandId}/launches/clone |
| Import live campaign | POST | /v1/brands/{brandId}/launches/import |
| Delete batch or pipeline card | DELETE | /v1/brands/{brandId}/launches/{launchId} |
| Add ad set | POST | /v1/brands/{brandId}/launches/{launchId}/ad-sets |
| Get ad set details | GET | /v1/brands/{brandId}/launches/{launchId}/ad-sets/{adsetId} |
| Swap creatives | POST | /v1/brands/{brandId}/launches/{launchId}/ad-sets/{adsetNodeId}/creatives/swap |
| Attach lead form | POST | /v1/brands/{brandId}/launches/{launchId}/ad-sets/{adsetNodeId}/lead-form |
| Add ads | POST | /v1/brands/{brandId}/launches/{launchId}/ads |
| Get ad details | GET | /v1/brands/{brandId}/launches/{launchId}/ads/{adId} |
| Add campaign | POST | /v1/brands/{brandId}/launches/{launchId}/campaigns |
| Import campaigns | POST | /v1/brands/{brandId}/launches/{launchId}/campaigns/import |
| Compute creative fatigue | GET | /v1/brands/{brandId}/launches/{launchId}/creative-fatigue |
| Distribute creative | POST | /v1/brands/{brandId}/launches/{launchId}/creatives/distribute |
| Get ad delivery status | GET | /v1/brands/{brandId}/launches/{launchId}/delivery-status |
| Get daily insights | GET | /v1/brands/{brandId}/launches/{launchId}/insights/daily |
| Get metrics | GET | /v1/brands/{brandId}/launches/{launchId}/metrics |
| Remove items from campaign tree | POST | /v1/brands/{brandId}/launches/{launchId}/nodes/remove |
| Update campaign, ad set or ad | PATCH | /v1/brands/{brandId}/launches/{launchId}/nodes/{nodeId} |
| Duplicate ad set or ad | POST | /v1/brands/{brandId}/launches/{launchId}/nodes/{nodeId}/duplicate |
| Edit live campaign budget | POST | /v1/brands/{brandId}/launches/{launchId}/nodes/{nodeId}/live-budget |
| Rename campaign, ad set or ad | POST | /v1/brands/{brandId}/launches/{launchId}/nodes/{nodeId}/rename |
| Duplicate and vary | POST | /v1/brands/{brandId}/launches/{launchId}/nodes/{nodeId}/variations |
| Launch campaign | POST | /v1/brands/{brandId}/launches/{launchId}/publish |
| Get settings | GET | /v1/brands/{brandId}/launches/{launchId}/settings |
| Update settings | PATCH | /v1/brands/{brandId}/launches/{launchId}/settings |
| Save campaign snapshot template | POST | /v1/brands/{brandId}/launches/{launchId}/snapshot-templates |
| Apply campaign snapshot template | POST | /v1/brands/{brandId}/launches/{launchId}/snapshot-templates/{templateId}/apply |
| Turn launch into structure template | POST | /v1/brands/{brandId}/launches/{launchId}/structure-templates |
| Apply structure template | POST | /v1/brands/{brandId}/launches/{launchId}/structure-templates/{templateId}/apply |
| Get targeting options | GET | /v1/brands/{brandId}/launches/{launchId}/targeting-options |
| Get campaign tree | GET | /v1/brands/{brandId}/launches/{launchId}/tree |
| Validate launch | GET | /v1/brands/{brandId}/launches/{launchId}/validation |
Pipeline
| Operation | Method | Path |
|---|---|---|
| Move pipeline card | POST | /v1/brands/{brandId}/pipeline/cards/move |
| List pipeline columns | GET | /v1/brands/{brandId}/pipeline/columns |
| Configure pipeline column | PATCH | /v1/brands/{brandId}/pipeline/columns/{columnId} |
| Create pipeline card | POST | /v1/brands/{brandId}/pipeline/tickets |
Snapshot Templates
| Operation | Method | Path |
|---|---|---|
| List campaign snapshot templates | GET | /v1/brands/{brandId}/snapshot-templates |
| Delete campaign snapshot template | DELETE | /v1/brands/{brandId}/snapshot-templates/{templateId} |
Structure Templates
| Operation | Method | Path |
|---|---|---|
| List structure templates | GET | /v1/brands/{brandId}/structure-templates |
| Create structure template | POST | /v1/brands/{brandId}/structure-templates |
| Get structure template | GET | /v1/brands/{brandId}/structure-templates/{templateId} |
| Delete structure template | DELETE | /v1/brands/{brandId}/structure-templates/{templateId} |
| Edit structure template rules | PATCH | /v1/brands/{brandId}/structure-templates/{templateId} |
Webhooks
| Operation | Method | Path |
|---|---|---|
| List webhook endpoints | GET | /v1/webhooks |
| Create webhook endpoint | POST | /v1/webhooks |
| Get webhook endpoint | GET | /v1/webhooks/{endpointId} |
| Delete webhook endpoint | DELETE | /v1/webhooks/{endpointId} |
| Update webhook endpoint | PATCH | /v1/webhooks/{endpointId} |
| List webhook deliveries | GET | /v1/webhooks/{endpointId}/deliveries |
| Enable webhook endpoint | POST | /v1/webhooks/{endpointId}/enable |
| Resend failed webhook deliveries | POST | /v1/webhooks/{endpointId}/resend-failed |
| Rotate webhook secret | POST | /v1/webhooks/{endpointId}/rotate-secret |
| Get webhook secret | GET | /v1/webhooks/{endpointId}/secret |
| Send webhook test event | POST | /v1/webhooks/{endpointId}/test |
Workflows
| Operation | Method | Path |
|---|---|---|
| List workflows | GET | /v1/brands/{brandId}/workflows |
| Save workflow | POST | /v1/brands/{brandId}/workflows |
| Get workflow | GET | /v1/brands/{brandId}/workflows/{workflowId} |
| Delete workflow | DELETE | /v1/brands/{brandId}/workflows/{workflowId} |
| Get workflow execution | GET | /v1/brands/{brandId}/workflows/{workflowId}/executions/{executionId} |
| Run workflow | POST | /v1/brands/{brandId}/workflows/{workflowId}/runs |
| Set workflow status | PATCH | /v1/brands/{brandId}/workflows/{workflowId}/status |
CLI
Install the koast command line, sign in with an API key or your browser, and run any API operation as a command.
Get team activity log
Returns the team activity log for the brand, who changed what and when, over the last days days. Filter by userId or entityId. activities is the cursor-paginated collection (limit, cursor, nextCursor); summary counts the activities of the returned page.