API reference

Lists every connection of yours that has not been deleted, with the slug you use to post to it and the timezone and posting slots its queue runs on.

Rate limit: 60 requests per minute per API key.

Returns one connection of yours, with the timezone and posting slots its queue runs on.

Rate limit: 60 requests per minute per API key.

The posts this connection has queued and not sent yet, earliest slot first. A post leaves the queue when it goes out, fails, or is cancelled with DELETE /posts/{postId}, and cancelling hands its slot back to the next post queued.

Rate limit: 60 requests per minute per API key, shared with PATCH /connections/{connectionId}/queue.

Replaces the connection's slot list, its timezone, or both. Send at least one of them.

Slots are wall times on the connection's own clock: a slot of { "weekday": 1, "time": "09:00" } with timezone Europe/Helsinki is 09:00 in Helsinki, whatever the offset is that week. At most 50 slots, and no two the same.

Changing the slots does not move posts that are already queued. A queued post was scheduled the moment it was queued, so it keeps the time it was given; the new slots decide where the next queued post lands.

Rate limit: 60 requests per minute per API key, shared with GET /connections/{connectionId}/queue.

Creates one end customer's profile. Connect accounts into it with the console, then post to them with profileId.

Rate limit: 60 requests per minute per API key.

Lists your profiles, newest first.

Rate limit: 60 requests per minute per API key.

Reads one profile of yours.

Rate limit: 60 requests per minute per API key.

Changes a profile's name, its external id, or both. Its connections are untouched.

Rate limit: 60 requests per minute per API key.

Deletes the profile and disconnects every account inside it: the credentials are deleted, the posts that already went out stay readable, and anything still waiting to be sent is cancelled. Your bill drops to the connections you have left.

Rate limit: 60 requests per minute per API key.

Answers with a hosted page you send your end customer to. They connect one of their own accounts into this profile there and come back to your redirectUrl with the connection on the query.

The link works once and lasts fifteen minutes. It carries the whole authorization: nobody signs in to yeetpost, and the page never shows your key, your email or anything about your other customers.

When an account was connected, the customer lands on your redirectUrl with connectSessionId, connectionId, profileId, slug and platform added to its query. When they cancelled or the platform refused, they land with connectSessionId and error (cancelled or connect_failed) instead, and no connection was made. Any query string your redirectUrl already carries is kept; these parameters are added to it.

A test key opens a session that offers the sandbox and nothing else, which is how you run the whole flow in CI without connecting anybody's account.

A key scoped to a profile may only open sessions for that one; another profile answers 403 forbidden. When the key carries a redirect allowlist, redirectUrl must be on one of its origins.

Rate limit: 60 requests per minute per API key.

How a connect link ended, for when you would rather poll than read the query your customer came back on. Both say the same thing.

Rate limit: 60 requests per minute per API key.

Mints an API key scoped to this profile and answers with it once. The key is what an integration acting for that one end customer holds: it reads and posts inside the profile and can reach nothing else, whatever the call says.

secret is the key itself and appears in this answer only. No API endpoint reads the secret back; the account owner can reveal any key in the console. Store it now, mint another, or go and look it up as yourself.

Only an unscoped key mints keys, and a key minted here is always scoped: there is no way to ask this endpoint for a key that reaches the account. A test key mints test keys only, so a CI run cannot produce something that publishes.

Rate limit: 60 requests per minute per API key, and 20 mints an hour per account. The second window is there because minting is the one call that makes more callers: every key it hands back carries a per-key budget of its own.

Lists the keys scoped to this profile, oldest first. Keys are listed by their first characters; no API endpoint reads the secret back, and the account owner can reveal any key in the console.

A test key sees the test keys and no live ones, the same rule that stops it revoking a live key.

Rate limit: 60 requests per minute per API key.

Revokes one key of this profile. The key stops authenticating immediately, on every surface at once, and the row stays so the key still lists with includeRevoked=true.

