HookPlaybook
Start free

Developers · REST API + MCP

Your X growth engine, inside your AI.

Ask Claude or ChatGPT what is going viral in your niche, how your week went, to draft your next posts in your voice and to fill your week. One API and one MCP server, in every plan. You choose what each key can do.

Get your API key Read the reference
  • Claude app
  • ChatGPT
  • Claude Code
  • Any MCP client
  • curl, any language
HookPlaybook connected

What went viral in my SaaS niche this week? Draft two posts in my voice from the best one.

list_viral_postsget_accountcreate_draft × 2

The best one this week got 14× its author's normal views, from an account your size. It opens with a number, then three short lines.

A founder in SaaS

2.1K followers

14.2× normal

Hook · a number or result   Format · a how-to list

Saved to your HookPlaybook Schedule

Draft 1 · your version of the patternNeeds your OK

Draft 2 · a thread of 3 postsNeeds your OK

An example: Claude with the HookPlaybook connector

18

endpoints, each one a tool for Claude and ChatGPT too

60/min

requests per key, with a clear 429 and Retry-After past it

$0

extra: in every plan, the free trial too

2

kinds of key: Draft only, or Draft and schedule

What you can build

Your account's data, wherever you already work.

CLAUDE · get_results
> How did my posts do this week?
# get_results { "days": 7 }

Ask Claude how your week went

Impressions, engagements, followers and your best post, against the week before, in plain words.

CLAUDE · list_viral_posts + create_draft
> Draft 3 posts like this week's best
# list_viral_posts { "niche": "saas" }
# create_draft × 3

Turn what is viral into drafts

Claude reads what works in your niche, for accounts your size, and writes your version of it.

CLAUDE · list_free_slots + schedule_post
> Fill my free times this week
# list_free_slots { "days": 7 }
# schedule_post × 4

Fill your week in one message

With a Draft and schedule key, Claude drafts, picks your free times and schedules. You see it all on the Schedule.

CLAUDE · list_mentions + get_person
> Who should I answer first?
# list_mentions { "sort": "top" }

Answer the replies that matter

Who replied to you, how you know them, and reply drafts in your voice for each. You send the one you like on X.

CRON · every Monday 9:00
0 9 * * 1  node weekly-report.js
# GET /api/v1/results?days=7

A Monday report, by itself

One request a week, into Slack, Notion or an email. Your numbers, where your team reads them.

YOUR APP · on deploy
curl -X POST $API/drafts -d '{"text": "v2.4 is out"}'
curl -X POST $API/posts/$ID/schedule

Drafts from what you ship

A release or a changelog entry becomes a draft, or, with a schedule key, a post at your next free time.

Ways in

Connected in a minute.

01No key to copy

The Claude app

Add a custom connector, press Connect, pick what Claude may do and approve on HookPlaybook.

  1. Settings › Connectors › Add custom connector
  2. Name it HookPlaybook and paste the URL
  3. Connect, pick what Claude may do, Approve
https://hookplaybook.com/api/v1/mcp
02Developer mode

ChatGPT

The same URL as a custom app. ChatGPT asks for its Developer mode, and what it allows depends on your ChatGPT plan.

  1. Settings › Apps & Connectors › Advanced › turn on Developer mode
  2. Back in Apps & Connectors, Create: name it HookPlaybook, paste the URL, pick OAuth
  3. Sign in on HookPlaybook, pick what ChatGPT may do, Approve
https://hookplaybook.com/api/v1/mcp
03One command

Claude Code

Make a key, run this once. Cursor, VS Code and any MCP client that sends a header work the same way.

Terminal
claude mcp add --transport http hookplaybook \
  https://hookplaybook.com/api/v1/mcp \
  --header "Authorization: Bearer YOUR_KEY"
04JSON over HTTPS

The REST API

For scripts, cron jobs and your own dashboards. Your key in one header.

Terminal
curl https://hookplaybook.com/api/v1/me \
  -H "Authorization: Bearer YOUR_KEY"

Keys are made in HookPlaybook: Settings menu › API and MCP. Up to 5 for each X account, each shown once.

Safe by design

You decide what a key is allowed to do.

Pick it when you make the key, or when you approve Claude or ChatGPT. Start with Draft only; make a second key the day you want your AI to fill your week too.

Draft only

Default

Reads everything and writes drafts. Every draft waits in your Schedule until you approve it in HookPlaybook.

  • Your account, posts, results, audience, viral posts, hooks, free times
  • Save, edit and delete drafts
  • Schedule, or change a scheduled post

Draft and schedule

You turn it on

