Schedule posts from your code, or from your AI assistant.

Five steps from zero to a published post. Every example uses curl; set your key once with export POSTYAY_API_KEY=pyk_live_….

1. 1

   Create an API key

   Go to Settings → API keys, give the key a name (e.g. “Zapier” or “Claude”) and copy it. You’ll only see it once; we store just a hash.

2. 2

   List your connected accounts

   Connect TikTok or Bluesky in the app first. Each account’s id is what you post to; health tells you if it needs reconnecting.

   curl https://postyay.com/api/v1/accounts \
     -H "Authorization: Bearer $POSTYAY_API_KEY"

3. 3

   Upload a video or photo

   Send the file as multipart, or give us a public URL and we download it. Keep the returned id. We convert the format for each platform when it publishes.

   curl https://postyay.com/api/v1/media \
     -H "Authorization: Bearer $POSTYAY_API_KEY" \
     -F [email protected]
   
   # or let postyay download it
   curl https://postyay.com/api/v1/media \
     -H "Authorization: Bearer $POSTYAY_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{ "url": "https://example.com/clip.mp4" }'

4. 4

   Schedule the post

   One post, several accounts. TikTok needs settings.privacyLevel. schedule is "now", an ISO 8601 time, or "draft". The same pre-flight checks as the app run first, and anything that would fail comes back as violations.

   curl https://postyay.com/api/v1/posts \
     -H "Authorization: Bearer $POSTYAY_API_KEY" \
     -H "Content-Type: application/json" \
     -H "Idempotency-Key: $(uuidgen)" \
     -d '{
       "text": "Behind the scenes of the shoot #bts",
       "mediaIds": ["MEDIA_ID"],
       "targets": [
         { "accountId": "TIKTOK_ACCOUNT_ID",
           "settings": { "privacyLevel": "PUBLIC_TO_EVERYONE", "allowComment": true } },
         { "accountId": "BLUESKY_ACCOUNT_ID",
           "settings": { "altText": { "MEDIA_ID": "A camera crew on set" } } }
       ],
       "schedule": "now"
     }'
   
   # "schedule": "2026-10-01T09:00:00+03:00" schedules it, "draft" only saves it.

5. 5

   Follow it until it’s live

   Poll the post every few seconds. When status is published, each target has its live url. TikTok videos can take a few minutes to process.

   while :; do
     status=$(curl -s https://postyay.com/api/v1/posts/POST_ID \
       -H "Authorization: Bearer $POSTYAY_API_KEY" | jq -r .status)
     echo "$status"
     case "$status" in published|failed|needs_action|canceled) break ;; esac
     sleep 5
   done

   {
     "id": "5b0e…",
     "status": "published",
     "source": "api",
     "targets": [
       { "platform": "tiktok", "status": "published",
         "url": "https://www.tiktok.com/@you/video/7431…" },
       { "platform": "bluesky", "status": "published",
         "url": "https://bsky.app/profile/you.bsky.social/post/3l…" }
     ]
   }

Send the key in the Authorization header of every request: Bearer pyk_live_….

• A key acts as the member who created it, in that workspace. If they leave the workspace, the key stops working.
• Revoke a key in Settings at any time; it stops working immediately. Last-used times help you spot keys you no longer need.
• Treat keys like passwords: keep them on your server or in your assistant’s settings, never in a browser, a mobile app or a public repository.

Every error has the same shape. requestId is also in the x-trace-id header: quote it when you contact support.

{
  "code": "PREFLIGHT",
  "message": "TikTok allows 2,200 characters — you're 100 over.",
  "requestId": "3f0c9d2e-…",
  "violations": [
    { "accountId": "…", "platform": "tiktok", "code": "text_too_long",
      "message": "TikTok allows 2,200 characters — you're 100 over.",
      "params": { "max": 2200, "over": 100 },
      "fix": { "mode": "manual", "action": "shorten_text" } }
  ]
}

