List brand notes

Returns the brand's agent notes, newest first: learnings, burned-out creatives or angles, and constraints saved through approved chat cards. notes is the cursor-paginated collection (limit up to 20, cursor, nextCursor). Filter with kind, accountId, status and includeDue. Notes are read-only on this API.

GET

/v1/brands/{brandId}/notes

Authorization

bearerAuth

headerAuthorizationBearer <token>

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.

Path Parameters

brandId*integer

The brand the request acts on. Every brand-scoped resource lives under its brand.

Query Parameters

purpose?string

chat-start: the notes a chat loads when it begins (active, not due for review, brand-wide or this ad account; constraints first; at most 20 notes or 6,000 characters). browse: every note, filtered and paged, including notes due for review and retired ones.

Default"browse"

Value in"chat-start""browse"

kind?string

browse only: one kind of note.

Value in"LEARNING""BURNOUT""CONSTRAINT"

accountId?string

An ad account linked to this brand (for example act_123) when the note is about that account only. Leave it out for a brand-wide note.

Length1 <= length <= 64

status?string

browse only: ACTIVE (default), RETIRED, or ALL.

Default"ACTIVE"

Value in"ACTIVE""RETIRED""ALL"

includeDue?boolean

browse only: false to leave out active notes past their review date.

Defaulttrue

cursor?string

Opaque cursor from the previous page's nextCursor. Omit for the first page.

limit?integer

Page size.

Range1 <= value <= 100

Default50

Response Body

List brand notes

application/json

response

purpose*string

Value in"chat-start""browse"

brandId*number

notes*array<>

The paged collection, newest first (chat-start: constraints first). Follow nextCursor for the next page.

total*number

chat-start: the notes that could load. browse: the notes on this page.

more*number

chat-start: active notes not loaded (other ad accounts, over the cap, due for review). 0 for browse.

nextCursor*|

Pass as cursor to read the next page. Null when there is no next page.

[key: string]?unknown

curl -X GET "https://example.com/v1/brands/0/notes" \  -H "Authorization: Bearer koast_sk_..."

{  "purpose": "chat-start",  "brandId": 0,  "notes": [    {      "id": "string",      "kind": "LEARNING",      "outcome": "WORKED",      "text": "string",      "status": "ACTIVE",      "account": {        "provider": "string",        "externalAccountId": "string",        "property1": null,        "property2": null      },      "author": {        "kind": "AGENT_CHAT",        "userId": 0,        "property1": null,        "property2": null      },      "createdAt": "string",      "reviewBy": "string",      "due": true,      "evidence": [        {          "kind": "string",          "id": "string",          "property1": null,          "property2": null        }      ],      "supersedesId": "string",      "retiredAt": "string",      "retiredReason": "USER",      "property1": null,      "property2": null    }  ],  "total": 0,  "more": 0,  "nextCursor": "string",  "property1": null,  "property2": null}

Required scope: read. CLI: koast list-brand-notes, see Notes commands. Authentication, headers, errors and pagination work the same on every operation. See Conventions.