links

POST `/v1/site-links/ingest`

Receive one batch of a site's outbound-link scan (signed webhook).

توثيقِ شناخت

یہ اینڈ پوائنٹ عوامی ہے۔ یہ کوئی اسناد اور کوئی تنظیم نہیں لیتا — یہ وہ ہے جسے ہماری اپنی مارکیٹنگ سائٹ اور AI کے جواب دینے والے انجن پڑھتے ہیں۔

یہ اینڈ پوائنٹ کوئی آرگنائزیشن آئی ڈی نہیں لیتا۔ آپ کی کلید پہلے ہی اس آرگنائزیشن کی شناخت کرتی ہے جس سے یہ تعلق رکھتی ہے، اور اس کا جواب اسی کے مطابق محدود ہوتا ہے۔

آزمائیں

کوئی بھی چیز جو زاویہ دار قوسین میں ہو اسے اپنی اقدار سے بدلیں، اور کلیدی پلیس ہولڈر کو اپنے ڈیش بورڈ کی کسی کلید سے بدلیں۔

curl -X POST https://api.zinndigital.com/v1/site-links/ingest \
  -H "Content-Type: application/json" \
  -d '{ "site": <string>, "scan_id": <string> }'

لاگ ان ہیں؟ آپ کے ڈیش بورڈ میں موجود API کنسول آپ کی حقیقی تنظیم کی آئی ڈی اور آپ کی اپنی کلید خود بخود پُر کر دیتا ہے، اور لائیو API پر درخواست چلاتا ہے تاکہ آپ اصل ردعمل دیکھ سکیں۔ اس اینڈ پوائنٹ کو API کنسول میں کھولیں

تفصیلات

What a site's Zinn® plugin POSTs when its scheduled link scan runs: the posts it looked at, and for each one every outbound `<a>` tag it found, with how many times that tag appears in that post. **Machine-to-machine; there is no principal.** Authentication is the **same HMAC scheme** `ingestSiteEvents` uses — SHA-256 over `"<timestamp>\n<body>"` in `X-Zinn-Cache-Signature`, with `X-Zinn-Cache-Timestamp` carrying the unix seconds, against a secret **derived** per site from the platform master key. ⛔ Deliberately not a second scheme: one secret, one derivation, one place for the two ends to agree. The organisation comes from the **resolved site** and never from the body. **A scan is a SNAPSHOT, delivered in batches.** One pass over a site carries one `scan_id` across as many requests as it takes; the request carrying `complete: true` triggers reconciliation, which deletes every post and placement for that site not stamped with that pass. ⛔ That is what makes a link the customer **removed** disappear from the report — an append-only index rots into a permanent overcount and looks authoritative while it does. ⛔ **An abandoned pass deletes nothing.** No completing batch, no sweep: the report goes stale rather than wrong-by-deletion. ⛔ **A batch from a superseded pass is ignored whole** and answers `ignored: true`. The plugin's POST is fire-and-forget with a two-second timeout, so a batch landing after the next cron tick has begun is expected; mixing it in would let a finished pass sweep away the live one's rows. **Every refusal is uninformative on purpose** — an unknown hostname is a bare `404` and a bad signature a bare `401`, because a chattier answer would tell anyone who can guess a hostname which domains this platform hosts.

پیرامیٹرز

نام	قسم	لازمی	یہ کیا ہے
`X-Zinn-Cache-Timestamp (header)`	`string`	ہاں	Unix seconds. Signed as part of the material, which is what bounds a replay.
`X-Zinn-Cache-Signature (header)`	`string`	ہاں	`sha256=<hex>`.

درخواست کا باڈی

نام	قسم	لازمی	یہ کیا ہے
`site`	`string`	ہاں	The site's own `home_url()`. An untrusted claim — it selects which site's derived secret the signature is checked against, and nothing more.
`scan_id`	`string`	ہاں	Identifies the pass, not the request. Minted by the plugin, because one pass spans many requests and the engine cannot mint it. Opaque: nothing is inferred from its value, a…
`complete`	`boolean`	نہیں	⛔ Only a literal `true` ends the pass. A missing key, a `null` or the string `"false"` all mean "not complete", because reading one as complete would sweep away every post the s…
`posts_sent`	`integer`	نہیں	Posts this pass has sent so far, cumulative across batches, as counted by the site. ⛔⛔ Load-bearing on the completing batch: the POST is non-blocking, so a site never learns…
`posts`	`object[]`	نہیں	—

جواب

نام	قسم	لازمی	یہ کیا ہے
`accepted`	`boolean`	ہاں	—
`ignored`	`boolean`	ہاں	The batch belonged to a superseded pass and was dropped whole. Expected occasionally: the plugin's POST is fire-and-forget with a two-second timeout.
`posts`	`integer`	ہاں	—
`links`	`integer`	ہاں	—
`truncated`	`boolean`	ہاں	A post reported more links than the per-post ceiling and the tail was dropped. Surfaced rather than swallowed — a report that silently under-counts is worse than one that says i…
`reconciled`	`boolean`	ہاں	This batch completed the pass, so the snapshot sweep ran.
`removed`	`integer`	ہاں	Rows the sweep deleted. ⭐ The only externally visible proof the snapshot reconciliation works: a site whose links change while this stays `0` on every pass is the append-only ro…
`refused`	`string`	نہیں	Why a completing batch was not swept, when it was not — a lost batch, or one whose post list was truncated. ⛔ Reported rather than swallowed: a pass that keeps completing wi…

وہ خرابیان جو یہ اینڈ پوائنٹ واپس کر سکتا ہے

401 · 404 · 422 · 503

POST /v1/site-links/ingest