Skip to content
Skimbly
Start free

Skimbly API

Schedule posts from your own code or an AI assistant.

Last updated October 25, 2026

Getting started

The API does what you do in Skimbly: list your accounts, write drafts, schedule or queue posts, add images and videos, and see how each post did. It acts as you, with the same checks and plan limits as the app.

  1. Open Settings, API keys and make a key. Copy it: Skimbly shows it only once.
  2. Send it with every request, then try this:
curl https://skimbly.com/api/v1/me \
  -H "Authorization: Bearer skm_your_key"

Every address below starts with https://skimbly.com/api/v1. Bodies are JSON (Content-Type: application/json), and so are answers. The full description is at /api/v1/openapi.json (OpenAPI 3.1), for tools and AI assistants.

AI assistants (MCP)

Claude and other AI assistants can schedule through Skimbly with its MCP server at https://skimbly.com/mcp. Ask in plain words, like “queue a post about our launch to LinkedIn and Threads”, and the assistant writes, checks and schedules it with your plan's limits.

Connect it with an API key, sent as a header:

  • Claude (Pro, Max and Team): add a custom connector with the address above and the header Authorization: Bearer skm_your_key.
  • Claude Code: run the line below.
  • Cursor and other assistants: add a remote (HTTP) MCP server with the same address and header.
claude mcp add --transport http skimbly https://skimbly.com/mcp   --header "Authorization: Bearer skm_your_key"

The assistant can list your accounts and posts, write drafts, schedule, queue or reschedule posts, add images from a link, and delete posts. Skimbly tells it to post straight away or delete only when you ask. ChatGPT needs a sign-in flow instead of a key; it is coming next.

API keys

Anyone with a key can schedule and delete posts on your accounts, so keep it like a password and never put it in a web page or an app people download. You can have 5 keys; Settings shows when each was last used. Revoke a key there and it stops working at once.

Accounts

GET /accounts lists your connected accounts with their id, network and handle. Posts go to accounts by id. When needs_reconnect is true the account's access expired: reconnect it in Skimbly before posting to it.

GET /me gives your plan, timezone and this month's usage (posts, X credits, storage).

Posts

POST /posts makes a post. mode says what happens to it:

  • draft (the default) saves it without posting.
  • schedule posts it at scheduled_at, a time with a UTC offset at least 2 minutes ahead.
  • queue puts it in the next free posting time that all its accounts share, as Add to queue does.
  • publish posts it now. The answer's sent says posted, failed (with sent_errors) or sending when a network is slow: read the post again in a minute.
curl https://skimbly.com/api/v1/posts \
  -H "Authorization: Bearer skm_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Our new guide is out: skimbly.com/blog",
    "account_ids": ["8f1c...", "2b7e..."],
    "mode": "schedule",
    "scheduled_at": "2026-11-03T09:30:00+05:30",
    "network_text": { "x": "New guide: skimbly.com/blog" }
  }'

Other fields: network_text (own text per network), media (a list of { id, alt } from the media endpoints) and follow_ups (replies posted under it, each with text and delay_minutes: 0, 1, 5, 15, 60), tag_ids (from GET /tags), repeat (day, 2days, 3days, week, 2weeks, month; scheduled and queued posts only) and network_settings, like { "threads": { "replies": "following" } } or { "linkedin": { "visibility": "connections" } } (all options are in the OpenAPI file). The answer is the post, with its status, scheduled_at and a link to it in Skimbly.

Safe retries

Send an Idempotency-Key header (any unique string, like a UUID) with a POST. If the connection drops and you send it again with the same key, you get the first answer back, marked Idempotent-Replayed: true, instead of a second post. Keys are kept for 24 hours; using one for a different request answers 422.

List and read

GET /posts lists posts, newest first; ?status=scheduled lists what is coming, soonest first. Other statuses: draft, posted, failed. Pages hold 20 posts (?limit= up to 100); pass next_cursor as ?cursor= for the next page.

GET /posts/{id} gives one post. Each of its destinations has its status, the live link once published, an error when it failed, and stats (likes, replies and the rest) where the network gives them.

Change, reschedule, delete

PATCH /posts/{id} changes a draft, scheduled or failed post. Send only what changes. To move it, send scheduled_at; to queue it again, { "mode": "queue" }; to schedule a draft, mode and scheduled_at.

DELETE /posts/{id} deletes it from Skimbly. Posts already published stay on the networks.

Images and videos

From a link: POST /media with { "url": "https://..." }. Skimbly downloads the image (JPEG, PNG, WebP or GIF, up to 10 MB) and answers with its id.

From a file: POST /media/uploads with the file's kind, name, type and size in bytes (a video also needs width, height and duration in seconds). For an image, PUT the file to upload_url. For a video, PUT each part_size slice to its link in part_urls and keep each answer's ETag. Then POST /media/{id}/complete (for a video with { "parts": [{ "part_number": 1, "etag": "..." }] }). Images up to 10 MB, videos up to 200 MB.

curl -X PUT --upload-file photo.jpg "<upload_url>"

Each network's own limits still apply when you post (Bluesky takes images up to 1 MB, Instagram JPEG only). Media not used in a post within a day is removed, and it counts toward your plan's storage.

Errors

Errors answer with a status code and { "error": { "code", "message", "details" } }. message says what to fix, and details names each field that is wrong.

  • 400 the request or the post is not valid (invalid_request, invalid_post, for example a used-up monthly limit or text over a network's limit).
  • 401 no key, or the key is not valid or was revoked.
  • 404 nothing with that id, or it is not yours.
  • 409 the post has started going out, so it can no longer change (or a request with the same Idempotency-Key is still running).
  • 422 the Idempotency-Key was used for a different request.
  • 413, 415 the body is over 256 KB, or is not JSON.
  • 429 too many requests (see below).

Limits

Each key can make 60 requests a minute. Over that, the API answers 429 with Retry-After; wait and try again.

Your plan's limits are the same as in the app: posts a month, connected accounts, X credits and storage. See pricing. Links to images and videos in answers work for an hour; read the post again for fresh ones.