Prompts API

Create, manage, and execute prompts programmatically.

Endpoints

Create Prompt

POST /v1/prompts

Create a new prompt.

Request:

{
  "name": "customer-classifier",
  "description": "Classifies customer support tickets",
  "template": "Classify this message: {message}",
  "model": "gpt-4",
  "parameters": {
    "temperature": 0.7,
    "max_tokens": 500
  },
  "tags": ["support", "classification"],
  "folder": "/customer-support"
}

Response:

{
  "data": {
    "id": "prompt_abc123",
    "name": "customer-classifier",
    "description": "Classifies customer support tickets",
    "template": "Classify this message: {message}",
    "model": "gpt-4",
    "parameters": {
      "temperature": 0.7,
      "max_tokens": 500
    },
    "version": 1,
    "tags": ["support", "classification"],
    "folder": "/customer-support",
    "created_at": "2025-01-15T10:00:00Z",
    "updated_at": "2025-01-15T10:00:00Z"
  }
}

Get Prompt

GET /v1/prompts/{name}

Retrieve a specific prompt.

Response:

{
  "data": {
    "id": "prompt_abc123",
    "name": "customer-classifier",
    "template": "Classify this message: {message}",
    "model": "gpt-4",
    "version": 1,
    "created_at": "2025-01-15T10:00:00Z"
  }
}

List Prompts

GET /v1/prompts

List all prompts.

Parameters:

Parameter	Type	Description
limit	integer	Number of results (default: 20, max: 100)
cursor	string	Pagination cursor
tags	string[]	Filter by tags
folder	string	Filter by folder
search	string	Search query

Response:

{
  "data": [
    {
      "id": "prompt_abc123",
      "name": "customer-classifier",
      "description": "Classifies customer support tickets",
      "version": 1,
      "created_at": "2025-01-15T10:00:00Z"
    }
  ],
  "pagination": {
    "has_more": true,
    "next_cursor": "xyz789",
    "total": 156
  }
}

Update Prompt

PATCH /v1/prompts/{name}

Update a prompt (creates new version).

Request:

{
  "template": "Updated template: {message}",
  "model": "gpt-4-turbo"
}

Response:

{
  "data": {
    "id": "prompt_abc123",
    "name": "customer-classifier",
    "template": "Updated template: {message}",
    "model": "gpt-4-turbo",
    "version": 2,
    "updated_at": "2025-01-15T11:00:00Z"
  }
}

Delete Prompt

DELETE /v1/prompts/{name}

Delete a prompt (soft delete).

Response:

{
  "data": {
    "deleted": true,
    "id": "prompt_abc123"
  }
}

Get Prompt Template

Fetch a prompt template for local SDK execution. Your LLM API keys stay on your system.

Get Latest Template

GET /v1/prompts/{id}/template

Returns the latest version's template data.

Get Specific Version Template

GET /v1/prompts/{id}/versions/{version}/template

Returns a specific version's template (e.g., /versions/2/template).

Get Template by Label

GET /v1/prompts/{id}/versions/by-label/{label}/template

Returns the labeled version's template (e.g., /versions/by-label/production/template).

Response:

{
  "prompt_id": "uuid",
  "prompt_name": "customer-classifier",
  "version": 2,
  "version_id": "uuid",
  "content": "Classify this message: {{message}}",
  "variables": {"message": {"type": "string"}},
  "provider": "openai",
  "model": "gpt-4",
  "temperature": 0.7,
  "max_tokens": 500
}

Run Prompt

Execute a prompt with the LLM. There are three ways to specify which version to run:

Run Latest Version

POST /v1/prompts/{id}/run

Runs the most recent version of the prompt.

Run Specific Version

POST /v1/prompts/{id}/versions/{version}/run

Runs a specific version number (e.g., /versions/2/run).

Run by Label

POST /v1/prompts/{id}/versions/by-label/{label}/run

Runs the version with a specific label (e.g., /versions/by-label/production/run).

Request:

{
  "user_input": "I need help with billing",
  "variables": {},
  "metadata": {
    "user_id": "user_123",
    "session_id": "session_456"
  }
}

Response:

{
  "data": {
    "id": "req_xyz789",
    "output": "billing",
    "prompt_name": "customer-classifier",
    "version": 2,
    "model": "gpt-4",
    "metadata": {
      "user_id": "user_123",
      "session_id": "session_456"
    },
    "usage": {
      "prompt_tokens": 50,
      "completion_tokens": 10,
      "total_tokens": 60,
      "estimated_cost_usd": 0.0012
    },
    "latency_ms": 1234,
    "created_at": "2025-01-15T12:00:00Z"
  }
}

Streaming

Set stream: true for streaming responses:

curl -X POST https://mandatum-api.gavelinivar.com/api/v1/prompts/greeting/run \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input_variables": {"name": "Alice"},
    "stream": true
  }'

Server-sent events response:

data: {"type": "start", "request_id": "req_abc"}

