GraphQL API Documentation

Overview

A single GraphQL endpoint that mirrors the core REST resources so callers can fetch exactly the fields they need in one round trip. Authentication, authorization, and the underlying Searchkick services are shared with the REST API, so a GraphQL query returns the same records the equivalent REST call would.

Endpoint

API Playground

Build and run GraphQL queries against your account in the browser. Requests use your API key when signed in. Sign in to enable live testing with your API key.

Authentication

GraphQL uses the same credentials and rate-limits as the REST API. Send your key on every request:

curl -X POST https://app.hienergy.ai/api/v1/graphql \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: $ROCKET_API_KEY" \
  -d '{"query":"{ __typename }"}'

Missing or invalid credentials return 401 Unauthorized in the standard REST error envelope ({ error: { code, message, … } }) rather than the GraphQL errors array, so existing tooling that branches on HTTP status keeps working.

What's exposed

Run an __schema introspection query (or the "Schema introspection" example in the playground) for the full field/argument list. The core surface:

Single-record lookups

• advertiser(id, slug)
• deal(id)
• transaction(id)
• publisher(id, slug)
• network(id, slug)
• tag(id, slug)

Paginated lists

All list fields return { nodes, pageInfo }. pageInfo always carries currentPage, perPage, nextPage, prevPage, and hasNextPage. totalCount / totalPages are only populated when includeTotal: true is requested (capped at 100,000).

• advertisers(publisherId, networkId, status, query, …) — Searchkick-backed
• deals(advertiserId, exclusive, featured, activeOn, …)
• transactions(advertiserId, publisherId, networkId, startDate, endDate, …) — Searchkick-backed
• clicks(startDate!, endDate!, publisherId, advertiserId, …) — Searchkick-backed, 90-day window
• publishers(query, …)
• networks(active, …)
• tags(query, …)

Pagination & totals

Every list field accepts page, perPage, and includeTotal:

• page defaults to 1.
• perPage defaults to 25, clamped at 200.
• includeTotal: true returns pageInfo.totalCount / totalPages. Off by default — counting on huge tables is slow.
• pageInfo.hasNextPage is always populated (using the standard n+1 trick).
• Hard cap: page * perPage must be ≤ 10,000. Use filters (date range, IDs) instead of deep paging.

Examples

1) Search advertisers by name with totals

curl -X POST https://app.hienergy.ai/api/v1/graphql \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: $ROCKET_API_KEY" \
  -d '{
    "query": "query($q: String) { advertisers(query: $q, perPage: 5, includeTotal: true) { nodes { id name domain network { name } } pageInfo { hasNextPage totalCount } } }",
    "variables": { "q": "nike" }
  }'

2) Transactions for a date range

curl -X POST https://app.hienergy.ai/api/v1/graphql \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: $ROCKET_API_KEY" \
  -d '{
    "query": "query($from: IsoDate!, $to: IsoDate!) { transactions(startDate: $from, endDate: $to, perPage: 25) { nodes { id transactionDate saleAmount commissionAmount advertiser { id name } } pageInfo { hasNextPage } } }",
    "variables": { "from": "2026-04-01", "to": "2026-04-30" }
  }'

3) Clicks for a 7-day window

curl -X POST https://app.hienergy.ai/api/v1/graphql \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: $ROCKET_API_KEY" \
  -d '{
    "query": "query($from: IsoDate!, $to: IsoDate!) { clicks(startDate: $from, endDate: $to, perPage: 50) { nodes { clickDate clickCount advertiserName networkName } pageInfo { hasNextPage } } }",
    "variables": { "from": "2026-05-19", "to": "2026-05-26" }
  }'

Errors & limits

• Auth failures return 401 in the REST error envelope.
• Validation / business errors (bad date range, depth exceeded, search unavailable, etc.) come back in the GraphQL errors array with HTTP 200 — standard GraphQL convention.
• Query depth is capped at 12.
• Query complexity is capped at 5,000.
• Pagination depth (page * perPage) is capped at 10,000.
• Reported totals are capped at 100,000 to keep counts bounded.
• Clicks date range is required and limited to 90 days.