API
API quickstart
Schedule a post end to end with three curl requests.
Last updated on
You need an API key (Developer API in the dashboard sidebar) and at least one connected channel.
1. Find a channel to post to
curl https://app.postonus.com/api/v1/integrations \
-H "x-api-key: $POSTONUS_API_KEY"[
{
"id": "int_...",
"platform": "LINKEDIN",
"name": "Ada Lovelace",
"image": "https://...",
"tokenStatus": "VALID",
"connectStatus": "ACTIVE",
"connectionErrorCode": null,
"connectionError": null,
"lastValidatedAt": "2026-08-01T09:00:00.000Z",
"expiresAt": null,
"autoRefreshUnavailable": false,
"hasFailedSchedules": false
}
]Take the id of the channel you want — that is the integrationId the next call needs.
2. Schedule the post
curl -X POST https://app.postonus.com/api/v1/posts \
-H "x-api-key: $POSTONUS_API_KEY" \
-H "content-type: application/json" \
-d '{
"rows": [{ "content": "Shipped it." }],
"shared": { "selectedIntegrations": ["int_..."] },
"postAction": "NEXT_WINDOW"
}'postAction picks when it goes out:
| Value | Meaning |
|---|---|
NEXT_WINDOW | The next recommended posting time (default). |
SCHEDULED_TIME | The scheduledAt you pass on each row. |
PUBLISH_NOW | Immediately. |
DRAFT | Not scheduled at all — held on the calendar if a row carries a date. |
A response of 201:
{
"postId": "pst_...",
"postIds": ["pst_..."],
"message": "Posts created successfully",
"scheduleCount": 1
}3. Check it landed
curl https://app.postonus.com/api/v1/posts/pst_... \
-H "x-api-key: $POSTONUS_API_KEY"The response includes a schedules array with one entry per channel, each carrying its own status (SCHEDULED, PUBLISHING, PUBLISHED, or FAILED) and scheduledAt.
If it fails
402 PAYMENT_REQUIRED— your workspace has no active subscription. A Free workspace can create drafts but not schedules; add a card.403 POST_QUOTA_EXCEEDED— you have hit your plan's monthly cap for that platform.400 CONTENT_TOO_LONGorMEDIA_RULE_VIOLATED— the content or media does not fit the target platform's rules.
See Errors for the full shape, and the reference for every field posts.create accepts, including media, threads, and per-platform overrides.