Create Post

`POST /developers/v1/post`

Schedule a post to one or more connected social media accounts. The post will be published at the specified date and time in the specified timezone. Call List Accounts first to obtain valid account IDs and types.

Request

Content-Type: application/json

Headers

Header	Required	Description
`X-API-KEY`	Yes*	Your personal API key.
`Authorization`	Yes*	Bearer token: `Bearer sp_tok_xxxxxxx`.
`Content-Type`	Yes	Must be `application/json`.

*Provide one of the two authentication headers.

Body parameters

Field	Type	Required	Description
`content`	string	Yes	The text of the post. Character limits vary by platform (e.g. 280 characters on Twitter/X).
`date`	string	Yes*	The date to publish, in `YYYY-MM-DD` format. Required unless `post_instant` is `true`.
`time`	string	Yes*	The time to publish, in 24-hour `HH:mm` format. Required unless `post_instant` is `true`.
`post_instant`	boolean	No	If `true`, the post is published immediately and `date`/`time` are ignored. Defaults to `false`.
`timezone`	string	No	IANA timezone name applied to `date`/`time`. Defaults to `"UTC"`. Examples: `"America/New_York"`, `"Europe/London"`, `"Asia/Tokyo"`.
`accounts`	array	Yes	Array of account objects. Minimum 1 item. Each object requires `id` (integer) and `type` (string).
`attachments`	array of strings	No	Media to attach, as `"type-id"` strings obtained from the media upload endpoint. Example: `["image-42", "video-7"]`. A single post cannot mix images and videos.
`replies`	array of strings	No	X/Twitter only. Reply tweets posted as a thread immediately after the main tweet, in array order (your "first comment"). Each reply is limited to 280 characters. Ignored for non-Twitter accounts.

Legacy fields

For backward compatibility the API still accepts the older scheduled_date ("YYYY-MM-DD HH:MM:SS") field as well as image_ids / video_ids (same "type-id" format as attachments). New integrations should use date + time and attachments.

Account object

Field	Type	Required	Description
`id`	integer	Yes	The account ID from List Accounts.
`type`	string	Yes	The platform type from List Accounts, e.g. `"twitter"`, `"linkedin"`.

Example request

curl -X POST https://api.schedpilot.com/developers/v1/post \
  -H "X-API-KEY: smm_4a9f3c1e8b205d7a6e0f2c49b8d3a15f" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Excited to announce our new product launch! Check it out at acme.com/launch",
    "date": "2026-06-15",
    "time": "14:30",
    "timezone": "America/New_York",
    "accounts": [
      { "id": 12, "type": "twitter" },
      { "id": 17, "type": "linkedin" },
      { "id": 23, "type": "instagram" }
    ],
    "attachments": ["image-42"],
    "replies": ["Here is the full thread with more detail 🧵", "And the final takeaway."]
  }'

Response

Status: 202 Accepted

Response fields

Field	Type	Description
`post_id`	integer	The unique ID of the newly created scheduled post.
`content`	string	The post text as stored.
`scheduled_date`	string	The scheduled publish datetime in `YYYY-MM-DD HH:MM:SS` format (in the timezone you supplied).
`timezone`	string	The timezone used for the scheduled datetime.
`accounts`	integer	Number of accounts the post will be published to.
`media`	integer	Number of media attachments on the post.
`replies`	integer	Number of reply tweets queued for the X/Twitter thread.
`status`	string	Delivery state — `"scheduled"`.

Example response

{
  "post_id": 8841,
  "content": "Excited to announce our new product launch! Check it out at acme.com/launch",
  "scheduled_date": "2026-06-15 14:30:00",
  "timezone": "America/New_York",
  "accounts": 3,
  "media": 1,
  "replies": 2,
  "status": "scheduled"
}

Error responses

Status	Description
`400 Bad Request`	Missing required field (e.g. `content`, `accounts`), missing `date`/`time` for a scheduled post, or an invalid date/time/timezone. The response body includes an `error` field with a description.
`401 Unauthorized`	Missing authentication header.
`403 Forbidden`	Invalid API key, or a media attachment does not exist or does not belong to you.
`429 Too Many Requests`	Write rate limit exceeded (30 requests/hour).

Notes

Get account IDs first. Call GET /accounts to retrieve valid id and type values.
Upload media first. To attach images or videos, upload them via POST /media/upload and pass the returned IDs in attachments as "image-<id>" / "video-<id>" strings. If an attachment ID is unknown or not yours, the whole request fails with 403 (media is not silently dropped).
Twitter/X character limit. Twitter enforces a 280-character limit on post text (and on each thread reply). Requests with longer content for a Twitter account will be rejected at publish time. Trim content before scheduling to avoid failed delivery.
Mutually exclusive media. A single post cannot contain both images and videos.
X/Twitter threads. Use replies to post a thread: the main tweet is published first, then each string in replies is posted in order as a reply to the previous tweet. Replies are only sent to X/Twitter accounts and are ignored for other platforms in the same post.
Timezone handling. date/time are interpreted in the timezone you provide. If timezone is omitted, they are treated as UTC. Use IANA timezone names such as "America/Chicago" or "Europe/Paris". Set post_instant: true to publish right away without a date/time.

POST /developers/v1/post​

Request​

Headers​

Body parameters​

Account object​

Example request​

Response​

Response fields​

Example response​

Error responses​

Notes​