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

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

# campaigns_set_taxonomy_presets

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

Sets the 3 taxonomy presets of one campaign: the taxonomy categories the Content Optimizer opens with.

## What it does

The tool sets the taxonomy presets of one campaign. A preset is one category of one taxonomy. The Content Optimizer opens with these categories.

The call replaces all 3 presets. The response contains the campaign after the change. In the web app, the presets show on the Settings tab of Edit Campaign, on the taxonomy presets card.

[taxonomy_taxonomies](https://oppalerts.com/docs/mcp/taxonomy_taxonomies) gives the taxonomy names, and [taxonomy_categories](https://oppalerts.com/docs/mcp/taxonomy_categories) gives the category ids and labels.

## 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.

**`preset_1`object, optional**

Optional. One taxonomy preset. Leave it out for no preset in this position. A preset that you send needs all 3 parts, and an empty preset is refused.

**`preset_1.taxonomy`string, required, at most 100 characters**

Required in a preset. The taxonomy name, as [taxonomy_taxonomies](https://oppalerts.com/docs/mcp/taxonomy_taxonomies) returns it. A name that is not in that list is refused.

**`preset_1.category_id`int, required, 1 to 9007199254740991**

Required in a preset. The category id in that taxonomy, a whole number, as [taxonomy_categories](https://oppalerts.com/docs/mcp/taxonomy_categories) returns it.

**`preset_1.category_label`string, required, at most 500 characters**

Required in a preset. The category name as displayed, at most 500 characters. It cannot be empty. It is kept as you send it.

**`preset_2`object, optional**

Optional. One taxonomy preset. Leave it out for no preset in this position. A preset that you send needs all 3 parts, and an empty preset is refused.

**`preset_2.taxonomy`string, required, at most 100 characters**

Required in a preset. The taxonomy name, as [taxonomy_taxonomies](https://oppalerts.com/docs/mcp/taxonomy_taxonomies) returns it. A name that is not in that list is refused.

**`preset_2.category_id`int, required, 1 to 9007199254740991**

Required in a preset. The category id in that taxonomy, a whole number, as [taxonomy_categories](https://oppalerts.com/docs/mcp/taxonomy_categories) returns it.

**`preset_2.category_label`string, required, at most 500 characters**

Required in a preset. The category name as displayed, at most 500 characters. It cannot be empty. It is kept as you send it.

**`preset_3`object, optional**

Optional. One taxonomy preset. Leave it out for no preset in this position. A preset that you send needs all 3 parts, and an empty preset is refused.

**`preset_3.taxonomy`string, required, at most 100 characters**

Required in a preset. The taxonomy name, as [taxonomy_taxonomies](https://oppalerts.com/docs/mcp/taxonomy_taxonomies) returns it. A name that is not in that list is refused.

**`preset_3.category_id`int, required, 1 to 9007199254740991**

Required in a preset. The category id in that taxonomy, a whole number, as [taxonomy_categories](https://oppalerts.com/docs/mcp/taxonomy_categories) returns it.

**`preset_3.category_label`string, required, at most 500 characters**

Required in a preset. The category name as displayed, at most 500 characters. It cannot be empty. It is kept as you send it.

## Rules

- Each preset (`preset_1`, `preset_2`, and `preset_3`) is optional. A preset that you leave out is removed.
- A preset that you send needs all 3 parts: `taxonomy`, `category_id`, and `category_label`. A missing or bad part is refused, and an empty preset is refused.
- Each preset must use a different taxonomy. 2 presets with the same taxonomy are refused with `taxonomy_twice`.

## 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 campaign after the change, in the same format that [campaigns_settings](https://oppalerts.com/docs/mcp/campaigns_settings) returns.

**`campaign.id`int**

The campaign id.

**`campaign.label`string**

The name of the campaign.

**`campaign.industry`string**

The industry of the campaign.

**`campaign.description`string**

The description of the campaign. It is an empty string when the campaign has none.

**`campaign.state`string**

The state of the campaign. The example shows `active`.

**`campaign.finalized`bool**

`true` when the campaign is finalized.

**`campaign.finalized_at`string**

The time when the campaign was finalized, as ISO 8601 text in UTC. Empty when `finalized` is `false`.

**`campaign.research`string**

The progress of the campaign’s research, with the values of `research` in [campaigns_list](https://oppalerts.com/docs/mcp/campaigns_list). The example shows `not_started`.

**`campaign.started_at`string**

The time when the campaign last counted as a start in the plan limit of campaigns started in 24 hours, as ISO 8601 text in UTC: its create, or [campaigns_activate](https://oppalerts.com/docs/mcp/campaigns_activate) of a campaign that was never finalized. Empty when the campaign has no such time.

**`campaign.taxonomy_presets`list**

The taxonomy presets of the campaign. Each item is one taxonomy category.

**`campaign.taxonomy_presets[].taxonomy`string**

The taxonomy of the category, as [taxonomy_taxonomies](https://oppalerts.com/docs/mcp/taxonomy_taxonomies) names it.

**`campaign.taxonomy_presets[].category_id`int**

The id of the category.

**`campaign.taxonomy_presets[].category_label`string**

The label of the category, for example `Travel > Travel Type > Hotels and Motels`.

**`campaign.daily_opportunities_email`object**

The daily opportunities email settings of the campaign.

**`campaign.daily_opportunities_email.enabled`bool**

`true` when the daily opportunities email is on.

**`campaign.daily_opportunities_email.email`string**

The address that gets the daily opportunities email.

**`campaign.daily_opportunities_email.first_name`string**

The first name used in the daily opportunities email.

**`campaign.daily_opportunities_email.send_hour`int**

The hour of the day when the daily opportunities email is sent, in `campaign.daily_opportunities_email.timezone`.

**`campaign.daily_opportunities_email.timezone`string**

The time zone of `send_hour`, for example `America/Los_Angeles`.

**`campaign.daily_opportunities_email.unsubscribed`bool**

`true` when the address unsubscribed from the daily opportunities email.

**`campaign.daily_opportunities_email.unsubscribed_at`string**

The time when the address unsubscribed with the link in the email, as ISO 8601 text in UTC. Empty when `unsubscribed` is `false`.

## Example

### Call

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "campaigns_set_taxonomy_presets",
    "arguments": {
      "campaign": 124,
      "preset_1": {
        "taxonomy": "iab-content-taxonomy",
        "category_id": 2358064203319202,
        "category_label": "Travel > Travel Type > Hotels and Motels"
      }
    }
  }
}
```

### Response

The response is shown in full.

```json
{
  "campaign": {
    "id": 124,
    "label": "Boutique Hotels",
    "industry": "Boutique hotels",
    "description": "Boutique hotel brands competing for direct bookings in mid-size US cities, against the online travel agencies and the big hotel chains.",
    "state": "active",
    "finalized": false,
    "finalized_at": "",
    "research": "not_started",
    "started_at": "2026-11-01T15:04:05Z",
    "taxonomy_presets": [
      {
        "taxonomy": "iab-content-taxonomy",
        "category_id": 2358064203319202,
        "category_label": "Travel > Travel Type > Hotels and Motels"
      }
    ],
    "daily_opportunities_email": {
      "enabled": true,
      "email": "pat@example.com",
      "first_name": "Pat",
      "send_hour": 7,
      "timezone": "America/Los_Angeles",
      "unsubscribed": false,
      "unsubscribed_at": ""
    }
  }
}
```

## 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.
- `taxonomy_twice` (HTTP 400 in the API): Not saved: two taxonomy presets named the same taxonomy. Each preset needs its own taxonomy.

## 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/set_taxonomy_presets HTTP/1.1
Host: api.oppalerts.com
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json

{"campaign": 124, "preset_1": {"taxonomy": "iab-content-taxonomy", "category_id": 2358064203319202, "category_label": "Travel > Travel Type > Hotels and Motels"}}
```

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

## Related pages

- [Edit Campaign in the web app](https://oppalerts.com/docs/app/campaign/edit)
- [POST /v1/campaigns/set_taxonomy_presets in the API](https://oppalerts.com/docs/api/campaigns_set_taxonomy_presets)
- [taxonomy_taxonomies](https://oppalerts.com/docs/mcp/taxonomy_taxonomies): the taxonomy names
- [taxonomy_categories](https://oppalerts.com/docs/mcp/taxonomy_categories): the categories of a taxonomy
- [campaigns_settings](https://oppalerts.com/docs/mcp/campaigns_settings): the presets of one campaign
- [Content Optimizer in the web app](https://oppalerts.com/docs/app/content/optimizer)
