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

# PrePrompt Management

> Admin endpoints for defining masked pre-prompts plus the public catalog used by clients.

PrePrompts let you present friendly, human-readable prompt suggestions to end-users
while sending a different (masked) instruction to the LLM. Each pre-prompt stores:

* a unique `key` (used by clients),
* the `public_value` shown in UI menus,
* the `masked_value` injected after the system prompt,
* optional `description` and `tags`.

## Authentication

Administrative endpoints live under `/api/v1/preprompts` and are protected by the
`backendSecretMiddleware`. Send either:

```
Authorization: Bearer <BACKEND_SECRET>
```

or

```
X-Backend-Secret: <BACKEND_SECRET>
```

where `BACKEND_SECRET` is configured in your environment variables. Requests without
this token receive `401 BACKEND_SECRET_REQUIRED`.

## Quick start

1. **Create** the masked prompt via the admin API (requires `BACKEND_SECRET`).
2. **Surface** the public catalog (`GET /api/v1/public/preprompts`) to end-users.
3. **Send** the chosen `preprompt_key` along with every `/api/v1/ai/chat` call.

All records persist inside the MongoDB `preprompts` collection—see the
[PrePrompts guide](/codebase/preprompts) for schema details.

## Endpoints & cURL snippets

### Create (admin)

`POST /api/v1/preprompts`

```bash theme={null}
curl -X POST https://api.handauncle.com/api/v1/preprompts \
  -H "Authorization: Bearer $BACKEND_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
        "key": "wealth_tax",
        "public_value": "Ask Handa Uncle for wealth tax help",
        "masked_value": "You are a chartered accountant specialising in wealth tax...",
        "description": "Personalised CA instructions for complex filings",
        "tags": ["tax", "advisor"]
      }'
```

Returns the created document with metadata. Reusing an active key triggers `409 CONFLICT`.

### List (admin)

`GET /api/v1/preprompts?include_deleted=false`

```bash theme={null}
curl -X GET "https://api.handauncle.com/api/v1/preprompts?include_deleted=false" \
  -H "X-Backend-Secret: $BACKEND_SECRET"
```

The optional `include_deleted=true` flag reveals soft-deleted rows to help with audits.

### Update (admin)

`PUT /api/v1/preprompts/{id}`

```bash theme={null}
curl -X PUT https://api.handauncle.com/api/v1/preprompts/<id> \
  -H "Authorization: Bearer $BACKEND_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
        "public_value": "Ask for personalised wealth tax advice",
        "masked_value": "You are an Indian chartered accountant...",
        "tags": ["tax","priority"]
      }'
```

Patch any subset of fields (`key`, `public_value`, `masked_value`, `description`, `tags`).
Key changes remain unique across deleted items as well.

### Soft-delete (admin)

`DELETE /api/v1/preprompts/{id}`

```bash theme={null}
curl -X DELETE https://api.handauncle.com/api/v1/preprompts/<id> \
  -H "X-Backend-Secret: $BACKEND_SECRET"
```

The record simply flips `is_deleted=true`, allowing instant restoration via `PUT` or re-`POST`.

### Public catalog (no auth)

`GET /api/v1/public/preprompts`

```bash theme={null}
curl -X GET https://api.handauncle.com/api/v1/public/preprompts
```

Example response:

```json theme={null}
{
  "success": true,
  "data": [
    {
      "key": "wealth_tax",
      "public_value": "Ask Handa Uncle for wealth tax help",
      "description": "Connects you with CA-style guidance",
      "tags": ["tax","advisor"]
    }
  ]
}
```

Front-ends should render these public labels and pass the corresponding `preprompt_key`
to `/api/v1/ai/chat`. Only the backend ever accesses `masked_value`, keeping internal
instructions hidden from clients.