{"openapi":"3.1.0","info":{"title":"Hole Monitor API","version":"1.0.0","summary":"Webhooks for security advisories.","description":"Live. Hole Monitor POSTs a signed OSV record to every endpoint whose filters match a new or materially changed advisory.\n\nAuthentication: an API key as `Authorization: Bearer hm_...`, or the dashboard session cookie. Keys, billing and account deletion need a session.\n\nErrors are RFC 9457 problem documents. Lists use cursor pagination: pass `next_cursor` back as `cursor`.\n\nPOST routes accept an `Idempotency-Key` header. A repeat with the same key within 24 hours returns the stored response with `Idempotent-Replayed: true` and changes nothing.\n\nRate limits: 120 requests a minute per API key, 300 a minute per IP address without a key. Every response carries `RateLimit-Policy`; a refused request gets 429 with `RateLimit` and `Retry-After`.\n\nThe webhook request and body are described under `webhooks`.\n"},"servers":[{"url":"https://api.holemonitor.live","description":"API host"},{"url":"https://holemonitor.live","description":"Site host","serves the same routes":null}],"tags":[{"name":"auth"},{"name":"account"},{"name":"keys"},{"name":"billing"},{"name":"endpoints"},{"name":"filters"},{"name":"deliveries"},{"name":"advisories"},{"name":"meta"},{"name":"ingest"},{"name":"admin","description":"Session only. Requires an account with the admin flag. A call that changes anything writes an audit entry."}],"paths":{"/auth/link":{"post":{"tags":["auth"],"operationId":"requestLoginLink","summary":"Request a magic link","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","format":"email"},"turnstile_token":{"type":"string"}},"required":["email","turnstile_token"]}}}},"responses":{"202":{"description":"Accepted. The same response whether or not the address has an account. At most 3 links per address and 10 per IP address an hour.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"detail":{"type":"string"}}}}}},"default":{"$ref":"#/components/responses/Problem"}}}},"/auth/confirm":{"post":{"tags":["auth"],"operationId":"confirmLogin","summary":"Consume a login token and start a session","description":"The token is the one in the emailed link's fragment. It works once, within 15 minutes, and only by POST. Sets the `hm_session` cookie (HttpOnly, Secure, SameSite=Lax, 30 days from last use).","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"token":{"type":"string"}},"required":["token"]}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Account"}}}},"default":{"$ref":"#/components/responses/Problem"}}}},"/auth/logout":{"post":{"tags":["auth"],"operationId":"logout","summary":"End the session","security":[{"session":[]}],"responses":{"204":{"description":"Success"},"default":{"$ref":"#/components/responses/Problem"}}}},"/oauth/device":{"post":{"tags":["auth"],"operationId":"deviceAuthorization","summary":"Start a device sign-in for a coding agent (RFC 8628)","security":[],"requestBody":{"required":true,"content":{"application/x-www-form-urlencoded":{"schema":{"type":"object","properties":{"scope":{"enum":["read","write"],"default":"write"},"client_name":{"type":"string","maxLength":60,"description":"Shown to the person when they approve."}}}}}},"responses":{"200":{"description":"A code for the person to approve","content":{"application/json":{"schema":{"type":"object","properties":{"device_code":{"type":"string"},"user_code":{"type":"string","example":"WXYZ-BCDF"},"verification_uri":{"type":"string","format":"uri"},"verification_uri_complete":{"type":"string","format":"uri"},"expires_in":{"type":"integer"},"interval":{"type":"integer"}}}}}},"400":{"$ref":"#/components/responses/OAuthError"}}}},"/oauth/register":{"post":{"tags":["auth"],"operationId":"registerClient","summary":"Register an MCP client (RFC 7591). Public clients only; PKCE replaces a client secret.","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["redirect_uris"],"properties":{"redirect_uris":{"type":"array","minItems":1,"maxItems":10,"items":{"type":"string","format":"uri"},"description":"https, http on a loopback address (any port), or an app scheme."},"client_name":{"type":"string","maxLength":60}}}}}},"responses":{"201":{"description":"Registered","content":{"application/json":{"schema":{"type":"object","properties":{"client_id":{"type":"string"},"client_id_issued_at":{"type":"integer"},"redirect_uris":{"type":"array","items":{"type":"string"}},"token_endpoint_auth_method":{"const":"none"}}}}}},"400":{"$ref":"#/components/responses/OAuthError"}}}},"/oauth/authorize":{"get":{"tags":["auth"],"operationId":"authorize","summary":"Start an authorization code sign-in with PKCE. Redirects the person to /activate to approve.","security":[],"parameters":[{"name":"response_type","in":"query","required":true,"schema":{"const":"code"}},{"name":"client_id","in":"query","required":true,"schema":{"type":"string"}},{"name":"redirect_uri","in":"query","schema":{"type":"string","format":"uri"}},{"name":"code_challenge","in":"query","required":true,"schema":{"type":"string"}},{"name":"code_challenge_method","in":"query","required":true,"schema":{"const":"S256"}},{"name":"state","in":"query","schema":{"type":"string"}},{"name":"scope","in":"query","schema":{"type":"string","example":"write"}},{"name":"resource","in":"query","schema":{"type":"string","format":"uri"},"description":"RFC 8707. Must be this server's /mcp URL or API base."}],"responses":{"302":{"description":"To /activate","or back to the client with an error":null},"default":{"$ref":"#/components/responses/Problem"}}}},"/oauth/token":{"post":{"tags":["auth"],"operationId":"token","summary":"Collect the API key, by device code (RFC 8628) or authorization code with PKCE (RFC 7636)","security":[],"requestBody":{"required":true,"content":{"application/x-www-form-urlencoded":{"schema":{"oneOf":[{"type":"object","required":["grant_type","device_code"],"properties":{"grant_type":{"const":"urn:ietf:params:oauth:grant-type:device_code"},"device_code":{"type":"string"}}},{"type":"object","required":["grant_type","code","client_id","code_verifier"],"properties":{"grant_type":{"const":"authorization_code"},"code":{"type":"string"},"client_id":{"type":"string"},"code_verifier":{"type":"string"},"redirect_uri":{"type":"string"},"resource":{"type":"string"}}}]}}}},"responses":{"200":{"description":"Approved. The key is returned once. A client that signs in again gets a new key and its previous one is revoked.","content":{"application/json":{"schema":{"type":"object","properties":{"access_token":{"type":"string","description":"An API key","hm_...":null},"token_type":{"const":"Bearer"},"scope":{"enum":["read","write"]}}}}}},"400":{"$ref":"#/components/responses/OAuthError"}}}},"/v1/device/{code}":{"get":{"tags":["auth"],"operationId":"getDeviceRequest","summary":"Read a pending sign-in (device or MCP client) by its user code","security":[{"session":[]}],"parameters":[{"name":"code","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"The request"},"default":{"$ref":"#/components/responses/Problem"}}}},"/v1/device/{code}/approve":{"post":{"tags":["auth"],"operationId":"approveDevice","summary":"Approve a sign-in, choosing read or write. For an MCP client the response has the redirect back to it.","security":[{"session":[]}],"parameters":[{"name":"code","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"scope":{"enum":["read","write"]}}}}}},"responses":{"200":{"description":"Approved"},"default":{"$ref":"#/components/responses/Problem"}}}},"/v1/device/{code}/deny":{"post":{"tags":["auth"],"operationId":"denyDevice","summary":"Deny a sign-in","security":[{"session":[]}],"parameters":[{"name":"code","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Denied"},"default":{"$ref":"#/components/responses/Problem"}}}},"/v1/account":{"get":{"tags":["account"],"operationId":"getAccount","summary":"Plan, limits and usage","security":[{"apiKey":[]},{"session":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Account"}}}},"default":{"$ref":"#/components/responses/Problem"}}},"delete":{"tags":["account"],"operationId":"deleteAccount","summary":"Delete the account","security":[{"session":[]}],"responses":{"204":{"description":"Success"},"default":{"$ref":"#/components/responses/Problem"}}}},"/v1/keys":{"get":{"tags":["keys"],"operationId":"listKeys","summary":"List API keys","security":[{"session":[]}],"parameters":[{"$ref":"#/components/parameters/Limit"},{"$ref":"#/components/parameters/Cursor"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiKeyList"}}}},"default":{"$ref":"#/components/responses/Problem"}}},"post":{"tags":["keys"],"operationId":"createKey","summary":"Create an API key","security":[{"session":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"scope":{"enum":["read","write"]}},"required":["scope"]}}}},"responses":{"201":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiKey"}}}},"default":{"$ref":"#/components/responses/Problem"}},"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}]}},"/v1/keys/{id}":{"delete":{"tags":["keys"],"operationId":"revokeKey","summary":"Revoke an API key","security":[{"session":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"Success"},"default":{"$ref":"#/components/responses/Problem"}}}},"/v1/billing/checkout":{"post":{"tags":["billing"],"operationId":"startCheckout","summary":"Start a Stripe Checkout session","security":[{"session":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"plan":{"enum":["starter","pro","business"]},"interval":{"enum":["month","year"]}},"required":["plan","interval"]}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Url"}}}},"default":{"$ref":"#/components/responses/Problem"}},"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}]}},"/v1/billing/portal":{"post":{"tags":["billing"],"operationId":"openPortal","summary":"Open the Stripe customer portal","security":[{"session":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Url"}}}},"default":{"$ref":"#/components/responses/Problem"}},"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}]}},"/v1/endpoints":{"get":{"tags":["endpoints"],"operationId":"listEndpoints","summary":"List endpoints","security":[{"apiKey":[]},{"session":[]}],"parameters":[{"$ref":"#/components/parameters/Limit"},{"$ref":"#/components/parameters/Cursor"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EndpointList"}}}},"default":{"$ref":"#/components/responses/Problem"}}},"post":{"tags":["endpoints"],"operationId":"createEndpoint","summary":"Create an endpoint and send its verification request","security":[{"apiKey":[]},{"session":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","format":"uri"},"description":{"type":"string"},"content":{"enum":["structured","full"]},"format":{"enum":["osv","csaf","cyclonedx"],"description":"Body format. osv (default) is an OSV 1.9.2 record, csaf a CSAF 2.0 document, cyclonedx a CycloneDX 1.6 BOM. See /docs/payload/."}},"required":["url"]}}}},"responses":{"201":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Endpoint"}}}},"default":{"$ref":"#/components/responses/Problem"}},"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}]}},"/v1/endpoints/{id}":{"get":{"tags":["endpoints"],"operationId":"getEndpoint","summary":"Read an endpoint","security":[{"apiKey":[]},{"session":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Endpoint"}}}},"default":{"$ref":"#/components/responses/Problem"}}},"patch":{"tags":["endpoints"],"operationId":"updateEndpoint","summary":"Change URL or description, pause or resume","description":"A changed URL returns the endpoint to `unverified` and sends a new verification request. An endpoint disabled by an administrator or by a 410 response cannot be set active by its owner.","security":[{"apiKey":[]},{"session":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","format":"uri"},"description":{"type":"string"},"status":{"enum":["active","paused"]},"content":{"enum":["structured","full"]},"format":{"enum":["osv","csaf","cyclonedx"],"description":"Body format. osv (default) is an OSV 1.9.2 record, csaf a CSAF 2.0 document, cyclonedx a CycloneDX 1.6 BOM. See /docs/payload/."}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Endpoint"}}}},"default":{"$ref":"#/components/responses/Problem"}}},"delete":{"tags":["endpoints"],"operationId":"deleteEndpoint","summary":"Delete an endpoint","security":[{"apiKey":[]},{"session":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"Success"},"default":{"$ref":"#/components/responses/Problem"}}}},"/v1/endpoints/{id}/verify":{"post":{"tags":["endpoints"],"operationId":"verifyEndpoint","summary":"Send the verification request again, or submit the code","security":[{"apiKey":[]},{"session":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"$ref":"#/components/parameters/IdempotencyKey"}],"description":"With `code`, activates the endpoint when it matches the code sent to it. Without, sends the verification request again, at most 5 times per endpoint per hour.","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string"}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Endpoint"}}}},"default":{"$ref":"#/components/responses/Problem"}}}},"/v1/endpoints/{id}/rotate-secret":{"post":{"tags":["endpoints"],"operationId":"rotateSecret","summary":"Issue a new signing secret","description":"The previous secret stays valid for 24 hours, during which each request carries one signature per secret.","security":[{"apiKey":[]},{"session":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"$ref":"#/components/parameters/IdempotencyKey"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Endpoint"}}}},"default":{"$ref":"#/components/responses/Problem"}}}},"/v1/endpoints/{id}/test":{"post":{"tags":["endpoints"],"operationId":"sendTest","summary":"Send a sample event marked as a test","security":[{"apiKey":[]},{"session":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"type":{"enum":["published","updated","kev_added","withdrawn"]}}}}}},"responses":{"202":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Delivery"}}}},"default":{"$ref":"#/components/responses/Problem"}}}},"/v1/endpoints/{id}/filters":{"get":{"tags":["filters"],"operationId":"listFilters","summary":"List an endpoint's filters","security":[{"apiKey":[]},{"session":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"$ref":"#/components/parameters/Limit"},{"$ref":"#/components/parameters/Cursor"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FilterList"}}}},"default":{"$ref":"#/components/responses/Problem"}}},"post":{"tags":["filters"],"operationId":"createFilter","summary":"Create a filter","security":[{"apiKey":[]},{"session":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"conditions":{"$ref":"#/components/schemas/Conditions"}},"required":["conditions"]}}}},"responses":{"201":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Filter"}}}},"default":{"$ref":"#/components/responses/Problem"}}},"put":{"tags":["filters"],"operationId":"replaceFilters","summary":"Replace an endpoint's whole filter set","security":[{"apiKey":[]},{"session":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"filters":{"type":"array","items":{"type":"object","properties":{"conditions":{"$ref":"#/components/schemas/Conditions"}},"required":["conditions"]}}},"required":["filters"]}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FilterList"}}}},"default":{"$ref":"#/components/responses/Problem"}}}},"/v1/filters/{id}":{"patch":{"tags":["filters"],"operationId":"updateFilter","summary":"Replace a filter's conditions","security":[{"apiKey":[]},{"session":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"conditions":{"$ref":"#/components/schemas/Conditions"}},"required":["conditions"]}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Filter"}}}},"default":{"$ref":"#/components/responses/Problem"}}},"delete":{"tags":["filters"],"operationId":"deleteFilter","summary":"Delete a filter","security":[{"apiKey":[]},{"session":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"Success"},"default":{"$ref":"#/components/responses/Problem"}}}},"/v1/filters/preview":{"post":{"tags":["filters"],"operationId":"previewFilter","summary":"List retained events the conditions would have matched","security":[{"apiKey":[]},{"session":[]}],"parameters":[{"$ref":"#/components/parameters/Limit"},{"$ref":"#/components/parameters/Cursor"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"conditions":{"$ref":"#/components/schemas/Conditions"},"since":{"type":"string","format":"date-time"}},"required":["conditions"]}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PreviewHitList"}}}},"default":{"$ref":"#/components/responses/Problem"}}}},"/v1/deliveries":{"get":{"tags":["deliveries"],"operationId":"listDeliveries","summary":"Delivery log","security":[{"apiKey":[]},{"session":[]}],"parameters":[{"$ref":"#/components/parameters/Limit"},{"$ref":"#/components/parameters/Cursor"},{"name":"endpoint","in":"query","schema":{"type":"string"}},{"name":"status","in":"query","schema":{"enum":["queued","delivered","failed","deferred"]}},{"name":"since","in":"query","schema":{"type":"string","format":"date-time"}},{"name":"include","in":"query","schema":{"enum":["body"]}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeliveryList"}}}},"default":{"$ref":"#/components/responses/Problem"}}}},"/v1/deliveries/{id}/redeliver":{"post":{"tags":["deliveries"],"operationId":"redeliver","summary":"Queue a delivery again","description":"Keeps the delivery ID, so `webhook-id` is unchanged. Possible while the event is retained and the endpoint is active.","security":[{"apiKey":[]},{"session":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"$ref":"#/components/parameters/IdempotencyKey"}],"responses":{"202":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Delivery"}}}},"default":{"$ref":"#/components/responses/Problem"}}}},"/v1/advisories":{"get":{"tags":["advisories"],"operationId":"searchAdvisories","summary":"Search stored advisories, newest published first","description":"Starter plan and above; other plans get 403 with `limit` set to `advisory_search`. Vendor and product given together match one affected entry. Vendor, product and package values are normalized the way filter terms are. Records without a CVSS score are left out when `min_cvss` is set. Withdrawn records are left out unless `include_withdrawn` is true.","security":[{"apiKey":[]},{"session":[]}],"parameters":[{"name":"vendor","in":"query","schema":{"type":"string","maxLength":128}},{"name":"product","in":"query","schema":{"type":"string","maxLength":128}},{"name":"ecosystem","in":"query","description":"With package","schema":{"type":"string"}},{"name":"package","in":"query","description":"With ecosystem","schema":{"type":"string"}},{"name":"purl","in":"query","description":"A purl without a version","schema":{"type":"string"}},{"name":"published_since","in":"query","description":"Inclusive. ISO 8601 date or UTC date-time","schema":{"type":"string"}},{"name":"published_until","in":"query","description":"Exclusive. ISO 8601 date or UTC date-time","schema":{"type":"string"}},{"name":"min_cvss","in":"query","schema":{"type":"number","minimum":0,"maximum":10}},{"name":"kev","in":"query","schema":{"type":"boolean"}},{"name":"exploited","in":"query","schema":{"type":"boolean"}},{"name":"source","in":"query","schema":{"enum":["cve","nvd","ghsa","drupal","drupal_osv","kev","wordfence","epss","redhat","vulncheck_kev","osv"]}},{"name":"include_withdrawn","in":"query","schema":{"type":"boolean","default":false}},{"name":"content","in":"query","schema":{"enum":["structured","full"]}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":200,"default":50}},{"name":"cursor","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/OsvRecord"}},"next_cursor":{"type":["string","null"]}}}}}},"default":{"$ref":"#/components/responses/Problem"}}}},"/v1/advisories/{id}":{"get":{"tags":["advisories"],"operationId":"getAdvisory","summary":"The current merged record, by any alias","security":[{"apiKey":[]},{"session":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"content","in":"query","schema":{"enum":["structured","full"]}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OsvRecord"}}}},"default":{"$ref":"#/components/responses/Problem"}}}},"/v1/openapi.json":{"get":{"tags":["meta"],"operationId":"getOpenApi","summary":"This document","security":[],"responses":{"200":{"description":"Success"},"default":{"$ref":"#/components/responses/Problem"}}}},"/status":{"get":{"tags":["meta"],"operationId":"getStatus","summary":"Last successful run of each source adapter","security":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"enum":["ok","degraded"]},"sources":{"type":"array","items":{"$ref":"#/components/schemas/SourceStatus"}}}}}}},"default":{"$ref":"#/components/responses/Problem"}}}},"/healthz":{"get":{"tags":["meta"],"operationId":"getHealth","summary":"Liveness check","security":[],"responses":{"200":{"description":"Success"}}}},"/billing/webhook":{"post":{"tags":["ingest"],"operationId":"stripeWebhook","summary":"Plan changes from Stripe, verified by Stripe's signature","description":"Verifies `Stripe-Signature` (HMAC-SHA256, 5 minute tolerance). Handles checkout.session.completed, customer.subscription.created, updated and deleted, and invoice.paid. A lapse to free pauses endpoints beyond the free limit, oldest kept.","security":[],"parameters":[{"name":"Stripe-Signature","in":"header","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{}}}}},"responses":{"200":{"description":"Success"},"default":{"$ref":"#/components/responses/Problem"}}}},"/ingest/wordfence":{"post":{"tags":["ingest"],"operationId":"wordfenceWebhook","summary":"Wordfence records, verified by Wordfence's signature","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{}}}}},"responses":{"204":{"description":"Success"},"default":{"$ref":"#/components/responses/Problem"}}}},"/v1/admin/stats":{"get":{"tags":["admin"],"operationId":"adminStats","summary":"Totals for the admin overview","security":[{"session":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"advisories":{"type":"integer"},"events_24h":{"$ref":"#/components/schemas/Counts"},"accounts_by_plan":{"$ref":"#/components/schemas/Counts"},"endpoints_by_status":{"$ref":"#/components/schemas/Counts"},"deliveries_24h":{"$ref":"#/components/schemas/Counts"},"deliveries_queued_over_1h":{"type":"integer"}}}}}},"default":{"$ref":"#/components/responses/Problem"}}}},"/v1/admin/sources":{"get":{"tags":["admin"],"operationId":"adminListSources","summary":"List source adapters and their health","security":[{"session":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SourceList"}}}},"default":{"$ref":"#/components/responses/Problem"}}}},"/v1/admin/sources/{source}":{"patch":{"tags":["admin"],"operationId":"adminUpdateSource","summary":"Pause or resume an adapter, or reset its cursor","security":[{"session":[]}],"parameters":[{"name":"source","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"enabled":{"type":"boolean"},"cursor":{"type":"string"}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Source"}}}},"default":{"$ref":"#/components/responses/Problem"}}}},"/v1/admin/sources/{source}/run":{"post":{"tags":["admin"],"operationId":"adminRunSource","summary":"Run an adapter now and report the result","security":[{"session":[]}],"parameters":[{"name":"source","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"The run's result (counts, or an error) and the source's status after it","content":{"application/json":{"schema":{"type":"object","properties":{"source":{"type":"string"},"result":{},"status":{"$ref":"#/components/schemas/Source"}}}}}},"default":{"$ref":"#/components/responses/Problem"}}}},"/v1/admin/advisories/{id}/replay":{"post":{"tags":["admin"],"operationId":"adminReplayAdvisory","summary":"Rebuild a record from its stored source fragments","security":[{"session":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"raise_event":{"type":"boolean"}}}}}},"responses":{"202":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"advisory_id":{"type":"string"},"event_id":{"type":["string","null"]},"event_type":{"type":["string","null"]}}}}}},"default":{"$ref":"#/components/responses/Problem"}}}},"/v1/admin/accounts":{"get":{"tags":["admin"],"operationId":"adminListAccounts","summary":"Search accounts","security":[{"session":[]}],"parameters":[{"$ref":"#/components/parameters/Limit"},{"$ref":"#/components/parameters/Cursor"},{"name":"email","in":"query","schema":{"type":"string"}},{"name":"plan","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdminAccountList"}}}},"default":{"$ref":"#/components/responses/Problem"}}}},"/v1/admin/accounts/{id}":{"get":{"tags":["admin"],"operationId":"adminGetAccount","summary":"Read an account","security":[{"session":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdminAccount"}}}},"default":{"$ref":"#/components/responses/Problem"}}},"patch":{"tags":["admin"],"operationId":"adminUpdateAccount","summary":"Suspend, restore, change the plan of, or cancel an account","security":[{"session":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"suspended":{"type":"boolean"},"plan":{"enum":["free","starter","pro","business"],"description":"Set a complimentary plan, or free to cancel. Cancelling also cancels any Stripe subscription. A plan with fewer endpoints pauses those beyond its limit. A paid change is refused while a Stripe subscription is live."},"paid_through":{"type":["string","null"],"format":"date-time"}},"minProperties":1}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdminAccount"}}}},"default":{"$ref":"#/components/responses/Problem"}}}},"/v1/admin/endpoints":{"get":{"tags":["admin"],"operationId":"adminListEndpoints","summary":"List endpoints across accounts","security":[{"session":[]}],"parameters":[{"$ref":"#/components/parameters/Limit"},{"$ref":"#/components/parameters/Cursor"},{"name":"account","in":"query","schema":{"type":"string"}},{"name":"status","in":"query","schema":{"type":"string"}},{"name":"host","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EndpointList"}}}},"default":{"$ref":"#/components/responses/Problem"}}}},"/v1/admin/endpoints/{id}":{"patch":{"tags":["admin"],"operationId":"adminUpdateEndpoint","summary":"Disable or restore an endpoint","security":[{"session":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"enum":["active","disabled"]}},"required":["status"]}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Endpoint"}}}},"default":{"$ref":"#/components/responses/Problem"}}}},"/v1/admin/deliveries":{"get":{"tags":["admin"],"operationId":"adminListDeliveries","summary":"Delivery log across accounts","security":[{"session":[]}],"parameters":[{"$ref":"#/components/parameters/Limit"},{"$ref":"#/components/parameters/Cursor"},{"name":"endpoint","in":"query","schema":{"type":"string"}},{"name":"status","in":"query","schema":{"type":"string"}},{"name":"since","in":"query","schema":{"type":"string","format":"date-time"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeliveryList"}}}},"default":{"$ref":"#/components/responses/Problem"}}}},"/v1/admin/vendor-aliases":{"get":{"tags":["admin"],"operationId":"adminListVendorAliases","summary":"List vendor name variants","security":[{"session":[]}],"parameters":[{"$ref":"#/components/parameters/Limit"},{"$ref":"#/components/parameters/Cursor"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VendorAliasList"}}}},"default":{"$ref":"#/components/responses/Problem"}}}},"/v1/admin/vendor-aliases/{variant}":{"put":{"tags":["admin"],"operationId":"adminPutVendorAlias","summary":"Map a variant to a canonical vendor name","security":[{"session":[]}],"parameters":[{"name":"variant","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"canonical":{"type":"string"}},"required":["canonical"]}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VendorAlias"}}}},"default":{"$ref":"#/components/responses/Problem"}}},"delete":{"tags":["admin"],"operationId":"adminDeleteVendorAlias","summary":"Remove a variant","security":[{"session":[]}],"parameters":[{"name":"variant","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"Success"},"default":{"$ref":"#/components/responses/Problem"}}}},"/v1/admin/audit":{"get":{"tags":["admin"],"operationId":"adminListAudit","summary":"Audit log","security":[{"session":[]}],"parameters":[{"$ref":"#/components/parameters/Limit"},{"$ref":"#/components/parameters/Cursor"},{"name":"account","in":"query","schema":{"type":"string"}},{"name":"action","in":"query","schema":{"type":"string"}},{"name":"since","in":"query","schema":{"type":"string","format":"date-time"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuditEntryList"}}}},"default":{"$ref":"#/components/responses/Problem"}}}}},"webhooks":{"advisoryEvent":{"post":{"summary":"An advisory event, delivered to a matching endpoint","description":"Signed as Standard Webhooks describes: `webhook-signature` is `v1,` and the base64 HMAC-SHA256 of `{webhook-id}.{webhook-timestamp}.{body}`, keyed with the endpoint secret (base64 after `whsec_`). During a rotation it carries one signature per secret, space-delimited.\n`webhook-id` is the delivery ID and repeats on every attempt and redelivery. Reject timestamps more than 5 minutes old and discard IDs already processed.\nAny 2xx is success. 410 disables the endpoint. Anything else is retried up to 11 attempts over about 3 days. Redirects are not followed; the timeout is 10 seconds.\nThe event type is inside the body at `database_specific.event.type`. Verification requests carry `{\"type\": \"verification\", \"code\": ...}` instead of an OSV record.\n","parameters":[{"name":"webhook-id","in":"header","required":true,"schema":{"type":"string"}},{"name":"webhook-timestamp","in":"header","required":true,"schema":{"type":"integer"}},{"name":"webhook-signature","in":"header","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OsvRecord"}}}},"responses":{"200":{"description":"Any 2xx acknowledges the delivery"},"410":{"description":"Disables the endpoint"}}}}},"components":{"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer","description":"An API key, sent as Authorization: Bearer hm_..."},"session":{"type":"apiKey","in":"cookie","name":"hm_session"}},"parameters":{"Limit":{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":200,"default":50}},"Cursor":{"name":"cursor","in":"query","schema":{"type":"string"}},"IdempotencyKey":{"name":"Idempotency-Key","in":"header","description":"A unique string per intended change. A repeat within 24 hours returns the stored response.","schema":{"type":"string","maxLength":255}}},"headers":{"RateLimitPolicy":{"description":"The caller's limit, for example `120;w=60`.","schema":{"type":"string"}},"RateLimit":{"description":"Current state, for example `limit=120, remaining=0, reset=60`.","schema":{"type":"string"}},"RetryAfter":{"description":"Seconds to wait after a 429.","schema":{"type":"integer"}}},"responses":{"OAuthError":{"description":"An RFC 6749 error, such as authorization_pending, slow_down, access_denied, expired_token or invalid_grant","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"error_description":{"type":"string"}}}}}},"Problem":{"description":"An error, as an RFC 9457 problem document. A 429 carries RateLimit and Retry-After.","headers":{"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"schemas":{"Problem":{"type":"object","required":["type","title","status"],"properties":{"type":{"type":"string","format":"uri"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"limit":{"type":"string"},"errors":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"message":{"type":"string"}}}}}},"Account":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string","format":"email"},"plan":{"enum":["free","starter","pro","business"]},"is_admin":{"type":"boolean"},"paid_through":{"type":["string","null"],"format":"date-time"},"limits":{"$ref":"#/components/schemas/Counts"},"features":{"type":"object","properties":{"advisory_search":{"type":"boolean","description":"GET /v1/advisories is available. Starter and above."}}},"usage":{"$ref":"#/components/schemas/Counts"}}},"Counts":{"type":"object","additionalProperties":{"type":"integer"}},"ApiKey":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":["string","null"]},"prefix":{"type":"string"},"scope":{"enum":["read","write"]},"created":{"type":"string","format":"date-time"},"last_used":{"type":["string","null"],"format":"date-time"},"revoked":{"type":["string","null"],"format":"date-time"},"secret":{"type":"string","description":"Returned only when the key is created."}}},"Endpoint":{"type":"object","properties":{"id":{"type":"string"},"content":{"enum":["structured","full"]},"format":{"enum":["osv","csaf","cyclonedx"]},"url":{"type":"string","format":"uri"},"description":{"type":["string","null"]},"status":{"enum":["unverified","active","paused","disabled"]},"status_reason":{"type":["string","null"],"description":"Why the endpoint is paused or disabled, for example owner, plan lapsed, 410 Gone, admin."},"first_failure":{"type":["string","null"],"format":"date-time"},"last_success":{"type":["string","null"],"format":"date-time"},"created":{"type":"string","format":"date-time"},"updated":{"type":"string","format":"date-time"},"secret":{"type":"string","description":"Returned only on creation and on rotation."}}},"Package":{"type":"object","description":"Either ecosystem and name, with an optional version, or a purl with an optional version and no qualifiers or subpath. With a version, the package matches only advisories that do not show that version as unaffected. See /docs/filters.","properties":{"ecosystem":{"type":"string"},"name":{"type":"string"},"version":{"type":"string","maxLength":128},"purl":{"type":"string","maxLength":512}}},"Conditions":{"type":"object","properties":{"sources":{"type":"array","items":{"type":"string"}},"event_types":{"type":"array","items":{"enum":["published","updated","kev_added","withdrawn"]}},"vendors":{"type":"array","items":{"type":"string"}},"products":{"type":"array","items":{"type":"string"}},"packages":{"type":"array","items":{"$ref":"#/components/schemas/Package"}},"min_cvss":{"type":"number","minimum":0,"maximum":10},"include_unscored":{"type":"boolean"},"min_epss":{"type":"number","minimum":0,"maximum":1},"kev_only":{"type":"boolean"},"exploited_only":{"type":"boolean"},"drupal_risk":{"type":"array","items":{"type":"string"}}}},"Filter":{"type":"object","properties":{"id":{"type":"string"},"endpoint_id":{"type":"string"},"is_broad":{"type":"boolean"},"terms":{"type":"integer"},"created":{"type":"string","format":"date-time"},"conditions":{"$ref":"#/components/schemas/Conditions"}}},"Delivery":{"type":"object","properties":{"id":{"type":"string"},"endpoint_id":{"type":"string"},"event_id":{"type":"string"},"advisory_id":{"type":"string"},"event_type":{"enum":["published","updated","kev_added","withdrawn","verification"]},"kind":{"enum":["event","test","verify"]},"status":{"enum":["queued","delivered","failed","deferred"]},"attempts":{"type":"integer"},"last_error":{"type":["string","null"]},"last_status_code":{"type":["integer","null"]},"last_duration_ms":{"type":["integer","null"]},"created":{"type":"string","format":"date-time"},"updated":{"type":"string","format":"date-time"},"body":{"description":"Present with include=body, in the endpoint's content mode and format.","$ref":"#/components/schemas/OsvRecord"}}},"OsvRecord":{"type":"object","description":"An OSV 1.9.2 record. Service-specific facts are under database_specific, including the event block at database_specific.event. Full JSON Schema at https://holemonitor.live/schemas/webhook-payload.json.","externalDocs":{"url":"https://holemonitor.live/docs/payload"},"required":["id","modified"],"additionalProperties":true},"PreviewHit":{"type":"object","properties":{"event_id":{"type":"string"},"advisory_id":{"type":"string"},"event_type":{"enum":["published","updated","kev_added","withdrawn"]},"created":{"type":"string","format":"date-time"}}},"SourceStatus":{"type":"object","properties":{"source":{"type":"string"},"last_success":{"type":["string","null"],"format":"date-time"},"stale":{"type":"boolean"}}},"Source":{"type":"object","properties":{"source":{"type":"string"},"enabled":{"type":"boolean"},"cursor":{"type":["string","null"]},"next_due":{"type":["string","null"],"format":"date-time"},"last_run":{"type":["string","null"],"format":"date-time"},"last_success":{"type":["string","null"],"format":"date-time"},"last_error":{"type":["string","null"]},"stale":{"type":"boolean"}}},"AdminAccount":{"allOf":[{"$ref":"#/components/schemas/Account"},{"type":"object","properties":{"is_admin":{"type":"boolean"},"suspended":{"type":"boolean"},"created":{"type":"string","format":"date-time"}}}]},"VendorAlias":{"type":"object","properties":{"variant":{"type":"string"},"canonical":{"type":"string"}}},"AuditEntry":{"type":"object","properties":{"id":{"type":"string"},"account_id":{"type":["string","null"]},"action":{"type":"string"},"detail":{"type":["object","null"]},"at":{"type":"string","format":"date-time"}}},"Url":{"type":"object","properties":{"url":{"type":"string","format":"uri"}}},"ApiKeyList":{"type":"object","required":["data","next_cursor"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ApiKey"}},"next_cursor":{"type":["string","null"]}}},"EndpointList":{"type":"object","required":["data","next_cursor"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Endpoint"}},"next_cursor":{"type":["string","null"]}}},"FilterList":{"type":"object","required":["data","next_cursor"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Filter"}},"next_cursor":{"type":["string","null"]}}},"DeliveryList":{"type":"object","required":["data","next_cursor"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Delivery"}},"next_cursor":{"type":["string","null"]}}},"PreviewHitList":{"type":"object","required":["data","next_cursor"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/PreviewHit"}},"next_cursor":{"type":["string","null"]}}},"SourceList":{"type":"object","required":["data","next_cursor"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Source"}},"next_cursor":{"type":["string","null"]}}},"AdminAccountList":{"type":"object","required":["data","next_cursor"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AdminAccount"}},"next_cursor":{"type":["string","null"]}}},"VendorAliasList":{"type":"object","required":["data","next_cursor"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/VendorAlias"}},"next_cursor":{"type":["string","null"]}}},"AuditEntryList":{"type":"object","required":["data","next_cursor"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AuditEntry"}},"next_cursor":{"type":["string","null"]}}}}}}