> ## 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.

# Create and Manage Prompts via the Prompt Bank API

> Step-by-step guide to creating, updating, filtering, and deleting prompts with the Prompt Bank API. Includes pagination and vault filtering examples.

Prompts are the core unit in Prompt Bank. This guide walks you through creating prompts for different media types, querying your prompt library with filters and pagination, making partial updates, and cleaning up prompts you no longer need. All examples use `curl`, but the same requests work with any HTTP client.

## Create a prompt

<Steps>
  <Step title="Create a text prompt">
    Text prompts are useful for storing reusable LLM instructions or any content not tied to a specific image or video model. Send a `POST` request to `/api/v1/prompts`:

    <CodeGroup>
      ```bash curl theme={null}
      curl -X POST https://www.promptbank.club/api/v1/prompts \
        -H "Authorization: Bearer YOUR_API_KEY" \
        -H "Content-Type: application/json" \
        -d '{
          "title": "Blog post intro writer",
          "prompt": "Write a compelling opening paragraph for a blog post about {topic}. Use an engaging hook, establish the problem the reader faces, and end with a clear transition into the body of the post. Tone: conversational and informative.",
          "promptType": "text"
        }'
      ```
    </CodeGroup>

    The API returns the full prompt object wrapped in the standard response envelope:

    ```json theme={null}
    {
      "data": {
        "id": 1001,
        "title": "Blog post intro writer",
        "prompt": "Write a compelling opening paragraph for a blog post about {topic}. Use an engaging hook, establish the problem the reader faces, and end with a clear transition into the body of the post. Tone: conversational and informative.",
        "promptType": "text",
        "platform": null,
        "status": "active",
        "images": [],
        "vaultIds": [],
        "createdAt": "2024-11-15T09:00:00Z",
        "updatedAt": "2024-11-15T09:00:00Z"
      },
      "error": null
    }
    ```
  </Step>

  <Step title="Create an image prompt">
    Image prompts target a specific model and can carry configuration like `aspectRatio` and `referenceMediaUrls`. The `modelId` field is **required** for `image` and `video` prompt types — it must match the pattern `fal-ai/...`. Supply a `vaultId` (integer) to add the prompt directly to an existing vault:

    <CodeGroup>
      ```bash curl theme={null}
      curl -X POST https://www.promptbank.club/api/v1/prompts \
        -H "Authorization: Bearer YOUR_API_KEY" \
        -H "Content-Type: application/json" \
        -d '{
          "title": "Cyberpunk cityscape at dusk",
          "prompt": "A vast cyberpunk city at dusk, towering neon-lit skyscrapers reflected in rain-soaked streets, volumetric fog, cinematic composition, 8k detail",
          "promptType": "image",
          "modelId": "fal-ai/recraft/v4.1/text-to-image",
          "aspectRatio": "16:9",
          "platform": "artstation",
          "vaultId": 42,
          "referenceMediaUrls": [
            "https://cdn.promptbank.club/refs/neon-ref-01.jpg"
          ]
        }'
      ```
    </CodeGroup>

    ```json theme={null}
    {
      "data": {
        "id": 1002,
        "title": "Cyberpunk cityscape at dusk",
        "prompt": "A vast cyberpunk city at dusk, towering neon-lit skyscrapers reflected in rain-soaked streets, volumetric fog, cinematic composition, 8k detail",
        "promptType": "image",
        "platform": "artstation",
        "status": "active",
        "images": [],
        "vaultIds": [42],
        "createdAt": "2024-11-15T09:05:00Z",
        "updatedAt": "2024-11-15T09:05:00Z"
      },
      "error": null
    }
    ```
  </Step>
</Steps>

## List prompts

Use `GET /api/v1/prompts` to retrieve your prompts. The endpoint supports cursor-based pagination and several filter parameters:

| Query param | Description                                                                          |
| ----------- | ------------------------------------------------------------------------------------ |
| `limit`     | Number of results to return. Range: `1`–`100`. Default: `20`.                        |
| `cursor`    | Opaque pagination cursor from the previous response's `pagination.nextCursor` field. |
| `vaultId`   | Filter to only prompts belonging to a specific vault (integer ID).                   |
| `type`      | Filter by `promptType`: `text`, `image`, or `video`.                                 |

### Fetch the first page

<CodeGroup>
  ```bash curl theme={null}
  curl "https://www.promptbank.club/api/v1/prompts?limit=20&type=image" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```
</CodeGroup>

```json theme={null}
{
  "data": [
    {
      "id": 1002,
      "title": "Cyberpunk cityscape at dusk",
      "prompt": "A vast cyberpunk city at dusk...",
      "promptType": "image",
      "platform": "artstation",
      "status": "active",
      "images": [],
      "vaultIds": [42],
      "createdAt": "2024-11-15T09:05:00Z",
      "updatedAt": "2024-11-15T09:05:00Z"
    }
  ],
  "pagination": {
    "nextCursor": "cur_01hxyzpage2token"
  },
  "error": null
}
```

### Fetch the next page

Pass the `pagination.nextCursor` value as the `cursor` query parameter to retrieve the following page:

<CodeGroup>
  ```bash curl theme={null}
  curl "https://www.promptbank.club/api/v1/prompts?limit=20&type=image&cursor=cur_01hxyzpage2token" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```
</CodeGroup>

When `pagination.nextCursor` is absent or `null`, you have reached the last page.

### Filter by vault

<CodeGroup>
  ```bash curl theme={null}
  curl "https://www.promptbank.club/api/v1/prompts?vaultId=42&limit=50" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```
</CodeGroup>

## Update a prompt

Use `PATCH /api/v1/prompts/{promptId}` to update one or more fields without replacing the entire object. Only include the fields you want to change:

<CodeGroup>
  ```bash curl theme={null}
  curl -X PATCH https://www.promptbank.club/api/v1/prompts/1002 \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "title": "Cyberpunk cityscape — golden hour",
      "aspectRatio": "4:3"
    }'
  ```
</CodeGroup>

```json theme={null}
{
  "data": {
    "id": 1002,
    "title": "Cyberpunk cityscape — golden hour",
    "prompt": "A vast cyberpunk city at dusk, towering neon-lit skyscrapers reflected in rain-soaked streets, volumetric fog, cinematic composition, 8k detail",
    "promptType": "image",
    "platform": "artstation",
    "status": "active",
    "images": [],
    "vaultIds": [42],
    "createdAt": "2024-11-15T09:05:00Z",
    "updatedAt": "2024-11-15T11:20:00Z"
  },
  "error": null
}
```

## Delete a prompt

Send a `DELETE` request to remove a prompt permanently. This action cannot be undone.

<CodeGroup>
  ```bash curl theme={null}
  curl -X DELETE https://www.promptbank.club/api/v1/prompts/1001 \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```
</CodeGroup>

A successful deletion returns HTTP `200` with an empty `data` field:

```json theme={null}
{
  "data": null,
  "error": null
}
```

## Next steps

* Learn how to organize your prompts into collections with the [Organize Vaults guide](/guides/organize-vaults).
* Ready to run a generation from your prompt? See the [Generate Media guide](/guides/generate-media).