curl --request POST \
--url https://api.onlyx.ai/v1/conversations/{conversationId}/takeover \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"holdMinutes": 120
}
'import requests
url = "https://api.onlyx.ai/v1/conversations/{conversationId}/takeover"
payload = { "holdMinutes": 120 }
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({holdMinutes: 120})
};
fetch('https://api.onlyx.ai/v1/conversations/{conversationId}/takeover', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));{
"creatorId": "cre_8f2c1a9b0d7e4c3f2a1b",
"fan": {
"avatarUrl": null,
"displayName": "Mike",
"id": "fan_6b2e8d4a1c9f3e7b5d0a",
"username": 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
}Take over a conversation
Gives the conversation to your team: its status becomes team, and the AI stops replying and withdraws any reply it had waiting in it until takenOverUntil, after which the chat returns to the AI on its own. Use it before your team works a chat, or to keep the AI out of a delicate conversation. holdMinutes sets the hold, from 15 minutes to 24 hours (default 12 hours); taking over a chat your team already holds restarts the hold. Nothing is sent to the fan.
Scope: requires inbox:write.
Rate limit: the general limit of 120 requests per 60 seconds per credential.
Idempotency: send an Idempotency-Key header to make retries safe: a replay within 24 hours returns the original response with Idempotent-Replayed: true.
curl --request POST \
--url https://api.onlyx.ai/v1/conversations/{conversationId}/takeover \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"holdMinutes": 120
}
'import requests
url = "https://api.onlyx.ai/v1/conversations/{conversationId}/takeover"
payload = { "holdMinutes": 120 }
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({holdMinutes: 120})
};
fetch('https://api.onlyx.ai/v1/conversations/{conversationId}/takeover', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));{
"creatorId": "cre_8f2c1a9b0d7e4c3f2a1b",
"fan": {
"avatarUrl": null,
"displayName": "Mike",
"id": "fan_6b2e8d4a1c9f3e7b5d0a",
"username": 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
}Authorizations
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 <credential>. API keys may also be sent as X-API-Key: <key>.
Headers
Optional. A unique value (8 to 64 letters, digits, - or _; a UUID is ideal) that makes a retry safe: the same key with the same request within 24 hours returns the stored response, with Idempotent-Replayed: true, instead of doing the work twice. The same key with a different request is 409 IDEMPOTENCY_KEY_REUSED; while the first request still runs it is 409 IDEMPOTENCY_IN_PROGRESS. A malformed key is 400 VALIDATION_ERROR.
8 - 64^[A-Za-z0-9_-]{8,64}$Path Parameters
The conversation id (cnv_…).
40Body
How long your team keeps the chat before it returns to the AI on its own: 15 to 1440 minutes. Default 720 (12 hours).
15 <= x <= 1440Response
The updated conversation.
The creator whose inbox this conversation is in.
Who the creator is talking to.
Show child attributes
Show child attributes
The conversation id (cnv_…).
The latest message, or null for an empty conversation.
Show child attributes
Show child attributes
When the latest message was sent.
Who answers this chat. ai: the AI chatter. team: your team (the AI is paused on it until takenOverUntil). handoff: the AI handed it to your team and is silent until the hand-off is resolved. ai_off: the AI is switched off for this chat.
ai, team, handoff, ai_off While status is team: when the chat returns to the AI on its own. Otherwise null.
Everything this fan has spent on the creator, in cents.
Fan messages not yet marked read in OnlyX.