REST API

Every operation available over MCP is also a REST endpoint. Same registry, same permissions, same rules.

#Base URL and authentication

• Base URL: https://reach-link-craft.lovable.app/api/public/v1
• API key: create one in Settings → MCP / API connections → Create API key (you can set an expiry). Send it as:

Authorization: Bearer xb_live_<id>_<secret>

The key acts with the current role of the person who created it. Keep it secret: it is shown once.

For n8n use an HTTP Request node with Header Auth (Name Authorization, Value Bearer <YOUR_KEY>); in Make use HTTP → Make a request; in Zapier use Webhooks by Zapier → Custom Request.

#Writes need an idempotency key

Every write (kinds X, W, D) needs an Idempotency-Key header (or idempotency_key in the body): 8–128 characters from A–Z a–z 0–9 . _ : -.

• Same key + same input → the stored answer or the same job. Nothing runs twice.
• Same key + different input → 409 idempotency_conflict.
• The first call with that key still running → 409 idempotency_processing, retry after 2 seconds with the same key.

Keys are scoped to the connection.

#Versioned settings

Settings with a revision need the revision you read: send If-Match: "<revision>" or expected_revision in the body. Responses for versioned objects carry an ETag. A stale revision returns 412 revision_conflict with the current value — merge and retry.

#Jobs and waiting

Live reads (L) and X actions (X) create jobs. The request waits for the job up to ?wait= seconds (0–20, default 15).

• Done in time → 200 with the result.
• Still queued, held or running → 202 with Location: /api/public/v1/jobs/{job_id} and Retry-After: 2. Poll GET /jobs/{job_id} (it can wait up to 20 seconds too).
• POST /jobs/{job_id}/cancel cancels a queued or held job. A running job is asked to stop and may still end succeeded, cancelled or unknown.

#Responses and pagination

Successful responses use one envelope:

{ "data": {}, "meta": { "request_id": "req_…", "operation": "account_list" }, "next_cursor": null, "has_more": false }

Lists return next_cursor; pass it back as cursor for the next page. Every response has an X-Request-Id header.

#Rate limit

600 calls per minute per connection. Responses carry RateLimit-Policy and RateLimit headers; over the limit you get 429 rate_limited with Retry-After. This is the API's limit — each X account's own action limits apply separately.

#Request history

Each call is added to the connection's usage history in X-Buddy right after its answer is sent, so the history never slows a call down. If the server stops at that exact moment, the history can miss that one call; what the call did (a job queued, a setting saved) is kept either way. Refusals of a paused or revoked connection are recorded once a minute.

#Batches

POST /batches (x_batch) runs one X action on up to 1,000 items: explicit account + arguments pairs, or X accounts / groups crossed with a list of arguments. It supports a dry run and spacing per X account. Limits, run hours and do-not-contact still apply. Follow it with x_batch_get; a batch.completed event fires at the end. Cancelling drops items not yet queued and cancels waiting jobs; running ones finish.

#Media

1. POST /media/uploads (media_create_upload) with a purpose of post (the default), profile or dm for the operation you'll use; it returns a short-lived upload_url and a media_id.
2. PUT the file bytes to upload_url with the content type you declared.
3. Use media_id in the post, profile or message operation that matches the purpose. Profile images accept JPG, PNG and WEBP only.

Limits: JPG, PNG and WEBP up to 5 MB; GIF up to 15 MB; MP4 and MOV up to 50 MB.

#Downloads

• OpenAPI 3.1 document — generate a client in any language.
• TypeScript SDK — one file, no dependencies.
• Postman collection
• API explorer — try calls in the browser.

All are generated from the same registry as the API reference.

#Example

curl "https://reach-link-craft.lovable.app/api/public/v1/accounts" \
  -H "Authorization: Bearer $XBUDDY_API_KEY"

#Related

• Errors
• Webhooks & events