ViewsBase

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 with vb_cli_ still work.

Scopes

ScopeAllows
campaigns:readGET /campaigns, GET /campaigns/current
posts:readGET /posts, GET /posts/{id}, GET /posts/{id}/views
posts:writePATCH /posts/{id}/cpm, POST /posts/{id}/finalize, POST /posts/{id}/refresh
creators:readGET /creators, GET /creators/{id}
creators:writePOST /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": "..." }.

StatusCodeMeaning
401invalid_tokenThe key is missing, wrong, revoked or expired, or its admin left
402integrations_plan_requiredThe workspace plan has no API. upgradeUrl links to billing
403insufficient_scopeThe key does not have the scope this route needs
404The record is not in this key's workspace or campaign
429rate_limitedMore 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 pathPurpose
GET /postsPaginated scoped posts with saved deals and payment breakdowns
GET /posts/{id}One scoped post and its current creator offer
GET /posts/{id}/viewsSampled view history
GET /creators/{id}Creator details, campaign offer and link in bio (tracking_link); includes a private portal link
POST /creators/{id}/offerReplace that creator's campaign offer
POST /creators/{id}/linkSet or clear that creator's link in bio for the campaign
PATCH /posts/{id}/cpmChange effective CPM/cap for an eligible CPM post
POST /posts/{id}/finalizeClose an eligible post using saved terms
POST /posts/{id}/refreshFetch 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.

On this page