Scheduling

How Scheduling Works

When you include schedule_at in a create post or thread request, Chirpie stores it with status scheduled and publishes it at the specified time.

curl -X POST https://chirpie.ai/api/v1/posts \
  -H "Authorization: Bearer chirpie_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "account_id": "YOUR_ACCOUNT_ID",
    "text": "This posts at noon UTC tomorrow",
    "schedule_at": "2026-03-24T12:00:00Z"
  }'

Timing

• schedule_at must be a future ISO 8601 datetime
• The scheduler runs every minute — posts publish within ~60 seconds of their scheduled time
• All times are UTC

Post Status Flow

scheduled → publishing → published
                      → failed (retry up to 3 times)

Thread Scheduling

When scheduling a thread, all posts share the same schedule_at. The thread publishes atomically — if any post fails, the entire thread is rescheduled for retry.

curl -X POST https://chirpie.ai/api/v1/threads \
  -H "Authorization: Bearer chirpie_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "account_id": "YOUR_ACCOUNT_ID",
    "posts": [
      { "text": "Thread post 1" },
      { "text": "Thread post 2" }
    ],
    "schedule_at": "2026-03-24T12:00:00Z"
  }'

Scheduled Post Limits

Scheduled posts count against a separate monthly quota:

Canceling a Scheduled Post

Delete the post before its scheduled time to cancel it:

curl -X DELETE https://chirpie.ai/api/v1/posts/POST_ID \
  -H "Authorization: Bearer chirpie_sk_YOUR_KEY"

Minimum Spacing

Scheduled posts for the same account must be at least 5 minutes apart. If you try to schedule a post within 5 minutes of an existing scheduled post for the same account, the API returns 400:

{ "error": { "code": "bad_request", "message": "Scheduled posts must be at least 5 minutes apart for the same account." } }

This prevents X API rate limit issues and ensures reliable delivery.

Retry Behavior

Failed posts are retried up to 3 times with a 5-minute delay between attempts. After 3 failures, the post is marked as failed with an error_message describing the issue.