Skip to navigation
API ReferenceV3

Create Session

Create a new session

Authentication

AuthorizationBearer

Personal API Key (apk_user_) or Service API Key (apk_)

Path parameters

org_idstringRequired

Organization ID (prefix: org-)

Query parameters

devin_idstring or nullOptional

Request

This endpoint expects an object.
promptstringRequired
The initial prompt or instructions for the Devin session.
attachment_urlslist of strings or nullOptional
Presigned URLs of files to attach to the session at creation.
bypass_approvalboolean or nullOptional

When true, skip safe-mode approval prompts for this session.

child_playbook_idstring or nullOptional
Playbook ID to run in child sessions spawned by this session.
create_as_user_idstring or nullOptional

Create the session on behalf of another user (requires enterprise admin).

devin_modeenum or nullOptional

Override the Devin agent mode for the session. 'normal' is the default agent mode (fast and good at long-horizon planning). 'fast' is ~2x faster, 4x more expensive, same intelligence. Fast mode is subject to the same feature flag and enterprise agent preview restrictions as the web app.

Allowed values:
knowledge_idslist of strings or nullOptional
IDs of knowledge notes to inject into the session context.
max_acu_limitinteger or nullOptional

Maximum ACU (AI Compute Unit) budget for this session.

platformstring or nullOptional

Override the VM platform for the session (e.g. 'windows'). When omitted (or set to 'inherit'), a session created by a parent Devin inherits the parent's platform; otherwise the organization default is used. Pass 'default' to force the organization default regardless of parent. Any other value must match a platform configured for your organization (case-insensitive); unrecognized values are rejected with a 400 whose error body lists the available platform labels for the org.

playbook_idstring or nullOptional

ID of a playbook to run when the session starts (prefix playbook-).

reposlist of strings or nullOptional
Repository URLs to clone into the session environment.
secret_idslist of strings or nullOptional
IDs of organization secrets to inject into the session.
session_secretslist of objects or nullOptional

Inline secrets (key-value pairs) to inject for this session only.

structured_output_requiredboolean or nullOptional

When true (default), the agent MUST call provide_structured_output with is_final=true before its turn ends. When false, the tool is available but not required — it is not guaranteed to be called in a given turn.

structured_output_schemamap from strings to any or nullOptional

JSON Schema (Draft 7) for validating structured output. Max 64KB. Must be self-contained (no external $ref).

tagslist of strings or nullOptional
Tags to apply to the session for filtering and organization.
titlestring or nullOptional

Optional human-readable title for the session.

Response

Successful Response
acus_consumeddouble
Total ACUs consumed by this session so far.
created_atinteger

Unix timestamp (seconds) when the session was created.

org_idstring

Organization that owns this session (prefix org-).

pull_requestslist of objects
Pull requests created by this session.
session_idstring

Unique session identifier (prefix devin-).

statusenum

Current lifecycle status: running, suspended, stopped, or blocked.

tagslist of strings
Tags applied to this session.
updated_atinteger

Unix timestamp (seconds) of the last session update.

urlstring
URL to view the session in the Devin web app.
categoryenum or nullOptional

The session's assigned use-case category, if categorisation has run. Only populated on get/list endpoints.

child_session_idslist of strings or nullOptional
Devin IDs of child sessions spawned by this session.
is_archivedbooleanOptionalDefaults to false
Whether the session has been archived.
originenum or nullOptional
The origin from which the session was created.
parent_session_idstring or nullOptional
Devin ID of the parent session, if this is a child session.
playbook_idstring or nullOptional
Playbook running in this session, if any.
service_user_idstring or nullOptional
Service user ID if the session was created via API key.
status_detailenum or nullOptional

Additional detail about the session's current status. When status is 'running': 'working' (actively working), 'waiting_for_user' (needs user input), 'waiting_for_approval' (awaiting action approval in safe mode), or 'finished' (task complete). When status is 'suspended': the reason for suspension such as 'inactivity', 'user_request', 'usage_limit_exceeded', 'out_of_credits', 'out_of_quota', 'no_quota_allocation', 'payment_declined', 'org_usage_limit_exceeded', 'total_session_limit_exceeded', or 'error'. Only populated on get/list endpoints.

structured_outputmap from strings to any or nullOptional

Validated structured output from the session. Only populated on get/list endpoints.

subcategorystring or nullOptional

The session's assigned subcategory display name. 'Other' when a category is set but no subcategory was assigned or resolved. Only populated on get/list endpoints.

titlestring or nullOptional

Human-readable session title.

user_idstring or nullOptional
ID of the user who created or owns the session.

Errors

422
Unprocessable Entity Error