Developer API

The Btagly engine, in your stack

Submit a page, get back per-link verdicts and the evidence behind them, from the same auditor the extension and the Telegram monitor run on. REST over HTTPS, JSON in and out.

Get API access → Manage your keys →

Included with Agency on either product (the extension plan or the Telegram tier). A dedicated pool of 20,000 engine checks a month.

⇆

Audit any page

POST a page and its links. Btagly resolves every redirect chain in its native market and classifies the destination.

◧

Pull verdicts and evidence

Poll results as JSON, or fetch the full evidence report as CSV or a white-label PDF when a brand is set.

◷

A dedicated quota

20,000 checks a month, separate from the extension audit pool and the Telegram daily cap. No surprise overage.

Quickstart

Submit a page in one call

Base URL https://api.btagly.app. Authenticate with a key from your dashboard, then POST the page and its links.

POST /v1/audits

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",
    "device": "desktop",
    "links": [
      { "url": "https://example-affiliate-site.com/visit/operator",
        "anchorText": "Claim bonus", "classification": "cloaked" }
    ]
  }'

Response

{ "auditId": "a1b2c3d4-...", "checksPlanned": 1 }

By default each link is checked once in its own native market (auto-geo). Pass an explicit "geos" array to check across markets instead. Markets: GB, DE, MT, SE, NL. Classifications: affiliate, cloaked, shortener.

Reference

Endpoints

POST/v1/auditsSubmit an audit

GET/v1/auditsList recent audits

GET/v1/audits/:idOne audit with per-link verdicts

GET/v1/audits/:id/diffWhat changed since the last run

GET/v1/reports/:id.csvEvidence report, inline CSV

GET/v1/reports/:id.pdfEvidence report, signed PDF URL

GET/v1/monitorsManage scheduled monitors

GET/v1/rulesetsManage rule sets

Authentication

Keys

Create and revoke keys from your dashboard (btagly.app/dashboard → API, Agency on either product). Keys look like btgly_live_…, are shown once at creation, and can be revoked at any time. Send the key either way:

Authorization

# 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

Keys act on behalf of the whole workspace. Key management itself needs a signed-in session (only the workspace owner can create or revoke), never a key, so a leaked key can never mint more of itself.

Results

Poll, then fetch evidence

Poll

# 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

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. Monitors and rule sets are manageable over the same API, with the same request shapes as the extension.

Errors

Status codes

401Invalid or revoked key

402Plan limit (geos, seats), with a human-readable message

403Feature not in your plan

429API check quota reached for the month, with the count remaining

404Not found, or not yours

Every error body is { "error": "…" }.

Need an endpoint that isn't here?

Tell us what you're building. We add shapes as teams need them.

hello@btagly.app