Developer API

# Preferred
Authorization: Bearer ap_live_xxxxxxxxxxxxxxxx
# Alternative
X-API-Key: ap_live_xxxxxxxxxxxxxxxx

# Ask for the full unresolved-diff list on a terminal scan:
GET /api/v1/scans/{id}?include=diffs

# Response adds a diffs[] array (value-blind: name + JS-type only):
{
  "status": "completed",
  "gate": { "passed": false, "failures": [ { "code": "new_vendors", "detail": "1 new-vendor diff(s)" } ] },
  "warnings": [],
  "diffs": [
    {
      "stepIndex": 2,
      "elementKey": "event:tiktok::purchase",
      "vendor": "tiktok",
      "diffType": "extra_event",
      "severity": "warning",
      "description": "Event present in the scan but not in the expected schema"
    }
  ]
}
# diffType is one of: missing_event | extra_event | event_drifted | missing_param |
# extra_param | param_type_changed | consent_value_changed | consent_unreadable |
# step_not_reached. elementKey is "event:<vendor>::<name>",
# "param:<vendor>::<event>::<param>", "consent:<vendor>::<event>::<country>.<signal>",
# or "step:<index>" for step_not_reached, which belongs to no vendor.

# Gate a per-PR preview deploy WITHOUT mutating the saved journey baseline.
# "scanType":"web_journey" replays one journey against $PREVIEW_URL as a
# dry-run: it produces diffs for the gate, but writes nothing back to the
# journey's expected schema, vendor watch-list, or regressions. Without a
# scanType a website test runs its default scan, a compliance audit.
# Add "journeyId" to pick the journey; omitted, the first runnable one is used.
#
# Idempotency-Key: commit + CI run ($RUN), mode, target and a HASH of the preview
# URL (plus any journeyId / maxJourneys you send). A retry of the same request
# replays its scan; a new push gets a fresh one (a finished key replays for 24 h),
# and the hash keeps the key within 200 chars. RUN below is for GitHub Actions;
# on another CI use its commit SHA and job id (GitLab: $CI_COMMIT_SHA-$CI_JOB_ID).
RUN="${GITHUB_SHA}-${GITHUB_RUN_ID}-${GITHUB_RUN_ATTEMPT:-1}"
URL_HASH=$(printf '%s' "$PREVIEW_URL" | cksum | cut -d' ' -f1)
SID=$(curl -fsS -X POST \
  -H "Authorization: Bearer $AP_KEY" \
  -H "Idempotency-Key: $RUN-web_journey-$TARGET_ID-$URL_HASH" \
  -H 'content-type: application/json' \
  -d "$(jq -cn --arg url "$PREVIEW_URL" '{url: $url, scanType: "web_journey"}')" \
  "$BASE/api/v1/targets/$TARGET_ID/scans" | jq -r .scanId)
# 400 journey_required is returned when the target has no journey to replay.

# Every runnable journey at once: "journeys":"all" (optional "maxJourneys").
# The response has NO top-level scanId, only scans[] (scanId + pollUrl per
# journey) and failed[] (journeys that could not be started).
RES=$(curl -fsS -X POST \
  -H "Authorization: Bearer $AP_KEY" \
  -H "Idempotency-Key: $RUN-all-$TARGET_ID-$URL_HASH" \
  -H 'content-type: application/json' \
  -d "$(jq -cn --arg url "$PREVIEW_URL" '{url: $url, journeys: "all"}')" \
  "$BASE/api/v1/targets/$TARGET_ID/scans")
[ "$(echo "$RES" | jq '.failed | length')" = "0" ] || { echo "$RES" | jq .failed; exit 1; }
# Then poll each "$BASE$POLL" in turn (not in parallel: five waits per key) with
# the single-scan loop from the CI recipes, and fail the job unless every gate passed.
for POLL in $(echo "$RES" | jq -r '.scans[].pollUrl'); do echo "$BASE$POLL"; done

# Keyset pagination (ordered createdAt DESC, id DESC):
curl -fsS -H "Authorization: Bearer $AP_KEY" \
  "$BASE/api/v1/scans?limit=20" | jq '{next: .nextCursor, count: (.scans | length)}'

