Skip to main content
PUT
/
api
/
admin
/
prompts
/
:id
/
update
Update Prompt
curl --request PUT \
  --url https://api.example.com/api/admin/prompts/:id/update \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "<string>",
  "section": "<string>",
  "subSection": "<string>",
  "route": "<string>",
  "categories": [
    {}
  ],
  "tags": [
    {}
  ],
  "systemPrompt": "<string>",
  "userPromptTemplate": "<string>",
  "tone": "<string>",
  "outputFormat": "<string>",
  "fewShot": [
    {}
  ],
  "context": {},
  "isActive": true
}
'
{
  "400": {},
  "401": {},
  "403": {},
  "404": {},
  "409": {},
  "data": {}
}
Updates an existing prompt. A new version snapshot is automatically created on every update, preserving the full change history.

​
Authentication

Requires JWT Bearer token (Cognito) with admin role.

​
Path Parameters

​
id
string
required
Prompt UUID to updateFormat: UUIDExample: 550e8400-e29b-41d4-a716-446655440000

​
Request Body

All fields are optional — only provide the fields you want to update.
​
name
string
Updated prompt nameMax length: 200
​
section
string
Updated agent section assignmentValues: parser, gap_detector, risk_analysis, report_generation
​
subSection
string
Updated sub-sectionMax length: 100
​
route
string
Updated frontend route association
​
categories
array
Updated list of applicable risk categories
​
tags
array
Updated tags
​
systemPrompt
string
Updated system prompt
​
userPromptTemplate
string
Updated user prompt templateSupports variable substitution: {{category_1}}, {{category_2}}, {{categories}}
​
tone
string
Updated tone instructionsMax length: 500
​
outputFormat
string
Updated output format instructionsMax length: 5000
​
fewShot
array
Updated few-shot examplesEach example has:
  • input (string, required): Example user input
  • output (string, required): Expected model output
​
context
object
Updated context configurationProperties:
  • persona (string): System persona definition
  • sources (array): List of reference sources
  • constraints (string): Operational constraints
  • guardrails (string): Safety guardrails
​
isActive
boolean
Set to true to activate this promptMay deactivate other prompts in the same section to maintain the rule: only one active prompt per section.

​
Response

​
data
object
The updated prompt object with incremented version number

​
Example Request

curl -X PUT https://api.example.com/api/admin/prompts/550e8400-e29b-41d4-a716-446655440000/update \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Gap Detection — Market Risk v3",
    "tags": ["v3", "production", "reviewed"],
    "systemPrompt": "You are an expert agricultural risk analyst with 15+ years of experience in CGIAR research programmes. Analyze the provided business plan document and identify gaps in the risk assessment across the specified categories.",
    "isActive": true
  }'

​
Example Response

{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Gap Detection — Market Risk v3",
    "section": "gap_detector",
    "subSection": "Market Risk",
    "route": "/assessments/:id/gap-detector",
    "categories": ["Market Risk"],
    "tags": ["v3", "production", "reviewed"],
    "version": 3,
    "isActive": true,
    "systemPrompt": "You are an expert agricultural risk analyst with 15+ years of experience 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.",
    "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": 3,
    "createdById": "user-uuid-123",
    "updatedById": "user-uuid-456",
    "createdAt": "2026-02-20T10:00:00.000Z",
    "updatedAt": "2026-03-04T14:30:00.000Z"
  }
}

​
Error Responses

​
400
error
Validation error (invalid field values)
​
401
error
Missing or invalid Bearer token
​
403
error
Forbidden — admin role required
​
404
error
Prompt not found
​
409
error
Conflict — concurrent update detectedThis occurs when another user updated the prompt between your read and write operations.

​
Versioning

On every update:
  1. Current prompt state is snapshotted to prompt_versions table
  2. Prompt version is incremented
  3. Prompt record is updated with new values
  4. A change record is created in prompt_changes table with:
    • changeType: UPDATE
    • changes field containing field-level diffs (old vs new values)
    • authorId (user who made the change)
    • version (new version number)
This allows full audit trail and rollback capabilities.

​
Conflict Detection

The update endpoint implements optimistic locking:
  • If the prompt was modified by another user since you last read it, you’ll receive a 409 Conflict error
  • Re-fetch the latest version, review changes, and retry your update

​
Partial Updates

Only the fields you provide in the request body are updated: 
{
  "tags": ["v3", "reviewed"]
}
This will update only the tags field, leaving all other fields unchanged.

​
Source Code

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

Build docs developers (and LLMs) love

Get started for freeTalk to us