Everything Draft only does, and it can approve a draft into your Schedule. It goes out at its time through HookPlaybook, with the same checks as a post you approve.

  • Everything Draft only can do
  • Schedule a draft, at a time or your next free one
  • Edit, unschedule or delete a scheduled post

Never anything else on X.

No key posts right away, replies, likes, follows, reposts or sends DMs. Posting always goes through your Schedule.

Your rules still apply.

Your weekly slots, your credits, a paused account and the check for two posts too alike: a schedule key gets the same answers you would.

Shown once. Revoked in one click.

We keep only a fingerprint of each key. Revoke it and it stops at once; each key shows when it was last used.

Reference

Everything the API does, on one page.

Base URL

https://hookplaybook.com/api/v1

Auth

Authorization: Bearer hp_live_…

Format

JSON in and out. Times are UTC, ISO 8601.

Headers

Every answer has X-RateLimit-Remaining. Send Idempotency-Key on a write so a retry never saves twice.

For agents: GET /api/v1/docs answers this whole reference as JSON, with no key.

Limits

Requests
60 a minute per key; X-RateLimit-Remaining on every answer, 429 with Retry-After past it
Drafts
100 a day per account (a refused draft takes no slot)
Scheduling
100 a day per account, and only what your credits pay for; they come back when a post is unscheduled
Keys
5 per account, made and revoked by its owner
MCP batches
10 messages a request; each tool call counts toward the 60
Retries
An Idempotency-Key seen in the last 24 hours gets the first answer back
Body size
256 KB

Errors

Every error is JSON with one message that says what to fix: {"error": "days must be one of: 7, 30, 90."}

400Bad requestA parameter or the body is wrong. The message says which, and what it may be.
401No key, or a wrong oneThe Authorization header is missing, or the key is wrong or was revoked.
402Credits or planNot enough credits to schedule it, or the free trial ended without a plan.
403Key can't do thatA Draft only key asked to schedule, or to change a scheduled post.
404Not foundNo such endpoint (the message lists them), or no such post in this account.
405Wrong methodFor example GET on /drafts. The message says what to use instead.
409Not nowThe post is already out, not scheduled, or changed while your request ran.
413 · 415BodyOver 256 KB, or not sent as Content-Type: application/json.
429Slow downOver 60 requests a minute, or 100 drafts or schedules today. Wait for Retry-After.
500Our sideSomething broke on our side and nothing was changed. Try again in a minute.

Account

Account

Who the key belongs to, what it may do, and your other X accounts.

GET/api/v1/meAny key · read

Your account: the plan, credits left and what a post costs in them, your X account, your niches and time zone, and what this key may do.

Parameters

none

The key names the account. Nothing in a request can point at another one.

Request
curl https://hookplaybook.com/api/v1/me \
  -H "Authorization: Bearer $HOOKPLAYBOOK_KEY"
Response200 OK
{
  "plan": { "id": "pro", "name": "Pro" },
  "creditsLeft": 640,
  "creditPrices": { "post": 5, "postWithLink": 50 },
  "x": { "handle": "you", "followers": 1240, "connected": true },
  "niches": ["saas", "seo"],
  "timezone": "America/New_York",
  "key": { "name": "Claude Code", "access": "schedule", "can": ["read", "draft", "schedule"] }
}
GET/api/v1/accountsAny key · read

Your X accounts (Pro has up to 5, Growth 10). Each is its own space, with its own voice, niches and Schedule, so a key belongs to one of them: this says which, and lists the others.

Parameters

none

To work on another account, make a key in that account's space.

Request
curl https://hookplaybook.com/api/v1/accounts \
  -H "Authorization: Bearer $HOOKPLAYBOOK_KEY"
Response200 OK
{
  "accounts": [
    { "handle": "you", "followers": 1240, "connected": true, "thisKey": true },
    { "handle": "yourproduct", "followers": 310, "connected": true, "thisKey": false }
  ]
}

Posts and drafts

Posts and drafts

Your Schedule: read it, add drafts, change them, delete them.

GET/api/v1/postsAny key · read

Your posts: drafts waiting for an OK, scheduled ones with their time, and posted ones with views, likes, replies and how they did against your normal.

Query parameters

status

optional

draft, scheduled or posted. Leave it out for all. Drafts newest first, scheduled soonest first, posted newest first.

from, to

optional · date

Only posts scheduled or posted in this range, like 2026-11-02.

limit

optional · 1–100

How many. 20 by default.

Request
curl "https://hookplaybook.com/api/v1/posts?status=scheduled&from=2026-11-02" \
  -H "Authorization: Bearer $HOOKPLAYBOOK_KEY"
