Skip to main content
A message is one turn appended to a session.

​
What a message can contain

Messages accept ordered typed parts:
  • text
  • file
  • image
File and image parts reference previously uploaded files by file_id.

​
Message lifecycle

Every message send creates a message record under a session. The delivery mode changes how the HTTP request returns:
  • async returns after the message is queued
  • sync waits for a terminal result
  • stream returns incremental output while the same message executes
The message record then moves through one of these statuses:
  • queued
  • running
  • completed
  • failed
If the session already has active execution, the new message signals that workflow. If the session is idle, the same session_id can start a new workflow for the new turn.

​
Retries

Retry policy comes from dari.yml, not from resubmitting the same message manually. Dari tracks the current attempt on the message record.

​
Output

Completed messages can expose:
  • Structured output in output
  • Start and completion timestamps
Use the message record when you need per-turn execution details. Use the session record when you only need the latest session state. Treat the session filesystem as the canonical file surface.