> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xquik.com/llms.txt
> Use this file to discover all available pages before exploring further.

# REST API Overview

> Xquik REST API v1: authentication, rate limits, pagination, error handling, and 120 documented operations for X data

<blockquote className="agent-llms-directive">
  For the complete documentation index, see <a href="/llms.txt">llms.txt</a>.
</blockquote>

The Xquik REST API v1 provides programmatic access to X data and automation. Endpoints are organized into these categories:

<CardGroup cols={2}>
  <Card title="Monitors & Events" icon="bell" href="/api-reference/monitors/create">
    Create account and keyword monitors, retrieve events, manage webhooks
  </Card>

  <Card title="Draws & Extractions" icon="shuffle" href="/api-reference/draws/create">
    Run giveaway draws, extract tweet data
  </Card>

  <Card title="X Data" icon="database" href="/api-reference/x/get-user">
    User lookups, tweet search, trends, media downloads
  </Card>

  <Card title="X Write Actions" icon="pen-line" href="/api-reference/x-write/create-tweet">
    Post tweets, like, retweet, follow, DM, profile updates
  </Card>

  <Card title="Account & Billing" icon="user" href="/api-reference/account/get">
    Account info, API keys, drafts, styles, subscriptions
  </Card>
</CardGroup>

## Base URL

```text theme={null}
https://xquik.com/api/v1
```

All endpoints are served over **HTTPS only**. Plain HTTP requests receive a `301` redirect to HTTPS. Always use the full base URL.

## OpenAPI spec

The full API specification is available as an OpenAPI 3.1 document:

```text theme={null}
https://xquik.com/openapi.json
```

YAML is also available at:

```text theme={null}
https://docs.xquik.com/openapi.yaml
```

