---
title: "Apply a previewed command"
method: POST
path: "/v1/tool-capabilities/commands"
tags: ["Tool Permissions"]
---

# Apply a previewed command

`POST /v1/tool-capabilities/commands`

## Request

- Base URL: `http://localhost:9998`
- URL: `http://localhost:9998/v1/tool-capabilities/commands`
- Auth: HTTP bearer

Applies the preview `previewId` names, once, while the generation is
still `expectedGeneration`, for the same management access that
prepared it. A preview with `requiresOwnerAuthentication` asks the
device owner to confirm on the Mac before anything is written; without
that confirmation nothing changes. `changed: false` means the command
left the policy as it was. Requires `system:control`.

## Request body

- ToolCapabilityApplyRequest
  - `expectedGeneration` string, required
  - `previewId` string, required

## Response `200`

The command was applied, or changed nothing

- ToolCapabilityCommandResult
  - `changed` boolean, required
  - `status` ToolCapabilityStatus, required
    - `generationId` string, required
    - `catalogId` string, required
    - `canEdit` boolean, required
    - `rows` ToolCapabilityRow[], required
      - `id` string, required
      - `name` string, required
      - `title` string, required
      - `operations` ToolCapabilityOperation[], required
        - `id` string, required
        - `label` string, required
        - `inclusion` 'included' | 'partial' | 'excluded' | 'unavailable', required
        - `supportedSelectors` string[], required
        - `includedCoverage` ToolCapabilityCoverage[], required
          - `operationId` string, required
          - `reachRevision` integer, required
          - `resourceKind` string, required
          - `resourceType` string
          - `installationId` string
          - `rawName` string
          - `contractFingerprint` string
          - `selector` ToolCapabilitySelector, required
            - `kind` 'all' | 'project' | 'resource', required
            - `id` string: The project or resource id; absent for `all`.
        - `excludedCoverage` ToolCapabilityCoverage[], required
          - `operationId` string, required
          - `reachRevision` integer, required
          - `resourceKind` string, required
          - `resourceType` string
          - `installationId` string
          - `rawName` string
          - `contractFingerprint` string
          - `selector` ToolCapabilitySelector, required
            - `kind` 'all' | 'project' | 'resource', required
            - `id` string: The project or resource id; absent for `all`.
        - `rules` ToolCapabilityRule[], required
          - `id` string, required
          - `coverage` ToolCapabilityCoverage, required
            - `operationId` string, required
            - `reachRevision` integer, required
            - `resourceKind` string, required
            - `resourceType` string
            - `installationId` string
            - `rawName` string
            - `contractFingerprint` string
            - `selector` ToolCapabilitySelector, required
              - …
          - `policy` string, required
          - `subject` ToolCapabilitySubject, required
            - `kind` 'agents' | 'client' | 'appWide', required
            - `client` ToolCapabilityClientKey: The stable identity of a client; never a token id.
              - …
          - `lifetime` ToolCapabilityLifetime, required
            - `kind` 'persistent' | 'expiresAt' | 'session', required
            - `value` string: The expiry instant or session id, when the kind needs one.
          - `origin` string
          - `authorKind` string, required
          - `authorClient` ToolCapabilityClientKey: The stable identity of a client; never a token id.
            - `kind` 'connected-app' | 'shared-class' | 'paired-device' | 'provider-ticket' | 'person', required
            - `id` string: The clientId, class name, pair-row key or ticket id; absent for `person`.
            - `mintOrigin` string
          - `authorDetail` string
        - `permissionSummary` string, required
        - `unavailableReason` string
        - `updatedSinceAllowed` boolean: Present, and true, only when the operation asks because an update reset an Allow the person chose for an earlier version of it. Absent otherwise.
      - `inclusion` 'included' | 'partial' | 'excluded' | 'unavailable', required
      - `availabilityReason` string
      - `unavailableReason` string
    - `delivery` ToolCapabilityDelivery[], required
      - `contextId` string, required
      - `mode` string, required
      - `band` string, required: The numeric budget band (lean, balanced or heavy).
      - `inherited` boolean: True when the context follows the app default.
    - `narrowing` ToolCapabilityNarrowing[], required
      - `id` string, required
      - `kind` string, required
      - `subjectKind` string, required
      - `subjectId` string
      - `client` ToolCapabilityClientKey: The stable identity of a client; never a token id.
        - `kind` 'connected-app' | 'shared-class' | 'paired-device' | 'provider-ticket' | 'person', required
        - `id` string: The clientId, class name, pair-row key or ticket id; absent for `person`.
        - `mintOrigin` string
      - `coverage` ToolCapabilityCoverage[], required
        - `operationId` string, required
        - `reachRevision` integer, required
        - `resourceKind` string, required
        - `resourceType` string
        - `installationId` string
        - `rawName` string
        - `contractFingerprint` string
        - `selector` ToolCapabilitySelector, required
          - `kind` 'all' | 'project' | 'resource', required
          - `id` string: The project or resource id; absent for `all`.

## Other responses

- `400`: The confirmation could not be read (`invalid_request`).
- `403`: The bearer lacks `system:control`, the request no longer has management access (`administration_forbidden`), or the device owner did not confirm (`owner_authentication_required`). Nothing was changed.
- `409`: The preview is stale, unknown or already used (`policy_conflict`), the confirmation was cancelled (`administration_cancelled`), or management state changed (`administration_stale`). Nothing was changed.
- `500`: The write failed (`storage_failed`); the policy in force is unchanged.
- `503`: The policy generation is unavailable (`administration_unavailable`).

---

[API](https://skmtc.dev/modelpiper/apis/toolpiper-api.md) · [All operations](https://skmtc.dev/modelpiper/apis/toolpiper-api/llms.txt) · [OpenAPI document](https://skmtc.dev/modelpiper/apis/toolpiper-api/revisions/6722bf56385c?raw)