data: {"type": "chunk", "content": "Hello"}

data: {"type": "chunk", "content": " Alice"}

data: {"type": "chunk", "content": "!"}

data: {"type": "end", "usage": {"total_tokens": 10}}

Version History

List Versions

GET /v1/prompts/{name}/versions

List all versions of a prompt.

Response:

{
  "data": [
    {
      "version": 2,
      "template": "Updated template",
      "model": "gpt-4-turbo",
      "created_at": "2025-01-15T11:00:00Z"
    },
    {
      "version": 1,
      "template": "Original template",
      "model": "gpt-4",
      "created_at": "2025-01-15T10:00:00Z"
    }
  ]
}

Get Specific Version

GET /v1/prompts/{name}/versions/{version}

Retrieve a specific version.

Response:

{
  "data": {
    "version": 1,
    "template": "Original template",
    "model": "gpt-4",
    "parameters": {...},
    "created_at": "2025-01-15T10:00:00Z"
  }
}

Rollback Version

POST /v1/prompts/{name}/rollback

Rollback to a previous version (creates new version).

Request:

{
  "version": 1
}

Response:

{
  "data": {
    "version": 3,
    "template": "Original template",
    "note": "Rolled back from version 2 to version 1"
  }
}

Examples

Python SDK (Recommended)

The SDK-first approach keeps your LLM API keys on your system. The SDK fetches templates from Mandatum, executes locally, and logs results back.

import os
from openai import OpenAI
from mandatum import Mandatum

# Initialize clients
mandatum = Mandatum(api_key=os.environ["MANDATUM_API_KEY"])
openai_client = OpenAI(api_key=os.environ["OPENAI_API_KEY"])

# Run prompt locally with your own API key
response = mandatum.prompts.run(
    prompt_id="your-prompt-id",
    user_input="Hello!",
    llm_client=openai_client,
    variables={"name": "Alice"},
    environment="production",
    tags=["greeting"],
    metadata={"user_id": "user_123"}
)

print(response.output)
print(f"Cost: ${response.cost}")
print(f"Latency: {response.latency_ms}ms")

# Run a specific version
response = mandatum.prompts.run(
    prompt_id="your-prompt-id",
    user_input="Hello!",
    llm_client=openai_client,
    version=2
)

# Run by label (e.g., production)
response = mandatum.prompts.run(
    prompt_id="your-prompt-id",
    user_input="Hello!",
    llm_client=openai_client,
    label="production"
)

# Get template only (for custom execution)
template = mandatum.prompts.get_template(
    prompt_id="your-prompt-id",
    label="production"
)
print(template.content)
print(template.model)

Using Anthropic

from anthropic import Anthropic
from mandatum import Mandatum

mandatum = Mandatum(api_key=os.environ["MANDATUM_API_KEY"])
anthropic_client = Anthropic(api_key=os.environ["ANTHROPIC_API_KEY"])

response = mandatum.prompts.run(
    prompt_id="your-prompt-id",
    user_input="Hello!",
    llm_client=anthropic_client,
)

print(response.output)

TypeScript SDK

Coming Soon

A TypeScript/JavaScript SDK is in development. For now, use the REST API directly.

cURL

# Create prompt
curl -X POST https://mandatum-api.gavelinivar.com/api/v1/prompts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "greeting",
    "template": "Hello {name}!",
    "model": "gpt-4"
  }'

# Run prompt (latest version)
curl -X POST https://mandatum-api.gavelinivar.com/api/v1/prompts/{prompt_id}/run \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "user_input": "Hello!",
    "variables": {}
  }'

# Run specific version
curl -X POST https://mandatum-api.gavelinivar.com/api/v1/prompts/{prompt_id}/versions/2/run \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "user_input": "Hello!",
    "variables": {}
  }'

# Run by label (e.g., production)
curl -X POST https://mandatum-api.gavelinivar.com/api/v1/prompts/{prompt_id}/versions/by-label/production/run \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "user_input": "Hello!",
    "variables": {}
  }'

# List prompts
curl -X GET "https://mandatum-api.gavelinivar.com/api/v1/prompts?limit=20" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Update prompt
curl -X PATCH https://mandatum-api.gavelinivar.com/api/v1/prompts/greeting \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"template": "Hi {name}!"}'

Error Responses

Invalid Template

{
  "error": {
    "type": "validation_error",
    "message": "Template contains undefined variables",
    "code": "INVALID_TEMPLATE",
    "details": {
      "missing_variables": ["age"],
      "template": "Hello {name}, you are {age} years old"
    }
  }
}

Prompt Not Found

{
  "error": {
    "type": "not_found_error",
    "message": "Prompt not found",
    "code": "PROMPT_NOT_FOUND",
    "details": {
      "prompt_name": "nonexistent-prompt"
    }
  }
}

See Also

• API Overview
• Integrations API
• Requests API
• Managing Prompts Guide