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

[Documentation](https://oppalerts.com/docs/) / [MCP](https://oppalerts.com/docs/mcp/) / campaigns_saved_opportunity_archive

# campaigns_saved_opportunity_archive

`POST https://mcp.oppalerts.com/mcp tool: campaigns_saved_opportunity_archive`

Archives one saved opportunity of a campaign.

## What it does

The tool archives one saved opportunity of a campaign. An archived saved opportunity is not counted and is not in the daily opportunities email. It keeps its stored counts.

A saved opportunity is never deleted. [campaigns_saved_opportunity_activate](https://oppalerts.com/docs/mcp/campaigns_saved_opportunity_activate) makes it active again.

The response contains the saved opportunity after the change, with `state` `archived`. In the web app, Archive on the Opportunities tab of Edit Campaign makes the same change.

## Who May Call It

- The account owner, an account editor, or a campaign editor of this campaign. An account viewer or a campaign viewer gets the error `no_access`.
- The token or the connection needs the scope `api:write`, and `mcp:use` as every MCP tool does. Without `api:write`, the call gets the error `forbidden`. [Authentication](https://oppalerts.com/docs/getting-started/authentication#scopes) says which tokens and apps have it.
- The tool tells the MCP client that it changes data, so a client such as Claude asks you before the call.

## Connect

```bash
claude mcp add --transport http oppalerts https://mcp.oppalerts.com/mcp
```

The first call opens a browser window for the OppAlerts login. Allow changes there. [Connect an AI Agent](https://oppalerts.com/docs/mcp/) has the details.

## Parameters

**`campaign`int, required, 1 to 4294967295**

The campaign id, from [campaigns_list](https://oppalerts.com/docs/mcp/campaigns_list). It must be a campaign of your account.

**`opportunity`int, required, 1 to 4294967295**

Required. The saved opportunity id, from [campaigns_saved_opportunities](https://oppalerts.com/docs/mcp/campaigns_saved_opportunities).

## Rules

- `opportunity` is required. [campaigns_saved_opportunities](https://oppalerts.com/docs/mcp/campaigns_saved_opportunities) gives the id.

## Strict Rules

- A field that is not in the list above is refused. The result then has `isError` true, and its text starts with `bad_param`. The error names the field: "<field> is not a field of this tool."
- A bad value is refused, and the error names the field. A bad value is a value of the wrong type, a number with a fraction for a whole-number field, a value out of its range, a value that is not in its list, or an empty text, list, or object. A required field that you do not send is refused too. To send no value for an optional field, leave the field out. No field has a default value, and the tool never changes a value that you send.
- An error about the format of a call, such as a refused field, names the field. Its message ends with one sentence: "Read the documentation at https://oppalerts.com/docs for the correct format." Every other error, such as `forbidden` below, has only its own sentence.

## Response fields

The response contains the saved opportunity, in the same format that [campaigns_saved_opportunities](https://oppalerts.com/docs/mcp/campaigns_saved_opportunities) returns for each saved opportunity.

**`opportunity.id`int**

The id of the saved opportunity. [news_opportunities](https://oppalerts.com/docs/mcp/news_opportunities) and [prospects_opportunities](https://oppalerts.com/docs/mcp/prospects_opportunities) take it as `opportunity`.

**`opportunity.label`string**

The name of the saved opportunity.

**`opportunity.state`string**

The state of the saved opportunity. The example shows `archived`.

**`opportunity.search`string**

What the saved opportunity finds: `no_type`, `opportunity_type`, `content_type`, or one of the 6 brand searches `brand_links`, `brand_mentions`, `unlinked_brand_mentions`, `brand_link_gap`, `competitor_links`, and `competitor_mentions`.

**`opportunity.opportunity_type`string**

The opportunity type as `<group>/<type>`, for `search` `opportunity_type`. Empty for another search.

**`opportunity.content_type`string**

The content type, for `search` `content_type`. Empty for another search.

**`opportunity.filters`object**

The numeric fields of the saved opportunity. A number that is not set is not in `filters`.

**`opportunity.filters.type_score_min`int, optional**

The minimum type score, 0 to 100.

**`opportunity.filters.similarity_score_min`int, optional**

The minimum similarity in percent, 1 to 100.

**`opportunity.filters.pr_domain_min`int, optional**

The minimum domain PageRank, 0 to 100.

**`opportunity.filters.pr_domain_max`int, optional**

The maximum domain PageRank, 0 to 100.

**`opportunity.filters.pr_host_min`int, optional**

The minimum host PageRank, 0 to 100.

**`opportunity.filters.pr_host_max`int, optional**

The maximum host PageRank, 0 to 100.

**`opportunity.filters.prot_domain_min`int, optional**

The minimum domain PRoT (PageRank over Time), 0 to 1000000.

**`opportunity.filters.prot_domain_max`int, optional**

The maximum domain PRoT, 0 to 1000000.

**`opportunity.filters.prot_host_min`int, optional**

The minimum host PRoT, 0 to 1000000.

**`opportunity.filters.prot_host_max`int, optional**

The maximum host PRoT, 0 to 1000000.

**`opportunity.filters.link_counts_min.article`object, optional**

The minimum number of outbound links in the article section of a page, for each link type: `follow`, `nofollow`, `sponsored`, and `ugc`. A saved opportunity with no link minimum has no `link_counts_min`.

**`opportunity.filters.link_counts_min.nav`object, optional**

The same, for the navigation section of a page.

**`opportunity.filters.link_counts_min.comments`object, optional**

The same, for the comments section of a page.

**`opportunity.similarity_target`string**

What the pages must be semantically similar to: `none`, `campaign`, or `similarity_text`. Empty when it is not set.

**`opportunity.similarity_text`string**

The text of `similarity_target` `similarity_text`. Empty when it is not set.

**`opportunity.vector_ready`bool**

`true` when the vector of the `similarity_text` of the saved opportunity is made.

**`opportunity.title_query`string**

The words the title must have. Empty when it is not set.

**`opportunity.body_query`string**

The words the body must have. Empty when it is not set.

**`opportunity.title_body_join`string**

How `title_query` and `body_query` are combined: `and` or `or`. Empty when it is not set.

## Example

### Call

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "campaigns_saved_opportunity_archive",
    "arguments": {
      "campaign": 124,
      "opportunity": 12
    }
  }
}
```

### Response

The response is shown in full.

```json
{
  "opportunity": {
    "id": 12,
    "label": "Media kits naming boutique hotels",
    "state": "archived",
    "search": "opportunity_type",
    "opportunity_type": "advertising/advertise-with-us",
    "content_type": "",
    "filters": {
      "type_score_min": 40,
      "similarity_score_min": 25,
      "pr_domain_min": 20,
      "pr_domain_max": 80,
      "pr_host_min": 10,
      "pr_host_max": 90,
      "prot_domain_min": 5,
      "prot_domain_max": 95,
      "prot_host_min": 5,
      "prot_host_max": 95,
      "link_counts_min": {
        "article": {
          "follow": 2,
          "nofollow": 1,
          "sponsored": 0,
          "ugc": 0
        },
        "nav": {
          "follow": 1,
          "nofollow": 0,
          "sponsored": 0,
          "ugc": 0
        },
        "comments": {
          "follow": 0,
          "nofollow": 1,
          "sponsored": 0,
          "ugc": 0
        }
      }
    },
    "similarity_target": "campaign",
    "similarity_text": "",
    "vector_ready": false,
    "title_query": "\"media kit\" OR advertise",
    "body_query": "",
    "title_body_join": ""
  }
}
```

## Errors

An error returns as a tool result with `isError` true. Its text starts with the error code. An example: a call by a team member who cannot make this change.

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "no_access: You have read permissions for this campaign."
      }
    ],
    "isError": true
  }
}
```

One error is not a tool result. A call with a token that does not have the scope `api:write` gets the HTTP status 403, as the MCP standard says. The answer has a `WWW-Authenticate` header with `error="insufficient_scope"` and the scopes that the call needs. An MCP app that reads this header asks you for the permissions to change campaigns. The body has the error code `forbidden` and its sentence. The tool does not run, and the call is not counted.

```http
HTTP/1.1 403 Forbidden
WWW-Authenticate: Bearer error="insufficient_scope", scope="mcp:use api:write", resource_metadata="https://mcp.oppalerts.com/.well-known/oauth-protected-resource/mcp", error_description="This token cannot change data. Make a new API token with edit permissions on the API tokens page, or connect the app again and allow changes."
Content-Type: application/json

{
  "error": "forbidden",
  "error_description": "This token cannot change data. Make a new API token with edit permissions on the API tokens page, or connect the app again and allow changes."
}
```

The error codes of this tool, each with its HTTP status and its sentence:

- `bad_param` (HTTP 400 in the API): A parameter is missing or has a wrong value. The sentence names it.
- `no_campaign` (HTTP 404 in the API): That campaign is not in this account.
- `forbidden` (HTTP 403 in the API, and HTTP 403 in MCP too, see above): This token cannot change data. Make a new API token with edit permissions on the API tokens page, or connect the app again and allow changes.
- `no_access` (HTTP 403 in the API): You have read permissions for this campaign.
- `db_error` (HTTP 500 in the API): The change could not be saved. Nothing was changed.
- `opportunity_not_found` (HTTP 404 in the API): That opportunity is not in this campaign.

## Limits

- This tool has its own daily count for the account. When the count is used up, the call is refused with `daily_limit` (HTTP 429 in the API). [account_calls_left](https://oppalerts.com/docs/mcp/account_calls_left) shows the calls left today and when the count resets.
- A refused call does not use the daily count of this tool.
- This tool is not an index search. It does not use the daily count of index searches.
- Only one change runs at a time per account. A call made while another change is running for the account is refused with `one_at_a_time` (HTTP 429 in the API) and uses no daily call. Send it again after a few seconds.

## Same change in the API

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

{"campaign": 124, "opportunity": 12}
```

The API page is [POST /v1/campaigns/saved_opportunity_archive](https://oppalerts.com/docs/api/campaigns_saved_opportunity_archive).

## Related pages

- [Edit Campaign in the web app](https://oppalerts.com/docs/app/campaign/edit)
- [POST /v1/campaigns/saved_opportunity_archive in the API](https://oppalerts.com/docs/api/campaigns_saved_opportunity_archive)
- [campaigns_saved_opportunity_activate](https://oppalerts.com/docs/mcp/campaigns_saved_opportunity_activate): make it active again
- [campaigns_saved_opportunities](https://oppalerts.com/docs/mcp/campaigns_saved_opportunities): the saved opportunities of one campaign and their ids
