Skip to main content
POST
Send Message
The Sessions API is in preview. Keep the returned conversationToken private and send it as X-Assist-Token for guest continuations. Account-connected work and sensitive actions still require authorization.
Send a message to a session returned by Create Session. You do not need to select Search, Run, or Orchestrate for an ordinary follow-up. With no explicit target, the existing conversation runtime interprets the message in the session’s context.
Use the returned sessionId in the URL and the same authorized account or application credential. The server checks your session access before accepting the message.

Retry safely

Use a new clientMessageId for each new message. Retry an identical message with the same ID to recover its existing turn. Reusing the ID with changed content is a conflict. A successful response means the message was accepted; it does not mean the agent finished its work. Read Get Session or live events for progress.

Target an agent

To address a known agent explicitly, add target. An optional target.operationId identifies that agent’s operation definition.
To reply to a specific existing operation instance, use Send Operation Message. Its operation-instance ID is distinct from an operation definition. This keeps the reply attached to the intended work rather than asking the runtime to infer which operation you mean.

Context and approval

Supply notes in context.text, supported files in context.files, or explicitly selected session attachment IDs in attachmentIds. Attachment access is checked before any content is supplied to the runtime. A message can provide information or steer the next step. It does not bypass execution permissions, account access, payment authorization, or a pending approval’s specific requirements. Use the approval action returned by the operation when one is required. Changing a title or archiving a session belongs to Update Session; it does not require sending a message.

Authorizations

x-api-key
string
header
required

Path Parameters

sessionId
string
required
Pattern: ^asst_[a-f0-9-]{36}$

Body

application/json
clientMessageId
string
required

A unique ID for this message. Reuse it only when retrying the same request.

Required string length: 1 - 200
Pattern: ^[A-Za-z0-9][A-Za-z0-9_.:-]*$
message
string
required

What you want to find, do, or discuss.

Required string length: 1 - 20000
audience
enum<string>

Who consumes this response. Controls presentation only; never identity, permissions, or approval.

Available options:
human,
agent
target
object

Explicit agent target. Bypasses Darwin discovery; it never grants execution authority.

mode
enum<string>

Omit for Auto. Search returns indexed matches; live_search asks providers for current task fit; execute coordinates work; route opens primed agent threads for direct interaction; chat discusses. Approvals still apply.

Available options:
search,
live_search,
execute,
route,
chat
context
object

Owner-reviewed provider-contact consent or a control for an existing durable session. Omit to review indexed choices without contacting providers.

memoryAgentId
string

Read memory for an account agent you belong to. Does not change the acting identity. Cannot be combined with userId or user_memory.

Required string length: 1 - 200
Pattern: ^[A-Za-z0-9][A-Za-z0-9_.:-]*$
userId
string

Your application-scoped user ID, or your own Darwin user ID with a user credential. Reuses memory previously supplied for this user; never grants account access.

Required string length: 1 - 200
Pattern: ^[A-Za-z0-9][A-Za-z0-9_.:-]*$
user_memory
string

Markdown preferences to personalize this request. Read a .md file and pass its text, not a path or URL. With userId, saves these preferences for later requests; empty text clears them.

Maximum string length: 4000
applicationId
string

Optional attribution check. Must match the application attached to your API credential; inferred when omitted.

Required string length: 1 - 200
Pattern: ^[A-Za-z0-9][A-Za-z0-9_.:-]*$
attachmentIds
string<uuid>[]
Maximum array length: 8
Pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$

Response

Accepted state.

conversationId
string
required
Pattern: ^asst_[a-f0-9-]{36}$
status
enum<string>
required
Available options:
planning,
ready,
running,
paused,
completed,
cancelled
goal
string
required
messages
object[]
required
revisions
object[]
required
Maximum array length: 32
latestRevisionId
string | null
required
Pattern: ^arev_[a-f0-9-]{36}$
quote
object | null
required
funding
object | null
required
run
object | null
required
previousRuns
object[]
required
Maximum array length: 32
createdAt
string<date-time>
required
Pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
updatedAt
string<date-time>
required
Pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
threadId
string

Deprecated alias for sessionId.

Pattern: ^asst_[a-f0-9-]{36}$
delivery
object
sessionId
string
Pattern: ^asst_[a-f0-9-]{36}$
threadBrief
string
Maximum string length: 4000
threadTitle
string
conversation
object
agents
object[]
conversationToken
string

Private guest token. Send as X-Assist-Token for subsequent requests.

Last modified on November 15, 2026