> ## Documentation Index
> Fetch the complete documentation index at: https://docs.omegas.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Create device

> Create + provision an Operator device. Runs the write gate (scope + entitlement), resolves the
target Space (org-wide key: `space_id` required + Space check; Space-scoped key: its held Space),
enforces the device-count and rolling-duration quotas, provisions the device sprite, and returns
the active device (201). `Idempotency-Key` replays a prior success and 409s a reused key + a
different body.



## OpenAPI

````yaml /schemas/operator.json post /v1/devices
openapi: 3.1.0
info:
  title: Omegas Operator API
  version: 0.1.0
  description: >-
    The public /v1 machine surface: cloud browser devices, tasks, live-view
    sessions, escalations, usage, webhook endpoints, and the audit trail.
    Generated from the same OpenAPI document the Rust API is checked against.
servers:
  - url: https://api.omegas.dev
    description: Production
security: []
paths:
  /v1/devices:
    post:
      tags:
        - Endpoints
      summary: Create device
      description: >-
        Create + provision an Operator device. Runs the write gate (scope +
        entitlement), resolves the

        target Space (org-wide key: `space_id` required + Space check;
        Space-scoped key: its held Space),

        enforces the device-count and rolling-duration quotas, provisions the
        device sprite, and returns

        the active device (201). `Idempotency-Key` replays a prior success and
        409s a reused key + a

        different body.
      operationId: create_device
      parameters:
        - name: Idempotency-Key
          in: header
          description: At-most-once key for the create
          required: false
          schema:
            type:
              - string
              - 'null'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateDeviceBody'
        required: true
      responses:
        '201':
          description: The provisioned device
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Device'
        '400':
          description: space_id_required or invalid input
        '401':
          description: invalid_api_key
        '403':
          description: insufficient_scope or product_not_entitled
        '409':
          description: idempotency_conflict
        '429':
          description: quota_exceeded or rate_limited
        '502':
          description: provider_error
        '503':
          description: browser_unavailable
      security:
        - bearer_operator: []
components:
  schemas:
    CreateDeviceBody:
      type: object
      description: >-
        The create-device request body. Every field is optional; an org-wide key
        MUST carry `space_id`,

        a Space-scoped key holding exactly one Space may omit it.
      properties:
        idle_suspend_secs:
          type:
            - integer
            - 'null'
          format: int32
          description: >-
            Per-device idle-suspend threshold in seconds; `null` uses the
            deployment default.
        name:
          type:
            - string
            - 'null'
          description: Human label; defaults to a generated `operator-device` name.
        region:
          type:
            - string
            - 'null'
          description: Sprite region; defaults to `ord`.
        space_id:
          type:
            - string
            - 'null'
          description: Raw uuid of the target Space.
    Device:
      type: object
      description: >-
        A device as returned on the `/v1` surface. `id`/`current_task_id` carry
        the `dev_`/`task_` prefixes

        (the bare uuids never leave the DB); `space_id` is a raw uuid (Spaces
        are not an Operator concept).
      required:
        - id
        - object
        - name
        - status
        - region
        - space_id
        - created_at
      properties:
        created_at:
          type: string
        current_task_id:
          type:
            - string
            - 'null'
          description: >-
            `task_<uuid>` of the task currently holding the device, or `null`
            when idle.
        id:
          type: string
          description: '`dev_<uuid>`.'
        last_active_at:
          type:
            - string
            - 'null'
        name:
          type: string
        object:
          type: string
          description: Discriminator for polymorphic SDK decoders. Always `"device"`.
        region:
          type: string
        space_id:
          type: string
        status:
          type: string
  securitySchemes:
    bearer_operator:
      type: http
      scheme: bearer
      bearerFormat: Opaque

````