Sovereign Matrix API
Build on 130+ autonomous AI agents. Execute agents, run multi-step playbooks, retrieve analytics, and trigger workflows -- all through a single REST API with built-in safety, rate limiting, and model routing.
https://sovereignmatrix.agencyFormat: JSONAuth: Bearer Token (Clerk)Quick Start
Make your first API call in under 30 seconds.
Get your API key
Sign up and generate a key from the dashboard integrations page.
Make a request
POST to any agent endpoint with your Bearer token and a JSON body.
Get results
Receive structured JSON with the agent’s output, model info, and timing.
Request
curl -X POST https://sovereignmatrix.agency/api/agents/leads \
-H "Authorization: Bearer sk_live_your_api_key" \
-H "Content-Type: application/json" \
-d '{
"prompt": "Find 50 fintech leads in NYC",
"confirmed": true
}'Response
{
"success": true,
"data": {
"leads": [
{ "company": "Acme Corp", "contact": "jane@acme.com", "score": 87 },
{ "company": "Beta Inc", "contact": "john@beta.io", "score": 82 }
],
"count": 50,
"model": "gemini-2.0-flash"
},
"responseTimeMs": 2340
}Authentication
All authenticated endpoints require a Bearer token from Clerk. Pass it in the Authorization header with every request. Free endpoints (marked below) do not require authentication.
Bearer Token Authentication
Include your API key in the Authorization header of every request. Generate your key from the dashboard integrations page.
Authorization: Bearer sk_live_your_api_keyUnauthenticated Endpoints
Some endpoints (marked "No Auth") work without a token. These are rate-limited by IP address and restricted to read-only agents. Use POST /api/free/run for unauthenticated agent access.
Security Best Practices
- --Never expose your API key in client-side code or public repositories.
- --Use environment variables to store your key on the server.
- --Rotate your key immediately if you suspect it has been compromised.
- --All requests pass through a 5-layer safety pipeline (jailbreak detection, PII scanning, content safety, quality scoring, critic review).
Agents
Execute any of 130+ specialized AI agents. Each agent handles a specific task -- lead generation, content writing, SEO analysis, competitor scanning, and more.
Playbooks
Playbooks are multi-step agent workflows. Start a playbook, then poll for live step-by-step progress. Each step executes a different agent in sequence, with outputs piped between steps.
Models
The platform routes requests through 35+ models across 6 providers (NVIDIA NIM, Google Gemini, Anthropic Claude, Groq, Ollama, Tavily). The smart router selects the optimal model per task, with an 11-model failover chain.
Webhooks
Trigger agent executions from external systems via webhooks. Useful for connecting Zapier, Make, n8n, or custom integrations.
Rate Limits
Rate limits are enforced per user per day. When you exceed your limit, the API returns a 429 response with your current usage and an upgrade URL.
Free
50 / day
Starter
$19/mo200 / day
Growth
$49/mo500 / day
Node
$199/mo2,000 / day
Enterprise
$499/mo10,000 / day
Rate Limit Headers
Every response includes rate limit information in headers:
X-RateLimit-Limit: 200
X-RateLimit-Remaining: 187
X-RateLimit-Reset: 1712534400
X-Free-Remaining: 2 # Only on /api/free/run429 Response Body
{
"error": "Monthly plan limit reached",
"usage": {
"used": 200,
"limit": 200,
"plan": "starter"
},
"upgradeUrl": "/pricing"
}Error Codes
The API uses standard HTTP status codes. Error responses always include an error field with a human-readable message.
| Code | Description |
|---|---|
| 400 | Bad Request -- Missing or invalid parameters. |
| 401 | Unauthorized -- Missing or invalid Bearer token. |
| 404 | Not Found -- Agent or playbook does not exist. |
| 429 | Too Many Requests -- Rate limit or plan quota exceeded. Check the usage object in the response body. |
| 500 | Internal Server Error -- Agent execution failed. Check the error field for details. |
| 502 | Bad Gateway -- Upstream model provider is temporarily unavailable. Retry with exponential backoff. |
| 503 | Service Unavailable -- Database tables not migrated. Run the SQL migration scripts. |
Error Response Shape
{
"error": "Agent \"nonexistent\" not found",
"available": ["leads", "blog-gen", "seo-dominator", "..."]
}Ready to build?
Generate your API key and make your first call in under a minute.