> ## 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.

# Create Session

> Create a new session

## Permissions

Requires a [service user](/api-reference/v3/service-users/members-service-users) or [personal access token](/api-reference/personal-access-tokens) with the `UseDevinSessions` (`org.devins.use`) permission at the organization level.

### Additional permissions for advanced features

| Feature | Required Permission |
| - | - |
| `create_as_user_id` | `ImpersonateOrgSessions` |

## Devin mode

The `devin_mode` parameter controls which Devin agent mode is used for the session:

| Mode | Description |
| - | - |
| `normal` | The default agent mode. Fast and good at long-horizon planning. |
| `fast` | \~2x faster, 4x more expensive, same intelligence. |
| `lite` | Devin Lite — a lighter, lower-cost mode for smaller-scope sessions. |
| `ultra` | Devin Ultra — the most capable mode. |
| `fusion` | Fusion — multi-model routing. |

When omitted, the session uses the organization's default mode. Preview modes are 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


## OpenAPI

````yaml v3-openapi.yaml POST /v3/organizations/{org_id}/sessions
openapi: 3.1.0
info:
  description: Devin v3 API with Service User authentication and RBAC
  title: Devin API v3
  version: 3.0.0
servers: []
security:
  - bearerAuth: []
paths:
  /v3/organizations/{org_id}/sessions:
    post:
      tags:
        - sessions
      summary: Create Session
      description: Create a new session
      operationId: handle_create_session_v3_organizations__org_id__sessions_post
      parameters:
        - description: 'Organization ID (prefix: org-)'
          in: path
          name: org_id
          required: true
          schema:
            anyOf:
              - type: string
              - type: 'null'
            example: org-abc123def456
            title: Org Id
        - in: query
          name: devin_id
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            title: Devin Id
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SessionCreateRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SessionResponse'
          description: Successful Response
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetail'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetail'
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetail'
          description: Not Found
        '409':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetail'
          description: Conflict
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetail'
          description: Unprocessable Content
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetail'
          description: Too Many Requests
