Chats

List chats in a session

GET/api/v1/sessions/{sessionId}/chats

Chats belonging to the session, oldest first. A chat exists only inside a session; there is no way to address one without it. Visible to every member of the organization that owns the session.

Path parameters

sessionIdstring · uuidrequired

Session UUID

Header parameters

X-Organization-Idstring

Selects which of the caller's organizations the request acts on. When omitted, the caller's default organization is used.

Returns

objectstringrequired

dataarrayrequired

Show child attributes

idstringrequired

The chat's own id

sessionstring · uuidrequired

Reference to the session the chat belongs to

titlestringnullable

organizationstringrequired

Reference to the owning organization

userstringrequired

Reference to the user who created the chat

metadataobject

Client-supplied metadata. deviceId binds the chat to an allocated device.

Show child attributes

deviceIdstring · uuid

createdAtstring · date-timerequired

updatedAtstring · date-timerequired

Request

curl https://api.mobilenexthq.com/api/v1/sessions/{sessionId}/chats \
  -X GET \
  -H 'Authorization: Bearer mob_...'

Response

Chats in the session

{
  "object": "list",
  "data": [
    {
      "id": "chat_2f1c8e4a-1f2b-4a1e-9a2c-0b7f5d3e6a11",
      "session": "string",
      "title": "string",
      "organization": "string",
      "user": "string",
      "metadata": {
        "deviceId": "string"
      },
      "createdAt": "2026-01-01T00:00:00Z",
      "updatedAt": "2026-01-01T00:00:00Z"
    }
  ]
}

Create a chat

POST/api/v1/sessions/{sessionId}/chats

Creates a chat in the session. Bind the chat to an allocated device by setting metadata.deviceId; the assistant's device tools then act on that device. Every action is still authorized against the caller, never against the bound device.

Path parameters

sessionIdstring · uuidrequired

Session UUID

Header parameters

X-Organization-Idstring

Selects which of the caller's organizations the request acts on. When omitted, the caller's default organization is used.

Body parameters

titlestring

Human-readable title

metadataobject

Client-supplied metadata. Set deviceId to bind the chat to a device allocated in this session.

Show child attributes

deviceIdstring · uuid

Returns

A conversation with the assistant, inside a session.

idstringrequired

The chat's own id

sessionstring · uuidrequired

Reference to the session the chat belongs to

titlestringnullable

organizationstringrequired

Reference to the owning organization

userstringrequired

Reference to the user who created the chat

metadataobject

Client-supplied metadata. deviceId binds the chat to an allocated device.

Show child attributes

deviceIdstring · uuid

createdAtstring · date-timerequired

updatedAtstring · date-timerequired

Request

curl https://api.mobilenexthq.com/api/v1/sessions/{sessionId}/chats \
  -X POST \
  -H 'Authorization: Bearer mob_...' \
  -H 'Content-Type: application/json' \
  -d '{"title":"string","metadata":{"deviceId":"string"}}'

Response

Chat created

{
  "id": "chat_2f1c8e4a-1f2b-4a1e-9a2c-0b7f5d3e6a11",
  "session": "string",
  "title": "string",
  "organization": "string",
  "user": "string",
  "metadata": {
    "deviceId": "string"
  },
  "createdAt": "2026-01-01T00:00:00Z",
  "updatedAt": "2026-01-01T00:00:00Z"
}

Get a chat

GET/api/v1/sessions/{sessionId}/chats/{chatId}

Returns a chat in the session. A chat id that belongs to a different session is not found, even within the same organization.

Path parameters

sessionIdstring · uuidrequired

Session UUID

chatIdstringrequired

Chat id, e.g. chat_2f1c…. Resolved within its session; a chat id from another session is not found.

Header parameters

X-Organization-Idstring

Selects which of the caller's organizations the request acts on. When omitted, the caller's default organization is used.

Returns

A conversation with the assistant, inside a session.

idstringrequired

The chat's own id

sessionstring · uuidrequired

Reference to the session the chat belongs to

titlestringnullable

organizationstringrequired

Reference to the owning organization

userstringrequired

Reference to the user who created the chat

metadataobject

Client-supplied metadata. deviceId binds the chat to an allocated device.

Show child attributes

deviceIdstring · uuid

createdAtstring · date-timerequired

updatedAtstring · date-timerequired

Request

curl https://api.mobilenexthq.com/api/v1/sessions/{sessionId}/chats/{chatId} \
  -X GET \
  -H 'Authorization: Bearer mob_...'

Response

Chat detail

{
  "id": "chat_2f1c8e4a-1f2b-4a1e-9a2c-0b7f5d3e6a11",
  "session": "string",
  "title": "string",
  "organization": "string",
  "user": "string",
  "metadata": {
    "deviceId": "string"
  },
  "createdAt": "2026-01-01T00:00:00Z",
  "updatedAt": "2026-01-01T00:00:00Z"
}

