Skip to main content

Publishing to social accounts

Once a video has rendered, POST /contents/upload/{content_id} dispatches it to your connected accounts.

Scope: upload.

The one mistake that looks like success​

account_ids is a list of objects, not strings
{ "account_ids": ["8f14e45f-..."] }        // WRONG — publishes nothing
{ "account_ids": [{"id": "8f14e45f-..."}] } // right

The handler reads a.get("id") on each element. A bare string has no id, so it resolves to no accounts selected — and the request is accepted, the status moves, and nothing is ever published. There is no error to catch.

If a publish appears to succeed but nothing appears on the platform, check this first.

1. Find your account ids​

curl -s https://api.botlobby.ai/v1/accounts \
  -H "Authorization: Bearer $BOTLOBBY_API_KEY"
{
  "page": 1,
  "total_pages": 1,
  "total_items": 2,
  "items": [
    {
      "id": "8f14e45f-ceea-467a-9fbb-9f0a1c2d3e4b",
      "name": "Main channel",
      "platform": "YouTube",
      "platform_acronym": "YT"
    }
  ]
}

Filter by platform if you like — but casing matters. The values are YouTube, TikTok, Instagram, compared literally. youtube matches nothing:

curl -s "https://api.botlobby.ai/v1/accounts?platform=YouTube" \
  -H "Authorization: Bearer $BOTLOBBY_API_KEY"

2. Publish​

curl -s -X POST https://api.botlobby.ai/v1/contents/upload/CONTENT_ID \
  -H "Authorization: Bearer $BOTLOBBY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "account_ids": [{"id": "8f14e45f-ceea-467a-9fbb-9f0a1c2d3e4b"}],
    "madeForKids": "no",
    "ageRestricted": "no",
    "generate_thumbnail": true
  }'

You can pass several accounts in one call to publish the same video to multiple platforms.

Options​

FieldTypeDefaultNotes
madeForKidsstring"no""yes" / "no" strings, not booleans. COPPA
ageRestrictedstring"no""yes" / "no". YouTube 18+
generate_thumbnailbooleanfalseApply the AI-generated thumbnail. YouTube only, small credit surcharge
instagram_captionstring—Falls back to the generated description if omitted
categorystring"22"Platform category id (YouTube: People & Blogs)
privacystring"public"Upload visibility
notifySubscribersbooleantrueYouTube subscriber notification
aiDisclosurebooleantrueDeclares AI-generated content to the platform
location_idstring—Platform-specific location tag
user_tagsarray—Accounts/users to tag in the post
tiktok_post_modestring"direct"direct or draft
tiktok_privacystring"SELF_ONLY"e.g. PUBLIC_TO_EVERYONE

madeForKids and ageRestricted cannot both be "yes" — that returns 400. A video cannot be for children and age-restricted simultaneously.

The full, generated-from-code parameter list is always up to date at the API Reference for this endpoint.

When generate_thumbnail is silently dropped​

It is ignored rather than refused — the upload proceeds without it — when:

  • your plan does not include custom thumbnails
  • no YouTube account is among the selected accounts
  • the video is a Short (3 minutes or less)

The Shorts case is the surprising one: YouTube auto-classifies short videos as Shorts and does not apply Data-API thumbnails to that surface, so applying one would do nothing. You are not charged the surcharge in any of these cases.

If the video's duration is unknown, it is treated as a Short — the conservative choice, since skipping a feature beats charging for one that won't appear.

3. Watch it​

curl -s https://api.botlobby.ai/v1/gen/task-status/CONTENT_ID \
  -H "Authorization: Bearer $BOTLOBBY_API_KEY"

UPLOADING → UPLOADED on success, FAILED_UPLOAD on failure with the reason in metadata.last_error.

To find where it actually landed, read published_url and published_platform. Both are null until an upload genuinely succeeded, which makes published_url a more reliable confirmation than the status alone.

They're on the list endpoint, not the detail one

published_url and published_platform come back from GET /contents. GET /contents/{content_id} returns a different, richer shape that does not include them.

curl -s "https://api.botlobby.ai/v1/contents?search=Water" -H "Authorization: Bearer $BOTLOBBY_API_KEY"

Duplicate dispatches​

A second publish while one is in flight returns 409:

{ "error": "An upload for this content is already in progress." }

This guards against a client that times out locally and retries while the first dispatch is still running server-side — without it, the platform receives the same video twice. It clears once the first dispatch passes the stall threshold, so genuine recovery after a real failure still works.

Don't loop on 409. Poll task-status to find out what actually happened before dispatching again.

What you can't do from the API​

Connecting and disconnecting accounts both live in the web app.

Connecting needs an OAuth browser flow. Disconnecting revokes the grant at YouTube or TikTok — a destructive action outside BotLobby that would need a browser re-authorization to undo, which is why no API key can trigger it.

You can rename a connection with PUT /accounts/{id} (write scope). Only the display name is editable; the platform and stored credentials are immutable, so a rename can never re-point a connection at a different identity.