API Overview

Mandatum provides a comprehensive REST API for programmatic access to all platform features.

Base URL

https://mandatum-api.gavelinivar.com/api/v1

Authentication

Include your API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Example:

curl -H "Authorization: Bearer mdt_live_abc123..." \
  https://mandatum-api.gavelinivar.com/api/v1/prompts

Learn more about authentication.

SDKs

Python

pip install mandatum-sdk

from mandatum import Mandatum

client = Mandatum(api_key="your-api-key")

TypeScript/JavaScript

Coming Soon

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

Request Format

All requests must use Content-Type: application/json:

curl -X POST https://mandatum-api.gavelinivar.com/api/v1/prompts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "test", "template": "Hello {name}"}'

Response Format

All responses are JSON:

{
  "data": {
    "id": "prompt_abc123",
    "name": "test",
    "template": "Hello {name}"
  },
  "meta": {
    "request_id": "req_xyz789"
  }
}

Error Handling

Errors follow this format:

{
  "error": {
    "type": "validation_error",
    "message": "Invalid prompt template",
    "code": "INVALID_TEMPLATE",
    "details": {
      "field": "template",
      "issue": "Missing required variable: name"
    }
  },
  "meta": {
    "request_id": "req_xyz789"
  }
}

HTTP Status Codes

Code	Meaning	Description
200	OK	Request succeeded
201	Created	Resource created successfully
400	Bad Request	Invalid request parameters
401	Unauthorized	Missing or invalid API key
403	Forbidden	Insufficient permissions
404	Not Found	Resource doesn't exist
429	Too Many Requests	Rate limit exceeded
500	Internal Server Error	Server error

Error Types

Type	Description
authentication_error	Invalid API key
authorization_error	Insufficient permissions
validation_error	Invalid request data
not_found_error	Resource not found
rate_limit_error	Too many requests
server_error	Internal server error

Pagination

List endpoints support cursor-based pagination:

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

Response includes pagination metadata:

{
  "data": [...],
  "pagination": {
    "has_more": true,
    "next_cursor": "xyz789",
    "total": 156
  }
}

Rate Limits

Rate limits vary by plan:

Plan	Requests/Minute	Requests/Day
Free	60	1,000
Pro	600	100,000
Enterprise	Custom	Custom

Rate limit headers are included in all responses:

X-RateLimit-Limit: 600
X-RateLimit-Remaining: 583
X-RateLimit-Reset: 1642876800

Idempotency

Use Idempotency-Key header to ensure requests are processed once:

curl -X POST https://mandatum-api.gavelinivar.com/api/v1/prompts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Idempotency-Key: unique-key-123" \
  -H "Content-Type: application/json" \
  -d '{"name": "test", "template": "Hello"}'

Versioning

The API is versioned via the URL path (/v1). Breaking changes will result in a new version.

Current version: v1

Webhooks

Subscribe to events via webhooks:

webhook = client.webhooks.create(
    url="https://your-app.com/webhooks",
    events=["request.completed", "request.failed"]
)

Learn more about webhooks.

API Resources

• Prompts - Create and manage prompts
• Integrations - Manage custom code
• Requests - View request logs
• API Keys - Manage API keys

Example Requests

Create a 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 a Prompt

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"
    },
    "metadata": {
      "user_id": "user_123"
    }
  }'

List Logs

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

Support

• Documentation: mandatum-documentation.netlify.app
• Email: support@gavelinivar.com

Rate Limit Best Practices

• Cache responses when possible
• Use exponential backoff on 429 errors
• Batch requests when available
• Monitor rate limit headers
• Upgrade plan if consistently hitting limits