API
Workspace API keys, scopes and the /api/v1 reference.
The ViewsBase API lets your own scripts and tools read and change campaign data.
It comes with Growth, Scale, Agency and Enterprise. On Starter, calls and new keys
are refused with 402 and code integrations_plan_required.
There are two ways to connect:
- An API key, for scripts and servers. Only workspace admins create keys, in Settings → API keys. A key has the scopes the admin picks, and can be limited to one campaign.
- MCP, for AI apps such as Claude or ChatGPT. Every team member can connect through MCP. MCP uses that person's own access.
API keys
- The key shows once, when you create it. Keep it in a secret store.
- A key expires after 90 days. Revoke it at any time in Settings.
- A key works only while the admin who made it is still a workspace admin.
- New keys start with
vb_api_. Keys that start withvb_cli_still work.
Scopes
| Scope | Allows |
|---|---|
campaigns:read | GET /campaigns, GET /campaigns/current |
posts:read | GET /posts, GET /posts/{id}, GET /posts/{id}/views |
posts:write | PATCH /posts/{id}/cpm, POST /posts/{id}/finalize, POST /posts/{id}/refresh |
creators:read | GET /creators, GET /creators/{id} |
creators:write | POST /creators, POST /creators/{id}/offer, POST /creators/{id}/status, POST /creators/{id}/link |
GET /me works with any valid key. Use it as a health check.
Requests
curl https://viewsbase.com/api/v1/posts \
-H "Authorization: Bearer vb_api_..." \
-H "X-ViewsBase-Campaign: my-campaign"Send X-ViewsBase-Campaign (campaign ID or slug) on campaign requests. A key
limited to one campaign uses that campaign.
Errors
Errors are JSON: { "error": "...", "code": "..." }.
| Status | Code | Meaning |
|---|---|---|
401 | invalid_token | The key is missing, wrong, revoked or expired, or its admin left |
402 | integrations_plan_required | The workspace plan has no API. upgradeUrl links to billing |
403 | insufficient_scope | The key does not have the scope this route needs |
404 | The record is not in this key's workspace or campaign | |
429 | rate_limited | More than 120 requests in a minute. Wait for Retry-After seconds |
Offer example
[
{
"payment_type": "per_post",
"name": "Per post + bonus",
"cpm": 0,
"cap_type": "views",
"post_terms": {
"version": 1,
"amount": 15,
"minimum_views": 300,
"posts_per_period": 20,
"period_days": 30,
"starts_at": "2026-10-01T00:00:00Z",
"counting_window_days": 30,
"bonus": {
"type": "milestones",
"milestones": [
{ "views": 100000, "amount": 100 },
{ "views": 250000, "amount": 250 }
]
}
}
}
]Endpoints
The base path is /api/v1 (the older /api/cli/v1 path still works). Data responses
use Cache-Control: no-store. No raw creator access code, token, proof link,
or payment reference is returned by these post endpoints.
| Method and path | Purpose |
|---|---|
GET /posts | Paginated scoped posts with saved deals and payment breakdowns |
GET /posts/{id} | One scoped post and its current creator offer |
GET /posts/{id}/views | Sampled view history |
GET /creators/{id} | Creator details, campaign offer and link in bio (tracking_link); includes a private portal link |
POST /creators/{id}/offer | Replace that creator's campaign offer |
POST /creators/{id}/link | Set or clear that creator's link in bio for the campaign |
PATCH /posts/{id}/cpm | Change effective CPM/cap for an eligible CPM post |
POST /posts/{id}/finalize | Close an eligible post using saved terms |
POST /posts/{id}/refresh | Fetch fresh views for one active post now (Scale and up; once per post every 10 minutes; daily workspace limit). Returns 402, 429 or 502 when refused or the fetch fails |
The offer request is { "compensation_mode": "cpm", "deal": [...] }, using the
same array as offer.json. Pending and no-CPM modes use an empty deal. The route
rejects unsupported fields and invalid terms with 400. It returns 409 for a
locked per-post schedule. Success returns the creator ID, campaign ID, handle,
compensation mode, and deal.
The link request is { "tracking_link": "https://link.example.com/handle" }.
Send null or "" to clear the link. The link must be an http:// or
https:// URL of at most 2048 characters. It is saved as given, with no UTM
changes, and applies to this campaign only. Success returns the creator ID,
campaign ID, handle, and the saved tracking_link. GET /creators and
GET /creators/{id} return the same tracking_link (null when none is saved).
The finalize request body is {}. 409 means the post is frozen, its window is
open, or its current state does not allow the action. A per-post refresh failure
returns 502; read the post before retrying. A successful response contains
post, including its stored amount and available breakdown. Missing or
out-of-scope records return 404; insufficient permissions return 403.
Expired or revoked keys return 401.