Overview

Xroad's posting API lets you publish to your connected social accounts from any HTTP client — your own AI agent, n8n, Make.com, Zapier, or a CLI script. Available on Creator and Business plans.

Base URL: https://xroadstudio.com/api/v1
Auth: Authorization: Bearer xrd_live_...
Rate limit: 60 requests / minute per key.
Posts count toward your monthly quota (Creator 120/mo, Business 500/mo) — same pool as the dashboard.
OpenAPI schema: /openapi.json — import into Postman, Insomnia, or a GPT action.

1. Create an API key

Go to Settings → API Keys, give your key a name, and accept the usage terms. The plaintext key is shown once — copy it now and store it in a secrets manager. We only keep the SHA-256 hash. If you lose it, revoke it and create a new one.

2. List your connected accounts

curl https://xroadstudio.com/api/v1/accounts \
  -H "Authorization: Bearer $XROAD_API_KEY"

# → { "data": [{ "id": "acc_abc123", "platform": "instagram", "username": "myhandle" }] }

Copy the id field for each account you want to post to. You'll pass it as social_account_ids when creating a post.

3. Upload an image or video

Upload media first to get a permanent CDN URL, then pass that URL when creating the post. Skip this step if the image is already on a stable public URL, or if you're using an asset from your Xroad library.

Option A — upload a file (up to 250 MB):

curl -X POST https://xroadstudio.com/api/v1/media \
  -H "Authorization: Bearer $XROAD_API_KEY" \
  -F "file=@/path/to/photo.jpg"

# → { "data": { "url": "https://media.xroadstudio.com/..." } }

Option B — re-host an expiring URL (ChatGPT / DALL-E, Gemini, Canva, Google Drive, Airtable):

curl -X POST https://xroadstudio.com/api/v1/media \
  -H "Authorization: Bearer $XROAD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://oaidalleapiprodscus.blob.core.windows.net/private/..." }'

# → { "data": { "url": "https://media.xroadstudio.com/..." } }
# The original link expires — the returned URL is permanent.

Google Drive: use https://drive.google.com/uc?export=download&id=FILE_ID (file must be shared publicly). URL re-host limit: 20 MB.

4. Schedule or publish a post

curl -X POST https://xroadstudio.com/api/v1/posts \
  -H "Authorization: Bearer $XROAD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "caption": "Launching today! 🚀",
    "scheduled_at": "2026-05-10T12:00:00Z",
    "social_account_ids": ["acc_abc123", "acc_xyz789"],
    "media_url": "https://media.xroadstudio.com/..."
  }'

# → { "data": { "id": "uuid", "status": "scheduled", ... } }

Omit scheduled_at to publish immediately.
scheduled_at must be at least 30 seconds in the future and no more than 3 months out.
Pass multiple account IDs to crosspost to several platforms at once.
Per-platform options (TikTok privacy level, YouTube title, Instagram placement) go in platform_configurations. See the OpenAPI schema.

5. Check post status

curl https://xroadstudio.com/api/v1/posts/$POST_ID \
  -H "Authorization: Bearer $XROAD_API_KEY"

# status: scheduled → processing → published (or failed / cancelled)

Poll every 30–60 seconds until status is published, failed, or cancelled. You can also list all posts with optional filters:

curl "https://xroadstudio.com/api/v1/posts?status=scheduled&limit=10" \
  -H "Authorization: Bearer $XROAD_API_KEY"

6. Edit a scheduled post

You can update the caption, scheduled time, or media on any post that is still in scheduled status.

curl -X PATCH https://xroadstudio.com/api/v1/posts/$POST_ID \
  -H "Authorization: Bearer $XROAD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "caption": "Updated caption with a new angle.",
    "scheduled_at": "2026-05-10T14:00:00Z"
  }'

# → { "data": { "id": "...", "status": "scheduled", "caption": "Updated caption...", ... } }

Returns not_updatable (409) if the post has already started processing or published.

7. Cancel a scheduled post

curl -X DELETE https://xroadstudio.com/api/v1/posts/$POST_ID \
  -H "Authorization: Bearer $XROAD_API_KEY"

# → { "data": { "id": "...", "status": "cancelled" } }

Works on scheduled and processing posts. Published posts cannot be deleted via the API — manage those directly on each platform.

8. Integrations

n8n

Use an HTTP Request node. Method: POST, URL: https://xroadstudio.com/api/v1/posts, Authentication: Header Auth with key Authorizationand value Bearer {{$credentials.apiKey}}. Body: JSON. Import /openapi.json for auto-completion.

Make.com

Use the HTTP module → Make a request. If your image lives in Google Drive or Airtable, add a first HTTP call to POST /v1/media with the file's download URL — this converts the expiring attachment into a permanent CDN URL. Then pass that URL in the second call to POST /v1/posts.

Zapier

Webhooks by Zapier → Custom Request (POST). Add header Authorization: Bearer YOUR_KEY and set the body to JSON.

ChatGPT Custom GPT / Claude Project

Import /openapi.json as a GPT Action (ChatGPT) or paste the skill file into your Claude Project context. Your AI assistant will know how to list accounts, upload media, and schedule posts without any extra setup. Set the API key as the Bearer token in the action authentication settings.

9. Errors

All errors use the envelope { "error": { "code", "message" } }.

invalid_key (401) — key is missing, malformed, or revoked. Regenerate in Settings.
plan_required (403) — account is not on Creator or Business plan.
quota_monthly (429) — monthly post limit reached. Resets on next billing cycle.
rate_limited (429) — more than 60 requests/minute. Retry after the Retry-After header value.
media_fetch_failed (422) — URL was not publicly reachable or exceeded 20 MB.
not_updatable (409) — post is no longer in scheduled status and cannot be edited.
not_cancellable (409) — post has already been published.

10. Security

Always pass the key in the Authorization header. Query-string auth is not supported and would expose the key in server logs.
Store keys in a secrets manager (Doppler, Infisical, AWS Secrets Manager) — never in source code or a git repo.
Keys do not expire. Revoke any key you no longer need in Settings → API Keys. Revocation takes effect within seconds.
Each request records the timestamp and originating IP against the key. You can audit recent activity in Settings.

API Reference