API Documentation

Access your CiteHawk data programmatically. All endpoints use REST conventions and return JSON.

Authentication

All API requests require an API key passed in the Authorization header.

Authorization: Bearer YOUR_API_KEY

Generate API keys in Settings > API Keys within your workspace.

All requests without a valid API key return 401 Unauthorized.

Base URL

https://citehawk.com/api/v1

Endpoints

GET/api/v1/brands

Returns all brands in your workspace.

Example request

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://citehawk.com/api/v1/brands

Example response

{
  "brands": [
    {
      "id": "abc123",
      "name": "Acme Corp",
      "keywords": ["acme", "acme corporation"]
    }
  ],
  "workspaceId": "ws_123"
}

GET/api/v1/metrics

Returns daily visibility metrics and latest KPIs for your workspace.

Example request

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://citehawk.com/api/v1/metrics?days=7"

Example response

{
  "timeseries": [
    {
      "date": "2026-04-20",
      "visibilityScore": 72,
      "citationCount": 15
    }
  ],
  "kpis": {
    "visibilityScore": 72,
    "citationCount": 145,
    "responseCount": 892
  },
  "days": 7
}

GET/api/v1/responses

Returns recent AI platform responses mentioning your brands.

Example request

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://citehawk.com/api/v1/responses?limit=10&offset=0"

Example response

{
  "responses": [
    {
      "id": "resp_123",
      "provider": "chatgpt",
      "model": "gpt-4o",
      "responseText": "According to Acme Corp...",
      "citations": ["https://acme.com/about"]
    }
  ],
  "total": 892
}

Rate Limits

API requests are rate-limited to ensure fair usage. If you exceed the limit, you will receive a 429 Too Many Requests response.

Error Codes