Developer reference

Wire InstaPin into your stack.

Two integration points: the Current Domain API your apps poll, and the Callback API that pushes signed events to you the moment something changes. Keys are created under Callbacks & API in the panel.

Authentication

Send your key in the X-API-Key header (or as a Bearer token). Keys are workspace-scoped; revoke them any time.

curl https://YOUR-INSTAPIN-HOST/api/v1/status \
  -H "X-API-Key: ip_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Current Domain API

Returns the domain traffic should use for a group right now: the flagged current domain, or the first healthy domain in priority order.

Method	Path	Description
GET	/api/v1/current-domain?group=main	Current domain for a group, with the full chain.
GET	/api/v1/domains	All monitored domains with status.
POST	/api/v1/domains	Bulk add: {"domains": ["a.com","b.com"], "group": "main"}
POST	/api/v1/domains/{id or name}/check	Manual check (counts toward your monthly manual-check quota).
GET	/api/v1/events	Latest 50 events (blocks, switches, detections).
GET	/api/v1/status	Plan and key health.

GET /api/v1/current-domain?group=main

{
  "group": "main",
  "domain": "brand-3.com",
  "status": "ok",
  "since": "2026-09-22T10:41:03.120Z",
  "url": "https://brand-3.com",
  "chain": [
    { "name": "brand-1.com", "priority": 10, "current": false, "status": "blocked" },
    { "name": "brand-3.com", "priority": 20, "current": true,  "status": "ok" },
    { "name": "brand-4.com", "priority": 30, "current": false, "status": "ok" }
  ],
  "checkedAt": "2026-09-22T10:45:12.004Z"
}

Callback API

Each callback endpoint receives a JSON POST per event. Verify the signature with the endpoint secret shown in the panel: HMAC-SHA256(secret, timestamp + "." + rawBody).

Header	Value
X-InstaPin-Event	Event name, e.g. domain.blocked
X-InstaPin-Timestamp	Unix seconds when the request was signed
X-InstaPin-Signature	sha256=<hex digest>

{
  "id": "88ea0f70-b2c7-47a1-a9d1-b7f901108a68",
  "event": "domain.blocked",
  "timestamp": "2026-09-22T10:45:12.004Z",
  "data": {
    "domain": "brand-1.com",
    "group": "main",
    "method": "dns-blockpage",
    "currentDomain": "brand-3.com",
    "detectedAt": "2026-09-22T10:45:11.900Z"
  }
}

Events: domain.blocked domain.unblocked domain.switched domain.family_filtered domain.dns_changed radar.detection gateway.down gateway.up callcenter.low_balance ping

// Node.js signature verification
import { createHmac, timingSafeEqual } from "crypto";

export function verify(req, rawBody, secret) {
  const ts = req.headers["x-instapin-timestamp"];
  const given = String(req.headers["x-instapin-signature"] || "").replace("sha256=", "");
  const expected = createHmac("sha256", secret).update(`${ts}.${rawBody}`).digest("hex");
  return given.length === expected.length && timingSafeEqual(Buffer.from(given), Buffer.from(expected));
}

Rate limits

Current Domain API: cache the answer for 30–60 seconds on your side; it changes only when a switch happens. Manual checks count toward your plan quota.

Retries

Callbacks time out after 10 seconds and are logged with the response code. Return 2xx quickly and process asynchronously.

Telegram actions

Inline buttons in alerts call the same operations as the panel: re-check, switch to next, acknowledge.