Skip to content
reelspanDocs

Publish

Validate a post

Check a post for every network before you publish it. Errors and warnings per network, with nothing published, stored or counted against your plan.

POSTapi.reelspan.com/v1/posts/validateTry it →

Send the post you are about to publish and Reelspan runs the same checks the publish endpoints run, network by network, without publishing it. Use it to catch a caption that is too long for Threads, a missing Pinterest board or an account that needs reconnecting before your users press Publish.

Nothing is published or stored, and it doesn't count against your monthly uploads. The key needs the publish scope.

Check a post

curl -X POST https://api.reelspan.com/v1/posts/validate \
  -H "Authorization: Bearer $REELSPAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "kind": "video",
    "user": "my-brand",
    "platform": ["tiktok", "youtube", "bluesky"],
    "title": "Launch day",
    "video_media_id": "med_Wm4Kq8Zt1Rb6Yn3Px9Cv"
  }'
{
  "success": true,
  "ok": false,
  "kind": "video",
  "profile_username": "my-brand",
  "errors": [],
  "warnings": [],
  "platforms": {
    "tiktok": { "ok": true, "errors": [], "warnings": [] },
    "youtube": {
      "ok": true,
      "errors": [],
      "warnings": [{ "code": "not_a_short", "message": "Over 3 minutes, so YouTube posts it as a regular video, not a Short." }]
    },
    "bluesky": {
      "ok": false,
      "errors": [
        { "code": "bluesky_video_too_large", "message": "Bluesky takes videos up to 100 MB; this one is 212.4 MB. Set bluesky_compress=true to fix it." },
        { "code": "video_too_long", "message": "Bluesky takes videos up to 3 minutes; this one is longer." }
      ],
      "warnings": []
    }
  }
}
  • ok is true when neither the post nor any network has an error. Warnings never stop a post: they say what will happen (a long X post becomes a thread, extra photos are left out).
  • errors and warnings at the top are about the whole post: missing media, a file over your plan's size, not enough uploads left this month.
  • Each network in platforms has its own ok, errors and warnings. Each issue has a code, a message you can show as it is, and sometimes the field it is about.
  • A network with an error would fail if you published now; the others would go out. Leave it out, or fix what it says, and check again.

The request

It takes the same fields as Post a video, Post photos, Post text and Post a document, as JSON, plus kind:

Field
kind video (default), photo, text or document: the endpoint the post is for.
user The profile (also profile_username).
platform The networks, as an array (platform[] works too).
title, description The post's text, as on the publish endpoints.
{network}_title, {network}_description and every other {network}_… setting Checked for that network, as publishing would read them.
scheduled_date, add_to_queue When set, a network with no account connected yet is a warning, not an error: a scheduled post is checked again when it runs.
video_media_id, photo_media_ids, document_media_id, {network}_photo_media_ids Media you uploaded with Upload media. Its stored size, length and dimensions are checked.
video, photos, document Media URLs. They are not fetched, so tell Reelspan what they hold in media.
media For URLs: { "size_bytes", "duration_seconds", "width", "height" } for the video or document, or an array with one per photos URL, in order (add "type": "video" for a video in a carousel).

A URL without media gets a media_not_measured warning and its size and length aren't checked.

What is checked

For the whole post:

  • the media the post type needs is there, and a media_id belongs to your workspace;
  • a text or document post has a title;
  • the video fits your plan's upload size;
  • your plan has enough uploads left this month for every network that would post.

For each network:

Check Codes
The network takes this kind of post (documents go to LinkedIn only). unsupported_post_type, platform_not_available, platform_disabled
The fields it needs, such as YouTube's title, Pinterest's board or Reddit's subreddit. invalid_request, title_required
The title and text fit, counted the way the network counts (an emoji is one character). On X and Bluesky longer text becomes a thread, so it is a warning. title_too_long, text_too_long, posted_as_thread
The media fits: file size, video length, photos per post, photo shapes (Instagram's 4:5 to 1.91:1, one shape for a Pinterest carousel). file_too_large, bluesky_video_too_large, video_too_long, video_too_short, photo_ratio, mixed_shapes, too_many_photos, videos_left_out, not_a_short
An account is connected, signed in, and its access isn't about to run out. not_connected, reauth_required, connection_expiring
A first_comment can be posted: the network allows comments through its API and the account granted the permission. See Permissions. first_comment_unsupported, first_comment_unavailable, permission_missing
X link posts left on your plan, when x_keep_links is on. x_links_removed

Some things only the network knows until it gets the post, such as TikTok's daily limit for an account or a video Instagram can't process. Those still show up in Post status and the upload_completed webhook after you publish.

Errors

Status When
400 No profile given, or the body isn't valid JSON.
403 The key can't use this profile, or lacks the publish scope.
404 No such profile.

Problems with the post itself are never an error status: they come back with 200 in errors and warnings.

From an AI agent

The MCP server has the same check as the validate_post tool, so an agent can check a post before it calls upload_video, upload_photos or upload_text.

Request body

application/json

  • kindstringdefault "video"

    The publish endpoint this post is for: posts/video, posts/photos, posts/text or posts/document

    videophototextdocument

  • userstring

    The profile (also profile_username)

  • profile_usernamestring
  • platformstring[]

    The networks, like platform[] on the publish endpoints

  • titlestring
  • descriptionstring
  • video_media_idstring
  • videostring

    A video URL

  • photo_media_idsstring[]
  • photosstring[]

    Photo URLs

  • document_media_idstring
  • documentstring

    A document URL

  • mediaobject or object[]

    For URLs: the video’s or document’s details, or one per photos[] URL in order

Responses

200 The checks

{
  "success": true,
  "ok": true,
  "kind": "string",
  "profile_username": "string",
  "errors": [
    {
      "code": "string",
      "message": "string",
      "field": "string"
    }
  ],
  "warnings": [
    {
      "code": "string",
      "message": "string",
      "field": "string"
    }
  ],
  "platforms": {}
}

400 Invalid input

{
  "success": false,
  "message": "string",
  "error": "string",
  "error_code": "string"
}

404 No such profile

{
  "success": false,
  "message": "string",
  "error": "string",
  "error_code": "string"
}

Something unclear or missing? Write to [email protected] and we’ll fix the page.