Sign in
X Write

Create community

Creates an X Community through a connected account.

post/api/v1/x/communities

Headers

Idempotency-Keystring required

Use one unique value per intended write. Reuse it only for an identical retry. Matching retries return the original action. Different input returns 409. Protection lasts at least 90 days.

Request body

accountstring required

X account (@username or ID) creating the community

namestring required

Community name

descriptionstring

Community description

Example request

{
  "account": "@elonmusk",
  "name": "Example Name",
  "description": "A community for Tesla enthusiasts"
}

Response

Write reached a terminal state.

object'x_write_action' required
idstring required
writeActionIdstring required
action'create_tweet' | 'delete_tweet' | 'like' | 'unlike' | 'retweet' | 'unretweet' | 'follow' | 'unfollow' | 'remove_follower' | 'send_dm' | 'upload_media' | 'update_profile' | 'update_avatar' | 'update_banner' | 'create_community' | 'delete_community' | 'join_community' | 'leave_community' required
status'accepted' | 'dispatching' | 'pending_confirmation' | 'success' | 'failed' | 'expired' required
terminalboolean required
retryableboolean required

True only when a new attempt can reasonably succeed.

safeToRetryboolean required

True only when no write was dispatched and a new idempotency key may be used.

statusUrlstring required
pollAfterMsinteger nullable required
chargedboolean required
chargedCreditsstring required
targetIdstring nullable required
requestHashstring
requestIdstring
idempotentboolean
errorstring
messagestring
sendDispatchedboolean required
sendDispatchedAtstring date-time

Dispatch timestamp when the write reached execution.

createdAtstring date-time
updatedAtstring date-time
completedAtstring date-time
expiresAtstring date-time

Deadline for resolving a non-terminal write. This is not the Idempotency-Key retention deadline.

confirmedAtstring date-time
confirmationCheckedAtstring date-time
confirmationAttemptsinteger
tweetIdstring

Compatibility field for a confirmed tweet result ID.

messageIdstring

Compatibility field for a confirmed direct message ID.

mediaIdstring

Compatibility field for a confirmed media upload ID.

mediaUrlstring uri

Public media URL when the upload creates one.

communityIdstring

Compatibility field for a confirmed community ID.

communityNamestring

Confirmed community name when available.

resultIdstring

Compatibility result ID for other write actions.

mediaobject

Media count, kind, size, and billing details when used.

detailsobject

Structured recovery context for a failed write.

successboolean required

Example response

{
  "id": "12345",
  "writeActionId": "12345",
  "action": "like",
  "status": "success",
  "terminal": true,
  "statusUrl": "/api/v1/x/write-actions/12345",
  "pollAfterMs": 1000,
  "charged": true,
  "chargedCredits": "10",
  "billing": {
    "status": "charged",
    "charged": true,
    "plannedCredits": "10",
    "chargedCredits": "10"
  },
  "request": {
    "hash": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
    "payload": {
      "tweet_id": "9876543210"
    }
  },
  "account": {
    "id": "42",
    "username": "example"
  },
  "target": {
    "type": "tweet",
    "id": "9876543210"
  },
  "targetId": "9876543210",
  "result": {
    "type": "state_change",
    "id": "9876543210",
    "state": "liked"
  },
  "nextAction": {
    "type": "poll",
    "url": "/api/v1/x/write-actions/12345",
    "afterMs": 2000
  },
  "requestHash": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
  "requestId": "01JZ8R7QSC9QKT0V7JX4M2A6B8",
  "error": "x_write_ambiguous",
  "message": "Invalid input. Check request fields.",
  "sendDispatched": true,
  "sendDispatchedAt": "2026-07-21T05:00:00Z",
  "createdAt": "2026-07-21T05:00:00Z",
  "updatedAt": "2026-07-21T05:00:02Z",
  "completedAt": "2026-07-21T05:00:02Z",
  "expiresAt": "2026-07-22T05:00:00Z",
  "confirmedAt": "2026-07-21T05:00:02Z",
  "confirmationCheckedAt": "2026-07-21T05:00:02Z",
  "confirmationAttempts": 1,
  "tweetId": "9876543210",
  "messageId": "1234567890",
  "mediaId": "2345678901",
  "mediaUrl": "https://media.xquik.com/example.jpg",
  "communityId": "3456789012",
  "communityName": "Builders",
  "resultId": "9876543210",
  "media": {
    "count": 1,
    "kind": "image"
  },
  "details": {
    "suggestion": "Poll the action status URL."
  },
  "success": true
}

Changes