List messages in a chat

GET/api/v1/sessions/{sessionId}/chats/{chatId}/messages

The most recent messages of the chat, returned oldest first, with cursor pagination backwards into older history. Each assistant message includes the tool calls it made, so a client can rebuild the conversation — text and tool calls — after a page reload. Follow nextCursor with ?before= to load older messages.

Path parameters

sessionIdstring · uuidrequired

Session UUID

chatIdstringrequired

Chat id, e.g. chat_2f1c…. Resolved within its session; a chat id from another session is not found.

Query parameters

limitinteger

Maximum messages to return (default 100, max 500)

beforestring · date-time

Cursor: return the messages created strictly before this RFC3339 timestamp. Pass the nextCursor of a previous page to walk further back through the conversation.

Header parameters

X-Organization-Idstring

Selects which of the caller's organizations the request acts on. When omitted, the caller's default organization is used.

Returns

objectstringrequired

dataarrayrequired

Show child attributes

idstringrequired

chatstringrequired

Reference to the chat

rolestringrequired

statusstringrequired

For an assistant message this is its execution's status.

contentarrayrequired

Show child attributes

typestringrequired

textstringrequired

executionobject

The work behind an assistant message. Synthesized from the message; not a separate resource.

Show child attributes

idstringrequired

statusstringrequired

triggerMessagestringrequired

Reference to the user message that started this execution

responseMessagestringrequired

Reference to the assistant message this execution produces

eventsUrlstringrequired

SSE stream of this execution's events

toolCallsUrlstringrequired

cancelUrlstringrequired

startedAtstring · date-timenullable

completedAtstring · date-timenullable

toolCallsarray

Tool calls made while producing this message. Absent when there were none.

Show child attributes

idstringrequired

executionstringrequired

messagestringrequired

toolstringrequired

statusstringrequired

inputobject

Tool arguments, shape depends on the tool

outputobject

Tool result, shape depends on the tool

errorstringnullable

createdAtstring · date-timerequired

completedAtstring · date-timenullable

createdAtstring · date-timerequired

completedAtstring · date-timenullable

nextCursorstringnullable

Cursor for the next page; absent when there are no more results

Request

curl https://api.mobilenexthq.com/api/v1/sessions/{sessionId}/chats/{chatId}/messages \
  -X GET \
  -H 'Authorization: Bearer mob_...'

Response

Paginated list of messages, oldest first

{
  "object": "list",
  "data": [
    {
      "id": "msg_9a3b…",
      "chat": "string",
      "role": "user",
      "status": "running",
      "content": [
        {
          "type": "text",
          "text": "string"
        }
      ],
      "execution": {
        "id": "exec_7d2a…",
        "status": "running",
        "triggerMessage": "string",
        "responseMessage": "string",
        "eventsUrl": "string",
        "toolCallsUrl": "string",
        "cancelUrl": "string",
        "startedAt": "2026-01-01T00:00:00Z",
        "completedAt": "2026-01-01T00:00:00Z"
      },
      "toolCalls": [
        {
          "id": "toolcall_1b9e…",
          "execution": "string",
          "message": "string",
          "tool": "instance_bash",
          "status": "running",
          "input": {},
          "output": {},
          "error": "string",
          "createdAt": "2026-01-01T00:00:00Z",
          "completedAt": "2026-01-01T00:00:00Z"
        }
      ],
      "createdAt": "2026-01-01T00:00:00Z",
      "completedAt": "2026-01-01T00:00:00Z"
    }
  ],
  "nextCursor": "string"
}

Post a message and run the assistant

POST/api/v1/sessions/{sessionId}/chats/{chatId}/messages

Appends a user message and runs the assistant. Three modes:

default (async): responds 202 with the assistant message in status "running". Follow execution.eventsUrl to stream it.
mode=sync: runs inline and responds 201 with the completed assistant message and its tool calls.
stream=true: responds with a text/event-stream of execution and assistant.message events.

Set execute=false to store the user message without running the assistant.

Path parameters

sessionIdstring · uuidrequired

Session UUID

chatIdstringrequired

Chat id, e.g. chat_2f1c…. Resolved within its session; a chat id from another session is not found.

Header parameters

X-Organization-Idstring

Selects which of the caller's organizations the request acts on. When omitted, the caller's default organization is used.

Body parameters

rolestringrequired

contentarrayrequired

Show child attributes

typestringrequired

textstringrequired

executeboolean

false stores the user message without running the assistant

modestring

sync runs the assistant inline and returns the completed message

streamboolean

true responds with a text/event-stream instead of JSON

modelstring

Overrides the assistant's default model for this turn

