> ## Documentation Index > Fetch the complete documentation index at: https://docs.letmepost.dev/llms.txt > Use this file to discover all available pages before exploring further. # Publish or schedule a multi-target post > Publish a single body to up to 25 connected accounts in one call, or schedule the whole batch for a future time. - **Multi-target only:** the v1 wire shape requires `targets[]`. The legacy `account: {}` single-target shape is no longer accepted. - **Idempotent:** include `Idempotency-Key`. Replays within 24 hours return the original response. - **Preflight:** every documented platform constraint runs locally before the upstream call. Cheap shape preflight is atomic across the batch — if any target fails the synchronous checks the whole call is rejected as `400 preflight_failed`. Deep checks (URL reachability, MIME sniffing, byte caps) run per target and surface inside `results[i].error`, producing a `partial_failed` batch rather than a 400. - **Errors:** failures use the [stable error envelope](https://letmepost.dev/docs/errors/) — `code`, `rule`, `platformResponse`, `remediation`, `docUrl`, `ruleUrl`. For per-platform payload differences, see the [platforms guides](https://letmepost.dev/docs/platforms/bluesky/). ## OpenAPI ````yaml /api-reference/openapi.json post /v1/posts openapi: 3.1.0 info: title: letmepost.dev API version: v1 description: >- Open-source social media publishing API. Preflight validation, transparent errors, idempotency, stable platform versions. The full developer documentation lives at [letmepost.dev/docs/](https://letmepost.dev/docs/). This reference is generated from the canonical Zod schemas at `packages/schemas/`. **Auth:** Bearer key in the `Authorization` header. See [Authentication](https://letmepost.dev/docs/authentication/). **Idempotency:** every write accepts `Idempotency-Key`. See [Idempotency](https://letmepost.dev/docs/idempotency/). **Errors:** stable envelope with `code`, `rule`, `platformResponse`, `remediation`, `docUrl`, `ruleUrl`. See [Errors](https://letmepost.dev/docs/errors/). contact: name: letmepost.dev url: https://github.com/rosekamallove/letmepost.dev license: name: Apache-2.0 url: https://www.apache.org/licenses/LICENSE-2.0 servers: - url: https://api.letmepost.dev description: Production security: - bearer: [] tags: - name: Posts description: >- Publish and read posts. Multi-target: a single `POST /v1/posts` fans out to up to 25 connected accounts. - name: Media description: Upload and reference media assets. - name: Accounts description: Connect, list, and disconnect platform accounts. - name: API Keys description: Mint and revoke API keys (dashboard session only). - name: Webhooks description: Register, test, and manage outbound webhook endpoints. paths: /v1/posts: post: tags: - Posts summary: Publish or schedule a multi-target post description: >- Publish a single body to up to 25 connected accounts in one call, or schedule the whole batch for a future time. - **Multi-target only:** the v1 wire shape requires `targets[]`. The legacy `account: {}` single-target shape is no longer accepted. - **Idempotent:** include `Idempotency-Key`. Replays within 24 hours return the original response. - **Preflight:** every documented platform constraint runs locally before the upstream call. Cheap shape preflight is atomic across the batch — if any target fails the synchronous checks the whole call is rejected as `400 preflight_failed`. Deep checks (URL reachability, MIME sniffing, byte caps) run per target and surface inside `results[i].error`, producing a `partial_failed` batch rather than a 400. - **Errors:** failures use the [stable error envelope](https://letmepost.dev/docs/errors/) — `code`, `rule`, `platformResponse`, `remediation`, `docUrl`, `ruleUrl`. For per-platform payload differences, see the [platforms guides](https://letmepost.dev/docs/platforms/bluesky/). parameters: - $ref: '#/components/parameters/IdempotencyKey' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreatePostRequest' examples: single-target-explicit-id: summary: Single target by accountId value: targets: - accountId: 00000000-0000-0000-0000-000000000000 text: Hello from letmepost.dev single-target-auto-resolve: summary: Single target by platform (auto-resolved) value: targets: - platform: bluesky text: Hello from letmepost.dev multi-target-fan-out: summary: Three-platform fan-out with per-target overrides value: text: Shipped multi-target publishing today. targets: - platform: twitter - platform: bluesky - platform: linkedin text: >- Launching multi-target publishing — read the deep dive at https://letmepost.dev/blog/multi-target. twitter-reply: summary: Reply to a tweet via target options value: targets: - platform: twitter options: platform: twitter replyToTweetId: '1234567890' text: Following up on this. scheduled-batch: summary: Schedule a batch for the future value: scheduledAt: '2026-06-01T12:00:00.000Z' text: Scheduled drop. targets: - platform: twitter - platform: bluesky responses: '200': description: >- Immediate publish completed. The batch envelope's `status` is `published` (all targets succeeded), `partial_failed` (mixed outcomes), or `failed` (every target failed). Per-target detail lives inside `results[]`. headers: X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-Request-Id: $ref: '#/components/headers/X-Request-Id' content: application/json: schema: $ref: '#/components/schemas/CreatePostResponse' examples: all-published: summary: All targets succeeded value: id: 00000000-0000-0000-0000-000000000000 status: published createdAt: '2026-05-15T18:00:00.000Z' results: - accountId: 11111111-1111-1111-1111-111111111111 platform: twitter postId: 22222222-2222-2222-2222-222222222222 status: published uri: https://twitter.com/i/web/status/1798765432101234567 - accountId: 33333333-3333-3333-3333-333333333333 platform: bluesky postId: 44444444-4444-4444-4444-444444444444 status: published uri: at://did:plc:example/app.bsky.feed.post/3kabc cid: bafyreigh2akiscaildc... partial-failed: summary: Mixed outcome — one target rejected upstream value: id: 00000000-0000-0000-0000-000000000000 status: partial_failed createdAt: '2026-05-15T18:00:00.000Z' results: - accountId: 11111111-1111-1111-1111-111111111111 platform: twitter postId: 22222222-2222-2222-2222-222222222222 status: published uri: https://twitter.com/i/web/status/1798765432101234567 - accountId: 33333333-3333-3333-3333-333333333333 platform: instagram postId: 44444444-4444-4444-4444-444444444444 status: rejected error: code: platform_rejected message: >- Instagram rejected the media URL (OAuthException 2207052). rule: instagram.media.url_unreachable remediation: >- Confirm the URL responds 200 to an anonymous GET, or upload via POST /v1/media. '202': description: >- Scheduled batch accepted; every target row is queued and will publish at `scheduledAt`. headers: X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-Request-Id: $ref: '#/components/headers/X-Request-Id' content: application/json: schema: $ref: '#/components/schemas/CreatePostResponse' example: id: 00000000-0000-0000-0000-000000000000 status: queued createdAt: '2026-05-15T18:00:00.000Z' scheduledAt: '2026-06-01T12:00:00.000Z' results: - accountId: 11111111-1111-1111-1111-111111111111 platform: twitter postId: 22222222-2222-2222-2222-222222222222 status: queued - accountId: 33333333-3333-3333-3333-333333333333 platform: bluesky postId: 44444444-4444-4444-4444-444444444444 status: queued '400': $ref: '#/components/responses/ValidationError' '401': $ref: '#/components/responses/Unauthenticated' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/IdempotencyConflict' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/InternalError' '502': $ref: '#/components/responses/PlatformError' security: - bearer: [] components: parameters: IdempotencyKey: name: Idempotency-Key in: header required: false description: >- Recommended on every write. Replays within 24 hours return the original response; conflicting bodies surface as `409 idempotency_conflict`. See [Idempotency](https://letmepost.dev/docs/idempotency/). schema: type: string minLength: 1 maxLength: 128 example: post-launch-2026-05-15-001 schemas: CreatePostRequest: type: object description: >- Multi-target publish request — fans a single body out to up to 25 connected accounts in one call. The legacy single-target `account: {}` shape is no longer accepted. required: - targets properties: targets: type: array minItems: 1 maxItems: 25 items: $ref: '#/components/schemas/PostTarget' text: type: string minLength: 1 description: Default text applied to any target that omits its own `text`. media: type: array items: $ref: '#/components/schemas/MediaInput' description: Default media applied to any target that omits its own `media`. firstComment: $ref: '#/components/schemas/FirstComment' publishNow: type: boolean description: >- Explicit immediate-publish mode. Mutually exclusive with `scheduledAt` (`mode_conflict`). When neither is set the request publishes immediately. scheduledAt: type: string format: date-time description: >- ISO-8601 timestamp at least 1 second in the future. When set, every target row is queued and the response is 202. Scheduled posts currently accept text only — media and firstComment require an immediate publish. example: '2026-06-01T12:00:00.000Z' profileId: type: string format: uuid description: >- Profile scope for this batch. Use to target a specific workspace when the API key or OAuth token is org-wide. Forbidden when the key is already scoped to a different profile (rule `profile.scope_mismatch`). Omit to fall back to the key's bound profile. example: targets: - platform: twitter - platform: bluesky - platform: linkedin text: 'Launching with deep links: https://letmepost.dev' text: Shipped multi-target publishing today. CreatePostResponse: type: object description: >- Batch envelope returned by `POST /v1/posts`. `status` summarizes the per-target outcomes. required: - id - status - createdAt - results properties: id: type: string description: >- Batch id — unique per request, ties the per-target rows together for audit. example: 00000000-0000-0000-0000-000000000000 status: type: string enum: - queued - published - partial_failed - failed description: >- `queued`: all targets queued for a scheduled publish (202). `published`: every target succeeded. `partial_failed`: mixed outcomes. `failed`: every target failed. createdAt: type: string format: date-time scheduledAt: type: string format: date-time description: Set when the batch was scheduled (202 responses). results: type: array items: $ref: '#/components/schemas/PostTargetResult' PostTarget: type: object description: >- One target on a multi-target publish. Carries an `accountId`, a `platform` hint, or both (must agree). Per-target `text` / `media` / `firstComment` / `options` override the top-level defaults. properties: accountId: type: string format: uuid description: >- letmepost platform_account id. When omitted, `platform` must be set and the org must have exactly one connected account for that platform. platform: allOf: - $ref: '#/components/schemas/Platform' description: >- Auto-resolve hint. Used alone when the org has exactly one connected account for the platform; combined with `accountId` it must agree (else `targets.account.platform_mismatch`). text: type: string minLength: 1 description: Per-target text override. Falls back to the top-level `text`. media: type: array items: $ref: '#/components/schemas/MediaInput' description: Per-target media override. Falls back to the top-level `media`. firstComment: allOf: - $ref: '#/components/schemas/FirstComment' description: Per-target first-comment override. options: $ref: '#/components/schemas/TargetOptions' MediaInput: type: object description: >- A single media item attached to a post. Exactly one of `mediaId` / `url` / `bytesBase64` must be present. required: - kind properties: kind: type: string enum: - image - video altText: type: string description: Per-platform alt-text caps apply (e.g. Bluesky 2000, Twitter 1000). mediaId: type: string pattern: ^med_[0-9A-Za-z]{22}$ description: >- References a previous `POST /v1/media` upload. Preferred for production — bytes already live on our CDN. example: med_01HY6X4AWBJM2K9F2PTQMR url: type: string format: uri description: >- Public URL we fetch from your CDN at publish time. Must respond 200 to anonymous GET. example: https://cdn.example.com/launch.jpg bytesBase64: type: string description: >- Inline base64. Convenient for tiny images and tests; use `POST /v1/media` for anything substantial. FirstComment: type: object description: >- Auto-posted reply to the published post. Bluesky-only today; ignored on platforms that don't support it. required: - text properties: text: type: string minLength: 1 PostTargetResult: type: object description: >- Per-target outcome inside a `CreatePostResponse.results[]`. `error` is set when this target failed; otherwise `uri` / `cid` (when the platform exposes them) are set. required: - accountId - platform - status properties: accountId: type: string description: Echo of the resolved account id for this target. platform: $ref: '#/components/schemas/Platform' postId: type: string description: >- letmepost-side post row id for this target. Use with `GET /v1/posts/{id}`. status: $ref: '#/components/schemas/PostStatus' uri: type: string description: >- Platform-native URI (e.g. AT Proto `at://…` for Bluesky, post URN for LinkedIn). cid: type: string description: Content id (Bluesky only). firstCommentUri: type: string firstCommentCid: type: string warnings: type: array items: type: object required: - code - message properties: code: type: string message: type: string error: type: object description: >- Per-target failure detail. Present only when `status` is `rejected` or `failed`. required: - code - message properties: code: $ref: '#/components/schemas/ErrorCode' message: type: string rule: type: string remediation: type: string platformResponse: {} ApiError: type: object description: >- Stable error envelope. Every non-2xx response uses this shape. `docUrl` is always present; `ruleUrl` is present whenever `rule` is set. required: - error properties: error: type: object required: - code - message - docUrl - requestId properties: code: $ref: '#/components/schemas/ErrorCode' message: type: string description: >- Human-readable summary. Stable enough to log, not stable enough to switch on — switch on `code` and `rule`. rule: type: string description: >- The specific preflight rule or validator that failed (e.g. `bluesky.text.max_graphemes`, `targets.options.platform_mismatch`). example: bluesky.text.max_graphemes platform: $ref: '#/components/schemas/Platform' platformVersion: type: string description: >- Pinned upstream API version the call targeted (e.g. `graph-v23.0` for Facebook). platformResponse: description: Raw upstream platform response, when available. remediation: type: string description: Actionable next step for the caller — short, imperative. docUrl: type: string format: uri description: Link to the docs page for this `code`. example: https://docs.letmepost.dev/errors/preflight_failed ruleUrl: type: string format: uri description: >- Link to the docs page for this preflight `rule`. Present whenever `rule` is set. example: https://docs.letmepost.dev/preflight/bluesky-text-max_graphemes requestId: type: string description: >- Per-request correlation id, also echoed in the `X-Request-Id` response header. example: req_01HY6X4AWBJM2K9F2PTQMRD9JQ traceId: type: string description: OpenTelemetry trace id, when tracing is active. example: error: code: preflight_failed message: Bluesky posts are capped at 300 graphemes; this body is 312. rule: bluesky.text.max_graphemes platform: bluesky remediation: Trim 12 graphemes, or split into a thread. docUrl: https://docs.letmepost.dev/errors/preflight_failed ruleUrl: https://docs.letmepost.dev/preflight/bluesky-text-max_graphemes requestId: req_01HY6X4AWBJM2K9F2PTQMRD9JQ Platform: type: string enum: - bluesky - facebook - instagram - linkedin - pinterest - threads - tiktok - twitter description: >- Supported platforms. `tiktok` is currently in App Review — connect requests return `platform_not_enabled` until approval lands. TargetOptions: description: >- Per-target platform options. Discriminated on `platform`; the discriminator must match the resolved account's platform or the request fails with `targets.options.platform_mismatch`. Replaces the v0 top-level `pinterest` / `threads` / `twitter` keys. oneOf: - type: object required: - platform properties: platform: type: string enum: - twitter replyToTweetId: type: string minLength: 1 description: Reply under this tweet id. quoteTweetId: type: string minLength: 1 description: >- Quote this tweet id. Mutually exclusive with `replyToTweetId` — X rejects tweets that combine the two. - type: object required: - platform properties: platform: type: string enum: - pinterest boardId: type: string minLength: 1 description: >- Pinterest board to pin to. Falls back to the account's default board when omitted. destinationUrl: type: string format: uri description: Outbound link attached to the pin. title: type: string minLength: 1 coverImageUrl: type: string format: uri description: Cover image URL for video pins. - type: object required: - platform properties: platform: type: string enum: - threads replyToId: type: string minLength: 1 description: Threads thread id to reply under. - type: object required: - platform properties: platform: type: string enum: - bluesky - type: object required: - platform properties: platform: type: string enum: - facebook - type: object required: - platform properties: platform: type: string enum: - instagram - type: object required: - platform properties: platform: type: string enum: - linkedin discriminator: propertyName: platform PostStatus: type: string enum: - queued - validated - publishing - published - failed - rejected - canceled description: >- Lifecycle state of a single per-target post row. `canceled` is the terminal state reached via `DELETE /v1/posts/{id}` on a queued scheduled post. ErrorCode: type: string enum: - validation_failed - preflight_failed - platform_auth_failed - platform_rejected - platform_unavailable - platform_not_enabled - internal_error - unauthenticated - unauthorized - not_found - idempotency_conflict - rate_limited description: >- Canonical error codes. See https://letmepost.dev/docs/errors/ for per-code documentation. headers: X-RateLimit-Limit: description: >- Per-route request ceiling for this endpoint. A static contract — sliding-window remaining/reset live on the IETF-draft `RateLimit-*` headers (no prefix) when enforcement is active. schema: type: integer minimum: 1 example: 1000 X-Request-Id: description: >- Per-request correlation id, also echoed inside the error envelope as `error.requestId`. schema: type: string example: req_01HY6X4AWBJM2K9F2PTQMRD9JQ responses: ValidationError: description: >- `validation_failed` — request body or query parameters didn't match the schema. Rules surfaced include `body.json`, `targets.required`, `targets.max`, `mode_conflict`, `targets.options.platform_mismatch`, `targets.account.platform_mismatch`, `target.account.not_connected`, `target.account.ambiguous`, `scheduledAt.future`, `scheduledAt.text_only`. headers: X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-Request-Id: $ref: '#/components/headers/X-Request-Id' content: application/json: schema: $ref: '#/components/schemas/ApiError' Unauthenticated: description: '`unauthenticated` — missing or invalid Bearer key.' headers: X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-Request-Id: $ref: '#/components/headers/X-Request-Id' content: application/json: schema: $ref: '#/components/schemas/ApiError' NotFound: description: >- `not_found` — the resource does not exist in the caller's organization (or, for profile-scoped keys, in the caller's profile). headers: X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-Request-Id: $ref: '#/components/headers/X-Request-Id' content: application/json: schema: $ref: '#/components/schemas/ApiError' IdempotencyConflict: description: >- `idempotency_conflict` — the same `Idempotency-Key` was used with a different request body. Use a new key, or retry with the original body. headers: X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-Request-Id: $ref: '#/components/headers/X-Request-Id' content: application/json: schema: $ref: '#/components/schemas/ApiError' RateLimited: description: >- `rate_limited` — too many requests. Inspect `X-RateLimit-Limit` (static ceiling) and the IETF-draft `RateLimit-*` headers (sliding-window remaining/reset) before retrying. headers: X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-Request-Id: $ref: '#/components/headers/X-Request-Id' content: application/json: schema: $ref: '#/components/schemas/ApiError' InternalError: description: >- `internal_error` — something on our end failed unexpectedly. Quote the `requestId` when reporting. headers: X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-Request-Id: $ref: '#/components/headers/X-Request-Id' content: application/json: schema: $ref: '#/components/schemas/ApiError' PlatformError: description: >- `platform_auth_failed`, `platform_rejected`, `platform_unavailable`, or `platform_not_enabled` — the upstream platform refused the call. `platformResponse` carries the raw upstream payload when available. headers: X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-Request-Id: $ref: '#/components/headers/X-Request-Id' content: application/json: schema: $ref: '#/components/schemas/ApiError' securitySchemes: bearer: type: http scheme: bearer bearerFormat: lmp_live_… or lmp_test_… description: >- Mint an API key in the dashboard. See https://letmepost.dev/docs/authentication/. ````