Posts

Create a Post

Posts are published immediately by default. Add schedule_at to schedule for later.

POST /api/v1/posts
Authorization: Bearer chirpie_sk_YOUR_KEY
Content-Type: application/json

Request Body

Field	Type	Required	Description
`account_id`	`string` (UUID)	Yes	ID of the connected account (X, Bluesky, LinkedIn, Threads, Mastodon, Instagram, Facebook, Telegram, Reddit, Pinterest, TikTok, YouTube, Google Business Profile, or Snapchat)
`text`	`string`	Yes	Post content. Max length depends on platform: 280 (X standard), 25,000 (X Premium), 300 (Bluesky), 3,000 (LinkedIn), 500 (Threads), 500 (Mastodon), 2,200 (Instagram), 63,206 (Facebook), 4,096 (Telegram), 40,000 (Reddit), 500 (Pinterest), 2,200 (TikTok), 5,000 (YouTube), 1,500 (Google Business Profile), or 160 (Snapchat)
`media_urls`	`string[]`	No	Public image/video URLs (up to 4 for most platforms, up to 10 for Instagram carousel — see Media below)
`schedule_at`	`string` (ISO 8601)	No	Schedule for a future time

Media Support

Pass public URLs in media_urls. Chirpie downloads, validates, and uploads them to the target platform automatically.

Platform	Images	Max Image Size	Max Images	Video	Max Video Size
X/Twitter	JPEG, PNG, WebP, GIF	5 MB	4	MP4, MOV	512 MB (1 per post)
Bluesky	JPEG, PNG, WebP, GIF	5 MB	4	Not supported	—
LinkedIn	JPEG, PNG, GIF	8 MB	4	Not supported	—
Threads	JPEG, PNG, WebP, GIF	5 MB	1	Not supported	—
Mastodon	JPEG, PNG, WebP, GIF	8 MB	4	MP4, WebM	40 MB (1 per post)
Instagram	JPEG, PNG	8 MB	10 (carousel)	Not supported	—
Facebook	JPEG, PNG, GIF	10 MB	4	Not supported	—
Telegram	JPEG, PNG, GIF, WebP	10 MB	10	MP4	50 MB
Reddit	JPEG, PNG, GIF	20 MB	1	Not supported	—
Pinterest	JPEG, PNG	20 MB	1 (required)	Not supported	—
TikTok	JPEG, PNG	10 MB	1	MP4 (required)	287 MB
YouTube	—	—	—	MP4, MOV (required)	128 GB
Google Business	JPEG, PNG	5 MB	1	Not supported	—
Snapchat	JPEG, PNG	5 MB	1 (required)	MP4 (required)	32 MB

Media requirements vary by platform: Bluesky, LinkedIn, Threads, and Google Business Profile do not support video. Threads supports only 1 image per post. Instagram requires at least one image — text-only posts are not supported. Instagram supports up to 10 images as a carousel post. Facebook supports Pages only (not personal profiles). Pinterest requires exactly 1 image. TikTok requires video or photo — text-only not supported. YouTube requires video — no image-only posts. Snapchat requires media (image or video). Reddit supports 1 image per post.

For scheduled posts, media is downloaded and stored immediately (URLs may expire before publish time). Media is uploaded to the platform at publish time and cleaned up after.

Example

curl -X POST https://chirpie.ai/api/v1/posts \
  -H "Authorization: Bearer chirpie_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "account_id": "550e8400-e29b-41d4-a716-446655440000",
    "text": "Shipping new features today!",
    "media_urls": ["https://example.com/screenshot.png"],
    "schedule_at": "2026-04-01T14:00:00Z"
  }'

Response `201 Created`

{
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "platform": "x",
    "account_id": "550e8400-e29b-41d4-a716-446655440000",
    "text": "Shipping new features today!",
    "media_urls": null,
    "platform_post_id": null,
    "status": "scheduled",
    "scheduled_at": "2026-04-01T14:00:00.000Z",
    "published_at": null,
    "thread_id": null,
    "thread_order": null,
    "error_message": null,
    "created_at": "2026-03-23T10:00:00.000Z"
  }
}

Error Responses

Status	Code	Condition
`400`	`bad_request`	Invalid text, missing fields, or `schedule_at` in the past
`401`	`unauthorized`	Invalid or missing API key
`404`	`not_found`	Account not found or inactive
`429`	`rate_limited`	Monthly post limit exceeded
`502`	`upstream_error`	Platform API returned an error

List Posts

GET /api/v1/posts
Authorization: Bearer chirpie_sk_YOUR_KEY

Query Parameters

Parameter	Type	Default	Description
`limit`	`integer`	`20`	Results per page (max 100)
`offset`	`integer`	`0`	Pagination offset
`status`	`string`	—	Filter: `draft`, `scheduled`, `publishing`, `published`, `failed`, `deleted`
`account_id`	`string`	—	Filter by account UUID

Example

curl "https://chirpie.ai/api/v1/posts?status=published&limit=10" \
  -H "Authorization: Bearer chirpie_sk_YOUR_KEY"

Response `200 OK`

{
  "data": [
    {
      "id": "a1b2c3d4-...",
      "text": "Hello world!",
      "status": "published",
      "platform_post_id": "1234567890",
      "published_at": "2026-03-23T10:01:00.000Z",
      ...
    }
  ]
}

Get a Post

GET /api/v1/posts/:id
Authorization: Bearer chirpie_sk_YOUR_KEY

Response `200 OK`

Returns a single post object (same shape as list items).

Status	Code	Condition
`404`	`not_found`	Post doesn't exist or belongs to another user

Delete a Post

DELETE /api/v1/posts/:id
Authorization: Bearer chirpie_sk_YOUR_KEY

If the post was published on X, Bluesky, LinkedIn, Threads, Mastodon, Instagram, Facebook, Telegram, Reddit, Pinterest, YouTube, Google Business Profile, or Snapchat, Chirpie also deletes it from the platform. Note: TikTok does not support deletion via API. If the platform deletion fails, the post is still marked as deleted in Chirpie.

Response `200 OK`

{
  "data": {
    "id": "a1b2c3d4-...",
    "deleted": true
  }
}

On this page