Use these with any OpenAPI-compatible tool (Postman, Insomnia, Swagger UI) or to generate client libraries. The spec follows [RFC 9727](https://www.rfc-editor.org/rfc/rfc9727) service discovery conventions.

API service discovery is published at:

```text theme={null}
https://xquik.com/.well-known/api-catalog
```

## Authentication

Pass your API key via the `x-api-key` header:

```text theme={null}
x-api-key: xq_YOUR_KEY_HERE
```

Generate keys from your [dashboard](https://xquik.com). See [Authentication](/api-reference/authentication) for full details on key format, dual auth endpoints, and security best practices.

### Machine Payments Protocol

Eligible X API endpoints also accept anonymous [MPP](/mpp/overview) payments. The server returns a 402 challenge; your client pays via Tempo (USDC) and retries with a payment credential. No API key needed. See the [MPP overview](/mpp/overview) for eligible endpoints and pricing.

## First request

Copy-paste this to verify your API key works:

```bash theme={null}
curl -s https://xquik.com/api/v1/account \
  -H "x-api-key: xq_YOUR_KEY_HERE" | jq
```

**Response:**

```json theme={null}
{
  "plan": "active",
  "monitorsAllowed": 9007199254740991,
  "monitorsUsed": 0,
  "monitorBilling": {
    "activeDailyEstimate": "0",
    "activeHourlyBurn": "0",
    "creditsPerActiveMonitorDay": "500",
    "creditsPerActiveMonitorHour": "21",
    "eventsIncluded": true,
    "instantCheckIntervalSeconds": 1,
    "unlimitedSlots": true
  },
  "creditInfo": {
    "balance": "140000",
    "lifetimePurchased": "140000",
    "lifetimeUsed": "0",
    "autoTopupEnabled": false,
    "autoTopupAmountDollars": 10,
    "autoTopupThreshold": "50000"
  }
}
```

Replace `xq_YOUR_KEY_HERE` with your actual API key from the [dashboard](https://xquik.com). If you get `401`, double-check that the header name is `x-api-key` (lowercase) and the key starts with `xq_`.

## Integration readiness checklist

Run this checklist before connecting a production client, workflow builder, or agent to the API.

<CardGroup cols={2}>
  <Card title="Authentication" icon="key">
    Send `x-api-key` on subscription endpoints or use the documented MPP flow on eligible X data endpoints. Handle `401 unauthenticated`, `402 no_subscription`, or an MPP 402 payment challenge.
  </Card>

  <Card title="Response contract" icon="file-json">
    Default REST examples use the v1 shape. Send `xquik-api-contract: 2026-04-29` only when your client expects snake\_case, structured errors, `has_more`, and `next_cursor`. This prevents field-name drift between generated clients, MCP calls, and hand-written REST code.
  </Card>

  <Card title="Pagination" icon="list">
    Use `after` with `nextCursor` on events, draws, extractions, and drafts. Use `cursor` with `next_cursor` on X data endpoints. Handle missing pages, duplicate records, and opaque cursors.
  </Card>

  <Card title="Billing" icon="credit-card">
    Handle `402 no_credits` and `402 insufficient_credits`. Estimate extraction cost before creating extraction jobs so partial paid result pages, failed draws, or blocked jobs are expected states.
  </Card>

  <Card title="Rate limits" icon="timer">
    Respect `Retry-After`. Read calls are 60 per 1s, write calls are 30 per 60s, and delete calls are 15 per 60s. Back off on repeated `429 rate_limit_exceeded` responses.
  </Card>

  <Card title="Ambiguous writes" icon="activity">
    Treat `202 x_write_unconfirmed` as pending confirmation. Store `writeActionId`, call `GET /x/write-actions/{id}`, and do not retry-send while status is `pending_confirmation`.
  </Card>
</CardGroup>

## Rate limits

<CardGroup cols={3}>
  <Card title="Read requests" icon="database">
    `GET`, `HEAD`, and `OPTIONS` requests share a 60 per 1s user bucket.
    Standard read throttles return `Retry-After: 1`.
  </Card>

  <Card title="Write requests" icon="pen-line">
    `POST`, `PUT`, and `PATCH` requests share a 30 per 60s user bucket.
    Throttled writes return `Retry-After: 60`.
  </Card>

  <Card title="Delete requests" icon="trash">
    `DELETE` requests use a separate 15 per 60s user bucket. Throttled deletes
    return `Retry-After: 60`.
  </Card>
</CardGroup>

Exceeding limits returns `429 rate_limit_exceeded` with `Retry-After` and a JSON `retryAfter` field. See the [Rate Limits guide](/guides/rate-limits) for backoff implementations in multiple languages.

## Conventions

<AccordionGroup>
  <Accordion title="IDs are strings">
    All IDs are returned as strings representing bigint values. Always treat IDs as opaque strings - never parse them as numbers:

    ```json theme={null}
    { "id": "123456789" }
    ```
  </Accordion>

  <Accordion title="Timestamps are ISO 8601 UTC">
    All timestamps use ISO 8601 format in UTC. Store and compare timestamps as strings or parse them into proper date objects:

    ```json theme={null}
    { "createdAt": "2026-02-24T10:30:00.000Z" }
    ```
  </Accordion>

  <Accordion title="Errors follow a consistent format">
    All errors return a JSON body with an `error` field containing a machine-readable error code:

    ```json theme={null}
    { "error": "error_code" }
    ```

    **Common errors:**

    <CardGroup cols={2}>
      <Card title="400 validation" icon="circle-alert">
        `invalid_input` means the request body, query, or path failed
        validation. Fix the schema, field types, or required parameters before
        retrying.
      </Card>

      <Card title="401 authentication" icon="key-round">
        `unauthenticated` means the API key or bearer token is missing or
        invalid. Send `x-api-key` or a valid `Authorization` bearer token.
      </Card>

      <Card title="402 billing state" icon="credit-card">
        `no_subscription`, `no_credits`, and `insufficient_credits` mean the
        request needs an active plan, credit balance, or top-up before retrying.
      </Card>

      <Card title="404 missing resource" icon="search">
        `not_found` means the requested resource does not exist or is not
        available to the authenticated account.
      </Card>

      <Card title="429 rate limit" icon="timer">
        `rate_limit_exceeded` includes `Retry-After` and JSON `retryAfter`.
        Wait for the window and retry with backoff.
      </Card>

      <Card title="502 read service retry" icon="rotate-ccw">
        `x_api_unavailable` means the read service is temporarily unavailable.
        Retry with exponential backoff.
      </Card>
    </CardGroup>

    See [Error Handling](/guides/error-handling) for the full error code list and handling strategies.
  </Accordion>

  <Accordion title="Cursor-based pagination">
    <Tabs>
      <Tab title="Platform endpoints">
        Events, draws, extractions, and drafts use cursor-based pagination. When more results exist, the response includes `hasMore: true` and a `nextCursor` value:

        ```json theme={null}
        {
          "events": [],
          "hasMore": true,
          "nextCursor": "MjAyNi0wMi0yNFQxMDozMDowMC4wMDBa..."
        }
        ```

        Pass `nextCursor` as the `after` query parameter to fetch the next page:

        ```bash theme={null}
        curl "https://xquik.com/api/v1/events?after=MjAyNi0wMi0yNFQxMDozMDowMC4wMDBa..." \
         -H "x-api-key: xq_YOUR_KEY_HERE"
        ```
      </Tab>

      <Tab title="X endpoints">
        X data endpoints (`/x/*`) use a different pagination shape. When more results exist, the response includes `has_next_page: true` and a `next_cursor` value:

        ```json theme={null}
        {
          "tweets": [],
          "has_next_page": true,
          "next_cursor": "DAABCgABGRnYttk__..."
        }
        ```

        Pass `next_cursor` as the `cursor` query parameter to fetch the next page:

        ```bash theme={null}
        curl "https://xquik.com/api/v1/x/tweets/search?q=xquik&cursor=DAABCgABGRnYttk__..." \
         -H "x-api-key: xq_YOUR_KEY_HERE"
        ```
      </Tab>
    </Tabs>

    Cursors are opaque strings - do not decode or construct them manually. Monitors, webhooks, and API keys return up to 200 items without pagination.
  </Accordion>

  <Accordion title="Opt-in response contract">
    v1 keeps the default response contract unchanged for existing clients. Send `xquik-api-contract: 2026-04-29` to opt in to the normalized v1 response contract.

    ```bash theme={null}
    curl "https://xquik.com/api/v1/events" \
     -H "x-api-key: xq_YOUR_KEY_HERE" \
     -H "xquik-api-contract: 2026-04-29"
    ```

    Opt-in responses use snake\_case field names, Unix timestamps in seconds, structured error objects, `has_more` and `next_cursor` pagination fields, an `object` field on recognized resources, and prefixed IDs where available.

    ```json theme={null}
    {
      "events": [],
      "has_more": true,
      "next_cursor": "MjAyNi0wMi0yNFQxMDozMDowMC4wMDBa..."
    }
    ```

    Legacy dependency failures that return `502` by default return `424 Failed Dependency` in the opt-in contract:

    ```json theme={null}
    {
      "error": {
        "type": "dependency_error",
        "code": "x_api_unavailable",
        "message": "Read service temporarily unavailable. Retry shortly."
      }
    }
    ```
  </Accordion>
</AccordionGroup>

## Event types

### Monitor events

Used across monitors, webhooks, and events:

Valid account monitor and webhook types: `tweet.new`, `tweet.quote`,
`tweet.reply`, `tweet.retweet`, `tweet.media`, `tweet.link`, `tweet.poll`,
`tweet.mention`, `tweet.hashtag`, `tweet.longform`,
`profile.avatar.changed`, `profile.banner.changed`, `profile.name.changed`,
`profile.username.changed`, `profile.bio.changed`,
`profile.location.changed`, `profile.url.changed`, `profile.verified.changed`,
`profile.protected.changed`, `profile.pinned_tweet.changed`,
`profile.unavailable.changed`.

<CardGroup cols={2}>
  <Card title="tweet.new" icon="bell">
    Original tweet posted by the monitored account or matching query. Used when
    no reply, quote, or retweet signal is present.
  </Card>

  <Card title="tweet.quote" icon="quote">
    Quote tweet posted by the monitored account or matching query. Classified
    when quote metadata is present.
  </Card>

  <Card title="tweet.reply" icon="message-circle">
    Reply posted by the monitored account or matching query. Classified from
    reply flags or reply target IDs.
  </Card>

  <Card title="tweet.retweet" icon="repeat-2">
    Retweet posted by the monitored account or matching query. Classified from
    retweet flags or `RT @` text.
  </Card>
</CardGroup>

## Next steps

<CardGroup cols={3}>
  <Card title="Error Handling" icon="triangle-alert" href="/guides/error-handling">
    Handle errors gracefully with retries and fallbacks.
  </Card>

  <Card title="Rate Limits" icon="gauge" href="/guides/rate-limits">
    Understand limits and implement backoff strategies.
  </Card>

  <Card title="Workflows" icon="workflow" href="/guides/workflows">
    End-to-end examples: monitors, events, and webhooks.
  </Card>

  <Card title="X Data Endpoints" icon="database" href="/api-reference/x/get-user">
    User lookups, tweet search, trends, and media downloads.
  </Card>

  <Card title="X Write Actions" icon="pen" href="/api-reference/x-write/create-tweet">
    Post tweets, like, retweet, follow, DM, and more.
  </Card>

  <Card title="Monitors" icon="radar" href="/api-reference/monitors/create">
    Track X accounts and receive real-time events.
  </Card>
</CardGroup>