Response200 OK
{
  "posts": [{
    "id": "01JBX7Q2MDV4H8C3N5P9R2K6TE",
    "status": "scheduled",
    "text": "Shipped dark mode today.",
    "thread": [],
    "scheduledAt": "2026-11-03T17:57:00.000Z",
    "source": "user"
  }]
}
GET/api/v1/posts/{id}Any key · read

One post, with its thread, the reply under it, where it came from, and its numbers once it is out.

Parameters

id

path

A post id from /posts, or from the answer that made it.

Request
curl https://hookplaybook.com/api/v1/posts/01JBX7Q2MDV4H8C3N5P9R2K6TE \
  -H "Authorization: Bearer $HOOKPLAYBOOK_KEY"
Response200 OK
{
  "post": {
    "id": "01JBX7Q2MDV4H8C3N5P9R2K6TE",
    "status": "posted",
    "url": "https://x.com/you/status/18509…",
    "views": 4210, "likes": 88, "replies": 14,
    "multiple": 3.4,
    "from": "Made with the API"
  }
}
POST/api/v1/draftsAny key · drafts

Saves a draft, or a thread, in your Schedule with no time. With a Draft only key it waits there for your OK; a schedule key can then schedule it.

JSON body

text

required · string

The post. Up to 4,000 characters are saved; past X's 280 it comes back with a warning, since only X Premium can post it as it is.

thread

optional · string[]

For a thread: the posts after the first, in order. Up to 24.

reply

optional · string

A reply to go under the post, like a link to the full article.

Request
curl -X POST https://hookplaybook.com/api/v1/drafts \
  -H "Authorization: Bearer $HOOKPLAYBOOK_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6f1c…" \
  -d '{"text": "Shipped dark mode today."}'
Response201 Created
{
  "post": {
    "id": "01JBX7Q2MDV4H8C3N5P9R2K6TE",
    "status": "draft",
    "text": "Shipped dark mode today.",
    "scheduledAt": null
  },
  "warnings": []
}
PATCH/api/v1/posts/{id}Any key · drafts

Changes a post that has not gone out; send only what changes. A draft with any key; a scheduled post only with a schedule key, and it keeps its time.

JSON body

text

optional · string

The new words.

thread

optional · string[]

The new thread; [] makes it a single post.

reply

optional · string | null

The reply under it; null removes it.

Request
curl -X PATCH https://hookplaybook.com/api/v1/posts/01JBX7Q2MDV4H8C3N5P9R2K6TE \
  -H "Authorization: Bearer $HOOKPLAYBOOK_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "Dark mode is live."}'
Response200 OK
{
  "post": { "id": "01JBX7Q2MDV4H8C3N5P9R2K6TE", "status": "draft", "text": "Dark mode is live." },
  "warnings": []
}
DELETE/api/v1/posts/{id}Any key · drafts

Deletes a draft (any key) or a scheduled post (schedule key), giving back a scheduled post's credits. A post already on X stays there.

Parameters

id

path

The post to delete.

Request
curl -X DELETE https://hookplaybook.com/api/v1/posts/01JBX7Q2MDV4H8C3N5P9R2K6TE \
  -H "Authorization: Bearer $HOOKPLAYBOOK_KEY"
Response200 OK
{ "deleted": "01JBX7Q2MDV4H8C3N5P9R2K6TE", "creditsBack": 0 }

Scheduling

Scheduling

Approve a draft into your Schedule, at a time or your next free one. Needs a Draft and schedule key.

GET/api/v1/slotsAny key · read

Your next free times to post: your weekly slots, or each day's best hours when you have none, without the times already taken.

Query parameters

days

optional · 1–28

How far ahead. 7 by default.

limit

optional · 1–50

How many times. 10 by default.

Request
curl "https://hookplaybook.com/api/v1/slots?days=7&limit=3" \
  -H "Authorization: Bearer $HOOKPLAYBOOK_KEY"
Response200 OK
{
  "timezone": "America/New_York",
  "slots": [
    "2026-11-02T14:04:00.000Z",
    "2026-11-03T17:57:00.000Z",
    "2026-11-04T14:02:00.000Z"
  ]
}
POST/api/v1/posts/{id}/scheduleDraft and schedule key

Approves a draft into your Schedule. It goes out at that time through HookPlaybook, like a post you approve: its credits are taken now, and it waits while posting is paused.

JSON body

at

optional · ISO time

When it goes out. Leave it out for your next free time, away from a post too alike.

id

path

A draft. A follow-up's other version is deleted, as in the app.

