Build with VERSE.
VERSE is the AI-native programmatic in-venue DOOH platform. These docs cover the public REST API powering everything inside Ads Manager, Screen Manager, and Agency Suite. Bearer-authenticated, JSON only, idempotent on writes, versioned at /v1.
Pick your surface
VERSE has three audiences and three product surfaces. Each has a matching API surface scoped to a workspace token. You can combine them: an agency token, for example, can act on its sub-account workspaces.
Create and manage campaigns, upload creatives, run forecasts, pull live impressions, scans, and brand-lift reporting. Pay per impression at £0.0061 on the UK premium rate.
/campaigns · /creatives · /forecasts · /reportingPair displays in 60 seconds, schedule playlists, generate AI menus, query payouts. Free signage forever. Up to 50% of ad revenue back when ad fill is enabled and a VERSE Sense module is paired.
/screens · /pairing · /playlists · /payoutsManage ring-fenced sub-accounts per client, run cross-roster reporting, export consolidated billing. Up to 30% off platform CPM on every impression once a roster is live.
/agency/clients · /agency/reports · /invoicesConventions
The same rules apply across every surface. Read these once, skip them in the per-resource pages.
Versioning
Everything is namespaced under /v1/. Breaking changes ship behind a new major version (/v2/) with a 12-month overlap window. Additive changes (new fields on a response, new optional query params) ship in place and are flagged in the changelog.
JSON only
Requests and responses are JSON. Send Content-Type: application/json on writes; we always send application/json; charset=utf-8 back. There is no XML, form-encoded, or RPC surface, anywhere. File uploads (creatives) use signed URLs returned by POST /creatives, the binary itself is uploaded directly to object storage.
Idempotency
Every mutating endpoint accepts an Idempotency-Key header. Send a UUID per logical operation; we cache the response for 24 hours. Retried requests return the original result without re-executing. Without a key, retries can double-charge wallets, so it is strongly recommended on every POST and DELETE.
Idempotency-Key: 8c2b7e1c-2a4d-4f3e-9c87-3f2d1c81f9a4Authentication
Every request carries an Authorization: Bearer sk_live_... header. Tokens are issued from your VERSE workspace under Settings → API keys. Tokens are scoped to a single workspace and can be created with read-only or read-write privileges; a separate sandbox key prefix (sk_test_...) hits the staging environment.
curl https://api.verse.ad/v1/campaigns \
-H "Authorization: Bearer sk_live_..."One token per integration. If your billing tool, your in-house dashboard, and your DSP all need access, mint three separate tokens. Rate limits apply per token, not per workspace.
Pagination
List endpoints return up to 50 items per page by default. Pass ?limit= (1, 100) and ?cursor= for stable cursor pagination. Responses include has_more and a next_cursor string when applicable. Cursors are opaque, do not parse them.
Errors
| Status | Meaning |
|---|---|
| 400 | Validation failed (see error.fields for the offending paths) |
| 401 | Missing or invalid bearer token |
| 403 | Token lacks scope for this workspace or resource |
| 404 | Resource not found in this workspace |
| 409 | Idempotency key conflict, or business-state conflict (campaign already approved, etc.) |
| 422 | Semantic validation failed (forecast unservable, budget below floor) |
| 429 | Rate limit exceeded, retry after Retry-After |
| 5xx | Platform error, retry with exponential backoff (250ms, 500ms, 1s, 2s, 4s, max 60s) |
Rate limits
Default is 600 requests per minute per token, with a burst capacity of 200 requests per second. Higher limits are raised on request, write to hello@verse.ad with a one-line description of the integration. Every response carries X-RateLimit-Remaining and X-RateLimit-Reset headers.
Regions and currency
The API is single-tenant per region but routed transparently. Workspaces created in the UK report in GBP; USA, Canada, Western Europe, and Tunisia report in their local currencies. Spend, payouts, and invoices are returned in workspace currency unless ?currency=GBP is passed on aggregation endpoints.
Get started in five steps
You can be live in well under an hour. The shape is the same whether you are a brand, an agency, or a venue group integrating Screen Manager.
- 01
Create your workspace
Sign up at hub.verse.ad/register. Pick the audience (brand, agency, venue) on creation. Workspaces are free; you only pay when impressions deliver or media is reserved.
- 02
Mint a token
In your VERSE workspace go to Settings, API keys, New token. Pick a scope (read-only or read-write) and copy the
sk_live_...string. It is shown once, store it in your secrets manager. - 03
Make your first call
GET /v1/mereturns the workspace identity, region, and active token scope. If the response is 200, you are wired up. - 04
Run a forecast or pair a screen
Brands:
POST /v1/forecastswith a brief and a budget. Venues:POST /v1/pairingto mint a 6-digit code valid for 60 seconds. Agencies:POST /v1/agency/clientsto spin up a sub-account. - 05
Subscribe to webhooks
Register an endpoint with
POST /v1/webhooksfor the events you care about (campaign approved, scan recorded, payout issued). Verify every payload with the signing secret returned at registration.
Where to go next
API reference, every endpoint, request, response.
DOOH glossary, plain-English definitions of CPM, dwell, daypart, in-venue, attribution.
Status
Per-surface guides marked Soon in the sidebar are in active drafting. Production endpoints are stable and used by the live VERSE platform; integrations against them should reference the API reference. For anything not yet documented, hello@verse.ad reaches an engineer the same day.