Publications

Publications are the recommended way to publish. Creating one responds immediately with 202 Accepted and processes the upload in the background — poll for status until it is published or failed.

List publications

GET /v1/publications

Returns your publications, newest first (max 100 per page).

Query parameters

Param	Type	Description
profile_id	string	Filter by profile UUID
platform	string	youtube or tiktok
status	string	pending · processing · published · failed
limit	integer	1–100, default 20
offset	integer	Pagination offset, default 0

Response

{
  "publications": [ /* Publication objects */ ],
  "total": 42,
  "limit": 20,
  "offset": 0
}

Create publication

POST /v1/publications

Creates a publication and starts publishing asynchronously. The server always responds 202 Accepted immediately — the upload happens in the background. Poll GET /v1/publications/:id until status is published or failed. Use status=draft to save metadata without triggering a publish.

Provide the video in one of two ways: upload a file (multipart/form-data) or pass a public URL (application/json with video_url). With a URL, the server downloads it for you — no large file transfer needed.

Option A — file upload (multipart/form-data)

Field	Type	Required	Description
platform	string	yes	youtube or tiktok
video	file	yes*	Video file (mp4 recommended). *Required unless status=draft
title	string	no	Title (max 100 chars for YouTube, 150 for TikTok)
description	string	no	Description (YouTube only, max 5000 chars)
privacy	string	no	YouTube: public · private · unlisted. Default private
profile_id	string	no	Profile UUID. Omit to use the default channel
status	string	no	published (default) or draft

Option B — video URL (application/json)

Field	Type	Required	Description
platform	string	yes	youtube or tiktok
video_url	string	yes*	Public HTTP/HTTPS URL to the video. *Required unless status=draft
title	string	no	Title (max 100 chars for YouTube, 150 for TikTok)
description	string	no	Description (YouTube only, max 5000 chars)
privacy	string	no	YouTube: public · private · unlisted. Default private
profile_id	string	no	Profile UUID. Omit to use the default channel
status	string	no	published (default) or draft

Example — publish by URL

curl -X POST https://storyload.io/v1/publications \
  -H "Authorization: Bearer sl_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "platform": "youtube",
    "video_url": "https://example.com/my-short.mp4",
    "title": "My YouTube Short",
    "description": "Auto-published via API",
    "privacy": "public"
  }'

Response — 202 Accepted (always immediate)

{
  "publication": {
    "id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
    "platform": "youtube",
    "status": "processing",
    "video_id": null,
    "video_url": null
  },
  "message": "Publication created. Poll GET /v1/publications/9b1deb... for status."
}

Poll until published

# Poll every 5s until status is "published" or "failed"
curl https://storyload.io/v1/publications/PUBLICATION_ID \
  -H "Authorization: Bearer sl_live_..."

Published response (after processing)

{
  "publication": {
    "id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
    "platform": "youtube",
    "status": "published",
    "video_id": "dQw4w9WgXcQ",
    "video_url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
    "privacy": "public",
    "published_at": "2026-03-30T12:00:00.000Z"
  }
}

Get publication

GET /v1/publications/:id

Retrieve a single publication by its ID.

{ "publication": { /* Publication object */ } }

Update publication

PATCH /v1/publications/:id

Update editable fields. Only draft or pending publications can be updated — published ones are immutable.

Field	Type	Description
title	string	Update the title
description	string	Update the description
privacy	string	public · private · unlisted
status	string	draft or pending

{ "publication": { /* Updated publication object */ } }

Delete publication

DELETE /v1/publications/:id

Deletes a publication record. This removes the record from Storyload only — the video on YouTube or TikTok is not affected.

{ "ok": true, "message": "Publication deleted" }