Heading API Reference

Programmatic access to properties, prompts, competitors, and visibility data. Authenticate with API keys, get JSON responses.

Base URL

https://api.useheading.com/v1

Authentication

All requests require an API key passed as a Bearer token in the Authorization header.

Create API keys from Settings > API in the Heading dashboard. Keys use the hdg_sk_live_ prefix.

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

API keys are shown once at creation and cannot be retrieved later. Store them securely.

Access levels

DELETE operations are not available via the API. Use the dashboard to delete resources.

Property scoping

Keys can be scoped to specific properties or granted access to all properties on the team. Scoped keys only return data for their allowed properties.

Resources

Response format

All responses return JSON with a consistent structure.

Success

{
  "data": [...],
  "total": 5
}

Error

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Authorization header is required"
  }
}

Status codes

Rate limits

• 100 requests/min per API key
• Rate-limited responses include a Retry-After header (seconds until reset)
• X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers are included on all responses