Agent API reference
Review the supported Beacon Agent API routes, inputs, responses, and common errors.
The Agent API supports direct automation with an agent key or OAuth access token.
Base address:
https://postwithbeacon.comSend the credential in the standard Authorization header:
Authorization: Bearer YOUR_CREDENTIALJSON is a text format for structured data. Supported JSON errors use application/problem+json.
Programmatic API
Use /public/v1/* for the SDK, n8n, Zapier, and your own code. Do not use /agent/v1/* for these uses.
The /agent/v1/* routes serve AI agents and MCP. They ask for confirmed: true or a Beacon approval so that a person can review each write. The /public/v1/* routes serve software that acts on its own authority. They do not use these approval steps.
The Programmatic API has the same routes, request bodies, and responses as the Agent API below. Replace the /agent/v1 prefix with /public/v1. These rules apply:
- Use a public API key (
bcn_) or an agent key (bcn_agent_). Send it in theX-API-Keyheader or as a bearer token. OAuth access tokens do not work on these routes. - A public key sees the whole workspace. Writes are attributed to the workspace owner, and the key id stays in the audit details. An agent key keeps its own permissions and workspace scope.
- Both key types need the Growth plan or higher, except the
GET /public/v1/meidentity check. - Do not send
confirmed. Beacon fills it in for you. Do not sendapprovalId. - An immediate post (
state: "immediate") publishes at once. It does not need an approval. - Every write that can repeat still needs a stable
Idempotency-Keyheader oridempotencyKeyfield. Beacon never retries a write for you. - Every key shares the same per-credential request budget. Wait for
Retry-Afterafter a429response.
GET /public/v1/me
Send a public or agent key in the X-API-Key header or as a bearer token. Returns the workspace and key details. An agent key also returns its permissions.
Cursor pagination
Post and media lists use cursor pagination. Channel and calendar routes return arrays.
A list response contains items and nextCursor. Send a non-null nextCursor as the next request's cursor. Treat the cursor as opaque text. Do not parse or change it.
Identity
GET /agent/v1/me
Returns the selected workspace, credential permissions, current user, and enabled providers.
This route requires a valid Agent API credential. It does not require an additional permission.
Channels
GET /agent/v1/channels
Requires channels:read.
Returns enabled channels with connection status and publication availability.
GET /agent/v1/channels/{channelId}
Requires channels:read.
Returns one channel with its health, credential expiry, and publishing readiness. Use this to check a connection before a Zap or flow runs. A missing channel returns 404 with channel_not_found.
DELETE /agent/v1/channels/{channelId}
Requires channels:write and an Idempotency-Key header.
Send confirmed=true. Beacon cancels pending targets for the channel, then disconnects it. The response reports the cancelled target count.
Brands
GET /agent/v1/brands
Requires brands:read.
Returns the brands or clients in the selected workspace. A Workspace is the managed brand or client boundary. Use this list as the customer or group list for automations. The TypeScript SDK exposes this call under client.brands.
Notifications
GET /agent/v1/notifications
Requires notifications:read.
Returns notifications for the key owner in the selected workspace, plus the unread count. Use limit up to 100. Use this to poll for delivery changes when webhooks are not configured. The TypeScript SDK exposes this call under client.notifications.
Platform contracts
GET /agent/v1/provider-contracts
Requires channels:read.
Returns the safe composition rules for each enabled platform: text limits, media rules, required settings, and supported relations. Use this before a create action to shape provider settings. The TypeScript SDK exposes this call under client.providerContracts.
GET /agent/v1/provider-contracts/{provider}
Requires channels:read.
Returns the rules for one platform, for example x, linkedin, instagram, tiktok, or youtube. A missing platform returns 404.
Calendar
GET /agent/v1/calendar
Requires calendar:read.
| Name | Meaning |
|---|---|
from | Inclusive ISO 8601 date and time. |
to | Exclusive ISO 8601 date and time. |
The maximum requested range is 62 days.
Check a post plan
POST /agent/v1/post-checks
Requires channels:read. It also requires media:read when the plan contains media.
Send the planned content, destinations, media, and publication timing. Beacon returns ready, destination details, media details, and actionable issues.
This route does not create a post. It does not queue work, contact a provider, or create or use an approval.
List posts
GET /agent/v1/posts
Requires posts:read.
Use these optional query values:
| Name | Meaning |
|---|---|
cursor | The opaque nextCursor value from the prior response. |
limit | A result count from 1 through 100. |
q | Text to find in posts. |
status | all, draft, scheduled, published, or failed. |
The response contains customer-safe post summaries. It does not contain target IDs, publication-unit IDs, provider external IDs, or internal schedule revisions.
Get a post
GET /agent/v1/posts/{postId}
Requires posts:read. postId identifies the post inside the selected workspace.
Returns content, media, review status, channel destinations, publication parts, an editToken, and one controlToken for each channel.
The tokens are opaque compare-and-swap values. Get the post again after a stale-token response.
Beacon reports an uncertain provider result as checking. Do not treat checking as failed or retry it.
Create a post
POST /agent/v1/posts
Requires posts:write.
Send these required values:
confirmed: trueidempotencyKeystate- Shared
channelIdsandtext, or channel-specifictargets
state accepts draft, scheduled, or immediate.
A scheduled post requires publishAt. An immediate post requires a separate Beacon approval.
Reuse an idempotency key only for an unchanged request. Do not retry this write automatically after an unknown result.
Edit a post
POST /agent/v1/posts/{postId}/edit
Requires posts:write, confirmed: true, an Idempotency-Key header, and the latest editToken.
Send content and editToken. Beacon permits this edit only while every active destination is a draft or scheduled. A successful response returns a new editToken.
Reschedule one destination
POST /agent/v1/posts/{postId}/reschedule
Requires posts:write, confirmed: true, an Idempotency-Key header, and the latest channel controlToken.
Send channelId, controlToken, and the new publishAt. Beacon permits this command only when the exact destination is scheduled. A successful response returns a new controlToken.
Cancel one destination
POST /agent/v1/posts/{postId}/cancel
Requires posts:write, confirmed: true, an Idempotency-Key header, and the latest channel controlToken.
Send channelId and controlToken. Beacon rejects cancellation after publishing starts or after it finds published evidence.
Retry one failed destination
POST /agent/v1/posts/{postId}/retry
Requires posts:write, confirmed: true, an Idempotency-Key header, and the latest channel controlToken.
Send channelId, controlToken, and a new publishAt.
Beacon permits this command only from the exact failed state. Beacon rejects publishing, checking, delayed, reconnect_required, partially_published, and published results. It also rejects a failed destination that has unsafe publication evidence.
Never use this route to repeat an uncertain provider create request.
Delete a draft
DELETE /agent/v1/posts/{postId}
Requires posts:write and an Idempotency-Key header.
Beacon deletes drafts only. It never deletes delivery history. A missing draft returns 422 with post_not_deletable. Cancel a scheduled post instead. There is no bulk delete and no delete by group. Delete each draft by its ID.
Beacon never accepts a client-supplied release URL. The release URL comes only from a verified external post ID after publication. Do not send it in create or edit calls.
Media
GET /agent/v1/media
Requires media:read.
Returns ready media from the selected workspace. Use kind, limit, and the standard cursor pattern.
POST /agent/v1/media
Requires media:write.
Send multipart form data with file, confirmed=true, and an Idempotency-Key header. altText is optional.
Beacon checks the file bytes before it stores the asset. The response does not include a content hash, storage key, organization ID, or internal file name. Do not retry this write automatically after an unknown result.
POST /agent/v1/media/from-url
Requires media:write and an Idempotency-Key header.
Send fileUrl, confirmed=true, and optional altText. Beacon fetches only public HTTPS URLs, checks the file bytes, and stores a ready asset. An unreachable or oversized file returns 422. The TypeScript SDK exposes this call under client.media.uploadFromUrl.
GET /agent/v1/media/{mediaId}
Requires media:read.
Returns the file type, size, creation time, and descriptive data for one media item.
GET /agent/v1/media/{mediaId}/content
Requires media:read.
Returns validated image bytes for visual inspection. Beacon does not return video, audio, or document bytes through this route.
The TypeScript SDK provides these stable methods under client.media.
AI actions
POST /agent/v1/ai/post-drafts
Requires ai:generate and an Idempotency-Key header.
The request includes a brief, destinations, language, tone, confirmation, and one requested result. Use mode: "tailored" for separate destination variants. Optional fields include audience, currentText, mediaIds, and modelId.
Read maxCharacters from a channel result or destinations[].maxCharacters from a post check before generation. For X limits above 280, set the generation destination's id to that connected channel's ID. Beacon checks the channel in the authenticated workspace and rejects unconfirmed subscription access before it starts generation. Basic, Premium, and PremiumPlus accounts can use 25,000 characters. Missing subscription data keeps the limit at 280. Reconnect X to refresh the stored subscription. Beacon checks eligibility again at delivery.
POST /agent/v1/ai/post-images
Requires ai:generate.
The request includes alt text, aspect ratio, confirmation, prompt, and provider. Do not retry this write automatically.
Webhooks
GET /agent/v1/webhooks/endpoints
Requires webhooks:read.
Returns webhook endpoints in the selected workspace. The signing secret is never returned here. Use this list to drive n8n or Zapier trigger setup.
POST /agent/v1/webhooks/endpoints
Requires webhooks:write and an Idempotency-Key header.
Send name, targetUrl, eventTypes, and confirmed=true. Beacon returns the signing secret one time. Store it in a secret manager. Read Publication webhooks for event names and verification.
DELETE /agent/v1/webhooks/endpoints/{endpointId}
Requires webhooks:write and an Idempotency-Key header.
Removes one endpoint from the selected workspace. In-flight deliveries stop on their next attempt.
The TypeScript SDK provides these stable methods under client.webhooks.
OpenAPI description
OpenAPI is a standard description of supported HTTP routes and data.
Open /openapi for the interactive reference. Open /openapi/json for the machine-readable description.