Posts

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 — code, rule, platformResponse, remediation, docUrl, ruleUrl.

For per-platform payload differences, see the platforms guides.

post/v1/posts

Request

  • Base URL: https://api.letmepost.dev
  • URL: https://api.letmepost.dev/v1/posts
  • Auth: HTTP bearer

Headers

Idempotency-Keystring
Example:post-launch-2026-05-15-001

Recommended on every write. Replays within 24 hours return the original response; conflicting bodies surface as 409 idempotency_conflict. See Idempotency.

Request body

textstring

Default text applied to any target that omits its own text.

publishNowboolean

Explicit immediate-publish mode. Mutually exclusive with scheduledAt (mode_conflict). When neither is set the request publishes immediately.

scheduledAtstring date-time

ISO-8601 timestamp at least 1 second in the future. When set, every target row is queued and the response is 202. Scheduled posts accept text and media (media refs persist and the worker reads them back at fire time); firstComment (rule scheduledAt.no_first_comment) and Bluesky reply threading (rule scheduledAt.no_bluesky_reply) require an immediate publish.

profileIdstring uuid

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 request

{
  "targets": [
    {
      "platform": "twitter"
    },
    {
      "platform": "bluesky"
    },
    {
      "platform": "linkedin",
      "text": "Launching with deep links: https://letmepost.dev"
    }
  ],
  "text": "Shipped multi-target publishing today."
}

Response

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

idstring required

Batch id — unique per request, ties the per-target rows together for audit.

status'queued' | 'published' | 'partial_failed' | 'failed' required

queued: all targets queued for a scheduled publish (202). published: every target succeeded. partial_failed: mixed outcomes. failed: every target failed.

createdAtstring date-time required
scheduledAtstring date-time

Set when the batch was scheduled (202 responses).

Example response

{
  "id": "00000000-0000-0000-0000-000000000000"
}

Changes

No recorded changes to this operation across all 1 revision of this API.