twitr-sh Snapshots API

openapi: 3.2.0
info:
  title: twitr.sh Snapshots API
  version: 1.0.0
  contact:
    email: support@twitr.sh
  description: 'Pay-per-call X/Twitter data API for AI agents: single-object reads, tweet/user search, timelines, lists, communities, bulk extractions (23 tools, async with downloadable datasets), real-time account/keyword monitors (prepaid hours; events via free polling or signed webhooks), giveaway draws, trend radar, and an AI tweet composer. No signup — the wallet is the account; an optional API key (Authorization: Bearer) spends a prepaid card balance instead. Payment via x402 v2 (USDC on Base/Solana) and MPP (USDC on Tempo). Per-result reads use x402 upto on Base only: the 402 quotes a maximum, empty results cost $0, and non-empty calls have a $0.0024 minimum. Volume tools bill per returned item against a mandatory resultsLimit; extractions and monitors settle before dispatch.'
  x-guidance: 'All tools are POST /api/tools/{tool} and return 402 with payment options on first call (Base upto only for per-result reads; fixed operations can offer exact x402 and MPP); pay and retry to receive data. Volume tools (x_search, x_timeline, x_lists, x_communities non-info kinds, followers-you-know) REQUIRE resultsLimit (integer 1–10000) — you are billed per returned item and the cap is enforced upstream. x_extract is async: it returns {snapshot_id, status_url}; poll GET /api/snapshots/{id} (free, SIWX) until status=ready for a download_url. x_monitor is PREPAID by the hour: it stops at expires_at unless extended — extend early, never expect refunds on deletion; events flow to GET /api/monitors/{id}/events (free, SIWX) or your registered webhook (/api/webhooks, signed with X-Twitr-Signature). draws, x_extract and x_monitor require an Idempotency-Key header. radar + compose are flat floor-priced. GET /api/snapshots and GET /api/monitors (SIWX) list the wallet''s history for free. Errors are RFC 9457 Problem bodies (components.schemas.Problem) with machine-actionable `retryable` and `hint` fields — retryable:true means retry the SAME request unchanged after a backoff; x402 reads settle after success; prepaid operations can fail after payment. Alternative to per-call payment: send `Authorization: Bearer tw_live_…` (an API key created at /dashboard) and each call is charged to that account''s prepaid USD balance at the same prices — per-result reads charge only returned records; the free SIWX endpoints accept the same key.'
