Developers

Hooklane API v1

Create photo slideshows, manage automations, read analytics and publish to TikTok. Existing ReelFarm clients can keep their endpoint paths and most request fields.

Base URLhttps://hooklane.social/api/v1

Overview

API uses JSON over HTTPS. All v1 endpoints live under one stable base URL. API access requires Starter plan or above.

Format

application/json

Authentication

Bearer API key

Rate limit

20 requests / 60s

Migrating from ReelFarm: replace base URL and use a Hooklane key beginning with hl_live_. Hooklane also returns native aliases such as id, name and hooks so current Hooklane clients keep working.

Authentication

Send your API key in Authorization header on every request. Create and revoke keys from Dashboard → Settings → API Keys. Keys are shown once.

curl "https://hooklane.social/api/v1/account" \
  -H "Authorization: Bearer hl_live_your_key" \
  -H "Content-Type: application/json"

Keep API keys server-side. Never place them in browser code, screenshots or public repositories.

Slideshows

Generate copy from a hook or render exact text and images. One slideshow costs one credit. Maximum 35 slides.

POST/slideshows/generate

Generate a slideshow

additional_context is required. Generation runs asynchronously; poll status every 5–10 seconds. Account needs at least one image collection.

Example request

{
  "additional_context": "5 habits that changed my morning",
  "images": ["https://example.com/coffee.jpg"],
  "product_id": "optional-legacy-id"
}

Example response

{
  "slideshow_id": "uuid",
  "status": "processing",
  "product_id": null
}

POST/slideshows/create

Create with direct control

Renders exact text without an AI copywriting call. Supports ReelFarm named font sizes, colors, text styles, fonts and grid aliases, plus Hooklane numeric values. Output URLs expire after one hour.

Top-level options include title, aspect_ratio, text_position, overlay flags, background_opacity and keep_original_aspect_ratio. Each slide accepts image_url or image_urls, image_layout, text_items and is_cta.

Example request

{
  "slides": [{
    "image_url": "https://example.com/hook.jpg",
    "text_items": [{
      "text": "5 habits that changed my morning",
      "font_size": "extra_large",
      "text_color": "white",
      "text_style": "black_50_background",
      "text_align": "center"
    }]
  }],
  "aspect_ratio": "9:16",
  "is_bg_overlay_on": true,
  "background_opacity": 20
}

Example response

{
  "slideshow_id": "uuid",
  "status": "completed",
  "slideshow_images": ["https://signed-image-url"],
  "slide_count": 1
}

GET/slideshows/{slideshow_id}/status

Check generation status

Accepts a generation ID or completed slideshow ID. Completed direct-control slideshows can be polled too.

Example response

{
  "slideshow_id": "uuid",
  "status": "processing | completed | failed",
  "stage": "rendering",
  "slideshow_images": [],
  "error": null,
  "code": null
}

Automations

Save hooks and generation settings, activate or pause them, and trigger one-off runs. ReelFarm and Hooklane field names are both accepted.

POST/automations

Create an automation

Hooklane-native names are name, hooks and optional format_config. ReelFarm aliases are title, slideshow_hooks, style, image_settings and tiktok_post_settings.

Legacy create requests containing a schedule start active. Native requests without status: active start paused.

Example request

{
  "title": "Fitness motivation",
  "slideshow_hooks": ["5 habits that changed my fitness journey"],
  "tiktok_account_id": "uuid",
  "schedule": [{ "cron": "0 14 * * *" }],
  "style": "One clear idea per slide",
  "language": "English",
  "tiktok_post_settings": {
    "auto_post": true,
    "visibility": "SELF_ONLY"
  }
}

Example response

{
  "id": "uuid",
  "automation_id": "uuid",
  "name": "Fitness motivation",
  "title": "Fitness motivation",
  "hooks": ["5 habits that changed my fitness journey"],
  "slideshow_hooks": ["5 habits that changed my fitness journey"],
  "status": "active",
  "schedule": [{ "job_id": "uuid", "cron": "0 14 * * *" }]
}

GET/automations?limit=20&offset=0

List automations

Returns { automations, total, limit, offset }. Each item includes both id/automation_id, name/title and hooks/slideshow_hooks.

GET/automations/{automation_id}

Get one automation

Returns one automation object. IDs are scoped to authenticated account.

PATCH/automations/{automation_id}

Update or pause an automation

Accepts action: pause|unpause, status: active|paused, and both native and ReelFarm content fields.

Example request

{
  "action": "pause"
}

// or
{
  "title": "New title",
  "slideshow_hooks": ["New hook"]
}

DELETE/automations/{automation_id}

Delete an automation

Soft-deletes automation and stops future use.

Example response

{
  "deleted": true,
  "message": "Automation deleted"
}

POST/automations/{automation_id}/run

Run once

hook overrides hook for this run only. Run does not change saved schedule.

Example request

{
  "hook": "My top 5 productivity tools",
  "mode": "export"
}

Example response

{
  "message": "Slideshow generation started",
  "automation_id": "uuid",
  "generation_id": "uuid",
  "slideshow_id": "uuid",
  "status": "processing"
}

Automation schedules

Hooklane stores one schedule per automation. ReelFarm job IDs and batch-shaped updates are accepted as compatibility aliases for that schedule. Cron defaults to Pacific time.

POST/automations/{automation_id}/schedule

