Sign in

v1

latestOpenAPI 3.1.02026-07-26269227514.8 KB
sessions

Create Session

Create a new session

post/v3/organizations/{org_id}/sessions

Path parameters

org_idstring nullable required
Example:org-abc123def456

Organization ID (prefix: org-)

Query parameters

devin_idstring nullable

Request body

attachment_urlsstring[] nullable
bypass_approvalboolean nullable
child_playbook_idstring nullable
create_as_user_idstring nullable
devin_mode'normal' | 'fast' | 'lite' | 'ultra' | 'fusion' nullable

Override the Devin agent mode for the session. 'normal' uses the default Agent mode, 'fast' uses Fast mode, 'lite' uses Devin Lite, 'ultra' uses Devin Ultra, and 'fusion' uses Fusion. Preview modes are subject to the same feature flag and enterprise agent preview restrictions as the web app.

knowledge_idsstring[] nullable
max_acu_limitinteger nullable
platformstring nullable

Override the VM platform for the session (e.g. 'windows'), or the name of an outpost (BYOB) pool to run the session on one of your own machines. When omitted (or set to 'inherit'), a session created by a parent Devin inherits the parent's placement — both its platform and its outpost pool, so an outpost-placed parent spawns children on the same pool; otherwise the organization default is used. Any value must match either a platform configured for your organization or an outpost pool name (case-insensitive) — built-in platforms take priority when a name matches both. Unrecognized values are rejected with a 400 whose error body lists the available platform labels and outpost pool names for the org.

playbook_idstring nullable
promptstring required
reposstring[] nullable
resumableboolean

Whether to preserve the session's VM state after it stops so the session can be resumed. Set to false for disposable sessions.

secret_idsstring[] nullable
session_linksstring[] nullable
structured_output_requiredboolean nullable

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_schemaobject nullable

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

tagsstring[] nullable
titlestring nullable

Response

Successful Response

acus_consumednumber required
category'bug_fixing' | 'ci_cd_and_devops' | 'code_quality_and_security' | 'code_review' | 'code_review_and_analysis' | 'data_and_automation' | 'documentation_and_content' | 'feature_development' | 'migrations_and_upgrades' | 'other' | 'production_investigation' | 'refactoring_and_optimization' | 'research_and_exploration' | 'security' | 'unit_test_generation' nullable

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

child_session_idsstring[] nullable
created_atinteger required
is_archivedboolean
org_idstring required
origin'webapp' | 'slack' | 'teams' | 'api' | 'linear' | 'jira' | 'automation' | 'cli' | 'desktop' | 'code_scan' | 'other' nullable

The origin from which the session was created.

parent_session_idstring nullable
playbook_idstring nullable
service_user_idstring nullable
session_idstring required
status'new' | 'claimed' | 'running' | 'exit' | 'error' | 'suspended' | 'resuming' required
status_detail'working' | 'waiting_for_user' | 'waiting_for_approval' | 'finished' | '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' | 'error' nullable

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_outputobject nullable

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

subcategorystring nullable

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.

tagsstring[] required
titlestring nullable
updated_atinteger required
urlstring required
user_idstring nullable