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
Human-readable prompt nameMin length: 1
Max length: 200Example: Gap Detection — Market Risk v2
The agent pipeline section this prompt belongs toValues: parser, gap_detector, risk_analysis, report_generationDetermines which Bedrock agent will use it.
Optional sub-section for further grouping within a sectionMax length: 100Example: Market Risk
Frontend route that uses this prompt — useful for filtering in the Prompt Manager UIExample: /assessments/:id/gap-detector
Risk category names this prompt applies toExample: ["Market Risk", "Credit Risk"]
Free-form tags for filtering and organizationExample: ["v2", "production", "reviewed"]
The system-level prompt sent to the model to establish persona, task, and constraintsMin length: 1Example: You are an expert agricultural risk analyst. Analyze the provided business plan document and identify gaps in the risk assessment across the specified categories.
The user-turn prompt templateMin length: 1Supports 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 and style instructions for the model responseMax length: 500Example: Professional, analytical, concise. Use bullet points for lists. Avoid jargon.
Instructions for how the model should format its outputMax length: 5000Example: Return a JSON object with keys: "gaps" (array of strings), "severity" (low|medium|high), "recommendations" (array of strings)
Few-shot examples to guide model behaviorEach example has:
input (string, required): Example user inputoutput (string, required): Expected model output
Example:[
{
"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."
}
]
Additional context configuration for persona, sources, constraints, and guardrailsProperties:
persona (string): System persona definitionsources (array): List of reference sourcesconstraints (string): Operational constraintsguardrails (string): Safety guardrails
Example:{
"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."
}
Whether this prompt is active and used by Bedrock agentsOnly one prompt per section should be active at a time.
Response
The created prompt objectIncludes all fields from the request plus:
id (string): Generated UUIDversion (number): Initial version (1)commentsCount (number): Initial count (0)createdById (string): UUID of creating userupdatedById (string): UUID of creating usercreatedAt (string): ISO 8601 timestampupdatedAt (string): ISO 8601 timestamp
Example Request
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
{
"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
Validation error (missing required fields, invalid length, etc.)
Missing or invalid Bearer token
Forbidden — admin role required
Versioning
When a prompt is created:
- The prompt record is created in the
prompts table with version: 1
- A snapshot is automatically saved to
prompt_versions table
- 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 
