REST API

A versioned JSON API at https://api.roi.me/v1 with scoped keys, cursor pagination, idempotent writes and an OpenAPI specification.

In development

The ROI.me API is in development. Resource names and shapes below reflect the v1 design and may change before general availability.

Authentication

Create API keys under Developers → API keys in the portal. Keys are scoped, shown once at creation and stored only as a hash. Send them as a bearer token.

bash

curl https://api.roi.me/v1/campaigns \
  -H "Authorization: Bearer roi_live_…"

Scopes

A key can only do what its scopes allow, and never more than the organization role of the person who created it.

Scope	Allows
brands:read	Read brands, products and Brand Brain
brands:write	Create and edit brands and products
creative:read	Read creative, assets and scores
creative:write	Generate, edit and score creative
campaigns:read	Read campaigns and their channel structures
campaigns:write	Create and edit draft campaigns
campaigns:launch	Request launches and spend changes (approval policy still applies)
analytics:read	Read performance and conversions
audiences:read	Read audiences and sync history
audiences:write	Create, edit and sync audiences
visitors:read	Read visitors, identity and intent
events:write	Send server-side events and offline conversions
agents:read	Read agent runs and recommendations
agents:execute	Start agent runs

Conventions

Pagination: list endpoints return data and next_cursor; pass ?cursor= to continue.
Idempotency: send an Idempotency-Key header on POST requests. Retries with the same key return the original result.
Request IDs: every response carries x-request-id. Include it when contacting support.
Rate limits: per key, reported in ratelimit-* headers, with 429 and retry-after when exceeded.

Error response

HTTP/1.1 403 Forbidden
x-request-id: req_2Hq9…

{
  "error": {
    "type": "approval_required",
    "message": "Launching this campaign requires approval under your organization's policy.",
    "approval_id": "apv_7Kc1…"
  }
}

Resources

Brands

brands:read · brands:write

A brand and its Brand Brain: identity, voice, products, claims and restrictions.

GET/v1/brandsList brands
POST/v1/brandsCreate a brand from a domain
GET/v1/brands/{id}Retrieve a brand
POST/v1/brands/{id}/analyzeStart a Brand Brain analysis

Products

brands:read · brands:write

Products and services belonging to a brand, from your catalog or Brand Brain.

GET/v1/productsList products
POST/v1/productsCreate a product

Visitors

visitors:read

First-party visitors with identity state, intent score and funnel stage.

GET/v1/visitorsList visitors, filterable by intent and stage
GET/v1/visitors/{id}Retrieve a visitor with timeline

Events

events:write

Server-side events for conversions and product usage the pixel can't see.

POST/v1/eventsSend one or more events

Audiences

audiences:read · audiences:write

Rule-based audiences and their destinations on connected ad networks.

GET/v1/audiencesList audiences
POST/v1/audiencesCreate an audience
POST/v1/audiences/{id}/syncSync to destinations

Creative

creative:read · creative:write

Creative projects, concepts, variants, assets and quality scores.

GET/v1/creativeList creative
POST/v1/creative/generationsQueue a generation job
POST/v1/creative/{id}/scoreScore a creative

Campaigns

campaigns:read · campaigns:write · campaigns:launch

Cross-channel campaigns and their per-network structures.

GET/v1/campaignsList campaigns
POST/v1/campaignsCreate a draft campaign
POST/v1/campaigns/{id}/launchRequest launch (subject to approval policy)
POST/v1/campaigns/{id}/pausePause a campaign

Conversions

analytics:read · events:write

Conversion definitions and recorded conversions from pixel, CRM and networks.

GET/v1/conversionsList conversions
POST/v1/conversionsRecord an offline conversion

Analytics

analytics:read

Spend, conversions, CPA, revenue and ROAS by channel, campaign, audience and creative.

GET/v1/analytics/performanceQuery performance metrics

Agents

agents:read · agents:execute

ROI Agent runs, recommendations and proposed actions.

POST/v1/agents/runsAsk a question or request analysis
GET/v1/agents/runs/{id}Retrieve a run with its tool calls

Example: create an audience

curl https://api.roi.me/v1/audiences \
  -H "Authorization: Bearer $ROI_API_KEY" \
  -H "Idempotency-Key: 9f2c6d1e-…" \
  -H "Content-Type: application/json" \
  -d '{
    "brand": "brd_8fK2…",
    "name": "High intent, no demo",
    "rules": {
      "all": [
        { "intent_score": { "gte": 70 } },
        { "page_viewed": { "path": "/pricing", "count_gte": 2 } },
        { "not": { "conversion": "demo_booked" } }
      ]
    }
  }'