# Chats

## List chats in a session[​](#list-chats "Direct link to 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

`sessionId`string · uuidrequired

Session UUID

Header parameters

`X-Organization-Id`string

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

Returns

`object`stringrequired

`data`arrayrequired

Show child attributes

`id`stringrequired

The chat's own id

`session`string · uuidrequired

Reference to the session the chat belongs to

`title`stringnullable

`organization`stringrequired

Reference to the owning organization

`user`stringrequired

Reference to the user who created the chat

`metadata`object

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

Show child attributes

`deviceId`string · uuid

`createdAt`string · date-timerequired

`updatedAt`string · date-timerequired

Request

```
curl https://api.mobilenexthq.com/api/v1/sessions/{sessionId}/chats \

  -X GET \

  -H 'Authorization: Bearer mob_...'
```

Response

200401403404

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[​](#create-chat "Direct link to 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

`sessionId`string · uuidrequired

Session UUID

Header parameters

`X-Organization-Id`string

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

Body parameters

`title`string

Human-readable title

`metadata`object

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

Show child attributes

`deviceId`string · uuid

Returns

A conversation with the assistant, inside a session.

`id`stringrequired

The chat's own id

`session`string · uuidrequired

Reference to the session the chat belongs to

`title`stringnullable

`organization`stringrequired

Reference to the owning organization

`user`stringrequired

Reference to the user who created the chat

`metadata`object

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

Show child attributes

`deviceId`string · uuid

`createdAt`string · date-timerequired

`updatedAt`string · 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

201400401403404

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-chat "Direct link to 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

`sessionId`string · uuidrequired

Session UUID

`chatId`stringrequired

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

Header parameters

`X-Organization-Id`string

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.

`id`stringrequired

The chat's own id

`session`string · uuidrequired

Reference to the session the chat belongs to

`title`stringnullable

`organization`stringrequired

Reference to the owning organization

`user`stringrequired

Reference to the user who created the chat

`metadata`object

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

Show child attributes

`deviceId`string · uuid

`createdAt`string · date-timerequired

`updatedAt`string · date-timerequired

Request

```
curl https://api.mobilenexthq.com/api/v1/sessions/{sessionId}/chats/{chatId} \

  -X GET \

  -H 'Authorization: Bearer mob_...'
```

Response

200401404

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[​](#list-chat-messages "Direct link to 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

`sessionId`string · uuidrequired

Session UUID

`chatId`stringrequired

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

Query parameters

`limit`integer

Maximum messages to return (default 100, max 500)

`before`string · 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-Id`string

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

Returns

`object`stringrequired

`data`arrayrequired

Show child attributes

`id`stringrequired

`chat`stringrequired

Reference to the chat

`role`stringrequired

`status`stringrequired

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

`content`arrayrequired

Show child attributes

`type`stringrequired

`text`stringrequired

`execution`object

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

Show child attributes

`id`stringrequired

`status`stringrequired

`triggerMessage`stringrequired

Reference to the user message that started this execution

`responseMessage`stringrequired

Reference to the assistant message this execution produces

`eventsUrl`stringrequired

SSE stream of this execution's events

`toolCallsUrl`stringrequired

`cancelUrl`stringrequired

`startedAt`string · date-timenullable

`completedAt`string · date-timenullable

`toolCalls`array

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

Show child attributes

`id`stringrequired

`execution`stringrequired

`message`stringrequired

`tool`stringrequired

`status`stringrequired

`input`object

Tool arguments, shape depends on the tool

`output`object

Tool result, shape depends on the tool

`error`stringnullable

`createdAt`string · date-timerequired

`completedAt`string · date-timenullable

`createdAt`string · date-timerequired

`completedAt`string · date-timenullable

`nextCursor`stringnullable

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

200400401404

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[​](#create-chat-message "Direct link to 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

`sessionId`string · uuidrequired

Session UUID

`chatId`stringrequired

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

Header parameters

`X-Organization-Id`string

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

Body parameters

`role`stringrequired

`content`arrayrequired

Show child attributes

`type`stringrequired

`text`stringrequired

`execute`boolean

false stores the user message without running the assistant

`mode`string

sync runs the assistant inline and returns the completed message

`stream`boolean

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

`model`string

Overrides the assistant's default model for this turn

`metadata`object

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

200201202400401403404

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

```
// No response body
```

## Get a message[​](#get-chat-message "Direct link to Get a message")

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

Path parameters

`sessionId`string · uuidrequired

Session UUID

`chatId`stringrequired

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

`messageId`stringrequired

Message id, e.g. msg\_9a3b…

Header parameters

`X-Organization-Id`string

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

Returns

`id`stringrequired

`chat`stringrequired

Reference to the chat

`role`stringrequired

`status`stringrequired

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

`content`arrayrequired

Show child attributes

`type`stringrequired

`text`stringrequired

`execution`object

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

Show child attributes

`id`stringrequired

`status`stringrequired

`triggerMessage`stringrequired

Reference to the user message that started this execution

`responseMessage`stringrequired

Reference to the assistant message this execution produces

`eventsUrl`stringrequired

SSE stream of this execution's events

`toolCallsUrl`stringrequired

`cancelUrl`stringrequired

`startedAt`string · date-timenullable

`completedAt`string · date-timenullable

`toolCalls`array

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

Show child attributes

`id`stringrequired

`execution`stringrequired

`message`stringrequired

`tool`stringrequired

`status`stringrequired

`input`object

Tool arguments, shape depends on the tool

`output`object

Tool result, shape depends on the tool

`error`stringnullable

`createdAt`string · date-timerequired

`completedAt`string · date-timenullable

`createdAt`string · date-timerequired

`completedAt`string · date-timenullable

Request

```
curl https://api.mobilenexthq.com/api/v1/sessions/{sessionId}/chats/{chatId}/messages/{messageId} \

  -X GET \

  -H 'Authorization: Bearer mob_...'
```

Response

200401404

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[​](#stream-chat-message-events "Direct link to 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

`sessionId`string · uuidrequired

Session UUID

`chatId`stringrequired

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

`messageId`stringrequired

Message id, e.g. msg\_9a3b…

Header parameters

`X-Organization-Id`string

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

200401404

An event stream for the message's execution

```
// No response body
```

## List a message's tool calls[​](#list-chat-message-tool-calls "Direct link to List a message's tool calls")

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

Path parameters

`sessionId`string · uuidrequired

Session UUID

`chatId`stringrequired

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

`messageId`stringrequired

Message id, e.g. msg\_9a3b…

Header parameters

`X-Organization-Id`string

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

Returns

`object`stringrequired

`data`arrayrequired

Show child attributes

`id`stringrequired

`execution`stringrequired

`message`stringrequired

`tool`stringrequired

`status`stringrequired

`input`object

Tool arguments, shape depends on the tool

`output`object

Tool result, shape depends on the tool

`error`stringnullable

`createdAt`string · date-timerequired

`completedAt`string · 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

200401404

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[​](#cancel-chat-message "Direct link to 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

`sessionId`string · uuidrequired

Session UUID

`chatId`stringrequired

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

`messageId`stringrequired

Message id, e.g. msg\_9a3b…

Header parameters

`X-Organization-Id`string

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

Returns

`id`stringrequired

`chat`stringrequired

Reference to the chat

`role`stringrequired

`status`stringrequired

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

`content`arrayrequired

Show child attributes

`type`stringrequired

`text`stringrequired

`execution`object

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

Show child attributes

`id`stringrequired

`status`stringrequired

`triggerMessage`stringrequired

Reference to the user message that started this execution

`responseMessage`stringrequired

Reference to the assistant message this execution produces

`eventsUrl`stringrequired

SSE stream of this execution's events

`toolCallsUrl`stringrequired

`cancelUrl`stringrequired

`startedAt`string · date-timenullable

`completedAt`string · date-timenullable

`toolCalls`array

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

Show child attributes

`id`stringrequired

`execution`stringrequired

`message`stringrequired

`tool`stringrequired

`status`stringrequired

`input`object

Tool arguments, shape depends on the tool

`output`object

Tool result, shape depends on the tool

`error`stringnullable

`createdAt`string · date-timerequired

`completedAt`string · date-timenullable

`createdAt`string · date-timerequired

`completedAt`string · date-timenullable

Request

```
curl https://api.mobilenexthq.com/api/v1/sessions/{sessionId}/chats/{chatId}/messages/{messageId}/cancel \

  -X POST \

  -H 'Authorization: Bearer mob_...'
```

Response

200401403404

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"

}
```