Heading API Reference

Prompts are the questions sent to AI platforms to monitor your brand's visibility. Each prompt is linked to a property and optionally categorised by topic.

List Prompts

GET /v1/prompts

Returns active monitoring prompts scoped to the API key's allowed properties. Ordered by creation date, newest first.

Keys with all properties access return prompts across every property on the team
Scoped keys return only prompts for their authorised properties

Headers

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

Example

curl https://api.useheading.com/v1/prompts \
  -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?",
      "category": "SEO Tools",
      "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	Canonical prompt UUID
`text`	string	The prompt text sent to AI platforms
`category`	string or null	Topic category (e.g. "SEO Tools", "Brand Comparison")
`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
`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

Prompts