Posts

Publish YouTube Shorts via API

A POST /posts with the youtube connection and format shorts sends the video to the channel your customer connected. Your product doesn't implement YouTube OAuth or store tokens: it sends the video URL and Connect publishes it in the background, on the same endpoint as the other networks.

The request

POST /api/posts?customer_integration=<connection uuid>
Authorization: Bearer <merchant token>
x-customer-token: <customer token>
Idempotency-Key: <unique key>

{
  "external_reference": "video-88",
  "format": "shorts",
  "caption": "Behind the scenes of our latest shoot.",
  "media": [
    {
      "type": "video",
      "url": "https://cdn.example.com/short.mp4"
    }
  ],
  "youtube": {
    "title": "Behind the scenes",
    "privacy_status": "public",
    "category_id": "<category id>",
    "tags": [
      "bts",
      "making of"
    ],
    "made_for_kids": false,
    "notify_subscribers": true
  }
}

What you can do

  • Publish a short video to the channel, with a title and description.
  • Choose the visibility: public, unlisted or private.
  • List the assignable categories with GET /posts/youtube/categories and use the id in youtube.category_id.
  • Set tags, the made-for-kids flag (made_for_kids) and the subscriber notification.
  • Pick the channel by connection (customer_integration) or by source_name.

Rules and limits

  • The format is always shorts, with exactly 1 video and no alt_text.
  • youtube.title (up to 100 characters) and youtube.privacy_status are required. Title and description do not accept < or >.
  • The description (caption) goes up to 5000 bytes. Tags do not accept <, > or commas, and add up to 500 characters.
  • YouTube decides whether it is a Short from the video itself: vertical and up to 3 minutes.
  • POST /posts responds 202 and publishing runs afterwards. Track it with GET /posts/{uuid}.
  • Videos above 8 MB can be uploaded first in parts through the media module, which returns the URL to use in media.url.

Main fields

FieldTypeRequiredDescription
external_referencestringYesThe video's id in your system (up to 100 characters). Stops the same video from being published twice on the same channel.
formatstringYesAlways shorts on YouTube.
captionstringNoBecomes the video description. Up to 5000 bytes, no < or >.
mediaarrayYesExactly 1 video, without alt_text.
youtube.titlestringYesVideo title, up to 100 characters, no < or >.
youtube.privacy_statusstringYesVisibility: public, unlisted or private.
youtube.category_idstringNoThe video category. Comes from GET /posts/youtube/categories.
youtube.tagsarrayNoVideo tags, without <, > or commas. Together, up to 500 characters.
youtube.made_for_kidsbooleanNoDeclares the video as made for kids.
youtube.notify_subscribersbooleanNoNotifies the channel's subscribers.

Who it is for

  • Creator platform

    The creator records once and the product publishes the Short to the connected channel, with title, tags and visibility set.

  • Short video repurposing

    A social media tool sends the same vertical video to Reels and YouTube Shorts in separate calls.

  • Video AI agent

    An agent generates the video and metadata, picks the category from GET /posts/youtube/categories and publishes as private for review.

Works with

  • YouTube

Frequently asked questions

How does YouTube know it is a Short?

From the video itself: vertical and up to 3 minutes. You send format shorts and YouTube decides.

How do I find the category_id?

Call GET /posts/youtube/categories with the connection or source_name. region_code (default BR) and hl set the country and the language of the titles.

Can I publish as private first?

Yes. youtube.privacy_status accepts public, unlisted or private.

Related

See everything you can do with Posts

See Connect applied to your product.

Try it for 15 days with no card, or walk our team through your use case.