Update competitor

Edits a tracked competitor. Every field is optional: omit one and it is left alone. Send only what you are changing.

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


PATCH /v1/brands/{brand_id}/competitors/{competitor_id}

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.

Any parameter you pass returns 400 invalid_request naming the offending key.

Body

application/json. At least one field is required.

Field	Type	Required	Description
`name`	`string`, 1–200 chars	optional
`primary_url`	`string`, up to 2048 chars	optional	`http` or `https`, pointing at a domain. Cannot be cleared
`aliases`	`string[]`, up to 50	optional	Replaces the existing aliases outright. Send the full list
`relation`	`string`	optional	One of `direct_competitor`, `indirect_competitor`, `partner`
`is_active`	`boolean`	optional	Set `false` to stop tracking without losing history
`match_case_sensitive`	`boolean`	optional
`match_require_domain`	`boolean`	optional

Request

cURL


curl --request PATCH \
  --url 'https://api.askylabs.com/v1/brands/242546de-4cee-4a7d-952e-f6aa60c63ef8/competitors/c4a7e1b2-38d9-4f60-b5ac-2d90e7f14b83' \
  --header 'Authorization: Bearer <api-key>' \
  --header 'Idempotency-Key: <unique-per-attempt>' \
  --header 'Content-Type: application/json' \
  --data '{"relation":"indirect_competitor","aliases":["Try Profound","Profound AI"]}'

Python


import requests
 
url = "https://api.askylabs.com/v1/brands/242546de-4cee-4a7d-952e-f6aa60c63ef8/competitors/c4a7e1b2-38d9-4f60-b5ac-2d90e7f14b83"
headers = {"Authorization": "Bearer <api-key>", "Idempotency-Key": "<unique-per-attempt>"}
payload = {"relation": "indirect_competitor", "aliases": ["Try Profound", "Profound AI"]}
 
response = requests.patch(url, json=payload, headers=headers)
print(response.text)

JavaScript


const options = {
  method: 'PATCH',
  headers: {Authorization: 'Bearer <api-key>', 'Idempotency-Key': '<unique-per-attempt>', 'Content-Type': 'application/json'},
  body: JSON.stringify({relation: 'indirect_competitor', aliases: ['Try Profound', 'Profound AI']})
};
 
fetch('https://api.askylabs.com/v1/brands/242546de-4cee-4a7d-952e-f6aa60c63ef8/competitors/c4a7e1b2-38d9-4f60-b5ac-2d90e7f14b83', options)
  .then(res => res.json()).then(res => console.log(res)).catch(err => console.error(err));

Response

200


{
  "data": {
    "competitor": {
      "id": "c4a7e1b2-38d9-4f60-b5ac-2d90e7f14b83",
      "name": "Profound",
      "primary_url": "https://tryprofound.com",
      "domain": "tryprofound.com",
      "relation": "indirect_competitor",
      "aliases": ["Try Profound", "Profound AI"],
      "is_active": true,
      "is_manual": true,
      "match_case_sensitive": false,
      "match_require_domain": false,
      "match_mode": "apex"
    }
  },
  "request_id": "req_8a03c7de51b94f26d1ac"
}

400


{
  "error": {
    "code": "invalid_request",
    "message": "Provide at least one field to update: name, primary_url, aliases, relation, is_active, match_case_sensitive, match_require_domain.",
    "request_id": "req_2c95e0af38d14b70a6cf"
  }
}

403


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

404


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

Response fields

Identical to Create competitor. The full competitor is returned, read back after the write, not just the fields you changed.

Errors

Status	Code	When
400	`invalid_request`	Unknown field, no fields at all, a URL that is not `http`/`https` or does not point at a domain, an unknown `relation`, or more than 50 aliases
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

aliases replaces, it does not merge. Send the aliases you want the competitor to end up with. Sending [] removes them all. Read the current list from Get competitor first if you are adding to it.

primary_url cannot be cleared. There is no null for it here: a manually added competitor is required to have one, and every competitor this API can create is manually added.

Changing primary_url moves attribution. domain is re-derived on every URL change, so citations attributed to the old domain stop counting and the new domain starts. Read the returned domain to confirm what the competitor now claims. A null means another competitor on this brand already holds that domain.

Deactivating is not deleting, and deactivating is usually what you want. is_active: false stops the competitor being tracked going forward and keeps all of its history, so your past visibility and share-of-voice numbers stay comparable.

There is no delete endpoint yet. Deleting a competitor removes every measurement ever recorded against it, which for an established competitor is tens of thousands of rows, and it changes historical share of voice for the others, since share is relative. We would rather ship that with a way to preview the damage first than without one, so it is not here yet. Deactivate instead unless you genuinely want the history gone.

Idempotency-Key is required. Reuse it when retrying an attempt and the original response is replayed rather than the write happening twice. See Idempotency.