Prompt Management

Version-controlled prompt templates with Jinja2 rendering, A/B testing, and analytics. Manage prompts as code — versioned, diffable, and testable.

How It Works

Prompts are stored as versioned templates identified by a slug. Each version has a lifecycle: draft → published → archived. Only one version can be published at a time.

Create a Prompt

curl https://api.agilecloud.ai/api/v1/prompts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "slug": "summarize",
    "name": "Document Summarizer",
    "description": "Summarizes a document in the given language",
    "template": "Summarize the following document in {{ language }}:\n\n{{ document }}",
    "variables": ["language", "document"],
    "model": "qwen-2.5-3b"
  }'

Render a Template

Render a prompt with variables using Jinja2 template syntax. Supports loops, conditionals, filters, and default values.

curl https://api.agilecloud.ai/api/v1/prompts/summarize/render \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "variables": {
      "language": "Spanish",
      "document": "DirectAI deploys inference inside..."
    }
  }'

# Response
{
  "rendered": "Summarize the following document in Spanish:\n\nDirectAI deploys inference inside..."
}

Versioning

Create new versions, diff between them, and publish when ready.

# Create a new version (draft)
curl -X POST https://api.agilecloud.ai/api/v1/prompts/summarize/versions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "template": "Provide a concise {{ language }} summary of:\n\n{{ document }}",
    "change_note": "More concise phrasing"
  }'

# Publish the draft
curl -X POST https://api.agilecloud.ai/api/v1/prompts/summarize/versions/2/publish \
  -H "Authorization: Bearer YOUR_API_KEY"

# Diff two versions
curl "https://api.agilecloud.ai/api/v1/prompts/summarize/diff?v1=1&v2=2" \
  -H "Authorization: Bearer YOUR_API_KEY"

A/B Testing

Split traffic between two prompt versions to compare performance. Results include per-version latency, token usage, and user ratings.

# Start A/B test
curl https://api.agilecloud.ai/api/v1/prompts/summarize/ab-test \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "version_a": 1,
    "version_b": 2,
    "traffic_split": 0.5
  }'

# Check results
curl https://api.agilecloud.ai/api/v1/prompts/summarize/ab-results \
  -H "Authorization: Bearer YOUR_API_KEY"

Endpoints

Method	Path	Description
POST	/api/v1/prompts	Create prompt
GET	/api/v1/prompts	List prompts
GET	/api/v1/prompts/{slug}	Get prompt
PATCH	/api/v1/prompts/{slug}	Update metadata
DELETE	/api/v1/prompts/{slug}	Archive prompt
POST	/api/v1/prompts/{slug}/versions	Create draft version
POST	/api/v1/prompts/{slug}/versions/{ver}/publish	Publish draft
POST	/api/v1/prompts/{slug}/render	Render with variables
POST	/api/v1/prompts/{slug}/ab-test	Start A/B test
GET	/api/v1/prompts/{slug}/ab-results	A/B test results

Template Syntax

Prompts use standard Jinja2 syntax. Variables are wrapped in {{ }}, conditionals use {% if %}, and filters are available via pipes ( {{ name | upper }}). Undefined variables raise a render error rather than silently producing empty strings.

Using Prompts in Batch

Prompt templates can be used in batch JSONL files by replacing messages with prompt_slug and variables. See the Batch API docs for the full JSONL format and examples.