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

# Update project machine pool grant

> Updates the grant's overrides and limits. Omitted fields keep their current values; null clears an override so the grant follows the machine pool again. Overlay objects and metadata are replaced whole when present. Existing machines keep their configuration; the updated defaults and limits apply to new launches.



## OpenAPI

````yaml /api-reference/openapi.yaml patch /orgs/{orgID}/projects/{projectID}/machine-pool-grants/{poolGrantID}
openapi: 3.1.2
info:
  title: Omnara API
  version: 0.1.0
  description: Public HTTP API contract for Omnara.
servers:
  - url: https://api.omnara.com/v1
    description: Hosted Omnara
security:
  - bearerAuth: []
  - browserSessionCookie: []
tags:
  - name: Agents
    description: >-
      Launch agents, send inputs, manage the input backlog, and work with tool
      calls.
    externalDocs:
      description: Guide
      url: https://docs.omnara.com/agents/overview
  - name: Interactions
    description: List and resolve the approvals and questions that pause an agent.
    externalDocs:
      description: Guide
      url: https://docs.omnara.com/events/interactions
  - name: Actors
    description: Attribute agent inputs and interaction responses to external users.
    externalDocs:
      description: Guide
      url: >-
        https://docs.omnara.com/events/sending-input#who-said-that-actors-and-attribution
  - name: Events
    description: Read or stream the agent timeline, list turns, and download artifacts.
    externalDocs:
      description: Guide
      url: https://docs.omnara.com/events/streaming
  - name: Configs and Profiles
    description: >-
      Create agent configs, manage reusable launch profiles, and set up
      integrations.
    externalDocs:
      description: Guide
      url: https://docs.omnara.com/agents/configuration
  - name: Models
    description: Configure model providers and models, and grant projects access to them.
    externalDocs:
      description: Guide
      url: https://docs.omnara.com/organization/model-providers
  - name: Machines
    description: Register machines, control project access, and manage daemon tokens.
    externalDocs:
      description: Guide
      url: https://docs.omnara.com/machines/connect
  - name: Machine Pools
    description: Define machine pools and grant projects access to them.
    externalDocs:
      description: Guide
      url: https://docs.omnara.com/machines/pools
  - name: Secrets
    description: >-
      Manage secret ownership and versions, and inspect or grant project
      availability.
    externalDocs:
      description: Guide
      url: https://docs.omnara.com/organization/secrets
  - name: Skills
    description: Manage versioned skill ownership and load skill instructions on demand.
    externalDocs:
      description: Guide
      url: https://docs.omnara.com/tools/skills
  - name: Organizations and Projects
    description: Create organizations and projects and manage membership.
    externalDocs:
      description: Guide
      url: https://docs.omnara.com/organization/members
  - name: Users and API Keys
    description: >-
      The authenticated user, personal and organization API keys, and
      invitations.
    externalDocs:
      description: Guide
      url: https://docs.omnara.com/api/authentication
  - name: Machine Daemon
    description: Routes the Omnara machine daemon uses to connect a machine.
paths:
  /orgs/{orgID}/projects/{projectID}/machine-pool-grants/{poolGrantID}:
    parameters:
      - name: orgID
        in: path
        required: true
        schema:
          type: string
          pattern: ^org_[a-z2-7]{26}$
      - name: projectID
        in: path
        required: true
        schema:
          type: string
          pattern: ^proj_[a-z2-7]{26}$
      - name: poolGrantID
        in: path
        required: true
        schema:
          type: string
          pattern: ^pmpg_[a-z2-7]{26}$
    patch:
      tags:
        - Machine Pools
      summary: Update project machine pool grant
      description: >-
        Updates the grant's overrides and limits. Omitted fields keep their
        current values; null clears an override so the grant follows the machine
        pool again. Overlay objects and metadata are replaced whole when
        present. Existing machines keep their configuration; the updated
        defaults and limits apply to new launches.
      operationId: updateProjectMachinePoolGrant
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateProjectMachinePoolGrantRequest'
      responses:
        '200':
          description: Project machine pool grant updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProjectMachinePoolGrant'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
        4XX:
          $ref: '#/components/responses/ClientError'
        5XX:
          $ref: '#/components/responses/ServerError'
      security:
        - bearerAuth: []
        - browserSessionCookie: []
          csrfHeader: []
