Robopost REST API Reference

This document provides a reference for using the Robopost Public API directly via HTTP, rather than through the Python client library. Here, you’ll find endpoint details, request and response structures, authentication parameters, and usage examples in a REST context.

Base URL: https://public-api.robopost.app/v1

If you want to use the API through our Python Wrapper, click here.

Authentication

All requests to the Robopost Public API must include your API key as a query parameter:

?apikey=YOUR_API_KEY

For example:

POST /v1/scheduled_posts?apikey=YOUR_API_KEY

If the apikey is missing or invalid, the server will respond with an appropriate 4xx error status.

All endpoints discussed here require an API key, passed as a query parameter named apikey. You can generate API Keys under "Team" > "Manage API Keys".

Upload Media

Use this endpoint to upload images or videos that you want to attach to your scheduled posts. Each upload returns a media object containing the ID and a storage_object_id, which you’ll reference later when creating a scheduled post.

POST /medias/upload

• Authentication: apikey query parameter
• Request: multipart/form-data with a single field named file (the binary file to upload).
• Response: A JSON object describing the uploaded media.

Example Request (cURL)

curl -X POST \
  "https://public-api.robopost.app/v1/medias/upload?apikey=YOUR_API_KEY" \
  -F "file=@path/to/image.jpg"

Example Successful Response (JSON)

{
  "id": "64f20e2c915d2f1970ec8c09",
  "name": "image.jpg",
  "extension": "jpg",
  "storage_object_id": "9f73ad62-xxxxx-xxxxx-xxxxx-9556dcb903f4"
}

Create Scheduled Posts

Use this endpoint to schedule new posts (including drafts and recurring posts) across one or multiple social channels. You will need:

• The channel_id (or multiple IDs) for each social account.
• (Optionally) the storage_object_id for media uploads (if you plan to attach images or video).

POST /scheduled_posts/

• Authentication: apikey query parameter
• Request Body: JSON object matching the PublicAPIScheduledPostCreateHTTPPayload schema (see below).
• Response: Array of objects matching the PublicAPIScheduledPostRead schema, each representing a newly created scheduled post.

Note: The endpoint always returns an array (even if you only schedule one post).

URL

POST /v1/scheduled_posts/?apikey=YOUR_API_KEY

Example Request (cURL)

Below is an example showing how to schedule one post (with text, channel IDs, and attached medias).

You'll find several additional cURL examples demonstrating how to use the image_urls, gif_url, and video_url fields in your payload:

Example: Using image_urls

This example shows how to post with multiple image URLs. The API will download each image from the provided URLs, process, and upload them automatically.

curl -X POST \
  "https://public-api.robopost.app/v1/scheduled_posts/?apikey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Check out these images!",
    "channel_ids": ["my_instagram_channel_id"],
    "image_urls": [
      "https://example.com/image1.jpg",
      "https://example.com/image2.jpg"
    ],
    "schedule_at": "2025-03-01T10:00:00Z",
    "is_draft": false
  }'

Example: Using gif_url

Here’s an example of scheduling a post with a direct URL for a GIF. The API will automatically handle downloading and processing the GIF.

curl -X POST \
  "https://public-api.robopost.app/v1/scheduled_posts/?apikey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Animated fun with this GIF!",
    "channel_ids": ["my_facebook_channel_id"],
    "gif_url": "https://example.com/animated.gif",
    "schedule_at": "2025-03-01T12:00:00Z",
    "is_draft": false
  }'

Example: Using video_url

This example demonstrates how to post a video using a direct URL. The API will download, process, and upload the video automatically.

curl -X POST \
  "https://public-api.robopost.app/v1/scheduled_posts/?apikey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Watch this amazing video!",
    "channel_ids": ["my_youtube_channel_id"],
    "video_url": "https://example.com/video.mp4",
    "schedule_at": "2025-03-01T14:00:00Z",
    "is_draft": false
  }'

Each of these examples shows a different media type being used directly via URL. Simply replace the URL(s) and channel IDs with your own values as needed.

You can also use image_object_ids, video_id or gif_id, by passing the "storage_object_id" attribute that you got from /medias/upload endpoint.

curl -X POST \
  "https://public-api.robopost.app/v1/scheduled_posts/?apikey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Hello from the REST API!",
    "channel_ids": ["my_facebook_channel_id"],
    "image_object_ids": ["9f73ad62-xxxxx-xxxxx-xxxxx-9556dcb903f4"],
    "schedule_at": "2025-03-01T10:00:00Z",
    "is_draft": false
  }'

Example Successful Response

