# 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:

```text
https://postwithbeacon.com
```

Send the credential in the standard `Authorization` header:

```http
Authorization: Bearer YOUR_CREDENTIAL
```

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

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