# Pass the previous response's nextCursor to fetch the next page;
# nextCursor is null on the final page (truncated is kept for back-compat):
curl -fsS -H "Authorization: Bearer $AP_KEY" \
  "$BASE/api/v1/scans?limit=20&cursor=$NEXT_CURSOR"

# Make retries safe: repeat the same Idempotency-Key header (or "idempotencyKey"
# body field) and a replay returns HTTP 200 with idempotentReplay=true and the
# original scanId instead of starting a second scan.
curl -fsS -X POST \
  -H "Authorization: Bearer $AP_KEY" \
  -H "Idempotency-Key: $GITHUB_SHA" \
  -H 'content-type: application/json' -d '{}' \
  "$BASE/api/v1/targets/$TARGET_ID/scans"

# .github/workflows/analyticsproof.yml
name: AnalyticsProof
on: pull_request
concurrency:
  group: analyticsproof-${{ github.ref }}
  cancel-in-progress: true
permissions:
  contents: read           # checkout
  pull-requests: write     # PR comment
  security-events: write   # SARIF upload
jobs:
  gate:
    runs-on: ubuntu-latest
    if: github.event.pull_request.head.repo.full_name == github.repository
    timeout-minutes: 20   # poll deadline (15 min default) + at least 5 min (start retries, SARIF, comment)
    steps:
      - uses: actions/checkout@v4
      - uses: your-org/your-repo/.github/actions/analyticsproof@v1
        with:
          api-key: ${{ secrets.ANALYTICSPROOF_API_KEY }}
          target-id: <TARGET_ID>   # discover via: GET /api/v1/targets
          url: https://preview-${{ github.event.number }}.example.com
          all-journeys: 'true'     # run EVERY runnable, quota-admitted journey
      - if: always() && hashFiles('analyticsproof.sarif') != ''
        uses: github/codeql-action/upload-sarif@v4
        with:
          sarif_file: analyticsproof.sarif
          category: analyticsproof

# Find the TARGET_ID of a saved test (project-scoped):
curl -fsS -H "Authorization: Bearer $AP_KEY" \
  "$BASE/api/v1/targets" | jq -r '.targets[] | "\(.id)\t\(.name)"'

# .github/workflows/analyticsproof.yml — gate one journey of a PR preview (dry run)
# Run it only on pull requests (on: pull_request), so the preview belongs to the PR.
- name: AnalyticsProof dataLayer gate
  env:
    AP_KEY: ${{ secrets.ANALYTICSPROOF_API_KEY }}
    BASE: https://analyticsproof.com
    TARGET_ID: <TARGET_ID>   # discover via: GET $BASE/api/v1/targets
    PREVIEW_URL: https://preview-${{ github.event.number }}.example.com
  run: |
    set -euo pipefail
    # scanType web_journey replays the first runnable journey (add "journeyId"
    # to pick one); without it a website test runs its compliance audit.
    # Key = commit + run id + run attempt + mode + target + preview-URL hash (add any
    # journeyId you send): a retry replays its scan, a new push, workflow run or
    # re-run gets a fresh one, and it stays under 200 chars.
    URL_HASH=$(printf '%s' "$PREVIEW_URL" | cksum | cut -d' ' -f1)
    SID=$(curl -fsS -X POST \
      -H "Authorization: Bearer $AP_KEY" \
      -H "Idempotency-Key: $GITHUB_SHA-$GITHUB_RUN_ID-${GITHUB_RUN_ATTEMPT:-1}-web_journey-$TARGET_ID-$URL_HASH" \
      -H 'content-type: application/json' \
      -d "$(jq -cn --arg url "$PREVIEW_URL" '{url: $url, scanType: "web_journey"}')" \
      "$BASE/api/v1/targets/$TARGET_ID/scans" | jq -r .scanId)

    # A journey is judged by its diffs; minComplianceScore belongs to a compliance test.
    GATE=$(jq -rn '{failOnSeverity:"critical",failOnBrokenStep:true} | @uri')

    # Re-poll until the scan reaches a terminal status and its findings have
    # settled (a terminal answer with settled:false is provisional).
    # ?wait long-polls up to 120s per attempt (server cap 300s).
    RES=''
    for _ in $(seq 1 20); do
      RES=$(curl -fsS -H "Authorization: Bearer $AP_KEY" \
        "$BASE/api/v1/scans/$SID?wait=120&gate=$GATE&include=diffs&scope=direct-datalayer")
      case "$(echo "$RES" | jq -r 'if .settled == false then "settling" else .status end')" in
        completed|failed|cancelled|broken_step|no_data) break ;;
      esac
    done

    echo "$RES" | jq '{status, settled, score, gate, warnings}'
    if [ "$(echo "$RES" | jq -r '.settled != false and .gate.passed == true')" != "true" ]; then
      echo "::error::AnalyticsProof gate failed"
      echo "$RES" | jq -r '.diffs[]? | "  [\(.severity)] step \(.stepIndex) \(.vendor // "-"): \(.description)"'
      exit 1
    fi

