Heading API Reference

The competitors API returns brands you're tracking alongside your own in AI search responses. Competitors belong to the team and can optionally be linked to a specific property.

List Competitors

GET /v1/competitors

Returns competitors for the authenticated key's team. Ordered by creation date, newest first.

Keys with all properties access return every competitor on the team
Scoped keys return team-wide competitors (no property link) plus competitors linked to their authorised properties

Headers

Header	Value	Required
`Authorization`	`Bearer hdg_sk_live_...`	Yes

Example

curl https://api.useheading.com/v1/competitors \
  -H "Authorization: Bearer hdg_sk_live_abc123..."

Response — `200 OK`

{
  "data": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "displayName": "Competitor A",
      "trackedName": "competitor-a",
      "domains": ["competitor-a.com", "competitor-a.co.uk"],
      "propertyId": null,
      "createdAt": "2026-03-01T00:00:00.000Z",
      "updatedAt": "2026-03-20T14:30:00.000Z"
    },
    {
      "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "displayName": "Niche Rival",
      "trackedName": "niche-rival",
      "domains": ["nicherival.com"],
      "propertyId": "f1e2d3c4-b5a6-7890-abcd-ef1234567890",
      "createdAt": "2026-03-10T00:00:00.000Z",
      "updatedAt": "2026-03-18T09:15:00.000Z"
    }
  ],
  "total": 2
}

Response fields

Field	Type	Description
`id`	string	Competitor UUID
`displayName`	string	Human-readable name
`trackedName`	string	Internal tracking identifier
`domains`	string[]	Domains associated with this competitor
`propertyId`	string or null	Linked property UUID, or `null` for team-wide competitors
`createdAt`	string	ISO 8601 creation timestamp
`updatedAt`	string	ISO 8601 last update timestamp

Error responses

Status	Code	When
`401`	`MISSING_AUTH`	No Authorization header
`401`	`INVALID_KEY`	Invalid or revoked API key
`429`	`rate_limit_exceeded`	Rate limit exceeded (100 req/min)
`500`	`INTERNAL_ERROR`	Server error

Competitors