offerprobe.com · Developer page (your key, quick start) · openapi.yaml · Plans

OfferProbe API

offerprobe v0.1 · async REST · authenticate every call (except /healthz) with X-API-Key, or from the web app with a session's Authorization: Bearer token

The machine-readable contract is openapi.yaml (OpenAPI 3.1), also served by the API at GET /openapi.yaml and /openapi.json; generate a client or a Postman collection from it. This page is the same contract with the reasoning behind each field.

Model

A test browses one tracking link through a proxy matching the requested targeting and returns what a real user would reach. Tests run asynchronously: submitting returns 202 with an id; poll GET /v1/tests/{id} or receive a webhook. Status flow: queued → running → done | failed. done means the engine produced a result — the result's own success/verdict say how the offer fared; failed means the engine could not run at all. The owner's first GET of a finished test counts as having read it: an account gets a result mail only for a finished test nobody fetched within a minute (and for every full-mode test), so a client that polls gets no mail.

POST /v1/tests

{
  "url": "https://track.example/click?id=1",   // required, public http(s)
  "country": "BR",                             // required: the country the visitor comes from
  "carrier": "Claro",                          //   carrier name (or ASN name fragment)
  "device_type": "mobile",                     //   mobile | residential | datacenter
  "expect": "com.some.app",                    // expected destination → verdict (see below)
  "os": "Android",                             // how the visitor should look; pick one of
  "os_version": "12",                          //   the entries in /v1/options → devices[]
  "browser": "Chrome Mobile",
  "fresh": true,                               // guarantee an unused fingerprint for this test
  "state": "California",                       // precision targeting: the server provisions a
  "city": "Los Angeles",                       //   matching exit for this test and releases it
  "asn": "AS7922",                             //   afterwards (requires country)
  "isp": "deutsche telekom ag",
  "mode": "standard",                          // lite | standard | full, see below
  "screenshot": true,                          // default true in standard and full; lite never captures
  "skip_visits": 2,                            // 0–20, cloaker bypass; standard and full only, 400 with mode lite
  "webhook_url": "https://you.example/hook",   // optional completion push
  "reference": "camp-7"                        // your own label: echoed on the test and in the webhook, a list filter
}

→ 202 {"id": "…", "status": "queued", "queue_position": 3, "estimated_wait_seconds": 90}. Unknown fields are rejected (a typo must fail loudly). Send an Idempotency-Key header (any string unique to the request, up to 200 characters, scoped to your key and kept 24 hours) and a retry after a timeout replays the first answer with Idempotent-Replayed: true instead of queueing and billing a second test; the same key with another body is 409 idempotency_conflict, and while the first request is still in flight 409 idempotency_in_progress. A refused request releases the key, so the same retry succeeds once the refusal's cause is gone. A test with no country is refused with 400 country_required: a visit comes from somewhere, and a browse straight from our host is an operator's tool. queue_position is 1 for the next test to run; the wait is the position over the number of browser slots times the median recent run, an estimate, and both fields also appear on GET while the test is queued.

mode — how much evidence, and how long the slot is held

You describe the visit you want, not the machinery that makes it. provider, proxy_id and profile_id are refused with 400: which supplier is used, which exit is provisioned and which stored fingerprint is loaded are server decisions. Everything above is the full targeting vocabulary.

expect — what the link should reach

GET /v1/tests/{id}

{
  "id": "…", "status": "done",
  "request": { …as submitted… },
  "verdict": "working",                        // indexed from the result
  "final_url": "https://play.google.com/…",
  "created_at": "…", "started_at": "…", "finished_at": "…",
  "result_expired_at": "…",                    // present once the plan's history window passed: result gone, verdict kept
  "result": {
    "success": true, "verdict": "working", "verdict_reason": "…",
    "expected": "app:com.some.app", "destination_app": "app:com.some.app",
    "outcome": "captured", "final_url": "…", "page_title": "…",
    "redirect_chain": [{"url":"…","source_url":"…","status_code":302,"kind":"http"}],
    "capture": {"frames": [{"name":"lander","url":"…",
                            "screenshot_url":"https://api…/v1/tests/…/frames/0?exp=…&sig=…",
                            "timing_ms":1200,"cta_text":"CLAIM NOW"}]},
    "capture_mode": "deep", "capture_stop_reason": "reached_terminal",
    "capture_stop_detail": "…", "transport_verdict": "…",
    "error_code": "…", "errors": ["…"],
    "timing": {"total_ms": 18400, "redirects_count": 3},
    "recording_url": "https://api…/v1/tests/…/recording?exp=…&sig=…",   // mode full
    "recording_format": "webm", "recording_duration_ms": 30000,
    "recording_continuations": [{"url":"…","recording_url":"…/recording/0?exp=…&sig=…","duration_ms":5000}],
    "evidence_expires_at": "2026-09-20T12:00:00Z",
    "visit": {
      "country": "BR", "carrier": "Claro", "connection": "mobile",
      "exit_ip": "177.44.x.x",                 // masked
      "asn": "AS28573",                        // only if the test targeted asn/isp
      "match": "fallback",                     // exact | fallback
      "requested": {"country":"BR","carrier":"Claro","device_type":"mobile"},
      "device": {"os":"Android 12","browser":"Chrome Mobile 131",
                 "device_type":"mobile","screen":"720x1600","pixel_ratio":3,
                 "touch":true,"language":"pt-BR","timezone":"America/Sao_Paulo",
                 "user_agent":"Mozilla/5.0 …"}
    }
  }
}

