Skip to Content
APICompetitor keywords

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

FieldTypeRequiredNotes
resultsobject[]yes
idstringyesStable membership UUID (never the shared canonical keyword id).
valuestringyesNormalized keyword value (trimmed, lowercased, whitespace collapsed).
targetstringyesMatching surface for this membership. — one of: "post", "comment", "post_comment"
match_typestringyesMatching mode for this membership. — one of: "all_words", "exact"
enabledboolean | nullyesRead-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

Content-Type: application/json — unknown keys are rejected.

FieldTypeRequiredNotes
valuestringyes1–200 chars
targetstring | nullnoone of: "post", "comment", "post_comment"
match_typestring | nullnoone of: "all_words", "exact"
{ "value": "pricing" }

Responses

201Createdapplication/json

FieldTypeRequiredNotes
idstringyesStable membership UUID (never the shared canonical keyword id).
valuestringyesNormalized keyword value (trimmed, lowercased, whitespace collapsed).
targetstringyesMatching surface for this membership. — one of: "post", "comment", "post_comment"
match_typestringyesMatching mode for this membership. — one of: "all_words", "exact"
enabledboolean | nullyesRead-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

FieldTypeRequiredNotes
idstringyesStable membership UUID (never the shared canonical keyword id).
valuestringyesNormalized keyword value (trimmed, lowercased, whitespace collapsed).
targetstringyesMatching surface for this membership. — one of: "post", "comment", "post_comment"
match_typestringyesMatching mode for this membership. — one of: "all_words", "exact"
enabledboolean | nullyesRead-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

Content-Type: application/json — unknown keys are rejected.

FieldTypeRequiredNotes
valuestringno1–200 chars
targetstringnoone of: "post", "comment", "post_comment"
match_typestringnoone of: "all_words", "exact"
{ "value": "competitor pricing" }

Responses

200OKapplication/json

FieldTypeRequiredNotes
idstringyesStable membership UUID (never the shared canonical keyword id).
valuestringyesNormalized keyword value (trimmed, lowercased, whitespace collapsed).
targetstringyesMatching surface for this membership. — one of: "post", "comment", "post_comment"
match_typestringyesMatching mode for this membership. — one of: "all_words", "exact"
enabledboolean | nullyesRead-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.

Last updated on