General Conventions

This section describes the request format for the HTTP API. The DolphinX API also supports WebSocket calls. For field mapping rules between HTTP and WebSocket, see WebSocket Protocol.

By default, the HTTP API uses JSON as the request and response format. The client should construct requests according to the following conventions:

• Content-Type: application/json
• Common request headers:
  • x-agent-id: Optional. Specifies agentId, equivalent to agentId in the request body or query parameters.
  • x-session-id: Optional. Specifies sessionId.

The DolphinX API reuses the DolphinDB login session and current user identity. HTTP calls typically obtain a session or token through the DolphinDB login API (/api/login) first. WebSocket connections can include Authorization: Bearer during the handshake. The server uses the current user from the authentication context as userId. Developers must not pass userId in the payload to impersonate another identity. If you don't have the necessary permissions, the API returns BUS_PERMISSION_DENIED. If you are not logged in or the login session has expired, it returns BUS_UNAUTHENTICATED.

Common permissions include:

Obtain the DolphinDB login token

curl -sS -X POST "http://localhost:8848/api/login" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"username":"admin","password":"your-password"}'

The response is as follows. The DolphinDB login token is stored in the result field. Note that the result field is a string array. To retrieve the token, use result[0].

{
  "session":"8351577110388618226",
  "user":"admin",
  "code":0,
  "message":"",
  "result":["xxx"]
}

Non-streaming responses use a standard envelope structure. An envelope is a JSON object that wraps the data field, which contains the business data. To avoid repeating common outer fields, response examples in later articles show only the content of the data field. When calling an API, you receive the complete envelope and must retrieve the business data from the data field.

Envelope structure:

{
 "type": "RESPONSE",
 "msgId": "...",
 "correlationId": "<requestId>",
 "action": "<action>",
 "agentId": "<agentId>",
 "sessionId": "<sessionId>",
 "data": { ... },
 "headers": { "...": "..." }
}

• type: the return type.
• msgId: the message ID generated by the server.
• correlationId: used to correlate requests and responses. If the request does not provide x-request-id or a WebSocket requestId, the server generates one automatically.
• action: the called API.
• agentId: the agent ID.
• sessionId: the session ID.
• data: the business data.
• headers: business metadata fields within the envelope, not HTTP response headers. Returned only when the server-side envelope headers are not empty.

A response may include compatibility, diagnostic, or internal fields not listed in this article. These fields are not part of the stable public contract, and developers should not rely on them.

The following is an example error response. For detailed error code descriptions, see Error Codes.

{
 "type": "ERROR",
 "msgId": "...",
 "correlationId": "<requestId>",
 "action": "<action>",
 "agentId": "<agentId>",
 "sessionId": "<sessionId>",
 "error": {
 "code": "<BusErrorCode>",
 "message": "<error message>",
 "reason": "<optional, reason for the error>",
 "providerStatus": "<optional, HTTP status code from LLM provider>",
 "providerCode": "<optional, error code from LLM provider>",
 "retryable": "<optional, true|false>"
 },
 "headers": {
 "busErrorCode": "<BusErrorCode>",
 "httpStatus": "<HTTP status code>",
 "llmProviderStatus": "<optional, HTTP status code from LLM provider>",
 "providerCode": "<optional, error code from LLM provider>",
 "retryable": "<optional, true|false>"
 }
}

All list-related APIs support the following parameters:

Pagination parameters can be passed as URL query parameters or in the JSON request body.

For HTTP APIs that support streaming responses, the stream request parameter controls how the response is returned:

• stream=true (default): The response is returned as Server-Sent Events (SSE), so the server sends content as it is generated.
• stream=false: The response is returned as an envelope after the server has generated all content.

For WebSocket calls, specify this parameter in payload.stream in the request frame.

HTTP SSE and WebSocket use the same set of envelope types; only the outer transport format differs. A typical event sequence is as follows:

[Optional EVENT ...]
↓
STREAM_START
↓
[STREAM_CHUNK / STREAM_REASONING / EVENT ...]
↓
STREAM_END or STREAM_ERROR