metadataobject

Request

curl https://api.mobilenexthq.com/api/v1/sessions/{sessionId}/chats/{chatId}/messages \
  -X POST \
  -H 'Authorization: Bearer mob_...' \
  -H 'Content-Type: application/json' \
  -d '{"role":"user","content":[{"type":"text","text":"string"}],"execute":true,"mode":"async","stream":false,"model":"string","metadata":{}}'

Response

stream=true: a text/event-stream of execution.* and assistant.message.* events

// No response body

Get a message

GET/api/v1/sessions/{sessionId}/chats/{chatId}/messages/{messageId}

Path parameters

sessionIdstring · uuidrequired

Session UUID

chatIdstringrequired

Chat id, e.g. chat_2f1c…. Resolved within its session; a chat id from another session is not found.

messageIdstringrequired

Message id, e.g. msg_9a3b…

Header parameters

X-Organization-Idstring

Selects which of the caller's organizations the request acts on. When omitted, the caller's default organization is used.

Returns

idstringrequired

chatstringrequired

Reference to the chat

rolestringrequired

statusstringrequired

For an assistant message this is its execution's status.

contentarrayrequired

Show child attributes

typestringrequired

textstringrequired

executionobject

The work behind an assistant message. Synthesized from the message; not a separate resource.

Show child attributes

idstringrequired

statusstringrequired

triggerMessagestringrequired

Reference to the user message that started this execution

responseMessagestringrequired

Reference to the assistant message this execution produces

eventsUrlstringrequired

SSE stream of this execution's events

toolCallsUrlstringrequired

cancelUrlstringrequired

startedAtstring · date-timenullable

completedAtstring · date-timenullable

toolCallsarray

Tool calls made while producing this message. Absent when there were none.

Show child attributes

idstringrequired

executionstringrequired

messagestringrequired

toolstringrequired

statusstringrequired

inputobject

Tool arguments, shape depends on the tool

outputobject

Tool result, shape depends on the tool

errorstringnullable

createdAtstring · date-timerequired

completedAtstring · date-timenullable

createdAtstring · date-timerequired

completedAtstring · date-timenullable

Request

curl https://api.mobilenexthq.com/api/v1/sessions/{sessionId}/chats/{chatId}/messages/{messageId} \
  -X GET \
  -H 'Authorization: Bearer mob_...'

Response

Message detail, including its tool calls

{
  "id": "msg_9a3b…",
  "chat": "string",
  "role": "user",
  "status": "running",
  "content": [
    {
      "type": "text",
      "text": "string"
    }
  ],
  "execution": {
    "id": "exec_7d2a…",
    "status": "running",
    "triggerMessage": "string",
    "responseMessage": "string",
    "eventsUrl": "string",
    "toolCallsUrl": "string",
    "cancelUrl": "string",
    "startedAt": "2026-01-01T00:00:00Z",
    "completedAt": "2026-01-01T00:00:00Z"
  },
  "toolCalls": [
    {
      "id": "toolcall_1b9e…",
      "execution": "string",
      "message": "string",
      "tool": "instance_bash",
      "status": "running",
      "input": {},
      "output": {},
      "error": "string",
      "createdAt": "2026-01-01T00:00:00Z",
      "completedAt": "2026-01-01T00:00:00Z"
    }
  ],
  "createdAt": "2026-01-01T00:00:00Z",
  "completedAt": "2026-01-01T00:00:00Z"
}

Stream a message's execution events

GET/api/v1/sessions/{sessionId}/chats/{chatId}/messages/{messageId}/events

Server-Sent Events for one assistant message: execution.started, assistant.message.started, assistant.message.delta, tool_call.created, tool_call.completed, assistant.message.completed, execution.completed|failed.

Safe to call after a disconnect: a still-running execution replays its events from the start, and a finished one replays its stored final state — the stored replay emits the message text as a single delta and no tool_call events. Clients must therefore not render the message's persisted text and also reattach here, or the text appears twice.

Path parameters

sessionIdstring · uuidrequired

Session UUID

chatIdstringrequired

Chat id, e.g. chat_2f1c…. Resolved within its session; a chat id from another session is not found.

messageIdstringrequired

Message id, e.g. msg_9a3b…

Header parameters

X-Organization-Idstring

Selects which of the caller's organizations the request acts on. When omitted, the caller's default organization is used.

Request

curl https://api.mobilenexthq.com/api/v1/sessions/{sessionId}/chats/{chatId}/messages/{messageId}/events \
  -X GET \
  -H 'Authorization: Bearer mob_...'

Response

An event stream for the message's execution

// No response body

List a message's tool calls

GET/api/v1/sessions/{sessionId}/chats/{chatId}/messages/{messageId}/tool-calls

Path parameters

