---
title: "Update a stash"
method: PATCH
path: "/v1/workspaces/{workspaceId}/stashes/{id}"
tags: ["Stashes"]
---

# Update a stash

`PATCH /v1/workspaces/{workspaceId}/stashes/{id}`

## Request

- Base URL: `https://external-api.pirros.com`
- URL: `https://external-api.pirros.com/v1/workspaces/{workspaceId}/stashes/{id}`
- Auth: OAuth 2
  - Client credentials
  - Token URL: `https://auth.pirros.com/oauth/token`

Update a stash's name, description, or is_permanent flag. Accepts an optional Idempotency-Key header. The post-update stash must satisfy a granted stash:write filter. A stash in another workspace or missing returns 404 (no existence disclosure).

## Path parameters

- `workspaceId` string, uuid, required
- `id` string, uuid, required

## Request body

- ExternalStashUpdateBody: Update a stash. Only name, description, and is_permanent are mutable; membership, project, and identity are not. At least one field is required.
  - `name` string
  - `description` string, nullable
  - `is_permanent` boolean

## Response `200`

Stash updated

- ExternalStashResponse: Single stash resource
  - `response` object, required: Stash metadata for external API consumers. is_firm_stash is read-only: true for a firm stash, listed under Firm for every member whose role can view firm stashes; false for a stash listed in its owner's Private list. An API key's stash placement decides it at creation.
    - `id` string, uuid, required
    - `name` string, required
    - `description` string, nullable, required
    - `project_id` string, uuid, required
    - `firm_id` string, uuid, required
    - `workspace_id` string, uuid, required
    - `is_permanent` boolean, required
    - `is_firm_stash` boolean, required
    - `is_archived` boolean, required
    - `downloaded_at` string, date-time, nullable, required
    - `items` union[], required
      - union
        - object
          - `item_type` 'detail', required
          - `detail_id` string, uuid, required
          - `family_id` unknown, required
        - object
          - `item_type` 'family', required
          - `detail_id` unknown, required
          - `family_id` string, uuid, required
    - `created_at` string, date-time, required
    - `expanded` object, required
  - `meta` object, required
    - `request_id` string, uuid, required

## Other responses

- `400`: Invalid request (bad path param, query param, or cursor)
- `401`: Unauthorized (invalid or missing token)
- `403`: The post-update stash does not satisfy a granted stash:write filter (invalid_filter)
- `404`: Stash not found in this workspace
- `409`: Idempotency-Key replay conflict (IDEMPOTENCY_CONFLICT): the same Idempotency-Key was reused with a different request body. An identical retry instead replays the original stored response.
- `429`: Rate limit exceeded (1000 requests per hour per client)
- `503`: External API temporarily disabled by operator kill switch (service_unavailable)

---

[API](https://skmtc.dev/pirros/apis/pirros-external-api.md) - [All operations](https://skmtc.dev/pirros/apis/pirros-external-api/llms.txt) - [OpenAPI document](https://skmtc.dev/pirros/apis/pirros-external-api/revisions/01c66b8d9fd1?raw)