Choosing a brand

A brand is a workspace: its own identities, drafts, connected accounts, queue and metrics. An account can hold several, and one token reaches all of them.

So most endpoints need to know which brand you mean. That is what the X-Postlyra-Brand header is for.

The header

curl https://api.postlyra.com/ideas/mining-context \
  -H "Authorization: Bearer $POSTLYRA_TOKEN" \
  -H "X-Postlyra-Brand: 0f8fad5b-d9cb-469f-a165-70867728950e"

The value is a brand id: the brand's slug, a UUID minted when the brand is created. List them with GET /teams:

{
  "teams": [
    { "id": 1, "name": "My Brand", "slug": "0f8fad5b-d9cb-469f-a165-70867728950e" },
    { "id": 2, "name": "Side Project", "slug": "7c9e6679-7425-40de-944b-e07fc1f90ae7" }
  ]
}

Use slug, not id.

What happens without the header

Situation	Result
Header sent, you belong to that brand	That brand is used for this request only
Header sent, you do not belong to it	403, with a message telling you to call GET /teams
No header, account has one brand	That brand is used
No header, account has several	Your last-selected brand in Studio is used
No header, no brand at all	403 No team selected.

Passing the header never changes which brand is selected in the Studio UI. It applies to that one request.

Always send it

Relying on the fallback means a script's behaviour depends on what you last clicked in a browser. Send the header explicitly on every call and that whole class of bug disappears.

One endpoint ignores the header

GET /me/entitlements reads your currently-selected brand directly and does not look at X-Postlyra-Brand at all.

To check entitlements for a specific brand, switch first:

curl -X PATCH https://api.postlyra.com/me/team \
  -H "Authorization: Bearer $POSTLYRA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"team_id": 2}'

PATCH /me/team takes the numeric id, not the slug, and it does persist the selection. See Entitlements.

On MCP

The MCP server uses the same model with a different spelling: every tool takes an optional brand argument holding the same brand id. See Choosing a brand on MCP.