Stored message formats

Assistant Cloud stores a format name with every message. The format preserves the writer's message shape, while a message read can request a compatible AI SDK shape.

The stored formats

The aui/v0 shape

aui/v0 is the complete assistant-ui message shape. It is stored with format: "aui/v0".

Message fields

Message parts

Attachments and metadata

Encode a message

The encoder drops the top level id and createdAt, because the server supplies those values. It rewrites a running status as { type: "incomplete", reason: "cancelled" }.

Attachments are stored only on a user message and only when that message has attachments. A tool call stores args when JSON.stringify(args) equals argsText; otherwise it stores argsText. A non JSON tool result or data value is still written after a warning. Nested tool messages keep their own ID and ISO createdAt.

An unsupported message part throws Message part type not supported by aui/v0: <type>. An unsupported attachment part throws Attachment part type not supported by aui/v0: <type>.

Decode a message

The decoder injects the server message ID and created_at, and exposes the stored parent_id as parentId. A nested tool message without an ID receives one synthesized from the containing message ID, tool call ID, and its indexes. A message with no status decodes as { type: "complete", reason: "unknown" }.

The ai-sdk/v6 shape

ai-sdk/v6 stores a UI message without its id. On read, the adapter adds the server message ID and the server parent ID as parentId.

Its telemetry reader examines assistant messages only. It opens a step for each step-start part, concatenates text parts into output text, and reads a tool's arguments from input or args and its result from output or result. A tool-<name> part is a frontend tool, while a dynamic-tool part with toolName is an MCP tool. Tool calls mark their step as tool-calls, and sampling calls are attached by tool call ID from metadata.samplingCalls.

Usage comes from metadata.usage, or from the sum of metadata.steps[].usage when that is absent. The reader sums usage across assistant messages and reads the model ID from message metadata. It reports completed when any text or tool call exists, and incomplete otherwise.

The ai-sdk/v5 shape

ai-sdk/v5 is the older AI SDK row with role and parts. It remains readable and can be converted to ai-sdk/v6. Its tool parts carry toolCallId, toolName, state, input, optional output, and optional errorText.

When converted from aui/v0, a tool call has output-available whenever result is present, output-error when isError is true, and input-available otherwise. Any result other than undefined counts as present, including false, 0, an empty string and null. During a v5 to v6 conversion, output-error becomes an error result and tries to parse errorText as JSON.

Read a compatible format

Pass format to GET /v1/threads/{thread_id}/messages or GET /v1/projects/threads/{thread_id}/messages to request a compatible row.

const { messages } = await cloud.threads.messages.list(
  "thread_0qzof3jPoDwr7K3agyJN3D4U",
  { format: "ai-sdk/v6" },
);
console.log(messages);

curl "https://backend.assistant-api.com/v1/threads/thread_0qzof3jPoDwr7K3agyJN3D4U/messages?format=ai-sdk%2Fv6" \
  -H "Authorization: Bearer $ASSISTANT_API_KEY" \
  -H "Aui-User-Id: user_123" \
  -H "Aui-Workspace-Id: workspace_123"

If a stored row cannot be parsed or converted, the list skips that row and logs a warning. It does not fail the whole response.

Extract text for a thread title

Thread title generation reads only messages whose role is user or assistant. A user message with no extracted text is omitted; an assistant message with no extracted text remains as an empty message. The title model then uses the first user and first assistant message, and only their text.