Schedule social media posts with a REST API

The complete sequence

To schedule a post through Mellow Hub, identify the credential’s authority, select connected channels, validate one request, then create it with a stable idempotency key. Read the resulting post again to establish what happened on each destination. A successful create response is not proof that every network published it.

This recipe uses REST. An MCP client follows the equivalent whoami → list_channels → validate_post → create_post → get_post sequence described in the social media MCP guide.

1. Check the account and credential

Connect your own channels in Hub and create a credential with the channels and mode you intend to delegate. Store it in your server’s secret environment as MELLOW_HUB_KEY; never put it in frontend JavaScript or a public repository. The examples read that environment variable without displaying its value.

curl --fail-with-body https://www.mellow.world/api/hub/v1/whoami \
  -H "Authorization: Bearer $MELLOW_HUB_KEY"

curl --fail-with-body https://www.mellow.world/api/hub/v1/channels \
  -H "Authorization: Bearer $MELLOW_HUB_KEY"

Use the channel IDs returned for this account. The spc_… values below are placeholders. Check the mode and available allowance before creating anything. A review credential prepares a post for a person to approve. An autopilot credential can act within its delegated scope, ceiling and expiry.

2. Describe the actual post

Save the following structure as post.json. Replace both channel IDs, the sample media address, the text and the example date. Use an explicit ISO 8601 timezone offset or UTC Z; the timestamp represents an instant, not the reader’s local clock. The sample’s 2030 date is deliberately illustrative.

{
  "caption": "A short look at how this piece was made.",
  "channels": ["spc_your_instagram_channel", "spc_your_youtube_channel"],
  "media": ["https://cdn.example.com/your-video.mp4"],
  "scheduledAt": "2030-01-15T10:00:00Z",
  "options": {
    "instagram": { "placement": "reels" },
    "youtube": { "title": "How this piece was made", "privacyStatus": "public" }
  }
}

The network fetches media at publication time, so the real HTTPS URL must remain reachable then. A private local file or an expired signed URL will not work. This example gives YouTube its separate title while selecting the Reels placement for Instagram. Format availability still depends on your connected accounts and the provider.

3. Validate without publishing

curl --fail-with-body https://www.mellow.world/api/hub/v1/validate \
  -H "Authorization: Bearer $MELLOW_HUB_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @post.json

Inspect the response’s ok, issues and notes. Correct every blocking issue before continuing. Validation can return HTTP 200 with ok: false, so checking the HTTP status alone is insufficient. The authenticated endpoint checks your actual channel ownership as well as input rules.

For an account-free preview of caption, title and media-count checks, use the free post checker. Neither preview measures the duration or aspect ratio of your actual file, and a provider can still reject delivery.

4. Create once, retry consistently

The next request creates the post. Run it only when the content and destination authority are correct. Under review mode it waits for approval; under autopilot the delegated action can proceed at the scheduled time.

curl --fail-with-body https://www.mellow.world/api/hub/v1/posts \
  -H "Authorization: Bearer $MELLOW_HUB_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: studio-process-video-slot-001" \
  --data-binary @post.json

Persist the idempotency key alongside the job in your application. If the response is lost, retry the same request with the same key. Do not create a new key just because a timeout occurred. A different post needs a different key; reusing one for changed content is rejected.

5. Read the result per destination

Save the returned post.id and retrieve it with GET /api/hub/v1/posts/{id}, using the same authorization header. Inspect each entry in targets and its public URL. A multi-network post may be partial: one destination can succeed while another fails.

Keep the planned time, Hub post ID, idempotency key and destination outcomes together in your own job record. Avoid logging credentials or full authorization headers. When a target fails, use its reported error to decide the next action rather than blindly recreating the entire post.

Questions that come up in real integrations

Can I use a different caption on one network?

Yes. A perChannel entry keyed by the real channel ID overrides that channel’s caption or media. Platform-wide fields belong in options. See the worked examples in the Hub reference.

Can an agent connect my social accounts by itself?

No. The account owner completes the relevant connection flow. An API key is delegation for already authorized actions, not permission to impersonate the owner at a network’s login screen.

Does one request use one publication from my plan?

The allowance is counted per network destination. Check the current plans and the credential’s remaining allowance before choosing targets.