REST API | Build with GetHookd Ad Intelligence

Get Started with the REST API

Authenticate with a bearer token and start querying ads and brands programmatically in under five minutes.

1

Generate an API Token

Sign in to your GetHookd account, go to Settings → API Tokens, and click Generate API Key. Choose the scopes your integration needs - you can select multiple. Tokens can be revoked at any time. Public API access requires a paid plan.

explore:read brand-spy:read brand-spy:write swipe-file:read swipe-file:write boards:read *:read
2

Authenticate Your First Request

All API requests use bearer token authentication. Pass your token in the Authorization header. The base URL is https://app.gethookd.com/api/v1.

curl

curl -sS \ -H "Authorization: Bearer <YOUR_API_TOKEN>" \ -H "Accept: application/json" \ "https://app.gethookd.com/api/v1/explore?query=dropshipping&limit=5"
3

Use the API from JavaScript or Python

You can call the API from any language. Here are quick-start examples for the two most common environments.

JavaScript (fetch)

const response = await fetch( 'https://app.gethookd.com/api/v1/explore?query=dropshipping&limit=5', { headers: { 'Authorization': 'Bearer <YOUR_API_TOKEN>', 'Accept': 'application/json', }, } ); const { data } = await response.json(); console.log(data); // array of ad objects

Python (requests)

import requests resp = requests.get( "https://app.gethookd.com/api/v1/explore", params={"query": "dropshipping", "limit": 5}, headers={"Authorization": "Bearer <YOUR_API_TOKEN>"}, ) resp.raise_for_status() ads = resp.json()["data"] print(ads)
4

Explore the Full API Reference

The interactive API reference documents every endpoint, parameter, and response shape - including the explore search, brand spy endpoints, and swipe-file management. Deep-link to specific tags for the area you're integrating with.

View Full API Reference

Frequently Asked Questions About the GetHookd REST API

What endpoints are available?

The public API covers ad exploration (GET /api/v1/explore, GET /api/v1/ads/{id}), brand intelligence (GET /api/v1/brands, GET /api/v1/brands/{id}), brand spy tracking (GET /api/v1/brandspy, GET /api/v1/brandspy/{id}, GET /api/v1/brandspy/{id}/top-ads), and swipe-file management (boards, collections, briefs). The full interactive reference with every parameter and response schema is available at the public API docs.

Where do I get my API key?

Sign in to your GetHookd account and go to Settings → API Tokens. Click Generate API Key, select the scopes you need, and copy the token. Tokens are shown once at creation - save it somewhere secure immediately. You can generate multiple tokens (e.g. one per integration) and revoke any of them at any time without affecting the others.

Is there a rate limit?

Yes. Each token has a per-token rate limit enforced on a sliding window. If you exceed it, the API returns 429 Too Many Requests. Back off briefly and retry - the window resets automatically. The exact ceiling depends on your plan; check the API response headers (X-RateLimit-Limit, X-RateLimit-Remaining) to track your usage in real time.

What plan do I need to use the API?

Public API access is available on paid plans via the public_api feature flag. See our Pricing page for details on which tier includes API access. Once unlocked, you can generate as many tokens as you need, each with its own scope selection.

Is there a webhook system?

Not yet. The current API is a read-focused REST interface. Webhook support for events like new brand ad activity or swipe-file additions is on the roadmap. In the meantime, you can poll the relevant endpoints on a schedule - the API is designed for high-frequency read access.

How does credit billing work for API calls?

Search and listing endpoints (explore, brand spy) consume credits proportional to the number of results returned. Lookup endpoints (individual ad, individual brand, top-ads) are free. Every charged response includes used_credits and remaining_credits in the JSON envelope so you can monitor consumption in real time. If your workspace runs out of credits before a request completes, you'll receive a 402 Insufficient credits response before any work runs.

Can I use the same token for the REST API and the MCP server?

Yes - one token works for both surfaces. The MCP server is a structured tool layer built on top of the same /api/v1/* endpoints. Generate one token with the scopes you need, and use it in both your REST API Authorization header and your Claude Desktop / Claude Code MCP config block. No separate MCP credential needed.

What format do API responses use?

All responses are JSON with a consistent envelope: { "errors": false, "data": [...], "meta": { "result_count": N } } for success, and { "errors": true, "message": "..." } for errors. Paginated endpoints include cursor-based pagination metadata. The full schema for every resource is documented in the interactive API reference.

API Access

Get Started with the REST API

Generate an API Token

Authenticate Your First Request

Use the API from JavaScript or Python

Explore the Full API Reference

Frequently Asked Questions About the GetHookd REST API