Create or replace schedule

Minute, hour and day-of-week fields support lists, ranges and steps. Day-of-month and month must be *.

Example request

{
  "cron": "0 9 * * 1-5",
  "timezone": "Asia/Shanghai"
}

Example response

{
  "job_id": "uuid",
  "cron": "0 9 * * 1,2,3,4,5",
  "timezone": "Asia/Shanghai",
  "next_run_at": "2026-09-11T01:00:00Z"
}

PATCH/automations/{automation_id}/schedule

Update schedule

Because Hooklane has one schedule per automation, latest update replaces current cron.

Example request

{
  "job_id": "uuid",
  "cron": "0 10 * * *"
}

// ReelFarm batch shape also accepted
{ "actions": [{ "type": "update", "job_id": "uuid", "cron": "0 10 * * *" }] }

DELETE/automations/{automation_id}/schedule

Disable schedule

Clears next run without deleting automation.

Example response

{ "deleted": true }

Videos

For ReelFarm compatibility, API calls completed photo slideshows “videos”. Hooklane does not export MP4 through v1.

GET/videos/{video_id}

Get one slideshow

Returns metadata plus fresh signed slideshow_images.

GET/videos/{video_id}/analytics

Get TikTok analytics

Metrics are null until post is published and analytics have synced.

Example response

{
  "views": 15400,
  "likes": 1230,
  "comments": 89,
  "shares": 234,
  "bookmarks": 567,
  "view_count": 15400,
  "like_count": 1230,
  "published_at": "2026-09-10T14:00:00Z"
}

POST/videos/{video_id}/publish

Publish through saved slideshow

Idempotent per slideshow. Use MEDIA_UPLOAD to send a draft instead of direct posting.

Example request

{
  "tiktok_account_id": "uuid",
  "post_mode": "DIRECT_POST",
  "privacy_level": "SELF_ONLY"
}

Example response

{
  "publish_job_id": "uuid",
  "status": "processing"
}

TikTok

Read connected accounts, publish a completed slideshow and inspect published posts. OAuth connection remains a dashboard action.

POST/tiktok/publish

Publish standalone

slideshow_id and video_id are both accepted. ReelFarm fields visibility, allow_comments and auto_music map to Hooklane publishing settings.

Example request

{
  "video_id": "uuid",
  "tiktok_account_id": "uuid",
  "caption": "5 habits that changed my morning",
  "post_mode": "DIRECT_POST",
  "visibility": "SELF_ONLY",
  "allow_comments": true,
  "auto_music": true
}

GET/tiktok/accounts

List connected accounts

Returns safe profile fields only. Both id and tiktok_account_id are included; tokens are never returned.

GET/tiktok/posts?timeframe=30&sort=recent&limit=20&offset=0

List posts and analytics

Optional filters: timeframe in days and tiktok_account_id. Response includes post metrics, aggregate statistics and pagination.

Collections

Read image collections already created in Hooklane. Collection creation and uploads stay in dashboard.

GET/collections?limit=20&offset=0

List collections

Returns collection metadata with both id and collection_id.

GET/collections/{collection_id}/images?limit=20&offset=0

List collection images

Returns signed URLs, dimensions, rights status and source URL. Both id and image_id are included.

Discovery

Search image sources and browse Hooklane inspiration data.

GET/pinterest/search?query=coffee&cursor=

Search Pinterest

Returns detailed results plus ReelFarm-compatible images URL array. q is accepted as alias for query.

GET/library/niches

List inspiration niches

Returns niche slug, label and item count.

GET/library?niche=fitness&limit=20&offset=0

Browse inspiration library

Returns public inspiration slideshows ordered by views.

Account

Read credit balance and subscription tier before starting paid generation work.

GET/account

Get account balance

ai_credits is total-balance compatibility alias. Do not add it to other credit fields.

Example response

{
  "credits": 20,
  "purchased_credits": 5,
  "subscription_tier": "Starter",
  "ai_credits": 25
}

Errors and rate limits

Errors use one stable JSON envelope. Rate-limit headers are included after successful authentication.

{
  "error": "Human-readable message",
  "code": "VALIDATION_ERROR"
}

Code	HTTP	Meaning
`UNAUTHORIZED`	401	Missing, invalid or revoked key
`FORBIDDEN`	403	Plan does not include API access
`NOT_FOUND`	404	Unknown endpoint or resource
`VALIDATION_ERROR`	400	Invalid request or unsupported value
`INSUFFICIENT_CREDITS`	402	Generation balance is empty
`RATE_LIMITED`	429	More than 20 requests in 60 seconds
`INTERNAL_ERROR`	500	Unexpected server failure

Read X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset and, on 429, Retry-After. Need help? support@hooklane.social.

Hooklane API v1

Overview

Authentication

Slideshows

Generate a slideshow

Create with direct control

Check generation status

Automations

Create an automation

List automations

Get one automation

Update or pause an automation

Delete an automation

Run once

Automation schedules

Create or replace schedule

Update schedule

Disable schedule

Videos

List completed slideshows

Get one slideshow

Get TikTok analytics

Publish through saved slideshow

TikTok

Publish standalone

List connected accounts

List posts and analytics

Collections

List collections

List collection images

Discovery

Search Pinterest

List inspiration niches

Browse inspiration library

Account

Get account balance

Errors and rate limits