> ## Documentation Index > Fetch the complete documentation index at: https://help.onlyx.ai/llms.txt > Use this file to discover all available pages before exploring further. > ## Agent Instructions > You are reading OnlyX Help: the OnlyX Help Center and the OnlyX developer documentation. OnlyX is an AI chatting and CRM platform for OnlyFans agencies. Its AI chatter is called Hugo in the app. > Pages at the site root (for example /inbox/..., /hugo/..., /billing/...) are Help Center articles for agency owners, admins, chatters and creators who use the app at app.onlyx.ai. Words in bold are the exact button, menu and label names the app shows; keep them exactly as written. When these pages do not answer a question, the person can email support at support@onlyx.ai. > Pages under /developers are the developer documentation. REST API base URL: https://api.onlyx.ai/v1 (authenticate with `Authorization: Bearer `; keys start with onx_sk_ and are created in app.onlyx.ai under Settings > API & MCP). MCP server: https://mcp.onlyx.ai/mcp (OAuth, or a Bearer API key). In the API the AI chatter is `ai` on the wire. Money is integer US cents in fields ending in Cents; timestamps are UTC ISO-8601. > Rules for assistants acting on a user's behalf: discover ids with list calls and never invent them; before any call that reaches a real fan or the live OnlyFans account (sending a message, releasing a chat to the AI, turning AI on for a chat, resolving a hand-off, turning review mode off, changing the welcome message, creating a tracking link) show the user the exact content and get explicit confirmation; send every POST with an Idempotency-Key and reuse it on retry; never resend a message whose delivery status is unconfirmed; never ask a creator for her OnlyFans password or codes - she signs in herself through a connect link and the OnlyX Login app. # Get a conversation > Returns one conversation with the full fan (subscription, spend, notes, lists and `salesOptOut`), the open hand-off if there is one, and `aiCanReply`: whether the AI would answer this chat right now. Read it before writing to a fan so you know who you are talking to and whether a paid message is allowed. A conversation the credential cannot see is `404 CONVERSATION_NOT_FOUND`. **Scope:** requires `inbox:read`. **Rate limit:** the general limit of 120 requests per 60 seconds per credential. ## OpenAPI ````yaml /developers/api-reference/openapi.json get /v1/conversations/{conversationId} openapi: 3.1.0 info: contact: email: developers@onlyx.ai name: OnlyX developers url: https://docs.onlyx.ai/ description: > The OnlyX API runs your OnlyX workspace from your own code and AI tools: creators and their connection, the fan inbox, fans, vault media, statistics, the AI chatter's setup and tracking links. **Authentication.** Send an API key as `Authorization: Bearer onx_sk_…` (create one in OnlyX under Settings → API & MCP), or an OAuth access token issued to a connected app. Keys belong to the workspace, carry scopes, and can be limited to some creators. **Conventions.** JSON with camelCase fields; timestamps are ISO-8601 UTC with a `Z`; money is integer US cents (fields end in `Cents`). Lists return `{"data": [...], "hasMore": bool, "nextCursor": string|null}` and page with `limit` and `cursor`. **Scopes.** Every operation names the scope it needs in `x-required-scope` and in its description; a credential without it gets `403 INSUFFICIENT_SCOPE`. **Errors and limits.** Errors are `{"error": {"code", "message", "requestId"}}`; every response carries `X-Request-Id`. The default limit is 120 requests per 60 seconds per credential, reported in `X-RateLimit-*` headers; over it you get `429 RATE_LIMITED` with `Retry-After`. Operations with limits of their own list them in `x-rate-limits`. **Idempotency and safety.** Every write accepts an `Idempotency-Key` header (required when sending a message, adding a creator and creating a tracking link): retry with the same key and you get the original answer instead of a second action. Operations marked `x-reaches-fans: true` can reach a real fan or change the live OnlyFans account. Guides, the MCP server and more: [docs.onlyx.ai](https://docs.onlyx.ai). summary: >- Run your OnlyX workspace (creators, inbox, fans, stats and the AI chatter) from code and AI tools. title: OnlyX API version: 1.0.0 servers: - description: Production url: https://api.onlyx.ai security: - bearerAuth: [] tags: - description: 'Who you are: the workspace and credential behind a key.' name: Workspace - description: >- The creators your workspace manages: list, read, add, rename, and the AI switch. name: Creators - description: >- Connecting a creator's OnlyFans account: connect links she opens on her own device, and the connection status to poll. name: Connect - description: >- The fan inbox: list and count conversations, read state, take over, release, and the per-chat AI switch. name: Conversations - description: Read message history and send text, free media and paid messages to fans. name: Messages - description: Conversations the AI chatter handed to your team, and resolving them. name: Hand-offs - description: >- Fans, their purchases, fan lists, and your team's notes, custom names and mute flag. name: Fans - description: >- Each creator's OnlyFans vault: media ids for messages and levels, and thumbnails. name: Media - description: >- Today, revenue, audience, the cached overview report, and each creator's transaction ledger. name: Stats - description: The brief the AI chatter follows to chat as each creator. name: AI persona - description: 'The AI content ladder: folders, ladders, priced levels and their media.' name: AI content - description: >- Follow-ups, review mode, the master AI switch, and OnlyFans' welcome message. name: AI settings - description: >- OnlyFans tracking and trial links, your cost fields, and creating new links. name: Tracking links externalDocs: description: OnlyX developer documentation url: https://docs.onlyx.ai paths: /v1/conversations/{conversationId}: get: tags: - Conversations summary: Get a conversation description: >- Returns one conversation with the full fan (subscription, spend, notes, lists and `salesOptOut`), the open hand-off if there is one, and `aiCanReply`: whether the AI would answer this chat right now. Read it before writing to a fan so you know who you are talking to and whether a paid message is allowed. A conversation the credential cannot see is `404 CONVERSATION_NOT_FOUND`. **Scope:** requires `inbox:read`. **Rate limit:** the general limit of 120 requests per 60 seconds per credential. operationId: getConversation parameters: - description: The conversation id (`cnv_…`), from `GET /v1/conversations`. in: path name: conversationId required: true schema: description: The conversation id (`cnv_…`), from `GET /v1/conversations`. maxLength: 40 title: Conversationid type: string responses: '200': content: application/json: example: aiCanReply: false creatorId: cre_8f2c1a9b0d7e4c3f2a1b fan: avatarUrl: null conversationId: cnv_3d9e7b1a5c2f4e8d6a0b createdAt: '2026-03-02T18:21:07.000Z' creatorId: cre_8f2c1a9b0d7e4c3f2a1b customName: Mike (birthday 14 May) displayName: Mike id: fan_6b2e8d4a1c9f3e7b5d0a lastActiveAt: '2026-09-25T21:40:12.000Z' lastPurchaseAt: '2026-09-24T22:03:55.000Z' lists: - id: lst_9c1d2e3f4a5b6c7d8e9f name: VIP muted: false notes: Likes lingerie sets. Tips on Fridays. paidMessagesCents: 36500 renewOn: true salesOptOut: false subscribed: true subscribedAt: '2026-03-02T18:21:07.000Z' subscriptionExpiresAt: '2026-10-02T18:21:07.000Z' subscriptionPriceCents: 999 tipsCents: 12000 totalSpentCents: 48500 username: null handoff: null id: cnv_3d9e7b1a5c2f4e8d6a0b lastMessage: at: '2026-09-25T21:40:12.000Z' direction: in text: are you online tonight? lastMessageAt: '2026-09-25T21:40:12.000Z' status: team takenOverUntil: '2026-09-26T09:40:12.000Z' totalSpentCents: 48500 unreadCount: 2 schema: $ref: '#/components/schemas/ConversationDetail' description: >- The conversation, with the full fan, the open hand-off and whether the AI would reply. 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' X-Request-Id: $ref: '#/components/headers/X-Request-Id' '400': content: application/json: examples: VALIDATION_ERROR: summary: VALIDATION_ERROR value: error: code: VALIDATION_ERROR message: 'conversationId: String should have at most 40 characters' requestId: req-3f9a1c2b7d4e5f60a1b2c3d4 schema: $ref: '#/components/schemas/Error' description: >- The request is not valid and was not carried out. Fix it before retrying. `VALIDATION_ERROR`: the request is not valid; `message` names the field and the problem. headers: X-Request-Id: $ref: '#/components/headers/X-Request-Id' '401': $ref: '#/components/responses/Unauthorized' '403': content: application/json: examples: INSUFFICIENT_SCOPE: summary: INSUFFICIENT_SCOPE value: error: code: INSUFFICIENT_SCOPE message: This key does not have the `inbox:read` scope. requestId: req-3f9a1c2b7d4e5f60a1b2c3d4 WORKSPACE_SUSPENDED: summary: WORKSPACE_SUSPENDED value: error: code: WORKSPACE_SUSPENDED message: This workspace is suspended. requestId: req-3f9a1c2b7d4e5f60a1b2c3d4 schema: $ref: '#/components/schemas/Error' description: >- The credential may not do this. `INSUFFICIENT_SCOPE`: the credential lacks the `inbox:read` scope (the `WWW-Authenticate` header names it; an OAuth token's message says "token" instead of "key"). `WORKSPACE_SUSPENDED`: the workspace is suspended. headers: WWW-Authenticate: $ref: '#/components/headers/WWW-Authenticate' X-Request-Id: $ref: '#/components/headers/X-Request-Id' '404': content: application/json: examples: CONVERSATION_NOT_FOUND: summary: CONVERSATION_NOT_FOUND value: error: code: CONVERSATION_NOT_FOUND message: Conversation not found. requestId: req-3f9a1c2b7d4e5f60a1b2c3d4 schema: $ref: '#/components/schemas/Error' description: >- Not found. An id that does not exist, belongs to another workspace, or is outside this credential's creators all get the same answer. `CONVERSATION_NOT_FOUND`: no conversation with this `conversationId` is visible to this credential. headers: X-Request-Id: $ref: '#/components/headers/X-Request-Id' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/InternalError' components: schemas: ConversationDetail: examples: - aiCanReply: false creatorId: cre_8f2c1a9b0d7e4c3f2a1b fan: avatarUrl: null conversationId: cnv_3d9e7b1a5c2f4e8d6a0b createdAt: '2026-03-02T18:21:07.000Z' creatorId: cre_8f2c1a9b0d7e4c3f2a1b customName: Mike (birthday 14 May) displayName: Mike id: fan_6b2e8d4a1c9f3e7b5d0a lastActiveAt: '2026-09-25T21:40:12.000Z' lastPurchaseAt: '2026-09-24T22:03:55.000Z' lists: - id: lst_9c1d2e3f4a5b6c7d8e9f name: VIP muted: false notes: Likes lingerie sets. Tips on Fridays. paidMessagesCents: 36500 renewOn: true salesOptOut: false subscribed: true subscribedAt: '2026-03-02T18:21:07.000Z' subscriptionExpiresAt: '2026-10-02T18:21:07.000Z' subscriptionPriceCents: 999 tipsCents: 12000 totalSpentCents: 48500 username: null handoff: null id: cnv_3d9e7b1a5c2f4e8d6a0b lastMessage: at: '2026-09-25T21:40:12.000Z' direction: in text: are you online tonight? lastMessageAt: '2026-09-25T21:40:12.000Z' status: team takenOverUntil: '2026-09-26T09:40:12.000Z' totalSpentCents: 48500 unreadCount: 2 properties: aiCanReply: description: >- Whether the AI would answer this chat right now: the creator's AI is on and set up, the chat is `ai`, and she is connected. type: boolean creatorId: description: The creator whose inbox this conversation is in. type: string fan: $ref: '#/components/schemas/Fan' description: The fan, in full. handoff: anyOf: - $ref: '#/components/schemas/Handoff' - type: 'null' description: The open hand-off on this conversation, or `null`. id: description: The conversation id (`cnv_…`). type: string lastMessage: anyOf: - $ref: '#/components/schemas/LastMessage' - type: 'null' description: The latest message, or `null` for an empty conversation. lastMessageAt: anyOf: - type: string - type: 'null' description: When the latest message was sent. status: description: Who answers this chat (see `Conversation.status`). enum: - ai - team - handoff - ai_off type: string takenOverUntil: anyOf: - type: string - type: 'null' description: >- While `status` is `team`: when the chat returns to the AI on its own. Otherwise `null`. totalSpentCents: description: Everything this fan has spent on the creator, in cents. type: integer unreadCount: description: Fan messages not yet marked read in OnlyX. type: integer required: - id - creatorId - fan - status - unreadCount - lastMessage - lastMessageAt - takenOverUntil - totalSpentCents - handoff - aiCanReply title: ConversationDetail type: object Error: properties: error: properties: code: description: Stable, machine-readable error code. type: string message: description: What went wrong, in a sentence for a person. type: string requestId: description: >- The id of this request (also in the `X-Request-Id` header). Quote it to support. type: string required: - code - message - requestId type: object required: - error type: object Fan: examples: - avatarUrl: null conversationId: cnv_3d9e7b1a5c2f4e8d6a0b createdAt: '2026-03-02T18:21:07.000Z' creatorId: cre_8f2c1a9b0d7e4c3f2a1b customName: Mike (birthday 14 May) displayName: Mike id: fan_6b2e8d4a1c9f3e7b5d0a lastActiveAt: '2026-09-25T21:40:12.000Z' lastPurchaseAt: '2026-09-24T22:03:55.000Z' lists: - id: lst_9c1d2e3f4a5b6c7d8e9f name: VIP muted: false notes: Likes lingerie sets. Tips on Fridays. paidMessagesCents: 36500 renewOn: true salesOptOut: false subscribed: true subscribedAt: '2026-03-02T18:21:07.000Z' subscriptionExpiresAt: '2026-10-02T18:21:07.000Z' subscriptionPriceCents: 999 tipsCents: 12000 totalSpentCents: 48500 username: null properties: avatarUrl: anyOf: - type: string - type: 'null' description: The fan's OnlyFans avatar, when known. conversationId: anyOf: - type: string - type: 'null' description: The conversation with this fan, or `null` if there is none yet. createdAt: anyOf: - type: string - type: 'null' description: When OnlyX first saw this fan. creatorId: description: The creator this fan subscribes (or subscribed) to. type: string customName: anyOf: - type: string - type: 'null' description: The name your team gave this fan in OnlyX. Only your team sees it. displayName: description: The fan's OnlyFans display name. type: string id: description: The fan id (`fan_…`). A fan belongs to one creator. type: string lastActiveAt: anyOf: - type: string - type: 'null' description: The fan's last activity OnlyX saw (a message or a purchase). lastPurchaseAt: anyOf: - type: string - type: 'null' description: The fan's last purchase. lists: description: The creator's fan lists this fan is on. items: $ref: '#/components/schemas/FanListRef' type: array muted: description: >- Your team's mute flag in OnlyX. It never mutes or blocks the fan on OnlyFans. type: boolean notes: anyOf: - type: string - type: 'null' description: Your team's notes on this fan. paidMessagesCents: description: Paid-message purchases, in cents. type: integer renewOn: anyOf: - type: boolean - type: 'null' description: Whether auto-renew is on. `null` when OnlyFans has not said. salesOptOut: description: >- `true` when the fan asked not to be sold to. Paid messages to this fan are refused with `409 SALES_OPTED_OUT`, and the AI does not sell to them. type: boolean subscribed: description: '`true` while the subscription is active.' type: boolean subscribedAt: anyOf: - type: string - type: 'null' description: When the current (or last) subscription started. subscriptionExpiresAt: anyOf: - type: string - type: 'null' description: When the current subscription ends or ended. subscriptionPriceCents: anyOf: - type: integer - type: 'null' description: What the fan pays per period, in cents. `0` on a free page. tipsCents: description: Tips, in cents. type: integer totalSpentCents: description: Everything the fan has spent on this creator, in cents. type: integer username: anyOf: - type: string - type: 'null' description: The fan's OnlyFans username, when known. required: - id - creatorId - conversationId - displayName - customName - avatarUrl - subscribed - subscribedAt - subscriptionExpiresAt - subscriptionPriceCents - renewOn - totalSpentCents - tipsCents - paidMessagesCents - lastActiveAt - lastPurchaseAt - muted - notes - salesOptOut - lists - createdAt title: Fan type: object Handoff: examples: - conversationId: cnv_3d9e7b1a5c2f4e8d6a0b createdAt: '2026-09-25T21:41:03.000Z' creatorId: cre_8f2c1a9b0d7e4c3f2a1b fanName: Mike id: esc_5e1f2a3b4c5d6e7f8a9b label: Asks for a refund note: He says the video he bought does not play and wants his money back. reason: payment_dispute status: open properties: conversationId: description: The conversation that was handed off. type: string createdAt: anyOf: - type: string - type: 'null' description: When the conversation was handed off. creatorId: description: The creator of that conversation. type: string fanName: description: The fan's name, for display. type: string id: description: The hand-off id (`esc_…`). type: string label: description: >- The specific situation, for people (for example "Asks for a refund"). type: string note: anyOf: - type: string - type: 'null' description: >- A short summary of the situation when it was raised, or your team's note once resolved with one. `null` when there is none. reason: description: >- Why the AI handed off, as a stable code: `welfare`, `prohibited_request`, `real_world`, `payment_dispute`, `custom_request`, `whale_risk`, `confusion` or `failed_delivery`. More values may be added. type: string status: description: '`open` until your team resolves it.' enum: - open - resolved type: string required: - id - conversationId - creatorId - fanName - reason - label - note - status - createdAt title: Handoff type: object LastMessage: properties: at: anyOf: - type: string - type: 'null' description: When it was sent. direction: description: '`in` from the fan, `out` to the fan.' enum: - in - out type: string text: description: >- The message text, shortened for a preview (may be empty for a media-only message). type: string required: - text - direction - at title: LastMessage type: object FanListRef: properties: id: description: The fan list id (`lst_…`). type: string name: description: The list name. type: string required: - id - name title: FanListRef type: object headers: X-RateLimit-Limit: description: >- Requests allowed in the current window of the tightest limit this request counted against. example: 120 schema: type: integer X-RateLimit-Remaining: description: Requests left in that window. example: 117 schema: type: integer X-RateLimit-Reset: description: When that window resets, as Unix epoch seconds. example: 1790431380 schema: type: integer X-Request-Id: description: >- The id of this request. Your own `X-Request-Id` (8 to 64 letters, digits or `-`) is echoed back; otherwise OnlyX creates one. Also in every error body as `requestId`: quote it to support. example: req-3f9a1c2b7d4e5f60a1b2c3d4 schema: type: string WWW-Authenticate: description: >- The authentication challenge (RFC 6750), for example `Bearer error="insufficient_scope", scope="messages:send"`. schema: type: string Retry-After: description: Seconds to wait before trying again. example: 12 schema: type: integer responses: Unauthorized: content: application/json: examples: INVALID_API_KEY: summary: INVALID_API_KEY value: error: code: INVALID_API_KEY message: The API key is invalid, expired or revoked. requestId: req-3f9a1c2b7d4e5f60a1b2c3d4 INVALID_TOKEN: summary: INVALID_TOKEN value: error: code: INVALID_TOKEN message: The access token is invalid, expired or revoked. requestId: req-3f9a1c2b7d4e5f60a1b2c3d4 UNAUTHORIZED: summary: UNAUTHORIZED value: error: code: UNAUTHORIZED message: >- Authentication required. Send your API key as `Authorization: Bearer onx_sk_…`. requestId: req-3f9a1c2b7d4e5f60a1b2c3d4 schema: $ref: '#/components/schemas/Error' description: >- No credential was sent (`UNAUTHORIZED`), or it is invalid, expired or revoked (`INVALID_API_KEY` for API keys, `INVALID_TOKEN` for OAuth access tokens: refresh the token or reconnect the app). Too many failed attempts from one address with credentials OnlyX never issued are answered `429 RATE_LIMITED` instead. headers: WWW-Authenticate: $ref: '#/components/headers/WWW-Authenticate' X-Request-Id: $ref: '#/components/headers/X-Request-Id' RateLimited: content: application/json: examples: RATE_LIMITED: summary: RATE_LIMITED value: error: code: RATE_LIMITED message: Too many requests. Try again in 12 seconds. requestId: req-3f9a1c2b7d4e5f60a1b2c3d4 schema: $ref: '#/components/schemas/Error' description: >- Over a rate limit (`RATE_LIMITED`). Wait `Retry-After` seconds, then retry — with the same `Idempotency-Key` for a write. headers: Retry-After: $ref: '#/components/headers/Retry-After' 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' X-Request-Id: $ref: '#/components/headers/X-Request-Id' InternalError: content: application/json: examples: INTERNAL_ERROR: summary: INTERNAL_ERROR value: error: code: INTERNAL_ERROR message: Something went wrong on our side. requestId: req-3f9a1c2b7d4e5f60a1b2c3d4 schema: $ref: '#/components/schemas/Error' description: >- Something went wrong on OnlyX's side (`INTERNAL_ERROR`). Retry with backoff (reuse the `Idempotency-Key` for a write); quote `requestId` to support if it persists. headers: X-Request-Id: $ref: '#/components/headers/X-Request-Id' securitySchemes: bearerAuth: bearerFormat: onx_sk_… API key or onx_at_… access token description: >- An API key (`onx_sk_…`) created in OnlyX under Settings → API & MCP, or an OAuth access token (`onx_at_…`) issued to a connected app. Send it as `Authorization: Bearer `. API keys may also be sent as `X-API-Key: `. scheme: bearer type: http ````