Quickstart

This quickstart takes about five minutes. You will create an API key, confirm it works, find a creator and a conversation, and send one message with delivery tracking. Before you start

You are an owner or admin of an OnlyX workspace. Other roles cannot create keys.
At least one creator in the workspace is connected. If none is, follow Add a creator first.
You have curl, Python 3 with requests (pip install requests), or Node.js 18 or newer. The JavaScript examples use the built-in fetch and top-level await: save them in a file ending in .mjs and run it with node file.mjs.

Create an API key

Open app.onlyx.ai and go to Settings → API & MCP.
Under API keys, click Create API key.
Name it after what will use it, for example Reporting script.
Choose an access preset. For this quickstart pick Full access, because step 5 sends a message. For a real integration pick the smallest set of scopes it needs (see Authentication).
Leave Creators on All creators and Expires on Never, or restrict them.
Click Create and copy the key. It starts with onx_sk_ and is shown only once. OnlyX stores only a hash of it.

Store the key in an environment variable, never in code:

export ONLYX_API_KEY="onx_sk_..."

Check the key: GET /v1/me

GET /v1/me tells you which workspace the key belongs to, which scopes it has, and your rate limit. Every key can call it.

curl https://api.onlyx.ai/v1/me \
  -H "Authorization: Bearer $ONLYX_API_KEY"

import os
import requests

API = "https://api.onlyx.ai/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['ONLYX_API_KEY']}"}

me = requests.get(f"{API}/me", headers=HEADERS, timeout=30)
me.raise_for_status()
print(me.json())

const API = "https://api.onlyx.ai/v1";
const headers = { Authorization: `Bearer ${process.env.ONLYX_API_KEY}` };

const res = await fetch(`${API}/me`, { headers });
if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);
console.log(await res.json());

Response 200

{
  "workspace": {
    "id": "agc_1a2b3c4d5e6f7a8b9c0d",
    "name": "Northstar Talent",
    "timezone": "Europe/London"
  },
  "credential": {
    "kind": "api_key",
    "id": "apk_0c9d8e7f6a5b4c3d2e1f",
    "name": "Reporting script",
    "scopes": ["workspace:read", "creators:read", "inbox:read", "messages:send"],
    "creatorIds": null
  },
  "rateLimit": { "limit": 120, "windowSeconds": 60 }
}

A 401 with INVALID_API_KEY means the key was mistyped, revoked or expired. See Errors.

List your creators

curl https://api.onlyx.ai/v1/creators \
  -H "Authorization: Bearer $ONLYX_API_KEY"

creators = requests.get(f"{API}/creators", headers=HEADERS, timeout=30).json()["data"]
for c in creators:
    print(c["id"], c["displayName"], c["connection"]["status"], c["aiEnabled"])

const { data: creators } = await (await fetch(`${API}/creators`, { headers })).json();
for (const c of creators) console.log(c.id, c.displayName, c.connection.status, c.aiEnabled);

Response 200

{
  "data": [
    {
      "id": "cre_5f2d9a1c7b3e4f60a2d1",
      "displayName": "Mia Rose",
      "handle": "miarose",
      "publicName": "Mia",
      "avatarUrl": "https://...",
      "platform": "onlyfans",
      "aiEnabled": true,
      "connection": { "status": "connected", "connected": true },
      "onlyfans": {
        "userId": "412345678",
        "verified": true,
        "subscribePriceCents": 999,
        "postsCount": 812,
        "photosCount": 1540,
        "videosCount": 230
      },
      "stats": {
        "fans": 2841,
        "conversations": 1912,
        "unreadConversations": 14,
        "openHandoffs": 2,
        "revenueCents": 1284350,
        "pendingCents": 96420,
        "revenueKnown": true
      },
      "contentConsentRequired": false,
      "createdAt": "2026-08-02T09:12:44.000Z"
    }
  ],
  "hasMore": false,
  "nextCursor": null
}

Copy a creator id (cre_...) whose connection.status is connected.

Read the inbox

List that creator’s unread conversations, then read the newest messages of one of them.

curl "https://api.onlyx.ai/v1/conversations?creatorId=cre_5f2d9a1c7b3e4f60a2d1&unread=true&limit=5" \
  -H "Authorization: Bearer $ONLYX_API_KEY"

curl "https://api.onlyx.ai/v1/conversations/cnv_9f2c41d7a8b35e06c1f4/messages?limit=20" \
  -H "Authorization: Bearer $ONLYX_API_KEY"

chats = requests.get(
    f"{API}/conversations",
    headers=HEADERS,
    params={"creatorId": "cre_5f2d9a1c7b3e4f60a2d1", "unread": "true", "limit": 5},
    timeout=30,
).json()["data"]
chat = chats[0]

