Skip to Content
APICompetitors

Competitors

A competitor is an absolute http(s) website URL, unique within its project. Competitors are created through the API (or the website) and each carries nested keyword_rules with their stable ids — manage those rules on Competitor keywords.

Use the project’s id as {projectId} and the competitor’s id as {competitorId}. Competitor IDs are returned by list and create operations.

List competitors

List the project’s competitors with their nested keyword rules.

The response is an unpaginated {results} collection. A competitor whose rules were all deleted stays listed as an empty row.

GET/api/v1/projects/{projectId}/competitors/

Responses

200OKapplication/json

FieldTypeRequiredNotes
resultsobject[]yes
idstringyesStable competitor UUID.
websitestringyesNormalized competitor website (absolute http(s) URL, trimmed).
keyword_rulesobject[]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": "9d8c7b6a-2222-4f5e-8d9c-0b1a2f3e4d5c", "website": "https://competitor.example.com", "keyword_rules": [ { "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 competitor

Add one competitor website, unique within the project. The server atomically seeds one derived default keyword (target=post_comment, match_type=all_words).

export INTENTLOOM_API_TOKEN='il_live_REPLACE_WITH_YOUR_TOKEN' export INTENTLOOM_PROJECT='b1a2c3d4-0000-4a5b-8c6d-7e8f9a0b1c2d' curl -fsS -X POST "https://api.intentloom.com/api/v1/projects/$INTENTLOOM_PROJECT/competitors/" \ -H "Authorization: Token $INTENTLOOM_API_TOKEN" \ -H 'Content-Type: application/json' \ -d '{"website":"https://competitor.example.com"}'

Creation is atomic: if anything fails (derivation, collision, quota) nothing is created. A 201 returns the competitor with its seeded rule.

POST/api/v1/projects/{projectId}/competitors/

Request body

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

FieldTypeRequiredNotes
websitestringyesAbsolute http(s) competitor URL (1-200 chars after trim; project-unique). — 1–200 chars
{ "website": "https://competitor.example.com" }

Responses

201Createdapplication/json

FieldTypeRequiredNotes
idstringyesStable competitor UUID.
websitestringyesNormalized competitor website (absolute http(s) URL, trimmed).
keyword_rulesobject[]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.
{ "id": "9d8c7b6a-2222-4f5e-8d9c-0b1a2f3e4d5c", "website": "https://competitor.example.com", "keyword_rules": [ { "id": "5e4f3g2h-3333-4a5b-8c7d-6e5f4a3b2c1d", "value": "competitor.example.com", "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 website collision or an already-owned rule answers 409 with no mutation — reconcile by listing instead of replaying the POST (errors & retries).

Get competitor

Read one competitor by its stable id, including its nested keyword_rules.

GET/api/v1/projects/{projectId}/competitors/{competitorId}/

Responses

200OKapplication/json

FieldTypeRequiredNotes
idstringyesStable competitor UUID.
websitestringyesNormalized competitor website (absolute http(s) URL, trimmed).
keyword_rulesobject[]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.
{ "id": "9d8c7b6a-2222-4f5e-8d9c-0b1a2f3e4d5c", "website": "https://competitor.example.com", "keyword_rules": [ { "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.

Rename competitor

Rename one competitor. The body accepts only website; existing keywords are neither regenerated nor replaced.

An unchanged website is a 200 no-op.

PATCH/api/v1/projects/{projectId}/competitors/{competitorId}/

Request body

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

FieldTypeRequiredNotes
websitestringyes1–200 chars
{ "website": "https://rebranded.example.com" }

Responses

200OKapplication/json

FieldTypeRequiredNotes
idstringyesStable competitor UUID.
websitestringyesNormalized competitor website (absolute http(s) URL, trimmed).
keyword_rulesobject[]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.
{ "id": "9d8c7b6a-2222-4f5e-8d9c-0b1a2f3e4d5c", "website": "https://rebranded.example.com", "keyword_rules": [ { "id": "5e4f3g2h-3333-4a5b-8c7d-6e5f4a3b2c1d", "value": "competitor.example.com", "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.

Delete competitor

Delete one competitor. The delete cascades to the competitor’s keywords.

DELETE/api/v1/projects/{projectId}/competitors/{competitorId}/

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