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
| Field | Type | Required | Notes |
|---|---|---|---|
results | object[] | yes | |
id | string | yes | Stable competitor UUID. |
website | string | yes | Normalized competitor website (absolute http(s) URL, trimmed). |
keyword_rules | 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": "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
| Field | Type | Required | Notes |
|---|---|---|---|
website | string | yes | Absolute http(s) competitor URL (1-200 chars after trim; project-unique). — 1–200 chars |
{
"website": "https://competitor.example.com"
}Responses
201Createdapplication/json
| Field | Type | Required | Notes |
|---|---|---|---|
id | string | yes | Stable competitor UUID. |
website | string | yes | Normalized competitor website (absolute http(s) URL, trimmed). |
keyword_rules | 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. |
{
"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
| Field | Type | Required | Notes |
|---|---|---|---|
id | string | yes | Stable competitor UUID. |
website | string | yes | Normalized competitor website (absolute http(s) URL, trimmed). |
keyword_rules | 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. |
{
"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
| Field | Type | Required | Notes |
|---|---|---|---|
website | string | yes | 1–200 chars |
{
"website": "https://rebranded.example.com"
}Responses
200OKapplication/json
| Field | Type | Required | Notes |
|---|---|---|---|
id | string | yes | Stable competitor UUID. |
website | string | yes | Normalized competitor website (absolute http(s) URL, trimmed). |
keyword_rules | 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. |
{
"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.