[
  {
    "id": "64f20e2c915d2f1970ec8c09",
    "text": "Hello from the REST API!",
    "channel_ids": ["my_facebook_channel_id"],
    "image_object_ids": ["9f73ad62-xxxxx-xxxxx-xxxxx-9556dcb903f4"],
    "video_object_id": null,
    "gif_object_id": null,
    "facebook_settings": {
      "postType": "POST"
    },
    "instagram_settings": {
      "postType": "POST"
    },
    "pinterest_settings": {
      "pinTitle": "",
      "destinationLink": ""
    },
    "wordpress_settings": {
      "postTitle": "",
      "postText": "",
      "postSlug": "",
      "postType": "POST",
      "postCategories": [],
      "postTags": [],
      "postFeaturedImage": null,
      "postParentPage": 0
    },
    "youtube_settings": {
      "videoTitle": "",
      "videoType": "video",
      "videoDescription": "",
      "videoPrivacyStatus": "public",
      "videoThumbnailImageObject": null,
      "videoThumbnailGroupUuid": null
    },
    "tiktok_settings": {
      "title": "",
      "privacyLevel": "PUBLIC_TO_EVERYONE",
      "disableDuet": false,
      "disableComment": false,
      "disableStitch": false,
      "videoCoverTimestampMs": 0,
      "videoThumbnailGroupUuid": null,
      "autoAddMusic": true
    },
    "gmb_settings": {
      "postTopicType": "STANDARD",
      "offerTitle": "",
      "offerCouponCode": "",
      "offerRedeemOnlineUrl": "",
      "offerTermsConditions": "",
      "offerStartDt": null,
      "offerEndDt": null,
      "eventTitle": "",
      "eventStartDt": null,
      "eventEndDt": null,
      "ctaButtonActionType": "ACTION_TYPE_UNSPECIFIED",
      "ctaUrl": ""
    },
    "is_draft": false,
    "post_collection_id": null,
    "schedule_at": "2025-03-01T10:00:00Z",
    "is_recur": false,
    "recur_interval": "DAILY",
    "recur_generate_new_ai_image": false,
    "recur_generate_new_ai_image_model": "DALLE",
    "recur_until_dt": null,
    "recur_until_dt_enabled": false,
    "recur_rephrase_text_with_ai": false,
    "recur_rephrase_text_with_ai_tone": "FRIENDLY",
    "recur_interval_time_slots": []
  }
]

Request and Response Models

Below are the essential models for scheduling a post via the Robopost Public API.
These closely match the Python Pydantic models, but here we’ll describe them in a pure REST context.

PublicAPIScheduledPostCreateHTTPPayload

PublicAPIScheduledPostRead

Represents the newly created scheduled post (or draft) returned by the API. Most fields mirror those in the PublicAPIScheduledPostCreateHTTPPayload. Notable difference: the id is always set and additional fields reflect the final stored state.

FacebookSettings

InstagramSettings

PinterestSettings

WordpressSettings

YoutubeSettings

Note: The actual uploaded video is tied to video_object_id in the main payload. The videoType and videoPrivacyStatus further configure how YouTube handles it.

TikTokSettings

Note: The actual uploaded TikTok video is tied to video_object_id in the main payload.

GMBSettings

Enums

1. AIImageModel
   • DALLE, FLUX_SCHNELL, FLUX_DEV, FLUX_PRO
2. PostAIGenerateVoiceTone
   • Examples: POLITE, WITTY, INFORMATIONAL, FUNNY, FRIENDLY, etc.
3. AutomationRecurInterval
   • DAILY_SPECIFIC_TIME_SLOTS, WEEKLY_SPECIFIC_TIME_SLOTS, EVERY_3_HOURS, EVERY_6_HOURS, BI_DAILY, DAILY, WEEKLY, MONTHLY, YEARLY
4. FacebookPostType
   • POST, REELS
5. InstagramPostType
   • POST, REELS, STORIES
6. WordpressPostType
   • POST, PAGE (other types may be supported by your WP environment)
7. YoutubeVideoType
   • video, short
8. YoutubePrivacyStatus
   • public, private, unlisted
9. TikTokPrivacyLevel
   • PUBLIC_TO_EVERYONE
10. GMBPostTopicType
    • STANDARD, OFFER, EVENT
11. GMBCTAButtonActionType
    • ACTION_TYPE_UNSPECIFIED, BOOK, ORDER, SHOP, LEARN_MORE, SIGN_UP, CALL

Error Handling

The Robopost Public API responds with standard HTTP status codes to indicate success or failure:

Typical error responses include a JSON body describing the cause. For instance, if you try to schedule a post with no channel_ids (and is_draft=false), you’ll receive a 400 error.

Example Workflow

1. Upload Media (Optional)
   • POST /medias/upload?apikey=YOUR_API_KEY with multipart/form-data to get storage_object_id.
