---
title: "POST /api/v1/x/accounts"
method: POST
path: "/api/v1/x/accounts"
tags: ["X Accounts"]
---

# POST /api/v1/x/accounts

`POST /api/v1/x/accounts`

## Request

- Base URL: `https://xquik.com`
- URL: `https://xquik.com/api/v1/x/accounts`
- Auth: API key in cookie `__Host-xquik_session`

Starts an X account connection flow. Needs a dashboard session, so X credentials never pass through an API key.

## Request body

- object
  - `username` string, required: X username of the account to connect, with or without @
  - `email` string, required: Account email
  - `password` string, required: Account password
  - `totp_secret` string, required: Authenticator App TOTP secret required for durable login

## Response `201`

X account connected after verification

- SanitizedXAccount: Sanitized X account summary returned by connect and reauth.
  - `id` string, required
  - `xUserId` string, required
  - `xUsername` string, required
  - `status` 'active', required
  - `health` 'healthy' | 'locked' | 'needsReauth' | 'recovering' | 'suspended' | 'temporaryIssue', required
  - `createdAt` string, date-time, required

## Other responses

- `202`: Connection continues or needs an email code
- `400`: Invalid input. A value past its maxLength gets this answer, & the message names the field & its limit.
- `401`: Unauthenticated
- `403`: An API key or OAuth token called a route that needs a dashboard session. Sign in at dashboard.xquik.com/account instead.
- `409`: This X account is already connected to this Xquik account. The error code is `account_already_connected`.
- `422`: Login requires new credentials, account verification, or a wait. Cooldowns include `retryAfterMs` and `Retry-After`. Codes are `login_failed` or `passkey_required`. `reason` is `account_not_found` (unknown username), `repeated_login_error`, or `login_unconfirmed` (X showed no known page after the password). Retrying a `login_unconfirmed` login before `Retry-After` can make X lock the account.
- `429`: Too many requests. `rate_limit_exceeded` includes `retryAfter` and `Retry-After`. `login_cooldown` also includes `reason` and `retryAfterMs`.
- `500`: Unexpected error.
- `502`: X couldn't resolve this username. Check the handle & that the account exists. Default v1 returns 502. The best-practice contract returns 424. The error code is `x_user_lookup_failed`.
- `503`: The X connection service is temporarily unavailable. Retry shortly. The error code is `service_unavailable`.
- `default`: Unexpected error.

## Changes

- **2026-10-20** `45942c75fdc2`: 20 warning
  - added the new `topup_in_progress` enum value to the `error/oneOf[subschema #1: LegacyErrorCode]/` response property for the response status `400`
  - added the new `topup_in_progress` enum value to the `error/oneOf[subschema #1: LegacyErrorCode]/` response property for the response status `401`
  - added the new `topup_in_progress` enum value to the `error/oneOf[subschema #1: LegacyErrorCode]/` response property for the response status `403`
  - added the new `topup_in_progress` enum value to the `error/oneOf[subschema #1: LegacyErrorCode]/` response property for the response status `409`
  - …16 more

[Operation history](https://skmtc.dev/xquik-dev/apis/xquik-api/changes/api/v1/x/accounts/post.md)

---

[API](https://skmtc.dev/xquik-dev/apis/xquik-api.md) · [All operations](https://skmtc.dev/xquik-dev/apis/xquik-api/llms.txt) · [OpenAPI document](https://skmtc.dev/xquik-dev/apis/xquik-api/revisions/45942c75fdc2?raw)