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

Update a competitor

scope write:competitors cost 1 RU idempotent optional

Curate a competitor entity: rename it, reclassify its category, set its website or label it with tags. Only the fields you send change. A category change also updates how past reports count it. Setting category to my_brand says the entity is the brand itself: its names become brand aliases, past reports are recalculated in the background and it leaves the directory.

Path parameters

Query parameters

  • dry_run boolean optional

    Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns 200 with a dry_run object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns 422.

    default: false

Header parameters

  • Idempotency-Key string optional

    Optional. A retry with the same key and body within 24 hours replays the first response.

Request body

application/json required
Type: CompetitorUpdate
  • category enum (nullable) nullable

    Reclassify the entity. One of direct_competitor, indirect_competitor, ai_platform, publisher, other, my_brand. A category change also updates how past reports count it. my_brand means the entity is the brand itself: its name and aliases become brand aliases, past reports count its mentions as the brand (visibility and rank are recalculated in the background) and it leaves the competitor directory, so later requests for this id answer not_found. Any name or website sent with it is ignored.

  • name string (nullable) nullable

    New canonical display name.

  • tags array of string (nullable) nullable

    Replace the entity's labels (up to 10, 40 characters each). Send [] to clear them.

  • website string (nullable) nullable

    Website URL for the entity. Send an empty string to clear it.

Responses

Updated a competitor application/json
Type: Competitor
  • brand_id string required

    Owning brand id (UUID).

  • created_at string required

    ISO-8601 timestamp when the entity was first registered.

    format: `date-time`

  • id string required

    Stable competitor identifier (UUID).

  • name string required

    Canonical display name of the entity.

  • updated_at string required

    ISO-8601 timestamp when the entity was last updated.

    format: `date-time`

  • aliases array of string

    Alternative names that resolve to this entity.

  • category enum (nullable) nullable

    Entity classification. One of direct_competitor, indirect_competitor, ai_platform, publisher, other, or my_brand.

  • domain string (nullable) nullable

    Bare domain (e.g. nike.com).

  • first_seen_at string (nullable) nullable

    ISO-8601 timestamp of the first report this entity appeared in.

    format: `date-time`

  • last_seen_at string (nullable) nullable

    ISO-8601 timestamp of the most recent report this entity appeared in.

    format: `date-time`

  • mention_count integer

    Total mentions across the brand's reports.

    min: 0 · default: `0`

  • object string

    Always competitor.

    default: `competitor`

  • reason string (nullable) nullable

    Short explanation of why this entity is classified as a competitor.

  • report_count integer

    Number of reports this entity appeared in.

    min: 0 · default: `0`

  • tags array of string

    Labels the team gave this entity.

  • website string (nullable) nullable

    Normalised website URL.

Example response 
{
  "aliases": [
    "Nike Running",
    "Nike Inc."
  ],
  "brand_id": "3f9c7e8a-1b6a-4d8e-92cf-7d9c8b1e2a04",
  "category": "direct_competitor",
  "created_at": "2026-01-05T09:00:00+00:00",
  "domain": "nike.com",
  "first_seen_at": "2026-01-05T09:00:00+00:00",
  "id": "018e7c2e-33ab-7df1-b1cd-2ac3a8f9112d",
  "last_seen_at": "2026-04-18T09:00:00+00:00",
  "mention_count": 42,
  "name": "Nike",
  "object": "competitor",
  "reason": "Sells running shoes to the same buyers.",
  "report_count": 7,
  "tags": [
    "Retail"
  ],
  "updated_at": "2026-04-18T09:00:00+00:00",
  "website": "https://www.nike.com"
}
Request validation failed application/json
Type: ApiError
  • error object required
    Show fields
    • code string required

      Stable machine-readable error code from the catalog.

    • message string required

      Human-readable description suitable for logging.

    • details object

      Optional, code-specific context (e.g. errors array for validation_error, retry_after for service_unavailable). Shape depends on error.code; treat as opaque otherwise.

      Show fields

      Empty object (no properties).

  • request_id string

    Server-generated correlation id for the request. Mirrors the X-Correlation-ID response header. Include this when contacting support.

    format: `uuid`

Example response 
{
  "error": {
    "code": "validation_error",
    "message": "Request validation failed"
  },
  "request_id": "9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"
}
Missing or invalid credentials application/json
Type: ApiError
  • error object required
    Show fields
    • code string required

      Stable machine-readable error code from the catalog.

    • message string required

      Human-readable description suitable for logging.

    • details object

      Optional, code-specific context (e.g. errors array for validation_error, retry_after for service_unavailable). Shape depends on error.code; treat as opaque otherwise.

      Show fields

      Empty object (no properties).

  • request_id string

    Server-generated correlation id for the request. Mirrors the X-Correlation-ID response header. Include this when contacting support.

    format: `uuid`

