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
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
Values
Allowed values
Allowed values
Pattern: ^custom:.+$
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
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
Values
Allowed values
Allowed values
Pattern: ^custom:.+$
Responses
Session ID
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
Values
Allowed values
Allowed values
Pattern: ^custom:.+$
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
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
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
Values
Allowed values
Allowed values
Pattern: ^custom:.+$
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
Soft-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
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
Values
Allowed values
Allowed values
Pattern: ^custom:.+$
Responses
Session ID
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
Values
Allowed values
Allowed values
Pattern: ^custom:.+$
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
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
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
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
@deprecated Use thinking block `signature` fields with `signatureProvider: "google"` instead. Do not use in new code.
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
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
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
Responses
ID of the created user message
Agent status after message submission
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
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
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
@deprecated Use thinking block `signature` fields with `signatureProvider: "google"` instead. Do not use in new code.
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
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