Droid Sessions API
Create and drive Droid sessions: manage their lifecycle, settings, and messages.
List sessions
Returns a paginated list of sessions for the authenticated user. This feature is enabled for selected organizations only.
curl 'https://api.factory.ai/api/v0/sessions' \
-H 'Authorization: Bearer $FACTORY_API_KEY'Parameters
Maximum number of items to return (1-100)
Cursor for pagination
Computer ID to query directly
Responses
Session ID
Immediate parent session ID for a Task subagent, if one exists
Session title
Current session execution status
Allowed values
Number of messages in session
Creation timestamp (Unix ms)
Last update timestamp (Unix ms)
Completion timestamp (Unix ms)
Connected computer ID
Allowed values
Allowed values
Allowed values
Deprecated: use interactionMode + autonomyLevel instead.
Allowed values
Allowed values
Allowed values
Allowed values
Values
Allowed values
Allowed values
Integration artifacts (pull requests, issues, pages) the session touched, oldest first
Allowed values
Allowed values
Allowed values
Allowed values
Allowed values
Total Factory credits consumed by the session and its subagents
Whether there are more items after this page
Cursor to use for the next page, null if no more pages
401Response for status 401
Human-readable error message
HTTP status code
HTTP status title
Additional error metadata
Values
403Response for status 403
Human-readable error message
HTTP status code
HTTP status title
Additional error metadata
Values
500Response for status 500
Human-readable error message
HTTP status code
HTTP status title
Additional error metadata
Values
503Response for status 503
Human-readable error message
HTTP status code
HTTP status title
Additional error metadata
Values
Create a session
Creates a new session with the specified configuration. This feature is enabled for selected organizations only.
curl -X POST 'https://api.factory.ai/api/v0/sessions' \
-H 'Authorization: Bearer $FACTORY_API_KEY' \
-H 'Content-Type: application/json' \
-d '{ ... }'Request body
Computer ID to connect
Working directory for the session on the computer.
Allowed values
Allowed values
Allowed values
Deprecated: use interactionMode + autonomyLevel instead.
Allowed values
Allowed values
Allowed values
Allowed values
Values
Allowed values
Allowed values
Pattern: \S
Allowed values
Allowed values
Responses
Session ID
Immediate parent session ID for a Task subagent, if one exists
Session title
Current session execution status
Allowed values
Number of messages in session
Creation timestamp (Unix ms)
Last update timestamp (Unix ms)
Completion timestamp (Unix ms)
Connected computer ID
Allowed values
Allowed values
Allowed values
Deprecated: use interactionMode + autonomyLevel instead.
Allowed values
Allowed values
Allowed values
Allowed values
Values
Allowed values
Allowed values
Integration artifacts (pull requests, issues, pages) the session touched, oldest first
Allowed values
Allowed values
Allowed values
Allowed values
Allowed values
Total Factory credits consumed by the session and its subagents
400Response for status 400
Human-readable error message
HTTP status code
HTTP status title
Additional error metadata
Values
401Response for status 401
Human-readable error message
HTTP status code
HTTP status title
Additional error metadata
Values
403Response for status 403
Human-readable error message
HTTP status code
HTTP status title
Additional error metadata
Values
429Response for status 429
Human-readable error message
HTTP status code
HTTP status title
Additional error metadata
Values
500Response for status 500
Human-readable error message
HTTP status code
HTTP status title
Additional error metadata
Values
503Response for status 503
Human-readable error message
HTTP status code
HTTP status title
Additional error metadata
Values
504Response for status 504
Human-readable error message
HTTP status code
HTTP status title
Additional error metadata
Values
Get a session
Returns detailed session information including settings and stats. This feature is enabled for selected organizations only.
curl 'https://api.factory.ai/api/v0/sessions/{sessionId}' \
-H 'Authorization: Bearer $FACTORY_API_KEY'Parameters
Session ID
Computer ID to query directly
Responses
Session ID
Immediate parent session ID for a Task subagent, if one exists
Session title
Current session execution status
Allowed values
Number of messages in session
Creation timestamp (Unix ms)
Last update timestamp (Unix ms)
Completion timestamp (Unix ms)
Connected computer ID
Allowed values
Allowed values
Allowed values
Deprecated: use interactionMode + autonomyLevel instead.
Allowed values
Allowed values
Allowed values
Allowed values
Values
Allowed values
Allowed values
Integration artifacts (pull requests, issues, pages) the session touched, oldest first
Allowed values
Allowed values
Allowed values
Allowed values
Allowed values
Total Factory credits consumed by the session and its subagents
401Response for status 401
Human-readable error message
HTTP status code
HTTP status title
Additional error metadata
Values
403Response for status 403
Human-readable error message
HTTP status code
HTTP status title
Additional error metadata
Values
404Response for status 404
Human-readable error message
HTTP status code
HTTP status title
Additional error metadata
Values
500Response for status 500
Human-readable error message
HTTP status code
HTTP status title
Additional error metadata
Values
503Response for status 503
Human-readable error message
HTTP status code
HTTP status title
Additional error metadata
Values
Delete a session
Deletes a session (can be restored within retention period). This feature is enabled for selected organizations only.
curl -X DELETE 'https://api.factory.ai/api/v0/sessions/{sessionId}' \
-H 'Authorization: Bearer $FACTORY_API_KEY'Parameters
Session ID
Computer ID to query directly
Responses
400Response for status 400
Human-readable error message
HTTP status code
HTTP status title
Additional error metadata
Values
401Response for status 401
Human-readable error message
HTTP status code
HTTP status title
Additional error metadata
Values
403Response for status 403
Human-readable error message
HTTP status code
HTTP status title
Additional error metadata
Values
404Response for status 404
Human-readable error message
HTTP status code
HTTP status title
Additional error metadata
Values
500Response for status 500
Human-readable error message
HTTP status code
HTTP status title
Additional error metadata
Values
503Response for status 503
Human-readable error message
HTTP status code
HTTP status title
Additional error metadata
Values
Update a session
Updates session configuration such as model and reasoning effort. This feature is enabled for selected organizations only.
curl -X PATCH 'https://api.factory.ai/api/v0/sessions/{sessionId}' \
-H 'Authorization: Bearer $FACTORY_API_KEY' \
-H 'Content-Type: application/json' \
-d '{ ... }'Parameters
Session ID
Request body
Allowed values
Allowed values
Allowed values
Deprecated: use interactionMode + autonomyLevel instead.
Allowed values
Allowed values
Allowed values
Allowed values
Values
Allowed values
Responses
Session ID
Immediate parent session ID for a Task subagent, if one exists
Session title
Current session execution status
Allowed values
Number of messages in session
Creation timestamp (Unix ms)
Last update timestamp (Unix ms)
Completion timestamp (Unix ms)
Connected computer ID
Allowed values
Allowed values
Allowed values
Deprecated: use interactionMode + autonomyLevel instead.
Allowed values
Allowed values
Allowed values
Allowed values
Values
Allowed values
Allowed values
Integration artifacts (pull requests, issues, pages) the session touched, oldest first
Allowed values
Allowed values
Allowed values
Allowed values
Allowed values
Total Factory credits consumed by the session and its subagents
401Response for status 401
Human-readable error message
HTTP status code
HTTP status title
Additional error metadata
Values
403Response for status 403
Human-readable error message
HTTP status code
HTTP status title
Additional error metadata
Values
404Response for status 404
Human-readable error message
HTTP status code
HTTP status title
Additional error metadata
Values
500Response for status 500
Human-readable error message
HTTP status code
HTTP status title
Additional error metadata
Values
503Response for status 503
Human-readable error message
HTTP status code
HTTP status title
Additional error metadata
Values
List a session's child sessions
Returns the caller's sessions spawned under one parent session (Task subagents, mission agents) with their last reported status and the state of the computer each runs on, oldest first. A member of a shared workstream lists the agents under it they are a member of instead. Computer details are only included for computers the caller owns. Artifacts are included only when `includeArtifacts=true`; what each session is waiting on only when `includeAttention=true`; token usage and Factory Standard Credits, rolled up with each session's Task subagents, only when `includeUsage=true`. Archived sessions are left out unless `includeArchived=true`, which lists them with `archivedAt` and sets `archivedIncluded` on the response. For enterprise organizations, `usage.tokenCountsScope` is `byok_only` and token counts cover only calls the client reported as made with the organization's own provider keys (BYOK); managed-inference calls, and usage reported before clients tagged BYOK calls, count as zero. Credits always cover every call.
curl 'https://api.factory.ai/api/v0/sessions/{sessionId}/children' \
-H 'Authorization: Bearer $FACTORY_API_KEY'Parameters
The parent session id
Whether to include each child session’s integration artifacts (pull requests, issues, pages).
Allowed values
Whether to include what each child session is waiting on (a permission prompt or a question).
Allowed values
Whether to include each child session’s token usage and Factory Standard Credits, rolled up with its Task subagents.
Allowed values
Whether to include archived child sessions, such as a mission agent whose computer was reclaimed, each with its archivedAt. The response sets archivedIncluded when it does.
Allowed values
Responses
Session ID
Session title; empty until the session has one
Current session execution status
Allowed values
Creation timestamp (Unix ms)
Last update timestamp (Unix ms); the status has held at least since then
Session tags, including any mission identity
Values
Integration artifacts the session created; only returned when includeArtifacts=true
Allowed values
Allowed values
Allowed values
Allowed values
Allowed values
What the session is waiting on, or null when it is not blocked; only returned when includeAttention=true
Allowed values
Token usage and Factory Standard Credits for the session and its Task subagents, or null when it has not reported any; factoryCredits is omitted when the organization hides billable usage. For enterprise organizations tokenCountsScope is byok_only and the token counts cover only calls the client reported as BYOK; managed-inference calls, and usage reported before clients tagged BYOK calls, count as zero. Only returned when includeUsage=true
Allowed values
When the session was archived (Unix ms), or null when it is archived but its stored marker has no readable time; absent for a live session. Only returned when includeArchived=true
The computer the session records; null when it runs on the parent's own machine
The recorded computer when the caller owns it, or null when there is none, it is gone, or it is someone else's; compare with computerId to tell these apart
Allowed values
Last known sandbox lifecycle state; null for BYOM computers. More states may be added, so treat a value you do not know as unknown.
Allowed values
Present when the list includes archived child sessions, as includeArchived=true asks for
Allowed values
400Response for status 400
Human-readable error message
HTTP status code
HTTP status title
Additional error metadata
Values
401Response for status 401
Human-readable error message
HTTP status code
HTTP status title
Additional error metadata
Values
402Response for status 402
Human-readable error message
HTTP status code
HTTP status title
Additional error metadata
Values
403Response for status 403
Human-readable error message
HTTP status code
HTTP status title
Additional error metadata
Values
404Response for status 404
Human-readable error message
HTTP status code
HTTP status title
Additional error metadata
Values
429Response for status 429
Human-readable error message
HTTP status code
HTTP status title
Additional error metadata
Values
500Response for status 500
Human-readable error message
HTTP status code
HTTP status title
Additional error metadata
Values
503Response for status 503
Human-readable error message
HTTP status code
HTTP status title
Additional error metadata
Values
List pending session elicitations
Returns the permission prompts (including spec approvals) and AskUser questions the session is waiting on. Each item carries the same fields the SDK permissionHandler and askUserHandler receive, plus the requestId to answer it with, and a permission prompt lists only the options the answer endpoint accepts. Items use these SDK shapes, not the MCP elicitation JSON Schema form. Option pickers (pick_options requests) are not covered. This feature is enabled for selected organizations only.
curl 'https://api.factory.ai/api/v0/sessions/{sessionId}/elicitations' \
-H 'Authorization: Bearer $FACTORY_API_KEY'Parameters
Session ID
Responses
Permission prompts and AskUser questions the session is waiting on
Each item is one of
Allowed values
Values
Allowed values
Allowed values
Allowed values
Allowed values
Allowed values
Allowed values
Allowed values
Allowed values
Allowed values
Allowed values
Allowed values
Allowed values
Allowed values
Allowed values
Allowed values
Allowed values
Allowed values
Allowed values
Values
Allowed values
Allowed values
Allowed values
Allowed values
Allowed values
Allowed values
Allowed values
Allowed values
Allowed values
Allowed values
Allowed values
Allowed values
Allowed values
Allowed values
Allowed values
Allowed values
Allowed values
Allowed values
ID to answer the prompt with
Allowed values
ID to answer the questions with
400Response for status 400
Human-readable error message
HTTP status code
HTTP status title
Additional error metadata
Values
401Response for status 401
Human-readable error message
HTTP status code
HTTP status title
Additional error metadata
Values
402Response for status 402
Human-readable error message
HTTP status code
HTTP status title
Additional error metadata
Values
403Response for status 403
Human-readable error message
HTTP status code
HTTP status title
Additional error metadata
Values
404Response for status 404
Human-readable error message
HTTP status code
HTTP status title
Additional error metadata
Values
429Response for status 429
Human-readable error message
HTTP status code
HTTP status title
Additional error metadata
Values
500Response for status 500
Human-readable error message
HTTP status code
HTTP status title
Additional error metadata
Values
503Response for status 503
Human-readable error message
HTTP status code
HTTP status title
Additional error metadata
Values
504Response for status 504
Human-readable error message
HTTP status code
HTTP status title
Additional error metadata
Values
Answer a pending session elicitation
Answers one pending elicitation with the same result the SDK handlers return: `selectedOption` (one of the prompt's listed `options[].value`) for a permission prompt, or `answers` (exactly one per question, matched by index) or `cancelled: true` for AskUser questions. Persistent "always" options, `proceed_edit`, and `proceed_new_session*` are not listed or accepted. `comment` reaches the agent only when approving a spec; a `cancel` drops it, so send feedback with `POST /api/v0/sessions/{sessionId}/messages` after rejecting. 200 means the session applied this answer; for a permission prompt the response names the option it applied. Returns 409 when the elicitation is not pending: it was never a pending prompt of this session, another client answered it first, or its turn ended. Returns 503 when the session's computer runs a Droid version that cannot answer elicitations through this API. This feature is enabled for selected organizations only.
curl -X POST 'https://api.factory.ai/api/v0/sessions/{sessionId}/elicitations/{requestId}' \
-H 'Authorization: Bearer $FACTORY_API_KEY' \
-H 'Content-Type: application/json' \
-d '{ ... }'Parameters
Session ID
Pending elicitation ID
Request body
Dismiss an AskUser elicitation without answering
Allowed values
Answers to an AskUser elicitation: exactly one per question, matched by index
Allowed values
One of the permission elicitation's options[].value
Allowed values
Note passed to the agent when approving a spec. Rejections and other prompts drop it; after cancel, send feedback as a message
Responses
The answered elicitation ID
For a permission prompt, the option the session settled it with: the one this answer sent
Allowed values
400Response for status 400
Human-readable error message
HTTP status code
HTTP status title
Additional error metadata
Values
401Response for status 401
Human-readable error message
HTTP status code
HTTP status title
Additional error metadata
Values
402Response for status 402
Human-readable error message
HTTP status code
HTTP status title
Additional error metadata
Values
403Response for status 403
Human-readable error message
HTTP status code
HTTP status title
Additional error metadata
Values
404Response for status 404
Human-readable error message
HTTP status code
HTTP status title
Additional error metadata
Values
409Response for status 409
Human-readable error message
HTTP status code
HTTP status title
Additional error metadata
Values
429Response for status 429
Human-readable error message
HTTP status code
HTTP status title
Additional error metadata
Values
500Response for status 500
Human-readable error message
HTTP status code
HTTP status title
Additional error metadata
Values
503Response for status 503
Human-readable error message
HTTP status code
HTTP status title
Additional error metadata
Values
504Response for status 504
Human-readable error message
HTTP status code
HTTP status title
Additional error metadata
Values
Interrupt a session
Interrupts a running agent loop. Idempotent if already idle. This feature is enabled for selected organizations only.
curl -X POST 'https://api.factory.ai/api/v0/sessions/{sessionId}/interrupt' \
-H 'Authorization: Bearer $FACTORY_API_KEY'Parameters
Responses
Current session execution status
Allowed values
400Response for status 400
Human-readable error message
HTTP status code
HTTP status title
Additional error metadata
Values
401Response for status 401
Human-readable error message
HTTP status code
HTTP status title
Additional error metadata
Values
402Response for status 402
Human-readable error message
HTTP status code
HTTP status title
Additional error metadata
Values
403Response for status 403
Human-readable error message
HTTP status code
HTTP status title
Additional error metadata
Values
404Response for status 404
Human-readable error message
HTTP status code
HTTP status title
Additional error metadata
Values
429Response for status 429
Human-readable error message
HTTP status code
HTTP status title
Additional error metadata
Values
500Response for status 500
Human-readable error message
HTTP status code
HTTP status title
Additional error metadata
Values
503Response for status 503
Human-readable error message
HTTP status code
HTTP status title
Additional error metadata
Values
Get session messages
Returns paginated message history with optional role filtering. This feature is enabled for selected organizations only.
curl 'https://api.factory.ai/api/v0/sessions/{sessionId}/messages' \
-H 'Authorization: Bearer $FACTORY_API_KEY'Parameters
Maximum number of items to return (1-100)
Cursor for pagination
Computer ID to query directly
Filter messages by role
Allowed values
Responses
Allowed values
Each item is one of
Allowed values
Allowed values
Allowed values
Allowed values
Allowed values
Allowed values
Allowed values
Allowed values
Allowed values
Values
Allowed values
Each item is one of
Allowed values
Allowed values
Allowed values
Allowed values
Allowed values
Allowed values
Allowed values
Allowed values
Allowed values
Allowed values
Allowed values
Allowed values
Allowed values
Allowed values
Allowed values
Allowed values
Allowed values
Allowed values
Allowed values
Allowed values
Allowed values
Allowed values
@deprecated Use thinking block `signature` fields with `signatureProvider: "google"` instead. Do not use in new code.
Allowed values
Allowed values
Allowed values
Allowed values
Whether there are more items after this page
Cursor to use for the next page, null if no more pages
400Response for status 400
Human-readable error message
HTTP status code
HTTP status title
Additional error metadata
Values
401Response for status 401
Human-readable error message
HTTP status code
HTTP status title
Additional error metadata
Values
402Response for status 402
Human-readable error message
HTTP status code
HTTP status title
Additional error metadata
Values
403Response for status 403
Human-readable error message
HTTP status code
HTTP status title
Additional error metadata
Values
404Response for status 404
Human-readable error message
HTTP status code
HTTP status title
Additional error metadata
Values
429Response for status 429
Human-readable error message
HTTP status code
HTTP status title
Additional error metadata
Values
500Response for status 500
Human-readable error message
HTTP status code
HTTP status title
Additional error metadata
Values
503Response for status 503
Human-readable error message
HTTP status code
HTTP status title
Additional error metadata
Values
504Response for status 504
Human-readable error message
HTTP status code
HTTP status title
Additional error metadata
Values
Add a message to a session
Adds a user message and optionally waits for agent completion. Supports text, images, and file attachments. This feature is enabled for selected organizations only.
curl -X POST 'https://api.factory.ai/api/v0/sessions/{sessionId}/messages' \
-H 'Authorization: Bearer $FACTORY_API_KEY' \
-H 'Content-Type: application/json' \
-d '{ ... }'Parameters
Request body
Message text content
Optional base64-encoded images
Allowed values
Allowed values
Optional file attachments (PDFs, text files)
Each item is one of
Allowed values
Allowed values
Allowed values
Allowed values
Computer ID to route the message to; falls back to the session.computerId if omitted
The mission session sending this message (the orchestrator, or an agent by name), stored on the message so clients can attribute it and the model sees a [From …] header. Omit for human messages.
Allowed values
Allowed values
Responses
ID of the created user message
Agent status after message submission
Allowed values
The recipient's agent status before this message was submitted: idle means the message starts a turn now, running means it is queued behind the current turn. Omitted when the session was addressed by computerId.
Allowed values
400Response for status 400
Human-readable error message
HTTP status code
HTTP status title
Additional error metadata
Values
401Response for status 401
Human-readable error message
HTTP status code
HTTP status title
Additional error metadata
Values
402Response for status 402
Human-readable error message
HTTP status code
HTTP status title
Additional error metadata
Values
403Response for status 403
Human-readable error message
HTTP status code
HTTP status title
Additional error metadata
Values
404Response for status 404
Human-readable error message
HTTP status code
HTTP status title
Additional error metadata
Values
429Response for status 429
Human-readable error message
HTTP status code
HTTP status title
Additional error metadata
Values
500Response for status 500
Human-readable error message
HTTP status code
HTTP status title
Additional error metadata
Values
503Response for status 503
Human-readable error message
HTTP status code
HTTP status title
Additional error metadata
Values
504Response for status 504
Human-readable error message
HTTP status code
HTTP status title
Additional error metadata
Values
Get a message by ID
Returns a single message from the session by its ID. This feature is enabled for selected organizations only.
curl 'https://api.factory.ai/api/v0/sessions/{sessionId}/messages/{messageId}' \
-H 'Authorization: Bearer $FACTORY_API_KEY'Parameters
Session ID
Message ID
Computer ID to query directly
Responses
Allowed values
Each item is one of
Allowed values
Allowed values
Allowed values
Allowed values
Allowed values
Allowed values
Allowed values
Allowed values
Allowed values
Values
Allowed values
Each item is one of
Allowed values
Allowed values
Allowed values
Allowed values
Allowed values
Allowed values
Allowed values
Allowed values
Allowed values
Allowed values
Allowed values
Allowed values
Allowed values
Allowed values
Allowed values
Allowed values
Allowed values
Allowed values
Allowed values
Allowed values
Allowed values
Allowed values
@deprecated Use thinking block `signature` fields with `signatureProvider: "google"` instead. Do not use in new code.
Allowed values
Allowed values
Allowed values
Allowed values
400Response for status 400
Human-readable error message
HTTP status code
HTTP status title
Additional error metadata
Values
401Response for status 401
Human-readable error message
HTTP status code
HTTP status title
Additional error metadata
Values
402Response for status 402
Human-readable error message
HTTP status code
HTTP status title
Additional error metadata
Values
403Response for status 403
Human-readable error message
HTTP status code
HTTP status title
Additional error metadata
Values
404Response for status 404
Human-readable error message
HTTP status code
HTTP status title
Additional error metadata
Values
429Response for status 429
Human-readable error message
HTTP status code
HTTP status title
Additional error metadata
Values
500Response for status 500
Human-readable error message
HTTP status code
HTTP status title
Additional error metadata
Values
503Response for status 503
Human-readable error message
HTTP status code
HTTP status title
Additional error metadata
Values