> ## Documentation Index
> Fetch the complete documentation index at: https://docs.promptbank.club/llms.txt
> Use this file to discover all available pages before exploring further.

# Organize Prompts into Vaults in Prompt Bank

> Learn how to create vaults, set visibility, add and move prompts, fork public vaults, and pin your favorite prompts using the Prompt Bank API.

Vaults give structure to your prompt library. Whether you're building a personal collection, collaborating with a team, or publishing prompts for the community, vaults let you group related prompts, control access, and share your work. This guide walks you through the full vault workflow from creation to sharing.

## Typical vault workflow

<Steps>
  <Step title="Create a vault">
    Create a new vault by sending a `POST` request to `/api/v1/vaults`. Supply a `name`, an optional `description`, and a `visibility` setting:

    ```bash theme={null}
    curl -X POST https://www.promptbank.club/api/v1/vaults \
      -H "Authorization: Bearer YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "name": "Cyberpunk Scenes",
        "description": "A curated set of prompts for neon-noir cityscape imagery.",
        "visibility": "private"
      }'
    ```

    ```json theme={null}
    {
      "data": {
        "id": 42,
        "name": "Cyberpunk Scenes",
        "slug": "cyberpunk-scenes",
        "description": "A curated set of prompts for neon-noir cityscape imagery.",
        "visibility": "private",
        "accessType": "owner",
        "isLocked": false,
        "coverImageUrl": null,
        "isSystem": false,
        "promptCount": 0,
        "createdAt": "2024-11-15T08:00:00Z",
        "updatedAt": "2024-11-15T08:00:00Z"
      },
      "error": null
    }
    ```
  </Step>

  <Step title="Add prompts to the vault">
    Once you have prompt IDs, add up to 50 at a time with `POST /api/v1/vaults/{vaultId}/prompts`. Use the integer `id` values returned when you created each prompt:

    ```bash theme={null}
    curl -X POST https://www.promptbank.club/api/v1/vaults/42/prompts \
      -H "Authorization: Bearer YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "promptIds": [1001, 1002, 1003]
      }'
    ```

    The response returns the updated vault with the new `promptCount`.
  </Step>

  <Step title="Set visibility to share the vault">
    When your vault is ready to share, update its `visibility` with a `PATCH` request:

    ```bash theme={null}
    curl -X PATCH https://www.promptbank.club/api/v1/vaults/42 \
      -H "Authorization: Bearer YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "visibility": "public"
      }'
    ```

    Other users can now discover and fork your vault.
  </Step>
</Steps>

## Vault visibility

You can create vaults at any visibility level and change them at any time.

**Private vault** — only you can see it:

```bash theme={null}
curl -X POST https://www.promptbank.club/api/v1/vaults \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Work in Progress",
    "visibility": "private"
  }'
```

**Unlisted vault** — accessible via direct link, not listed publicly:

```bash theme={null}
curl -X POST https://www.promptbank.club/api/v1/vaults \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Client Preview",
    "visibility": "unlisted"
  }'
```

**Public vault** — discoverable by anyone:

```bash theme={null}
curl -X POST https://www.promptbank.club/api/v1/vaults \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Open Prompt Pack",
    "visibility": "public"
  }'
```

## Adding prompts to a vault

Use `POST /api/v1/vaults/{vaultId}/prompts` to associate existing prompts with a vault. Pass an array of integer prompt `id` values in `promptIds`. You can add up to 50 at a time:

```bash theme={null}
curl -X POST https://www.promptbank.club/api/v1/vaults/42/prompts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "promptIds": [1001, 1002]
  }'
```

The `promptIds` values are the integer `id` fields returned when you created each prompt. You can also add a prompt directly to a vault at creation time by including a `vaultId` integer in the `POST /api/v1/prompts` body.

## Removing a prompt from a vault

To remove a prompt from a vault without deleting the underlying prompt, use `DELETE /api/v1/vaults/{vaultId}/prompts/{vaultPromptId}`. The `vaultPromptId` is the ID of the vault-prompt association (returned when you add prompts), not the prompt's own ID:

```bash theme={null}
curl -X DELETE \
  https://www.promptbank.club/api/v1/vaults/42/prompts/789 \
  -H "Authorization: Bearer YOUR_API_KEY"
```

The prompt object itself is unaffected and remains accessible in any other vaults it belongs to.

## Pinning and unpinning prompts

Pinning a prompt marks it as featured within the vault. Pinned prompts are surfaced at the top of vault listings. Use the `vaultPromptId` — the ID of the vault-prompt association, returned when you add a prompt — not the prompt's own `id`.

**Pin a prompt:**

```bash theme={null}
curl -X POST \
  https://www.promptbank.club/api/v1/vaults/42/prompts/789/pin \
  -H "Authorization: Bearer YOUR_API_KEY"
```

A `200 OK` response confirms the prompt is now pinned.

**Unpin a prompt:**

```bash theme={null}
curl -X DELETE \
  https://www.promptbank.club/api/v1/vaults/42/prompts/789/pin \
  -H "Authorization: Bearer YOUR_API_KEY"
```

A `200 OK` response confirms the prompt is no longer pinned.

## Moving prompts between vaults

To transfer a prompt from one vault to another, use `POST /api/v1/vaults/{vaultId}/prompts/{vaultPromptId}/move` with a `targetVaultId` integer in the body:

```bash theme={null}
curl -X POST \
  https://www.promptbank.club/api/v1/vaults/42/prompts/789/move \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "targetVaultId": 99
  }'
```

The prompt is removed from the source vault and added to the target vault. The underlying prompt object is unchanged.

## Forking a vault

Forking copies all prompts from a `public` or `unlisted` vault into a new vault owned by your account. The forked vault starts as `private`.

```bash theme={null}
curl -X POST https://www.promptbank.club/api/v1/vaults/42/fork \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```json theme={null}
{
  "data": {
    "id": 101,
    "name": "Cyberpunk Scenes (fork)",
    "slug": "cyberpunk-scenes-fork",
    "description": "A curated set of prompts for neon-noir cityscape imagery.",
    "visibility": "private",
    "accessType": "owner",
    "isLocked": false,
    "coverImageUrl": null,
    "isSystem": false,
    "promptCount": 24,
    "createdAt": "2024-11-15T14:00:00Z",
    "updatedAt": "2024-11-15T14:00:00Z"
  },
  "error": null
}
```

You can fork any vault whose visibility is `public` or `unlisted`. The original vault and its owner are not affected.

## Next steps

* Learn how to run image and video generations and save outputs to a vault in the [Generate Media guide](/guides/generate-media).
* Need to create prompts first? See [Manage Prompts](/guides/manage-prompts).