API Reference

REST API endpoints for the Revme ad platform.

Base URL: https://revme.io/api/v1

Authentication: Authenticated endpoints require a JWT token via the Authorization: Bearer <token> header.

Ad Serving

Public endpoints for fetching and tracking ads. No auth required.

GET /ads

Fetch a text ad filtered by geo, scoped to the API key's owner.

Parameters:
NameTypeRequiredDescription
keystringYesAPI key identifying the publisher
langstringNoBrowser language (e.g. "en-US")
tzstringNoTimezone (e.g. "America/New_York")
Response:
{ "ad": { "text": "Build faster with Cursor AI", "url": "https://cursor.sh", "sponsor": "Cursor", "adId": "ad_abc123" }, "nextPollMs": 300000 }
POST /ads/:adId/impression

Record an impression event for an ad.

Request Body:
{ "lang": "en-US", "tz": "America/New_York" }
Response:
{ "ok": true }
POST /ads/:adId/click

Record a click event for an ad.

Request Body:
{ "lang": "en-US", "tz": "America/New_York" }
Response:
{ "ok": true }

Ads Management

CRUD operations for your text ads. Requires authentication.

GET /my/ads

List all ads owned by the authenticated user.

Response:
{ "ads": [{ "id": "ad_abc123", "text": "Build faster with Cursor AI", "url": "https://cursor.sh", "sponsor": "Cursor", "target_languages": ["en"], "target_timezones": [], "weight": 1.0, "active": true, "created_at": "2026-01-15T10:00:00Z" }] }
POST /my/ads

Create a new text ad.

Request Body:
{ "text": "Build faster with Cursor AI", "url": "https://cursor.sh", "sponsor": "Cursor", "target_languages": ["en"], "target_timezones": ["America/New_York"], "weight": 1.0, "active": true }
Response:
{ "ad": { "id": "ad_xyz", "text": "..." } }
PUT /my/ads/:id

Update an existing ad. Only include fields you want to change.

Request Body:
{ "text": "Updated ad text", "active": false }
Response:
{ "ad": { "id": "ad_abc123", "text": "Updated ad text", "active": false } }
DELETE /my/ads/:id

Delete an ad permanently.

Response:
{ "ok": true }

Analytics

View impressions, clicks, and trends for your ads.

GET /my/stats

Aggregated stats across all ads.

Response:
{ "total_impressions": 1250, "total_clicks": 89, "click_rate": 0.0712 }
GET /my/stats/daily

Daily breakdown of impressions and clicks.

Parameters:
NameTypeRequiredDescription
daysnumberNoNumber of days to look back (default: 7, max: 30)
Response:
{ "daily": [{ "date": "2026-01-15", "impressions": 180, "clicks": 12 }] }
GET /my/stats/daily-by-ad

Per-ad daily stats.

Parameters:
NameTypeRequiredDescription
daysnumberNoNumber of days (default: 30, max: 365)
GET /my/stats/by-ad

Aggregated stats broken down by individual ad.

API Keys

Manage API keys used by the SDK to fetch ads.

GET /my/keys

List all API keys.

Response:
{ "keys": [{ "id": "key_abc", "name": "Production", "key": "ad_live_...", "created_at": "2026-01-10T08:00:00Z" }] }
POST /my/keys

Create a new API key.

Request Body:
{ "name": "Production" }
Response:
{ "key": { "id": "key_xyz", "name": "Production", "key": "ad_live_..." } }
DELETE /my/keys/:id

Revoke and delete an API key.

Response:
{ "ok": true }