---
title: "Bulk mutate keywords"
method: POST
path: "/keywords/bulk"
tags: ["keywords"]
---

# Bulk mutate keywords

`POST /keywords/bulk`

## Request

- Base URL: `https://eu.bisibility.com/api/v1`
- URL: `https://eu.bisibility.com/api/v1/keywords/bulk`
- Auth: one of:
  - HTTP bearer
  - HTTP bearer
  - OAuth 2 (authorization code, authorization URL `/api/auth/oauth2/authorize`, token URL `/api/auth/oauth2/token`, scopes: `api:write`)

## Query parameters

- `project` string

## Headers

- `Bisibility-API-Version` 'v1'
- `Idempotency-Key` string
- `X-Bisibility-Project` string
- `X-Bisibility-Source` 'sdk' | 'cli' | 'mcp'

## Request body

- object: Partial mutation: optional fields may be absent. target_url accepts null to clear the URL; for set_target_url, omission also clears it. Other top-level fields reject null. Tag operations require nonempty tags; set_frequency requires frequency or schedule.
  - `frequency` 'paused' | 'manual' | 'daily' | 'weekly' | 'monthly' | 'custom_cron'
  - `keyword_ids` string[], required
  - `operation` 'add_tags' | 'delete' | 'remove_tags' | 'set_frequency' | 'set_target_url', required
  - `schedule` object
    - `cron_expression` string, nullable
    - `frequency` 'paused' | 'manual' | 'daily' | 'weekly' | 'monthly' | 'custom_cron', required
    - `jitter_minutes` integer
    - `serp_depth` 10 | 20 | 50 | 100 | null, nullable
    - `timezone` string
  - `tags` string[]
  - `target_url` string, nullable

## Response `200`

JSON response

- object
  - `operation` 'add_tags' | 'delete' | 'remove_tags' | 'set_frequency' | 'set_target_url', required
  - `results` object[], required
    - `keyword_id` string, required
    - `status` 'updated' | 'deleted' | 'not_found', required

## Other responses

- `400`: Bad request
- `401`: Unauthorized
- `403`: Forbidden
- `404`: Not found
- `409`: Unsupported API version
- `429`: Rate limited

## Changes

- **2026-10-19** `a6e1ec0dec82`: 1 breaking, 1 warning, 9 info
  - added required request body
  - removed the optional property `created` from the response with the `200` status
  - the endpoint scheme security `AppOAuth` was added to the API
  - added the new optional `header` request parameter `Idempotency-Key`
  - …7 more

[Operation history](https://skmtc.dev/bisibility/apis/bisibility-public-api/changes/keywords/bulk/post.md)

---

[API](https://skmtc.dev/bisibility/apis/bisibility-public-api.md) · [All operations](https://skmtc.dev/bisibility/apis/bisibility-public-api/llms.txt) · [OpenAPI document](https://skmtc.dev/bisibility/apis/bisibility-public-api/revisions/a6e1ec0dec82?raw)