Skip to main content
POST
Create a new agent session

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json
prompt
string
required
Minimum string length: 1
workspaceElementType
enum<string>
Available options:
tenant,
app,
connector,
oauth-client,
action,
connection,
browser-session,
agent-session,
data-table,
data-table-record,
external-event-log-record,
external-event-pull,
event-source,
event-listener,
action-run-log-record,
external-api-log-record,
incoming-webhook-log-record,
external-reference,
job,
deliverable,
receipt,
job-contract,
job-operator-assignment,
crew-member,
routine,
routine-run,
task,
intake,
command-execution,
canvas,
screen,
file,
knowledge-article,
source-tree,
source-tree-version,
source-module
workspaceElementId
string
Minimum string length: 1
memberTenantId
string
labels
string[]

Client-supplied labels on the session — a flat, unordered set used to group sessions across workspaces and elements (benchmark runs, an experiment arm, a customer tier). Trimmed and de-duplicated on write; filterable with the label query on the session list.

Maximum array length: 20
Required string length: 1 - 64
metadata
object

Freeform client-owned JSON stored on the session and returned unchanged. The platform never reads it; use labels for anything you need to filter on.

isExternal
boolean
startedAt
string

When the mirrored run actually began. External sessions only — a hosted session starts when it is created, so supplying it there is rejected.

endedAt
string

When the mirrored run actually finished. External sessions only — a hosted session ends when its worker says so, so supplying it there is rejected.

externalSessionId
string

The producer's own id for the session this mirror follows — e.g. a local Claude Code session id. External sessions only; rejected on a hosted session.

Required string length: 1 - 200
modelId
string
Required string length: 3 - 200
Pattern: ^[^\s/]+\/[^\s]+$
reasoningEffort
enum<string>

Reasoning effort for every model call in the session. Omit it to use the selected model/provider default; use none to explicitly disable reasoning.

Available options:
none,
minimal,
low,
medium,
high,
xhigh,
max
preset

Which situation the agent runs in. Defaults from the bound element type, else general — external sessions get the same derivation, and carrying a preset never turns an external session into a hosted run. Retired ids (context, universe, external-task, connection-build, action-build, capture) are accepted and resolve to their successors.

Available options:
general,
canvas,
screen,
data,
events,
knowledge,
connection,
action,
work,
client,
task,
learning
surface
enum<string>

The UI surface this session is launched in — selects the affordance instruction the agent gets (whether it can render one-click buttons, whether a live user is watching, whether it is already inside the connect flow). Defaults to background for child / inline-build sessions, else unset.

Available options:
console-chat,
context-rail,
table-chat,
connect-popup,
mcp-embedded,
cli,
desktop,
local,
background,
default-external-agent
launchContext
object

Where the session is launched from (surface / app route / anchored element). Merged with the top-level surface and workspaceElementType/Id fields (which win when both are set) and rendered into the agent's "Where you are" context.

agentHarnessId
string
Minimum string length: 1
adminCatalog
boolean

Run with the platform command catalog instead of the workspace one. Platform admins only; the session records the flag and the agent composes the wider command index from it.

promptAttachments
object[]
parentSessionId
string
Minimum string length: 1
synthetic
boolean

When true, the initial prompt is a hidden system kickoff: the model receives it, but the chat UI suppresses the user bubble. Mirrors the resume-path synthetic flag.

Response

200 - application/json
id
string
required
workspaceId
string
required
type
string
required
status
enum<string>
required
Available options:
queued,
starting,
running,
completed,
failed,
cancelled
prompt
string
required
lastActivityAt
string<date-time>
required

Last meaningful session progress timestamp used for inactivity timeout checks.

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))$
hasWorker
boolean
required
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))$
tenantId
string
ownerName
string | null
orgWorkspaceId
string
ownerPlatformUserId
string
workspaceElementType
enum<string>
Available options:
tenant,
app,
connector,
oauth-client,
action,
connection,
browser-session,
agent-session,
data-table,
data-table-record,
external-event-log-record,
external-event-pull,
event-source,
event-listener,
action-run-log-record,
external-api-log-record,
incoming-webhook-log-record,
external-reference,
job,
deliverable,
receipt,
job-contract,
job-operator-assignment,
crew-member,
routine,
routine-run,
task,
intake,
command-execution,
canvas,
screen,
file,
knowledge-article,
source-tree,
source-tree-version,
source-module
workspaceElementId
string
error
object
archivedAt
string<date-time>

When set, the session is archived (soft-deleted) and hidden from lists.

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))$
title
string
summary
string
labels
string[]

Client-supplied labels on the session — a flat, unordered set used to group sessions across workspaces and elements (benchmark runs, an experiment arm, a customer tier). Trimmed and de-duplicated on write; filterable with the label query on the session list.

Maximum array length: 20
Required string length: 1 - 64
metadata
object

Freeform client-owned JSON stored on the session and returned unchanged. The platform never reads it; use labels for anything you need to filter on.

cost
number
estimatedCost
number

API-list-price equivalent for subsidized provider usage; not deducted from AI credits.

extraSpendAllowance
number

Money granted to this session beyond the configured lifetime spend ceiling, by an operator continuing a run the ceiling stopped. The session may spend that ceiling plus this. Non-zero means someone decided this run was worth more than the default, which is what makes an unusually expensive run visible rather than silently unlimited.

state
enum<string>
default:busy
Available options:
busy,
idle
promptPending
boolean

A user turn is queued but not yet picked up. An IDLE session with one is still working, so anything deciding whether a run has settled must read this alongside state (see taskStatusForSettledAgentSession).

promptSynthetic
boolean

The buffered prompt is a hidden system kickoff: the model receives it, but the chat UI must not draw it as a user bubble while the transcript loads.

inputs
object[]

Unconsumed and withdrawn items in the session input timeline, ordered by sequence.

stopping
boolean

A durable stop targets the open activation and will cancel it at its next fenced wake.

isExternal
boolean

Whether an external harness (e.g. Claude Code) produces the session. An external session is never dispatched to a Membrane worker, whatever its preset says: its producer pushes the transcript up and downloads the composed context package down. One session row carries both directions.

startedAt
string<date-time>

When the mirrored run actually began, as reported by the producer of an external session. A hosted session is created the moment it starts, so createdAt is its start; an external session is created when its producer first uploads, which can be long after the work began. Timeline spans read this in preference to createdAt.

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))$
endedAt
string<date-time>

When the mirrored run actually finished, as reported by the producer of an external session. Read only once the session has settled — a session still working keeps an open span whatever this says.

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))$
externalSessionId
string

The producer's own id for the session this external session mirrors — e.g. a local Claude Code session id. External sessions only; lets a producer recover its local-to-platform mapping from the API.

preset
enum<string>

Which situation the one membrane agent runs in — selects the skills + context it loads.

Available options:
general,
canvas,
screen,
data,
events,
knowledge,
connection,
action,
work,
client,
task,
learning
adminCatalog
boolean

Whether the session runs with the platform command catalog (platform-admin sessions).

launchContext
object

Where the session was launched from — the resolved surface / route / element envelope shared by the console UI and the agent.

agentHarnessId
string
agentHarnessSnapshotId
string
modelId
string

AI Gateway model preset used by this session.

reasoningEffort
enum<string>

Reasoning effort used for every model call in this session. When omitted, the selected model/provider default is preserved; none explicitly disables reasoning.

Available options:
none,
minimal,
low,
medium,
high,
xhigh,
max
output
object
outputAttachments
object[]
promptAttachments
object[]
parentSessionId
string