Create Prompt Template

Sprint 3

Create a new prompt template with parameterization.

Endpoint

POST /api/v1/prompt-templates

Headers

Header	Required	Description
Authorization	Yes	Bearer <access_token>
Content-Type	Yes	application/json

Request Body

{
  "name": "Sales Report Template",
  "description": "Template for generating sales reports",
  "template_text": "Show me {{metric}} for {{time_period}}",
  "parameters": [
    {
      "name": "metric",
      "type": "string",
      "required": true,
      "description": "Metric to report on"
    },
    {
      "name": "time_period",
      "type": "string",
      "required": true,
      "default": "last_30_days"
    }
  ],
  "category": "reports",
  "tags": ["sales", "report"],
  "icon_url": "https://example.com/icon.png",
  "compatible_data_source_ids": [1, 2],
  "status": "published",
  "is_public": true
}

Parameters

Field	Type	Required	Description
name	string	Yes	Template name (1-255 characters)
description	string	No	Template description (max 500 characters)
template_text	string	Yes	Template text with placeholders like {{param}} (min length: 1)
parameters	array[object]	No	Template parameter definitions
category	string	Yes	Template category (1-100 characters)
tags	array[string]	No	Tags for categorization
icon_url	string	No	Icon file path or URL (max 512 characters)
compatible_data_source_ids	array[integer]	Yes	List of compatible data source IDs (min length: 1)
status	string	No	Template status: "draft" or "published" (default: "draft")
is_public	boolean	No	Shareable within organization (default: false)

Parameter Object

Field	Type	Required	Description
name	string	Yes	Parameter name
type	string	Yes	Parameter type
required	boolean	No	Required flag (default: true)
default	any	No	Default value
description	string	No	Parameter description

Response

Success (201)

{
  "success": true,
  "data": {
    "id": 1,
    "organization_id": 1,
    "name": "Sales Report Template",
    "description": "Template for generating sales reports",
    "template_text": "Show me {{metric}} for {{time_period}}",
    "parameters": [...],
    "category": "reports",
    "tags": ["sales", "report"],
    "status": "published",
    "compatible_data_source_ids": [1, 2],
    "is_system_template": false,
    "is_public": true,
    "usage_count": 0,
    "created_by_user_id": 1,
    "created_at": "2024-12-01T08:00:00Z"
  },
  "message": "Prompt template created successfully"
}

Error Codes

Status	Code	Description
400	BAD_REQUEST	Invalid request data
401	UNAUTHORIZED	Invalid or missing authentication token
500	INTERNAL_SERVER_ERROR	Internal server error

Template Syntax

• Use {{param_name}} for parameter placeholders
• Parameters are replaced with actual values during execution
• Example: "Show me {{metric}} for {{time_period}}" becomes "Show me sales for last_30_days"

Features

• Parameterized templates
• Category organization
• Public/private sharing
• Compatible data source specification
• Organization-scoped

Example

curl -X POST "https://api.rivergen.com/api/v1/prompt-templates" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Sales Report Template",
    "template_text": "Show me {{metric}} for {{time_period}}",
    "category": "reports",
    "compatible_data_source_ids": [1, 2]
  }'

Related Endpoints

• Execute Template - Execute template with parameters
• List Templates - List all templates