> For the complete documentation index, see [llms.txt](https://docs.castmagic.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.castmagic.io/endpoints/prompts.md).

# Prompts

List a space's prompt library and create recurring prompts.

Prompts drive AI content generation. A space's prompt library contains both Castmagic's built-in prompts and your own custom recurring prompts. Recurring prompts run automatically on every new recording in the space, and can also be run on demand via [`POST /v1/recordings/:id/generate`](/endpoints/generation.md).

{% hint style="info" %}
**Tier:** `GET /v1/prompts` is `core`. `POST /v1/prompts` requires `automation`. Base URL `https://app.castmagic.io`.
{% endhint %}

## List prompts

<mark style="color:blue;">`GET`</mark> `https://app.castmagic.io/v1/prompts`

**Tier:** `core`

#### Query Parameters

| Name      | Type   | Description                         |
| --------- | ------ | ----------------------------------- |
| space\_id | String | Defaults to the key's default space |

{% tabs %}
{% tab title="200: OK" %}

```json
{
    "space": { "id": "a1...", "name": "Acme Podcast" },
    "prompts": [
        {
            "id": "p1...",
            "name": "LinkedIn post",
            "type": "dynamic",
            "description": "Turn the episode into a LinkedIn post",
            "prompt": "Write a LinkedIn post summarizing...",
            "disabled": false
        }
    ],
    "count": 1
}
```

{% endtab %}
{% endtabs %}

## Create a recurring prompt

<mark style="color:green;">`POST`</mark> `https://app.castmagic.io/v1/prompts`

**Tier:** `automation`

Creates a recurring prompt on the space — it runs for every new recording, and can be run on demand via [`POST /v1/recordings/:id/generate`](/endpoints/generation.md).

#### Request Body

| Name                                     | Type   | Description                         |
| ---------------------------------------- | ------ | ----------------------------------- |
| name<mark style="color:red;">\*</mark>   | String | Display name for the prompt         |
| prompt<mark style="color:red;">\*</mark> | String | The prompt text                     |
| space\_id                                | String | Defaults to the key's default space |
| description                              | String | Optional description                |

{% tabs %}
{% tab title="201: Created" %}

```json
{
    "prompt": {
        "id": "p2...",
        "name": "LinkedIn post",
        "type": "dynamic",
        "description": null,
        "prompt": "Write a LinkedIn post summarizing...",
        "disabled": false
    }
}
```

{% endtab %}

{% tab title="403: Forbidden Recurring-prompt limit reached" %}

```json
{ "error": "your plan's recurring prompt limit has been reached" }
```

{% endtab %}
{% endtabs %}