X Calls API: the 10 endpoints X never announced

#Quick answer

The X Calls API is a live, unannounced set of 10 endpoints under /2/calls that lets code start an X call, hand out its join link, schedule it on a calendar, and put a software participant inside it over a WebSocket carrying PCM16 audio. It is defined in spec version 2.174 and it is not in the changelog, not in the machine-readable docs index, and the three OAuth scopes it requires are absent from every scope list X publishes. The reference pages exist but they are generated spec dumps: the socket protocol you need to actually build against it has never been written down.

Last updated: November 2026

Everything below was measured on 12 November 2026 against the live OpenAPI description at api.x.com/2/openapi.json, cross-checked against X's pricing page, rate-limit page, the three llms.txt indexes and the 4.8 MB llms-full.txt bundle.

#The 10 operations

Eight of the 10 accept OAuth 1.0a user tokens as an alternative to OAuth 2.0. The two that do not are join and leave, the pair that moves audio. Those are OAuth 2.0 user context only, with no fallback, which matters if you were planning to drive this from an older twurl-shaped stack. The split is worth reading alongside which auth each X API endpoint actually takes, because this is the first endpoint group on the platform that quietly drops OAuth 1.0a entirely.

#The scopes do not exist on paper

X's OAuth 2.0 guide carries a scope table. It runs 24 rows, from tweet.read at the top to broadcast.write at the bottom, and it is the canonical list every tutorial copies.

calls.read, calls.write and calls.join are not in it.

That is not a reading error. llms-full.txt is X's own single-file dump of the entire documentation set, 4,860,318 bytes on 12 November 2026. Each of those three strings appears in it zero times. The spec is the only published artefact that names them, and it names them only inside the security block of each operation.

Practically, you request them in the authorize URL like any other scope and find out whether the consent screen accepts them. There is no documented display string, no description row, and no entry in the authentication mapping guide that tells you which endpoints a scope unlocks. For a surface that can put a microphone-shaped thing into a conversation, that is a thin paper trail.

#Join is the interesting one

POST /2/calls/{id}/join is not a "mark me as present" call. It starts a media session, and the 200 response is a handshake:

You open a WebSocket to media_url, send the media_token as a Bearer credential, and from there you exchange audio and events. The request body lets you choose the format: media.type is websocket (the only value), media.audio.encoding is pcm16 (the only value, little-endian mono), and media.audio.sample_rate is 8000, 16000, 24000 or 48000, defaulting to 24000.

Raw PCM16 at 24 kHz is the native input format of every realtime speech model shipping right now. That is not a coincidence, and X is not being coy about the intent: the description on POST /2/calls says the call is "hosted by the authenticated user (typically a bot)", and the description on POST /2/calls/scheduled tells you to "put an agent in it at start time with POST /2/calls/:id/join".

Here is the gap. The event schema on that socket is undocumented. The strings media_token, pcm16, requires_approval and session.ended each appear exactly once in the entire documentation bundle, which is the one sentence of endpoint description they come from. There is no event list, no error taxonomy, no reconnect guidance, no sample code in any language. The single named event anywhere is session.ended with reason: left, mentioned in passing on the leave endpoint. Anyone building a voice agent on this is reverse-engineering a protocol by connecting to it.

Neither official SDK helps. The Python and TypeScript XDK indexes mention calls zero times, which matches the module inventory of the published Python wheel: no Calls module at all. Same story as the gaps catalogued in the X API OpenAPI spec, where the spec consistently runs ahead of both the docs and the generated clients.

#The call id is the join secret

Read this field description twice, because it is doing a lot of work:

id - Unique identifier of the call; also its join secret.

A call id is not an opaque handle you can sprinkle through logs and error reports. It is the credential. The same note appears on ScheduledCall.call_id. The only barrier in front of a leaked id is join_policy, which you set once at create time and cannot change afterwards through any of the 10 endpoints:

• open (the default): anyone with the link joins
• closed: the host admits each person individually
• trusted: members of the host's Verified Organization join, everyone else asks

Note which one is the default. If you build anything that creates calls programmatically and stores or forwards the ids, pass join_policy: "closed" or "trusted" explicitly on every create, scrub ids from your logs, and treat an id in a support ticket the way you would treat a session cookie. A joiner can also check viewer_may_join on GET /2/calls/{id} to learn whether they get in without asking.

