> ## 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.

# List Prompts

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 section

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

**Example:** `gap_detector`

**route** `string`

Filter by associated frontend route

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

**tag** `string`

Filter by a specific tag

**Example:** `production`

**search** `string`

Full-text search across prompt name, system prompt, and user prompt template

**Example:** `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:** 1

**Example:** `2`

**limit** `number` (default: 20)

Number of results per page

**Minimum:** 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 section

**Values:** `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 prompt

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

**prompts\[].categories** `array`

Risk category names this prompt applies to

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

**prompts\[].tags** `array`

Free-form tags for filtering and organization

**Example:** `["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 agents

Only 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 support

**Variables:** `{{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 guidance

Each 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

```bash theme={null}
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

```json theme={null}
{
  "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`


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