Skip to main content

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​

HeaderRequiredDescription
X-API-KEYYes*Your personal API key.
AuthorizationYes*Bearer token: Bearer sp_tok_xxxxxxx.
Content-TypeYesMust be application/json.

*Provide one of the two authentication headers.

Body parameters​

FieldTypeRequiredDescription
contentstringYesThe text of the post. Character limits vary by platform (e.g. 280 characters on Twitter/X).
scheduled_datestringYesThe date and time to publish, in YYYY-MM-DD HH:MM:SS format.
timezonestringNoIANA timezone name for scheduled_date. Defaults to "UTC". Examples: "America/New_York", "Europe/London", "Asia/Tokyo".
accountsarrayYesArray of account objects. Minimum 1 item. Each object requires id (integer) and type (string).
image_idsarray of stringsNoMedia IDs of images to attach, obtained from the media upload endpoint. Example: ["image-42", "image-55"]. Cannot be combined with video_ids.
video_idsarray of stringsNoMedia IDs of videos to attach, obtained from the media upload endpoint. Example: ["video-7"]. Cannot be combined with image_ids.

Account object​

FieldTypeRequiredDescription
idintegerYesThe account ID from List Accounts.
typestringYesThe 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",
    "scheduled_date": "2026-06-15 14:30:00",
    "timezone": "America/New_York",
    "accounts": [
      { "id": 12, "type": "twitter" },
      { "id": 17, "type": "linkedin" },
      { "id": 23, "type": "instagram" }
    ],
    "image_ids": ["image-42"]
  }'

Response​

Status: 201 Created

Response fields​

FieldTypeDescription
post_idintegerThe unique ID of the newly created scheduled post.
contentstringThe post text as stored.
scheduled_datestringThe scheduled publish datetime in YYYY-MM-DD HH:MM:SS format.
timezonestringThe timezone used for scheduled_date.
account_countintegerNumber of accounts the post will be published to.
image_countintegerNumber of images attached to the post.
video_countintegerNumber of videos attached to the post.

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",
  "account_count": 3,
  "image_count": 1,
  "video_count": 0
}

Error responses​

StatusDescription
400 Bad RequestMissing required field, invalid datetime format, both image_ids and video_ids provided, or no accounts specified. The response body includes an error field with a description.
401 UnauthorizedMissing or invalid authentication credentials.
422 Unprocessable EntityOne or more account IDs are invalid or do not belong to the authenticated user.
429 Too Many RequestsWrite rate limit exceeded (30 requests/hour).

Notes​

  • Get account IDs first. Call GET /accounts to retrieve valid id and type values. Supplying an ID that does not belong to your account returns a 422 error.
  • Upload media first. If you want to attach images or videos, upload them via POST /media/upload and use the returned media IDs in image_ids or video_ids.
  • Twitter/X character limit. Twitter enforces a 280-character limit on post text. 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. Use either image_ids or video_ids, not both.
  • Timezone handling. scheduled_date is interpreted in the timezone you provide. If timezone is omitted, the datetime is treated as UTC. Use IANA timezone names such as "America/Chicago" or "Europe/Paris".