VALIDATION_ERROR adds details (the fields that are wrong). PREFLIGHT adds violations: one per problem, with the account, the platform and a stable code such as text_too_long or media_required.

Limits are per key, in one-minute windows: 60 requests a minute, of which at most 10 may create posts. MCP tool calls count against the same budget.

Every response says where you stand with RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset (seconds) and RateLimit-Policy. Over the limit you get 429 RATE_LIMITED with Retry-After.

RateLimit-Policy: 60;w=60, 10;w=60;comment="posts"
RateLimit-Limit: 60
RateLimit-Remaining: 0
RateLimit-Reset: 23
Retry-After: 23

Posts also count toward your plan’s monthly post limit, exactly like posts made in the app. GET /api/v1/me shows your usage.

Lists return { data, nextCursor }, newest first. Pass limit (1–100, default 25) and, for the next page, cursor=nextCursor. nextCursor is null on the last page. GET /api/v1/posts also filters by status, accountId, from and to.

curl "https://postyay.com/api/v1/posts?status=scheduled&limit=50" \
  -H "Authorization: Bearer $POSTYAY_API_KEY"

# next page
curl "https://postyay.com/api/v1/posts?status=scheduled&limit=50&cursor=NEXT_CURSOR" \
  -H "Authorization: Bearer $POSTYAY_API_KEY"

Network hiccups happen. Send an Idempotency-Key header (any unique string, e.g. a UUID) with POST /api/v1/posts and retry freely: for 24 hours, the same key with the same body returns the first result with Idempotent-Replayed: true instead of creating a second post. The same key with a different body is refused.

A post goes to one or more accounts; each is a target with its own status. The post’s status is the most urgent of its targets’.

draft

Saved, not scheduled.

scheduled

Waiting for its time.

queued

Due; picked up for publishing.

preparing

Media is being converted for the platform.

publishing

Being sent to the platform.

processing

The platform accepted it and is processing it.

published

Live; the target has its url.

needs_action

Someone has to act (e.g. reconnect the account); see error.

failed

Gave up after retries; see error.

canceled

The post was deleted before it published.

postyay speaks the Model Context Protocol, so AI assistants can schedule posts for you: “post this clip to TikTok and Bluesky tomorrow at 9”. It uses the same API key, limits and checks as the REST API.

Tools

• list_accountsConnected accounts with their ids and health.
• upload_media_from_urlDownloads a video, photo or PDF from a public URL.
• create_postCreates and schedules a post (now, a time, or draft), with pre-flight feedback.
• schedule_postSchedules an existing draft.
• list_postsPosts with their status, filtered and paginated.
• get_post_statusOne post’s delivery timeline and live URLs.
• reschedule_postMoves a post to a new time.
• delete_postDeletes a post and cancels what hasn’t published.
• get_best_timeSuggests a time to post. For now a fixed heuristic (tomorrow 09:00 in your time zone), not audience data, and it says so.

Connect your assistant

Claude Code

One command adds the server with your key:

claude mcp add --transport http postyay https://postyay.com/mcp \
  --header "Authorization: Bearer pyk_live_…"

Claude Desktop

Add this to claude_desktop_config.json (Settings → Developer → Edit config) and restart Claude. mcp-remote bridges the remote server and sends your key as a header.

{
  "mcpServers": {
    "postyay": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://postyay.com/mcp",
               "--header", "Authorization:${POSTYAY_API_KEY}"],
      "env": { "POSTYAY_API_KEY": "Bearer pyk_live_…" }
    }
  }
}

Cursor, VS Code and other clients

Any client that lets you set HTTP headers on a remote MCP server works with the URL and the header:

{
  "mcpServers": {
    "postyay": {
      "url": "https://postyay.com/mcp",
      "headers": { "Authorization": "Bearer pyk_live_…" }
    }
  }
}

Generated from the same schemas the API validates with. Base URL: https://postyay.com/api/v1. Import the OpenAPI document into Postman, Insomnia or your code generator.