Execute Prompt

Sprint 3

Platform

Execute a natural language prompt. AI generates SQL query and executes it against selected data sources.

Account Type & Use Case

Platform Account

Platform APIs enable business users and analysts to query data using natural language, converting questions to SQL and executing across federated data sources without SQL expertise. This endpoint is used to ask questions in plain language and receive query results, democratizing data access and reducing dependency on data engineers.

Endpoint

POST /api/v1/prompts/execute

Headers

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

Request Body

{
  "prompt_text": "Show me total sales by region for the last quarter",
  "workspace_id": 1,
  "selected_data_source_ids": [1, 2],
  "selected_schema_names": ["public", "analytics"],
  "name": "Q4 Sales Report",
  "save_prompt": true,
  "ai_model": "gpt-4",
  "tags": ["sales", "quarterly"]
}

Parameters

Field	Type	Required	Description
prompt_text	string	Yes	Natural language prompt (min length: 1)
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: [])
name	string	No	Prompt name
save_prompt	boolean	No	Save prompt after execution (default: false)
ai_model	string	No	AI model to use
tags	array[string]	No	Tags for categorization

Response

Success - Processing (200)

{
  "success": true,
  "data": {
    "execution_id": 1,
    "prompt_id": null,
    "status": "processing",
    "ai_processing_status": "in_progress",
    "query_execution_status": null,
    "started_at": "2024-12-01T10:00:00Z",
    "progress_percentage": 30
  },
  "message": "Prompt execution started"
}

Success - Completed (200)

{
  "success": true,
  "data": {
    "execution_id": 1,
    "prompt_id": 5,
    "status": "completed",
    "ai_processing_status": "completed",
    "query_execution_status": "completed",
    "started_at": "2024-12-01T10:00:00Z",
    "ai_processing_started_at": "2024-12-01T10:00:00Z",
    "ai_processing_completed_at": "2024-12-01T10:00:05Z",
    "ai_response_time_ms": 5000,
    "query_execution_started_at": "2024-12-01T10:00:05Z",
    "query_execution_completed_at": "2024-12-01T10:00:10Z",
    "query_execution_duration_ms": 5000,
    "total_duration_ms": 10000,
    "completed_at": "2024-12-01T10:00:10Z",
    "generated_query_id": 10,
    "generated_query_text": "SELECT region, SUM(sales) FROM sales_data WHERE date >= '2024-09-01' GROUP BY region",
    "rows_returned": 5,
    "result_preview": [
      {"region": "North", "total_sales": 150000},
      {"region": "South", "total_sales": 200000}
    ],
    "ai_metadata": {
      "model": "gpt-4",
      "confidence": 0.95,
      "tokens_used": 150
    }
  },
  "message": "Prompt executed successfully"
}

Success - Failed (200)

{
  "success": true,
  "data": {
    "execution_id": 1,
    "status": "failed",
    "error_message": "Query execution failed: Connection timeout",
    "error_code": "QUERY_EXECUTION_ERROR"
  },
  "message": "Prompt execution failed"
}

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

Execution Flow

1. AI Processing: AI generates SQL query from natural language prompt
2. Query Execution: Generated query is executed against selected data sources
3. Result Return: Query results are returned with metadata

Status Values

• processing: AI is generating query or query is executing
• completed: Query executed successfully
• failed: Execution failed

Features

• Natural language to SQL conversion
• Multiple data source support
• Schema filtering
• Optional prompt saving
• AI model selection
• Execution tracking with detailed metadata
• Result preview

Example

curl -X POST "https://api.rivergen.com/api/v1/prompts/execute" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt_text": "Show me total sales by region",
    "selected_data_source_ids": [1, 2],
    "save_prompt": true
  }'

Related Endpoints

• Get Execution Status - Check execution status
• Get Execution History - Get execution history