Platform API

The Platform API lets your own scripts and apps read Bloss data. It's read-only, so nothing can be changed, posted or paid through it. It has two parts:

• Creator API: everything a creator or a coach can read about their own work: your account, your creator profile and stats, the brands you create for, your videos, views, earnings and payouts, bounties, and your coaching workspace. It's free. You don't need a paid plan.
• Brand API: what a brand admin sees about a brand: its settings and team, creators, videos, analytics and campaign reach, and for full admins its pay data. It needs the brand to be on the Scale plan. See Brand API.

QuickstartCopy Anchor Link

curl https://www.bloss.app/api/v1/me \
  -H "Authorization: Bearer $BLOSS_API_TOKEN"

{
  "id": "…",
  "name": "Sam Rivera",
  "email": "sam@example.com",
  "creator": { "id": "…", "slug": "sam-rivera", "listingStatus": "public" },
  "coach": null,
  "brands": [
    {
      "id": "…",
      "name": "Glow Skincare",
      "slug": "glow",
      "adminTier": null,
      "creatorStatus": "active"
    }
  ]
}

BasicsCopy Anchor Link

A token reads only what its permissions allow, and only data you can see in the app yourself. A brand you don't belong to, or a resource that isn't yours, answers 404, exactly as if it didn't exist.

Money data is opt-inCopy Anchor Link

Earnings, payouts and your payout setup sit behind a separate permission, Your earnings, payouts and payout-account status, marked Money data on the token page. A token without it can't read any amount you earned or were paid, and asking returns 403 insufficient_scope.

Even with that permission, payout details are masked: you see where a brand pays you and whether your account there is set up, never a full email address or account number.

The Brand API works the same way: a brand's pay rules, payouts, spend, funds and subscription each need a permission marked Money data. See Who can read what.

Brand APICopy Anchor Link

The Brand API reads a brand the way its admins see it in Bloss. Use it to pull campaign numbers into a client report, keep a dashboard in sync, or let an AI agent answer questions about your program.

It's included in the Scale plan. See Plans and features. The Creator API doesn't depend on any plan.

What you can readCopy Anchor Link

The API calls a set a "pair" in a few places, for example in field descriptions. It's the same thing. Every endpoint in each area is in the Platform API reference.

Who can read whatCopy Anchor Link

• Money data needs a full admin. A limited admin who asks for pay data gets 403 forbidden, even if the token has the money permissions. Agency owners and agency admins are full admins of every brand in the agency. See Full vs limited admins.
• The subscription is the agency owner's. As in the app, where billing is owner-only, everyone else gets 403 forbidden, brand keys included.
• The brand must be on Scale. Otherwise every Brand API endpoint answers 403 plan_required, with details.requiredPlan set to "scale". The agency owner changes the brand's plan in agency billing.
• Access follows the app. Each request checks your access to the brand again, so a token stops reading a brand the moment you leave it or lose admin access.

Pay rules aren't part of the brand's settings in the API: base pay, bonus tiers and the payout model are on the money side, behind Payout settings, cycles and payouts.

Personal tokens and brand keysCopy Anchor Link

You can read the Brand API with either kind of credential.

Use a personal token for your own scripts and AI agents, or when you work across several brands. Use a brand key for an integration that should keep running when people join or leave the team, such as a client dashboard. See Brand keys.

A brand key asked about another brand answers 404. It can't call the Creator API or GET /me: those answer 403 forbidden. Older keys marked Campaign API (v0) only don't work on the Brand API at all (401); create a new key for it.

Every Brand API path takes the brand's id. Find it under SettingsIntegrationsAPI Keys, next to Brand ID, with a copy button. A personal token can also read it from GET /me.

ExamplesCopy Anchor Link

List the brand's payout cycles. Cycle days are YYYY-MM-DD in the brand's time zone, and current marks the cycle today falls in.

curl https://www.bloss.app/api/v1/brands/$BRAND_ID/cycles \
  -H "Authorization: Bearer $BLOSS_API_TOKEN"

{
  "data": [
    {
      "cycleId": "cyc_oct",
      "startDate": "2026-10-01",
      "endDate": "2026-10-31",
      "status": "pending",
      "current": true
    },
    {
      "cycleId": "cyc_sep",
      "startDate": "2026-09-01",
      "endDate": "2026-09-30",
      "status": "paid",
      "current": false
    }
  ]
}

