Public API

Everything Evolve 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 Evolve.
`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.

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.

Heartbeat from any job

Create a monitor, then wrap the job. Evolve 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:

![Checkout succeeds](https://api.e-volv.io/api/public/v1/slo/<id>/badge.svg)

Runs from an external agent

Agents that run somewhere else can still appear in the ledger. Post a run with the agent’s externalId; Evolve 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 Evolve.