---
title: "List prompts"
method: POST
path: "/api/prompts/list/"
tags: ["Prompts"]
---

# List prompts

`POST /api/prompts/list/`

## Request

- Base URL: `https://api.respan.ai`
- URL: `https://api.respan.ai/api/prompts/list/`
- Auth: one of:
  - HTTP bearer
  - HTTP bearer

## Query parameters

- `page` integer
- `page_size` integer
- `sort_by` '-id' | 'id' | '-current_version__updated_at' | 'current_version__updated_at'

## Request body

- object
  - `filters` object: Each key is a field to filter on, and each value is a condition: `{"<field>": {"operator": "<operator>", "value": [...]}}`. A prompt must match every condition. To set two conditions on one field, such as a range, pass a list of conditions. **Operators:** `""` (equals, the default), `not`, `in`, `not_in`, `lt`, `lte`, `gt`, `gte`, `contains`, `not_contains`, `icontains` (ignores case), `startswith`, `not_startswith`, `endswith`, `not_endswith`, `empty`, `not_empty`. Put values in a list: `""` and `in` match any of the listed values, and `not` and `not_in` match none of them. Other operators take one value; for `empty` and `not_empty`, send `[""]`. **Fields:** `prompt_id`, `prompt_slug`, `name`, `description`, `starred`, `commit_count`, `creator_email`, version fields through `current_version__<field>` or `live_version__<field>` (for example `current_version__model` or `current_version__updated_at`), `tags` (prompts with any of the given tag IDs), and `is_deleted` (send `"value": true` to get deleted prompts instead of active ones). Unsupported fields return a 400 error. **Example:** ```json { "name": {"operator": "icontains", "value": ["support"]}, "current_version__model": {"operator": "in", "value": ["gpt-5.5", "claude-sonnet-4-5-20250929"]} } ```
    - `prompt_id` FilterValue: A filter condition with an operator and value.
      - `operator` '' | 'not' | 'in' | 'not_in' | 'lt' | 'lte' | 'gt' | 'gte' | 'contains' | 'not_contains' | 'icontains' | 'startswith' | 'not_startswith' | 'endswith' | 'not_endswith' | 'empty' | 'not_empty': Comparison operator. An empty string means equals.
      - `value` unknown[], required: Value(s) to filter by.
        - unknown
    - `prompt_slug` FilterValue: A filter condition with an operator and value.
      - `operator` '' | 'not' | 'in' | 'not_in' | 'lt' | 'lte' | 'gt' | 'gte' | 'contains' | 'not_contains' | 'icontains' | 'startswith' | 'not_startswith' | 'endswith' | 'not_endswith' | 'empty' | 'not_empty': Comparison operator. An empty string means equals.
      - `value` unknown[], required: Value(s) to filter by.
        - unknown
    - `name` FilterValue: A filter condition with an operator and value.
      - `operator` '' | 'not' | 'in' | 'not_in' | 'lt' | 'lte' | 'gt' | 'gte' | 'contains' | 'not_contains' | 'icontains' | 'startswith' | 'not_startswith' | 'endswith' | 'not_endswith' | 'empty' | 'not_empty': Comparison operator. An empty string means equals.
      - `value` unknown[], required: Value(s) to filter by.
        - unknown
    - `description` FilterValue: A filter condition with an operator and value.
      - `operator` '' | 'not' | 'in' | 'not_in' | 'lt' | 'lte' | 'gt' | 'gte' | 'contains' | 'not_contains' | 'icontains' | 'startswith' | 'not_startswith' | 'endswith' | 'not_endswith' | 'empty' | 'not_empty': Comparison operator. An empty string means equals.
      - `value` unknown[], required: Value(s) to filter by.
        - unknown
    - `starred` FilterValue: A filter condition with an operator and value.
      - `operator` '' | 'not' | 'in' | 'not_in' | 'lt' | 'lte' | 'gt' | 'gte' | 'contains' | 'not_contains' | 'icontains' | 'startswith' | 'not_startswith' | 'endswith' | 'not_endswith' | 'empty' | 'not_empty': Comparison operator. An empty string means equals.
      - `value` unknown[], required: Value(s) to filter by.
        - unknown
    - `tags` FilterValue: A filter condition with an operator and value.
      - `operator` '' | 'not' | 'in' | 'not_in' | 'lt' | 'lte' | 'gt' | 'gte' | 'contains' | 'not_contains' | 'icontains' | 'startswith' | 'not_startswith' | 'endswith' | 'not_endswith' | 'empty' | 'not_empty': Comparison operator. An empty string means equals.
      - `value` unknown[], required: Value(s) to filter by.
        - unknown
    - `current_version__updated_at` FilterValue: A filter condition with an operator and value.
      - `operator` '' | 'not' | 'in' | 'not_in' | 'lt' | 'lte' | 'gt' | 'gte' | 'contains' | 'not_contains' | 'icontains' | 'startswith' | 'not_startswith' | 'endswith' | 'not_endswith' | 'empty' | 'not_empty': Comparison operator. An empty string means equals.
      - `value` unknown[], required: Value(s) to filter by.
        - unknown
    - `current_version__created_at` FilterValue: A filter condition with an operator and value.
      - `operator` '' | 'not' | 'in' | 'not_in' | 'lt' | 'lte' | 'gt' | 'gte' | 'contains' | 'not_contains' | 'icontains' | 'startswith' | 'not_startswith' | 'endswith' | 'not_endswith' | 'empty' | 'not_empty': Comparison operator. An empty string means equals.
      - `value` unknown[], required: Value(s) to filter by.
        - unknown
    - `is_deleted` FilterValue: A filter condition with an operator and value.
      - `operator` '' | 'not' | 'in' | 'not_in' | 'lt' | 'lte' | 'gt' | 'gte' | 'contains' | 'not_contains' | 'icontains' | 'startswith' | 'not_startswith' | 'endswith' | 'not_endswith' | 'empty' | 'not_empty': Comparison operator. An empty string means equals.
      - `value` unknown[], required: Value(s) to filter by.
        - unknown