2. Create Scheduled Post
   • POST /scheduled_posts/?apikey=YOUR_API_KEY with a JSON body that includes:
     • channel_ids (unless you’re making a draft)
     • image_object_ids or video_object_id referencing any uploaded media
     • schedule_at in UTC
     • Any optional platform-specific settings (FacebookSettings, YouTubeSettings, etc.)
3. Receive Confirmation
   • The API returns an array of newly created post objects in JSON format.

Notes

• Dates/Times: Provide all datetimes in ISO 8601 format in UTC (e.g., "2025-03-02T15:30:00Z").
• Recurring Posts: If is_recur=true, you must specify recur_interval and any relevant fields for daily or weekly specific time slots (recur_interval_time_slots).
• Draft vs. Scheduled: Use is_draft=true for a draft (no immediate scheduling) or is_draft=false for an actual scheduled post.
• Post Collections: Provide post_collection_id if you want to group your posts; otherwise leave it as null or omit it.

For additional usage examples, please refer to the Python Client documentation or contact support.

Video Generation Endpoints

Video Series Management

Create Video Series

Create a new faceless video series configuration for generating multiple videos with consistent settings.

POST /video-series/

Authentication: apikey query parameter

Example Request

curl -X POST \
  "https://public-api.robopost.app/v1/video-series/?apikey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Educational Series",
    "content_type": "ELI5",
    "style": "ANIME",
    "voice": "ALICE",
    "lang": "en",
    "max_duration": 60,
    "format": "PORTRAIT",
    "font_size": 120,
    "font_color": "YELLOW",
    "position": "CENTER_BOTTOM",
    "channel_ids": ["channel_id_1", "channel_id_2"],
    "is_recur": true,
    "recur_interval": "DAILY",
    "timezone": "America/New_York"
  }'

Example Response

{
  "id": "series_123456",
  "name": "My Educational Series",
  "content_type": "ELI5",
  "style": "ANIME",
  "voice": "ALICE",
  "format": "PORTRAIT",
  "max_duration": 60,
  "is_recur": true,
  "recur_interval": "DAILY",
  "created_at": "2025-01-10T10:00:00Z",
  "updated_at": "2025-01-10T10:00:00Z"
}

List Video Series

Get all video series for your team with optional filtering and pagination.

GET /video-series/

Authentication: apikey query parameter
Query Parameters:

• search_text (optional): Search in series names
• skip (optional, default: 0): Number of items to skip
• limit (optional, default: 10, max: 100): Maximum items to return
• sort_by_field (optional, default: "created_at"): Field to sort by
• sort_order (optional, default: "desc"): Sort order ("asc" or "desc")

Example Request

curl -X GET \
  "https://public-api.robopost.app/v1/video-series/?apikey=YOUR_API_KEY&search_text=educational&limit=20"

Get Video Series

Retrieve a specific video series by ID.

GET /video-series/{series_id}

Authentication: apikey query parameter
Path Parameters:

• series_id: The ID of the video series

Example Request

curl -X GET \
  "https://public-api.robopost.app/v1/video-series/series_123456?apikey=YOUR_API_KEY"

Update Video Series

Update an existing video series configuration.

PUT /video-series/{series_id}

Authentication: apikey query parameter
Path Parameters:

• series_id: The ID of the video series Request Body: JSON object with fields to update

Example Request

curl -X PUT \
  "https://public-api.robopost.app/v1/video-series/series_123456?apikey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated Series Name",
    "max_duration": 90,
    "font_color": "RED"
  }'

Delete Video Series

Soft delete a video series (marks as deleted but preserves data).

DELETE /video-series/{series_id}

Authentication: apikey query parameter
Path Parameters:

• series_id: The ID of the video series

Example Request

curl -X DELETE \
  "https://public-api.robopost.app/v1/video-series/series_123456?apikey=YOUR_API_KEY"

Video Generation Tasks

Generate Video

Create a new video generation task from a video series.

POST /video-tasks/{series_id}/generate

Authentication: apikey query parameter
Path Parameters:

• series_id: The ID of the video series to generate from

Example Request

curl -X POST \
  "https://public-api.robopost.app/v1/video-tasks/series_123456/generate?apikey=YOUR_API_KEY"

Example Response

{
  "task_id": "task_789012",
  "video_series_id": "series_123456",
  "status": "IN_PROGRESS",
  "created_at": "2025-01-10T10:30:00Z"
}

Get Video Task Status

Check the status of a video generation task.

GET /video-tasks/{task_id}

Authentication: apikey query parameter
Path Parameters:

• task_id: The ID of the video task

Example Request

