Signals API

What Signals is for

Signals endpoints tell an agent what to make before it pays for a render: proven hooks and current trends. They use the same API key as generation and are free reads (subject to the 60 requests/minute read limit).

Endpoints

GET /api/v1/x-hooks — proven X hookslive · free

High-performing real hooks mined from X, ranked for your topic. Query parameters: topic (string) and limit (1–25, default 5).

curl -s "https://api.reelsbuilder.ai/api/v1/x-hooks?topic=onboarding&limit=5" \
  -H "Authorization: Bearer $REELSBUILDER_API_KEY"

{
  "success": true,
  "data": {
    "hooks": [
      {
        "id": "...",
        "hook": "The fastest way to make better short-form videos is to stop starting from a blank page.",
        "format": "conflict",
        "score": 88,
        "relevance_score": 75,
        "virality_score": 91,
        "freshness_score": 80,
        "topics": ["short-form"],
        "niches": ["tech"],
        "source_url": "https://x.com/...",
        "metrics": { "likes": 1240, "reposts": 186, "replies": 74, "views": 83000 }
      }
    ]
  }
}

GET /api/v1/trending — trending topicslive · free

Current X trending topics from a server-side cache that is refreshed periodically. Query parameters: woeid (Where-On-Earth location id; US is 23424977), category (filter to a category such as tech or finance) and limit (up to 50, default 20).

curl -s "https://api.reelsbuilder.ai/api/v1/trending?category=tech&limit=20" \
  -H "Authorization: Bearer $REELSBUILDER_API_KEY"

{
  "success": true,
  "data": {
    "trends": [
      { "name": "...", "tweet_count": 48200, "category": "tech", "score": 74, "woeid": 23424977, "synced_at": "2026-10-06T12:00:00.000Z" }
    ],
    "source": "x_trends_cache",
    "note": "..."
  }
}

An empty trends array means the cache has no data for that filter yet.

GET /api/v1/brand-profile — not available yet

The schema is published in GET /api/v1/tools for agent discovery, but the endpoint returns 501 ENDPOINT_NOT_IMPLEMENTED. Generation endpoints already use your account's brand context automatically.

How the data composes with generation

const headers = { Authorization: `Bearer ${process.env.REELSBUILDER_API_KEY}` };
const base = "https://api.reelsbuilder.ai/api/v1";

// 1. Decide what to make (free reads)
const trends = (await (await fetch(`${base}/trending?category=tech&limit=10`, { headers })).json()).data.trends;
const hooks = (await (await fetch(`${base}/x-hooks?topic=${encodeURIComponent(trends[0].name)}&limit=5`, { headers })).json()).data.hooks;

// 2. Render with the best signal as input (paid)
const job = await fetch(`${base}/generate-and-post`, {
  method: "POST",
  headers: { ...headers, "Content-Type": "application/json", "Idempotency-Key": crypto.randomUUID() },
  body: JSON.stringify({ prompt: `${hooks[0].hook} — ${trends[0].name}`, duration_target_sec: 15 }),
});

// 3. Poll the job, then hand the video to your publisher

The data calls are free. The render in step 2 is the only charge. See Stock Video API.

Where to go next

• Stock Video API — turn a signal into a video
• Quickstart
• Rate limits