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 X account
`text`	`string`	Yes	Post content (1-280 characters)
`media_urls`	`string[]`	No	Up to 4 public image/video URLs (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 X automatically.

Type	Formats	Max Size	Per Post
Images	JPEG, PNG, WebP, GIF	5 MB	Up to 4
Video	MP4, MOV	512 MB	1 per post

For scheduled posts, media is downloaded and stored immediately (URLs may expire before publish time). Media is uploaded to X 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",
    "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`	X 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 X 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, Chirpie also deletes it from X. If the X deletion fails, the post is still marked as deleted in Chirpie.

Response `200 OK`

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

On this page