Competitor keywords
Competitor keywords are the keyword rules owned by one competitor. The
field contract is the same as project keywords — value
normalization, defaults and the narrow PATCH rules all behave identically.
Use the owning project’s id as {projectId}, the competitor’s id as
{competitorId}, and the keyword’s id as {keywordId}.
List keywords
List one competitor’s keywords.
The response is an unpaginated {results} collection. A keyword belonging
to a different competitor under the same URL answers 404 — always copy
ids from list responses.
GET/api/v1/projects/{projectId}/competitors/{competitorId}/keywords/
Responses
200OKapplication/json
| Field | Type | Required | Notes |
|---|---|---|---|
results | object[] | yes | |
id | string | yes | Stable membership UUID (never the shared canonical keyword id). |
value | string | yes | Normalized keyword value (trimmed, lowercased, whitespace collapsed). |
target | string | yes | Matching surface for this membership. — one of: "post", "comment", "post_comment" |
match_type | string | yes | Matching mode for this membership. — one of: "all_words", "exact" |
enabled | boolean | null | yes | Read-only provider-observed enabled state (null = never observed); never accepted on write. |
{
"results": [
{
"id": "5e4f3g2h-3333-4a5b-8c7d-6e5f4a3b2c1d",
"value": "competitor.example.com",
"target": "post_comment",
"match_type": "all_words",
"enabled": null
}
]
}All errors answer the standard problem body — this operation can also return 401, 404, 429, 5xx, documented in Errors & retries.
Create keyword
Add one keyword to a competitor. The same rule cannot be owned by two
competitors in one project — that answers 409.
Reconcile conflicts by listing instead of replaying the POST (errors & retries).
POST/api/v1/projects/{projectId}/competitors/{competitorId}/keywords/
Request body
| Field | Type | Required | Notes |
|---|---|---|---|
value | string | yes | 1–200 chars |
target | string | null | no | one of: "post", "comment", "post_comment" |
match_type | string | null | no | one of: "all_words", "exact" |
{
"value": "pricing"
}Responses
201Createdapplication/json
| Field | Type | Required | Notes |
|---|---|---|---|
id | string | yes | Stable membership UUID (never the shared canonical keyword id). |
value | string | yes | Normalized keyword value (trimmed, lowercased, whitespace collapsed). |
target | string | yes | Matching surface for this membership. — one of: "post", "comment", "post_comment" |
match_type | string | yes | Matching mode for this membership. — one of: "all_words", "exact" |
enabled | boolean | null | yes | Read-only provider-observed enabled state (null = never observed); never accepted on write. |
{
"id": "1a2b3c4d-5555-4e6f-8a9b-0c1d2e3f4a5b",
"value": "pricing",
"target": "post",
"match_type": "all_words",
"enabled": null
}409Conflict
Competitor website collision, duplicate/overlapping keyword identity, or a canonical rule already owned by another competitor in this project.
All errors answer the standard problem body — this operation can also return 400, 401, 403, 404, 429, 5xx, documented in Errors & retries.
Get keyword
Read one competitor keyword by its stable id.
GET/api/v1/projects/{projectId}/competitors/{competitorId}/keywords/{keywordId}/
Responses
200OKapplication/json
| Field | Type | Required | Notes |
|---|---|---|---|
id | string | yes | Stable membership UUID (never the shared canonical keyword id). |
value | string | yes | Normalized keyword value (trimmed, lowercased, whitespace collapsed). |
target | string | yes | Matching surface for this membership. — one of: "post", "comment", "post_comment" |
match_type | string | yes | Matching mode for this membership. — one of: "all_words", "exact" |
enabled | boolean | null | yes | Read-only provider-observed enabled state (null = never observed); never accepted on write. |
{
"id": "5e4f3g2h-3333-4a5b-8c7d-6e5f4a3b2c1d",
"value": "competitor.example.com",
"target": "post_comment",
"match_type": "all_words",
"enabled": null
}All errors answer the standard problem body — this operation can also return 401, 404, 429, 5xx, documented in Errors & retries.
Update keyword
Update one competitor keyword. Send any nonempty subset of the writable fields; omitted fields stay unchanged.
JSON nulls, unknown keys and the read-only enabled field are rejected
with 400.
PATCH/api/v1/projects/{projectId}/competitors/{competitorId}/keywords/{keywordId}/
Request body
| Field | Type | Required | Notes |
|---|---|---|---|
value | string | no | 1–200 chars |
target | string | no | one of: "post", "comment", "post_comment" |
match_type | string | no | one of: "all_words", "exact" |
{
"value": "competitor pricing"
}Responses
200OKapplication/json
| Field | Type | Required | Notes |
|---|---|---|---|
id | string | yes | Stable membership UUID (never the shared canonical keyword id). |
value | string | yes | Normalized keyword value (trimmed, lowercased, whitespace collapsed). |
target | string | yes | Matching surface for this membership. — one of: "post", "comment", "post_comment" |
match_type | string | yes | Matching mode for this membership. — one of: "all_words", "exact" |
enabled | boolean | null | yes | Read-only provider-observed enabled state (null = never observed); never accepted on write. |
{
"id": "5e4f3g2h-3333-4a5b-8c7d-6e5f4a3b2c1d",
"value": "competitor pricing",
"target": "post_comment",
"match_type": "all_words",
"enabled": null
}409Conflict
Competitor website collision, duplicate/overlapping keyword identity, or a canonical rule already owned by another competitor in this project.
All errors answer the standard problem body — this operation can also return 400, 401, 403, 404, 429, 5xx, documented in Errors & retries.
A PATCH whose result is identical to the stored row is a 200 no-op.
Delete keyword
Remove one competitor keyword. The competitor itself stays in place — possibly with no rules; nothing is reseeded implicitly.
DELETE/api/v1/projects/{projectId}/competitors/{competitorId}/keywords/{keywordId}/
Responses
204No Contentno body
All errors answer the standard problem body — this operation can also return 401, 403, 404, 429, 5xx, documented in Errors & retries.
Success is 204 with no body. Deleting the same id again returns 404.