--- title: "Add one or more keywords" method: POST path: "/projects/{project_id}/keywords" tags: ["keywords"] --- # Add one or more keywords `POST /projects/{project_id}/keywords` ## Request - Base URL: `https://eu.bisibility.com/api/v1` - URL: `https://eu.bisibility.com/api/v1/projects/{project_id}/keywords` - 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`) ## Path parameters - `project_id` string, required: Public project ID; membership and token scope are enforced. ## Headers - `Bisibility-API-Version` 'v1' - `Idempotency-Key` string - `X-Bisibility-Source` 'sdk' | 'cli' | 'mcp' ## Request body - union - object - `keywords` union[], required - union - object - `city` string, nullable - `country` 'United States' | 'United Kingdom' | 'Canada' | 'Australia' | 'Germany' | 'France' | 'Spain' | 'Italy' | 'Netherlands' | 'Sweden' | 'Poland' | 'Ireland' | 'Portugal' | 'Belgium' | 'Switzerland' | 'Austria' | 'Denmark' | 'Norway' | 'Finland' | 'Brazil' | 'Mexico' | 'India' | 'Japan' | 'Singapore' | 'New Zealand' | 'South Africa' | 'United Arab Emirates' - `device` 'desktop' | 'mobile' - `intent` string, nullable - `keyword` string, required - `language` string - `location` 'United States' | 'United Kingdom' | 'Canada' | 'Australia' | 'Germany' | 'France' | 'Spain' | 'Italy' | 'Netherlands' | 'Sweden' | 'Poland' | 'Ireland' | 'Portugal' | 'Belgium' | 'Switzerland' | 'Austria' | 'Denmark' | 'Norway' | 'Finland' | 'Brazil' | 'Mexico' | 'India' | 'Japan' | 'Singapore' | 'New Zealand' | 'South Africa' | 'United Arab Emirates' - `location_key` string - `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 - `topic` string, nullable - string - object[] - `city` string, nullable - `country` 'United States' | 'United Kingdom' | 'Canada' | 'Australia' | 'Germany' | 'France' | 'Spain' | 'Italy' | 'Netherlands' | 'Sweden' | 'Poland' | 'Ireland' | 'Portugal' | 'Belgium' | 'Switzerland' | 'Austria' | 'Denmark' | 'Norway' | 'Finland' | 'Brazil' | 'Mexico' | 'India' | 'Japan' | 'Singapore' | 'New Zealand' | 'South Africa' | 'United Arab Emirates' - `device` 'desktop' | 'mobile' - `intent` string, nullable - `keyword` string, required - `language` string - `location` 'United States' | 'United Kingdom' | 'Canada' | 'Australia' | 'Germany' | 'France' | 'Spain' | 'Italy' | 'Netherlands' | 'Sweden' | 'Poland' | 'Ireland' | 'Portugal' | 'Belgium' | 'Switzerland' | 'Austria' | 'Denmark' | 'Norway' | 'Finland' | 'Brazil' | 'Mexico' | 'India' | 'Japan' | 'Singapore' | 'New Zealand' | 'South Africa' | 'United Arab Emirates' - `location_key` string - `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 - `topic` string, nullable - object - `city` string, nullable - `country` 'United States' | 'United Kingdom' | 'Canada' | 'Australia' | 'Germany' | 'France' | 'Spain' | 'Italy' | 'Netherlands' | 'Sweden' | 'Poland' | 'Ireland' | 'Portugal' | 'Belgium' | 'Switzerland' | 'Austria' | 'Denmark' | 'Norway' | 'Finland' | 'Brazil' | 'Mexico' | 'India' | 'Japan' | 'Singapore' | 'New Zealand' | 'South Africa' | 'United Arab Emirates' - `device` 'desktop' | 'mobile' - `intent` string, nullable - `keyword` string, required - `language` string - `location` 'United States' | 'United Kingdom' | 'Canada' | 'Australia' | 'Germany' | 'France' | 'Spain' | 'Italy' | 'Netherlands' | 'Sweden' | 'Poland' | 'Ireland' | 'Portugal' | 'Belgium' | 'Switzerland' | 'Austria' | 'Denmark' | 'Norway' | 'Finland' | 'Brazil' | 'Mexico' | 'India' | 'Japan' | 'Singapore' | 'New Zealand' | 'South Africa' | 'United Arab Emirates' - `location_key` string - `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 - `topic` string, nullable ## Response `200` JSON response - object - `created` integer, required - `skipped` integer, required - `warnings` string[] - `results` object[], required - `keyword` Keyword, required - `country` string, required: Resolved keyword location display name. - `created_at` string, date-time, required - `device` 'desktop' | 'mobile', required - `id` string, required - `intent` string, nullable, required - `latest_check` KeywordLatestCheck, nullable, required: The most recent executed check of any status. A completed check with `position: null` can have unknown coverage; read `observation_completeness` before inferring absence within the requested depth; `latest_check.status: "failed"` means "unknown, the check did not run to completion". - `checked_at` string, date-time, required - `error` string, nullable, required - `error_code` string, nullable, required - `id` string, required - `observation_completeness` 'complete' | 'truncated_by_stop_on_match' | 'unknown' | 'null', nullable, required: Persisted coverage, or null when legacy metadata is absent. Only complete coverage supports absence within depth; a valid positive rank remains valid with truncated coverage. - `position` integer, nullable, required - `run_id` string, nullable, required: Rank-check run that produced this check, or null for a legacy row. - `status` 'completed' | 'failed' | 'running', required - `latest_position` integer, nullable, required: `latest_position` = `latest_check.position`; it is `null` for failed checks, unknown observation coverage, or absence within the requested depth. Agents that need "the last known ranking" must read `latest_successful_check.position`. - `latest_successful_check` KeywordLatestSuccessfulCheck, nullable, required: The most recent completed check. Null position with unknown observation_completeness does not establish absence within depth. - `checked_at` string, date-time, required - `id` string, required - `observation_completeness` 'complete' | 'truncated_by_stop_on_match' | 'unknown' | 'null', nullable, required: Persisted coverage, or null when legacy metadata is absent. Only complete coverage supports absence within depth; a valid positive rank remains valid with truncated coverage. - `position` integer, nullable, required - `ranking_url` string, nullable, required - `run_id` string, nullable, required: Rank-check run that produced this check, or null for a legacy row. - `language_code` string, required - `language_label` string, required - `location` string, required: Resolved keyword location display name. - `location_key` string, required: Canonical country, region, or city key, optionally qualified with @language. The default language normalizes to the unqualified key. - `previous_position` integer, nullable, required: `previous_position` = the position recorded on `latest_check` as its predecessor. - `project_id` string, required - `ranking_url` string, nullable, required - `schedule` object, nullable, required - `cron_expression` string, nullable, required - `frequency` 'paused' | 'manual' | 'daily' | 'weekly' | 'monthly' | 'custom_cron', required - `jitter_minutes` integer, required: Whole-minute random delay from 0 to 120. Set 0 to disable jitter. - `last_checked_at` string, date-time, nullable, required - `next_check_at` string, date-time, nullable, required - `source` 'keyword' | 'project_default', required: Whether these schedule values come from the keyword's own row or from the project defaults. - `timezone` string, required: IANA time zone that anchors monthly and custom cron wall-clock schedules. Daily and weekly use a stable keyword-specific interval phase that timezone does not move. - `tags` string[], required - `target_url` string, nullable, required - `text` string, required - `topic` string, nullable, required - `updated_at` string, date-time, required - `status` 'created' | 'skipped', required - `warning` string ## Other responses - `201`: At least one keyword created - `400`: Bad request - `401`: Unauthorized - `403`: Forbidden - `404`: Not found - `409`: Unsupported API version - `429`: Rate limited ## Changes - **2026-10-19** `a6e1ec0dec82`: 3 breaking, 12 info - added the new path request parameter `project_id` - added required request body - the `created` response's property type changed from `array` to `integer` for status `200` - the endpoint scheme security `AppOAuth` was added to the API - …11 more [Operation history](https://skmtc.dev/bisibility/apis/bisibility-public-api/changes/projects/:project_id/keywords/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)