Request
curl -X POST https://hookplaybook.com/api/v1/posts/01JBX7Q2MDV4H8C3N5P9R2K6TE/schedule \
  -H "Authorization: Bearer $HOOKPLAYBOOK_KEY" \
  -H "Content-Type: application/json" \
  -d '{"at": "2026-11-03T17:57:00Z"}'
Response200 OK
{
  "post": {
    "id": "01JBX7Q2MDV4H8C3N5P9R2K6TE",
    "status": "scheduled",
    "scheduledAt": "2026-11-03T17:57:00.000Z"
  },
  "creditsLeft": 635,
  "warnings": []
}
POST/api/v1/posts/{id}/unscheduleDraft and schedule key

Takes a scheduled post off the Schedule: it becomes a draft again and its credits come back.

Parameters

id

path

A scheduled post that has not gone out.

Request
curl -X POST https://hookplaybook.com/api/v1/posts/01JBX7Q2MDV4H8C3N5P9R2K6TE/unschedule \
  -H "Authorization: Bearer $HOOKPLAYBOOK_KEY"
Response200 OK
{
  "post": { "id": "01JBX7Q2MDV4H8C3N5P9R2K6TE", "status": "draft", "scheduledAt": null },
  "creditsBack": 5,
  "warnings": []
}

Your X account

Your X account

Everything on your X account, posted from HookPlaybook or not: each post and reply with its numbers, and the totals.

GET/api/v1/x/postsAny key · read

Every post on your X account in the window, posted from HookPlaybook or on X itself, with views, likes, replies, reposts, bookmarks, its multiple of your normal, hook and format.

Query parameters

days

optional · 7, 30, 90

30 by default.

sort

optional

newest (default), views, likes or multiple.

limit, offset

optional · 1–100

20 at a time; next gives the offset of the next page.

Request
curl "https://hookplaybook.com/api/v1/x/posts?sort=multiple&limit=1" \
  -H "Authorization: Bearer $HOOKPLAYBOOK_KEY"
Response200 OK
{
  "days": 30,
  "posts": [{
    "url": "https://x.com/you/status/18509…",
    "postedAt": "2026-10-21T15:10:00.000Z",
    "views": 12900, "likes": 241, "replies": 38,
    "reposts": 19, "bookmarks": 64,
    "multiple": 12.9, "hook": "intro", "format": "story",
    "madeWith": "x"
  }],
  "next": 1
}
GET/api/v1/x/repliesAny key · read

Your replies on X, with the post each one answered when we know it, and how many views and likes they got.

Query parameters

days

optional · 7, 30, 90

7 by default.

sort

optional

newest (default), views or likes.

limit, offset

optional · 1–100

20 at a time.

Request
curl "https://hookplaybook.com/api/v1/x/replies?sort=views" \
  -H "Authorization: Bearer $HOOKPLAYBOOK_KEY"
Response200 OK
{
  "days": 7,
  "total": 97,
  "replies": [{
    "text": "…",
    "inReplyTo": { "handle": "…", "text": "…" },
    "views": 2310, "likes": 17,
    "sentFrom": "hookplaybook"
  }]
}
GET/api/v1/resultsAny key · read

The Results page's numbers: the whole X account once it has been read, and what went out through HookPlaybook, each against the window before.

Query parameters

days

optional · 7, 30, 90

The window. 7 by default.

Request
curl "https://hookplaybook.com/api/v1/results?days=30" \
  -H "Authorization: Bearer $HOOKPLAYBOOK_KEY"
Response200 OK
{
  "days": 30,
  "account": {
    "followers": 1240, "followerGain": 96,
    "impressions": 48200, "impressionsBefore": 31900
  },
  "throughHookPlaybook": { "posts": 18, "reachChange": 0.36 }
}

Audience

Audience

The people around your account: followers, people you follow, your circle, and who replied to you.

GET/api/v1/peopleAny key · read

The people around your account: followers, people you follow and mutuals (up to about 10,000 each), or your circle, the ones you actually talk with. Biggest first.

Query parameters

who

optional

followers (default), following, mutual or circle.

q

optional

Search names and handles.

limit, offset

optional · 1–100

30 at a time.

Request
curl "https://hookplaybook.com/api/v1/people?who=circle&limit=1" \
  -H "Authorization: Bearer $HOOKPLAYBOOK_KEY"
Response200 OK
{
  "who": "circle",
  "total": 61,
  "people": [{
    "handle": "…", "followers": 4800,
    "follow": "mutual",
    "talks": { "repliedToYou": 4, "youReplied": 2 },
    "lastTalk": "2026-10-29T09:12:00.000Z"
  }]
}
GET/api/v1/people/{handle}Any key · read

One person: how you know each other, your note on them, and the replies between you, newest first.

