ScriptHooks API Documentation

Overview

The ScriptHooks API gives you programmatic access to our curated database of viral video hooks. Each hook is tagged with metadata including archetype, emotional trigger, niche, and performance data.

Base URL

https://scripthooks.ai/api/hookdata

What's Included

The hook text (exact wording from viral videos)
View count from source video
Platform (TikTok, YouTube, Reels, etc.)
Archetype classification (curiosity gap, bold claim, etc.)
Emotional trigger (fear, aspiration, surprise, etc.)
Niche/vertical category

Authentication

All API requests require authentication via an API key. Include your key in the request header:

                        Header
                        Authorization: Bearer YOUR_API_KEY
                    

Keep your API key secret.

Do not expose it in client-side code or public repositories.

Getting an API Key

Contact wes@scripthooks.ai to get your API key. Include your use case and expected call volume.

Already have an API key? View your dashboard to manage usage and regenerate keys.

Request API Access API Dashboard

Pricing

Simple, predictable pricing based on your usage needs.

Starter

$29 /month

1,000 API calls

All endpoints
Full hook metadata
Email support

Popular

Growth

$99 /month

10,000 API calls

All endpoints
Full hook metadata
Priority support
Trend data access

Scale

$299 /month

100,000 API calls

All endpoints
Full hook metadata
Dedicated support
Trend data access
Bulk export

Enterprise

Custom

1,000,000+ API calls

99.9% uptime SLA
Webhook access
Full bulk export
Dedicated support

Endpoints

GET /hooks Popular

Retrieve viral hooks from the database with filtering and pagination.

Request

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://scripthooks.ai/api/hookdata/hooks

GET /hooks/search

Search hooks by niche, emotion, archetype, or keyword.

Request

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://scripthooks.ai/api/hookdata/hooks/search?q=nobody%20knows"

GET /hooks/random

Get random viral hooks for inspiration.

Request

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://scripthooks.ai/api/hookdata/hooks/random?count=5"

GET /hooks/full

Get complete hook data with metadata.

Request

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://scripthooks.ai/api/hookdata/hooks/full

GET /archetypes

List all hook archetypes with descriptions and examples.

Request

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://scripthooks.ai/api/hookdata/archetypes

GET /meta

Get API metadata and statistics.

Request

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://scripthooks.ai/api/hookdata/meta

GET /trends New

Access trending hook patterns and rising archetypes.

Request

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://scripthooks.ai/api/hookdata/trends?period=30d"

Rate Limits

Free Tier

100

requests/day

Pro Tier

10,000

requests/day

Enterprise

Unlimited

custom limits

Webhooks Enterprise

Receive real-time notifications when new hooks are added to the database.

Setup

Configure your webhook endpoint in the API Dashboard or contact support.

                        POST https://your-app.com/webhooks/scripthooks
Content-Type: application/json
X-ScriptHooks-Signature: sha256=...
                    

Payload

{
  "event": "hooks.new",
  "timestamp": "2026-01-15T08:00:00Z",
  "data": {
    "count": 47,
    "hooks": [
      {
        "id": "hook_98765",
        "text": "Nobody talks about this satisfying...",
        "views": 1250000,
        "platform": "TikTok",
        "archetype": "curiosity_gap",
        "emotional_trigger": "curiosity",
        "niche": "lifestyle"
      }
    ]
  }
}

Filtering

Only receive hooks matching your criteria:

{
  "webhook_url": "https://your-app.com/webhooks/scripthooks",
  "filters": {
    "niche": ["finance", "business"],
    "min_views": 500000,
    "archetype": ["curiosity_gap", "bold_claim"]
  }
}

Retry Policy

Failed deliveries (non-2xx response) are retried:

1st retry: 1 minute
2nd retry: 5 minutes
3rd retry: 30 minutes
4th retry: 2 hours

After 4 failures, the webhook is paused and you'll receive an email notification.

Bulk Export Scale+

Download the complete dataset or filtered subsets for offline use.

Request Export

POST /export
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "format": "jsonl",
  "filters": {
    "niche": ["finance"],
    "min_views": 100000
  }
}

Response

{
  "export_id": "exp_abc123",
  "status": "processing",
  "estimated_records": 892,
  "download_url": null
}

Check Status

GET /export/exp_abc123

When complete:

{
  "export_id": "exp_abc123",
  "status": "complete",
  "records": 892,
  "format": "jsonl",
  "size_bytes": 1248576,
  "download_url": "https://scripthooks.ai/exports/exp_abc123.jsonl",
  "expires_at": "2026-01-22T12:00:00Z"
}

Formats

Format	Extension	Use Case
JSON	.json	Single array, easy parsing
JSONL	.jsonl	Streaming, large datasets, BigQuery
CSV	.csv	Spreadsheets, SQL import

Limits

Scale plan: 1 export per day, up to 10,000 records
Enterprise: Unlimited exports, full database access

Response Schema

All successful responses return JSON with the following structure:

{
  "success": true,
  "data": [
    {
      "id": "hook_12345",
      "text": "POV: You finally understand...",
      "views": 2400000,
      "platform": "TikTok",
      "archetype": "curiosity_gap",
      "emotional_trigger": "surprise",
      "niche": "finance"
    }
  ],
  "count": 1,
  "timestamp": "2026-01-14T12:00:00Z"
}

Error Codes

401 Unauthorized

Invalid or missing API key

429 Rate Limit Exceeded

Too many requests - upgrade your plan or wait

404 Not Found

Endpoint or resource doesn't exist

500 Server Error

Something went wrong on our end

Code Examples

Quick examples to get you started in your language of choice.

Python

import requests

API_KEY = "your_api_key"
BASE_URL = "https://scripthooks.ai/api/hookdata"

def get_hooks(niche=None, archetype=None, limit=20):
    headers = {"Authorization": f"Bearer {API_KEY}"}
    params = {"limit": limit}

    if niche:
        params["niche"] = niche
    if archetype:
        params["archetype"] = archetype

    response = requests.get(
        f"{BASE_URL}/hooks",
        headers=headers,
        params=params
    )
    return response.json()

# Get curiosity gap hooks for finance
hooks = get_hooks(niche="finance", archetype="curiosity_gap")

for hook in hooks["data"]:
    print(f"{hook['text']} - {hook['views']:,} views")

JavaScript

const API_KEY = 'your_api_key';
const BASE_URL = 'https://scripthooks.ai/api/hookdata';

async function getHooks({ niche, archetype, limit = 20 } = {}) {
  const params = new URLSearchParams({ limit });

  if (niche) params.append('niche', niche);
  if (archetype) params.append('archetype', archetype);

  const response = await fetch(
    `${BASE_URL}/hooks?${params}`,
    {
      headers: {
        'Authorization': `Bearer ${API_KEY}`
      }
    }
  );

  return response.json();
}

// Get curiosity gap hooks for finance
const hooks = await getHooks({
  niche: 'finance',
  archetype: 'curiosity_gap'
});

hooks.data.forEach(hook => {
  console.log(`${hook.text} - ${hook.views.toLocaleString()} views`);
});

cURL

Bash

curl -X GET "https://scripthooks.ai/api/hookdata/hooks?niche=finance&archetype=curiosity_gap&limit=20" \
  -H "Authorization: Bearer YOUR_API_KEY"