Appearance System Light Dark

Your tools are welcome.

Use the API to manage posts and media, publish and schedule, and read recorded social-account statistics. Connect an MCP client to use the same operations through an assistant.

Create an API token in Settings · OpenAPI specification · Download the Node upload helper

Authentication

Crickets+ and the separate API/MCP add-on are required. Create a named token in Account settings → API access; it is automatically scoped to your account. Tokens have full access to supported account operations. Copy the token once and store it as a secret. Send Authorization: Bearer <token>; never include it in a URL. Browser-only account and Administration controls are not exposed.

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

Responses contain data and request_id. Failures contain error.code, error.message, and optional field details. Store returned workspace, account, brand, post, and media IDs exactly.

Draft, check, publish

Resource URLs begin /api/v1/workspaces/{workspace_id}. Creating a post always saves a draft. Publishing and scheduling are separate actions.

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

Set BASE=https://app.crickets.social/api/v1/workspaces/WORKSPACE_ID. Retrieve GET /posts/{id} and keep its ETag. Edit with PATCH /posts/{id} and If-Match: "revision". Omitted fields stay unchanged; a supplied destination array replaces the list. Destination text/media overrides are supported.

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"}]}'

POST /posts/{id}/publish publishes immediately. POST /posts/{id}/schedule and PATCH /posts/{id}/reschedule take scheduled_at as an ISO instant and support an IANA timezone. Use times at least 30 seconds in the future. These actions require both If-Match and Idempotency-Key. Other actions are cancel and duplicate. Poll the post’s destination outcomes after an accepted publish. A 202 response is not proof of publication.

Preflight never saves, publishes, or reserves allowance. Conditions are rechecked at publication. X allowance and YouTube Private-only restrictions apply exactly as in the app. Published, publishing, and uncertain history cannot be edited/deleted. Deleting a draft does not delete social-network content. Uncertain delivery retry requires checked_platform:true after checking the platform.

Media

List GET /media, inspect GET /media/{id}, download GET /media/{id}/file, save alt text with PATCH /media/{id}, and delete unused items with DELETE /media/{id}. Media stays private.

Use the helper for uploads: unzip the kit, install Sharp, and run the helper with Node 22.14 or newer. It reads current image defaults, normalizes orientation, strips source metadata, preserves proportions without enlargement, flattens transparency onto white, and uses Crickets’ Squoosh resize/MozJPEG policy.

npm install sharp@0.35.4
export CRICKETS_WORKSPACE_ID='WORKSPACE_ID'
node --experimental-strip-types scripts/api-upload.mjs '/path/to/photo.png'

Direct uploads accept prepared JPEGs or unchanged H.264 MP4 videos. MP4 size must be strictly below 10,000,000 bytes. Start with POST /media/uploads containing name/type/size. Upload sequential binary parts with PUT /media/{id}/parts/{number}, then complete with POST /media/{id}/complete and the ordered parts array. The API validates type, dimensions, metadata, actual size, and storage allowance. A failed completion removes the invalid item. Start again after correcting the source. Attachment references prevent deletion.

Statistics and discovery

GET /accounts, /brands, and /capabilities expose usable destinations, platform limits, image defaults, and remaining allowance. Read /accounts/{id}/statistics, /posts/{id}/statistics, or /statistics. Follower queries accept start_date/end_date with a maximum 365-day span. Engagement is cumulative at its recorded refresh time, not a historical engagement backfill. Missing values are null; zero is real zero. Coverage, errors, timestamps, and last-known values remain explicit.

Request POST /accounts/{id}/statistics/refresh for a guarded asynchronous refresh. Provider permissions, five-minute refresh guards, leases, and platform budgets still apply. List endpoints support cursor/limit (50 by default, maximum 100). Post/account lists and workspace statistics support intersecting brand_id/platform filters; use brand_id=none for ungrouped items.

Reliable writes

Use a stable unique Idempotency-Key for each create, duplicate, publish, schedule, reschedule, cancel, or retry command. Results are retained for 24 hours. Identical retries return the stored result; changed input with the same key returns 409. If a request is still running, retry later with the same key. Obtain a fresh ETag after a 412 revision conflict. Revoking access does not cancel already accepted schedules.

Limits are 60 requests per credential and 180 per user each minute across REST/MCP. Inspect RateLimit-Limit, RateLimit-Remaining, and Retry-After. Credentials and request bodies are excluded from activity logs.

Statistics example

curl "$BASE/workspaces/$CRICKETS_WORKSPACE_ID/statistics" \
  -H "Authorization: Bearer $CRICKETS_API_TOKEN"

Signed webhooks

Create POST /webhooks with a public HTTPS url and an events array. Save the returned signing_secret once. Supported events: post.created, post.updated, post.draft, post.scheduled, post.publishing, post.published, post.partial, post.failed, delivery.published, delivery.failed, delivery.blocked, delivery.needs_review, media.ready, account.reconnect_required.

Events contain stable id/type/workspace_id/created_at and resource identifiers/statuses in data. Verify the Crickets-Signature header: t=timestamp,v1=base64url_signature. Calculate HMAC-SHA256 of timestamp + "." + raw_request_body using the signing secret; compare in constant time and reject timestamps more than five minutes away. Deduplicate by event id. Return 2xx promptly. Delivery is at least once; retries occur after 1 minute, 5 minutes, 30 minutes, 2 hours, and 12 hours.

Inspect GET /webhooks/{id}/deliveries and replay failed deliveries with POST /webhooks/{id}/deliveries/{delivery_id}/replay. Webhooks belong to their integration. Revocation, loss of account access, or an inactive API/MCP add-on blocks delivery. Losing subscription access suspends credentials without deleting them; access resumes when eligibility returns. Private-network destinations and redirects are rejected.

curl "$BASE/workspaces/$CRICKETS_WORKSPACE_ID/webhooks" \
  -H "Authorization: Bearer $CRICKETS_API_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"url":"https://your-service.example/crickets","events":["post.published","delivery.failed","media.ready"]}'

MCP connections

Set your client’s Streamable HTTP URL to https://app.crickets.social/mcp. Browser OAuth reuses Crickets sign-in, shows the client and requested full access, and lets automatically scopes access to your account. Connected applications appear in Settings → API access. Clients supporting custom headers can instead send your Crickets API token in Authorization: Bearer.

Tools have named operations and schemas matching the API. Workspace IDs remain explicit API parameters for compatibility; they identify your internal account container. Editing actions take revision; retry-safe commands take idempotency_key. Creating a draft never publishes it. Upload tools return a 15-minute upload ticket, resource URL, and HTTP instructions; binary parts stay outside model tool arguments. Download instructions use an equally short-lived ticket. Tickets stop working if their integration is revoked or loses workspace access.

MCP tool example

This request uses the current protocol. Older clients can use their normal initialization and Streamable HTTP flow.

curl https://app.crickets.social/mcp \
  -H "Authorization: Bearer $CRICKETS_API_TOKEN" \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H 'MCP-Protocol-Version: 2026-07-28' \
  -H 'Mcp-Method: tools/call' -H 'Mcp-Name: get_identity' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"get_identity","arguments":{},"_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28","io.modelcontextprotocol/clientCapabilities":{}}}}'