🔗 Public API

The Gethookd Public API lets you pull ad intelligence, competitor tracking data, saved collections, and AI-generated creatives directly into your own dashboards, reports, or internal tools — no browser needed.

Whether you're building an internal analytics pipeline, syncing ad data to a spreadsheet, or automating your creative workflow, the API gives you programmatic access to the same features you use in the Gethookd app.

Before You Start

• Plan required: Grow or Scale (API Access is not available on the Launch plan)
• Credits: API calls cost 0.01 credits per item returned. Write operations (adding a brand, saving an ad) cost 0.01 credits each.
• Where to go: Log in to Gethookd → Integrations → API Access (or go directly to /connect)
• Base URL: https://app.gethookd.ai/api/v1/
• Interactive docs: Scalar API Reference — try endpoints live with your token

Step 1: Generate Your API Key

1. Go to Integrations > API Access
2. Select the scopes your token needs from the dropdown. You can pick individual scopes (like "Explore Read" or "Brand Spy Write") or use All Features (Read) or All Features (Full Access) for broader access.
3. Click Generate API Key
4. Your new token appears in the table — click the copy button to copy it to your clipboard
5. Important: Store your token securely. You can reveal and copy it again later, but treat it like a password.

You can generate multiple keys with different scopes and revoke any key at any time.

Step 2: Authenticate Your Requests

Every API request must include your token in the Authorization header:

Authorization: Bearer YOUR_API_TOKEN

Test your token by calling the auth check endpoint:

GET /api/v1/authcheck

A successful response looks like:

{
  "errors": false,
  "data": {
    "authenticated": true,
    "workspace": {
      "id": 123,
      "name": "Your Workspace"
    },
    "scopes": ["explore:read"]
  }
}

If you see "authenticated": true, you're good to go.

Endpoints

Explore — Search the Ad Library

Search and filter across 21M+ ads, just like the Explore page in the app.

GET /api/v1/explore

Scope required: explore:read

Query parameters:

Niche IDs: 1=Accessories, 2=Alcohol, 3=App/Software, 4=Automotive, 5=Beauty, 6=Book/Publishing, 7=Business/Professional, 8=Charity/NFP, 9=Info, 10=Entertainment, 11=Fashion, 12=Finance, 13=Food/Drink, 14=Games, 15=Government, 16=Health/Wellness, 17=Home/Garden, 18=Insurance, 19=Jewelry/Watches, 20=Kids/Baby, 21=Media/News, 22=Medical, 23=Pets, 24=Real Estate, 25=Service Business, 26=Sports/Outdoors, 27=Tech, 28=Travel, 29=Other, 30=Supplements

Creative Category IDs: 1=Before and After, 2=Testimonial/Reviews, 8=Promotion/Discount, 11=FAQ Explainers, 12=Holiday/Seasonal, 14=Humor/Fun, 16=Reasons Why, 17=Facts and Stats, 18=Features and Benefits, 19=Media and Press, 20=Us vs Them

Example request:

GET /api/v1/explore?query=skincare&platform=facebook&status=active&per_page=10&sort_column=days_active&sort_direction=desc

Example response:

{
  "errors": false,
  "data": [
    {
      "id": 123,
      "external_id": "9999999",
      "platform": "facebook, instagram",
      "display_format": "video",
      "title": "Great offer",
      "body": "...",
      "landing_page": "https://example.com",
      "cta_type": "SHOP_NOW",
      "cta_text": "Shop Now",
      "start_date": "2025-01-05",
      "end_date": null,
      "days_active": 21,
      "active_in_library": 1,
      "used_count": 4,
      "performance_score": 120,
      "performance_score_title": "Winning",
      "share_url": "https://app.gethookd.ai/share/ad/123...",
      "brand": {
        "external_id": "2016485295279615",
        "name": "Acme",
        "logo_url": "https://...",
        "active_ads": 109
      },
      "media": [
        {
          "type": "video",
          "url": "https://...",
          "thumbnail_url": "https://..."
        }
      ]
    }
  ],
  "used_credits": 0.10,
  "remaining_credits": 199.90,
  "sorting": { "column": "days_active", "direction": "desc" },
  "filters": { "platforms": ["facebook"] }
}

Brand Spy — Track Competitors

Monitor competitors' ad activity programmatically. List your spied brands, view their ads, add new brands, or remove them.

Scope required: brand-spy:read (for GET), brand-spy:write (for POST/DELETE)

List your spied brands

GET /api/v1/brandspy

Get a brand's ads

GET /api/v1/brandspy/{brand_id}

Returns the brand details plus a paginated list of their ads.

Add a brand to spy on

POST /api/v1/brandspy

Body (JSON):

{ "brand_id": 12345 }

Returns the newly spied brand. If the brand is already being spied on, you'll get a 409 Conflict.

Remove a spied brand

DELETE /api/v1/brandspy/{brand_id}

Swipe File — Saved Ads

