Rival Ads

API & MCP

Rival Ads exposes the same competitor-monitoring capabilities through a versioned REST API and a remote MCP server. Both are thin interfaces over the dashboard’s domain services, so plan limits, source validation, tenant isolation and report rules stay identical everywhere.

Choose a connection

  • Use the REST API for scripts, data pipelines, dashboards and backend integrations. It accepts workspace-scoped API keys.
  • Use MCP with OAuth 2.1 and PKCE for interactive AI clients. The client opens Rival Ads, the user signs in, reviews the requested read or write permissions and approves the connection.
  • Use MCP with an API key for headless agents, CI and server-to-server automations that cannot complete an interactive sign-in.

The production REST base URL is https://www.rivalads.io/api/v1. The remote MCP endpoint is https://www.rivalads.io/api/mcp.

Create an API key

Only the workspace owner can manage developer credentials.

  1. Open Settings → Developer.
  2. Enter a descriptive name such as Weekly client report.
  3. Choose Read only or Read and write.
  4. Choose an expiry and select Create API key.
  5. Copy the ra_live_… value immediately. Rival Ads stores only a hash and cannot show it again.

Send the key as a Bearer token:

curl https://www.rivalads.io/api/v1/monitors \
  -H "Authorization: Bearer ra_live_your_key"

The x-api-key header is also accepted. Prefer Authorization: Bearer because it works for both REST and MCP. Never put a key in a URL, browser bundle or repository. Revoke a leaked or unused key from Settings → Developer.

REST API resources

The API covers the workspace, monitors, projects, ad movement, stored strategy reads, sync jobs, swipe-file folders and ads, and public report links.

  • GET /workspace
  • GET|POST /monitors
  • GET|PATCH|DELETE /monitors/{monitorId}
  • GET /monitors/{monitorId}/ads
  • GET /monitors/{monitorId}/analyses
  • POST|GET /monitors/{monitorId}/sync
  • GET|POST /projects
  • GET|PATCH|DELETE /projects/{projectId}
  • GET|POST /library/folders
  • PATCH|DELETE /library/folders/{folderId}
  • GET /library/ads
  • PUT|DELETE /library/ads/{adId}
  • GET|PATCH /monitors/{monitorId}/report-share

List endpoints use cursor pagination. Pass limit from 1 to 100 and then send the returned pagination.nextCursor as cursor.

Every success response wraps the result in data. Errors use a stable shape:

{
  "error": {
    "code": "not_found",
    "message": "Monitor not found"
  }
}

The interactive, branded API reference is generated from the same Zod request contracts the routes validate. The raw OpenAPI 3.1 document is at /api/openapi.json.

Connect an AI client with OAuth

Give a compatible MCP client only this server URL:

https://www.rivalads.io/api/mcp

The client discovers Rival Ads’ OAuth metadata, registers itself, uses an authorization code with PKCE and opens the consent screen. The available scopes are:

  • mcp:read — list workspaces and read monitors, projects, ad movement, analyses, library items, report-link state and sync state.
  • mcp:write — create, update or delete monitors, projects and library folders; save ads; request syncs; update report links.

OAuth connections are approved by a workspace owner and can access workspaces that person owns. If that account owns more than one workspace, tools require organizationId; call list_workspaces first. Revoke a client from Settings → Developer → OAuth connections.

Connect a headless MCP client

For a server or CI job, configure the same MCP URL with a Bearer API key:

{
  "mcpServers": {
    "rival-ads": {
      "url": "https://www.rivalads.io/api/mcp",
      "headers": {
        "Authorization": "Bearer ra_live_your_key"
      }
    }
  }
}

An API key is fixed to the workspace where it was created. A read-only key cannot call write tools. Use a short expiry and the narrowest access that works.

MCP tool groups

The server exposes small, task-oriented tools for:

  • listing available workspaces;
  • listing, reading, creating, editing and deleting monitors;
  • listing, creating, editing and deleting projects;
  • reading started, stopped and continuing ads;
  • reading stored strategy analyses without triggering a new model run;
  • listing and managing swipe-file folders and saved ads;
  • requesting and polling monitor sync jobs;
  • reading and updating revocable public report links.

Tool responses include structured JSON, and destructive tools are marked as destructive in their MCP annotations.

Security and tenant boundaries

API keys are attached to exactly one workspace. OAuth requests re-check the signed-in user’s current owner memberships. Every resource lookup also filters by that resolved workspace, so knowing another tenant’s ID does not grant access. Keys and OAuth connections have independent read/write permissions, expiry and revocation.

REST keys are limited to 120 requests per minute per credential. A 429 response means the key has exceeded that window. Sync requests enqueue work and return a job ID; poll the corresponding sync endpoint or MCP tool rather than holding the request open.

Next steps