Create Prompt

Create Prompt

curl --request POST \
  --url https://api.example.com/api/admin/prompts/create \
  --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
}
'

import requests

url = "https://api.example.com/api/admin/prompts/create"

payload = {
    "name": "<string>",
    "section": "<string>",
    "subSection": "<string>",
    "route": "<string>",
    "categories": [{}],
    "tags": [{}],
    "systemPrompt": "<string>",
    "userPromptTemplate": "<string>",
    "tone": "<string>",
    "outputFormat": "<string>",
    "fewShot": [{}],
    "context": {},
    "isActive": True
}
headers = {"Content-Type": "application/json"}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({
    name: '<string>',
    section: '<string>',
    subSection: '<string>',
    route: '<string>',
    categories: [{}],
    tags: [{}],
    systemPrompt: '<string>',
    userPromptTemplate: '<string>',
    tone: '<string>',
    outputFormat: '<string>',
    fewShot: [{}],
    context: {},
    isActive: true
  })
};

fetch('https://api.example.com/api/admin/prompts/create', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.example.com/api/admin/prompts/create",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'name' => '<string>',
    'section' => '<string>',
    'subSection' => '<string>',
    'route' => '<string>',
    'categories' => [
        [
                
        ]
    ],
    'tags' => [
        [
                
        ]
    ],
    'systemPrompt' => '<string>',
    'userPromptTemplate' => '<string>',
    'tone' => '<string>',
    'outputFormat' => '<string>',
    'fewShot' => [
        [
                
        ]
    ],
    'context' => [
        
    ],
    'isActive' => true
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/api/admin/prompts/create"

	payload := strings.NewReader("{\n  \"name\": \"<string>\",\n  \"section\": \"<string>\",\n  \"subSection\": \"<string>\",\n  \"route\": \"<string>\",\n  \"categories\": [\n    {}\n  ],\n  \"tags\": [\n    {}\n  ],\n  \"systemPrompt\": \"<string>\",\n  \"userPromptTemplate\": \"<string>\",\n  \"tone\": \"<string>\",\n  \"outputFormat\": \"<string>\",\n  \"fewShot\": [\n    {}\n  ],\n  \"context\": {},\n  \"isActive\": true\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.example.com/api/admin/prompts/create")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"<string>\",\n  \"section\": \"<string>\",\n  \"subSection\": \"<string>\",\n  \"route\": \"<string>\",\n  \"categories\": [\n    {}\n  ],\n  \"tags\": [\n    {}\n  ],\n  \"systemPrompt\": \"<string>\",\n  \"userPromptTemplate\": \"<string>\",\n  \"tone\": \"<string>\",\n  \"outputFormat\": \"<string>\",\n  \"fewShot\": [\n    {}\n  ],\n  \"context\": {},\n  \"isActive\": true\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.example.com/api/admin/prompts/create")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"name\": \"<string>\",\n  \"section\": \"<string>\",\n  \"subSection\": \"<string>\",\n  \"route\": \"<string>\",\n  \"categories\": [\n    {}\n  ],\n  \"tags\": [\n    {}\n  ],\n  \"systemPrompt\": \"<string>\",\n  \"userPromptTemplate\": \"<string>\",\n  \"tone\": \"<string>\",\n  \"outputFormat\": \"<string>\",\n  \"fewShot\": [\n    {}\n  ],\n  \"context\": {},\n  \"isActive\": true\n}"

response = http.request(request)
puts response.read_body

{
  "400": {},
  "401": {},
  "403": {},
  "data": {}
}

POST

api

admin

prompts

create

Create Prompt

curl --request POST \
  --url https://api.example.com/api/admin/prompts/create \
  --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
}
'

import requests

url = "https://api.example.com/api/admin/prompts/create"

payload = {
    "name": "<string>",
    "section": "<string>",
    "subSection": "<string>",
    "route": "<string>",
    "categories": [{}],
    "tags": [{}],
    "systemPrompt": "<string>",
    "userPromptTemplate": "<string>",
    "tone": "<string>",
    "outputFormat": "<string>",
    "fewShot": [{}],
    "context": {},
    "isActive": True
}
headers = {"Content-Type": "application/json"}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({
    name: '<string>',
    section: '<string>',
    subSection: '<string>',
    route: '<string>',
    categories: [{}],
    tags: [{}],
    systemPrompt: '<string>',
    userPromptTemplate: '<string>',
    tone: '<string>',
    outputFormat: '<string>',
    fewShot: [{}],
    context: {},
    isActive: true
  })
};