visit is how the offer saw you. It is deliberately descriptive rather than operational: there is no proxy id, credential, supplier name or fingerprint id in it, and error on a failed test is a sentence chosen by its error_code, never the engine's own text — error_code is the field to branch on. visit.match is exact when the country, carrier and device type you asked for all served, fallback when another carrier in the country (or another device type) did, with visit.requested naming what you asked for; a test with no targeting carries neither. A carrier is best effort: the queue creates the exit at whichever supplier lists the carrier (pick it from /v1/directory/carriers, or type any name), and only when none does, or every exit for it is dead, does the test run from another carrier in the same country, saying so here rather than failing. A carrier named without a device_type is served as a mobile exit: a carrier is a mobile network, and the carrier list defaults to mobile.

Screenshots and recordings

Evidence is never inlined. Every screenshot_url and recording_url is a signed link that serves the object with no API key, so an <img> or <video> element can load it directly; the recording routes honour Range, so a player can seek. The links share one deadline, evidence_expires_at (default one hour after the GET); fetching the test again mints fresh ones. A frame without an image has no screenshot_url.

The same paths also answer to the owner's X-API-Key with no exp/sig, which is what a script wants. A tampered or foreign link is 403 evidence_link_invalid; a link past its deadline is 403 evidence_link_expired; neither credential is 401. The stored result keeps object keys, not bytes, and the key is never published.

capture_stop_reason says why the click-through ended. Besides the terminal ones (reached_app_store_intent, reached_deep_offer_domain, user_input_required) and the failures, two are budgets: max_clicks (the per-mode click cap, 8 for standard and 12 for full by default) and revisited_page, set when a click navigated back to a page already captured — the funnel was cycling, and the frames already show everything it has.

Verdicts

A failed test (engine could not run) is billed like inconclusive: never.

Targeting data — build the test form from these

Precision targeting

country, carrier and device_type are matched against exits that already exist. state, city, asn and isp are finer than any pool can be held at, so putting one of them on a test makes the server provision an exit that matches, run the test pinned to it, and release it when the test finishes. Nothing extra to call, and no proxy lifecycle to manage from the client — that machinery is operator-side.

Operators: proxy provisioning, the fingerprint template library, tests pinned to a specific exit and the raw engine JSON live on the admin plane, which listens on loopback only and requires an operator key (key create --role operator).

Other endpoints

Accounts and keys