Revoking is idempotent: a key that was already revoked answers the same 200, and the time it was first revoked stays.

One thing outlives the key: a connect URL it already issued keeps working for the rest of its fifteen minutes. The link carries its own single-use token and was authorized when it was created, so revoking the key that made it does not close it.

A test key may revoke test keys only. A live key of yours answers 404 not_found to a test key, the same answer a key of somebody else's account gets, so test credentials cannot be used to probe for live key ids.

Rate limit: 60 requests per minute per API key.

Lists your account's own keys, the unscoped ones and every profile's, oldest first, each with the profile it is scoped to. Keys are listed by their first characters; no API endpoint reads the secret back, and the account owner can reveal any key in the console.

Only an unscoped key may read this: a scoped key gets 403 forbidden rather than a listing of one. A test key sees the test keys and no live ones.

Rate limit: 60 requests per minute per API key.

Revokes any key of your account, scoped or not. The key stops authenticating immediately.

A key may revoke itself: the call answers 200, and the next request made with it is 401 unauthorized.

Revoking is idempotent: a key that was already revoked answers the same 200, and the time it was first revoked stays.

One thing outlives the key: a connect URL it already issued keeps working for the rest of its fifteen minutes. The link carries its own single-use token and was authorized when it was created, so revoking the key that made it does not close it.

A test key may revoke test keys only. A live key of yours answers 404 not_found to a test key, the same answer a key of somebody else's account gets, so test credentials cannot be used to probe for live key ids.

Rate limit: 60 requests per minute per API key.

Uploads one image and answers with the id you attach to a post. The body is the raw file, not a multipart form: set Content-Type to the image type and send the bytes. The bytes have to be that type: a file whose signature disagrees with the header is rejected with 400 invalid_media_type.

Images are free. The only limits are size: 8 MB per image, 50 MB stored per account, and 5 images per post. Delete images you no longer need to make room.

Uploading the same bytes twice is one image. The second upload answers with the id of the first and costs nothing against your allowance, so a client that retries an upload cannot fill your storage with copies. If the second upload carries alt_text and the stored image has none, the description is kept; if the stored image already has one, it wins and the new one is ignored. Give a post its own altText to override either.

Rate limit: 60 requests per minute per API key.

Serves the bytes back, with the Content-Type they were uploaded as. The response also carries X-Content-Type-Options: nosniff and Content-Disposition: inline, so a browser renders it as the type it is and never guesses another. Only your own images: somebody else's id answers 404.

Rate limit: 60 requests per minute per API key.

Deletes the image and frees the storage. Posts that used it keep their text and lose the image, so delete an image only once the posts that need it have gone out. A scheduled post whose images were deleted sends as text.

Rate limit: 60 requests per minute per API key.

The one-liner endpoint: the request body is the post itself, as plain text. It posts to a single connection and is the simplest thing to call from a shell script or a cron job.

This is the original v2 endpoint and it is not going away, but new integrations should prefer POST /posts, which takes JSON, posts to several connections at once, supports Idempotency-Key, and returns the post id.

Content-Type must be text/plain or application/x-www-form-urlencoded, or be omitted; anything else is rejected with 415.

Rate limit: 60 requests per minute per API key.

Posts the same text to every connection in connectionSlugs, immediately, at scheduledFor, with queue: true into each connection's next free posting slot, or with isDraft: true into a draft that goes nowhere until you publish it. Duplicate slugs are ignored.

Partial failures are normal. As long as at least one slug matches a live connection, the response is 200 and every connection gets its own entry in results with a status of sent, scheduled or failed. Check the per-item status and error, not just the HTTP status. The request as a whole only fails (400 invalid_connection) when none of the slugs match a connection of yours.

Idempotency. Send an Idempotency-Key header to make retries safe: the first request stores its response under the key and any later request with the same key and the same body replays that stored response verbatim, without posting again. Keys live for 24 hours and are scoped to your account.

