---
title: "Create a stash"
method: POST
path: "/v1/workspaces/{workspaceId}/stashes"
tags: ["Stashes"]
---

# Create a stash

`POST /v1/workspaces/{workspaceId}/stashes`

## Request

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

Create a workspace-scoped stash. Accepts an optional Idempotency-Key header for safe retries. The candidate stash must satisfy a granted stash:write filter (403 invalid_filter otherwise); an invalid item reference returns 400 INVALID_ITEM_REFERENCE. The response equals a subsequent GET. Ownership: a stash created with an API key is owned by the member who created the key, and one created through a connected AI client by the member who connected it. By default it appears in that member's Private stash list. An API key whose stash placement a firm administrator set to "firm" creates a firm stash instead, listed under Firm for every member whose role can view firm stashes; while the key's creator lacks the Create Firm Stashes permission in the workspace the request is refused with 403 FIRM_STASH_NOT_PERMITTED, and no private stash is made in its place. is_firm_stash in the response says which it is.

## Path parameters

- `workspaceId` string, uuid, required

## Request body

- ExternalStashCreateBody: Create a stash from detail and family references. Every referenced item must belong to project_id within the workspace; any cross-project/cross-workspace/missing reference returns a single generic 400 INVALID_ITEM_REFERENCE (no id disclosure).
  - `name` string, required
  - `description` string, nullable
  - `project_id` string, uuid, required
  - `item_ids` object, required
    - `detail_ids` string[], required
    - `family_ids` string[], required
  - `is_permanent` boolean

## Response `201`

Stash created

- 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`: Token has no eligible stash:write filter, or the candidate does not satisfy one (insufficient_scope / invalid_filter); the API key's creator is no longer an active member of its firm (CREDENTIAL_OWNER_UNAVAILABLE); or the key places its stashes with the firm and its creator lacks Create Firm Stashes in this workspace (FIRM_STASH_NOT_PERMITTED)
- `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)