Skip to main content
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 for schema details.

​
Endpoints & cURL snippets

​
Create (admin)

POST /api/v1/preprompts 
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 
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} 
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} 
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 
curl -X GET https://api.handauncle.com/api/v1/public/preprompts
Example response: 
{
  "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.