> ## 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 model grant

> Updates the project's overrides for the configured model. Omitted fields keep their current values; null clears an override so the project inherits from the configured model. The grant is live policy: agents already using the model re-apply the updated overrides on their next model call, against the configured-model revision each agent pinned at launch. Updates are validated against the configured model's current revision only, so an update can make an agent pinned to an older, incompatible revision fail its next model call.



## OpenAPI

````yaml /api-reference/openapi.yaml patch /orgs/{orgID}/projects/{projectID}/model-grants/{modelGrantID}
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}/model-grants/{modelGrantID}:
    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: modelGrantID
        in: path
        required: true
        schema:
          type: string
          pattern: ^pmog_[a-z2-7]{26}$
    patch:
      tags:
        - Models
      summary: Update project model grant
      description: >-
        Updates the project's overrides for the configured model. Omitted fields
        keep their current values; null clears an override so the project
        inherits from the configured model. The grant is live policy: agents
        already using the model re-apply the updated overrides on their next
        model call, against the configured-model revision each agent pinned at
        launch. Updates are validated against the configured model's current
        revision only, so an update can make an agent pinned to an older,
        incompatible revision fail its next model call.
      operationId: updateProjectModelGrant
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateProjectModelGrantRequest'
      responses:
        '200':
          description: Route response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProjectModelGrantEnvelope'
        '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:
    UpdateProjectModelGrantRequest:
      type: object
      description: >-
        Update a project model grant's overrides. Omitted fields keep their
        current values. Null clears an override so the project inherits from the
        configured model; for arrays, an empty array clears the override.
      additionalProperties: false
      minProperties: 1
      properties:
        context_window_tokens:
          type:
            - integer
            - 'null'
          minimum: 1
          description: >-
            Project token-window limit. Cannot exceed the configured model's
            current limit.
        max_output_tokens:
          type:
            - integer
            - 'null'
          minimum: 1
          description: >-
            Project output-token ceiling. Cannot exceed the configured model's
            ceiling.
        default_max_output_tokens:
          type:
            - integer
            - 'null'
          minimum: 1
          description: Project default per-request output-token cap.
        default_cache_retention:
          anyOf:
            - $ref: '#/components/schemas/ModelCacheRetention'
            - type: 'null'
        supports_tools:
          type:
            - boolean
            - 'null'
          description: >-
            Project-level tool-use gate. Can disable tools, but cannot enable
            tools when the configured model does not support them.
        supports_reasoning:
          type:
            - boolean
            - 'null'
          description: >-
            Project-level reasoning gate. Can disable reasoning, but cannot
            enable reasoning when the configured model does not support it.
        default_reasoning_effort:
          type:
            - string
            - 'null'
          description: Project default reasoning effort.
        supported_reasoning_efforts:
          type: array
          description: >-
            Project subset of configured-model reasoning efforts. If this
            excludes the inherited default_reasoning_effort, set
            default_reasoning_effort on the grant too.
          items:
            type: string
        input_modalities:
          type: array
          description: Project subset of configured-model input types.
          items:
            type: string
        output_modalities:
          type: array
          description: Project subset of configured-model output types.
          items:
            type: string
    ProjectModelGrantEnvelope:
      type: object
      additionalProperties: false
      required:
        - grant
      properties:
        grant:
          $ref: '#/components/schemas/ProjectModelGrant'
    ModelCacheRetention:
      type: string
      description: >-
        Default prompt-cache hint for model requests. `none` means Omnara does
        not send a cache hint; providers may still apply their own automatic
        caching. `short` and `long` are translated to the closest supported
        control for the selected API.
      enum:
        - none
        - short
        - long
    ProjectModelGrant:
      type: object
      additionalProperties: false
      required:
        - id
        - org_id
        - project_id
        - configured_model_id
        - supported_reasoning_efforts
        - input_modalities
        - output_modalities
        - created_at
        - updated_at
      properties:
        id:
          $ref: '#/components/schemas/ProjectModelGrantID'
        org_id:
          $ref: '#/components/schemas/OrganizationID'
        project_id:
          $ref: '#/components/schemas/ProjectID'
        configured_model_id:
          $ref: '#/components/schemas/ConfiguredModelID'
        context_window_tokens:
          type:
            - integer
            - 'null'
          description: >-
            Project token-window limit, or omitted/null to inherit from the
            configured model.
        max_output_tokens:
          type:
            - integer
            - 'null'
          description: >-
            Project output-token ceiling, or omitted/null to inherit from the
            configured model.
        default_max_output_tokens:
          type:
            - integer
            - 'null'
          description: >-
            Project default per-request output-token cap, or omitted/null to
            inherit from the configured model.
        default_cache_retention:
          $ref: '#/components/schemas/ModelCacheRetention'
        supports_tools:
          type:
            - boolean
            - 'null'
          description: >-
            Project-level tool-use override, or omitted/null to inherit from the
            configured model.
        supports_reasoning:
          type:
            - boolean
            - 'null'
          description: >-
            Project-level reasoning override, or omitted/null to inherit from
            the configured model.
        default_reasoning_effort:
          type: string
          description: >-
            Project default reasoning effort, or omitted/empty to inherit from
            the configured model.
        supported_reasoning_efforts:
          type: array
          description: >-
            Project subset of configured-model reasoning efforts. Empty means
            inherit. When non-empty, default_reasoning_effort must resolve to
            one of these values.
          items:
            type: string
        input_modalities:
          type: array
          description: >-
            Project subset of configured-model input types (text, image, or
            file). Empty means inherit.
          items:
            type: string
        output_modalities:
          type: array
          description: >-
            Project subset of configured-model output types. Empty means
            inherit.
          items:
            type: string
        created_at:
          $ref: '#/components/schemas/Timestamp'
        updated_at:
          $ref: '#/components/schemas/Timestamp'
    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
    ProjectModelGrantID:
      type: string
      pattern: ^pmog_[a-z2-7]{26}$
    OrganizationID:
      type: string
      pattern: ^org_[a-z2-7]{26}$
    ProjectID:
      type: string
      pattern: ^proj_[a-z2-7]{26}$
    ConfiguredModelID:
      type: string
      pattern: ^mdl_[a-z2-7]{26}$
    Timestamp:
      type: string
      format: date-time
  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.

````