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

# Create prompts

> POST /v1/sites/{site_id}/prompts

> [!NOTE]
>
> Needs a key with **Read and manage prompts** access. Counts against the write limit of 20 requests a minute.

Add up to 100 prompts. A prompt whose text already exists (ignoring case and spacing) is returned as it is rather than duplicated, so retrying is safe. Active prompts count against the plan's cap; a request that would exceed it is refused whole with `422 prompt_limit_reached`, and `details` says how many slots remain. `dry_run` validates and reports without writing.

> [!WARNING]
>
> Every active prompt is asked on every engine every day. Adding prompts changes what your plan measures from the next daily scan onward.

## Path parameters

**site\_id** `string` *required*

The site's id, from [List sites](/api-reference/endpoints/list-sites).

## Body

**prompts** `object[]` *required*

1 to 100 prompts.

**properties**

**text** `string` *required*

The question, 3 to 300 characters.

**category** `enum\<string\>` (default: Discovery)

One of: `Discovery`, `Comparison`, `Alternatives`, `How-to`, `Pricing`, `Brand`.

**market** `string`

Location for this prompt, e.g. `Lahore, Pakistan`. Omit or null to use the site's market.

**active** `boolean` (default: true)

Create it switched off with `false`.

**dry\_run** `boolean` (default: false)

Validate and report without writing.

## Response

**dry\_run** `boolean`

**created** `number`

Prompts that are new.

**existing** `number`

Prompts that already existed and were returned unchanged.

**data** `object[]`

Every prompt in the request, new and existing. On a dry run new prompts have no `id` yet.

**properties**

**id** `string`

**text** `string`

**category** `enum\<string\>`

One of: `Discovery`, `Comparison`, `Alternatives`, `How-to`, `Pricing`, `Brand`.

**market** `string`

**status** `enum\<string\>`

One of: `active`, `disabled`.

**created\_at** `string`

**updated\_at** `string`

```bash cURL theme={"system"}
curl -X POST https://api.rankraft.ai/v1/sites/3f2c9a10-7b1e-4c55-9d2a-1a2b3c4d5e6f/prompts \
  -H "X-API-Key: $RANKRAFT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompts": [
      { "text": "best mixed pickle brand", "category": "Discovery" },
      { "text": "achar price per kg", "category": "Pricing", "active": false }
    ],
    "dry_run": false
  }'
```

```javascript JavaScript theme={"system"}
// npm install rankraft-js · https://www.npmjs.com/package/rankraft-js
import { RankRaft, PromptLimitError } from "rankraft-js";

const rr = new RankRaft(); // reads RANKRAFT_API_KEY (needs "Read and manage prompts")

try {
  const result = await rr.prompts.create({
    site_id: "3f2c9a10-7b1e-4c55-9d2a-1a2b3c4d5e6f",
    prompts: [
      { text: "best mixed pickle brand", category: "Discovery" },
      { text: "achar price per kg", category: "Pricing", active: false },
    ],
    dry_run: false,
  });
  console.log(result.created, result.existing);
} catch (err) {
  if (err instanceof PromptLimitError) console.log(`Only ${err.remaining} slots left`);
  else throw err;
}
```

```python Python theme={"system"}
# pip install rankraft-py · https://pypi.org/project/rankraft-py/
from rankraft import RankRaft, PromptLimitError

with RankRaft() as rr:  # reads RANKRAFT_API_KEY (needs "Read and manage prompts")
    try:
        result = rr.prompts.create(
            site_id="3f2c9a10-7b1e-4c55-9d2a-1a2b3c4d5e6f",
            prompts=[
                {"text": "best mixed pickle brand", "category": "Discovery"},
                {"text": "achar price per kg", "category": "Pricing", "active": False},
            ],
            dry_run=False,
        )
        print(result["created"], result["existing"])
    except PromptLimitError as err:
        print(f"Only {err.remaining} slots left")
```

```json 200 theme={"system"}
{
  "dry_run": false,
  "created": 1,
  "existing": 1,
  "data": [
    {
      "id": "8a1e4b2c-6d0f-4e3a-9b51-2c7d8e9f0a1b",
      "text": "best mixed pickle brand",
      "category": "Discovery",
      "market": null,
      "status": "active",
      "created_at": "2026-09-02T08:12:00.000Z",
      "updated_at": "2026-09-02T08:12:00.000Z"
    },
    {
      "id": "0c4f1d7e-2a9b-4c3d-8e5f-6a7b8c9d0e1f",
      "text": "achar price per kg",
      "category": "Pricing",
      "market": null,
      "status": "disabled",
      "created_at": "2026-10-16T09:00:00.000Z",
      "updated_at": "2026-10-16T09:00:00.000Z"
    }
  ]
}
```

```json 422 theme={"system"}
{
  "error": {
    "code": "prompt_limit_reached",
    "message": "This would make 501 active prompts; the enterprise plan allows 500.",
    "details": { "limit": 500, "active": 500, "requested": 1, "remaining": 0 }
  },
  "request_id": "8c1f2a3b4c5d6e7f-LHR"
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.