API quickstart
From a new API key to the first audit results with curl, in five requests.
This page runs the whole flow from a terminal: add a site, start an audit, wait for it, read what to fix. You need curl; the last script also uses jq.
1. Create a key
In the app, turn on developer tools once under Settings → Developer tools (see who they are for). Then open API keys, create a key with the scopes sites:read, sites:write, audits:read and audits:write, and copy it: it is shown once. Then set:
export METRICEVO_API="https://app.metricevo.com/api/v1"
export METRICEVO_API_KEY="mev_live_..."2. Add a site
curl -X POST "$METRICEVO_API/sites" \
-H "Authorization: Bearer $METRICEVO_API_KEY" \
-H "Content-Type: application/json" \
-d '{"url":"https://www.example.com","name":"Example"}'HTTP/1.1 201 Created
{ "id": "site_01JC9Z0000000000000000000", "origin": "https://www.example.com", ... }Keep the id. Already on your list? The answer is 409 site_exists, and the body carries the existing siteId. To find ids later: GET /sites.
3. Start an audit
Starting an audit needs an Idempotency-Key: any unique string. If the network drops and you send the same request again with the same key, you get the same run back instead of a second audit.
curl -i -X POST "$METRICEVO_API/audit-runs" \
-H "Authorization: Bearer $METRICEVO_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"siteId":"site_01JC9Z0000000000000000000"}'HTTP/1.1 202 Accepted
Location: /api/v1/audit-runs/run_01JCA40000000000000000000
Retry-After: 5
{ "id": "run_01JCA40000000000000000000", "status": "queued", "triggerType": "api", ... }The audit is now in the queue. Your request is already answered: nothing audits while you wait.
4. Wait for the result
curl -i "$METRICEVO_API/audit-runs/run_01JCA40000000000000000000" \
-H "Authorization: Bearer $METRICEVO_API_KEY"While status is queued or running, the response has a Retry-After header: wait that many seconds and ask again. Stop when the status is succeeded, partial or failed. Most audits finish within a minute.
5. Read the results
curl "$METRICEVO_API/audit-runs/run_01JCA40000000000000000000/observations?status=fail" \
-H "Authorization: Bearer $METRICEVO_API_KEY"{
"data": [
{
"id": "obs_01JCA4...",
"auditRunId": "run_01JCA40000000000000000000",
"area": "security",
"ruleId": "security.hsts",
"status": "fail",
"severity": "medium",
"confidence": "high",
"summary": "No Strict-Transport-Security header.",
...
}
],
"nextCursor": null
}Leave out ?status=fail to get every check. You can also filter by area. What each field means: Key concepts; every field in detail: Audit runs reference.
All in one script
The same steps for an existing site, ready for a cron job or a CI step. Set SITE_ID first.
#!/usr/bin/env bash
# Audits one site and prints the checks to fix. Needs curl and jq.
set -euo pipefail
: "${METRICEVO_API:?}" "${METRICEVO_API_KEY:?}" "${SITE_ID:?}"
auth=(-H "Authorization: Bearer $METRICEVO_API_KEY")
run=$(curl -fsS -X POST "$METRICEVO_API/audit-runs" "${auth[@]}" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d "{\"siteId\":\"$SITE_ID\"}" | jq -r .id)
echo "queued $run"
while :; do
status=$(curl -fsS "$METRICEVO_API/audit-runs/$run" "${auth[@]}" | jq -r .status)
case "$status" in
queued|running) sleep 5 ;;
*) break ;;
esac
done
echo "status $status"
curl -fsS "$METRICEVO_API/audit-runs/$run/observations?status=fail" "${auth[@]}" \
| jq -r '.data[] | "\(.severity)\t\(.area)\t\(.summary)"'For a CI job that fails the build on high-severity findings, see CI pipelines.