Skip to content
Optiwork API Docs

Chat with a conversation history

POST
/ai/text/chat/contextual
curl --request POST \
  --url https://ai.work.optidata.cloud/api/ai/text/chat/contextual \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "messages": [ { "role": "system", "content": "Answer in one word." }, { "role": "user", "content": "Say OK." } ] }'

Sends a whole conversation — instructions, earlier questions and answers — and streams the assistant’s next answer as server-sent events. The last entry of messages is the one being answered.

Roles follow the usual chat convention: system for instructions, user for the person’s messages, assistant for earlier answers.

Authorizations

Section titled “Authorizations”

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
object
messages
required

The conversation so far, oldest first. The last entry is answered.

Array<object>
>= 1 items
object
role
required

Who wrote the message.

string
Allowed values: system user assistant
content
required

The message text.

string
Examples
Exampleconversation
{
  "messages": [
    {
      "role": "system",
      "content": "Answer in one word."
    },
    {
      "role": "user",
      "content": "Say OK."
    }
  ]
}

Responses

Section titled “ Responses ”

200

Section titled “200”

The answer, streamed as server-sent events. Each message event’s data is a JSON-encoded piece of text; a final content-end event closes the stream.

Media typetext/event-stream
string
Examples
Exampleanswer
id: 0
event: message
data: ""


id: 1
event: message
data: "OK"


id: -1
event: content-end
data: {"time": "2026-10-19 11:27:46"}

401

Section titled “401”

No authentication key was sent.

Media typeapplication/json

Authentication failures use an error key rather than message.

object
error
required
string
Examples
Examplemissing

No bearer token sent

{
  "error": "JWT passport exception: Missing bearer token in request"
}

419

Section titled “419”

The authentication key is expired or not recognised. Get a fresh one and retry.

Media typeapplication/json

Authentication failures use an error key rather than message.

object
error
required
string
Examples
Exampleexpired
{
  "error": "JWT passport expired: Passport expired"
}

422

Section titled “422”

A message is missing its role or content, or messages was not sent.

Media typeapplication/json
object
message
required

The first validation message.

string
errors
required

Validation messages keyed by field name.

object
key
additional properties
Array<string>
Examples
ExamplemissingContent
{
  "message": "The messages.0.content field is required.",
  "errors": {
    "messages.0.content": [
      "The messages.0.content field is required."
    ]
  }
}