REST workflow examples

REST source, visual, and publication sequences with operation IDs, polling intervals, and completion checks.

Publishing, source extraction, and visual generation use the Submit → Poll → Result pattern. Read the completion rules for the exact operation. For task instructions using MCP, start with Agent workflows.

System Prompt for Agents

You can use the following snippet to instruct your AI agent on how to interact with Blotato:

Blotato API Protocol: All creation operations (posts, videos, sources) are async.

1. Call the CREATE endpoint. Record the ID from the 201 response (id for sources, item.id for videos, postSubmissionId for posts). A scheduled post also returns scheduledTime, the resolved UTC publish time.

2. Check the GET endpoint at least 10 seconds apart for posts and sources, and at least 15 seconds apart for visuals.

3. Continue polling while status is processing (see status values below).

4. Stop on a terminal result. Report success only for the operation's success state, not for a failure or draft.

5. Set a waiting limit. Preserve the operation ID if processing remains unfinished. Do not submit a duplicate write because a poll failed or time elapsed.

Terminal Status Values by Operation:

• Sources: completed (success) or failed

• Videos: done (success), creation-from-template-failed, insufficient-credits, or any response with item.error. A draft is not a rendered result.

• Posts: published (success), failed, or scheduled for a future publication. Stop immediate polling after a scheduled result.

All Video Status Values (in order): queueing -> generating-script -> script-ready -> generating-media -> media-ready -> exporting -> done

Always fetch accounts first: GET /v2/users/me/accounts to get accountId for publishing. To get pageId for Facebook/LinkedIn or playlistIds for YouTube, also fetch GET /v2/users/me/accounts/{accountId}/subaccounts.

For social platforms, set content.platform and target.targetType to the same value (e.g., both "twitter"). The REST webhook target uses other with webhook.

Content Calendar: GET /v2/schedules to list scheduled posts. PATCH /v2/schedules/:id to update content or time. DELETE /v2/schedules/:id to cancel. GET /v2/schedule/slots for recurring time slots.

Full reference: API reference for agents.

---

1. Create Source -> Get Source

Goal: Research a topic or extract content from a URL so Blotato can generate related visuals.

Endpoints:

• Create: POST /v2/source-resolutions-v3

• Poll: GET /v2/source-resolutions-v3/:id

Source Types:

• youtube, tiktok, article, pdf, audio, twitter - Extract content from a URL (each type requires a url field)

• text - Transform raw text content with optional AI instructions

• perplexity-query - AI-powered web research on any topic (requires a text field)

Example Payloads

From YouTube URL:

{
  "source": {
    "sourceType": "youtube",
    "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
  }
}

From AI Research Query (use this for agents to research topics):

{
  "source": {
    "sourceType": "perplexity-query",
    "text": "latest trends in AI-generated content for social media"
  }
}

From Text with Custom Instructions:

{
  "source": {
    "sourceType": "text",
    "text": "Your raw content here..."
  },
  "customInstructions": "Summarize in 5 bullet points for Instagram carousel"
}

---

2. Create Visual -> Get Visual

Goal: Generate a video or image from a template.

Endpoints:

• Create: POST /v2/videos/from-templates

• Poll: GET /v2/videos/creations/:id

• Templates: GET /v2/videos/templates?fields=id,name,description,inputs

Discovering Templates

If you don't have a specific template ID, retrieve available templates:

GET https://backend.blotato.com/v2/videos/templates?fields=id,name,description,inputs&search=carousel

Choose the template for the requested output. An image carousel, a narrated video, and a clip compilation use different templates and input structures. Inspect the selected template's inputs before generating.

Visual Generation Flow

Example Payload (with AI Prompt)

{
  "templateId": "/base/v2/image-slideshow/5903b592-1255-43b4-b9ac-f8ed7cbf6a5f/v1",
  "inputs": {},
  "prompt": "Create a 5-slide carousel about productivity tips",
  "render": true
}

Example Payload (with Manual Inputs)

Replace the example image URLs with the user's accessible media URLs before submitting. These URLs illustrate the request structure, not content to publish.

{
  "templateId": "/base/v2/image-slideshow/5903b592-1255-43b4-b9ac-f8ed7cbf6a5f/v1",
  "inputs": {
    "slides": [
      {
        "imageSource": "https://example.com/slide-1.jpg",
        "textOverlay": "Introduction"
      },
      {
        "imageSource": "https://example.com/slide-2.jpg",
        "textOverlay": "Next step"
      }
    ]
  },
  "render": true
}

