---
title: "Preview one capability, permission or delivery command"
method: POST
path: "/v1/tool-capabilities/preview"
tags: ["Tool Permissions"]
---

# Preview one capability, permission or delivery command

`POST /v1/tool-capabilities/preview`

## Request

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

Prepares one command against the generation and catalog the caller
read and returns the status before and after it, the operations it
changes, and whether applying it needs the device owner to confirm on
the Mac. Nothing is written. The preview is held for this caller until
it is applied or expires, and `previewId` names it to
`POST /v1/tool-capabilities/commands`. Requires `system:control`.

## Request body

- ToolCapabilityPreviewRequest
  - `expectedGeneration` string, required
  - `expectedCatalogId` string, required
  - `command` ToolCapabilityCommand, required
    - `action` 'include' | 'exclude' | 'resetCapabilities' | 'resetCarriedRestriction' | 'setPermission' | 'removePermission' | 'resetPermissions' | 'setDelivery' | 'inheritDelivery', required
    - `contextId` string
    - `selections` ToolCapabilitySelection[]
      - `operationId` string, required
      - `selector` ToolCapabilitySelector, required
        - `kind` 'all' | 'project' | 'resource', required
        - `id` string: The project or resource id; absent for `all`.
    - `restrictionId` string
    - `ruleId` string
    - `ruleIds` string[]: removePermission of several rules as one write, in place of ruleId.
    - `policy` 'allow' | 'ask' | 'deny'
    - `subject` ToolCapabilitySubject
      - `kind` 'agents' | 'client' | 'appWide', required
      - `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
    - `lifetime` ToolCapabilityLifetime
      - `kind` 'persistent' | 'expiresAt' | 'session', required
      - `value` string: The expiry instant or session id, when the kind needs one.
    - `delivery` ToolCapabilityDelivery
      - `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.

## Response `200`

The prepared change

- ToolCapabilityPreview
  - `previewId` string, required
  - `before` 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`.
  - `after` 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`.
  - `requiresOwnerAuthentication` boolean, required
  - `changedOperationIds` string[], required

## Other responses

- `400`: The command could not be read or is not valid for this generation, or this caller already holds too many pending previews (`invalid_request`).
- `403`: The bearer lacks `system:control`, or the request no longer has management access (`administration_forbidden`).
- `409`: The generation or catalog changed since it was read (`policy_conflict`), or management state changed (`administration_stale`). Nothing was prepared.
- `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)