> ## Documentation Index
> Fetch the complete documentation index at: https://alliancebioversityciat-alliance-risk-analysis-tool.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Prompt

Creates a new AI prompt. A version snapshot (v1) is automatically created. The prompt is inactive by default unless `isActive` is explicitly set to true.

## Authentication

Requires JWT Bearer token (Cognito) with **admin role**.

## Request Body

**name** `string` *required*

Human-readable prompt name

**Min length:** 1\
**Max length:** 200

**Example:** `Gap Detection — Market Risk v2`

**section** `string` *required*

The agent pipeline section this prompt belongs to

**Values:** `parser`, `gap_detector`, `risk_analysis`, `report_generation`

Determines which Bedrock agent will use it.

**subSection** `string`

Optional sub-section for further grouping within a section

**Max length:** 100

**Example:** `Market Risk`

**route** `string`

Frontend route that uses this prompt — useful for filtering in the Prompt Manager UI

**Example:** `/assessments/:id/gap-detector`

**categories** `array`

Risk category names this prompt applies to

**Example:** `["Market Risk", "Credit Risk"]`

**tags** `array`

Free-form tags for filtering and organization

**Example:** `["v2", "production", "reviewed"]`

**systemPrompt** `string` *required*

The system-level prompt sent to the model to establish persona, task, and constraints

**Min length:** 1

**Example:** `You are an expert agricultural risk analyst. Analyze the provided business plan document and identify gaps in the risk assessment across the specified categories.`

**userPromptTemplate** `string` *required*

The user-turn prompt template

**Min length:** 1

Supports variable substitution:

* `{{category_1}}` — First category
* `{{category_2}}` — Second category
* `{{categories}}` — Comma-separated list of all categories

**Example:**

```
Given the following business plan section:

{{document_excerpt}}

Identify gaps in risk coverage for the following categories: {{categories}}
```

**tone** `string`

Tone and style instructions for the model response

**Max length:** 500

**Example:** `Professional, analytical, concise. Use bullet points for lists. Avoid jargon.`

**outputFormat** `string`

Instructions for how the model should format its output

**Max length:** 5000

**Example:** `Return a JSON object with keys: "gaps" (array of strings), "severity" (low|medium|high), "recommendations" (array of strings)`

**fewShot** `array`

Few-shot examples to guide model behavior

Each example has:

* `input` (string, required): Example user input
* `output` (string, required): Expected model output

**Example:**

```json theme={null}
[
  {
    "input": "What are the main market risks for smallholder farmers?",
    "output": "The main market risks include price volatility, lack of market access, and limited contract farming opportunities."
  }
]
```

**context** `object`

Additional context configuration for persona, sources, constraints, and guardrails

**Properties:**

* `persona` (string): System persona definition
* `sources` (array): List of reference sources
* `constraints` (string): Operational constraints
* `guardrails` (string): Safety guardrails

**Example:**

```json theme={null}
{
  "persona": "You are an expert agricultural risk analyst specializing in CGIAR research programmes.",
  "sources": ["CGIAR Research Programs", "FAO Risk Framework"],
  "constraints": "Respond only based on the provided document. Do not speculate beyond the evidence.",
  "guardrails": "Do not provide specific investment advice. Do not name individual companies."
}
```

**isActive** `boolean` (default: false)

Whether this prompt is active and used by Bedrock agents

Only one prompt per section should be active at a time.

## Response

**data** `object`

The created prompt object

Includes all fields from the request plus:

* `id` (string): Generated UUID
* `version` (number): Initial version (1)
* `commentsCount` (number): Initial count (0)
* `createdById` (string): UUID of creating user
* `updatedById` (string): UUID of creating user
* `createdAt` (string): ISO 8601 timestamp
* `updatedAt` (string): ISO 8601 timestamp

## Example Request

```bash theme={null}
curl -X POST https://api.example.com/api/admin/prompts/create \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Gap Detection — Market Risk v2",
    "section": "gap_detector",
    "subSection": "Market Risk",
    "route": "/assessments/:id/gap-detector",
    "categories": ["Market Risk"],
    "tags": ["v2", "production"],
    "systemPrompt": "You are an expert agricultural risk analyst. Analyze the provided business plan document and identify gaps in the risk assessment across the specified categories.",
    "userPromptTemplate": "Given the following business plan section:\n\n{{document_excerpt}}\n\nIdentify gaps in risk coverage for the following categories: {{categories}}",
    "tone": "Professional, analytical, concise. Use bullet points for lists.",
    "outputFormat": "Return a JSON object with keys: 'gaps' (array of strings), 'severity' (low|medium|high), 'recommendations' (array of strings)",
    "fewShot": [
      {
        "input": "What are the main market risks?",
        "output": "The main market risks include price volatility, lack of market access, and limited contract farming opportunities."
      }
    ],
    "context": {
      "persona": "Expert agricultural risk analyst specializing in CGIAR research.",
      "sources": ["CGIAR Research Programs", "FAO Risk Framework"],
      "constraints": "Respond only based on the provided document.",
      "guardrails": "Do not provide investment advice."
    },
    "isActive": true
  }'
```

## Example Response

```json theme={null}
{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Gap Detection — Market Risk v2",
    "section": "gap_detector",
    "subSection": "Market Risk",
    "route": "/assessments/:id/gap-detector",
    "categories": ["Market Risk"],
    "tags": ["v2", "production"],
    "version": 1,
    "isActive": true,
    "systemPrompt": "You are an expert agricultural risk analyst. Analyze the provided business plan document and identify gaps in the risk assessment across the specified categories.",
    "userPromptTemplate": "Given the following business plan section:\n\n{{document_excerpt}}\n\nIdentify gaps in risk coverage for the following categories: {{categories}}",
    "tone": "Professional, analytical, concise. Use bullet points for lists.",
    "outputFormat": "Return a JSON object with keys: 'gaps' (array of strings), 'severity' (low|medium|high), 'recommendations' (array of strings)",
    "fewShot": [
      {
        "input": "What are the main market risks?",
        "output": "The main market risks include price volatility, lack of market access, and limited contract farming opportunities."
      }
    ],
    "context": {
      "persona": "Expert agricultural risk analyst specializing in CGIAR research.",
      "sources": ["CGIAR Research Programs", "FAO Risk Framework"],
      "constraints": "Respond only based on the provided document.",
      "guardrails": "Do not provide investment advice."
    },
    "commentsCount": 0,
    "createdById": "user-uuid-123",
    "updatedById": "user-uuid-123",
    "createdAt": "2026-03-04T12:00:00.000Z",
    "updatedAt": "2026-03-04T12:00:00.000Z"
  }
}
```

## Error Responses

**400** `error`

Validation error (missing required fields, invalid length, etc.)

**401** `error`

Missing or invalid Bearer token

**403** `error`

Forbidden — admin role required

## Versioning

When a prompt is created:

1. The prompt record is created in the `prompts` table with `version: 1`
2. A snapshot is automatically saved to `prompt_versions` table
3. A change record is created in `prompt_changes` table with type `CREATE`

This preserves full audit history from the moment of creation.

## Source Code

Implementation: `packages/api/src/prompts/prompts.controller.ts:64`


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