REST API reference and publishing workflow

Base URL and discovery

Base URL: https://app.crickets.social/api/v1. Authenticate with Authorization: Bearer <token>. JSON writes use Content-Type: application/json. Resource routes use /workspaces/{workspace_id}. Get the ID from GET /workspaces.

curl 'https://app.crickets.social/api/v1/workspaces' \
  -H "Authorization: Bearer $CRICKETS_API_TOKEN"

# Substitute the returned ID.
BASE='https://app.crickets.social/api/v1/workspaces/WORKSPACE_ID'
curl "$BASE/accounts" -H "Authorization: Bearer $CRICKETS_API_TOKEN"
curl "$BASE/capabilities" -H "Authorization: Bearer $CRICKETS_API_TOKEN"

Download the current OpenAPI specification for complete input/output schemas. List results use data.items and data.next_cursor. Failures contain error.code, error.message and optional field details; responses include a non-secret request_id.

Create and validate a draft

curl "$BASE/posts" -X POST \
  -H "Authorization: Bearer $CRICKETS_API_TOKEN" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: my-draft-001' \
  -d '{"text":"A small update.","destinations":[{"account_id":"ACCOUNT_ID"}]}'

# Preflight checks readiness without saving or reserving allowance.
curl "$BASE/posts/validate" -X POST \
  -H "Authorization: Bearer $CRICKETS_API_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"text":"A small update.","destinations":[{"account_id":"ACCOUNT_ID"}]}'

Creating always saves a draft. Destination text, media_ids and options can override shared content. For X threads, put the first post in destination text and subsequent replies in options.thread, an ordered array of up to five text strings. Attachments apply to the first post. Each thread consumes one X allowance slot per selected X account. Account responses include x_subscription_type, x_subscription_checked_at and x_subscription_error; preflight uses these cached results. Publication rechecks subscriptions for longer text. Post responses include confirmed thread_publications with IDs, URLs and publication times. Incomplete or uncertain threads require manual review and cannot be retried as a whole. For PATCH, omitted fields stay unchanged; a supplied destinations array replaces the list. Retrieve the post and save its current ETag before edits or publication.

Publish or schedule explicitly

# This action publishes. Use it only when publication is intended.
# Use the current ETag exactly, including its quotation marks.
curl "$BASE/posts/POST_ID/publish" -X POST \
  -H "Authorization: Bearer $CRICKETS_API_TOKEN" \
  -H 'Content-Type: application/json' \
  -H 'If-Match: "1"' \
  -H 'Idempotency-Key: publish-POST_ID-001' \
  -d '{}'

Schedule with POST /posts/{id}/schedule; reschedule with PATCH /posts/{id}/reschedule. Both require a current If-Match, stable Idempotency-Key, and scheduled_at as an ISO instant at least 30 seconds in the future. An optional IANA timezone controls display.

Poll the post’s destination outcomes after an accepted action. 202 means accepted, not published. Conditions are checked again at publication. Uncertain retry requires checked_platform:true after reviewing the platform. Locked published/publishing or uncertain history cannot be edited or deleted.

Revisions, retries and limits

An idempotency key identifies one intended command. Use a unique key for each create, duplicate, publish, schedule, reschedule, cancel or retry command. Keep the same key when resending that command after a timeout.

Identical retries return the stored result for 24 hours. Different input with the same key returns 409. If work is still running, retry later with the same key.

The ETag identifies the post’s revision. After a 412 revision conflict, retrieve the current post and ETag before deciding how to apply your change. Missing or invalid revision preconditions return 428. Do not automatically overwrite another editor’s work.

REST and MCP share limits of 60 requests per credential and 180 per user per minute. Check RateLimit-Limit, RateLimit-Remaining and Retry-After.

List endpoints return 50 items by default and allow up to 100. Use the returned cursor to read the next page. Brand and platform filters narrow results together; brand_id=none selects ungrouped items.

Operation reference

Routes below are relative to /api/v1. Parameters in braces come from returned resource IDs. Use the matching MCP tool when connecting through an assistant.

Read media upload instructions and webhook verification before implementing those flows. API & MCP access does not bypass any provider, storage, media, billing or 𝕏 publication limit.