SEO discoverability push capability. Submits content URLs to IndexNow (Bing/Yandex) for a (host, key), and pings a WebSub/PubSubHubbub hub in publisher mode that a feed has updated. Both are stateless outbound actions. Also optionally serves the per-host IndexNow verification key file when a deploy owns the host→key map (public, unauthenticated — search engines HEAD-probe it).
- Group: Content & media
- Contract:
contracts/seo-discoverability/v1/openapi.yaml
- Public base:
https://api.vagarylabs.com (the consolidated API gateway — one host, per-brand sibling api.<zone>)
- Auth: a product API key (
vgk_…) issued from the console — Authorization: Bearer vgk_…
- Product face (customer-keyed):
https://api.vagarylabs.com/product/v1/seo/submit
Endpoints
| Method | Path | Summary |
|---|
POST | /v1/indexnow/submit | Submit a batch of URLs for one host to IndexNow (Bing/Yandex fan-out). Every URL must belong to the submitted host; the batch must be within the engine cap (default 10000). The key is taken from the body or the service's configured host→key map. |
| | |
POST | /v1/websub/publish | Ping the WebSub hub (publisher mode, hub.mode=publish) that a feed topic URL has new content. Stateless — the hub then fetches the feed and fans out to subscribers. |
| | |
GET | /{key}.txt | Serve the per-host IndexNow verification key file (public, unauthenticated). Responds only when the requested filename equals the requesting host's registered key; any other *.txt → 404. |
| | |
GET | /health | liveness + config posture (tenancy_enforced, stateless, key_hosts) |
GET | /metrics | Prometheus metrics (seo_indexnow_urls_submitted_total, seo_websub_publishes_total) |
Schemas
IndexNowSubmit
| Field | Type | Description |
|---|
organization_id | string | end-customer tenant (I6); resolved/verified server-side, never trusted raw |
host | string | the domain the URLs belong to (e.g. indexofnews.com) |
urls | array | URLs to submit; every URL must belong to host. Alias: urlList. |
key | string | IndexNow key; if omitted, taken from the service host→key map (domain config) |
IndexNowResult
| Field | Type | Description |
|---|
submitted | integer | |
host | string | |
upstream_status | integer | the IndexNow HTTP status (200/202 = accepted) |
WebSubPublish
| Field | Type | Description |
|---|
organization_id | string | end-customer tenant (I6); resolved/verified server-side |
topic_url | string | the feed URL that updated (WebSub topic) |
hub | string | override the default WebSub hub |
WebSubResult
| Field | Type | Description |
|---|
published | boolean | |
hub | string | |
topic_url | string | |
upstream_status | integer | |
Error
| Field | Type | Description |
|---|
error | string | stable machine code (validation_error |
reason | string | human-readable one-line explanation (no secrets/PII) |
detail | object | |
request_id | string | |
Generated by scripts/gen-capability-docs.py from contracts/seo-discoverability/v1/openapi.yaml — the contract IS the source of truth; edit the contract, not this page.