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

# Créer une session

> Créer une nouvelle session

<div id="permissions">
  ## Autorisations
</div>

Nécessite un compte de service disposant de l’autorisation `ManageOrgSessions` au niveau de l’organisation.

<div id="additional-permissions-for-advanced-features">
  ### Autorisations supplémentaires pour les fonctions avancées
</div>

| Fonctionnalité      | Autorisation requise     |
| ------------------- | ------------------------ |
| `create_as_user_id` | `ImpersonateOrgSessions` |

<div id="devin-mode">
  ## Mode Devin
</div>

Le paramètre `devin_mode` détermine le mode d'agent Devin utilisé pour la session :

| Mode     | Description                                                                        |
| -------- | ---------------------------------------------------------------------------------- |
| `normal` | Le mode d'agent par défaut. Rapide et efficace pour la planification à long terme. |
| `fast`   | \~2x plus rapide, 4x plus cher, même intelligence.                                 |

S'il n'est pas renseigné, la session utilise le mode par défaut de l'organisation. Le mode rapide est soumis aux mêmes restrictions de feature flag et d'aperçu de l'agent Enterprise que l'application web.

<div id="user-impersonation">
  ## Usurpation d'identité d'un utilisateur
</div>

Le paramètre `create_as_user_id` permet de créer une session sur le compte d'un autre utilisateur. Cela nécessite :

1. Le compte de service doit disposer de l'autorisation `ImpersonateOrgSessions`
2. L'utilisateur cible doit être membre de l'organisation
3. L'utilisateur cible doit disposer de l'autorisation `UseDevinSessions`


## OpenAPI

````yaml fr/v3-openapi.yaml POST /v3/organizations/{org_id}/sessions
openapi: 3.1.0
info:
  description: API Devin v3 avec authentification par compte de service et RBAC
  title: Devin API v3
  version: 3.0.0
servers: []
security:
  - bearerAuth: []
paths:
  /v3/organizations/{org_id}/sessions:
    post:
      tags:
        - sessions
      summary: Créer une session
      description: Créer une nouvelle session
      operationId: handle_create_session_v3_organizations__org_id__sessions_post
      parameters:
        - description: 'ID de l’organisation (préfixe : 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: Réponse réussie
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Erreur de validation
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: >-
            Redéfinit le mode Agent de Devin pour la session. 'normal' utilise
            le mode Agent par défaut, 'fast' utilise le mode Fast, 'lite'
            utilise Devin Lite, 'ultra' utilise Devin Ultra et 'fusion' utilise
            Fusion. Les modes Preview sont soumis aux mêmes restrictions de flag
            de fonctionnalité et d’aperçu de l’agent Enterprise que
            l’application web.
          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: "Applique une dérogation à la plateforme de VM pour la session (p.\_ex. 'windows'). Si elle est omise (ou définie sur 'inherit'), une session créée par un Devin parent hérite de la plateforme du parent\_; sinon, la plateforme par défaut de l'organisation est utilisée. Toute valeur doit correspondre à une plateforme configurée pour votre organisation (sans distinction de casse)\_; les valeurs non reconnues sont rejetées avec une erreur 400 dont le corps liste les libellés de plateforme disponibles pour l'organisation."
          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: >-
            Indique s’il faut conserver l’état de la VM de la session après son
            arrêt afin de pouvoir reprendre la session. Définissez cette valeur
            sur false pour les sessions temporaires.
          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: >-
            Lorsque la valeur est true (par défaut), l’agent DOIT appeler
            provide_structured_output avec is_final=true avant la fin de son
            tour. Lorsque la valeur est false, l’outil est disponible mais non
            obligatoire — son appel n’est pas garanti pour un tour donné.
          title: Structured Output Required
        structured_output_schema:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          description: "JSON Schema (Draft 7) pour la validation de la sortie structurée. Taille maximale\_: 64\_Ko. Doit être autonome (aucune référence externe via $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: >-
            Catégorie de cas d’usage attribuée à la session, si la
            catégorisation a été effectuée. Renseigné uniquement sur les
            endpoints get/list.
          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: Origine depuis laquelle la session a été créée.
          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: >-
            Informations supplémentaires sur le statut actuel de la session.
            Lorsque status vaut 'running' : 'working' (travaille activement),
            'waiting_for_user' (nécessite une saisie de l’utilisateur),
            'waiting_for_approval' (en attente d’approbation d’une action en
            mode sécurisé) ou 'finished' (tâche terminée). Lorsque status vaut
            'suspended' : le motif de la suspension, par exemple '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' ou
            'error'. Renseigné uniquement sur les endpoints get/list.
          title: Status Detail
        structured_output:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          description: >-
            Sortie structurée validée provenant de la session. Renseignée
            uniquement sur les endpoints GET/list.
          title: Structured Output
        subcategory:
          anyOf:
            - type: string
            - type: 'null'
          description: >-
            Nom d’affichage de la sous-catégorie attribuée à la session. 'Other'
            lorsqu’une catégorie est définie, mais qu’aucune sous-catégorie n’a
            été attribuée ou résolue. Renseigné uniquement sur les endpoints
            get/list.
          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: Modèle d’entrée pour un secret de session fourni via l’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: "Identifiant de compte de service (préfixe\_: cog_)"
      scheme: bearer
      type: http

````