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