One more asymmetry: the recipient's settings still win. X's help documentation gates calls behind a prior Direct Message, and the four permission toggles are exposed on PUT /2/chat/settings as accept_calls_from_everyone, accept_calls_from_following, accept_calls_from_verified and accept_calls_from_addressbook. Those belong to the person being called, not to your app. The consumer-side rules, including the privacy default that leaks IP addresses peer to peer, are in audio and video calls on X, and the container they live in is XChat.

#The scheduling half is a calendar, not a queue

Six of the 10 endpoints are about scheduled calls, and they are closer to Outlook than to a job runner. POST /2/calls/scheduled takes start_time (RFC 3339, not in the past), up to 25 invitee_ids, a duration_minutes that defaults to 30 and tops out at 44,640, and an optional RFC 5545 recurrence RRULE such as FREQ=WEEKLY;BYDAY=MO with an IANA time_zone. Invitees get an email unless you pass notify_invitees: false.

A few edges that will bite:

• 44,640 minutes is 31 days. The maximum call length on paper is a month long.
• Recurring edits need two parameters. scope takes all, this or this_and_following, and this-style scopes need occurrence_start_time to say which occurrence you mean. scope defaults to all without it and this with it.
• Linked calendars are read-only. GET /2/calls/scheduled returns X Calls events and events from Microsoft Outlook calendars the user linked to X. Outlook-sourced entries have calendar: "outlook", no id, and no invitees, so you cannot update, cancel or RSVP to them through the API. Those have to be changed in Outlook.
• The list window is capped. It defaults to the next 24 hours and may span at most 7 days, with max_results between 1 and 100 defaulting to 20.
• Reads are field-gated. call.fields offers 8 values and host_id is only reachable through expansions=host_id; scheduled_call.fields offers 12, with call_id, invitees and organizer_id behind expansions. The pattern is the same one documented for X API expansions.

Cancelling something already cancelled succeeds, which is a sane idempotency choice and rarer in this API than it should be.

#Nobody has priced it

X prices resource categories, not routes. Reads run from $0.001 to $0.010 per resource, writes from $0.005 to $0.200 per request, and webhook events get their own table. There is no Call row in any of them, and no /2/calls row on the rate-limit page either.

X's pricing page covers itself: different endpoints have different costs, and current rates live in the Developer Console. So the honest answer is that the Console is the only authority, and the first call you make is also your price discovery. If you are modelling spend, what pay-per-use actually costs is the arithmetic to start from, and a media session that bills per minute would behave unlike anything else on the platform.

Account shape is its own question. The endpoint description says the host is "typically a bot", and bot accounts are created and tokened through their own endpoint group, covered in the X Bots API. Whether a bot token can hold calls.join is not documented anywhere, which is the sort of thing you learn from a 403.

#What this is for, and what it is not

The shape of the surface tells you the use cases X has in mind. A support agent that answers a call in an XChat conversation. A standing weekly call with an AI notetaker that joins on the recurrence. A voice interface to a product, reachable from a join link in a post. All three are now buildable against a documented request body and an undocumented socket.

What it is not is a growth tool. There is no discovery here, no way to reach someone who has not DMed you first, and no broadcast. Calls are a one-to-few surface with a hard prerequisite on the other person's prior action, and X built it that way on purpose. If what you want is reach rather than conversation, the API side of that story has been narrowing since the February 2026 reply restrictions, and what the X API is and how to use it is the current map.

That gap is where browser-driven tools like X-Autopilot live, and the trade is worth stating plainly rather than selling. Driving your own browser on your own machine is not the sanctioned path, and we do not claim it complies with X's terms: browser automation is a grey area and X's automation rules are the document to read before deciding anything. What it offers against cloud schedulers is a lower detection surface, not an absent one - residential IP, your own browser session, no delegate account, no shared cloud IP pool. Reduced exposure. If sanctioned access is a hard requirement, the API is the route, and /2/calls is now part of it whether or not X has said so.

#The bottom line

Ten endpoints, three undocumented scopes, one undocumented WebSocket protocol, and no price. The Calls API is real, it is in the spec, and the reference pages are live at docs.x.com/x-api/calls/* even though the index that AI tools read has never heard of them.

If you want to build on it, start from the spec rather than the docs, set join_policy explicitly on every create, treat call ids as secrets, and expect to discover the socket protocol by connecting to it. And watch the changelog: when X finally announces this, the announcement is also likely to be the first time the scopes get a definition.