Home

AI API

version 1

The SeaRates Artificial Intelligence API allows you to ask the AI Assistant chat about everything on logistics and get access to a range of Digital Solutions for shipping from the SeaRates ecosystem.

OpenAPI Specification

Start designing your API in minutes. The OpenAPI specification file enables you to learn and interact with API elements, including all available endpoints, input and output representations.

OpenAPI Spec

General information

AI API is organized around REST.
Our API has predictable resource-oriented URLs, accepts form-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.

API endpoint#

1https://ai-api.searates.com

All endpoints are only accessible via HTTPS and are located at ai-api.searates.com

Stream Text Assistant Response

post/client/stream

Streams a text AI answer for an authorized user. clientId is resolved from the bearer token, not from the request body.

Headers

Content-Typeapplication/json

Body Parameters
  • queryREQUIREDstring
  • chatIdOptionalstring

    Existing chat id. Omit to create a new chat.

  • messagesOptionalarray[object]
Request sample
{
  "query": "Where is container MSKU7834389?"
}
Response example
Chunked text stream. Final line includes `done`, `chatId`, and `clientId`.

WebSocket Assistant Stream

get/client/stream

Upgrades to a WebSocket connection at /client/stream. The upgrade request must include Authorization: Bearer <token>. After connection, the server sends ready; then the client can send JSON messages for chat creation, text stream, voice stream, cancel, and ping.

Headers

Content-Typeapplication/json

Response example
WebSocket upgrade accepted.

Stream Voice Assistant Response

post/client/voice-stream

Streams text plus generated voice audio for an authorized user. clientId is resolved from the bearer token. voiceId can be sent in body or query.

Headers

Content-Typeapplication/json

Query Parameters
  • voiceIdOptionalstring

    Optional voice id for voice streaming. Body voiceId also works.

    Allowed values:tiffanymatthewamyambreflorianbeatricelorenzogretalennartlupecarlos

    Default:tiffany

Request sample
{
  "query": "Tell me about current freight rates from Shanghai to Los Angeles.",
  "voiceId": "tiffany"
}
Response example
Chunked mixed stream with `audio_meta:`, `response:`, `audio:`, and `voice_error:` prefixes.

Stream Authorized Chat Response

post/chat/client/stream

Streams an AI answer for an authorized chat user. This endpoint uses the same bearer-token authorization and returns clientId with final chatId.

Headers

Content-Typeapplication/json

Body Parameters
  • queryREQUIREDstring
  • chatIdOptionalstring

    Existing chat id. Omit to create a new chat.

  • messagesOptionalarray[object]
Response example
Chunked text stream.

Stream Guest Chat Response

post/chat/guest/stream

Streams AI chat for guests without login. Guest limits are tracked by socket IP plus guestId when present. The endpoint returns guest metadata and limit headers. When the free limit is reached, it streams a localized limit message instead of answering the user question.

Headers

Content-Typeapplication/json

Body Parameters
  • queryREQUIREDstring
  • guestIdOptionalstring
  • guest_idOptionalstring

    Legacy alias for guestId.

  • messagesOptionalarray[object]
Request sample
{
  "query": "How can I ship a container from Shanghai to Los Angeles?"
}
Response example
Chunked guest stream with guest limit metadata.

List Authorized User Chats

get/chat/list

Returns all chats for the authorized user. clientId is resolved from the bearer token.

Headers

Content-Typeapplication/json

Response example
List of chats.

Get Authorized User Chat By ID

get/chat/{chatId}

Returns a full chat by chatId for the authorized user. clientId is resolved from the bearer token.

Headers

Content-Typeapplication/json

Path Parameters
  • chatIdREQUIREDstring
Response example
Chat details.

Delete Authorized User Chat By ID

delete/chat/{chatId}

Deletes one chat by chatId for the authorized user. This endpoint never deletes all chats.

Headers

Content-Typeapplication/json

Path Parameters
  • chatIdREQUIREDstring
Response example
Chat deleted.
SeaRates 2026—Find a toolRequest an IT quoteContact us