---
title: "Post or schedule a video"
method: POST
path: "/api/social/posts"
tags: ["Social"]
---

# Post or schedule a video

`POST /api/social/posts`

## Request

- Base URL: `https://app.pedra.ai`
- URL: `https://app.pedra.ai/api/social/posts`
- Auth: none required

Posts one video to one or more connected networks, now or at `scheduledAt`. Pedra copies the video to its own storage (max 1 GB); a Pedra video URL (img.pedra.ai) is used as is. Omit `scheduledAt` to post now (goes out within about a minute). Returns one post per network with `status: "pending"`; follow up with socialListPosts. Instagram posts as a Reel on a professional account. Video only. Pedra Pro only; a scheduled post is only published if the account is still on Pro when it's due, otherwise it fails. No credits; 25 posts per network per rolling 24 hours.

## Request body

- object
  - `apiKey` string, required: Account API key, sent in the request body. Get one at https://app.pedra.ai under Settings → API.
  - `videoUrl` string, uri, required: Public https URL of an MP4 (max 1 GB).
  - `scheduledAt` string, date-time: ISO 8601. Omit to post now. Can't be in the past; max 180 days ahead.
  - `timezone` string: IANA timezone (e.g. Europe/Madrid), stored for display only.
  - `coverOffsetMs` integer: Cover frame on Instagram and TikTok, in milliseconds from the start of the video. Ignored for Facebook and YouTube.
  - `posts` SocialPostInput[], required: One entry per network, each network at most once.
    - `network` 'instagram' | 'facebook' | 'tiktok' | 'youtube', required: A supported social network.
    - `caption` string: Post text; on YouTube it's the description. Max 2,200 characters on Instagram and TikTok, 5,000 on YouTube.
    - `title` string: YouTube only, required there. Title and caption can't contain < or >.
    - `privacyStatus` 'public' | 'unlisted' | 'private': YouTube only.
    - `categoryId` string: YouTube only. YouTube category number as a string, e.g. "22".
    - `videoType` 'REEL' | 'FEED': Facebook only.
    - `firstComment` string: Facebook only. Posted as the Page's first comment, e.g. a link.
    - `privacyLevel` 'PUBLIC_TO_EVERYONE' | 'MUTUAL_FOLLOW_FRIENDS' | 'FOLLOWER_OF_CREATOR' | 'SELF_ONLY': TikTok only, required there. Must be one the creator's account allows.
    - `disableComment` boolean: TikTok only.
    - `disableDuet` boolean: TikTok only.
    - `disableStitch` boolean: TikTok only.
    - `brandOrganicToggle` boolean: TikTok only. The video promotes your own brand.
    - `brandContentToggle` boolean: TikTok only. Paid partnership; not allowed with SELF_ONLY.
    - `aiGenerated` boolean: TikTok only. TikTok's AI-generated content label; set false only for real footage.

## Response `201`

Posts created, one per network.

- object
  - `videoId` string, required
  - `videoUrl` string, required: The stored copy of the video.
  - `posts` SocialPost[], required
    - `postId` string, required: Pedra's id for the post.
    - `network` 'instagram' | 'facebook' | 'tiktok' | 'youtube', required: A supported social network.
    - `status` 'pending' | 'processing' | 'posted' | 'failed' | 'cancelled', required: pending: waiting for its time (only pending posts can be cancelled). processing: being published. posted: live on the network. failed: not published, see error. cancelled: cancelled before it went out.
    - `scheduledAt` string, date-time, required: When the post is due, in UTC.
    - `postedAt` string, date-time, nullable, required: When it went out, or null.
    - `platformPostId` string, nullable, required: The network's id once posted (e.g. the YouTube video id). For private TikTok posts, the publish id.
    - `videoId` string, required: The stored video, shared by all posts from the same call.
    - `error` string, nullable, required: Why the post failed, or null.
    - `firstCommentError` string: Only present when a Facebook first comment failed. The post itself still went out.

## Other responses

- `400`: Invalid input: invalid_video_url, video_unreachable, not_a_video, video_too_large, invalid_network, not_connected, invalid_post (the message names the network and field), invalid_scheduled_at or invalid_cover.
- `401`: Missing or invalid API key.
- `403`: The account isn't on Pedra Pro.
- `405`: Wrong HTTP method; these endpoints accept POST only.
- `429`: 25 posts on that network in the last 24 hours.
- `500`: Unexpected server error.

---

[API](https://skmtc.dev/pedra/apis/pedra-api.md) · [All operations](https://skmtc.dev/pedra/apis/pedra-api/llms.txt) · [OpenAPI document](https://skmtc.dev/pedra/apis/pedra-api/revisions/87b2e76912c8?raw)