links

POST `/v1/site-links/ingest`

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

Kimlik Doğrulama

Bu uç nokta arakatmana açıktır. Kimlik bilgisi ve organizasyon gerektirmez; kendi pazarlama sitemizin ve yapay zeka yanıt motorlarımızın okuduğu yerdir.

Bu uç nokta hiçbir organizasyon kimliği almaz. Anahtarınız zaten ait olduğu organizasyonu tanımlar ve yanıt bu organizasyonla sınırlandırılır.

Dene

Köşeli parantez içindeki her şeyi kendi değerlerinizle ve anahtar yer tutucusunu panonuzdan bir anahtarla değiştirin.

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

Oturum açtınız mı? Panonuzdaki API konsolu, gerçek organizasyon kimliğinizi ve kendi anahtarınızı otomatik olarak doldurur ve isteği canlı API üzerinde çalıştırarak gerçek yanıtı görmenizi sağlar. Bu uç noktayı API konsolunda açın

Ayrıntılar

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.

Parametreler

Ad	Tür	Zorunlu	Ne olduğu
`X-Zinn-Cache-Timestamp (header)`	`string`	Evet	Unix seconds. Signed as part of the material, which is what bounds a replay.
`X-Zinn-Cache-Signature (header)`	`string`	Evet	`sha256=<hex>`.

İstek gövdesi

Ad	Tür	Zorunlu	Ne olduğu
`site`	`string`	Evet	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`	Evet	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`	Hayır	⛔ 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`	Hayır	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[]`	Hayır	—

Yanıt

Ad	Tür	Zorunlu	Ne olduğu
`accepted`	`boolean`	Evet	—
`ignored`	`boolean`	Evet	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`	Evet	—
`links`	`integer`	Evet	—
`truncated`	`boolean`	Evet	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`	Evet	This batch completed the pass, so the snapshot sweep ran.
`removed`	`integer`	Evet	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`	Hayır	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…

Bu uç noktanın dönderebileceği hatalar

401 · 404 · 422 · 503

POST /v1/site-links/ingest