API Reference

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 all paid plans (Starter, Creator, and Business). For no-code workflows, see the integrations page.

• 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 (Starter 30/mo, Creator 120/mo, Business 500/mo) — same pool as the dashboard.
• OpenAPI schema: /openapi.json — import into Postman or Insomnia.

1. Create an API key

Go to Settings → API Keys and create an API key, 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 1 GB):

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.
• Instead of media_url, you can pass asset_id (a UUID from your Xroad library or generation history) and we will resolve the URL automatically. The two fields are mutually exclusive.
• 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. Use with AI Agents

The xroad-studio-skill.md file teaches your agent the Xroad API in one step. Once installed, just tell your agent what to post and where — it handles the API calls, account IDs, and scheduling automatically.

Claude Code

Run once inside your project, then set your API key:

# 1. Fetch the skill from GitHub into your project
curl -fsSL https://raw.githubusercontent.com/xroad-studio/Skill_autoposting/main/xroad-studio-skill.md \
  -o .claude/skills/xroad-studio.md

# 2. Add your API key to the environment
export XROAD_API_KEY=xrd_live_...

# 3. Test — list connected accounts
curl https://xroadstudio.com/api/v1/accounts \
  -H "Authorization: Bearer $XROAD_API_KEY"

Claude Code will now read .claude/skills/xroad-studio.md on every session start. You can then say: "Post this image to Instagram and LinkedIn, scheduled for tomorrow 9am Prague time" — the agent will look up your account IDs and call the API itself.

Cursor

mkdir -p .cursor/skills && curl -fsSL \
  https://raw.githubusercontent.com/xroad-studio/Skill_autoposting/main/xroad-studio-skill.md \
  -o .cursor/skills/xroad-studio.md

Codex / API clients

Import /openapi.json into your API client for schema auto-complete. For Codex, paste the raw skill file URL into your system context or instructions file:

# Raw skill URL — paste into agent instructions or system prompt
https://raw.githubusercontent.com/xroad-studio/Skill_autoposting/main/xroad-studio-skill.md

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 to convert 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.

See the integrations page for visual setup guides for each no-code platform.

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 a paid plan (Starter, Creator, or Business).
• subscription_inactive (403) — subscription has expired or payment failed. Update billing at /billing.
• quota_monthly (429) — monthly post limit reached. Resets on next billing cycle.
• quota_queue (429) — too many posts currently queued waiting to publish. Wait for existing posts to go out.
• rate_limited (429) — more than 60 requests/minute. Check the retry_after field in the error body for seconds to wait.
• 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.