The Rutba Relay API

The one call the portal makes on every page load. Shape is stable — the portal builds on it.

Outstanding first. Tokens are never returned — a link is shown once, at mint.

Returns a single-use URL that lets somebody outside the organisation authorise one account. The link carries no API key and can do nothing else. Send it to the person who holds the platform credentials.

Kills a link that has not been used yet — the one thing you need when a link went to the wrong chat.

For platforms whose auth.kind is not oauth2. The required fields are listed by GET /v1/platforms. OAuth platforms use POST /v1/oauth/{platform}/start instead.

Metadata is merged, not replaced. This is how per-connection settings are set — e.g. {"metadata":{"channel":"#general"}} for Slack.

Deletes the stored credentials. Deliveries already published stay in history; pending ones for this connection are cancelled.

Calls the platform. Refreshes the cached handle and display name, and flags the connection if the platform has stopped accepting it.

Returns an authorization URL to send the account owner to. The connection appears once they approve and the platform redirects back.

One row per (post, destination), newest first. Filterable by platform, status, post, connection and date, and keyset paginated with cursor.

status and platform accept comma-separated lists — "which Instagram and Threads deliveries failed this week" is one request, not two.

Requeues a single failed delivery, leaving every other destination of the same post alone — including ones that succeeded, which is the whole point: eight platforms took the post and Reddit was rate-limited.

A rejected delivery is not retried. The platform refused the content, and sending the same bytes again fails identically; edit the post instead.

Send content plus targets. Targets can be given three ways: targets (with per-target overrides), connection_ids, or platforms (every active connection on those platforms).

Returns 202 with a post id and one delivery per target. Deliveries settle independently — watch them with webhooks or GET /v1/posts/{id}.

Send an Idempotency-Key header. A repeat of the same request returns the original response instead of publishing twice.

Drafts and scheduled posts only. A published post cannot be edited — the relay cannot reach into fifteen networks and change what is already there — so it is refused with a pointer at POST /v1/posts/{id}/duplicate.

The post is re-projected against every target, so a target that was refused at validation gets another chance: the edit may be the fix. Changing the targets rewrites the deliveries; leaving them out keeps the ones there are.

scheduled_at: null unschedules, turning a scheduled post back into a draft.

Only pending deliveries are cancelled. Anything already published stays published — the relay cannot un-post.

Newest first. A row with no decided_at is an open review. "Rejected twice before it went out" is a question this answers and a single status column cannot.

Reposting is the most common thing a customer does after publishing. The copy is a draft aimed at the same accounts, and nothing is sent until you call publish or schedule.

Targets whose connection is no longer usable are dropped and listed in dropped_targets — a duplicate of a post from June should not look ready to send to an account that was revoked in July.

external_id is not copied: it names one record in your system, and two posts claiming it would break every lookup by it.

The body is optional — a bare POST duplicates as a plain draft. It may carry external_id, source, scheduled_at and timezone.

The most recent reading collected for each of the post's deliveries.

Every field is nullable and a null is not a zero: platforms report different things, and most report no impressions at all. A total is absent when no platform supplied that number, rather than being summed as zero — "nobody counted" and "nobody saw it" are different answers.

Readings are collected on a schedule that decays with the post's age and stops after a week, so next_collection_at is null for an older post and collected_at is when the platform was last asked, not when it counted.

Queues every pending delivery immediately. A scheduled post can be released early this way — its delayed jobs are removed first, so it goes out once rather than now and again at the time nobody wants any more.

Targets refused at validation stay refused: publishing is not a retry, and sending content a platform already rejected would fail identically.

Requeues deliveries in failed state. Deliveries in rejected state are not retried — the platform refused the content, and sending it again would fail identically.

Works on a draft and on an already-scheduled post: the delayed job is removed and re-added, because BullMQ ignores an add for a job it already holds and the time would otherwise silently not move.

scheduled_at takes an ISO instant ("2026-08-17T04:00:00Z") or a local wall clock ("2026-08-17T09:00") read in timezone, then yours, then the organisation's. When the clocks change under that local time the response carries a schedule_notice saying how it was resolved.

A delivery already being published is left exactly as it is and reported in skipped — it is too late to move a post that is going out right now.

Moves a draft or scheduled post to pending_approval, where it cannot be published until somebody decides. Submitting twice leaves one open review rather than two.

from and to are local calendar dates (YYYY-MM-DD) in the requested timezone, and the range covers whole local days — a report for "16 August" in Karachi starts at 19:00 UTC on the 15th, and one that ignored that would be wrong by five hours at both ends.

Runs the same projection the worker publishes through, against the same connections, and writes nothing: no post, no deliveries, no queue job, no metered usage, no media fetch.

Returns per target the text as that platform would receive it, which media it will not take and why, and every warning. This is what a composer draws.

Media given as a url is not downloaded — its type is assumed from the URL and its size is not checked. Those refs come back in unverified_media so the preview never claims to have looked at something it has not.

multipart/form-data with a file part, and optionally alt. Returns an asset id to use in a post’s media array. The same bytes uploaded twice by one organization return the same asset. The largest file accepted is the plan’s media limit (GET /v1/billing).

Removes the asset. The stored file goes when no other asset of this organization refers to it; posts already published keep what the platform holds.

content takes the same shape as a post's, and default_targets the same selectors — so applying a template is a spread into POST /v1/posts rather than a translation.

The signing secret is returned once and cannot be read back.

Each request carries X-Relay-Signature: t={unix},v1={hmac} where the HMAC is SHA-256 over {t}.{raw body} keyed with the secret. Verify it and reject a timestamp older than five minutes.

One row per destination, worst success rate first — the ordering a customer is looking for, because the reason to open this page is that something is broken.

Deliveries by status, posts by status, and the success rate over them.

from and to take either a local calendar date (YYYY-MM-DD, resolved to whole days in timezone) or an ISO instant. Defaults to the last 30 days.

Buckets are local to timezone, so a daily chart breaks at the customer's midnight rather than at UTC's — five hours out for a Karachi tenant, which is enough to move an evening campaign into the wrong day.

Empty buckets are filled in. A chart that skips a day with no deliveries draws a line straight through it and hides the outage.

The OAuth apps this organisation connects through instead of the shared one. Client secrets are never returned. supported lists the platforms that can be given an app today.

Replaces any existing app for the same platform. The secret is encrypted at rest and never returned.

Switching an app off falls back to the shared app for new authorisations. Connections already made through it keep working.

Connections authorised through it are kept and keep publishing; they can no longer refresh their tokens, so they will ask to be reconnected once the current one expires.

Read from the organization’s plan record on every request: how it is on the plan (a subscription, a licence, or assigned by Rutba), its limits (-1 is unlimited), the features it carries, and posts and deliveries used this month. A post counts once, when its first destination takes it.

The price list, read from the catalogue record rutba.io shows: each card’s name, price and words, and the Relay limits and features of the plan it sells. A price_minor of null means on request. A limits of null means the card sells no plan this API enforces (an enterprise contract). Answers without a credential.