API

Agency plans include programmatic access to the same audit engine the extension uses: submit audits, poll results, and fetch evidence reports. Base URL: https://api.btagly.app

Authentication

Create API keys from the Btagly extension (account section → API keys; Agency plan required). Keys look like btgly_live_…, are shown once at creation, and can be revoked at any time. Send the key either way:

# as a bearer token
curl -H "Authorization: Bearer btgly_live_..." https://api.btagly.app/v1/me

# or as a header
curl -H "x-api-key: btgly_live_..." https://api.btagly.app/v1/me

API usage draws from the same monthly check pool as the extension (20,000 link-geo checks on Agency). Keys act on behalf of the whole workspace; key management itself is only possible from a signed-in session, never with a key.

Submit an audit

curl -X POST https://api.btagly.app/v1/audits \
  -H "x-api-key: btgly_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "pageUrl": "https://example-affiliate-site.com/best-offers",
    "geos": ["GB", "DE"],
    "device": "desktop",
    "links": [
      { "url": "https://example-affiliate-site.com/visit/operator",
        "anchorText": "Claim bonus", "classification": "cloaked" }
    ]
  }'

Returns { "auditId": "…" }. Geos: GB, DE, MT, SE, NL. Classifications: affiliate, cloaked, shortener. Each link × geo pair consumes one check; requests beyond your remaining pool return 402.

Poll results

# list recent audits
curl -H "x-api-key: btgly_live_..." https://api.btagly.app/v1/audits

# one audit with per-link verdicts (status: queued | running | done)
curl -H "x-api-key: btgly_live_..." https://api.btagly.app/v1/audits/AUDIT_ID

Fetch reports

# CSV, returned inline
curl -H "x-api-key: btgly_live_..." https://api.btagly.app/v1/reports/AUDIT_ID.csv

# PDF, returns a signed download URL
curl -H "x-api-key: btgly_live_..." https://api.btagly.app/v1/reports/AUDIT_ID.pdf

PDF reports honour your white-label brand when one is set in the extension. Monitors and rule sets are manageable over the same API (/v1/monitors, /v1/rulesets) with identical shapes to the extension’s requests.

Errors

401 invalid or revoked key · 402 plan limit (checks, geos, seats) with a human-readable message · 403 feature not in your plan · 404 not found or not yours. Every error body is { "error": "…" }.

Questions or a missing endpoint you need? hello@btagly.app