Core Concepts

A handful of objects make up the whole API. Once you know how they fit together, the rest of the docs are details.

Projects

A project is the workspace everything else lives in: connected accounts, posts, access keys, credits, notification rules and collaborators. Access keys are scoped to one project, so a key can never read or publish to another project's accounts.

You can belong to several projects (for example one per client) and switch between them from the project menu in the dashboard. See Collaborators & Projects.

Social accounts

A social account is one connected profile, page or channel on a platform, such as a LinkedIn profile, a Facebook Page or a YouTube channel. Each has a Relaycast id (a UUID) that you use as accountId when posting.

Accounts are connected in the dashboard through each platform's OAuth consent screen. Bluesky can also be connected through the API. An account's status is active or reconnect_required. See Social Accounts.

Accounts can be organised into Social Groups, for example by client or brand.

Posts and targets

A post is one publish request: shared content, optional media, and a list of targets. Each target is one social account, with optional per-account content and platform options.

When you create a post, Relaycast creates one target record per account. Targets are independent: one can publish while another fails, and each records its own externalUrl, errorCode and errorMessage.

post (status: published | partial | failed | ...)
├── target  linkedin  · jane-doe       → published  https://www.linkedin.com/...
├── target  twitter   · janedoe        → published  https://x.com/...
└── target  instagram · jane.doe       → failed     errorCode: "media_error"

Lifecycle

1. Validate. The request is checked against the schema, every accountId must belong to your project and be active, and the content and media are validated for each platform. Any problem returns 400 and nothing is created or charged.
2. Reserve credits. One credit per target is debited. If the balance is too low, you get 402 insufficient_credits.
3. Queue. The post is saved and each target is queued for its publish time.
4. Publish. A background worker publishes each target to its platform, retrying temporary failures with backoff.
5. Roll up. When every target has finished, the post's status becomes published, partial or failed, and notifications fire.

Post statuses

Target statuses

Credits

Publishing costs 1 credit per target. A post sent to three accounts costs three credits. Targets that fail are refunded automatically. See Credits & Usage.

Media

Attach media by public https:// URL, or by media://<id> reference to a file in your project's media library. Platforms download media when the post publishes. See Media & Uploads.

Platform options

Platform-specific settings, such as a YouTube title or a TikTok privacy level, go in targets[].options. See Platform Options.

Idempotency

Send an Idempotency-Key header on POST /v1/posts so a retried request never creates (or charges for) a duplicate post. See Idempotency & Retries.