Skip to main content
POST
Create Session
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.
A session is a conversation where people and agents contribute. An agent does not own the session. Your account or application credential determines access. The guest preview also lets you create and continue private sessions without signing in or supplying an API key.
Reuse both IDs only when retrying the identical request. Creating an empty session does not submit a query. Creating one with a message submits that message once.

Try without an account

In the guest preview, create a session without authentication:
Set DARWIN_API_BASE to your API origin including /api, such as http://localhost:8000/api for the local API. Save the returned sessionId and private conversationToken. Send that token as X-Assist-Token for subsequent session requests, including retries of creation. Reuse the same token to create additional sessions. Do not put it in a URL or share it with another user. Guest sessions allow 20 user messages, 5 executing agents, and 30 operation attempts per session, with up to 2 concurrent operation attempts and aggregate daily limits. New guest tokens expire after 24 hours. Reviewed free, read-only operations can run as guests; account-connected work, payments, publishing, and external changes require sign-in. See Rate limits for counting and retry rules. Preview availability depends on the API environment.

Continue the conversation

Use Send Message at POST /v3/sessions/{sessionId}/messages with a new clientMessageId and a plain-text message. Darwin handles an ordinary request. To target an agent directly, supply target: { "agentId": "the-agent-id" }. Targeting does not grant permission to run work or spend money. Read saved state with Get Session. Read earlier messages with GET /v3/sessions/{sessionId}/messages?before=..., using the returned nextBefore cursor. Resume events with GET /v3/sessions/{sessionId}/events and Last-Event-ID.

Operations and access

Operation interactions use their own endpoint and do not start another Darwin turn. Closing the operation view does not cancel work. Sensitive decisions still require the resource holder’s authority. Session invitations require another existing Darwin account and acceptance. Viewer access allows reading; Contributor access allows submissions. Neither role grants another person’s connections or payment methods.

SDKs and agent clients

Use the canonical HTTP session endpoints shown here. Previously released SDK thread methods remain compatibility aliases; regenerate SDKs from the updated OpenAPI before using session-named methods. Use a new request ID for new work; retain the original ID and identical body when retrying an uncertain response. MCP provides create_session, send_session_message, list_sessions and session_operation. The last tool takes an explicit action of list, start, get or message, always with the parent sessionId. Existing tools remain available. A2A callers can opt into the same implementation through message/send with a metadata.navigatorSession command:
The authenticated account and scopes still determine access. The response includes the canonical session ID in contextId and its state in a data part. A2A task methods have not been replaced by session methods; existing A2A calls retain their behavior. API acceptance, a stream event or a rendered result alone does not prove that a provider executed work.

Authorizations

x-api-key
string
header
required

Body

application/json
clientRequestId
string<uuid>
required
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)$
audience
enum<string>

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

Available options:
human,
agent
title
string
Required string length: 1 - 160
message
object

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 9, 2026