Skip to content

Developers

The ROAS Shield REST API

A stable, read-only API over your comments and leads. Pull ROAS Shield data into your own dashboards, BI tools, or client reporting — with scoped, per-workspace keys.

Base URL

https://roasshield.com/api/v1

Auth

Authorization: Bearer rsk_…

Format

JSON · cursor pagination

Rate limit

300 requests / min per key

Authentication

Create a key in your workspace under Settings → API keys (owner or admin only). The full key is shown once at creation and never again — store it somewhere safe. Each key looks like rsk_… and resolves to exactly one workspace, so a key can never read another workspace’s data. Revoke a key any time from the same screen.

Send it as a bearer token on every request:

Authorization: Bearer rsk_…

Quickstart

# 1. Verify your key resolves to the right workspace
curl https://roasshield.com/api/v1/workspace \
  -H "Authorization: Bearer rsk_…"

# 2. List comments (needs the comments:read scope)
curl "https://roasshield.com/api/v1/comments?limit=50&platform=instagram" \
  -H "Authorization: Bearer rsk_…"

# 3. Page with the cursor from the previous response
curl "https://roasshield.com/api/v1/comments?cursor=cmt_0Jq…" \
  -H "Authorization: Bearer rsk_…"

# 4. List new buyer-intent leads (needs the leads:read scope)
curl "https://roasshield.com/api/v1/leads?status=new" \
  -H "Authorization: Bearer rsk_…"

Responses are JSON shaped { "data": [ … ], "nextCursor": "…" }. When nextCursor is non-null, pass it back as cursor to fetch the next page.

Endpoints

Read-only, scoped access

Every key carries an explicit set of scopes — pick only what an integration needs. The current surface is read-only: comments:read and leads:read.

GET/api/v1/workspacescope: any valid key

Identity endpoint — echoes the workspace the key resolves to and the scopes it carries. Use it to test a key.

GET/api/v1/commentsscope: comments:read

List the workspace’s comments, newest first, with ad context (campaign, ad set, ad), moderation state and classification.

query: limit (1–100, default 50) · cursor · status · platform (facebook | instagram)

GET/api/v1/leadsscope: leads:read

List buyer-intent leads with a snapshot of the source comment, status, and — for won leads — the logged deal value.

query: limit (1–100, default 50) · cursor · status (new | contacted | won | lost | archived)

Errors

Predictable status codes

Errors return a JSON body { "error": "…", "message": "…" } with one of these statuses:

  • 401 unauthorized

    Missing, malformed, invalid, or revoked key.

  • 403 forbidden

    The key is valid but missing the scope the endpoint requires.

  • 429 rate_limited

    Over 300 requests/min — a Retry-After header tells you when to retry.

  • 400 invalid_query

    A query parameter failed validation.

The API never returns raw Meta access tokens or raw platform user IDs — tokens stay encrypted server-side and never reach any client.

Build on your ad-comment data

Start a 7-day trial, connect your Page, and generate a key in Settings → API keys. No card required.

Start 7-day free trialSee pricing