msgs = requests.get(
    f"{API}/conversations/{chat['id']}/messages",
    headers=HEADERS,
    params={"limit": 20},
    timeout=30,
).json()["data"]
for m in msgs:  # oldest first
    print(m["createdAt"], m["sender"], m["text"])

const q = new URLSearchParams({ creatorId: "cre_5f2d9a1c7b3e4f60a2d1", unread: "true", limit: "5" });
const { data: chats } = await (await fetch(`${API}/conversations?${q}`, { headers })).json();
const chat = chats[0];

const { data: msgs } = await (
  await fetch(`${API}/conversations/${chat.id}/messages?limit=20`, { headers })
).json();
for (const m of msgs) console.log(m.createdAt, m.sender, m.text); // oldest first

Response 200 (messages)

{
  "data": [
    {
      "id": "msg_2c8e4a6f1b3d5079e2a4",
      "conversationId": "cnv_9f2c41d7a8b35e06c1f4",
      "direction": "in",
      "sender": "fan",
      "text": "are you online rn?",
      "media": [],
      "paid": null,
      "tipCents": null,
      "createdAt": "2026-09-26T13:58:12.000Z",
      "delivery": null
    }
  ],
  "hasMore": true
}

The conversation’s status tells you who is answering it: ai (the AI chatter), team (a human took over), handoff (the AI asked for a human) or ai_off. See Conversations.

Send a first message

This reaches a real fan on OnlyFans. Try it in a chat with a test subscriber account you own, or skip this step.

Sending needs the messages:send scope and an Idempotency-Key header. Generate a new key (a UUID works) for each new message, and reuse the same key if you retry the same message.

curl -X POST https://api.onlyx.ai/v1/conversations/cnv_9f2c41d7a8b35e06c1f4/messages \
  -H "Authorization: Bearer $ONLYX_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f" \
  -d '{"text": "hey you, I am here now"}'

import uuid

sent = requests.post(
    f"{API}/conversations/{chat['id']}/messages",
    headers={**HEADERS, "Idempotency-Key": str(uuid.uuid4())},
    json={"text": "hey you, I am here now"},
    timeout=30,
)
sent.raise_for_status()  # 202 Accepted
message = sent.json()
print(message["id"], message["delivery"]["status"])  # "queued"

const sendRes = await fetch(`${API}/conversations/${chat.id}/messages`, {
  method: "POST",
  headers: { ...headers, "Content-Type": "application/json", "Idempotency-Key": crypto.randomUUID() },
  body: JSON.stringify({ text: "hey you, I am here now" }),
});
if (sendRes.status !== 202) throw new Error(`${sendRes.status} ${await sendRes.text()}`);
const message = await sendRes.json();
console.log(message.id, message.delivery.status); // "queued"

Response 202

{
  "id": "msg_7a1d3f9c2e5b40d8a6c3",
  "conversationId": "cnv_9f2c41d7a8b35e06c1f4",
  "direction": "out",
  "sender": "team",
  "text": "hey you, I am here now",
  "media": [],
  "paid": null,
  "tipCents": null,
  "createdAt": "2026-09-26T14:02:31.000Z",
  "delivery": { "status": "queued", "reason": null }
}

202 means OnlyX accepted the message and queued it for delivery. Poll GET /v1/conversations/{conversationId}/messages/{messageId} every 5–10 seconds until delivery.status is sent, failed, unconfirmed or not_sent. Never resend on unconfirmed: the fan almost always got it.Sending also moves the chat to team for 12 hours, so the AI does not talk over you. Details in Read and send messages.

Prefer your AI assistant?

You do not need code to use OnlyX from Claude, ChatGPT, Cursor or VS Code. Connect the OnlyX MCP server in one click, sign in, and ask in plain language: “Which fans are waiting for a reply on Mia’s account?”

Add OnlyX to Claude

Opens Claude with the OnlyX connector filled in. Click Add, then sign in.

All AI clients

ChatGPT, Cursor, VS Code, Claude Code and others.

Next steps

Authentication: scopes, creator restrictions, expiry and OAuth.
Add a creator: connect a new OnlyFans account, including face verification.
Read and send messages: paid messages, vault media, delivery states, take over and release.
Errors and Rate limits: what to retry and what to fix.

Get started

Guides

Reference topics

Prefer your AI assistant?

Add OnlyX to Claude

All AI clients

Next steps

​Prefer your AI assistant?

Add OnlyX to Claude

All AI clients

​Next steps

Prefer your AI assistant?

Next steps