sessionIdstring · uuidrequired

Session UUID

chatIdstringrequired

Chat id, e.g. chat_2f1c…. Resolved within its session; a chat id from another session is not found.

messageIdstringrequired

Message id, e.g. msg_9a3b…

Header parameters

X-Organization-Idstring

Selects which of the caller's organizations the request acts on. When omitted, the caller's default organization is used.

Returns

objectstringrequired

dataarrayrequired

Show child attributes

idstringrequired

executionstringrequired

messagestringrequired

toolstringrequired

statusstringrequired

inputobject

Tool arguments, shape depends on the tool

outputobject

Tool result, shape depends on the tool

errorstringnullable

createdAtstring · date-timerequired

completedAtstring · date-timenullable

Request

curl https://api.mobilenexthq.com/api/v1/sessions/{sessionId}/chats/{chatId}/messages/{messageId}/tool-calls \
  -X GET \
  -H 'Authorization: Bearer mob_...'

Response

Tool calls made while producing the message

{
  "object": "list",
  "data": [
    {
      "id": "toolcall_1b9e…",
      "execution": "string",
      "message": "string",
      "tool": "instance_bash",
      "status": "running",
      "input": {},
      "output": {},
      "error": "string",
      "createdAt": "2026-01-01T00:00:00Z",
      "completedAt": "2026-01-01T00:00:00Z"
    }
  ]
}

Cancel a running message

POST/api/v1/sessions/{sessionId}/chats/{chatId}/messages/{messageId}/cancel

Requests cancellation of a message whose execution is still running. Requires a read/write or admin role.

Path parameters

sessionIdstring · uuidrequired

Session UUID

chatIdstringrequired

Chat id, e.g. chat_2f1c…. Resolved within its session; a chat id from another session is not found.

messageIdstringrequired

Message id, e.g. msg_9a3b…

Header parameters

X-Organization-Idstring

Selects which of the caller's organizations the request acts on. When omitted, the caller's default organization is used.

Returns

idstringrequired

chatstringrequired

Reference to the chat

rolestringrequired

statusstringrequired

For an assistant message this is its execution's status.

contentarrayrequired

Show child attributes

typestringrequired

textstringrequired

executionobject

The work behind an assistant message. Synthesized from the message; not a separate resource.

Show child attributes

idstringrequired

statusstringrequired

triggerMessagestringrequired

Reference to the user message that started this execution

responseMessagestringrequired

Reference to the assistant message this execution produces

eventsUrlstringrequired

SSE stream of this execution's events

toolCallsUrlstringrequired

cancelUrlstringrequired

startedAtstring · date-timenullable

completedAtstring · date-timenullable

toolCallsarray

Tool calls made while producing this message. Absent when there were none.

Show child attributes

idstringrequired

executionstringrequired

messagestringrequired

toolstringrequired

statusstringrequired

inputobject

Tool arguments, shape depends on the tool

outputobject

Tool result, shape depends on the tool

errorstringnullable

createdAtstring · date-timerequired

completedAtstring · date-timenullable

createdAtstring · date-timerequired

completedAtstring · date-timenullable

Request

curl https://api.mobilenexthq.com/api/v1/sessions/{sessionId}/chats/{chatId}/messages/{messageId}/cancel \
  -X POST \
  -H 'Authorization: Bearer mob_...'

Response

The message with its updated status

{
  "id": "msg_9a3b…",
  "chat": "string",
  "role": "user",
  "status": "running",
  "content": [
    {
      "type": "text",
      "text": "string"
    }
  ],
  "execution": {
    "id": "exec_7d2a…",
    "status": "running",
    "triggerMessage": "string",
    "responseMessage": "string",
    "eventsUrl": "string",
    "toolCallsUrl": "string",
    "cancelUrl": "string",
    "startedAt": "2026-01-01T00:00:00Z",
    "completedAt": "2026-01-01T00:00:00Z"
  },
  "toolCalls": [
    {
      "id": "toolcall_1b9e…",
      "execution": "string",
      "message": "string",
      "tool": "instance_bash",
      "status": "running",
      "input": {},
      "output": {},
      "error": "string",
      "createdAt": "2026-01-01T00:00:00Z",
      "completedAt": "2026-01-01T00:00:00Z"
    }
  ],
  "createdAt": "2026-01-01T00:00:00Z",
  "completedAt": "2026-01-01T00:00:00Z"
}

List chats in a session​

Create a chat​

Get a chat​

List messages in a chat​

Post a message and run the assistant​

Get a message​

Stream a message's execution events​

List a message's tool calls​

Cancel a running message​

List chats in a session

Create a chat

Get a chat

List messages in a chat

Post a message and run the assistant

Get a message

Stream a message's execution events

List a message's tool calls

Cancel a running message