REST API

Plain JSON HTTP API backing the website, the CLI's auth flow, and the MCP server.

Base URL

https://xvideodownloader.org

Authentication

Anonymous requests work for basic downloads within the anonymous rate limit. For a persistent account (higher limits, download history, SVIP), send Authorization: Bearer <token> — get a token via the CLI's auth login command, or by signing in on the website.

Rate limits

Free plan (anonymous or registered): 2 downloads/day, 720p max, 25MB per file. Lifetime SVIP: no daily limit, no quality or size cap. Enforced per IP for anonymous requests and per account when authenticated.

Endpoints

POST/api/download

Create a download task from an X/Twitter post URL.

GET/api/downloads/{id}

Get a download task's status and metadata.

GET/api/file/{id}

302-redirect to the downloaded file. Pass ?dl=1 to count it against your daily quota; omit it for a read-only preview.

GET/api/downloads

List your download history. Requires authentication.

DELETE/api/downloads/{id}

Delete a download record. Cannot delete a running task.

GET/api/user/usage

Today's usage against your plan's daily limit.

GET/api/user/subscription

Current plan and, for legacy subscribers, subscription status.

Error codes

EMPTY_URL	No URL provided
INVALID_URL_FORMAT	URL doesn't start with http(s)
UNSUPPORTED_HOST	Only x.com and twitter.com are supported
RATE_LIMIT	Daily download limit reached
FILE_SIZE_LIMIT	Video exceeds the plan's file size limit
VIDEO_NOT_FOUND	Video could not be found or extracted
PRIVATE_TWEET	The post is private or protected
GEO_BLOCKED	Source content is geo-restricted

Example

Create a download, then poll until it's done:

curl -X POST https://xvideodownloader.org/api/download \
  -H "Content-Type: application/json" \
  -d '{"url": "https://x.com/user/status/123456789"}'

OpenAPI spec

Full request/response schema in OpenAPI 3.0 format for codegen or import into API tools:

/openapi.json →