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

posts

curl --request POST \
  --url https://api.letmepost.dev/v1/posts \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "targets": [
    {
      "accountId": "00000000-0000-0000-0000-000000000000"
    }
  ],
  "text": "Hello from letmepost.dev"
}
'

{
  "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..."
    }
  ]
}

Authorizations

Authorization

string

header

required

Mint an API key in the dashboard. See https://letmepost.dev/docs/authentication/.

Headers

Idempotency-Key

string

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

Required string length: 1 - 128

Example:

"post-launch-2026-05-15-001"

Body

application/json

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.

targets

object[]

required

Required array length: 1 - 25 elements

Show child attributes

text

string

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

Minimum string length: 1

media

object[]

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

Show child attributes

firstComment

object

Auto-posted reply to the published post. Bluesky-only today; ignored on platforms that don't support it.

Show child attributes

publishNow

boolean

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

scheduledAt

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

Example:

"2026-06-01T12:00:00.000Z"

profileId

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

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

Batch envelope returned by POST /v1/posts. status summarizes the per-target outcomes.

string

required

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

Example:

"00000000-0000-0000-0000-000000000000"

status

enum<string>

required

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

Available options:

queued,

published,

partial_failed,

failed

createdAt

string<date-time>

required

results

object[]

required

Show child attributes

scheduledAt

string<date-time>

Set when the batch was scheduled (202 responses).

curl --request POST \
  --url https://api.letmepost.dev/v1/posts \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "targets": [
    {
      "accountId": "00000000-0000-0000-0000-000000000000"
    }
  ],
  "text": "Hello from letmepost.dev"
}
'

{
  "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..."
    }
  ]
}

Posts

Media

Accounts

API Keys

Webhooks

Publish or schedule a multi-target post

Authorizations

Headers

Body

Response