Accounts are held by the identity service at <app origin>/api/auth/* (Better Auth: sign-up with email and password confirmed by mail, magic-link sign-in, password reset, sessions). The API never sees a password. A signed-in browser fetches a 15-minute token from GET /api/auth/token and sends it as Authorization: Bearer …; the API verifies it against the service's JWKS and acts as the account's primary key, created on first sight. Everything below is scoped to the account: a session, or any of the account's keys, sees the tests every key of the account created, including keys since revoked.

A key on any of these answers 403 session_required: a leaked key must not be able to mint a permanent one.

Billing

Plans are sold by a payment provider (Creem, a merchant of record that handles tax). The API starts the purchase, moves a subscriber to another plan and hands out the portal; the provider's webhook is the only thing that changes an account's plan.

After paying, the customer returns to /billing?checkout=success; after a switch they stay on the page. Either way the plan changes when the webhook lands, usually within seconds. GET /v1/usage then carries "subscription": {"status", "past_due", "period_end", "pending_plan"}: status is the provider's word (active, scheduled_cancel …), period_end is when a cancelled plan lapses or a pending downgrade takes effect, and pending_plan {"id", "name"} is present while a downgrade waits. Bearer refusals: 401 session_invalid, 401 session_expired (fetch a new token), 403 email_unverified, and 401 session_disabled on a server without auth.jwks_url.

Webhook

On completion the server POSTs a small event to webhook_url (one retry after 30 s):

POST <webhook_url>
Content-Type: application/json
User-Agent: OfferProbe-Webhook/1
X-OfferProbe-Event-Id: evt_…
X-OfferProbe-Signature: t=1790000000,v1=<hex>

{"id": "evt_…", "event": "test.finished", "created_at": "2026-09-26T12:00:00Z",
 "test_id": "…", "status": "done", "verdict": "working",
 "reference": "camp-7", "batch_id": "…"}          // reference and batch_id when the test has them

// when the engine could not run at all:
{…, "status": "failed", "verdict": "",
 "error": "the test engine could not run", "error_code": "engine_failed"}

// when it ran but failed before observing the offer:
{…, "status": "done", "verdict": "inconclusive",
 "error": "the exit could not be reached", "error_code": "tunnel_failed"}

Fetch the full result via GET /v1/tests/{id} — events stay small on purpose. error is a sentence chosen by error_code (one per code, never the engine's text). It is present exactly on the runs that are not billed: a failed test, and a done test whose result.success is false, where verdict_reason carries the same sentence; error_code is the field to branch on.

Verify the signature. v1 is HMAC-SHA256 over <t>.<raw body> keyed with the account's webhook_secret (GET /v1/account shows it, POST /v1/account/webhook-secret rotates it; the Developer page has both). Compute it over the bytes as received, compare in constant time, and refuse a t more than a few minutes from now, so a captured event cannot be replayed. In Python: hmac.compare_digest(v1, hmac.new(secret, f"{t}.".encode() + body, "sha256").hexdigest()). A test created by a key without an account (an operator's) is delivered unsigned.

What a delivery will not do. The POST is made from our host, so it is held to the target rule (public http(s) only) and, after DNS resolution, to public addresses only: a hostname that resolves to a private, loopback or link-local address is refused, and no redirect is followed (a 301 is a failed delivery, not a GET somewhere else). POST /v1/webhooks/test with {"url": "…"} sends one signed webhook.test event through the same rules, no retry, and answers {"event_id", "signed", "delivered", "status", "error"}, so a receiver is checked before a test depends on it.

Errors & limits

• Every error body carries an error_code: the specific ones below, else the generic one for the status: 400 validation_error (the message names the field), 401 unauthorized (missing or invalid key or session token), 403 forbidden, 404 not_found (not yours, or no such thing), 409 conflict (already_finished on a cancel), 500 internal, 503 unavailable (the API is restarting: Retry-After 10, from the edge).
• Back pressure. 503 queue_full when the whole queue is at its cap, 429 concurrency_limit when a single test would only wait behind your plan's one busy slot (an account's queued tests wait their turn; the queue runs at most the plan's max_concurrent of them at once, so a batch of the plan's size is always admitted; a plan-less key keeps a queued-plus-running cap), 429 guest_limit when a guest token's allowance is spent. Every 429 carries Retry-After in seconds. A batch is admitted whole or refused whole.
• Plan limits. 429 quota_exceeded when the plan's billable tests for the UTC calendar month are spent, counting tests queued or running as already spent (Retry-After runs to the first of next month); 429 daily_limit likewise for a plan with a daily cap (Retry-After to midnight UTC); 403 plan_feature for a mode the plan does not run (the free plan runs lite only; the message names the cheapest plan that runs it); 400 batch_limit when a batch is larger than the plan allows; 402 payment_past_due while a failed payment holds the account. Inconclusive, failed and cancelled tests never count. Each of these refusals also carries plan ({"id", "name"}), resets_at (quota and daily limits: when the count resets, RFC 3339) and, where the catalogue has one, upgrade: the cheapest plan that lifts the limit, as {"id", "name", "price_usd_month", "monthly_tests", "max_concurrent", "max_batch"}, so a client can offer one next step without reading the catalogue.
• Headroom on every create. POST /v1/tests and POST /v1/test-batches answer, accepted or refused, with X-Usage-Limit (the cap that binds: the month's, else the day's; a guest token's allowance), X-Usage-Remaining (what is left after everything queued or running, the accepted test included) and X-Usage-Reset (when the count resets, RFC 3339), so a client branches before the wall. Operator keys have no cap and no headers. GET /v1/usage shows the plan's modes, caps and headroom before you hit any of them: remaining_month and period_end, and for a plan with a daily cap remaining_day and day_end.
• error_code on a test names why a run failed before observing the offer: on a failed test one of engine_failed, timeout, provisioning_failed; on a done test with result.success false the engine's own token, such as no_matching_proxy (no exit for that country, carrier and device type could be found or created right now), tunnel_failed, proxy_conn_reset, dns_error, tls_error, timeout, browser_engine_missing or unknown; on a done test whose browser opened but whose exit died before the offer answered, proxy_transport_failed or proxy_auth_failed (result.success stays true, the verdict is inconclusive, nothing is billed). Tokens are only ever added.
• error_code accompanies every refusal above, the guest rules (guest_mode: free tests run the guest mode, use no webhook and target no state, city, ASN or ISP; guest_forbidden), country_required, and the evidence links (evidence_link_invalid, evidence_link_expired); it is the field to branch on, the error sentence may change.
• request_id is in every error body, and every response carries it as the X-Request-Id header (exposed to browser code). Quote it when reporting a problem: it names the one line in our log that describes your request.
• Target and webhook URLs must be public http(s): localhost, private and link-local IPs, dotless hosts and .local are rejected. DNS-rebinding is out of scope here: proxied tests egress through an external proxy that cannot reach the operator's LAN, and a test without a country (the one path that would browse from our host) is refused on this API.
• Request bodies are capped (max_body_bytes, default 1 MB); batches at 100 tests.
• Keys are minted by a signed-in account on POST /v1/keys, or by the operator with offerprobe key create --name …; shown once, storage holds only a SHA-256.