A campaign is the cycles you pass in cycleIds. Get its reach, the videos and views, with a breakdown per cycle:

curl "https://www.bloss.app/api/v1/brands/$BRAND_ID/campaign/summary?cycleIds=cyc_sep,cyc_oct" \
  -H "Authorization: Bearer $BLOSS_API_TOKEN"

{
  "metrics": { "totalVideos": 412, "totalViews": 3180450 },
  "cycles": [
    {
      "cycleId": "cyc_sep",
      "startDate": "2026-09-01",
      "endDate": "2026-09-30",
      "status": "paid",
      "videos": 236,
      "views": 2011300
    },
    {
      "cycleId": "cyc_oct",
      "startDate": "2026-10-01",
      "endDate": "2026-10-31",
      "status": "pending",
      "videos": 176,
      "views": 1169150
    }
  ]
}

Get what the same campaign cost, against a prepaid budget of 5,000 US dollars, with spend and CPM per tag. This needs a full admin and the Payout settings, cycles and payouts permission:

curl "https://www.bloss.app/api/v1/brands/$BRAND_ID/campaign/spend?cycleIds=cyc_sep,cyc_oct&prepayment=5000&breakdown=tag" \
  -H "Authorization: Bearer $BLOSS_API_TOKEN"

Spend is base pay plus the CPM bonus, in US dollars. With prepayment, the response adds what remains, the share of the budget used, and atThreshold once spend reaches thresholdPct of it (70% by default). breakdown=day gives spend per day instead.

Compared with the Campaign API (v0)Copy Anchor Link

The Campaign API reads the same campaign data, and the Brand API's campaign endpoints count the same videos and views for the same cycles. Your existing Campaign API integrations keep working. If you move one to the Brand API, these are the differences:

Filters work as before: cycleIds makes up the campaign, and tagIds and groupIds narrow it.

ResponsesCopy Anchor Link

A successful response is the resource itself, as JSON. There's no wrapper around single resources.

Lists that can grow long are paginated and look like this:

{
  "data": [{ "id": "…" }, { "id": "…" }],
  "nextCursor": "WzE3NjA…"
}

PaginationCopy Anchor Link

nextCursor is null on the last page. Cursors are opaque: pass them back unchanged. Pages don't shift when new rows appear while you're paging. A cursor that's been edited, or that came from a different endpoint, returns 400 validation_failed.

Dates and timesCopy Anchor Link

• Calendar days are YYYY-MM-DD strings. For a brand's data, a day is a day in the brand's time zone, and responses that group by day include the timeZone they used. Your stats across all brands use UTC days.
• Instants (when a video was posted, when a payout was made) are ISO 8601 timestamps in UTC, for example 2026-10-22T14:05:00.000Z.
• Date ranges take from and to, both inclusive. Unless an endpoint says otherwise, to defaults to today and from to 30 days before it.

ErrorsCopy Anchor Link

Every error has the same shape:

{
  "error": {
    "code": "insufficient_scope",
    "message": "This token needs the creator:earnings permission.",
    "details": { "requiredScope": "creator:earnings" },
    "requestId": "6f1c…"
  }
}

Branch on code, which never changes. message is for people and may be reworded. details is there only when it helps, for example the parameters that failed validation.

Rate limitsCopy Anchor Link

By default the Creator API allows 60 requests a minute and the Brand API 300.

• Personal tokens are counted per user, across all your tokens, so creating more tokens doesn't give you more requests. The Creator API and the Brand API each have their own count.
• Brand keys are counted per key.

Every response that counts toward the limit carries:

Over the limit, you get 429 rate_limited with a Retry-After header in seconds. Wait that long before you retry, and spread out or batch your calls.

Keep tokens safeCopy Anchor Link

A token reads your earnings, videos and brands as you, and a brand key reads its brand as a full admin. Keep both out of front-end code, mobile apps, screenshots and public repositories. If one leaks, revoke it right away.

RelatedCopy Anchor Link

• API tokens: create, limit and revoke tokens and brand keys.
• AI agents (MCP): let Claude, Cursor and other agents read your data.
• Use your brand's data with AI agents: the Brand API for brand admins.
• Platform API reference: every endpoint.
• Campaign API reference: the earlier, campaign-only API.