Type at least two letters.

    ↑ ↓ to moveEnter to open

    API quickstart

    From a new API key to the first audit results with curl, in five requests.

    Updated

    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.