Posts

Publish to a Facebook Page through the shared POST /v1/posts surface.

Cross-platform flow: Media guide.

Supported formats

`mediaKind`	Supported	With text	Notes
`text`	Yes	Required	No `mediaUrls`
`image`	Yes	Yes	Single image URL
`multi-image`	Yes	Yes	2–10 images only
`video`	Yes	Yes	Single video URL
`stories`	Yes	No	Photo or video Page story

Features

Feature	Supported	Notes
Thread	No	X / Threads
Quote	No	X / Threads
Schedule	Yes	`scheduledFor` + `timezone`
Remote delete	Yes	`DELETE …/destinations/:id`

Create

curl -X POST https://api.onepostly.com/v1/posts \
  -H "x-api-key: op_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Hello from Onepostly",
    "mediaKind": "text",
    "destinations": [
      { "connectionId": "YOUR_FACEBOOK_CONNECTION_ID" }
    ]
  }'

{
  "text": "Hello from Onepostly",
  "mediaKind": "text", // text | image | multi-image | video | stories
  "mediaUrls": [],
  "destinations": [
    { "connectionId": "YOUR_FACEBOOK_CONNECTION_ID" }
  ]
}

Response: 202 with status: "queued". Poll GET /v1/posts/:id until the destination is published or failed — or use webhooks instead of polling.

Image

{
  "text": "Caption optional",
  "mediaKind": "image",
  "mediaUrls": ["https://cdn.example.com/photo.jpg"],
  "destinations": [{ "connectionId": "YOUR_FACEBOOK_CONNECTION_ID" }]
}

Multi-photo

{
  "text": "Album caption",
  "mediaKind": "multi-image",
  "mediaUrls": [
    "https://cdn.example.com/1.jpg",
    "https://cdn.example.com/2.jpg"
  ],
  "destinations": [{ "connectionId": "YOUR_FACEBOOK_CONNECTION_ID" }]
}

Requires 2–10 image URLs
Video URLs in a multi-photo post → INVALID_MEDIA

Video

{
  "text": "Video description",
  "mediaKind": "video",
  "mediaUrls": ["https://cdn.example.com/video.mp4"],
  "destinations": [{ "connectionId": "YOUR_FACEBOOK_CONNECTION_ID" }]
}

Facebook may continue processing after the destination is marked published.

Stories

{
  "mediaKind": "stories",
  "mediaUrls": ["https://cdn.example.com/story.jpg"],
  "destinations": [{ "connectionId": "YOUR_FACEBOOK_CONNECTION_ID" }]
}

Image or video URL supported
Story video max 100 MB

Pass scheduledFor (timezone-naive local datetime, e.g. 2026-07-16T12:00:00) and timezone (IANA, e.g. America/New_York). Defaults to UTC when timezone is omitted. Do not send Z or a numeric offset on scheduledFor. Future times stay scheduled until publish time.

Remote delete

curl -X DELETE "https://api.onepostly.com/v1/posts/POST_ID/destinations/DEST_ID" \
  -H "x-api-key: op_YOUR_KEY"

Emits destination.deleted.

Media

POST /v1/media (multipart file) → CDN url
Pass that URL in mediaUrls on create post

Details and limits: Media.

Publish errors (Facebook)

Code	When
`TEXT_REQUIRED`	Text-only post with empty message
`MEDIA_REQUIRED`	Image / video / stories without a URL
`INVALID_MULTI_IMAGE`	Fewer than 2 or more than 10 multi-photo URLs
`INVALID_MEDIA`	Video in multi-photo, empty story body, story video >100 MB
`MEDIA_UNFETCHABLE`	Media URL could not be downloaded
`STORY_UPLOAD_FAILED`	Story upload failed
`TOKEN_INVALID`	Reconnect Page
`PERMISSION_DENIED`	Missing `pages_manage_posts` → reconnect
Transient / rate limit	Transient — retry later