API Documentation

Authentication

All API requests require a Bearer token in the Authorization header. API keys are prefixed with xthread_ and can be created from your dashboard or via the API.

Authorization: Bearer xthread_your_api_key_here

You can create up to 5 active API keys per account. Keys can be revoked at any time from your dashboard.

Rate Limits

API requests are rate-limited per API key:

• 60 requests per hour per API key
• 500 requests per day per API key

When a rate limit is exceeded, the API returns HTTP 429 with a Retry-After header indicating the number of seconds to wait before retrying.

Credit Costs

Each API request consumes credits from your balance. Costs vary by operation:

Credits are available in packs: 100 credits for $5, 500 credits for $19, or 1500 credits for $49. Pro subscribers receive 100 bonus credits per month.

Error Codes

All error responses follow a consistent format:

{
  "error": "error_code",
  "message": "Human-readable description"
}

POST /api/v1/keys

Create a new API key. Requires session authentication (cookie-based, from dashboard).

Request Body

{
  "name": "My App Key"
}

Example Request

curl -X POST https://x-thread.org/api/v1/keys \
  -H "Content-Type: application/json" \
  -H "Cookie: next-auth.session-token=YOUR_SESSION" \
  -d '{"name": "My App Key"}'

Example Response (201)

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "My App Key",
  "key": "xthread_4f3c2b1a9e8d7c6b5a4f3c2b1a9e8d7c6b5a4f3c2b1a9e8d7c6b5a4f3c2b1a",
  "credits_balance": 0,
  "status": "active",
  "created_at": "2025-01-15T10:30:00Z"
}

Note: The full API key is only returned at creation time. Store it securely.

GET /api/v1/keys

List all your API keys with masked values. Requires session authentication.

Example Request

curl https://x-thread.org/api/v1/keys \
  -H "Cookie: next-auth.session-token=YOUR_SESSION"

Example Response (200)

{
  "keys": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "name": "My App Key",
      "masked_key": "xthread_****2b1a",
      "credits_balance": 85,
      "status": "active",
      "created_at": "2025-01-15T10:30:00Z"
    }
  ]
}

DELETE /api/v1/keys/:id

Revoke an API key. The key will immediately stop working for all requests. Requires session authentication.

Example Request

curl -X DELETE https://x-thread.org/api/v1/keys/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "Cookie: next-auth.session-token=YOUR_SESSION"

Example Response (200)

{
  "success": true,
  "message": "API key revoked"
}

POST /api/v1/threads/convert

Convert an X thread URL to structured data. Requires Bearer token authentication.

Request Body

{
  "url": "https://x.com/username/status/1234567890",
  "format": "json"
}

The format parameter accepts json or markdown. Markdown format costs an additional 1 credit.

Example Request

curl -X POST https://x-thread.org/api/v1/threads/convert \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer xthread_your_api_key_here" \
  -d '{"url": "https://x.com/elonmusk/status/1234567890", "format": "json"}'

Example Response (200)

{
  "id": "t_abc123def456",
  "source_url": "https://x.com/elonmusk/status/1234567890",
  "author": {
    "name": "Elon Musk",
    "handle": "elonmusk"
  },
  "title": "Thread about technology and innovation",
  "tweets": [
    {
      "index": 0,
      "text": "Here's what I think about the future of AI...",
      "url": "https://x.com/elonmusk/status/1234567890"
    },
    {
      "index": 1,
      "text": "First, we need to understand that...",
      "url": "https://x.com/elonmusk/status/1234567891"
    }
  ],
  "cached": false,
  "credits_used": 2,
  "credits_remaining": 83
}

GET /api/v1/threads/:id

Retrieve a previously converted thread by its ID. Costs 1 credit. Requires Bearer token authentication.

Example Request

curl https://x-thread.org/api/v1/threads/t_abc123def456 \
  -H "Authorization: Bearer xthread_your_api_key_here"

Example Response (200)

{
  "id": "t_abc123def456",
  "source_url": "https://x.com/elonmusk/status/1234567890",
  "author": {
    "name": "Elon Musk",
    "handle": "elonmusk"
  },
  "title": "Thread about technology and innovation",
  "tweets": [
    {
      "index": 0,
      "text": "Here's what I think about the future of AI...",
      "url": "https://x.com/elonmusk/status/1234567890"
    },
    {
      "index": 1,
      "text": "First, we need to understand that...",
      "url": "https://x.com/elonmusk/status/1234567891"
    }
  ],
  "cached": true,
  "credits_used": 1,
  "credits_remaining": 82
}

Returns 404 if the thread does not exist or has been removed.

GET /api/v1/usage

Get your current credit balance and usage statistics. Requires Bearer token authentication.

Example Request

curl https://x-thread.org/api/v1/usage \
  -H "Authorization: Bearer xthread_your_api_key_here"

Example Response (200)

{
  "credits_remaining": 82,
  "credits_used_this_month": 18,
  "rate_limit": {
    "requests_per_hour": 60,
    "requests_per_day": 500,
    "hour_remaining": 55,
    "day_remaining": 487
  }
}

No-code Automation Guides

You don't need to write code to integrate x-thread.org into your workflow. Here are two popular ways to automate thread archives:

1. iOS Shortcuts (Apple Devices)

Create a Quick Action on your iPhone or Mac to convert any thread directly from the share sheet:

• Add a Get Shortcut Input action to receive Safari webpages.
• Use the Get Contents of URL action to make a POST request to https://x-thread.org/api/v1/threads/convert.
• Include the Authorization header with your API key, and set request body JSON with the input URL.
• Add a Show Web Page or Save File action to store the resulting markdown or open the viewer.

2. Make.com / Zapier Integrations

Automatically backup threads to Notion or Google Drive when you bookmark them:

• Trigger: Choose Twitter/X "New Tweet in Bookmarks" (or use RSS/Webhook triggers).
• Action: Add an HTTP module to send a POST request to x-thread.org API.
• Destination: Add a Notion database block or Google Drive upload block using the returned JSON values (e.g. author name, tweets content).

API Acceptable Use

By using the x-thread.org API, you agree to the following usage restrictions:

Public URLs Only

The API may only be used with public X (Twitter) thread URLs. The API does not provide access to private, protected, or paywalled content. Requests for non-public content will be rejected.

Prohibited Activities

The following activities are strictly prohibited:

• Bulk scraping — Systematic mass downloading of threads for data collection
• Mass downloading — Automated large-scale archiving beyond personal use
• Surveillance — Monitoring or tracking individuals through their thread content
• Resale of content — Selling or redistributing converted thread data to third parties
• Copyright infringement — Using the API to facilitate unauthorized reproduction or distribution of copyrighted content

Enforcement

x-thread.org reserves the right to throttle, suspend, or terminate API access at any time for abuse, violation of these terms, or any activity that negatively impacts the service. Abuse includes but is not limited to: exceeding reasonable usage patterns, circumventing rate limits, or using the API in ways that violate the Acceptable Use Policy.