Rate limit: 60 requests per minute per API key, shared with GET /posts.

Your posts, newest first, one row per connection they went to.

Rate limit: 60 requests per minute per API key, shared with POST /posts.

Returns one post of yours. Posts belonging to someone else are 404, same as posts that do not exist.

Rate limit: 60 requests per minute per API key, shared with DELETE /posts/{postId}.

One verb, three meanings, decided by what the post is.

A post that is still waiting to be sent is cancelled: the row is kept and moves to status cancelled, and nothing was published in the first place. If the worker claims the post while your request is in flight you get 409 post_not_cancellable.

A draft is deleted: a draft never went out, so there is no record to keep. The answer is { id, deleted: true } and the row and its images are gone.

A post that already went out is deleted on its platform: the head post and every reply this send published under it come down, newest first, and the row moves to status deleted with a deletedAt. X, Bluesky, Mastodon, Telegram, Discord and LinkedIn have a delete; SMS, email and Slack do not and answer 400 delete_unsupported. A platform that refuses the delete answers 422 platform_rejected and the post stays up. Deleting the same post twice answers 200 with the same body: it is already gone.

Nothing is refunded. X charges per tweet when the post goes out and keeps that fee for a tweet you delete later.

Rate limit: 60 requests per minute per API key, shared with GET /posts/{postId}.

Edits a draft in place: its text, its shape, its images and its tags. Only what you send is written.

Only drafts can be edited. A post that is sent, scheduled, cancelled or failed is a record of what happened, so editing one is 400 invalid_request. Whatever the draft ends up holding is validated against its connection again, so an edit cannot leave it in a shape the connection could never publish.

Rate limit: 60 requests per minute per API key, shared with GET /posts/{postId}.

Turns a draft into a real send: now, at scheduledFor, or with queue: true into the connection's next free posting slot. The stored text, shape, images and tags go out, and the post keeps the id it had as a draft, so an id you are already holding stays valid.

From here on it is an ordinary post: it is billed, counted against your limits and fair-use cap, and it fires webhooks. The draft keeps the mode it was created with, so one stored by a test key publishes as a test post whichever key publishes it, and it goes to the connection it was created against by id: delete that connection and the publish is 400 invalid_connection, even if a new connection has taken its slug.

A refusal you can still settle leaves the draft exactly where it was, so you can fix the problem and publish the same id again: queue_empty, queue_full, payment_method_required, spend_cap_reached and fair_use_reached. Every other refusal is what happened to the post, so the draft becomes a failed post.

A post id that is not a draft any more is 404 not_found, which is what a second publish of one draft gets. Two publishes of one draft at the same moment settle the same way, one 200 and one 404, and the post goes out once.

Takes an Idempotency-Key the same way POST /posts does.

Rate limit: 60 requests per minute per API key.

The numbers yeetpost has read back from the platform for one post: the newest read, and every read before it.

A post is read an hour after it goes out, then hourly for 48 hours, then once a day until it is 30 days old. Before the first read latest is null.

What each platform reports differs, and a number a platform does not report is null rather than 0. Bluesky and Mastodon give likes, reposts and replies for free. LinkedIn gives likes and comments on any share, and impressions and clicks only on a page. X gives impressions, likes, reposts and replies, and X charges for the read, so it is off unless the account has X analytics enabled.

Rate limit: 60 requests per minute per API key.

Every post that went out in a window, with the newest numbers read for each of them.

Counters are running totals, so a post counts once, at whatever its newest read said. A post counts on the day it went out, which is what makes days a series you can chart.

The window is named in whole UTC days at both ends. Left out, it is the last 30 days, which is exactly as long as a post's numbers are refreshed for. The longest window is 365 days.

Scoped like everything else: a test key counts sandbox posts only, and a key scoped to a profile counts that profile's posts only.

Rate limit: 60 requests per minute per API key.