fetch('https://api.example.com/api/admin/prompts/create', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.example.com/api/admin/prompts/create",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'name' => '<string>',
    'section' => '<string>',
    'subSection' => '<string>',
    'route' => '<string>',
    'categories' => [
        [
                
        ]
    ],
    'tags' => [
        [
                
        ]
    ],
    'systemPrompt' => '<string>',
    'userPromptTemplate' => '<string>',
    'tone' => '<string>',
    'outputFormat' => '<string>',
    'fewShot' => [
        [
                
        ]
    ],
    'context' => [
        
    ],
    'isActive' => true
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/api/admin/prompts/create"

	payload := strings.NewReader("{\n  \"name\": \"<string>\",\n  \"section\": \"<string>\",\n  \"subSection\": \"<string>\",\n  \"route\": \"<string>\",\n  \"categories\": [\n    {}\n  ],\n  \"tags\": [\n    {}\n  ],\n  \"systemPrompt\": \"<string>\",\n  \"userPromptTemplate\": \"<string>\",\n  \"tone\": \"<string>\",\n  \"outputFormat\": \"<string>\",\n  \"fewShot\": [\n    {}\n  ],\n  \"context\": {},\n  \"isActive\": true\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.example.com/api/admin/prompts/create")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"<string>\",\n  \"section\": \"<string>\",\n  \"subSection\": \"<string>\",\n  \"route\": \"<string>\",\n  \"categories\": [\n    {}\n  ],\n  \"tags\": [\n    {}\n  ],\n  \"systemPrompt\": \"<string>\",\n  \"userPromptTemplate\": \"<string>\",\n  \"tone\": \"<string>\",\n  \"outputFormat\": \"<string>\",\n  \"fewShot\": [\n    {}\n  ],\n  \"context\": {},\n  \"isActive\": true\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.example.com/api/admin/prompts/create")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"name\": \"<string>\",\n  \"section\": \"<string>\",\n  \"subSection\": \"<string>\",\n  \"route\": \"<string>\",\n  \"categories\": [\n    {}\n  ],\n  \"tags\": [\n    {}\n  ],\n  \"systemPrompt\": \"<string>\",\n  \"userPromptTemplate\": \"<string>\",\n  \"tone\": \"<string>\",\n  \"outputFormat\": \"<string>\",\n  \"fewShot\": [\n    {}\n  ],\n  \"context\": {},\n  \"isActive\": true\n}"

response = http.request(request)
puts response.read_body

{
  "400": {},
  "401": {},
  "403": {},
  "data": {}
}

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

string

required

Human-readable prompt nameMin length: 1
Max length: 200Example: Gap Detection — Market Risk v2

string

required

The agent pipeline section this prompt belongs toValues: parser, gap_detector, risk_analysis, report_generationDetermines which Bedrock agent will use it.

string

Optional sub-section for further grouping within a sectionMax length: 100Example: Market Risk

string

Frontend route that uses this prompt — useful for filtering in the Prompt Manager UIExample: /assessments/:id/gap-detector

array

Risk category names this prompt applies toExample: ["Market Risk", "Credit Risk"]

array

Free-form tags for filtering and organizationExample: ["v2", "production", "reviewed"]

string

required

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.

string

required

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}}

string

Tone and style instructions for the model responseMax length: 500Example: Professional, analytical, concise. Use bullet points for lists. Avoid jargon.

string

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)

array

Few-shot examples to guide model behaviorEach example has:

input (string, required): Example user input
output (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."
  }
]

object

Additional context configuration for persona, sources, constraints, and guardrailsProperties:

persona (string): System persona definition
sources (array): List of reference sources
constraints (string): Operational constraints
guardrails (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."
}

boolean

default:"false"

Whether this prompt is active and used by Bedrock agentsOnly one prompt per section should be active at a time.

Response

object

The created prompt objectIncludes 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

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

error

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

error

Missing or invalid Bearer token

error

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

Authentication

Assessments

Jobs

Prompts

Admin

Authentication

Request Body

Response

Example Request

Example Response

Error Responses

Versioning

Source Code

​Authentication

​Request Body

​Response

​Example Request

​Example Response

​Error Responses

​Versioning

​Source Code

Authentication

Request Body

Response

Example Request

Example Response

Error Responses

Versioning

Source Code