Heading API reference

Prompts are the questions sent to AI platforms to monitor your brand's visibility. Each prompt belongs to a property and carries that property's tags.

List prompts

GET /v1/prompts

Returns active monitoring prompts for paid properties in the API key's scope. Ordered by creation date, newest first.

Headers

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

Query parameters

Parameter	Type	Description
`propertyId`	string	Return prompts for one property only.
`limit`	integer	Maximum results per page. Default: 100, max: 1000.
`offset`	integer	Rows to skip. Default: 0.

Example

curl "https://api.useheading.com/v1/prompts?propertyId=f1e2d3c4-b5a6-7890-abcd-ef1234567890" \
  -H "Authorization: Bearer hdg_sk_live_abc123..."

Response: `200 OK`

{
  "data": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "text": "What is the best SEO tool for enterprise?",
      "tags": [
        {
          "id": "c9d8e7f6-a5b4-3210-abcd-ef1234567890",
          "name": "Comparison",
          "color": "#4F46E5"
        }
      ],
      "qualityScore": 85,
      "property": {
        "id": "f1e2d3c4-b5a6-7890-abcd-ef1234567890",
        "name": "Acme Corp"
      },
      "createdAt": "2026-03-15T00:00:00.000Z"
    }
  ],
  "total": 1
}

Response fields

Field	Type	Description
`id`	string	Prompt UUID. Matches `promptId` on `/v1/visibility` and `/v1/responses`.
`text`	string	The prompt text sent to AI platforms
`tags`	object[]	Tags on this prompt
`tags[].id`	string	Tag UUID
`tags[].name`	string	Tag name
`tags[].color`	string or null	Tag colour (hex)
`qualityScore`	number or null	Prompt quality score (0-100)
`property`	object	The property this prompt monitors
`property.id`	string	Property UUID
`property.name`	string	Property display name
`createdAt`	string	ISO 8601 creation timestamp

Error responses

Status	Code	When
`400`	`INVALID_PARAM`	Invalid query parameter
`401`	`MISSING_AUTH`	No Authorization header
`401`	`INVALID_AUTH`	Header is not `Bearer {key}`
`401`	`INVALID_KEY`	Invalid or revoked API key
`429`	`RATE_LIMIT_EXCEEDED`	Rate limit exceeded (100 req/min)
`500`	`INTERNAL_ERROR`	Server error

Prompts