curl -X GET \
  "https://public-api.robopost.app/v1/video-tasks/task_789012?apikey=YOUR_API_KEY"

Example Response

{
  "task_id": "task_789012",
  "video_series_id": "series_123456",
  "video_url": "https://api.robopost.app/stored_objects/123456789/download",
  "status": "COMPLETE",
  "created_at": "2025-01-10T10:30:00Z"
}

List Video Tasks

List all video generation tasks with optional filtering.

GET /video-tasks/

Authentication: apikey query parameter
Query Parameters:

• series_id (optional): Filter by video series ID
• status (optional): Filter by task status
• skip (optional, default: 0): Number of items to skip
• limit (optional, default: 10, max: 100): Maximum items to return
• sort_order (optional, default: "desc"): Sort order by creation date

Example Request

curl -X GET \
  "https://public-api.robopost.app/v1/video-tasks/?apikey=YOUR_API_KEY&status=IN_PROGRESS&limit=50"

Get Video Task Details

Get detailed information about a video generation task including error messages and results.

GET /video-tasks/{task_id}/details

Authentication: apikey query parameter
Path Parameters:

• task_id: The ID of the video task

Example Request

curl -X GET \
  "https://public-api.robopost.app/v1/video-tasks/task_789012/details?apikey=YOUR_API_KEY"

Cancel Video Task

Cancel an in-progress video generation task.

DELETE /video-tasks/{task_id}

Authentication: apikey query parameter
Path Parameters:

• task_id: The ID of the video task

Example Request

curl -X DELETE \
  "https://public-api.robopost.app/v1/video-tasks/task_789012?apikey=YOUR_API_KEY"

Video Series Models

PublicAPIGeneratedFacelessVideoSeriesCreate

Video Task Response Model

Enums for Video Generation

GeneratedFacelessVideoSeriesContentType

• RANDOM_AI_STORY
• SCARY_STORIES
• BEDTIME_STORIES
• INTERESTING_HISTORY
• URBAN_LEGENDS
• MOTIVATIONAL
• FUN_FACTS
• LONG_FORM_JOKES
• LIFE_PRO_TIPS
• ELI5
• DID_YOU_KNOW
• PHILOSOPHY
• RECIPES
• FITNESS
• BEAUTY
• GROWTH_ADVICE
• PRODUCT_MARKETING
• CUSTOM
• BLOG_ARTICLE

GeneratedFacelessVideoStyle

• DEFAULT
• REALISM
• IMPRESSIONISM
• SURREALISM
• ABSTRACT
• ART_NOUVEAU
• CUBISM
• POP_ART
• FUTURISM
• FANTASY_CONCEPT_ART
• MINIMALISM
• WATERCOLOR
• GOTHIC_MEDIEVAL_ART
• ANIME
• COMIC

GeneratedVideoFormat

• PORTRAIT
• WIDESCREEN
• SQUARE

VideoColor

• BLACK, WHITE, YELLOW, RED, BLUE, GREEN, ORANGE, PURPLE, CYAN, MAGENTA

VideoCaptionPosition

• CENTER_CENTER, CENTER_TOP, CENTER_BOTTOM
• LEFT_CENTER, LEFT_TOP, LEFT_BOTTOM
• RIGHT_CENTER, RIGHT_TOP, RIGHT_BOTTOM

AI Voices

• ALICE, BILL, SARAH, BRIAN, LAURA, ARIA, CALLUM, CHARLIE
• Custom ElevenLabs voice IDs

Error Handling

Example Video Generation Workflow

1. Create a Video Series

curl -X POST \
  "https://public-api.robopost.app/v1/video-series/?apikey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Daily Facts Series",
    "content_type": "FUN_FACTS",
    "style": "POP_ART",
    "voice": "ARIA",
    "max_duration": 45,
    "format": "PORTRAIT",
    "channel_ids": ["instagram_channel_id"],
    "create_scheduled_post": true
  }'

2. Generate a Video

curl -X POST \
  "https://public-api.robopost.app/v1/video-tasks/series_123456/generate?apikey=YOUR_API_KEY"

3. Check Task Status

curl -X GET \
  "https://public-api.robopost.app/v1/video-tasks/task_789012?apikey=YOUR_API_KEY"

4. When Complete, Video is Automatically Posted (if create_scheduled_post was true)

Notes

• Credits: Video generation consumes credits based on your plan
• Processing Time: Videos typically take 20 minutes to generate
• Recurring Series: Use is_recur=true with appropriate interval settings for automated generation
• Knowledge Base: Link a knowledge base for content-aware video generation
• Custom Content: Use content_type="CUSTOM" with content_custom field for specific instructions

Robopost – all-in-one AI-driven social media management!
For more information, visit: robopost.app