---

3. Create Post -> Get Post

Goal: Publish content to a social platform.

Endpoints:

• Create: POST /v2/posts

• Poll: GET /v2/posts/:postSubmissionId

• Account Lookup: GET /v2/users/me/accounts (docs)

• Subaccounts (for pageId): GET /v2/users/me/accounts/:accountId/subaccounts (docs)

n8n / Make.com users: Check the operations in your installed integration. If it exposes Get Post, pass the original postSubmissionId. Otherwise, use an HTTP request to GET /v2/posts/{postSubmissionId} with your Blotato credential. Do not assume all integration versions expose the same operations.

[!IMPORTANT] Prerequisites:

1. accountId: Get this from GET /v2/users/me/accounts. Always fetch the user's accounts before publishing. See Accounts reference.

2. pageId: Required for Facebook Pages and LinkedIn company Pages. Omit it for a LinkedIn personal-profile post. Get it from GET /v2/users/me/accounts/{accountId}/subaccounts. See How to Get the Right IDs.

3. mediaUrls: Use existing accessible media URLs, or mediaUrl and imageUrls from an authorized visual-generation request. No upload step required for these URLs. Do not generate new media for a request to publish an existing file. Text-only posts omit media when the selected platform supports them.

4. content.platform and target.targetType: For social platforms, set both to the same value (e.g., both "twitter").

Step 0: Fetch Available Accounts (Always Do This First)

GET https://backend.blotato.com/v2/users/me/accounts

Response:

{
  "items": [
    { "id": "98432", "platform": "twitter", "fullname": "Jane Smith", "username": "janesmith" }
  ]
}

For a Facebook Page or LinkedIn company Page, fetch subaccounts and select the requested pageId. Omit pageId for a LinkedIn personal profile. For YouTube, fetch subaccounts only when playlist placement is requested:

GET https://backend.blotato.com/v2/users/me/accounts/{accountId}/subaccounts

See Accounts reference for full details.

Publish Flow

Example Payload

{
  "post": {
    "accountId": "98432",
    "content": {
      "text": "Hello world!",
      "mediaUrls": ["https://database.blotato.io/user_1/media/vid_456.mp4"],
      "platform": "twitter"
    },
    "target": {
      "targetType": "twitter"
    }
  }
}

Get accountId from GET /v2/users/me/accounts. For social platforms, set content.platform and target.targetType to the same value.

To schedule instead of publishing immediately, add useNextFreeSlot or scheduledTime as a top-level field (sibling of post, not inside it). See Publish Post for details.

---

Complete End-to-End Workflow (Recommended for AI Agents)

This is the standard content creation sequence: research topic → create visual → publish to social.

Pseudocode for Agents

1. accountsList = GET /v2/users/me/accounts
2. sourceId = POST /v2/source-resolutions-v3 (specify sourceType: youtube, article, text, etc.)
3. LOOP: source = GET /v2/source-resolutions-v3/:sourceId
   - IF status = "completed": BREAK
   - IF status = "failed": STOP, report error
   - ELSE: WAIT at least 10 seconds, then check again
4. videoId = POST /v2/videos/from-templates (use source.content in prompt)
5. LOOP: video = GET /v2/videos/creations/:videoId
   - IF item.status = "done": BREAK
   - IF `item.error` is set: STOP, report error
   - IF item.status is "creation-from-template-failed" or "insufficient-credits": STOP, report error
   - IF item.status = "draft": STOP, report that no rendered result is available
   - ELSE: WAIT at least 15 seconds, then check again
6. postSubmissionId = POST /v2/posts (accountId from step 1, mediaUrl/imageUrls from step 5)
   - For social platforms, set content.platform and target.targetType to the same value
7. LOOP: post = GET /v2/posts/:postSubmissionId
   - IF status = "published": BREAK
   - IF status = "failed": STOP, check errorMessage
   - IF status = "scheduled": STOP, report scheduledTime
   - ELSE: WAIT at least 10 seconds, then check again
8. RETURN: post.publicUrl

---

4. Managing the Content Calendar

Goal: View, update, reschedule, or delete scheduled posts. Manage the recurring time slots that define your posting cadence.

How Slots and Schedules Work Together:

1. Slots define recurring time windows (e.g., "Monday 9 AM for Twitter"). Create them with POST /v2/schedule/slots.

