# API & MCP

> **Title:** API & MCP — Rival Ads Docs
> **Description:** Connect scripts, internal tools and AI clients to Rival Ads with workspace-scoped API keys or OAuth.
> **Canonical URL:** https://www.rivalads.io/docs/developer-api
> **Note:** This is the markdown twin of https://www.rivalads.io/docs/developer-api. Append `.md` to any Rival Ads page URL to get markdown.

---

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:

```bash
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:

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

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

## Connect an AI client with OAuth

Give a compatible MCP client only this server URL:

```text
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:

```json
{
  "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

- Read the public [API overview](/api).
- Open the [API reference](/api/docs).
- Follow the [MCP setup page](/mcp).
- Contact [support](/contact) when a client needs a capability that is not yet exposed.