REST API Reference¶

Acteon exposes a RESTful HTTP API via Axum with auto-generated OpenAPI/Swagger documentation.

Base URL¶

http://localhost:8080

Interactive Documentation¶

• Swagger UI: http://localhost:8080/swagger-ui/
• OpenAPI Spec: http://localhost:8080/api-doc/openapi.json

Health & Metrics¶

GET /health¶

Health check with metrics snapshot.

Response:

{
  "status": "ok",
  "metrics": {
    "dispatched": 1500,
    "executed": 1200,
    "deduplicated": 150,
    "suppressed": 50,
    "rerouted": 30,
    "throttled": 20,
    "failed": 10,
    "grouped": 25,
    "pending_approval": 5
  }
}

GET /metrics¶

Dispatch counters only.

Response:

{
  "dispatched": 1500,
  "executed": 1200,
  "deduplicated": 150,
  "suppressed": 50,
  "rerouted": 30,
  "throttled": 20,
  "failed": 10
}

Action Dispatch¶

POST /v1/dispatch¶

Dispatch a single action through the gateway pipeline.

Query Parameters:

Request Headers:

Request Body:

{
  "namespace": "notifications",
  "tenant": "tenant-1",
  "provider": "email",
  "action_type": "send_email",
  "payload": {
    "to": "user@example.com",
    "subject": "Hello!"
  },
  "dedup_key": "welcome-user@example.com",
  "metadata": {
    "labels": {
      "priority": "high"
    }
  },
  "status": "firing",
  "fingerprint": "alert-cluster1-cpu",
  "starts_at": "2026-01-15T10:00:00Z",
  "ends_at": "2026-01-15T11:00:00Z"
}

Response (200):

{
  "outcome": "executed",
  "response": {
    "status": "success",
    "body": {"sent": true}
  }
}

Possible Outcomes:

POST /v1/dispatch/batch¶

Dispatch multiple actions in a single request.

Query Parameters:

Request Headers:

Supports the same traceparent and tracestate headers as the single dispatch endpoint. The trace context applies to the batch request span; each individual action creates a child span within it.

Request Body:

{
  "actions": [
    {
      "namespace": "notifications",
      "tenant": "tenant-1",
      "provider": "email",
      "action_type": "send_email",
      "payload": {"to": "alice@example.com"}
    },
    {
      "namespace": "notifications",
      "tenant": "tenant-1",
      "provider": "sms",
      "action_type": "send_sms",
      "payload": {"to": "+1234567890"}
    }
  ]
}

Response (200):

{
  "results": [
    {"status": "success", "outcome": {"outcome": "executed", "response": {...}}},
    {"status": "error", "error": {"message": "Provider not found: sms"}}
  ]
}

Rule Management¶

GET /v1/rules¶

List all loaded rules.

Response:

{
  "rules": [
    {
      "name": "dedup-emails",
      "priority": 10,
      "enabled": true,
      "description": "Deduplicate email sends"
    },
    {
      "name": "block-spam",
      "priority": 1,
      "enabled": true,
      "description": "Block spam actions"
    }
  ]
}

POST /v1/rules/reload¶

Reload rules from the configured directory.

Response:

{
  "loaded": 5,
  "errors": []
}

PUT /v1/rules/{name}/enabled¶

Enable or disable a rule at runtime.

Request Body:

{"enabled": false}

Response: 200 OK

Audit Trail¶

GET /v1/audit¶

Query audit records with filters.

Query Parameters:

Response:

{
  "records": [...],
  "total": 150,
  "limit": 50,
  "offset": 0
}

GET /v1/audit/{action_id}¶

Get a specific audit record.

Events (State Machines)¶

GET /v1/events¶

List events, optionally filtered by status.

Query Parameters: status, namespace, tenant

GET /v1/events/{fingerprint}¶

Get event lifecycle state.

Query Parameters: namespace, tenant

PUT /v1/events/{fingerprint}/transition¶

Transition an event to a new state.

Request Body:

{
  "to_state": "acknowledged",
  "namespace": "monitoring",
  "tenant": "tenant-1"
}

Approvals¶

GET /v1/approvals¶

List pending approvals.

Query Parameters: namespace, tenant

POST /v1/approvals/{namespace}/{tenant}/{id}/approve¶

Approve a pending action (requires HMAC signature).

Query Parameters: sig, expires_at, kid (optional)

POST /v1/approvals/{namespace}/{tenant}/{id}/reject¶

