Public API

Plain HTTPS + JSON. Same features as the app: hooks, Studio, scheduling.

Base URL

url

https://app.hookbird.ai/api/public/v1

Authentication

Send your API key as the raw Authorization header (no “Bearer”). Get it in the app under Agents.

bash

curl https://app.hookbird.ai/api/public/v1/agents/ping \
  -H "Authorization: $HOOKBIRD_API_KEY"

Building for other users? Use an OAuth app: its hb_… tokens work in the same header.

Errors

Status	Meaning
400	Validation failed. Body: { msg } or the field errors
401	No API key, wrong key or invalid token
402	Not enough credits. Nothing was reserved
429	{ code: "RATE_LIMITED", bucket, limit, retryAfter }
503	Feature not configured on this instance

Brand & hooks

Endpoint	Does
GET/agents/ping	Check the key: { ok, organization, tools }
GET/brand	Brand profile ({ found: false } until read)
POST/hooks/score	Score { text, platform?, audienceId? }
POST/hooks/generate	Hooks { topic?, audienceId?, platform?, count? }

bash

curl -X POST https://app.hookbird.ai/api/public/v1/hooks/score \
  -H "Authorization: $HOOKBIRD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text":"POV: 11pm, your accountant wants 43 receipts","platform":"tiktok"}'

Returns score, pattern, strengths, fixes, rewrite, breakdown and benchmark (percentile, estimated).

Studio

Endpoint	Does
GET/studio/formats	Formats, inputs and credit prices
POST/studio/generations	Start: { formatId, input } → { id, status, credits }
GET/studio/generations	List (?status=queued\|running\|done\|failed)
GET/studio/generations/:id	Status and outputs
GET/credits	Credits left

bash

curl -X POST https://app.hookbird.ai/api/public/v1/studio/generations \
  -H "Authorization: $HOOKBIRD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"formatId":"wall_of_text","input":{"hook":"Nobody tells you this about your first 100 users"}}'

Poll /studio/generations/:id every few seconds until status is done. Outputs are media library files you can attach to a post.

Format ids include wall_of_text, slideshow, hook_plus_demo, voiceover, image_fast, image_quality, image_pro, video_clip. The full list: GET /studio/formats.

Channels

Endpoint	Does
GET/integrations	Connected channels: { id, name, identifier, … }
GET/social/:provider	Sign-in URL to connect a channel
GET/is-connected	Whether any channel is connected
DELETE/integrations/:id	Disconnect a channel
GET/analytics/:integration?date=	Channel analytics
GET/analytics/post/:postId?date=	Post analytics

Media

Endpoint	Does
POST/upload	Multipart field file → { id, path }
POST/upload-from-url	Import { url } (public http/https only)
GET/media	Media library

bash

curl -X POST https://app.hookbird.ai/api/public/v1/upload \
  -H "Authorization: $HOOKBIRD_API_KEY" \
  -F "file=@./slide-1.png"

Posts

Endpoint	Does
POST/posts	Create, schedule or draft
GET/posts?startDate=&endDate=	List posts in a range (ISO dates)
DELETE/posts/:id	Delete a post (and its group)
GET/find-slot/:id	Next free time for a channel

json

{
  "type": "schedule",
  "date": "2026-11-03T18:30:00.000Z",
  "shortLink": false,
  "tags": [],
  "posts": [
    {
      "integration": {
        "id": "<channel id from /integrations>"
      },
      "value": [
        {
          "content": "Nobody tells you this about your first 100 users",
          "image": [
            {
              "id": "<upload id>",
              "path": "<upload path>"
            }
          ]
        }
      ],
      "settings": {
        "__type": "x",
        "who_can_reply_post": "everyone"
      }
    }
  ]
}

type: schedule, now or draft.
settings.__type is the channel’s identifier; required settings differ per network.
Returns one item per channel with its postId.