Skip to main content
POST
/
v3
/
organizations
/
{org_id}
/
sessions
Create Session
curl --request POST \
  --url https://api.devin.ai/v3/organizations/{org_id}/sessions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "prompt": "<string>",
  "attachment_urls": [
    "<string>"
  ],
  "bypass_approval": true,
  "child_playbook_id": "<string>",
  "create_as_user_id": "<string>",
  "knowledge_ids": [
    "<string>"
  ],
  "max_acu_limit": 123,
  "platform": "<string>",
  "playbook_id": "<string>",
  "repos": [
    "<string>"
  ],
  "secret_ids": [
    "<string>"
  ],
  "session_links": [
    "<string>"
  ],
  "session_secrets": [
    {
      "key": "<string>",
      "value": "<string>",
      "sensitive": true
    }
  ],
  "structured_output_required": true,
  "structured_output_schema": {},
  "tags": [
    "<string>"
  ],
  "title": "<string>"
}
'
{
  "acus_consumed": 123,
  "created_at": 123,
  "org_id": "<string>",
  "pull_requests": [
    {
      "pr_state": "<string>",
      "pr_url": "<string>"
    }
  ],
  "session_id": "<string>",
  "tags": [
    "<string>"
  ],
  "updated_at": 123,
  "url": "<string>",
  "child_session_ids": [
    "<string>"
  ],
  "is_archived": false,
  "parent_session_id": "<string>",
  "playbook_id": "<string>",
  "service_user_id": "<string>",
  "structured_output": {},
  "subcategory": "<string>",
  "title": "<string>",
  "user_id": "<string>"
}

Documentation Index

Fetch the complete documentation index at: https://docs.devin.ai/llms.txt

Use this file to discover all available pages before exploring further.

​
Permissions

Requires a service user with the ManageOrgSessions permission at the organization level.

​
Additional permissions for advanced features

FeatureRequired Permission
create_as_user_idImpersonateOrgSessions

​
Devin mode

The devin_mode parameter controls which Devin agent mode is used for the session:
ModeDescription
normalThe default agent mode. Fast and good at long-horizon planning.
fast~2x faster, 4x more expensive, same intelligence.
When omitted, the session uses the organization’s default mode. Fast mode is subject to the same feature flag and enterprise agent preview restrictions as the web app.

​
User impersonation

The create_as_user_id parameter allows creating a session on behalf of another user. This requires:
  1. The service user must have ImpersonateOrgSessions permission
  2. The target user must be a member of the organization
  3. The target user must have UseDevinSessions permission

Authorizations

​
Authorization
string
header
required

Service User credential (prefix: cog_)

Path Parameters

​
org_id
string | null
required

Organization ID (prefix: org-)

Example:

"org-abc123def456"

Query Parameters

​
devin_id
string | null

Body

application/json
​
prompt
string
required
​
attachment_urls
string<uri>[] | null
Required string length: 1 - 2083
​
bypass_approval
boolean | null
​
child_playbook_id
string | null
​
create_as_user_id
string | null
​
devin_mode
enum<string> | null

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.

Available options:
normal,
fast
​
knowledge_ids
string[] | null
​
max_acu_limit
integer | null
​
platform
string | null

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_id
string | null
​
repos
string[] | null
​
secret_ids
string[] | null
​
session_links
string[] | null
​
session_secrets
SessionSecretInput · object[] | null
​
structured_output_required
boolean | null

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_schema
Structured Output Schema · object

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

​
tags
string[] | null
​
title
string | null

Response

Successful Response

​
acus_consumed
number
required
​
created_at
integer
required
​
org_id
string
required
​
pull_requests
SessionPullRequest · object[]
required
​
session_id
string
required
​
status
enum<string>
required
Available options:
new,
claimed,
running,
exit,
error,
suspended,
resuming
​
tags
string[]
required
​
updated_at
integer
required
​
url
string
required
​
category
enum<string> | null

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

Available options:
bug_fixing,
ci_cd_and_devops,
code_quality_and_security,
code_review_and_analysis,
data_and_automation,
documentation_and_content,
feature_development,
migrations_and_upgrades,
other,
refactoring_and_optimization,
research_and_exploration,
unit_test_generation
​
child_session_ids
string[] | null
​
is_archived
boolean
default:false
​
origin
enum<string> | null

The origin from which the session was created.

Available options:
webapp,
slack,
teams,
api,
linear,
jira,
automation,
cli,
desktop,
other
​
parent_session_id
string | null
​
playbook_id
string | null
​
service_user_id
string | null
​
status_detail
enum<string> | null

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.

Available options:
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
​
structured_output
Structured Output · object

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

​
subcategory
string | null

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.

​
title
string | null
​
user_id
string | null