API Reference
Threads
Create multi-post threads that publish as connected replies on X.
Create a Thread
Threads are arrays of 2-25 posts published in order as connected replies. Each post in the thread replies to the previous one.
POST /api/v1/threads
Authorization: Bearer chirpie_sk_YOUR_KEY
Content-Type: application/jsonRequest Body
| Field | Type | Required | Description |
|---|---|---|---|
account_id | string (UUID) | Yes | ID of the connected X account |
posts | array | Yes | Array of 2-25 post objects |
posts[].text | string | Yes | Post content (1-280 characters) |
posts[].media_urls | string[] | No | Up to 4 public image/video URLs per post (JPEG, PNG, WebP, GIF up to 5MB; MP4/MOV up to 512MB) |
schedule_at | string (ISO 8601) | No | Schedule the entire thread |
Example
curl -X POST https://chirpie.ai/api/v1/threads \
-H "Authorization: Bearer chirpie_sk_YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{
"account_id": "550e8400-e29b-41d4-a716-446655440000",
"posts": [
{ "text": "I just shipped a feature using Chirpie. Here'\''s how it went 🧵" },
{ "text": "First, I connected my X account via OAuth. Took about 30 seconds." },
{ "text": "Then I created an API key and made my first POST request. Done." },
{ "text": "The whole thing took under 2 minutes. Try it: chirpie.ai" }
]
}'Response 201 Created
{
"data": {
"id": "thread-uuid-here",
"account_id": "550e8400-e29b-41d4-a716-446655440000",
"posts": [
{
"id": "post-1-uuid",
"text": "I just shipped a feature using Chirpie...",
"platform_post_id": "1234567890",
"status": "published",
"thread_order": 0,
"created_at": "2026-03-23T10:00:00.000Z"
},
{
"id": "post-2-uuid",
"text": "First, I connected my X account...",
"platform_post_id": "1234567891",
"status": "published",
"thread_order": 1,
"created_at": "2026-03-23T10:00:00.000Z"
}
],
"status": "published",
"scheduled_at": null,
"created_at": "2026-03-23T10:00:00.000Z"
}
}Billing
A thread counts as N posts where N is the number of posts in the thread. Both post and scheduled limits are checked against the thread size.
Error Responses
| Status | Code | Condition |
|---|---|---|
400 | bad_request | Less than 2 or more than 25 posts, invalid text, or schedule_at in the past |
401 | unauthorized | Invalid or missing API key |
404 | not_found | Account not found or inactive |
429 | rate_limited | Thread would exceed monthly post or scheduled limit |
502 | upstream_error | X API error during publishing |
Scheduled Threads
When schedule_at is provided, all posts in the thread are stored with status: "scheduled". The entire thread is published atomically by the scheduler — if any post fails, the whole thread is rescheduled for retry.