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

# Crear una sesión

> Crea una nueva sesión.

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

Requiere un usuario de servicio con el permiso `ManageOrgSessions` a nivel de la organización.

<div id="additional-permissions-for-advanced-features">
  ### Permisos adicionales para características avanzadas
</div>

| Funcionalidad       | Permiso requerido        |
| ------------------- | ------------------------ |
| `create_as_user_id` | `ImpersonateOrgSessions` |

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

El parámetro `devin_mode` controla qué modo Agent de Devin se usa en la sesión:

| Modo     | Descripción                                                                       |
| -------- | --------------------------------------------------------------------------------- |
| `normal` | El modo Agent predeterminado. Rápido y bueno para la planificación a largo plazo. |
| `fast`   | \~2x más rápido, 4x más caro, misma inteligencia.                                 |

Si se omite, la sesión usa el modo predeterminado de la organización. El modo rápido está sujeto a las mismas restricciones de feature flag y de vista previa del agente de Enterprise que la aplicación web.

<div id="user-impersonation">
  ## Suplantación de usuario
</div>

El parámetro `create_as_user_id` permite crear una sesión en nombre de otro usuario. Esto requiere:

1. El usuario de servicio debe tener el permiso `ImpersonateOrgSessions`
2. El usuario objetivo debe ser miembro de la organización
3. El usuario objetivo debe tener el permiso `UseDevinSessions`


## OpenAPI

````yaml es/v3-openapi.yaml POST /v3/organizations/{org_id}/sessions
openapi: 3.1.0
info:
  description: API de Devin v3 con autenticación mediante usuario de servicio y RBAC
  title: Devin API v3
  version: 3.0.0
servers: []
security:
  - bearerAuth: []
paths:
  /v3/organizations/{org_id}/sessions:
    post:
      tags:
        - sessions
      summary: Crear una sesión
      description: Crea una nueva sesión.
      operationId: handle_create_session_v3_organizations__org_id__sessions_post
      parameters:
        - description: 'ID de la organización (prefijo: 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: Respuesta correcta
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Error de validación
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: >-
            Anula el modo Agent de Devin para la sesión. 'normal' usa el modo
            Agent predeterminado, 'fast' usa el modo Fast, 'lite' usa Devin
            Lite, 'ultra' usa Devin Ultra y 'fusion' usa Fusion. Los modos
            Preview están sujetos a la misma flag de función y a las mismas
            restricciones de vista previa del agente de Enterprise que la
            aplicación 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: >-
            Anula la plataforma de VM para la sesión (p. ej., 'windows'). Si se
            omite (o se establece en 'inherit'), una sesión creada por un Devin
            principal hereda la plataforma del principal; de lo contrario, se
            usa la plataforma predeterminada de la organización. Cualquier valor
            debe coincidir con una plataforma configurada para tu organización
            (sin distinguir mayúsculas de minúsculas); los valores no
            reconocidos se rechazan con un 400 cuyo cuerpo de error enumera las
            etiquetas de plataforma disponibles para la organización.
          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: >-
            Indica si se debe conservar el estado de la VM de la sesión después
            de detenerse para que pueda reanudarse. Establece el valor en false
            para sesiones desechables.
          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: >-
            Cuando es true (predeterminado), el agente DEBE llamar a
            provide_structured_output con is_final=true antes de que finalice su
            turno. Cuando es false, la herramienta está disponible, pero no es
            obligatorio usarla; no se garantiza que se llame en un turno
            determinado.
          title: Structured Output Required
        structured_output_schema:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          description: >-
            Esquema JSON (Draft 7) para validar la salida estructurada. Máx. 64
            KB. Debe ser autocontenido (sin $ref externos).
          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: >-
            La categoría de caso de uso asignada a la sesión, si se ha ejecutado
            la categorización. Solo se rellena en los 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: El origen desde el que se creó la sesión.
          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: >-
            Detalle adicional sobre el estado actual de la sesión. Cuando status
            es 'running': 'working' (trabajando activamente), 'waiting_for_user'
            (requiere intervención del usuario), 'waiting_for_approval' (a la
            espera de aprobación de la acción en modo seguro) o 'finished'
            (tarea completada). Cuando status es 'suspended': el motivo de la
            suspensión, como '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' o
            'error'. Solo se rellena en los endpoints GET/list.
          title: Status Detail
        structured_output:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          description: >-
            Salida estructurada validada de la sesión. Solo se incluye en
            endpoints GET/LIST.
          title: Structured Output
        subcategory:
          anyOf:
            - type: string
            - type: 'null'
          description: >-
            El nombre para mostrar de la subcategoría asignada a la sesión.
            'Other' cuando se establece una categoría, pero no se asignó ni se
            resolvió ninguna subcategoría. Solo se rellena en los 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: Modelo de entrada de un secreto de sesión proporcionado mediante la 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: 'Credencial de usuario de servicio (prefijo: cog_)'
      scheme: bearer
      type: http

````