Skip to documentation
Beacon Docs
Agent API and webhooks

Agent API reference

Review the supported Beacon Agent API routes, inputs, responses, and common errors.

Open Markdown

The Agent API supports direct automation with an agent key or OAuth access token.

Base address:

https://postwithbeacon.com

Send the credential in the standard Authorization header:

Authorization: Bearer YOUR_CREDENTIAL

JSON 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 the X-API-Key header 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/me identity check.
  • Do not send confirmed. Beacon fills it in for you. Do not send approvalId.
  • An immediate post (state: "immediate") publishes at once. It does not need an approval.
  • Every write that can repeat still needs a stable Idempotency-Key header or idempotencyKey field. Beacon never retries a write for you.
  • Every key shares the same per-credential request budget. Wait for Retry-After after a 429 response.

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.

NameMeaning
fromInclusive ISO 8601 date and time.
toExclusive 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:

NameMeaning
cursorThe opaque nextCursor value from the prior response.
limitA result count from 1 through 100.
qText to find in posts.
statusall, 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: true
  • idempotencyKey
  • state
  • Shared channelIds and text, or channel-specific targets

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.