> ## Documentation Index > Fetch the complete documentation index at: https://docs.superx.so/llms.txt > Use this file to discover all available pages before exploring further. # Add a dataset's people to a contact list > Copy the people in a ready dataset into a contact list you created. Costs ONE WRITE and no enrichment: the profiles come from the dataset the collection already hydrated, which is why people SuperX has never stored still land in the list. People are deduped by X account id before the write, and rows without an X account id or a usable handle are counted in `skipped_without_id` rather than added as blank members, so `added + duplicates` can be lower than the dataset's `row_count`. Re-running is safe: people already in the list come back in `duplicates`. Own-content datasets (your posts, your replies) hold no people and return 400 `dataset_has_no_people`; so does a dataset whose rows all lack an X account id. A dataset that is not `ready` returns 409 `dataset_not_ready`, and a system list returns 400 `system_list_read_only`. Works for your main account or any account linked to it (`account_id`); accounts shared with you are read-only. Needs the write scope. ## OpenAPI ````yaml /api-reference/openapi.yaml post /v1/datasets/{id}/contacts openapi: 3.1.0 info: title: SuperX API version: 1.0.0 description: > The SuperX public API: your Twitter/X content, analytics, audience and scheduling data over REST. All endpoints require an API key (`Authorization: Bearer sxk_...`) except `GET /v1/docs`. Keys are created in the SuperX app under Account > API / MCP / CLI and are server-side secrets. Timestamps are UTC ISO-8601 in both directions; inputs must carry an explicit `Z` or numeric offset. Every authenticated response carries `X-RateLimit-Limit`, `X-RateLimit-Remaining` and `X-RateLimit-Reset` headers. contact: name: SuperX url: https://superx.so servers: - url: https://api.superx.so security: - apiKey: [] tags: - name: Identity - name: Content - name: Analytics - name: Inspiration - name: Audience - name: Contact Lists - name: Signals - name: Datasets description: | The audience collections Ask SuperX builds in the app: the repliers, quoters or reposters of a post, the members of an X list, your own posts or replies, or a research brief. Collect a new one with `POST /v1/datasets` (a big collection answers 202 and finishes in the background), read it, export it, or copy the people in it into a contact list you created. Datasets are kept for 30 days, and the ones Ask SuperX builds in the app show up here too. - name: Engage description: | The account's saved Engage feeds and the candidate posts in them, for an agent to score and a person to act on. Read-only by design. These endpoints return feed candidates for a person to review; replies are written and sent by a person in the SuperX app, which is why there is no reply endpoint here. Sending spammy, automated, or AI-generated replies that read as inauthentic may get your X account suspended under X's inauthentic-behavior rules and your SuperX account terminated. AI suggestions must be reviewed and meaningfully edited before they are sent, and you are solely responsible for what you post. Reply activity is logged and may be audited. - name: X Lookups description: | Read any public post, its top replies, any public profile, or an account's latest posts LIVE from X, rather than from SuperX's stored data. These are owner-scoped, so none of them take an `account_id`: nothing about a public lookup is per-X-account. They cost the tighter live-enrichment allowance and share a daily allowance of 300 live lookups with Ask SuperX inside the app, so use them for what you actually need rather than to sweep. Repeat lookups within 15 minutes may be served from a short-lived server-side cache. - name: Tools description: | The composer helpers from the SuperX app, over the API: rewrite a post, edit one selected piece of it, apply one preset rewrite, check a claim, or compare two versions. Every one of them returns TEXT and writes nothing. Nothing here is posted, scheduled or sent; save what you keep with `POST /v1/posts/draft` or `POST /v1/scheduled-posts`. They cost AI credits, measured from the models' real cost, and spend no live-data allowance. - name: Media - name: Workers description: | The posts the account's Workers have written, and the three things a person does with one: save it as a draft, schedule it, or dismiss it. A Worker is a scheduled AI writer set up in the SuperX app. Creating, editing and running one stays in the app, so there is no create or run endpoint here. What a run produces lands in the app's "To review" queue and is read with `GET /v1/workers/suggestions`. NOTHING HERE POSTS TO X. Drafting or scheduling a suggestion writes a post the user can see in the app and on `GET /v1/scheduled-posts`, exactly like the app's own buttons. AI output must be reviewed and meaningfully edited by a person before it goes out, so show the text to the user and confirm the time before you schedule anything. - name: Scheduling - name: Tags - name: Context - name: Queue - name: DMs description: | Queue direct messages into the account's own DM pipeline, and read or cancel what is waiting. NOTHING HERE SENDS A MESSAGE. `POST /v1/dm/campaigns` enqueues; the SuperX app's scheduler is what sends, within the account's daily and monthly DM limits, so the create response is counts, not deliveries. Unsent messages can be cancelled until the scheduler picks them up. You are responsible for the messages you queue. Unsolicited or automated bulk DMs may get an X account suspended under X's rules and a SuperX account terminated, so confirm the recipient list and the exact wording with the person on whose behalf you are queueing. - name: Articles - name: Meta paths: /v1/datasets/{id}/contacts: post: tags: - Datasets summary: Add a dataset's people to a contact list description: | Copy the people in a ready dataset into a contact list you created. Costs ONE WRITE and no enrichment: the profiles come from the dataset the collection already hydrated, which is why people SuperX has never stored still land in the list. People are deduped by X account id before the write, and rows without an X account id or a usable handle are counted in `skipped_without_id` rather than added as blank members, so `added + duplicates` can be lower than the dataset's `row_count`. Re-running is safe: people already in the list come back in `duplicates`. Own-content datasets (your posts, your replies) hold no people and return 400 `dataset_has_no_people`; so does a dataset whose rows all lack an X account id. A dataset that is not `ready` returns 409 `dataset_not_ready`, and a system list returns 400 `system_list_read_only`. Works for your main account or any account linked to it (`account_id`); accounts shared with you are read-only. Needs the write scope. operationId: addDatasetToContacts parameters: - $ref: '#/components/parameters/DatasetId' requestBody: required: true content: application/json: schema: type: object required: - list_id properties: list_id: type: string description: A contact list you created, from `GET /v1/contact-lists`. account_id: type: string example: list_id: cl_9f2b71 responses: '200': description: The add finished. Read the counters for what happened. headers: X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/DatasetContactsResult' example: data: added: 198 duplicates: 12 failed: 0 skipped_without_id: 4 total_in_list_after: 242 '400': $ref: '#/components/responses/DatasetHasNoPeople' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/WriteForbidden' '404': description: | Either end of the copy is missing: `dataset_not_found` (no dataset with that id belongs to this key, or it has expired) or `list_not_found` (no contact list with that id belongs to this account). Read `error.code` to tell them apart. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: code: list_not_found message: No contact list with that id belongs to this account. '409': $ref: '#/components/responses/DatasetNotReady' '429': $ref: '#/components/responses/RateLimited' '502': $ref: '#/components/responses/UpstreamError' '503': $ref: '#/components/responses/UpstreamUnavailable' components: parameters: DatasetId: name: id in: path required: true description: The dataset id from `GET /v1/datasets`. schema: type: string pattern: ^[A-Za-z0-9_-]{1,64}$ headers: X-RateLimit-Limit: description: The limit of the rate window closest to exhaustion. schema: type: integer X-RateLimit-Remaining: description: Requests remaining in that window. schema: type: integer X-RateLimit-Reset: description: Unix timestamp (seconds) when that window resets. schema: type: integer schemas: DatasetContactsResult: type: object properties: added: type: integer duplicates: type: integer description: People already in the list. Never an error. failed: type: integer skipped_without_id: type: integer description: | Rows with no X account id or no usable handle. Nothing was sent for them. Repeat rows for a person already collected are deduped silently and are not counted here. total_in_list_after: type: integer ErrorEnvelope: type: object required: - error properties: error: type: object required: - code - message properties: code: type: string description: Stable machine-readable error code. message: type: string retry_after: type: integer description: Seconds to wait before retrying (rate-limit errors only). LegacyErrorEnvelope: type: object required: - error description: | Legacy shape used ONLY by the shared subscription middleware: a plain string `error` field. Seen on `403` when the subscription has lapsed (string starts with "subscription_required:") and on `500` when subscription verification fails (string starts with "internal_error:"). properties: error: type: string example: >- subscription_required: The SuperX API requires an active subscription DatasetNotReadyError: allOf: - $ref: '#/components/schemas/ErrorEnvelope' - type: object properties: error: type: object properties: dataset_status: type: string enum: - collecting - failed description: | The dataset's current status. `collecting` finishes on its own, `failed` has to be rebuilt in the SuperX app. Named `dataset_status` so it never reads as the HTTP status. description: | The `409 dataset_not_ready` body: the standard envelope plus the dataset's current status, so a poller can tell "wait" from "wrong id". responses: DatasetHasNoPeople: description: >- The dataset holds no people to add (`dataset_has_no_people`), a system list was targeted (`system_list_read_only`), or the body was malformed (`invalid_parameter`). content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: code: dataset_has_no_people message: >- This dataset has no people to add: own-content datasets hold your posts, and rows without an X account id are skipped. Unauthorized: description: >- Missing/malformed Authorization header (`unauthorized`) or an unknown/revoked key (`invalid_api_key`). content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: code: invalid_api_key message: Unknown or revoked API key WriteForbidden: description: >- Read-only key (`insufficient_scope`), an account shared with you (`writes_main_account_only`; shared accounts are read-only through the API, your own linked accounts are not), or a lapsed subscription (legacy string envelope). content: application/json: schema: oneOf: - $ref: '#/components/schemas/ErrorEnvelope' - $ref: '#/components/schemas/LegacyErrorEnvelope' example: error: code: insufficient_scope message: >- This API key is read-only. Create a key with the write scope to use this endpoint. DatasetNotReady: description: | The dataset id is valid but the dataset is not `ready`. The error carries the current `dataset_status`: `collecting` finishes on its own (poll `GET /v1/datasets/{id}`), `failed` has to be rebuilt in the SuperX app. content: application/json: schema: $ref: '#/components/schemas/DatasetNotReadyError' example: error: code: dataset_not_ready message: >- This dataset is not ready yet. Check GET /v1/datasets/{id}: a collecting dataset finishes on its own, and a failed one has to be rebuilt in the SuperX app. dataset_status: collecting RateLimited: description: Rate limit exceeded (limits vary by plan). Honor Retry-After. headers: Retry-After: description: Seconds to wait before retrying. schema: type: integer X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: code: rate_limited message: >- Rate limit exceeded for the Pro plan (30 requests/min). Upgrade for higher limits. retry_after: 42 UpstreamError: description: A dependent SuperX service returned an unexpected response. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: code: upstream_error message: Failed to fetch scheduled posts. Try again shortly. UpstreamUnavailable: description: >- The scheduling service is temporarily unreachable. Safe to retry; reuse your Idempotency-Key on POST. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: code: upstream_unavailable message: >- The scheduling service is temporarily unavailable. Retry with the same Idempotency-Key. securitySchemes: apiKey: type: http scheme: bearer description: >- A SuperX API key ("sxk_..."), created in the SuperX app under Account > API / MCP / CLI. Keys are server-side secrets. ````