Platform as Infrastructure
The Sovereignty Protocol dashboard is one way to use the platform. The REST API is another — and for developers building on top of their AI workforce, it is often the primary one.
API keys give you programmatic access to the same capabilities available in the dashboard: running cascades, querying reports, managing tasks, accessing agent memory, reading Spectre data, and more.
If you want to build your own front-end, embed AI workflows into an existing application, or drive automation from your own scripts — API keys are how you do it.
Generating API Keys
API keys are managed from Settings → API Keys. Each key has:
- Name — a human-readable label for identifying which integration uses this key
- Scopes — a set of permission scopes that define what the key can access
- Expiry — optional expiration date; keys without expiry are valid until revoked
- Last used — timestamp of the most recent API call made with this key
- Rate limit tier — standard, elevated, or unlimited based on your plan
Keys are shown only once on creation — store them securely in the Sentinel Vault or your own secrets management system. If a key is lost, revoke it and generate a new one.
Authentication
All API requests require an Authorization header:
GET /api/v1/cascades
Authorization: Bearer sp_live_your_key_here
Keys use the prefix sp_live_ for production keys and sp_test_ for test keys. Test keys have access to the full API surface but operate against a sandboxed data environment — safe for development and testing without touching production data.
Permission Scopes
API keys use a scoped permission model. When generating a key, you select exactly what it can access:
| Scope | Description |
|---|---|
cascades:read | List and query cascade definitions |
cascades:run | Trigger cascade executions |
cascades:write | Create and modify cascade definitions |
reports:read | Access Nexus Reports |
tasks:read | Query the task board |
tasks:write | Create and update tasks |
spectre:read | Access crawl results and campaign data |
spectre:run | Trigger crawls and campaigns |
memory:read | Query agent memory |
memory:write | Write to agent memory |
agents:chat | Invoke agent chat endpoints |
financial:read | Access Sentinel financial data |
admin | Full access (use sparingly) |
A webhook receiver that only needs to trigger cascades gets only cascades:run. A reporting dashboard that reads output gets only reports:read and tasks:read. Least-privilege is the default posture.
Core API Endpoints
Cascades
GET /api/v1/cascades — List all cascade definitions
GET /api/v1/cascades/:id — Get a specific cascade
POST /api/v1/cascades/:id/run — Trigger a cascade run
GET /api/v1/cascade-runs — List recent cascade run history
GET /api/v1/cascade-runs/:id — Get detailed run output
Agents
POST /api/v1/chat — Chat with an agent persona
POST /api/v1/agents/:persona/chat — Chat with a specific named persona
Reports
GET /api/v1/reports — List Nexus Reports (paginated)
GET /api/v1/reports/:id — Get a specific report with full content
POST /api/v1/reports/search — Full-text search across reports
Tasks
GET /api/v1/tasks — List all tasks (with column filter)
POST /api/v1/tasks — Create a new task
PATCH /api/v1/tasks/:id — Update a task (status, priority, etc.)
Spectre
POST /api/v1/spectre/extract — Crawl and extract a URL
GET /api/v1/spectre/campaigns — List campaigns
POST /api/v1/spectre/campaigns/:id/run — Trigger a campaign run
Memory
GET /api/v1/memory — Query agent memory (with relevance scoring)
POST /api/v1/memory — Write a memory record
DELETE /api/v1/memory/:id — Archive a memory record
Headless Use Cases
Custom dashboards — Build an internal dashboard that surfaces cascade runs, agent status, and Nexus Reports in a format tailored to your team — using your own design system, showing only the metrics you care about.
CI/CD integration — Trigger a code review cascade from your CI pipeline. When a PR is opened, call POST /api/v1/cascades/code-review/run with the PR URL as a parameter. Get the Nexus Report as the output.
Webhook receiver — Configure a third-party service to POST to a webhook endpoint, which calls cascades/:id/run with the webhook payload as parameters. External events drive internal automation with a single HTTP integration.
Mobile apps — Build a lightweight mobile companion app that queries task status and reports via the API, without shipping the full platform UI.
Agent memory management — Scripts that pre-load agent memory before important runs: POST /api/v1/memory with research context, domain knowledge, or project state — so agents start runs with richer context than they would have from an empty session.
Scheduled external triggers — Run cascade schedules from your existing job scheduler (Kubernetes CronJob, AWS EventBridge, GitHub Actions scheduled workflow) rather than the platform's built-in scheduler, for organisations that want external coordination.
Rate Limits
| Plan | Rate Limit |
|---|---|
| Free | 60 requests/minute |
| Pro | 600 requests/minute |
| Enterprise | Custom / unlimited |
Rate limit headers are included in every response:
X-RateLimit-Limit: 600
X-RateLimit-Remaining: 423
X-RateLimit-Reset: 1717171717
If you hit the rate limit, responses return 429 Too Many Requests with a Retry-After header indicating when you can resume.
OpenAPI Specification
The platform ships with a complete OpenAPI 3.0 specification (openapi.yaml) covering every endpoint, request schema, and response schema. Import it into Postman, Insomnia, or any OpenAPI-compatible client for instant access to the full API surface with request building, response validation, and documentation.
The spec is the authoritative contract. If the code and the spec disagree, the spec is wrong and we fix it.
Your AI workforce. Your API. Build whatever you need on top of it.