Execute Template

Sprint 3

Execute a prompt template with provided parameters.

Endpoint

POST /api/v1/prompt-templates/{template_id}/execute

Headers

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

Path Parameters

Parameter	Type	Required	Description
template_id	integer	Yes	Template ID

Request Body

{
  "workspace_id": 1,
  "selected_data_source_ids": [1, 2],
  "selected_schema_names": ["public"],
  "parameters": {
    "metric": "sales",
    "time_period": "last_30_days"
  },
  "save_prompt": true
}

Parameters

Field	Type	Required	Description
workspace_id	integer	No	Workspace ID
selected_data_source_ids	array[integer]	Yes	Array of data source IDs (min length: 1)
selected_schema_names	array[string]	No	Array of schema names to include (default: [])
parameters	object	No	Template parameter values (default: )
save_prompt	boolean	No	Save prompt after execution (default: false)

Response

Success - Processing (200)

{
  "success": true,
  "data": {
    "execution_id": 1,
    "status": "processing",
    "ai_processing_status": "in_progress"
  },
  "message": "Template execution started"
}

Success - Completed (200)

{
  "success": true,
  "data": {
    "execution_id": 1,
    "prompt_id": 5,
    "status": "completed",
    "generated_query_text": "SELECT region, SUM(sales) FROM sales_data WHERE date >= '2024-11-01' GROUP BY region",
    "rows_returned": 5,
    "result_preview": [...]
  },
  "message": "Template executed successfully"
}

Error Codes

Status	Code	Description
400	BAD_REQUEST	Invalid request data
401	UNAUTHORIZED	Invalid or missing authentication token
404	NOT_FOUND	Template not found
500	INTERNAL_SERVER_ERROR	Internal server error

Features

• Parameter substitution in template text
• Multiple data source support
• Schema filtering
• Optional prompt saving
• Execution tracking
• Organization-scoped access control

Parameter Substitution

Template parameters are replaced in the template text:

• Template: "Show me {{metric}} for {{time_period}}"
• Parameters: {"metric": "sales", "time_period": "last_30_days"}
• Result: "Show me sales for last_30_days"

Example

curl -X POST "https://api.rivergen.com/api/v1/prompt-templates/1/execute" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "selected_data_source_ids": [1, 2],
    "parameters": {
      "metric": "sales",
      "time_period": "last_30_days"
    }
  }'

Related Endpoints

• Get Template - Get template details
• Get Execution Status - Check execution status