API Reference

The Relaycast API is a JSON REST API. You can call it with any HTTP client: the examples use cURL, fetch in Node.js, and Python requests. There is no official SDK.

Base URL

https://social-publish-api.onrender.com

All resource endpoints are versioned under /v1. The health endpoints (/health, /ready) are at the root and need no authentication.

Authentication

Every /v1 request needs an API key. Create one in the dashboard under API Keys. Send it in either header:

A key belongs to one project; everything you create with it (posts, accounts) is scoped to that project. Revoked keys stop working immediately. See Authentication.

curl https://social-publish-api.onrender.com/v1/accounts \
  -H "x-access-key: $RELAYCAST_API_KEY"

const res = await fetch("https://social-publish-api.onrender.com/v1/accounts", {
  headers: { "x-access-key": process.env.RELAYCAST_API_KEY! },
});
const { data } = await res.json();

import os, requests

res = requests.get(
    "https://social-publish-api.onrender.com/v1/accounts",
    headers={"x-access-key": os.environ["RELAYCAST_API_KEY"]},
)
data = res.json()["data"]

Requests

• Send JSON bodies with content-type: application/json.
• Request bodies are limited to 1 MB. Media is never uploaded in the request body: pass a public https URL or a media library reference (media://<id>). See Media & Uploads.
• Timestamps are ISO 8601 strings. scheduledFor must include a time zone (Z or an offset such as +02:00).
• IDs are UUIDs.

Responses

Successful responses wrap the result in a data field, for single objects and lists alike:

{
  "data": [
    { "id": "6f1c2a7e-4b8d-4f7a-9a51-2d3c4b5a6e7f", "platform": "twitter", "handle": "acme" }
  ]
}

Errors

Errors use a single envelope with a machine-readable code, a human-readable message, and sometimes details:

{
  "error": {
    "code": "validation_error",
    "message": "Content is not valid for some platforms",
    "details": {
      "6f1c2a7e-4b8d-4f7a-9a51-2d3c4b5a6e7f": [
        { "field": "content", "message": "X posts allow 280 characters (links count as 23, emoji/CJK as 2); turn on Long post for Premium accounts; this is 312" }
      ]
    }
  }
}

validation_error has two details shapes:

• Schema errors (wrong types, missing fields): an array of issues, each with path (for example ["targets", 0, "accountId"]), message and code.
• Platform errors: an object keyed by account ID, each holding a list of { field, message }.

See Errors for handling advice.

Rate limits

Each API key may make 120 requests per minute by default (fixed one-minute window; self-hosted deployments set RATE_LIMIT_PER_MINUTE). Responses include:

Over the limit, the API returns 429 with code rate_limited; retry after the minute rolls over. See Rate Limits.

Lists and limits

GET /v1/posts returns the most recent posts first. Use limit (1–100, default 20). There is no cursor pagination; to browse or filter older posts, use Posts in the dashboard.

Idempotency

POST /v1/posts accepts an Idempotency-Key header. Retrying with the same key returns the post created by the first request (200) instead of creating and charging for a new one (201). See Idempotency & Retries.

Credits

Each post costs 1 credit per target account, charged when the post is created. Targets that fail permanently are refunded. See Credits & Usage.

Endpoints

Events are delivered to your server as webhooks.

Request logs

Every authenticated /v1 request is recorded in the dashboard under Logs, including requests rejected by the rate limiter. See Request Logs.