Skip to main content
GET
/
api
/
admin
/
prompts
/
list
List Prompts
curl --request GET \
  --url https://api.example.com/api/admin/prompts/list
{
  "401": {},
  "403": {},
  "data": {
    "data.prompts": [
      {
        "prompts[].id": "<string>",
        "prompts[].name": "<string>",
        "prompts[].section": "<string>",
        "prompts[].subSection": "<string>",
        "prompts[].route": "<string>",
        "prompts[].categories": [
          {}
        ],
        "prompts[].tags": [
          {}
        ],
        "prompts[].version": 123,
        "prompts[].isActive": true,
        "prompts[].systemPrompt": "<string>",
        "prompts[].userPromptTemplate": "<string>",
        "prompts[].tone": "<string>",
        "prompts[].outputFormat": "<string>",
        "prompts[].fewShot": [
          {}
        ],
        "prompts[].context": {},
        "prompts[].commentsCount": 123,
        "prompts[].createdAt": "<string>",
        "prompts[].updatedAt": "<string>"
      }
    ],
    "data.total": 123,
    "data.page": 123,
    "data.limit": 123,
    "data.totalPages": 123
  }
}
Returns a paginated list of AI prompts with optional filtering by section, route, tag, search term, and active status.

​
Authentication

Requires JWT Bearer token (Cognito) with admin role.

​
Query Parameters

​
section
string
Filter by agent pipeline sectionValues: parser, gap_detector, risk_analysis, report_generationExample: gap_detector
​
route
string
Filter by associated frontend routeExample: /assessments/:id/gap-detector
​
tag
string
Filter by a specific tagExample: production
​
search
string
Full-text search across prompt name, system prompt, and user prompt templateExample: market risk
​
isActive
boolean
Filter by active status
  • true — active prompts only
  • false — inactive prompts only
  • omit — all prompts
​
page
number
default:"1"
Page number (1-indexed)Minimum: 1Example: 2
​
limit
number
default:"20"
Number of results per pageMinimum: 1
Maximum: 100
Default: 20

​
Response

​
data
object
Paginated prompt list container
​
data.prompts
array
Array of prompt objects
​
prompts[].id
string
Prompt UUID
​
prompts[].name
string
Human-readable prompt name (max 200 characters)Example: Gap Detection — Market Risk v2
​
prompts[].section
string
Agent pipeline sectionValues: parser, gap_detector, risk_analysis, report_generation
​
prompts[].subSection
string
Optional sub-section grouping (max 100 characters)Example: Market Risk
​
prompts[].route
string
Frontend route that uses this promptExample: /assessments/:id/gap-detector
​
prompts[].categories
array
Risk category names this prompt applies toExample: ["Market Risk", "Credit Risk"]
​
prompts[].tags
array
Free-form tags for filtering and organizationExample: ["v2", "production", "reviewed"]
​
prompts[].version
number
Current version number (auto-incremented on update)
​
prompts[].isActive
boolean
Whether this prompt is active and used by Bedrock agentsOnly one prompt per section should be active at a time.
​
prompts[].systemPrompt
string
System-level prompt establishing persona, task, and constraints
​
prompts[].userPromptTemplate
string
User-turn prompt template with variable substitution supportVariables: {{category_1}}, {{category_2}}, {{categories}}
​
prompts[].tone
string
Tone and style instructions (max 500 characters)Example: Professional, analytical, concise. Use bullet points.
​
prompts[].outputFormat
string
Output format instructions (max 5000 characters)Example: Return JSON with keys: gaps, severity, recommendations
​
prompts[].fewShot
array
Few-shot examples for model guidanceEach example has:
  • input (string): Example user input
  • output (string): Expected model output
​
prompts[].context
object
Additional context configuration
  • persona (string): Persona definition
  • sources (array): Reference sources
  • constraints (string): Operational constraints
  • guardrails (string): Safety guardrails
​
prompts[].commentsCount
number
Number of comments on this prompt (denormalized for performance)
​
prompts[].createdAt
string
ISO 8601 timestamp of creation
​
prompts[].updatedAt
string
ISO 8601 timestamp of last update
​
data.total
number
Total number of prompts matching the filters
​
data.page
number
Current page number (1-indexed)
​
data.limit
number
Number of results per page
​
data.totalPages
number
Total number of pages

​
Example Request

curl -X GET "https://api.example.com/api/admin/prompts/list?section=gap_detector&isActive=true&page=1&limit=10" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

​
Example Response

{
  "data": {
    "prompts": [
      {
        "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", "reviewed"],
        "version": 2,
        "isActive": true,
        "systemPrompt": "You are an expert agricultural risk analyst specializing in CGIAR research programmes. 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. Avoid jargon.",
        "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 for smallholder farmers?",
            "output": "The main market risks include price volatility, lack of market access, and limited contract farming opportunities."
          }
        ],
        "context": {
          "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."
        },
        "commentsCount": 3,
        "createdAt": "2026-02-20T10:00:00.000Z",
        "updatedAt": "2026-03-01T14:30:00.000Z"
      }
    ],
    "total": 1,
    "page": 1,
    "limit": 10,
    "totalPages": 1
  }
}

​
Error Responses

​
401
error
Missing or invalid Bearer token
​
403
error
Forbidden — admin role required

​
Source Code

Implementation: packages/api/src/prompts/prompts.controller.ts:53

Build docs developers (and LLMs) love

Get started for freeTalk to us