Publishing to social networks
How to publish rendered clips to TikTok, Instagram, YouTube, and more
After rendering a clip, you can publish it to one or more connected accounts with POST /posts. A single post can carry multiple clips to multiple accounts at once.
Before you start
You need two things:
A rendered clip
The edit_id comes from the render: it identifies the video to publish, and it never expires.
Connected accounts
The connection_id comes from GET /connections. Connect new accounts via OAuth inside cut.pro. The API does not connect accounts.
How the body is built
Each item in videos points a clip (edit_id) to one or more targets (targets). Each target combines a connection (connection_id) with the metadata of that platform (title, privacy, etc.).
curl -X POST https://api.cut.pro/api/v1/posts \
-H "X-Api-Key: $CUTPRO_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"videos": [
{
"edit_id": "EDIT_ID",
"targets": [
{
"connection_id": "CONEXAO_TIKTOK",
"metadata": {
"tiktok": {
"title": "Meu corte viral",
"privacyLevel": "PUBLIC_TO_EVERYONE"
}
}
},
{
"connection_id": "CONEXAO_YOUTUBE",
"metadata": {
"youtube": {
"title": "Meu corte viral",
"description": "Cortes do episódio de hoje",
"categoryId": "22",
"privacyStatus": "public"
}
}
}
]
}
]
}'{
"id": "7412909001223344",
"item_count": 2,
"scheduled_at": null,
"status": "pending"
}The metadata changes per platform (TikTok, YouTube, Instagram, Threads, Bluesky, LinkedIn, Pinterest, Facebook). The required fields and options for each are detailed on the endpoint page POST /posts, with the interactive playground.
To schedule instead of publishing now, send scheduled_at with an ISO 8601 date in the future.
Track the publishing
The post is queued and publishes asynchronously. Poll GET /posts/{id}:
curl https://api.cut.pro/api/v1/posts/POST_ID \
-H "X-Api-Key: $CUTPRO_API_KEY"The post status evolves like this:
| Status | Meaning |
|---|---|
pending | In the queue, not started yet |
processing | Publishing to the accounts |
completed | All items published |
partial | Some published, others failed |
failed | No item published |
The items array shows the result per account, useful when the status is partial.
When something fails
Items fail independently: a target with an error does not bring down the ones that already published.
- Retry a failed item:
POST /posts/{id}/items/{itemId}/retry - Remove an item without touching the others:
DELETE /posts/{id}/items/{itemId} - Delete the whole post:
DELETE /posts/{id} - Edit before publishing (e.g. adjust scheduling):
PATCH /posts/{id}
partial is not success. If your product says "published" on a partial, it is lying to the user: read items and show what went up and what did not.
The refusals that happen before anything is created:
code | Status | What to do |
|---|---|---|
INVALID_CONNECTIONS | 400 | extra.invalid_connections lists the connections that are unknown, revoked or cannot publish video |
INVALID_METADATA | 400 | extra.field says which field failed, such as youtube.categoryId |
PLATFORM_UNAVAILABLE | 400 | That network is not open for publishing yet |
EDITS_NOT_FOUND | 404 | extra.invalid_edits lists the edit_id values that do not exist in this workspace |
DAILY_LIMIT_EXCEEDED | 403 | The account hit the platform's daily ceiling. extra carries daily_limit, used_today and how many items this request would add |
DUPLICATE_POST | 409 | The same clip is already on its way to the same account |
The file goes, the edit stays
Every item carries a render_id, and it turns null when the rendered file is purged by your plan's retention. The post is still there, with the published_url and the exact metadata that went live. To get the MP4 back, call POST /renders with the item's edit_id (see Recipes).