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:

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

{
  "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.