Agent REST API

The Agent REST API lets scripts and agents read your brands, create drafts and schedule them, with a key you control. It sits beside the MCP connector: use the connector inside an AI chat, and the REST API from your own code.

• Base URL: https://ops.rebrandos.com/api/agent/v1
• OpenAPI 3.1 description: https://ops.rebrandos.com/api/agent/v1/openapi.json
• JSON in and out. Errors are application/problem+json.
• Every plan includes the API, including during your free trial.

Quickstart

1. Create a key

1. Open Settings → Agent access keys and choose Create key.
2. Give it a label, pick a preset — Read-only analyst, Content agent or Publishing agent — and adjust the scopes.
3. Under Brands, keep All brands (current + future) or choose Specific brands only. Pick an expiry and, optionally, an IP allowlist.
4. Copy the key. It is shown once and starts with rbos_live_.

Only owners and admins can issue a key with publish:execute, accounts:manage or automations:execute. When an operator asks for one, it waits under Pending key requests until an owner or admin approves it.

2. Check the key

curl https://ops.rebrandos.com/api/agent/v1/whoami \
  -H "Authorization: Bearer $REBRANDOS_KEY"

{
  "ok": true,
  "keyId": "brandos_agent_key_6b1d…",
  "label": "Publishing bot",
  "organizationId": "org_northwind",
  "scopes": ["brands:read", "accounts:read", "drafts:read", "drafts:write", "schedule:read", "publish:execute"],
  "brands": ["northwind-coffee"],
  "expiresAt": "2027-01-17T09:00:00.000Z",
  "env": "live"
}

brands is null when the key may use every brand.

3. Find the brand and channel

curl "https://ops.rebrandos.com/api/agent/v1/brands" \
  -H "Authorization: Bearer $REBRANDOS_KEY"

{ "ok": true, "data": [{ "id": "northwind-coffee", "name": "Northwind Coffee", "status": "active" }], "nextCursor": null, "total": 1 }

curl "https://ops.rebrandos.com/api/agent/v1/accounts" \
  -H "Authorization: Bearer $REBRANDOS_KEY"

{ "ok": true, "data": [{ "brandId": "northwind-coffee", "platform": "linkedin", "account": "Northwind Coffee" }], "nextCursor": null, "total": 1 }

Use a brand’s id as brand, and an account’s platform as channel.

4. Create a draft

curl -X POST https://ops.rebrandos.com/api/agent/v1/drafts \
  -H "Authorization: Bearer $REBRANDOS_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: draft-2026-10-19-onboarding" \
  -d '{"brand":"northwind-coffee","channel":"linkedin","title":"Onboarding week","content":"Week one at Northwind starts with a cup…"}'

201 Created
{ "ok": true, "draft": { "id": "…", "title": "Onboarding week", "brand": "northwind-coffee", "channel": "linkedin", "status": "draft" } }

5. Publish

Try it with dryRun first: you get the plan, the account’s capacity check and your remaining daily posts, and nothing is scheduled.

curl -X POST https://ops.rebrandos.com/api/agent/v1/publish \
  -H "Authorization: Bearer $REBRANDOS_KEY" \
  -H "Content-Type: application/json" \
  -d '{"draftId":"DRAFT_ID","scheduledAt":"2026-10-20T09:00:00+01:00","dryRun":true}'

Then send the same request without dryRun, with an Idempotency-Key:

201 Created
{
  "ok": true,
  "scheduled": { "scheduleId": "…", "draftId": "…", "brand": "northwind-coffee", "channel": "linkedin", "scheduledAt": "2026-10-20T08:00:00.000Z" },
  "dailyCap": { "used": 1, "limit": 10, "remaining": 9, "resetAt": "2026-10-19T24:00:00Z" }
}

scheduledAt must be in the future and include a time zone; leave it out to schedule five minutes from now. Follow the post with GET /publish-jobs and GET /publish-receipts, or a webhook.

Endpoints

List endpoints take limit (1–200, default 50) and cursor, and return data, nextCursor and total. Pass nextCursor back as cursor until it is null. Endpoints that read social publishing data also need the workspace’s social publishing module to be active.

Authentication and scopes

Send the key in the Authorization: Bearer header on every request; keys in the URL are ignored. Keys look like rbos_live_ followed by 36 letters and digits that end in a checksum, so secret scanners can spot them.

A key can never do more than the person who created it can do right now. If that person loses access to the workspace, the key stops working (issuer_no_access); if they lose write access, its write scopes stop (issuer_cannot_write).

The scopes the REST API checks are in the endpoint table. Keys can also hold the connector’s scopes (personas, calendar, schedule:write, media:write, automations), which the REST endpoints don’t use. billing:* and keys:* can never be granted to a key.

Brand restriction

A key limited to specific brands only lists those brands, their accounts, drafts, jobs, receipts and media. Naming another brand returns 403 brand_not_permitted, and its webhooks only receive events about its own brands.

Expiry, rotation and revocation

• Every key expires. Choose 7, 30 or 90 days or 1 year when you create it. After that, requests return 401 expired.
• Rotate from the key’s row in Settings. You get a new key straight away and the old one keeps working for 24 hours (401 rotated after that). Rotation keeps the scopes, brands, limits and expiry.
• Revoke to stop a key immediately. Its sub-tokens stop too, and so do its webhooks.
• ReBrandOS can revoke a leaked key automatically when a secret-scanning service reports it. For keys pushed to a code host, that needs ReBrandOS to be registered as a secret-scanning partner with that host (for example GitHub’s partner program), so don’t rely on it: if a key leaks, revoke it yourself straight away.
• Pause all agent access stops every key, connector and webhook in the workspace (403 killed) until an admin turns it off.

