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/sdkQuestions or a larger rollout? Contact us (kevin@octadezx.com).
Operations
| Method | Path | Summary | Auth | Status |
|---|---|---|---|---|
| POST | /message | Send one customer message and get the AI reply (original endpoint). (sendMessage) | API key | available |
| GET | /messages?sessionId= | Read a conversation transcript (original endpoint). (getMessages) | API key | available |
| POST | /agent/start | Start a conversation, or continue one, and get the AI's turn. Accept: text/event-stream streams it. (agentStart) | API key | available (v0.1) |
| POST | /agent/reply | Send the customer's next message in a conversation. (agentReply) | API key | available (v0.1) |
| GET | /agent/conversations/{conversationId} | Read a conversation, its state, verified user and messages. (getConversation) | API key | available (v0.1) |
| POST | /agent/devices | Register 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 hash | available (v0.1) |
| DELETE | /agent/devices | Unregister a push token. (unregisterDevice) | API key, user token or user hash | available (v0.1) |
| POST | /messenger/identify | Verify 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 key | available (v0.1) |
| POST | /messenger/events | Record an event for a verified user. (messengerTrackEvent) | User token or hash, no API key | available (v0.1) |
Frequently asked questions
- Is there an OpenAPI spec for the OctaDezx API? Yes. The OpenAPI 3.1 spec covering the public, Agent API and messenger client endpoints is public at https://octadezx.com/openapi.yaml.
- Which endpoints need an API key? The public API and the Agent API. The messenger client endpoints use a user token or hash instead, and /agent/devices accepts either.
- Which endpoints are available? All of them: the original /message and /messages endpoints, and, at version 0.1, the Agent API and the messenger client endpoints, at https://api.octadezx.com/v1.