Reject a pending action (requires HMAC signature).

Query Parameters: sig, expires_at, kid (optional)

Event Groups¶

GET /v1/groups¶

List active event groups.

GET /v1/groups/{group_key}¶

Get group details including all events.

DELETE /v1/groups/{group_key}¶

Force flush/close a group, triggering immediate notification.

Embeddings¶

POST /v1/embeddings/similarity¶

Compute cosine similarity between a text and a topic using the configured embedding provider. Useful for testing semantic match thresholds before writing rules.

Rate limit: 5 requests per minute per caller.

Required permission: Dispatch (admin or operator role).

Request Body:

{
  "text": "The database connection pool is exhausted and queries are timing out",
  "topic": "Infrastructure issues, server problems"
}

Response (200):

{
  "similarity": 0.82,
  "topic": "Infrastructure issues, server problems"
}

Error Responses:

Event Streaming¶

GET /v1/stream¶

Subscribe to real-time action outcomes via Server-Sent Events (SSE).

Required permission: StreamSubscribe (admin, operator, or viewer role).

Query Parameters:

SSE Event Format:

event: action_dispatched
id: 550e8400-e29b-41d4-a716-446655440000
data: {"id":"550e8400-...","timestamp":"2026-02-07T14:30:00Z","type":"action_dispatched","outcome":{...},"provider":"email","namespace":"alerts","tenant":"acme","action_type":"send_email","action_id":"661f9511-..."}

SSE Event Types:

Security: - Events are tenant-isolated (scoped callers only see their tenants) - ProviderResponse bodies and headers are sanitized (replaced with null/empty) - Approval URLs are redacted to [redacted]

Error Responses:

Example:

curl -N -H "Authorization: Bearer <token>" \
  "http://localhost:8080/v1/stream?namespace=alerts&outcome=failed"

See Event Streaming for full documentation.

Recurring Actions¶

POST /v1/recurring¶

Create a new recurring action.

Request Body:

{
  "namespace": "notifications",
  "tenant": "acme",
  "cron_expr": "0 9 * * MON-FRI",
  "timezone": "US/Eastern",
  "provider": "email",
  "action_type": "send_digest",
  "payload": {"to": "team@example.com"},
  "description": "Weekday morning digest"
}

Response (201):

{
  "recurring_id": "uuid-...",
  "next_execution": "2026-02-10T14:00:00Z",
  "cron_expr": "0 9 * * MON-FRI",
  "timezone": "US/Eastern",
  "enabled": true
}

GET /v1/recurring¶

List recurring actions for a namespace and tenant.

Query Parameters:

GET /v1/recurring/{id}¶

Get a recurring action by ID.

Query Parameters: namespace, tenant

PUT /v1/recurring/{id}¶

Update a recurring action (partial update).

Query Parameters: namespace, tenant

DELETE /v1/recurring/{id}¶

Delete a recurring action.

Query Parameters: namespace, tenant

POST /v1/recurring/{id}/pause¶

Pause a recurring action (stops future executions).

Query Parameters: namespace, tenant

POST /v1/recurring/{id}/resume¶

Resume a paused recurring action (recomputes next execution from now).

Query Parameters: namespace, tenant

See Recurring Actions for full documentation.

Circuit Breaker Admin¶

These endpoints require the admin or operator role.

GET /admin/circuit-breakers¶

List all circuit breakers with their current distributed state and configuration.

Response:

{
  "circuit_breakers": [
    {
      "provider": "email",
      "state": "closed",
      "failure_threshold": 5,
      "success_threshold": 2,
      "recovery_timeout_seconds": 60,
      "fallback_provider": "webhook"
    }
  ]
}

POST /admin/circuit-breakers/{provider}/trip¶

Force-open a circuit breaker, immediately rejecting requests to the provider.

Response:

{
  "provider": "email",
  "state": "open",
  "message": "circuit breaker tripped"
}

POST /admin/circuit-breakers/{provider}/reset¶

Force-close a circuit breaker, restoring normal request flow.

Response:

{
  "provider": "email",
  "state": "closed",
  "message": "circuit breaker reset"
}

Authentication¶

POST /v1/auth/login¶

Authenticate and receive a JWT token.

Request Body:

{
  "username": "admin",
  "password": "secret"
}

Response:

{
  "token": "eyJ...",
  "expires_in": 3600
}

POST /v1/auth/logout¶

Revoke the current JWT token.

Headers: Authorization: Bearer <token>

Endpoint Summary¶