API Reference

POST/v1/intent

Submit an intent describing the resource you want to consume. The daemon replies with approval, denial, or a counter offer.

Request Body

{
  "agent_id": "crawler-01",
  "identity_id": "pat:user",
  "workload_id": "repo_scan",
  "scope_id": "repo:owner/project",
  "urgency": "normal"
}

Sample Response

{
  "decision": "approve",
  "intent_id": "evt_12345",
  "evaluation": {
    "risk_summary": "Low risk (P99 TTE > 1h)"
  }
}

GET/v1/health

Check whether the daemon is ready, degraded, or still initializing.

{
  "status": "ok",
  "version": "0.1.0",
  "uptime_seconds": 3600
}

GET/v1/graph

Returns the current constraint graph (pools, scopes, and identities plus their relationships).

Analytics & Reporting

Use the trends and reports endpoints for dashboards or auditors.

• GET /v1/trends: Aggregated usage over a time window (from, to, bucket, provider_id).
• GET /v1/reports: CSV exports for usage, access logs, or events (type, from, to).

Federation & Clustering

• GET /v1/cluster/nodes: Returns topology of known leaders and followers.
• POST /v1/federation/grant: Followers request grants from the leader (body: node_id, resource, amount).

Integrations

Register webhooks to receive streaming events.

{
  "url": "https://hooks.slack.com/...",
  "events": ["intent.denied", "system.alert"]
}

Administration

Prune old events and manage the event ledger.

{
  "before": "2023-01-01T00:00:00Z"
}

Event Streaming

Stream recent events as SSE or poll the latest batch.

• GET /v1/events: Parameters: limit (default 50), stream=true for SSE.

Identity Management

Register, inspect, and delete identities.

{
  "identity_id": "pat:github:rmax",
  "kind": "user",
  "metadata": { "name": "RMax" }
}

DELETE /v1/identities/<id> removes an identity and scrubs its history for compliance.

Observability

Prometheus-style metrics expose pool usage and forecast data.

• GET /metrics: Returns metrics such as `ratelord_usage`, `ratelord_limit`, `ratelord_intent_total`, `ratelord_forecast_seconds`.

Debugging

Inject synthetic provider data for testing flows.

{
  "provider_id": "github-mock",
  "pool_id": "core",
  "usage": 4500,
  "limit": 5000
}