# .gitlab-ci.yml — gate one journey of a merge-request preview (dry run)
analyticsproof:
  stage: verify
  image: alpine:latest
  variables:
    BASE: https://analyticsproof.com
    TARGET_ID: <TARGET_ID>   # discover via: GET $BASE/api/v1/targets
    PREVIEW_URL: https://preview-$CI_MERGE_REQUEST_IID.example.com
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
  before_script:
    - apk add --no-cache curl jq
  script:
    - |
      set -euo pipefail
      # scanType web_journey replays the first runnable journey (add "journeyId"
      # to pick one); without it a website test runs its compliance audit.
      # Key = commit + job + mode + target + preview-URL hash (add any journeyId you
      # send): a retry of the same request replays its scan, a new push or a job
      # retry gets a fresh one, and it stays under 200 chars.
      URL_HASH=$(printf '%s' "$PREVIEW_URL" | cksum | cut -d' ' -f1)
      SID=$(curl -fsS -X POST \
        -H "Authorization: Bearer $ANALYTICSPROOF_API_KEY" \
        -H "Idempotency-Key: $CI_COMMIT_SHA-$CI_JOB_ID-web_journey-$TARGET_ID-$URL_HASH" \
        -H 'content-type: application/json' \
        -d "$(jq -cn --arg url "$PREVIEW_URL" '{url: $url, scanType: "web_journey"}')" \
        "$BASE/api/v1/targets/$TARGET_ID/scans" | jq -r .scanId)

      # A journey is judged by its diffs; minComplianceScore belongs to a compliance test.
      GATE=$(jq -rn '{failOnSeverity:"critical",failOnBrokenStep:true} | @uri')

      RES=''
      for _ in $(seq 1 20); do
        RES=$(curl -fsS -H "Authorization: Bearer $ANALYTICSPROOF_API_KEY" \
          "$BASE/api/v1/scans/$SID?wait=120&gate=$GATE&include=diffs&scope=direct-datalayer")
        case "$(echo "$RES" | jq -r 'if .settled == false then "settling" else .status end')" in
          completed|failed|cancelled|broken_step|no_data) break ;;
        esac
      done

      echo "$RES" | jq '{status, settled, score, gate, warnings}'
      [ "$(echo "$RES" | jq -r '.settled != false and .gate.passed == true')" = "true" ] || {
        echo "AnalyticsProof gate failed"
        echo "$RES" | jq -r '.diffs[]?'
        exit 1
      }

# No key: request the free Web Compliance scan of one URL.
# 202 with a slug to poll, or 200 with cached: true and the result when the
# URL (query string and fragment ignored) was scanned in the last 28 days.
curl -fsS -X POST "$BASE/api/v1/public/scans" \
  -H "Content-Type: application/json" -d '{"url":"https://www.example.com"}'
curl -fsS "$BASE/api/v1/public/scans/<SLUG>"

# With a key of permission read: everything stored about one scan.
# Screenshot links in it work without a session for 15 minutes.
curl -fsS -H "Authorization: Bearer $AP_KEY" \
  "$BASE/api/v1/scans/<SCAN_ID>/evidence?steps=0,3"

https://analyticsproof.com/api/v1/openapi.json