API reference - v1

The Hookology API

Pull reconciled performance data and push creatives straight into your workspace. Every request is scoped to the workspace that owns the key, so you can never read another workspace's data.

Workspace keys

Create keys in Settings > Integrations. Shown once, stored hashed.

Scoped by design

Keys resolve to one workspace. Revoke instantly at any time.

Plain REST + JSON

No SDK needed. Bearer token auth, JSON in, JSON out.

Authentication

Send your key as a bearer token on every request. An X-API-Key header works too. Missing or revoked keys return 401.

Authorization: Bearer hk_live_xxxxxxxxxxxxxxxxxxxxxxxx

Base URL: https://hookology.ai

Endpoints

GET/api/public/v1/me

Confirm the key and list the clients it can see

Returns the workspace the key belongs to plus every client inside it. Use this to verify a key works.

Request

curl https://hookology.ai/api/public/v1/me \
  -H "Authorization: Bearer hk_live_your_key"

Response

{
  "workspace": { "id": "…", "name": "Acme Group", "created_at": "2026-01-04T09:12:00Z" },
  "clients": [ { "id": "…", "name": "Acme Retail" } ]
}

GET/api/public/v1/performance

Reconciled spend, revenue and efficiency

Query parameters: from and to (YYYY-MM-DD, defaults to the last 30 days), platform (optional filter) and group_by (day, platform or total).

Request

curl "https://hookology.ai/api/public/v1/performance?from=2026-07-01&to=2026-07-31&group_by=platform" \
  -H "Authorization: Bearer hk_live_your_key"

Response

{
  "from": "2026-07-01",
  "to": "2026-07-31",
  "group_by": "platform",
  "results": [
    { "key": "meta", "spend": 18240.5, "revenue": 71180.2, "clicks": 40210,
      "impressions": 1840322, "conversions": 1204, "roas": 3.902 }
  ]
}

GET/api/public/v1/creatives

List creatives in the workspace

Query parameters: limit (1-200, default 50) and platform (optional filter). Newest first.

Request

curl "https://hookology.ai/api/public/v1/creatives?limit=25" \
  -H "Authorization: Bearer hk_live_your_key"

Response

{
  "results": [
    { "id": "…", "name": "Summer hero 9x16", "platform": "meta",
      "format": "video", "campaign": "Summer sale", "asset_url": "https://…",
      "created_at": "2026-07-14T10:02:11Z" }
  ]
}

POST/api/public/v1/creatives

Push a creative into Hookology

Body fields: name and platform and format are required; asset_url, campaign and notes are optional. Creatives arrive tagged with source "api".

Request

curl -X POST https://hookology.ai/api/public/v1/creatives \
  -H "Authorization: Bearer hk_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Autumn hero 9x16",
    "platform": "meta",
    "format": "video",
    "asset_url": "https://cdn.example.com/autumn.mp4",
    "campaign": "Autumn launch"
  }'

Response

{
  "creative": { "id": "…", "name": "Autumn hero 9x16", "platform": "meta",
    "format": "video", "created_at": "2026-08-16T21:40:02Z" }
}

Errors

400	The query or body failed validation. The message names the problem field.
401	The key is missing, malformed or revoked.
500	Hookology could not load the data. Retry with backoff.

Ready to create a key?

Settings > Integrations inside your workspace.

Open API settings