> ## Documentation Index
> Fetch the complete documentation index at: https://docs.devinenterprise.com/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
        '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
                - lite
                - ultra
                - fusion
              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. 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. 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
        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
                - 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
        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
    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
        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
    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
  securitySchemes:
    bearerAuth:
      description: 'Service User credential (prefix: cog_)'
      scheme: bearer
      type: http

````