components:
  schemas:
    SessionCreateRequest:
      properties:
        attachment_urls:
          anyOf:
            - items:
                format: uri
                maxLength: 2083
                minLength: 1
                type: string
              type: array
            - type: 'null'
          title: Attachment Urls
        bypass_approval:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Bypass Approval
        child_playbook_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Child Playbook Id
        create_as_user_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Create As User Id
        devin_mode:
          anyOf:
            - enum:
                - normal
                - fast
                - fusion
                - lite
                - ultra
                - swe-2-medium
                - swe-2-high
                - swe-2-max
              type: string
            - type: 'null'
          description: >-
            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. The other values
            select the agent mode of the same name in the web app. Preview modes
            are subject to the same feature flag and enterprise agent preview
            restrictions as the web app.
          title: Devin Mode
        knowledge_ids:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Knowledge Ids
        max_acu_limit:
          anyOf:
            - type: integer
            - type: 'null'
          title: Max Acu Limit
        platform:
          anyOf:
            - type: string
            - type: 'null'
          description: >-
            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, and a personal outpost pool owned
            by the caller takes priority over an account-wide pool with the same
            name. Unrecognized values are rejected with a 400 whose error body
            lists the available platform labels and outpost pool names for the
            org.
          title: Platform
        playbook_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Playbook Id
        prompt:
          title: Prompt
          type: string
        repos:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Repos
        resumable:
          default: true
          description: >-
            Whether to preserve the session's VM state after it stops so the
            session can be resumed. Set to false for disposable sessions.
          title: Resumable
          type: boolean
        secret_ids:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Secret Ids
        security_profile:
          anyOf:
            - $ref: '#/components/schemas/SessionSecurityProfileSelection'
            - type: 'null'
          description: >-
            Attach a security profile to this session; omitted = default
            resolution applies (the playbook's security profile when one is
            bound, then the org/enterprise default). Requires the
            security-profile management permission.
        session_links:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Session Links
        session_secrets:
          anyOf:
            - items:
                $ref: '#/components/schemas/SessionSecretInput'
              type: array
            - type: 'null'
          title: Session Secrets
        structured_output_required:
          anyOf:
            - type: boolean
            - type: 'null'
          description: >-
            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.
          title: Structured Output Required
        structured_output_schema:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          description: >-
            JSON Schema (Draft 7) for validating structured output. Max 64KB.
            Must be self-contained (no external $ref).
          title: Structured Output Schema
        tags:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Tags
        title:
          anyOf:
            - type: string
            - type: 'null'
          title: Title
      required:
        - prompt
      title: SessionCreateRequest
      type: object
    SessionResponse:
      properties:
        acus_consumed:
          title: Acus Consumed
          type: number
        automation_id:
          anyOf:
            - type: string
            - type: 'null'
          description: ID of the automation that created this session, if any.
          title: Automation Id
        category:
          anyOf:
            - enum:
                - 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
              type: string
            - type: 'null'
          description: >-
            The session's assigned use-case category, if categorisation has run.
            Only populated on get/list endpoints.
          title: Category
        child_session_ids:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Child Session Ids
        created_at:
          title: Created At
          type: integer
        devin_mode:
          anyOf:
            - enum:
                - normal
                - fast
                - fusion
                - lite
                - ultra
                - swe-2-medium
                - swe-2-high
                - swe-2-max
              type: string
            - type: 'null'
          description: >-
            The Devin agent mode the session was created with, after resolving
            org/user defaults and parent-session inheritance. None when the
            session runs an agent preview that has no mode equivalent.
          title: Devin Mode
        is_archived:
          default: false
          title: Is Archived
          type: boolean
        on_demand_usage:
          anyOf:
            - type: number
            - type: 'null'
          description: >-
            On-demand (overage) spend in USD for this session, excluding child
            sessions. Only populated for Teams plans; 0 when the session was
            fully covered by quota. Omitted for other plans. Only populated on
            get/list endpoints.
          title: On Demand Usage
        org_id:
          anyOf:
            - type: string
            - type: 'null'
          description: >-
            Owning organization. Null for detached sessions, which are owned by
            their creator's account rather than an organization.
          title: Org Id
        origin:
          anyOf:
            - enum:
                - webapp
                - slack
                - teams
                - api
                - linear
                - jira
                - automation
                - cli
                - desktop
                - code_scan
                - other
              type: string
            - type: 'null'
          description: The origin from which the session was created.
          title: Origin
        parent_session_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Parent Session Id
        playbook_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Playbook Id
        pull_requests:
          items:
            $ref: '#/components/schemas/SessionPullRequest'
          title: Pull Requests
          type: array
        security_profile:
          anyOf:
            - $ref: '#/components/schemas/SessionSecurityProfileResponse'
            - type: 'null'
          description: >-
            The session's own security-profile binding. Only populated on
            get/list endpoints.
        service_user_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Service User Id
        session_id:
          title: Session Id
          type: string
        status:
          enum:
            - new
            - claimed
            - running
            - exit
            - error
            - suspended
            - resuming
          title: Status
          type: string
        status_detail:
          anyOf:
            - enum:
                - 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
                - user_usage_limit_exceeded
                - total_session_limit_exceeded
                - contract_expired
                - error
              type: string
            - type: 'null'
          description: >-
            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', 'user_usage_limit_exceeded',
            'total_session_limit_exceeded', 'contract_expired', or 'error'. Only
            populated on get/list endpoints.
          title: Status Detail
        structured_output:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          description: >-
            Validated structured output from the session. Only populated on
            get/list endpoints.
          title: Structured Output
        subcategory:
          anyOf:
            - type: string
            - type: 'null'
          description: >-
            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: Subcategory
        tags:
          items:
            type: string
          title: Tags
          type: array
        title:
          anyOf:
            - type: string
            - type: 'null'
          title: Title
        updated_at:
          title: Updated At
          type: integer
        url:
          title: Url
          type: string
        user_id:
          anyOf:
            - type: string
            - type: 'null'
          title: User Id
      required:
        - session_id
        - url
        - status
        - tags
        - org_id
        - created_at
        - updated_at
        - acus_consumed
        - pull_requests
      title: SessionResponse
      type: object
    ProblemDetail:
      description: >-
        RFC 9457 application/problem+json error body for the v3 API.


        detail is retained from the legacy {"detail": ...} body for back-compat;
        the

        other members are additive. errors carries field-level validation
        failures

        (422 only).
      properties:
        detail:
          anyOf:
            - type: string
            - type: 'null'
          description: A human-readable explanation specific to this occurrence.
          title: Detail
        error_code:
          anyOf:
            - type: string
            - type: 'null'
          description: >-
            Machine-readable code for blocked-action refusals (e.g.
            "user_frozen", "migrated_session").
          title: Error Code
        errors:
          anyOf:
            - items:
                additionalProperties: true
                type: object
              type: array
            - type: 'null'
          description: Field-level validation errors (422 responses only).
          title: Errors
        instance:
          anyOf:
            - type: string
            - type: 'null'
          description: A URI reference (the request path) for this occurrence.
          title: Instance
        status:
          description: The HTTP status code.
          title: Status
          type: integer
        title:
          description: A short, human-readable summary of the problem type.
          title: Title
          type: string
        type:
          default: about:blank
          description: A URI reference identifying the problem type.
          title: Type
          type: string
      required:
        - title
        - status
      title: ProblemDetail
      type: object
    SessionSecurityProfileSelection:
      description: An explicit security-profile selection for a new session.
      properties:
        profile_id:
          anyOf:
            - minLength: 1
              type: string
            - type: 'null'
          description: >-
            Security profile to attach to the session; must belong to your
            organization or, for enterprise organizations, its enterprise. null
            records an explicit opt-out (no profile, even when the org or
            enterprise has a default).
          title: Profile Id
      title: SessionSecurityProfileSelection
      type: object
    SessionSecretInput:
      description: Input model for a session secret provided via API.
      properties:
        key:
          maxLength: 256
          minLength: 1
          title: Key
          type: string
        sensitive:
          default: true
          title: Sensitive
          type: boolean
        value:
          maxLength: 65536
          title: Value
          type: string
      required:
        - key
        - value
      title: SessionSecretInput
      type: object
    SessionPullRequest:
      properties:
        pr_state:
          anyOf:
            - type: string
            - type: 'null'
          title: Pr State
        pr_url:
          title: Pr Url
          type: string
      required:
        - pr_url
        - pr_state
      title: SessionPullRequest
      type: object
    SessionSecurityProfileResponse:
      properties:
        profile_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Profile Id
        selection:
          description: >-
            The session's own binding: inherit (no binding of its own), none
            (explicit opt-out), or profile (pins profile_id). The effective
            configuration resolves the full governing chain (enterprise -> org
            -> automation/playbook -> session); an opt-out cannot escape a
            mandatory org/enterprise profile.
          enum:
            - inherit
            - none
            - profile
          title: Selection
          type: string
      required:
        - selection
      title: SessionSecurityProfileResponse
      type: object
  securitySchemes:
    bearerAuth:
      description: 'Service User credential (prefix: cog_)'
      scheme: bearer
      type: http

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.