2. When you publish with useNextFreeSlot: true, Blotato finds the next open slot matching the target platform and queues the post at that time.

3. A slot is "occupied" when a scheduled post is already queued at that time. The next useNextFreeSlot call skips occupied slots.

4. Schedules are the queued posts. Slots are the time windows. Manage them separately.

Endpoints:

• Schedules: GET /v2/schedules, GET /v2/schedules/:id, PATCH /v2/schedules/:id, DELETE /v2/schedules/:id (docs)

• Slots: GET /v2/schedule/slots, POST /v2/schedule/slots, PATCH /v2/schedule/slots/:id, DELETE /v2/schedules/slots/:id, POST /v2/schedule/slots/next-available (docs)

Schedule Response Shape

The draft field in a schedule is the same shape as the post object in Publish Post:

{
  "id": "sch_abc123",
  "scheduledAt": "2026-04-01T14:00:00.000Z",
  "account": {
    "id": "98432",
    "name": "Jane Smith",
    "username": "janesmith",
    "profileImageUrl": "https://...",
    "subaccountId": null,
    "subId": null,
    "subaccountName": null
  },
  "draft": {
    "accountId": "98432",
    "content": {
      "text": "Scheduled post content",
      "mediaUrls": [],
      "platform": "twitter"
    },
    "target": {
      "targetType": "twitter"
    }
  }
}

Note: The response uses scheduledAt for the publish time. The update endpoint accepts scheduledTime as the input field name.

Rescheduling to the Next Free Slot

The PATCH /v2/schedules/:id endpoint accepts scheduledTime but not useNextFreeSlot. To move a post to the next available slot:

1. POST /v2/schedule/slots/next-available
   Body: { "platform": "twitter", "accountId": "98432" }
   Response: { "slot": { "slotId": "slot_1", "slotTime": "2026-04-02T09:00:00Z" } }

2. PATCH /v2/schedules/sch_abc123
   Body: { "patch": { "scheduledTime": "2026-04-02T09:00:00Z" } }

Pseudocode for Calendar Management

1. schedules = GET /v2/schedules (paginate with cursor if needed)
2. Display scheduled posts to user (scheduledAt, account info, draft content)
3. To reschedule: PATCH /v2/schedules/:id { patch: { scheduledTime: "new ISO 8601" } }
4. To update content: PATCH /v2/schedules/:id { patch: { draft: { full post object } } }
5. To delete: DELETE /v2/schedules/:id
6. To reschedule to next free slot:
   a. nextSlot = POST /v2/schedule/slots/next-available { platform, accountId }
   b. PATCH /v2/schedules/:id { patch: { scheduledTime: nextSlot.slot.slotTime } }

---

Error Handling

All asynchronous operations can fail during processing. Handle failures gracefully:

Status Failure

When polling returns status: "failed", check the error message:

Source Failure (Get Source endpoint):

{
  "status": "failed",
  "message": "Unable to extract content from URL"
}

Video Failure (Get Visual Status endpoint):

{
  "item": {
    "status": "script-ready",
    "error": "2/5 media failed to generate. The video has been saved as a draft."
  }
}

Post Failure (Get Post Status endpoint):

{
  "postSubmissionId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "failed",
  "errorMessage": "Invalid account credentials"
}

Retry Strategy

• Don't retry automatically on failure - most failures are permanent

• Log the error message and report it to the user

• Inform user that the operation failed and provide next steps

• Retry failed reads after a delay. For a create request with an uncertain result, check existing work before resubmitting. For 429, wait and reduce request frequency. See Errors and retries.

---

Platform-Specific Setup

Different platforms require different fields and have different requirements. See detailed guides:

• Instagram Setup - Reels, Stories, Collaborators, Alt Text

• LinkedIn Setup - Company Pages, Professional Network

• Facebook Setup - Page ID, Media Types

• Platform Requirements - All platforms at a glance

When publishing, always include the required fields for the target platform:

• Facebook: target.pageId (required), target.mediaType -- required "reel" for videos (regular feed videos no longer supported), optional "story" for Stories, omit for text/image posts

• LinkedIn: target.pageId (optional)

• Pinterest: target.boardId (required)

• YouTube: target.playlistIds (optional - array of playlist IDs from subaccounts)

• TikTok: target.privacyLevel, target.disabledComments, etc. (required)

• Instagram: target.mediaType (optional - default is "reel")

• Twitter, Threads, Bluesky: Minimal required fields