Example response 
{
  "error": {
    "code": "unauthorized",
    "message": "Missing or invalid credentials"
  },
  "request_id": "9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"
}
You do not have permission to access this resource application/json
Type: ApiError
  • error object required
    Show fields
    • code string required

      Stable machine-readable error code from the catalog.

    • message string required

      Human-readable description suitable for logging.

    • details object

      Optional, code-specific context (e.g. errors array for validation_error, retry_after for service_unavailable). Shape depends on error.code; treat as opaque otherwise.

      Show fields

      Empty object (no properties).

  • request_id string

    Server-generated correlation id for the request. Mirrors the X-Correlation-ID response header. Include this when contacting support.

    format: `uuid`

Example response 
{
  "error": {
    "code": "forbidden",
    "message": "You do not have permission to access this resource"
  },
  "request_id": "9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"
}
Resource not found application/json
Type: ApiError
  • error object required
    Show fields
    • code string required

      Stable machine-readable error code from the catalog.

    • message string required

      Human-readable description suitable for logging.

    • details object

      Optional, code-specific context (e.g. errors array for validation_error, retry_after for service_unavailable). Shape depends on error.code; treat as opaque otherwise.

      Show fields

      Empty object (no properties).

  • request_id string

    Server-generated correlation id for the request. Mirrors the X-Correlation-ID response header. Include this when contacting support.

    format: `uuid`

Example response 
{
  "error": {
    "code": "not_found",
    "message": "Resource not found"
  },
  "request_id": "9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"
}
Resource conflict application/json
Type: ApiError
  • error object required
    Show fields
    • code string required

      Stable machine-readable error code from the catalog.

    • message string required

      Human-readable description suitable for logging.

    • details object

      Optional, code-specific context (e.g. errors array for validation_error, retry_after for service_unavailable). Shape depends on error.code; treat as opaque otherwise.

      Show fields

      Empty object (no properties).

  • request_id string

    Server-generated correlation id for the request. Mirrors the X-Correlation-ID response header. Include this when contacting support.

    format: `uuid`

Example response 
{
  "error": {
    "code": "conflict",
    "message": "Resource conflict"
  },
  "request_id": "9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"
}
Request body did not match the expected schema application/json
Type: ApiError
  • error object required
    Show fields
    • code string required

      Stable machine-readable error code from the catalog.

    • message string required

      Human-readable description suitable for logging.

    • details object

      Optional, code-specific context (e.g. errors array for validation_error, retry_after for service_unavailable). Shape depends on error.code; treat as opaque otherwise.

      Show fields

      Empty object (no properties).

  • request_id string

    Server-generated correlation id for the request. Mirrors the X-Correlation-ID response header. Include this when contacting support.

    format: `uuid`

Example response 
{
  "error": {
    "code": "body_validation_error",
    "message": "Request body did not match the expected schema"
  },
  "request_id": "9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"
}
Per-minute rate limit exceeded application/json
Type: ApiError
  • error object required
    Show fields
    • code string required

      Stable machine-readable error code from the catalog.

    • message string required

      Human-readable description suitable for logging.

    • details object

      Optional, code-specific context (e.g. errors array for validation_error, retry_after for service_unavailable). Shape depends on error.code; treat as opaque otherwise.

      Show fields

      Empty object (no properties).

  • request_id string

    Server-generated correlation id for the request. Mirrors the X-Correlation-ID response header. Include this when contacting support.

    format: `uuid`

Example response 
{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Per-minute rate limit exceeded"
  },
  "request_id": "9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"
}
An unexpected error occurred application/json
Type: ApiError
  • error object required
    Show fields
    • code string required

      Stable machine-readable error code from the catalog.

    • message string required

      Human-readable description suitable for logging.

    • details object

      Optional, code-specific context (e.g. errors array for validation_error, retry_after for service_unavailable). Shape depends on error.code; treat as opaque otherwise.

      Show fields

      Empty object (no properties).

  • request_id string

    Server-generated correlation id for the request. Mirrors the X-Correlation-ID response header. Include this when contacting support.

    format: `uuid`

Example response 
{
  "error": {
    "code": "internal_error",
    "message": "An unexpected error occurred"
  },
  "request_id": "9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"
}
Service temporarily unavailable, please retry application/json
Type: ApiError
  • error object required
    Show fields
    • code string required

      Stable machine-readable error code from the catalog.

    • message string required

      Human-readable description suitable for logging.

    • details object

      Optional, code-specific context (e.g. errors array for validation_error, retry_after for service_unavailable). Shape depends on error.code; treat as opaque otherwise.

      Show fields

      Empty object (no properties).

  • request_id string

    Server-generated correlation id for the request. Mirrors the X-Correlation-ID response header. Include this when contacting support.

    format: `uuid`

Example response 
{
  "error": {
    "code": "service_unavailable",
    "message": "Service temporarily unavailable, please retry"
  },
  "request_id": "9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"
}