Public API
Everything e-volv added in the reliability, identity, and rotation features also works without the app. A workspace API key opens a set of /public/v1 routes that a cron job, a GitHub Action, or another platform can call directly. These features are in early access; ask us to turn them on for your workspace.
Keys
Create a key under Settings → API keys. It starts with evk_, is shown exactly once, and only its SHA-256 hash is stored. Send it as a bearer token:
Authorization: Bearer evk_...
A key belongs to one workspace and carries only the scopes you grant it. A route checks its scope on every call; a key without it gets a 403.
Scopes
| Scope | Grants |
|---|---|
runs:write | Ingest runs from agents that execute outside e-volv. |
ledger:read | Read an agent’s ledger by its external ID. |
identity:mint | Mint a short-lived signed identity token for an agent. |
eval:run | Replay a step or run an eval suite. |
heartbeats:write | Create monitors and read their state (pings need no key). |
metrics:read | Prometheus metrics and SLO statuses. |
mcp:publish | Publish or deprecate MCP registry manifests. |
secrets:read | Read a vault secret’s current value by key. |
secrets:write | Trigger a rotation for a secret with a policy. |
slo:write | Reserved for SLO management from outside the app. |
logs:write | Ingest logs, spans and OTLP batches into e-volv Observer projects. |
logs:read | Search, tail and read e-volv Observer dashboards over the public API. |
Routes
Base URL https://api.e-volv.io/api. Routes marked none authenticate by the token in their URL or are public by design, so they work from places that cannot hold a secret.
| Route | Scope | Does |
|---|---|---|
POST /public/v1/runs | runs:write | Record a run from an external agent into its ledger. |
GET /public/v1/agents/:externalId/ledger | ledger:read | Everything one agent did, across workflows. |
POST /public/v1/agents/:externalId/identity-token | identity:mint | Ed25519-signed token; verify with /v1/entitlement/pubkey. |
POST /public/v1/eval/replay | eval:run | Replay a saved step with write tools stripped. |
POST /public/v1/eval/suites/:agent/run | eval:run | Run every fixture for an agent; fails on unmet assertions. |
POST /public/v1/heartbeats/:token?state=start|ok|fail | none | Check a job in. GET works too, for curl-only environments. |
GET /public/v1/metrics | metrics:read | Prometheus text format: runs, failures, tokens, SLO series. |
GET /public/v1/slo | metrics:read | Every SLO with budget, burn rates, and verdict. |
POST /public/v1/slo/:token/events | none | Post good/bad events for an ingested-events SLO. |
GET /public/v1/slo/:id/badge.svg | none | SVG badge for a public SLO. Cached 60 s. |
GET /public/v1/mcp/registry/:name | none | Resolve a manifest by name and range; JWKS at /public/v1/mcp/jwks. |
POST /public/v1/mcp/registry | mcp:publish | Publish a signed manifest version. |
GET /public/v1/secrets/:key | secrets:read | Current value of a vault secret. |
POST /public/v1/secrets/:key/rotate | secrets:write | Rotate now under the secret’s policy. |
POST /public/v1/logs | logs:write | Ingest a native SDK batch into the key’s e-volv Observer project. |
POST /public/v1/logs/otlp | logs:write | OTLP/HTTP JSON logs or traces; service.name picks the project. |
GET /public/v1/logs/query | logs:read | Search with the e-volv Observer query language; keyset-paginated. |
GET /public/v1/logs/dashboards | logs:read | Volume, error rate and p95 latency from continuous aggregates. |
GET /public/v1/logs/tail | logs:read | SSE stream of live events for the CLI and API clients. |
e-volv Observer
The logs:* routes are the standalone e-volv Observer surface: a project’s dedicated ingest key (shown once when the project is created) posts SDK batches and OTLP, and a workspace key with logs:read searches, tails and reads dashboards. e-volv Observer is a paid tier - the e-volv Observer guide has the SDK snippets, the query language and the CLI.
Heartbeat from any job
Create a monitor, then wrap the job. e-volv alerts when the start is late past the grace period, when the finish never arrives, or when the job reports fail.
curl -fsS -X POST "https://api.e-volv.io/api/public/v1/heartbeats/<token>?state=start" ./nightly-backup.sh && STATE=ok || STATE=fail curl -fsS -X POST "https://api.e-volv.io/api/public/v1/heartbeats/<token>?state=$STATE"
Events for an SLO
An SLO on the ingested events indicator counts whatever you post. dedupKey makes retries safe.
curl -X POST "https://api.e-volv.io/api/public/v1/slo/<token>/events" \
-H 'Content-Type: application/json' \
-d '{"events":[{"good":true,"at":"2026-09-04T10:00:00Z","dedupKey":"req-1"}]}'Embed the badge in a README once the SLO is marked public:
Runs from an external agent
Agents that run somewhere else can still appear in the ledger. Post a run with the agent’s externalId; e-volv creates the agent on first sight.
curl -X POST "https://api.e-volv.io/api/public/v1/runs" \
-H "Authorization: Bearer evk_..." -H 'Content-Type: application/json' \
-d '{"agent":{"externalId":"ci-fixer","name":"CI Fixer"},
"instruction":"Fix the failing lint job on acme/api pull 412",
"status":"completed","startedAt":"2026-09-04T10:00:00Z","completedAt":"2026-09-04T10:02:10Z",
"model":"claude-sonnet-5","provider":"anthropic",
"toolCalls":[{"name":"add_comment_to_pull_request","status":"success","output":"Commented on pull 412"}],
"message":"Root cause: an unused import. Comment posted."}'Scrape metrics
Point Prometheus, Grafana Agent, or the Datadog OpenMetrics check at the metrics route with the key in the Authorization header. Series include run counts by status, token totals, and evolve_slo_burn_rate per window.
scrape_configs:
- job_name: evolve
metrics_path: /api/public/v1/metrics
scheme: https
authorization:
credentials: evk_...
static_configs:
- targets: ['api.e-volv.io']Signed outbound webhooks
Alerts, late runs and rotation notices can be delivered to a URL of yours. Every delivery carries X-Evolve-Signature: sha256=…, an HMAC of the raw body with the workspace’s signing secret, so the receiver can reject anything it did not come from e-volv.