Remove competitor domain

Stops citations to an address counting toward this competitor. The competitor itself is untouched.

Requires the write:competitors scope, and the workspace must be enabled for API writes.


DELETE /v1/brands/{brand_id}/competitors/{competitor_id}/domains

This applies to answers already collected. Removing an address un-attributes citations that were already recorded, so the competitor’s citation rate can move the moment this returns. Nothing is deleted: those citations simply stop counting as theirs.

Authorization

Header	Type	Required
`Authorization`	`Bearer asky_sk_…`	required
`Idempotency-Key`	`string`	required

Path parameters

Parameter	Type	Required	Description
`brand_id`	`uuid`	required	From List brands
`competitor_id`	`uuid`	required	From List competitors

Query parameters

None.

Body

application/json

Field	Type	Required	Description
`address`	`string`, up to 2048 chars	required	The address to stop counting, exactly as returned by Get competitor

The address travels in the body rather than the path because a section contains slashes, which would need encoding in a path segment and is easy to get wrong.

Request

cURL


curl --request DELETE \
  --url 'https://api.askylabs.com/v1/brands/242546de-4cee-4a7d-952e-f6aa60c63ef8/competitors/c4a7e1b2-38d9-4f60-b5ac-2d90e7f14b83/domains' \
  --header 'Authorization: Bearer <api-key>' \
  --header 'Idempotency-Key: <unique-per-attempt>' \
  --header 'Content-Type: application/json' \
  --data '{"address":"ahrefs.de"}'

Python


import requests
 
url = "https://api.askylabs.com/v1/brands/242546de-4cee-4a7d-952e-f6aa60c63ef8/competitors/c4a7e1b2-38d9-4f60-b5ac-2d90e7f14b83/domains"
headers = {"Authorization": "Bearer <api-key>", "Idempotency-Key": "<unique-per-attempt>"}
 
response = requests.delete(url, json={"address": "ahrefs.de"}, headers=headers)
print(response.json()["data"]["addresses"])

JavaScript


const options = {
  method: 'DELETE',
  headers: {Authorization: 'Bearer <api-key>', 'Idempotency-Key': '<unique-per-attempt>', 'Content-Type': 'application/json'},
  body: JSON.stringify({address: 'ahrefs.de'})
};
 
fetch('https://api.askylabs.com/v1/brands/242546de-4cee-4a7d-952e-f6aa60c63ef8/competitors/c4a7e1b2-38d9-4f60-b5ac-2d90e7f14b83/domains', options)
  .then(res => res.json()).then(res => console.log(res.data.addresses));

Response

200


{
  "data": {
    "competitor_id": "c4a7e1b2-38d9-4f60-b5ac-2d90e7f14b83",
    "addresses": {
      "main": "ahrefs.com",
      "apexes": ["ahrefs.fr"],
      "sections": ["help.ahrefs.com"]
    }
  },
  "request_id": "req_1b48d0ae72c34f96e5da"
}

400


{
  "error": {
    "code": "invalid_request",
    "message": "address is not a valid web address. Use a domain like example.de, or a section like example.com/product.",
    "request_id": "req_7e02c9bf38a14d63b7fc"
  }
}

403


{
  "error": {
    "code": "insufficient_scope",
    "message": "This action requires the \"write:competitors\" scope, which your token does not have.",
    "request_id": "req_3d95b1ce06f24a87c0eb"
  }
}

404


{
  "error": {
    "code": "not_found",
    "message": "Not found.",
    "request_id": "req_9f26e0da51b34c78a3cd"
  }
}

Response fields

Identical to Add competitor domain. The full resulting set is returned, so you can confirm what the competitor now claims without a follow-up read.

Errors

Status	Code	When
400	`invalid_request`	Unknown field, missing `address`, or an address that is not a valid web address
401	`invalid_token`	The key is missing, malformed, or does not exist
403	`insufficient_scope`	The key does not carry `write:competitors`
403	`plan_required`	This workspace is not enabled for API writes
404	`not_found`	The brand or competitor does not exist, or this key is not allowed to reach it
429	`rate_limited`	Over 60 requests per minute

Notes

Removing a section never removes the whole domain, and the reverse. Dropping elastic.co/observability leaves elastic.co claimed if it was claimed separately, because those are two different statements about what the competitor owns. Remove each one you mean.

You cannot remove the main address here. addresses.main comes from the competitor’s primary_url. Change it with Update competitor instead.

Removing an address that is not there is not an error. The resulting set is returned either way, so a sync that removes optimistically stays simple.

Idempotency-Key is required. See Idempotency.