Heading API reference

Programmatic access to properties, prompts, visibility, AI responses, competitors, sources, and tasks. 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

The API is currently read-only: every endpoint is GET. Both key access levels are accepted:

Data access

The API returns data for properties on a paid plan (Starter, Growth, or Scale). Free properties do not appear in any endpoint, including /v1/properties.

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. Filtering by a propertyId outside the key's scope returns an empty list, not an error.

Resources

Pagination

List endpoints accept limit and offset:

• limit: integer. Maximum results per page. Default: 100, max: 1000.
• offset: integer. Rows to skip. Default: 0.

total in the response is the full match count, independent of pagination.

Date ranges

Time-series endpoints (/v1/visibility, /v1/responses, /v1/sources, /v1/sources/urls) accept from and to as UTC calendar days (yyyy-MM-dd). Both bounds are inclusive. Default range: the last 30 UTC days. All dates in responses are UTC.

Response format

All responses return JSON with a consistent structure.

Success: list

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

Success: detail

{
  "data": { ... }
}

Error

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

Every error, including 429, uses this envelope.

Status codes

Error codes

Rate limits

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