> ## 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 with the `ManageOrgSessions` 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.              |

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


## 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
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
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
                - lite
                - ultra
              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,
            and 'ultra' uses Devin Ultra. Fast, Lite, and Ultra 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'). When
            omitted (or set to 'inherit'), a session created by a parent Devin
            inherits the parent's platform; otherwise the organization default
            is used. Any 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.
          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
        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
        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
                - 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
        is_archived:
          default: false
          title: Is Archived
          type: boolean
        org_id:
          title: Org Id
          type: string
        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
        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
                - total_session_limit_exceeded
                - 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', 'total_session_limit_exceeded', 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
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          title: Detail
          type: array
      title: HTTPValidationError
      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
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          title: Location
          type: array
        msg:
          title: Message
          type: string
        type:
          title: Error Type
          type: string
      required:
        - loc
        - msg
        - type
      title: ValidationError
      type: object
  securitySchemes:
    bearerAuth:
      description: 'Service User credential (prefix: cog_)'
      scheme: bearer
      type: http

````