Introduction

The Revinel API is how your site talks to Revinel. Use it to:

Serve the ads currently running on your site
Record impressions and clicks
List the tiers an advertiser can buy
Start a checkout for a tier

Most integrations never call these endpoints by hand. The SDKs wrap them with a typed, friendlier surface. The raw REST endpoints are documented under Endpoints for everything else.

Base URL

The API is built on REST, returns JSON, and is served over HTTPS only. Unencrypted HTTP is not supported. All endpoints live under:

Base URL

https://api.revinel.com/v1

Authentication

The on-site surface needs none. Ad serving and event tracking are designed to run in the browser on your own site, so there is no secret to protect. Instead, every request is scoped by your workspace ID in the path, for example GET /v1/workspaces/{id}/ads/serving. Find your workspace ID on the dashboard Install page or under Settings → General. It is safe to ship in client-side code. Managing your workspace (approving ads, editing tiers and fields, and more) is a separate, authenticated surface. Those endpoints require an API key.

curl https://api.revinel.com/v1/workspaces/your-workspace-id/ads/serving

import { createRevinelClient } from "@revinel/sdk"

const revinel = createRevinelClient({ workspaceId: "your-workspace-id" })
const ad = await revinel.getAd()

Managing tiers, fields, and ad approvals also happens in the Revinel dashboard under your login. To automate it instead, use the management endpoints (the Beta-tagged routes in the reference) with an API key. The management API is in beta: its shapes may change before they are marked stable. The on-site surface (serving, tracking, checkout) is stable.

SDKs

Reach for an SDK before the raw endpoints:

@revinel/sdk: universal headless client (any JS runtime)
@revinel/react: React provider, hooks, and tracking
@revinel/browser: the embeddable tier selector
@revinel/embeds: the shared embed protocol

Response shapes

Successful responses follow one of three shapes, by endpoint kind:

Serving reads wrap the collection under its resource name, leaving room for serving metadata: GET /ads/serving returns { "ads": [...] } and GET /tiers/serving returns { "tiers": [...] }.
Paginated lists return a page envelope: { "items": [...], "total", "page", "perPage", "pageCount" }.
Single-resource reads and writes return the object itself, unwrapped.

Error handling

Errors come back as JSON with a machine-readable code, the HTTP status, and a human-readable message:

{
  "defined": false,
  "code": "NOT_FOUND",
  "status": 404,
  "message": "Workspace not found."
}

Validation failures add a data object mapping the bad fields:

{
  "defined": true,
  "code": "INPUT_VALIDATION_FAILED",
  "status": 422,
  "message": "Expected number <= 20, received 25",
  "data": {
    "formErrors": [],
    "fieldErrors": { "count": ["Expected number <= 20, received 25"] }
  }
}

The codes a public caller can hit:

NOT_FOUND

Status: 404
Problem: The workspace, tier price, or ad in the request does not exist.
Solution: Check the workspace ID and any resource IDs in the path or body.

PRECONDITION_FAILED

Status: 412
Problem: Checkout was called before the publisher finished connecting Stripe.
Solution: The publisher needs to finish Stripe setup (see Connect Stripe) before advertisers can pay.

INPUT_VALIDATION_FAILED

Status: 422
Problem: A query or body parameter failed validation.
Solution: Read data.fieldErrors to see which field was rejected and why.

TOO_MANY_REQUESTS

Status: 429
Problem: You exceeded the checkout rate limit.
Solution: Wait for the window to reset and retry.

Revinel API

Guides

SDKs

API endpoints

Base URL

Authentication

SDKs

Response shapes

Error handling

​Base URL

​Authentication

​SDKs

​Response shapes

​Error handling

Base URL

Authentication

SDKs

Response shapes

Error handling