API Reference
Base URL: https://api.savants.cloud/api/v1. Authenticated endpoints require a Bearer token.
FSM Schemas
| Method | Endpoint | Auth | Description |
|---|
GET | /fsm/schemas | Yes | List schemas for your org |
POST | /fsm/schemas | Yes | Create or update a schema |
Create a schema
curl -X POST https://api.savants.cloud/api/v1/fsm/schemas \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"id": "my-workflow",
"version": "1.0",
"initial_state": "draft",
"states": { "draft": { "type": "initial" }, "done": { "type": "terminal" } },
"events": ["finish"],
"transitions": [{ "from": "draft", "event": "finish", "to": "done" }]
}'
Entity Instances
| Method | Endpoint | Auth | Description |
|---|
GET | /fsm/instances | Yes | List all entities with current states |
GET | /fsm/instances/:schema/:entity | Yes | Get specific entity state |
POST | /fsm/instances/:id/event | Yes | Send an event to an entity |
Send an event
curl -X POST https://api.savants.cloud/api/v1/fsm/instances/pod-123/event \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"schema_id": "pod",
"event": "crash_detected",
"context": { "restart_count": 5, "namespace": "production" }
}'
# Response:
# { "success": false, "guard_blocked": true, "from_state": "running", "to_state": null }
Guards
| Method | Endpoint | Auth | Description |
|---|
GET | /fsm/guards | Yes | List all guards |
POST | /fsm/guards | Yes | Set a guard rule |
DELETE | /fsm/guards | Yes | Remove a guard |
Transition Audit Log
| Method | Endpoint | Auth | Description |
|---|
GET | /fsm/transitions | Yes | Query transition history |
Community Registry
| Method | Endpoint | Auth | Description |
|---|
GET | /registry | No | Browse packages |
GET | /registry/search?q=... | No | Search packages |
GET | /registry/categories | No | List categories |
GET | /registry/:slug | No | Package detail |
GET | /registry/:slug/versions | No | Version history |
POST | /registry/publish | Yes | Publish a profile |
POST | /registry/:slug/install | Yes | Install to your org |
POST | /registry/:slug/star | Yes | Star a package |
Authentication
All authenticated endpoints accept a Bearer token in the Authorization header:
Authorization: Bearer YOUR_JWT_OR_API_KEY
Get a token by signing in at savants.cloud/activate or creating an API key in the dashboard.