Create and Manage Prompts via the Prompt Bank API

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

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:

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"
  }'

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

{
  "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
}

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:

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"
    ]
  }'

{
  "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
}

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

curl "https://www.promptbank.club/api/v1/prompts?limit=20&type=image" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "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:

curl "https://www.promptbank.club/api/v1/prompts?limit=20&type=image&cursor=cur_01hxyzpage2token" \
  -H "Authorization: Bearer YOUR_API_KEY"

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

Filter by vault

curl "https://www.promptbank.club/api/v1/prompts?vaultId=42&limit=50" \
  -H "Authorization: Bearer YOUR_API_KEY"

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:

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"
  }'

{
  "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.

curl -X DELETE https://www.promptbank.club/api/v1/prompts/1001 \
  -H "Authorization: Bearer YOUR_API_KEY"

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

{
  "data": null,
  "error": null
}

Next steps

Learn how to organize your prompts into collections with the Organize Vaults guide.
Ready to run a generation from your prompt? See the Generate Media guide.

Get Started

Core Concepts

Guides

Create and Manage Prompts via the Prompt Bank API

Create a prompt

List prompts

Fetch the first page

Fetch the next page

Filter by vault

Update a prompt

Delete a prompt

Next steps

​Create a prompt

​List prompts

​Fetch the first page

​Fetch the next page

​Filter by vault

​Update a prompt

​Delete a prompt

​Next steps

Create a prompt

List prompts

Fetch the first page

Fetch the next page

Filter by vault

Update a prompt

Delete a prompt

Next steps