IP allowlist

Add IPv4 or IPv6 addresses or CIDR ranges, separated by commas or spaces, for example 203.0.113.0/24, 2001:db8::/32. Requests from anywhere else return 403 ip_not_allowed. Leave it empty to allow any address. An entry that isn’t a valid address or range is rejected when you save, rather than being dropped.

Sub-tokens

Give a sub-agent a narrower key without creating one in Settings. A sub-token can only narrow its parent: fewer scopes, fewer brands, lower limits, an IP range inside the parent’s, an earlier expiry. Revoking, rotating or expiring the parent disables it, and a sub-token cannot mint its own.

curl -X POST https://ops.rebrandos.com/api/agent/v1/subtokens \
  -H "Authorization: Bearer $REBRANDOS_KEY" \
  -H "Content-Type: application/json" \
  -d '{"label":"Caption checker","scopes":["drafts:read"],"brandIds":["northwind-coffee"],"caps":{"rateLimitPerMin":60},"expiresAt":"2026-10-26T00:00:00Z"}'

201 Created
{
  "ok": true,
  "token": "rbos_live_…",
  "apiKey": { "id": "…", "label": "Caption checker", "scopes": ["drafts:read"], "brandIds": ["northwind-coffee"],
              "caps": { "rateLimitPerMin": 60, "publishesPerDay": 10, … }, "expiresAt": "2026-10-26T00:00:00.000Z",
              "env": "live", "parentKeyId": "…" }
}

Rate limits and fair use

• 300 requests a minute per key; sub-tokens share their parent’s budget. Every response carries RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset (Unix seconds). Over the limit you get 429 rate_limited with a Retry-After header in seconds.
• 10 scheduled posts a day per key, shared with its sub-tokens, reset at 00:00 UTC. Successful POST /publish responses include dailyCap; over the cap you get 429 publish_cap_reached with resetAt. Dry runs and posts waiting for approval don’t count.
• A key can have lower limits than these, never higher. If you need more, contact us; see the fair-use section of the Terms.
• Request bodies are limited to 1 MB.

Idempotency

POST /drafts and POST /publish accept an Idempotency-Key header, scoped to your key. Retrying with the same key and the same body returns the first response instead of creating a second draft or post. The same key with a different body returns 409 idempotency_conflict; a retry while the first request is still running returns 409 idempotency_in_progress. Use a fresh key for each new draft or post, and the same key when you retry after a timeout.

Webhooks

Instead of polling, subscribe an https endpoint on a public host (private, loopback and link-local addresses are refused). The response includes the signing secret, once.

curl -X POST https://ops.rebrandos.com/api/agent/v1/webhooks \
  -H "Authorization: Bearer $REBRANDOS_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://hooks.example.com/rebrandos","events":["post.published","post.failed"]}'

201 Created
{
  "ok": true,
  "webhook": { "id": "…", "url": "https://hooks.example.com/rebrandos", "events": ["post.published", "post.failed"], "status": "active" },
  "secret": "whsec_…",
  "signatureScheme": "HMAC-SHA256 over `${X-RebrandOS-Timestamp}.${rawBody}`; compare X-RebrandOS-Signature (sha256=...)"
}

Events

Omit events to receive all of them. Each event is sent once; TikTok inbox deliveries are not publications and send nothing.

Request format and signature

POST /rebrandos HTTP/1.1
Content-Type: application/json
X-RebrandOS-Event: post.published
X-RebrandOS-Timestamp: 1760950800
X-RebrandOS-Signature: sha256=5d0c…

{"id":"evt_…","type":"post.published","createdAt":"2026-10-20T08:00:03.000Z","data":{ … }}

The signature is a hex HMAC-SHA256 of the timestamp, a dot, and the raw request body, keyed with your secret. Verify it before you parse the body:

import crypto from 'node:crypto';

export function verifyRebrandosWebhook(headers, rawBody, secret) {
  const timestamp = headers['x-rebrandos-timestamp'] || '';
  const received = headers['x-rebrandos-signature'] || '';
  const expected = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(`${timestamp}.${rawBody}`, 'utf8')
    .digest('hex');
  const fresh = Math.abs(Date.now() / 1000 - Number(timestamp)) < 300; // our suggestion: 5 minutes
  return fresh
    && received.length === expected.length
    && crypto.timingSafeEqual(Buffer.from(received), Buffer.from(expected));
}

Delivery and retries

• Answer with any 2xx within 8 seconds. Redirects are not followed.
• Network errors, 5xx and 429 are retried up to 4 attempts in total, a fraction of a second apart. Other 4xx responses are not retried.
• After 15 failed deliveries in a row the subscription is disabled. GET /webhooks shows its status and failureCount, and GET /webhooks/{id}/deliveries shows each attempt.
• A subscription stops receiving when the key that created it is revoked or expires, and while agent access is paused.

When your plan changes

Blocked writes return 402 entitlement_blocked with a reason. Reads, cancelling queued posts (POST /publish-jobs/{id}/cancel), deleting drafts, sub-tokens and webhook management keep working, and an owner can export the workspace’s data from the dashboard.

Errors

Errors use RFC 9457 problem details with the content type application/problem+json. code is stable; type links to the code’s row below; some codes add fields such as requiredScope, brandId, reason, limit or resetAt.

HTTP/1.1 403 Forbidden
Content-Type: application/problem+json

{
  "type": "https://www.rebrandos.com/docs/api#error-insufficient_scope",
  "title": "insufficient scope",
  "status": 403,
  "code": "insufficient_scope",
  "detail": "This key lacks the publish:execute scope.",
  "requiredScope": "publish:execute",
  "hint": "Recreate the key with the needed scope."
}