servers:
- url: https://twitr.sh
tags:
- name: Snapshots
paths:
  /api/snapshots:
    get:
      operationId: list_my_snapshots
      summary: List snapshots owned by the caller's wallet
      description: Returns every extraction snapshot the caller's wallet has paid for. Wallet identity is proven via SIWX (Sign-In-With-X, CAIP-122). Pending snapshots are reconciled against the live job state on read.
      tags:
      - Snapshots
      x-guidance: Call this when the user asks about their extraction history or progress on prior async runs. Free, no payment — just a SIWX signature.
      security:
      - siwx: []
      responses:
        '200':
          description: List of snapshots for the signing wallet.
          content:
            application/json:
              schema:
                type: object
                properties:
                  wallet:
                    type: string
                    description: Recovered signer address (lowercased).
                  count:
                    type: integer
                  snapshots:
                    type: array
                    items:
                      type: object
                      properties:
                        snapshot_id:
                          type: string
                        actor_id:
                          type: string
                          enum:
                          - x_read
                          - x_search
                          - x_timeline
                          - x_lists
                          - x_communities
                          - x_extract
                          - x_monitor
                          - draws
                          - radar
                          - compose
                        mode:
                          type: string
                        status:
                          type: string
                          enum:
                          - pending
                          - ready
                          - failed
                        created_at:
                          type: integer
                          description: Unix ms.
                        record_count:
                          type: integer
                          description: Only set when status=ready.
                        paid_amount:
                          type: string
                          description: USD decimal string.
                        paid_protocol:
                          type: string
                          enum:
                          - x402
                          - mpp
                          - balance
                      required:
                      - snapshot_id
                      - actor_id
                      - status
                      - created_at
                required:
                - wallet
                - count
                - snapshots
        '402':
          description: Identity Required. Response advertises the `sign-in-with-x` extension; sign a CAIP-122 message with the user's wallet and retry with `SIGN-IN-WITH-X` header.
  /api/snapshots/{id}:
    get:
      operationId: get_snapshot
      summary: Fetch one snapshot's status + records
      description: Returns a single snapshot. If pending, it is reconciled against the live extraction job first; if ready, includes all records (cached 24h for free re-fetches). Wallet-gated via SIWX — only the wallet that paid for this snapshot can read it.
      tags:
      - Snapshots
      x-guidance: Call when the user asks 'is my extraction done?' and you have the snapshot_id. Free (SIWX-signed).
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          pattern: ^sd_[a-zA-Z0-9]+$
      security:
      - siwx: []
      responses:
        '200':
          description: Snapshot is ready (includes `download_url` for the JSON blob) OR failed (includes `error`). Rate-limited to 10 download_url issuances per wallet per hour.
          content:
            application/json:
              schema:
                type: object
                properties:
                  snapshot_id:
                    type: string
                  status:
                    type: string
                    enum:
                    - ready
                    - failed
                  actor_id:
                    type: string
                  mode:
                    type: string
                  record_count:
                    type: integer
                  bytes:
                    type: integer
                    description: Size of the blob in bytes.
                  download_url:
                    type: string
                    description: Vercel Blob URL. Fetch with plain GET; no additional auth required. URL is stable until blob expiry (24h by default).
                  expires_at_estimate:
                    type: integer
                    description: Unix ms when the blob will expire (estimate — blob retention is 24h after creation).
                  error:
                    type: string
                    description: Only when status=failed.
                required:
                - snapshot_id
                - status
        '202':
          description: Snapshot still pending — the extraction job is still running.
          content:
            application/json:
              schema:
                type: object
                properties:
                  snapshot_id:
                    type: string
                  status:
                    type: string
                    enum:
                    - pending
                  actor_id:
                    type: string
                  mode:
                    type: string
                  elapsed_seconds:
                    type: integer
                  message:
                    type: string
                required:
                - snapshot_id
                - status
        '402':
          description: Identity Required — sign SIWX and retry.
        '403':
          description: Signing wallet doesn't own this snapshot.
        '404':
          description: Snapshot unknown or expired.
        '429':
          description: 60 downloads/hour per wallet exceeded. Includes Retry-After header.
components:
  securitySchemes:
    siwx:
      type: apiKey
      in: header
      name: SIGN-IN-WITH-X
      description: Sign-In-With-X (CAIP-122). Base64-encoded CAIP-122 payload signed by the caller's wallet. Server recovers the signer address cryptographically; any client-supplied wallet parameter is ignored.
    bearerKey:
      type: http
      scheme: bearer
      description: Optional API key (tw_live_…) created in the dashboard. Paid tools charge the key owner's prepaid USD balance instead of an on-chain payment; free endpoints accept it in place of SIWX.
    publicRead:
      type: apiKey
      in: query
      name: _public
      description: No-op placeholder. This endpoint requires no authentication; the scheme exists so validators that want a named security reference on public operations have one to point at.
x-ux-hints: Confirm with the user before any call that quotes above $0.10 or requests resultsLimit >= 500. Never spin a background poll loop — when the user asks progress on an extraction, call /api/snapshots/{id} (free, SIWX). Send Idempotency-Key with paid calls so a dropped response is replayed from cache (10 min) instead of re-running. Wallet history is free — use it when the user asks 'what have I extracted?'.
x-service-info:
  categories:
  - data
  - social
  - search
  - developer-tools
  docs:
    homepage: https://twitr.sh
    apiReference: https://twitr.sh/openapi.json
    llms: https://twitr.sh/llms.txt
x-discovery:
  ownershipProofs: []