Delete brand kit

Permanently delete a never-published, unbound Brand kit.

Outcome

Permanently delete a never-published, unbound Brand kit.

Before you start

Verify whoami and the pinned credential context, then inspect the exact discovered action before preparing input.
Discover a granted Brand workspace. Pass its resourceType/workspace identifier separately from input; a copied fixture identifier grants no access.
The declared permission is brand:delete. The active credential, application scope, resource binding and runtime authority must all authorize the request.
Review the exact mutation and recovery, including destructive scope, and execute only after the intended effect is authorized.

Discover the target

topolo whoami --json
topolo actions get app_topolo_brand.brand_kits.delete --detail --json
topolo resources topolo-brand --json
topolo workspaces list topolo-brand --json

Request

DELETE /api/brand-kits/{id}

Resource context is the selected Brand workspace. CLI/SDK action input includes path identifiers; direct HTTP JSON bodies exclude path parameters. Read the reviewed plan for the exact request.

Input fields

Field	Required	Meaning
`id`	Yes	Exact kit or binding identifier from the corresponding list action; its meaning is determined by this action.

Exact published input schema:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "minLength": 1,
      "description": "Exact kit or binding identifier from the corresponding list action; its meaning is determined by this action."
    }
  },
  "required": [
    "id"
  ],
  "additionalProperties": false
}

Effects

Refuses kits with publication history or bindings. For an eligible kit, erases associated rows and original/frozen objects, then records a surviving workspace-scoped deletion audit.

Interpret the response

deleted:true accompanies recordsDeleted and objectsDeleted. A 409 eligibility refusal preserves the kit. Retirement is a separate lifecycle operation and does not make a published kit eligible for deletion.

Response identifier contract:

{
  "kind": "brand_kits_delete",
  "identifierSource": "none",
  "explanation": "deleted:true accompanies recordsDeleted and objectsDeleted. A 409 eligibility refusal preserves the kit. Retirement is a separate lifecycle operation and does not make a published kit eligible for deletion."
}

Worked examples

These complete synthetic responses were captured from the local worker over canonical SQL migrations. Auth and R2 dependencies are simulated; notification delivery is not exercised. Set BRAND_WORKSPACE_ID from granted workspace discovery. Save reviewed input as payload.json, validate and inspect the unchanged plan. The final mutation command and MCP confirm flag assume the intended effect has already been authorized.

Minimal example

Input · payload.json:

{
  "id": "brand_f6f7cd1b-e613-4ae5-9163-a8f6dbf504a9"
}

CLI:

topolo actions validate app_topolo_brand.brand_kits.delete --data @payload.json --json
topolo actions plan app_topolo_brand.brand_kits.delete --resource-type workspace --resource-id "$BRAND_WORKSPACE_ID" --data @payload.json --json
topolo actions call app_topolo_brand.brand_kits.delete --resource-type workspace --resource-id "$BRAND_WORKSPACE_ID" --data @payload.json --confirm --json

MCP tool and arguments:

{
  "tool": "topolo_call_action",
  "arguments": {
    "actionId": "app_topolo_brand.brand_kits.delete",
    "input": {
      "id": "brand_f6f7cd1b-e613-4ae5-9163-a8f6dbf504a9"
    },
    "resourceType": "workspace",
    "resourceId": "<identifier returned by resource discovery>",
    "confirm": true
  }
}

Captured local response · HTTP 200:

{
  "deleted": true,
  "recordsDeleted": 2,
  "objectsDeleted": 0
}

Workflow example

Input · payload.json:

{
  "id": "brand_191615fc-d1d8-4127-9403-d80b987dd7a7"
}

CLI:

topolo actions validate app_topolo_brand.brand_kits.delete --data @payload.json --json
topolo actions plan app_topolo_brand.brand_kits.delete --resource-type workspace --resource-id "$BRAND_WORKSPACE_ID" --data @payload.json --json
topolo actions call app_topolo_brand.brand_kits.delete --resource-type workspace --resource-id "$BRAND_WORKSPACE_ID" --data @payload.json --confirm --json

MCP tool and arguments:

{
  "tool": "topolo_call_action",
  "arguments": {
    "actionId": "app_topolo_brand.brand_kits.delete",
    "input": {
      "id": "brand_191615fc-d1d8-4127-9403-d80b987dd7a7"
    },
    "resourceType": "workspace",
    "resourceId": "<identifier returned by resource discovery>",
    "confirm": true
  }
}

Captured local response · HTTP 200:

{
  "deleted": true,
  "recordsDeleted": 2,
  "objectsDeleted": 0
}

Verify the result

List kits and read the exact identifier to confirm removal. Preserve the result and check the selected workspace export for the surviving deletion audit.

Errors and recovery

refused · HTTP 404

{
  "input": {
    "id": "missing-fixture"
  },
  "response": {
    "error": "brand_kit_not_found"
  }
}

published history refused · HTTP 409

{
  "input": {
    "id": "brand_5b9a9c07-74db-48cd-85fe-b6cda159a7f7"
  },
  "response": {
    "error": "brand_kit_has_history",
    "message": "This Brand Kit has published versions that consumers may have resolved. Retire it instead."
  }
}

auth_error (HTTP 401): CLI/SDK authentication classification when Auth returns a non-code message: restore the authorized credential, then verify whoami and context. Preserve the exact service message.
permission_denied (HTTP 403): Use the exact permission and granted resource required by the reviewed action; organization membership alone is insufficient.
workspace_required (HTTP 400): Discover and select a granted Brand workspace before preparing the request.
brand_storage_unavailable (HTTP 503): The Brand storage bindings are unavailable. Preserve the request identifier and report the service fault; do not retry an unverified mutation.
brand_kit_not_found (HTTP 404): Discover the exact parent/resource again and inspect its lifecycle status. Missing, inaccessible or immutable resources can share this refusal.
brand_kit_has_history (HTTP 409): Preserve the current state and inspect the specific eligibility refusal. Review a supported alternative; do not repeat the same destructive request.

Recovery boundary

No restore action recovers the deleted kit, its versions or bytes. Export needed data before an authorized deletion.

app_topolo_brand.privacy.export: Export records and asset download paths belonging to the selected Brand workspace.

Evidence

Four real local SQLite stores use all canonical migrations; Auth identity/grants and archival plus R2 object storage are explicitly simulated. Notifications are disabled in fixtures. No notification delivery, live mutation, gateway credential parity or deployed environment proof is claimed. Fixture identifiers and timestamps are synthetic and must be replaced by exact authorized resource discovery.