components:
  schemas:
    UpdateProjectMachinePoolGrantRequest:
      type: object
      description: >-
        Update a project machine pool grant. Omitted fields keep their current
        values. Null clears an override so the grant follows the machine pool
        again. Overlay objects and metadata are replaced whole when present;
        send an empty object to clear them.
      additionalProperties: false
      minProperties: 1
      properties:
        description:
          type: string
        default_machine_cpu:
          type:
            - integer
            - 'null'
          format: int32
          minimum: 1
          maximum: 2147483647
        default_machine_memory_mb:
          type:
            - integer
            - 'null'
          format: int32
          minimum: 1
          maximum: 2147483647
        default_machine_env_overlay:
          type: object
          additionalProperties:
            type:
              - string
              - 'null'
        default_machine_secret_env_overlay:
          type: object
          additionalProperties:
            type:
              - string
              - 'null'
            pattern: ^sec_[a-z2-7]{26}$
        default_machine_provider_options_overlay:
          type: object
          additionalProperties: true
        default_cwd:
          type: string
        max_total_machines:
          type:
            - integer
            - 'null'
          format: int32
          minimum: 0
          maximum: 2147483647
        max_total_cpu:
          type:
            - integer
            - 'null'
          format: int32
          minimum: 0
          maximum: 2147483647
        max_total_memory_mb:
          type:
            - integer
            - 'null'
          format: int32
          minimum: 0
          maximum: 2147483647
        min_machine_cpu:
          type:
            - integer
            - 'null'
          format: int32
          minimum: 0
          maximum: 2147483647
        min_machine_memory_mb:
          type:
            - integer
            - 'null'
          format: int32
          minimum: 0
          maximum: 2147483647
        max_machine_cpu:
          type:
            - integer
            - 'null'
          format: int32
          minimum: 1
          maximum: 2147483647
        max_machine_memory_mb:
          type:
            - integer
            - 'null'
          format: int32
          minimum: 1
          maximum: 2147483647
        delete_after_idle_minutes:
          description: >-
            Idle minutes before deleting a machine created through this grant.
            Use 0 to disable for this grant; null restores inheritance from the
            pool; omitted leaves it unchanged. Values from 1 through 4 are
            invalid.
          type:
            - integer
            - 'null'
          format: int32
          minimum: 0
          maximum: 2147483647
          oneOf:
            - const: 0
            - type: integer
              minimum: 5
              maximum: 2147483647
            - type: 'null'
        metadata:
          $ref: '#/components/schemas/Metadata'
    ProjectMachinePoolGrant:
      type: object
      additionalProperties: false
      required:
        - id
        - org_id
        - project_id
        - machine_pool_id
        - description
        - default_machine_cpu
        - default_machine_memory_mb
        - default_machine_env_overlay
        - default_machine_secret_env_overlay
        - default_machine_provider_options_overlay
        - default_cwd
        - max_total_machines
        - max_total_cpu
        - max_total_memory_mb
        - min_machine_cpu
        - min_machine_memory_mb
        - max_machine_cpu
        - max_machine_memory_mb
        - delete_after_idle_minutes
        - metadata
        - created_at
        - updated_at
      properties:
        id:
          $ref: '#/components/schemas/ProjectMachinePoolGrantID'
        org_id:
          $ref: '#/components/schemas/OrganizationID'
        project_id:
          $ref: '#/components/schemas/ProjectID'
        machine_pool_id:
          $ref: '#/components/schemas/MachinePoolID'
        description:
          type: string
        default_machine_cpu:
          type:
            - integer
            - 'null'
          format: int32
          minimum: 1
          maximum: 2147483647
        default_machine_memory_mb:
          type:
            - integer
            - 'null'
          format: int32
          minimum: 1
          maximum: 2147483647
        default_machine_env_overlay:
          description: >-
            Env overlay merged over the pool's default_machine_env for machines
            materialized through this grant; a null entry removes the key.
          type: object
          additionalProperties:
            type:
              - string
              - 'null'
        default_machine_secret_env_overlay:
          description: >-
            Secret env overlay merged over the pool's default_machine_secret_env
            for machines materialized through this grant; a null entry removes
            the key.
          type: object
          additionalProperties:
            type:
              - string
              - 'null'
            pattern: ^sec_[a-z2-7]{26}$
        default_machine_provider_options_overlay:
          type: object
          additionalProperties: true
        default_cwd:
          type: string
        max_total_machines:
          type:
            - integer
            - 'null'
          format: int32
          minimum: 0
          maximum: 2147483647
        max_total_cpu:
          type:
            - integer
            - 'null'
          format: int32
          minimum: 0
          maximum: 2147483647
        max_total_memory_mb:
          type:
            - integer
            - 'null'
          format: int32
          minimum: 0
          maximum: 2147483647
        min_machine_cpu:
          type:
            - integer
            - 'null'
          format: int32
          minimum: 0
          maximum: 2147483647
        min_machine_memory_mb:
          type:
            - integer
            - 'null'
          format: int32
          minimum: 0
          maximum: 2147483647
        max_machine_cpu:
          type:
            - integer
            - 'null'
          format: int32
          minimum: 1
          maximum: 2147483647
        max_machine_memory_mb:
          type:
            - integer
            - 'null'
          format: int32
          minimum: 1
          maximum: 2147483647
        delete_after_idle_minutes:
          description: >-
            Idle minutes before deleting a machine created through this grant.
            Zero disables deletion for this grant; null inherits the pool
            default.
          type:
            - integer
            - 'null'
          format: int32
          minimum: 0
          maximum: 2147483647
          oneOf:
            - const: 0
            - type: integer
              minimum: 5
              maximum: 2147483647
            - type: 'null'
        metadata:
          $ref: '#/components/schemas/Metadata'
        created_at:
          $ref: '#/components/schemas/Timestamp'
        updated_at:
          $ref: '#/components/schemas/Timestamp'
    Metadata:
      type: object
      description: >-
        Arbitrary key-value metadata. Maximum 16 pairs, keys up to 64
        characters, values must be strings of up to 512 characters.
      x-go-type: resourcemeta.Metadata
      x-go-type-import:
        path: github.com/omnara-ai/omnara/internal/resourcemeta
      x-go-type-skip-optional-pointer: true
      maxProperties: 16
      propertyNames:
        minLength: 1
        maxLength: 64
      additionalProperties:
        type: string
        maxLength: 512
    ProjectMachinePoolGrantID:
      type: string
      pattern: ^pmpg_[a-z2-7]{26}$
    OrganizationID:
      type: string
      pattern: ^org_[a-z2-7]{26}$
    ProjectID:
      type: string
      pattern: ^proj_[a-z2-7]{26}$
    MachinePoolID:
      type: string
      pattern: ^mpo_[a-z2-7]{26}$
    Timestamp:
      type: string
      format: date-time
    Error:
      type: object
      additionalProperties: false
      required:
        - error
        - code
      properties:
        error:
          type: string
          description: Human-readable error message. Do not match on it programmatically.
        code:
          type: string
          description: Stable error code for programmatic handling.
          enum:
            - invalid_request
            - unauthorized
            - forbidden
            - not_found
            - conflict
            - gone
            - request_too_large
            - unsupported_media_type
            - unprocessable
            - rate_limited
            - internal_error
            - upstream_error
            - service_unavailable
            - idempotency_key_conflict
            - state_transition_conflict
            - managed_work_admission_denied
            - pending_work
            - not_wake_capable
            - daemon_runtime_unregistered
            - validation_failed
            - csrf_check_failed
            - authentication_unavailable
    ClientErrorCode:
      type: string
      description: >-
        Stable error code carried by 4XX statuses. Subset of the Error code enum
        whose statuses are client errors.
      enum:
        - invalid_request
        - validation_failed
        - unauthorized
        - forbidden
        - csrf_check_failed
        - not_found
        - conflict
        - idempotency_key_conflict
        - state_transition_conflict
        - pending_work
        - not_wake_capable
        - gone
        - daemon_runtime_unregistered
        - request_too_large
        - unsupported_media_type
        - unprocessable
        - rate_limited
    ServerErrorCode:
      type: string
      description: >-
        Stable error code carried by 5XX statuses. Subset of the Error code enum
        whose statuses are server errors.
      enum:
        - internal_error
        - upstream_error
        - service_unavailable
        - authentication_unavailable
  responses:
    BadRequest:
      description: The request was invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Authentication is required or invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Forbidden:
      description: The authenticated principal is not authorized.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: The requested resource was not found or is not visible.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Conflict:
      description: >-
        The request conflicts with current resource state or idempotency
        history.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    ServiceUnavailable:
      description: The service dependency required to satisfy the request is unavailable.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    ClientError:
      description: >-
        Any other client error. The body carries the shared Error envelope
        restricted to client error codes; statuses with a dedicated response
        above are documented precisely.
      content:
        application/json:
          schema:
            type: object
            additionalProperties: false
            required:
              - error
              - code
            properties:
              error:
                type: string
                description: >-
                  Human-readable error message. Do not match on it
                  programmatically.
              code:
                $ref: '#/components/schemas/ClientErrorCode'
    ServerError:
      description: >-
        Any other server error. The body carries the shared Error envelope
        restricted to server error codes.
      content:
        application/json:
          schema:
            type: object
            additionalProperties: false
            required:
              - error
              - code
            properties:
              error:
                type: string
                description: >-
                  Human-readable error message. Do not match on it
                  programmatically.
              code:
                $ref: '#/components/schemas/ServerErrorCode'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: Omnara personal or organization access token
      description: An opaque Omnara personal or organization bearer token.
    browserSessionCookie:
      type: apiKey
      in: cookie
      name: __Host-omnara_session
      description: >-
        Browser session cookie. HTTPS deployments use __Host-omnara_session;
        local HTTP development uses omnara_session.
    csrfHeader:
      type: apiKey
      in: header
      name: X-Omnara-Csrf
      description: >-
        CSRF token header required for browser-session mutations. The value must
        match the session's CSRF cookie.

````