Add competitor domain

A competitor is rarely one domain. They publish on country domains, on a docs subdomain, or on one section of a site they do not otherwise own. Adding an address here means citations to it count toward that competitor.

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


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

This applies to answers already collected. Adding an address re-attributes citations that were already recorded, so the competitor’s citation rate can move the moment this returns. It is not only forward-looking.

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	A whole domain like `example.de`, or one section like `example.com/product` or `help.example.com`

You do not say which kind it is. The address itself decides: anything narrower than a whole registrable domain is stored as a section, anything else as a domain.

Request

cURL


curl --request POST \
  --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.post(url, json={"address": "ahrefs.de"}, headers=headers)
print(response.json()["data"]["addresses"])

JavaScript


const options = {
  method: 'POST',
  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.de", "ahrefs.fr"],
      "sections": ["help.ahrefs.com"]
    }
  },
  "request_id": "req_2f6b90ce41a34d17b8ea"
}

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_4a70c1de83b24e59f2cb"
  }
}

403


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

404


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

Response fields

Field	Type	Description
`data.competitor_id`	`uuid`	required
`data.addresses.main`	`string \| null`	required. Derived from the competitor’s `primary_url`
`data.addresses.apexes`	`string[]`	required. Whole domains. Their subdomains are included
`data.addresses.sections`	`string[]`	required. Host or host/path claims on a site not otherwise theirs
`request_id`	`string`	required. Also returned as the `x-request-id` header

The full resulting set is returned, not just what you added, so you never need a follow-up read to see where the competitor now stands.

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

Subdomains are included, country domains are not. Adding example.com also counts docs.example.com and eu.example.com. It does not count example.de, which is a separate registrable domain and needs adding on its own.

Sections are for sites you do not own outright. example.com/product claims only that path and the pages under it, leaving the rest of example.com as an ordinary third-party source. Use it when a competitor has a presence on a shared platform rather than their own site.

Adding is idempotent in effect. An address already present stays present; the stored set is deduplicated, so re-adding is harmless.

Read the current set with Get competitor, which returns the same domains object.

Idempotency-Key is required. See Idempotency.