## Response `200`

Paginated list of prompts.

- object
  - `count` integer: Number of results on this page, not the total. Request pages until `next` is null to get every result.
  - `next` string, nullable: Next page URL.
  - `previous` string, nullable: Previous page URL.
  - `results` object[]
    - `id` string
    - `name` string
    - `description` string, nullable
    - `prompt_slug` string, nullable
    - `tags` object[]
      - `id` string
      - `name` string
      - `color` string
      - `created_at` string, date-time
      - `updated_at` string, date-time
    - `current_version` object, nullable: The prompt's current version, as the full version object that Get a prompt version returns.
      - `version` integer
      - `model` string
      - `updated_at` string, date-time
    - `live_version` object, nullable: The deployed version, as the full version object that Get a prompt version returns. `null` until a version is deployed.
      - `version` integer
      - `model` string
      - `updated_at` string, date-time

## Other responses

- `403`: The API key is missing, invalid or expired.

## Changes

- **2026-10-21** `c30bcb383ee8`: 9 breaking, 12 info
  - request body became required
  - the response property `next` became nullable for the status `200`
  - the response property `previous` became nullable for the status `200`
  - the response property `results/items/current_version` became nullable for the status `200`
  - …17 more
- **2026-10-02** `b830b79cfd52`: 16 breaking, 4 warning, 51 info
  - removed the enum value `iexact` of the request property `filters/current_version__updated_at/operator`
  - removed the enum value `iexact` of the request property `filters/description/operator`
  - removed the enum value `iexact` of the request property `filters/is_deleted/operator`
  - removed the enum value `iexact` of the request property `filters/name/operator`
  - …67 more
- **2026-09-17** `6fa8242da8c2`: 1 warning, 1 info
  - deleted the `header` request parameter `Authorization`
  - the endpoint scheme security `RespanApiKey` was added to the API
- **2026-09-12** `22b868ef3f22`: 1 info
  - api operation id `list-prompts` removed and replaced with `prompts_listPrompts`

[Operation history](https://skmtc.dev/respan/apis/respan-api/changes/api/prompts/list/post.md)

---

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