Access your saved ads collection. List, save, and remove ads from your swipe file.

Scope required: swipe-file:read (for GET), swipe-file:write (for POST/DELETE)

List saved ads

GET /api/v1/swipefile

Save an ad

POST /api/v1/swipefile

Body (JSON):

{ "ad_id": 12345 }

Remove a saved ad

DELETE /api/v1/swipefile/{ad_id}

Boards — Organize Collections

Create and manage boards (folders) to organize ads into themed collections.

Scope required: boards:read (for GET), boards:write (for POST/PUT/DELETE)

List boards

GET /api/v1/boards

Create a board

POST /api/v1/boards

Body (JSON):

{ "name": "Q1 Winners", "description": "Top-performing ads from Q1" }

Get board details with ads

GET /api/v1/boards/{board_id}

Update a board

PUT /api/v1/boards/{board_id}

Body (JSON):

{ "name": "Updated Name", "description": "Updated description" }

Delete a board

DELETE /api/v1/boards/{board_id}

Add an ad to a board

POST /api/v1/boards/{board_id}/ads

Body (JSON):

{ "ad_id": 12345 }

Remove an ad from a board

DELETE /api/v1/boards/{board_id}/ads/{ad_id}

Clone Ads — AI Ad Generation

Generate AI-powered ad variations based on existing ads, list your generation history, and retrieve results.

Scope required: clone-ads:read (for GET), clone-ads:write (for POST)

List clone history

GET /api/v1/clone-ads

Generate cloned ad variations

POST /api/v1/clone-ads

Body (JSON):

{
  "ad_id": 12345,
  "prompt": "Make it more playful and summer-themed",
  "aspect_ratio": "Square",
  "variations_count": 3
}

Note: Generation is asynchronous. The response returns the job details immediately. Poll the detail endpoint to check when your images are ready.

Get clone details

GET /api/v1/clone-ads/{clone_id}

Returns the generation details including all generated image variations and their URLs.

Credits & Billing

• Cost: 0.01 credits per item returned (per ad, per brand, per board)
• When you're charged: Only when data is successfully returned. Empty results cost nothing.
• Write operations: Adding a brand to spy on, saving an ad, or creating a board also costs 0.01 credits each.
• Clone Ads generation: Costs 0.01 credits per variation requested.
• Every response includes used_credits and remaining_credits so you can track your balance.

If you run out of credits mid-request, you'll receive:

{
  "errors": true,
  "message": "Not enough credits",
  "data": {
    "feature": "public_api",
    "credits_needed": 0.16,
    "remaining_credits": "0.04",
    "feature_cost": 0.01
  }
}

Status code: 402 Payment Required

Rate Limits

To keep the API fast and fair for everyone, requests are limited per token:

Every response includes rate limit headers so you know where you stand:

If you exceed a limit, you'll get a 429 Too Many Requests response. Just wait for the Retry-After period and try again.

Scopes Reference

Scopes control what each API token can access. When generating a token, you choose which scopes to grant.

If a request requires a scope your token doesn't have, you'll get:

{
  "errors": true,
  "message": "Forbidden. Missing scope: brand-spy:read"
}

Status code: 403 Forbidden

Error Handling

All error responses follow the same format:

{
  "errors": true,
  "message": "Description of what went wrong"
}

Troubleshooting

"Unauthenticated" error

Make sure your Authorization header starts with `Bearer ` (with a space) followed by your full token. Double-check that the token hasn't been revoked.

"Not enough credits" on every request

Check your remaining credits on your plan dashboard. You can purchase credit add-on packs or upgrade your plan for more credits.

"Forbidden. Missing scope" error

Your token doesn't have the right permissions for this endpoint. Generate a new token with the required scope.

Empty results when filtering

Try broadening your filters. Remove one filter at a time to identify which one is too restrictive. Make sure date ranges and niche/category IDs are valid.

Rate limited (429 errors)

Slow down your request rate. Check the Retry-After header and wait that many seconds before retrying. Consider adding a small delay between requests in your code.

FAQs

Does using the API cost extra beyond my plan?

No extra subscription cost — API access is included with Grow and Scale plans. You pay with the same credits included in your plan. Each item returned costs 0.01 credits.

Can I use the API on the Launch plan?

No, API access is available on the Grow and Scale plans only. You can upgrade from your account settings.

How do I revoke a compromised token?

Go to Integrations > API Access, find the token in the table, and click Revoke. The token stops working immediately. Then generate a new one.

Can I create multiple API tokens?

Yes! You can generate as many tokens as you need — for example, one per integration or team member. Each can be revoked independently.

Is there a way to test the API without writing code?

Yes — use the interactive API docs where you can paste your token and try any endpoint directly in the browser.

What format are dates in?

All dates in requests and responses use YYYY-MM-DD format (e.g., 2025-06-15).

Related Articles

• Credits System Explained
• Plans Overview
• Brand Spy
• Clone Ads
• Swipe File

Updated on: 09/03/2026