API reference

Reference summary of the OctaDezx API v1 OpenAPI 3.1 spec: the public message endpoints, the headless Agent API, device registration and the messenger client endpoints, with auth and status.

Status: available (v0.1). OctaDezx API v1 is one HTTPS service described by an OpenAPI 3.1 spec, with three groups of endpoints: the public API (/message and /messages, generally available), the headless Agent API (/agent/start, /agent/reply, /agent/conversations/:id and /agent/devices, available at version 0.1), and the messenger client endpoints (/messenger/identify and /messenger/events, available at version 0.1), which are called from browsers and apps with a signed user token or identity hash instead of an API key. Every error body is { error, code }.

Base URL and authentication

Base URL: https://api.octadezx.com/v1

Key-authenticated endpoints accept Authorization: Bearer odx_... or the x-api-key header, from a server only. Messenger client endpoints carry no API key and prove the user with a signed user token or an identity hash.

OpenAPI 3.1 spec

The full contract, including request and response schemas, is published as an OpenAPI 3.1 file at https://octadezx.com/openapi.yaml. Import it into Postman, Insomnia or a code generator. The table below summarises every operation.

Install

@octadezx/sdk (available, v0.1.0, MIT license)

Server SDK for Node.js 20 and newer: Agent API with streaming, signed user tokens, webhook verification and devices.

npm install @octadezx/sdk

@octadezx/sdk on npm

Questions or a larger rollout? Contact us (kevin@octadezx.com).

Operations

MethodPathSummaryAuthStatus
POST/messageSend one customer message and get the AI reply (original endpoint). (sendMessage)API keyavailable
GET/messages?sessionId=Read a conversation transcript (original endpoint). (getMessages)API keyavailable
POST/agent/startStart a conversation, or continue one, and get the AI's turn. Accept: text/event-stream streams it. (agentStart)API keyavailable (v0.1)
POST/agent/replySend the customer's next message in a conversation. (agentReply)API keyavailable (v0.1)
GET/agent/conversations/{conversationId}Read a conversation, its state, verified user and messages. (getConversation)API keyavailable (v0.1)
POST/agent/devicesRegister a push token for a verified user. API key from a server, or a user token or hash from a device. (registerDevice)API key, user token or user hashavailable (v0.1)
DELETE/agent/devicesUnregister a push token. (unregisterDevice)API key, user token or user hashavailable (v0.1)
POST/messenger/identifyVerify a user, store attributes and optionally bind a conversation. A failed verification is a 200 with verified: false. (messengerIdentify)User token or hash, no API keyavailable (v0.1)
POST/messenger/eventsRecord an event for a verified user. (messengerTrackEvent)User token or hash, no API keyavailable (v0.1)

Frequently asked questions

Keep reading

OctaDezx home · Pricing · Blog · Start free trial