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 currently accept text only — media and firstComment 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).

List posts (post log)

Fetch a single post with its publish attempts

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