Parameters

handle

path

Their X handle, without @.

Request
curl https://hookplaybook.com/api/v1/people/marclou \
  -H "Authorization: Bearer $HOOKPLAYBOOK_KEY"
Response200 OK
{
  "person": { "handle": "marclou", "follow": "youFollow", "inCircle": true, "note": "…" },
  "replies": [
    { "from": "them", "text": "…", "at": "2026-10-29T09:12:00.000Z" },
    { "from": "you", "text": "…", "at": "2026-10-29T09:40:00.000Z" }
  ]
}
GET/api/v1/mentionsAny key · read

Replies and mentions from the last 7 days still to answer, with your post they answer and up to 3 reply drafts in your voice once written (most are written ahead). You send the reply on X.

Query parameters

who

optional

mutual, followsYou, youFollow or stranger.

sort

optional

newest (default) or top, by followers.

Request
curl "https://hookplaybook.com/api/v1/mentions?sort=top" \
  -H "Authorization: Bearer $HOOKPLAYBOOK_KEY"
Response200 OK
{
  "mentions": [{
    "author": { "handle": "…", "followers": 9200, "follow": "followsYou" },
    "text": "…",
    "yourPost": "…",
    "drafts": ["…", "…", "…"],
    "replyOnX": "https://x.com/intent/tweet?in_reply_to=…"
  }]
}

Inspiration

Inspiration

What works in your niches: viral posts and the hooks behind them.

GET/api/v1/viralAny key · read

Posts at 2× or more of their author's normal views in your niches, accounts your size first, with the hook and format behind them. Learn the pattern; never copy the words.

Query parameters

niche

optional

One of the niches /me lists, like saas. All of them by default.

limit

optional · 1–50

How many. 10 by default.

Request
curl "https://hookplaybook.com/api/v1/viral?niche=saas&limit=1" \
  -H "Authorization: Bearer $HOOKPLAYBOOK_KEY"
Response200 OK
{
  "days": 14, "accountsYourSize": true,
  "posts": [{
    "author": { "handle": "…", "followers": 2100 },
    "views": 61300, "multiple": 14.2, "measured": true,
    "hook": "number-result", "format": "how-to-list"
  }]
}
GET/api/v1/hooksAny key · read

The hook library: each hook (or format) in your niches over 30 days, with its median lift and how many posts back it. Best first.

Query parameters

by

optional

hook (default) or format.

size

optional

yours (default) or every: accounts your size, or every size.

Request
curl "https://hookplaybook.com/api/v1/hooks?by=hook" \
  -H "Authorization: Bearer $HOOKPLAYBOOK_KEY"
Response200 OK
{
  "hooks": [
    { "hook": "number-result", "label": "A number or result", "medianLift": 3.1, "posts": 42 },
    { "hook": "intro", "label": "A personal intro", "medianLift": 2.4, "posts": 17 }
  ]
}

Questions

Asked before you build.

Something else? hello@hookplaybook.com

Is the API in every plan?

Yes, at no extra cost, the 3-day free trial too. If a trial ends without a plan, keys answer 402 until you pick one in Billing.

Can a key post to X?

Only through your Schedule. A Draft only key never schedules: every draft waits for your OK. A Draft and schedule key can approve a draft into your Schedule, where it goes out at its time like any post you approve. No key posts right away, replies, likes, follows or sends DMs.

Which key should I give Claude or ChatGPT?

Start with Draft only and approve what it writes in the app. Once you trust its drafts, make a Draft and schedule key so it can fill your week. You can have both, and revoke either at once.

Does it cost credits?

Reading and drafting cost nothing. Credits are taken when a post is scheduled, the same as in the app, and come back when it is unscheduled or deleted. /me says what a post costs today.

Does reading my audience cost X calls?

No. Followers, replies, mentions and your posts come from what HookPlaybook already reads for your account, so the API adds no X calls and no cost.

Which apps can use the MCP?

MCP is an open standard. The Claude app and ChatGPT connect with a custom connector you approve once, with no key to copy (ChatGPT asks for its Developer mode, and what it allows depends on your ChatGPT plan). Claude Code, Cursor, VS Code and any client that can send an Authorization header use a key.

Can I add pictures, or post a long post?

Pictures are added in the app. Up to 4,000 characters are saved; past X's 280 the answer carries a warning, since only X Premium accounts can post it as it is.

What if a key leaks?

Revoke it on the API and MCP page: it stops at once. We keep only a fingerprint of each key, so a lost key is revoked and replaced, never shown again.

Build on your own X data.

The API comes with every plan, the 3-day free trial too. No card to start.

Start freeGet your API key