---
title: "Bulk ignore and restore content keywords"
description: "Ignore or restore a list of irrelevant content keywords through the API, for one article or one website workspace."
canonical_url: "https://help.rankability.com/api/api-keyword-exclusions"
section: "API"
last_updated: 2026-10-30
related:
  - title: "Getting started with the API"
    url: "https://help.rankability.com/api/api-getting-started"
  - title: "Authentication and API scopes"
    url: "https://help.rankability.com/api/api-authentication"
  - title: "API usage, rate limits, and errors"
    url: "https://help.rankability.com/api/api-credits-rate-limits-and-errors"
  - title: "Getting started with the Tracker API"
    url: "https://help.rankability.com/api/api-reporter-getting-started"
  - title: "Prospect reports API"
    url: "https://help.rankability.com/api/api-prospect-scans"
  - title: "Tracker API endpoint reference"
    url: "https://help.rankability.com/api/api-reporter-endpoints"
  - title: "Researcher API"
    url: "https://help.rankability.com/api/api-researcher"
  - title: "Prospector API"
    url: "https://help.rankability.com/api/api-prospector"
  - title: "Backlink Profile API"
    url: "https://help.rankability.com/api/api-backlink-profile"
  - title: "Scrape, Crawl, and Extract API"
    url: "https://help.rankability.com/api/api-crawler"
  - title: "Site Auditor API"
    url: "https://help.rankability.com/api/api-site-auditor"
  - title: "Creating content jobs"
    url: "https://help.rankability.com/api/api-creating-content-jobs"
  - title: "Running Autopilot content jobs"
    url: "https://help.rankability.com/api/api-copywriter-autopilot"
  - title: "Supported languages"
    url: "https://help.rankability.com/api/api-supported-languages"
  - title: "Retrieving and using artifacts"
    url: "https://help.rankability.com/api/api-retrieving-artifacts"
  - title: "API use cases and integration patterns"
    url: "https://help.rankability.com/api/api-use-cases"
  - title: "Building a Looker Studio dashboard with the Tracker API"
    url: "https://help.rankability.com/api/api-reporter-looker-studio"
  - title: "Knowledge Base API endpoint"
    url: "https://help.rankability.com/api/api-knowledge-base"
  - title: "Connecting Rankability to AI assistants with MCP"
    url: "https://help.rankability.com/api/mcp-getting-started"
  - title: "Optimize API endpoint"
    url: "https://help.rankability.com/api/api-optimize-endpoint"
  - title: "Page Auditor API endpoints"
    url: "https://help.rankability.com/api/api-page-auditor"
  - title: "Search Intelligence API endpoints"
    url: "https://help.rankability.com/api/api-search-intelligence"
  - title: "Serena consultation API and MCP tool"
    url: "https://help.rankability.com/api/api-serena-consultation"
---
# Bulk ignore and restore content keywords

When several keyword recommendations don't belong in an article, you can ignore
them in one API request instead of updating each one in the editor. You can also
restore terms later.

This changes which recommendations count toward the content score. It doesn't
remove words already in your draft, rewrite content, or change search rankings.
It uses the same ignore lists as the editor, with no new research or generation.

## Choose the scope

| Target | Read the list | Ignore or restore terms | Required write scope |
| --- | --- | --- | --- |
| One content project | `GET /api/agent/v1/copywriter/jobs/:id/keyword-exclusions` | `PATCH /api/agent/v1/copywriter/jobs/:id/keyword-exclusions` | `copywriter:run` |
| One website workspace | `GET /api/agent/v1/clients/:id/keyword-exclusions` | `PATCH /api/agent/v1/clients/:id/keyword-exclusions` | `clients:write` |

Project reads need `copywriter:read`. Workspace reads accept `clients:read` or
`copywriter:read`. Existing API/account access requirements still apply.

Start with the project endpoint when a term is irrelevant to one article. Use the
workspace endpoint only when it should be excluded across that website's current
and future content projects. It does not affect your other client workspaces or
your organization-wide excluded topics.

## Preview before saving

Use your existing API credential and replace `PROJECT_ID` with an owned content
project ID:

```http
PATCH /api/agent/v1/copywriter/jobs/PROJECT_ID/keyword-exclusions
Authorization: Bearer rk_live_YOUR_KEY_HERE
Content-Type: application/json

{
  "ignore": ["unrelated product", "unrelated location"],
  "dry_run": true
}
```

The response lists the proposed additions in `changes.ignored`. For a preview,
`changed` is false because nothing was saved. `would_change` tells you whether
applying the request would alter the current list. `exclusion_count` is the
proposed total; `previous_exclusion_count` is the current total.

Review the scope and terms, then repeat the request with `dry_run: false`, or omit
that field, to save. Read the list back with the matching GET endpoint. GET reads
return up to 200 terms by default; use `limit` (1–500) and `offset` (0–100000),
following `pagination.next_offset` while `pagination.has_more` is true.

## Restore terms

```json
{
  "restore": ["unrelated product"]
}
```

You can combine `ignore` and `restore` in one request, but not for the same term.
Unrelated saved exclusions are preserved. Repeating an already-applied request is
a no-op; it doesn't rewrite the record or change its timestamp.

A project restore removes only the project ignore. If the workspace still blocks
that term, the response includes it in `still_ignored_by_workspace`. Use the
workspace endpoint—with the broader write scope—to remove a workspace exclusion.
Likewise, a workspace restore doesn't remove separate project ignores. Other
topic and recommendation-eligibility rules continue to apply.

## Limits and matching

- Send 1–200 entries across `ignore` and `restore` combined.
- Each term must contain 1–500 characters after trimming.
- Matching ignores letter case and repeated whitespace, just like the editor.
- Terms are exact matches, not wildcards, substring rules or AI instructions.
- A saved list can contain up to 5,000 distinct terms. If a legacy list is larger,
  you can still restore terms before adding new ones.
- Unknown fields, blank terms, conflicting actions and oversized batches return
  a validation error. Additions above the list cap return `exclusion_limit`.

The existing keyword CSV export leaves out ignored terms. It is not an import
template for this API. This first version is API-only; it doesn't add a CSV
importer or a new settings screen.

## What happens to scores and existing work?

Project changes use the editor's existing deterministic score calculation when
the saved research and draft are available. Read the normal job/artifact
endpoints for the current score.

Workspace changes don't rewrite every article or trigger background work. Score
readers detect the new workspace context on their next read. Refresh an
already-open editor to load the latest workspace list. These exclusions also
feed the existing workspace research/writing recommendation controls.

No draft text, published page, research report, tracking keyword or publishing
setting is changed. No generation usage is consumed by these list edits. Normal
API rate limits apply. Preview again if another editor may have changed the list
since you reviewed it; a preview is not a reservation of that earlier state.