Skip to main content
POST
Resolve a hand-off

Authorizations

Authorization
string
header
required

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

Idempotency-Key
string

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.

Required string length: 8 - 64
Pattern: ^[A-Za-z0-9_-]{8,64}$

Path Parameters

conversationId
string
required

The conversation id (cnv_…).

Maximum string length: 40

Body

application/json
note
string | null

Optional: what your team did, up to 300 characters.

Maximum string length: 300

Response

The resolved hand-off.

conversationId
string
required

The conversation that was handed off.

createdAt
string | null
required

When the conversation was handed off.

creatorId
string
required

The creator of that conversation.

fanName
string
required

The fan's name, for display.

id
string
required

The hand-off id (esc_…).

label
string
required

The specific situation, for people (for example "Asks for a refund").

note
string | null
required

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
string
required

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.

status
enum<string>
required

open until your team resolves it.

Available options:
open,
resolved