<!-- The markdown copy of https://oppalerts.com/docs/api . All pages: https://oppalerts.com/docs/llms.txt -->

[Documentation](https://oppalerts.com/docs/) / [API](https://oppalerts.com/docs/api/) / Authentication and Limits

# Authentication and Limits

`POST https://api.oppalerts.com/v1/{group}/{endpoint}`

The base URL, tokens, daily limits, and errors for the OppAlerts API.

## Base URL and routes

The API is at `https://api.oppalerts.com/v1/`. Each tool responds on two routes. Both return the same response.

- `POST /v1/{group}/{endpoint}`, for example `POST /v1/news/brand_links`.
- `POST /v1/{tool}`, for example `POST /v1/news_brand_links`.
- `GET /v1/tools` lists the tools.
- `GET /v1/health` reports whether the API is up.

The request body is JSON. Each tool’s API page lists its parameters.

## Authentication

Send a token in the `Authorization` header:

```http
POST /v1/account/calls_left HTTP/1.1
Host: api.oppalerts.com
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json

{}
```

- Create a personal token at [oppalerts.com/app/account/api_tokens](https://oppalerts.com/app/account/api_tokens). It starts with `pat_live_`. You choose whether it expires after 30, 90, or 365 days, or never. The default is 90 days.
- The API needs the scope `api:read`. A route that changes a campaign also needs `api:write`. See [Authentication](https://oppalerts.com/docs/getting-started/authentication#scopes).
- An OAuth access token also works. OAuth 2.0 with PKCE is at `https://auth.oppalerts.com`. [Authentication](https://oppalerts.com/docs/getting-started/authentication) has the details.

## Rules for every call

- **Authentication.** Every call needs a token in the `Authorization: Bearer` header: a personal token or an OAuth access token. The API needs the scope `api:read`. A tool that changes data also needs `api:write`. A missing or invalid token returns HTTP 401 `unauthorized`. See [Authentication](https://oppalerts.com/docs/getting-started/authentication).
- **Daily limits.** The 14 `news_` and `prospects_` tools are index searches. All index searches for an account share one daily count. Every other tool has a daily count of its own. Team members use the account’s counts. The counts reset every day at 04:00 New York time. [`account_calls_left`](https://oppalerts.com/docs/api/account_calls_left) shows the calls left today. A call over a count is refused with `daily_limit` (HTTP 429).
- **What counts.** Each tool call through the API or MCP uses one call from its daily count. A refused call with an HTTP status from 400 to 499 uses no daily call. Two responses are not refusals and use one call: a search stopped by the index (HTTP 422), and a server error (HTTP 500 to 599). The MCP messages `initialize`, `tools/list`, and `ping` are not tool calls and use no daily call. Calls from web app pages use the same counts, except when one of these 12 tools reads data from your own account: `campaigns_list`, `campaigns_settings`, `campaigns_organizations`, `campaigns_saved_opportunities`, `campaigns_dashboard`, `account_usage`, `account_team_members`, `account_calls_left`, `llm_answers_content_phrases`, `llm_answers_search_keywords`, `llm_answers_top_sites`, and `taxonomy_taxonomies`.
- **One search at a time.** Only one index search runs at a time for each account. A call to a `news_` or `prospects_` tool made while another index search runs is refused with `one_at_a_time` (HTTP 429) and uses no daily call. Wait a few seconds and send it again.
- **One change at a time.** Only one change runs at a time for each account. A call to one of the 16 tools that change data, made while another change is running for the account, is refused with `one_at_a_time` (HTTP 429) and uses no daily call. Send it again after a few seconds. The 16 tools: `campaigns_create`, `campaigns_update`, `campaigns_finalize`, `campaigns_archive`, `campaigns_activate`, `campaigns_rerun_research`, `campaigns_rebuild_counts`, `campaigns_set_taxonomy_presets`, `campaigns_set_daily_opportunities_email`, `campaigns_organization_add`, `campaigns_organization_update`, `campaigns_organization_delete`, `campaigns_saved_opportunity_add`, `campaigns_saved_opportunity_update`, `campaigns_saved_opportunity_archive`, and `campaigns_saved_opportunity_activate`.
- **Request log.** Each tool call with a valid token is written to the account’s request log: the time, the source, the token, the tool, the HTTP status, and whether it used a daily call. Refused calls are also logged. The MCP messages `initialize`, `tools/list`, and `ping` are in the log with `counted` false. A call of `account_calls_left` through the API or MCP is never logged. [`account_usage`](https://oppalerts.com/docs/api/account_usage) and the Usage page of the web app show the log for the last 14 days.

## Limits

- Index searches per day, shared by the 14 `news_` and `prospects_` tools: OppAlerts 250, 300. OppAlerts 500, 1,000. OppAlerts 1000, 3,000. The free account, 10.
- Each other tool, per day: OppAlerts 250, 300. OppAlerts 500, 1,000. OppAlerts 1000, 3,000. The free account, 10. [`POST /v1/account/calls_left`](https://oppalerts.com/docs/api/account_calls_left) has more: OppAlerts 250, 3,000. OppAlerts 500, 10,000. OppAlerts 1000, 30,000. The free account, 100.
- The counts reset every day at 04:00 New York time. `resets_at` in the response from [`POST /v1/account/calls_left`](https://oppalerts.com/docs/api/account_calls_left) gives the time in UTC.
- A `results_limit` above your plan’s maximum is refused, and the error gives that maximum. On the free account the maximum of an index search is 100. When you do not send `results_limit`, the answer has at most 100 rows.
- A request body is at most 1 MB (1,048,576 bytes). A larger body is refused with HTTP 413 `request_body_too_large`.

## Errors

An error response has this body and the HTTP status of the error:

```json
{"error": "no_campaign", "error_description": "That campaign is not in this account."}
```

- `bad_param` (HTTP 400): a parameter is missing or out of range, a field is not accepted by the tool, or an optional field is sent with empty text, an empty list, or an empty object. The error names the field. A tool that needs a campaign returns this error when the call has none.
- `unauthorized` (HTTP 401): the token is missing or invalid.
- `forbidden` (HTTP 403): the token or the account has no API permissions, or a tool that changes a campaign is called with a token that does not have the scope `api:write`. When a scope is missing, the response also has a `WWW-Authenticate` header with `error="insufficient_scope"` and the scopes that the call needs.
- `no_campaign` (HTTP 404): the campaign is not in this account.
- `daily_limit` (HTTP 429): the daily count of this tool is used up.
- `one_at_a_time` (HTTP 429): another index search of the account is running, or, for a tool that changes data, another change of the account is running. Wait a few seconds and send the call again.
- `backend_error` (HTTP 502): a data server did not answer, or its answer could not be read. Send the call again later.
- `db_error` (HTTP 500): the data could not be read or saved. The sentence says which data.

## All tools

The server has 50 tools, in 10 groups. Each tool has an MCP page and an API page.

### Account (3)

- [`POST /v1/account/calls_left`](https://oppalerts.com/docs/api/account_calls_left) (`account_calls_left`): Calls Left Today
- [`POST /v1/account/team_members`](https://oppalerts.com/docs/api/account_team_members) (`account_team_members`): Team Members
- [`POST /v1/account/usage`](https://oppalerts.com/docs/api/account_usage) (`account_usage`): Account Usage

### Backlinks (2)

- [`POST /v1/backlinks`](https://oppalerts.com/docs/api/backlinks) (`backlinks`): Backlinks of One or More Sites
- [`POST /v1/backlinks/link_gap`](https://oppalerts.com/docs/api/backlinks_link_gap) (`backlinks_link_gap`): Backlink Gap

### Campaigns (21)

- [`POST /v1/campaigns/activate`](https://oppalerts.com/docs/api/campaigns_activate) (`campaigns_activate`): Activate a Campaign
- [`POST /v1/campaigns/archive`](https://oppalerts.com/docs/api/campaigns_archive) (`campaigns_archive`): Archive a Campaign
- [`POST /v1/campaigns/create`](https://oppalerts.com/docs/api/campaigns_create) (`campaigns_create`): Create a Campaign
- [`POST /v1/campaigns/dashboard`](https://oppalerts.com/docs/api/campaigns_dashboard) (`campaigns_dashboard`): Campaign Dashboard
- [`POST /v1/campaigns/finalize`](https://oppalerts.com/docs/api/campaigns_finalize) (`campaigns_finalize`): Finalize a Campaign
- [`POST /v1/campaigns/list`](https://oppalerts.com/docs/api/campaigns_list) (`campaigns_list`): Campaign List
- [`POST /v1/campaigns/organization_add`](https://oppalerts.com/docs/api/campaigns_organization_add) (`campaigns_organization_add`): Add an Organization
- [`POST /v1/campaigns/organization_delete`](https://oppalerts.com/docs/api/campaigns_organization_delete) (`campaigns_organization_delete`): Delete an Organization
- [`POST /v1/campaigns/organization_update`](https://oppalerts.com/docs/api/campaigns_organization_update) (`campaigns_organization_update`): Update an Organization
- [`POST /v1/campaigns/organizations`](https://oppalerts.com/docs/api/campaigns_organizations) (`campaigns_organizations`): Campaign Organizations
- [`POST /v1/campaigns/rebuild_counts`](https://oppalerts.com/docs/api/campaigns_rebuild_counts) (`campaigns_rebuild_counts`): Rebuild the Daily Counts
- [`POST /v1/campaigns/rerun_research`](https://oppalerts.com/docs/api/campaigns_rerun_research) (`campaigns_rerun_research`): Run Stopped Research Again
- [`POST /v1/campaigns/saved_opportunities`](https://oppalerts.com/docs/api/campaigns_saved_opportunities) (`campaigns_saved_opportunities`): Saved Opportunities
- [`POST /v1/campaigns/saved_opportunity_activate`](https://oppalerts.com/docs/api/campaigns_saved_opportunity_activate) (`campaigns_saved_opportunity_activate`): Activate a Saved Opportunity
- [`POST /v1/campaigns/saved_opportunity_add`](https://oppalerts.com/docs/api/campaigns_saved_opportunity_add) (`campaigns_saved_opportunity_add`): Add a Saved Opportunity
- [`POST /v1/campaigns/saved_opportunity_archive`](https://oppalerts.com/docs/api/campaigns_saved_opportunity_archive) (`campaigns_saved_opportunity_archive`): Archive a Saved Opportunity
- [`POST /v1/campaigns/saved_opportunity_update`](https://oppalerts.com/docs/api/campaigns_saved_opportunity_update) (`campaigns_saved_opportunity_update`): Update a Saved Opportunity
- [`POST /v1/campaigns/set_daily_opportunities_email`](https://oppalerts.com/docs/api/campaigns_set_daily_opportunities_email) (`campaigns_set_daily_opportunities_email`): Set the Daily Opportunities Email
- [`POST /v1/campaigns/set_taxonomy_presets`](https://oppalerts.com/docs/api/campaigns_set_taxonomy_presets) (`campaigns_set_taxonomy_presets`): Set Taxonomy Presets
- [`POST /v1/campaigns/settings`](https://oppalerts.com/docs/api/campaigns_settings) (`campaigns_settings`): Campaign Settings
- [`POST /v1/campaigns/update`](https://oppalerts.com/docs/api/campaigns_update) (`campaigns_update`): Update a Campaign

### Link Graph (1)

- [`POST /v1/linkgraph/history`](https://oppalerts.com/docs/api/linkgraph_history) (`linkgraph_history`): PageRank History

### LLM Answers (3)

- [`POST /v1/llm_answers/content_phrases`](https://oppalerts.com/docs/api/llm_answers_content_phrases) (`llm_answers_content_phrases`): AI Content Phrases
- [`POST /v1/llm_answers/search_keywords`](https://oppalerts.com/docs/api/llm_answers_search_keywords) (`llm_answers_search_keywords`): AI Search Keywords
- [`POST /v1/llm_answers/top_sites`](https://oppalerts.com/docs/api/llm_answers_top_sites) (`llm_answers_top_sites`): Top Sites Named by AI

### News Index (7)

- [`POST /v1/news/brand_link_gap`](https://oppalerts.com/docs/api/news_brand_link_gap) (`news_brand_link_gap`): News Link Gap
- [`POST /v1/news/brand_links`](https://oppalerts.com/docs/api/news_brand_links) (`news_brand_links`): News Pages Linking to Brands
- [`POST /v1/news/brand_mentions`](https://oppalerts.com/docs/api/news_brand_mentions) (`news_brand_mentions`): News Brand Mentions
- [`POST /v1/news/opportunities`](https://oppalerts.com/docs/api/news_opportunities) (`news_opportunities`): News Opportunities
- [`POST /v1/news/search`](https://oppalerts.com/docs/api/news_search) (`news_search`): News Search
- [`POST /v1/news/similar_to_id`](https://oppalerts.com/docs/api/news_similar_to_id) (`news_similar_to_id`): Similar News Pages
- [`POST /v1/news/unlinked_brand_mentions`](https://oppalerts.com/docs/api/news_unlinked_brand_mentions) (`news_unlinked_brand_mentions`): News Unlinked Brand Mentions

### Prospect Index (7)

- [`POST /v1/prospects/brand_link_gap`](https://oppalerts.com/docs/api/prospects_brand_link_gap) (`prospects_brand_link_gap`): Prospect Link Gap
- [`POST /v1/prospects/brand_links`](https://oppalerts.com/docs/api/prospects_brand_links) (`prospects_brand_links`): Prospect Pages Linking to Brands
- [`POST /v1/prospects/brand_mentions`](https://oppalerts.com/docs/api/prospects_brand_mentions) (`prospects_brand_mentions`): Prospect Brand Mentions
- [`POST /v1/prospects/opportunities`](https://oppalerts.com/docs/api/prospects_opportunities) (`prospects_opportunities`): Prospect Opportunities
- [`POST /v1/prospects/search`](https://oppalerts.com/docs/api/prospects_search) (`prospects_search`): Prospect Search
- [`POST /v1/prospects/similar_to_id`](https://oppalerts.com/docs/api/prospects_similar_to_id) (`prospects_similar_to_id`): Similar Prospect Pages
- [`POST /v1/prospects/unlinked_brand_mentions`](https://oppalerts.com/docs/api/prospects_unlinked_brand_mentions) (`prospects_unlinked_brand_mentions`): Prospect Unlinked Brand Mentions

### Site Info (1)

- [`POST /v1/siteinfo/site`](https://oppalerts.com/docs/api/siteinfo_site) (`siteinfo_site`): Site Contact Details

### Taxonomies (3)

- [`POST /v1/taxonomy/categories`](https://oppalerts.com/docs/api/taxonomy_categories) (`taxonomy_categories`): Taxonomy Categories
- [`POST /v1/taxonomy/semantic_content_analyzer`](https://oppalerts.com/docs/api/taxonomy_semantic_content_analyzer) (`taxonomy_semantic_content_analyzer`): Semantic Content Analyzer
- [`POST /v1/taxonomy/taxonomies`](https://oppalerts.com/docs/api/taxonomy_taxonomies) (`taxonomy_taxonomies`): Available Taxonomies

### Types (2)

- [`POST /v1/types/content_types`](https://oppalerts.com/docs/api/types_content_types) (`types_content_types`): Content Types
- [`POST /v1/types/opportunity_types`](https://oppalerts.com/docs/api/types_opportunity_types) (`types_opportunity_types`): Opportunity Types

## Related pages

- [Connect an AI Agent (MCP)](https://oppalerts.com/docs/mcp/)
- [Authentication](https://oppalerts.com/docs/getting-started/authentication)
- [Every tool, on the documentation home page](https://oppalerts.com/docs/#mcp-and-api)
