API overview
Base URL: https://api.vulnify.io
The machine contract is the public OpenAPI document at https://api.vulnify.io/openapi.json (OpenAPI 3.0, API version 0.3.0, contract v1). CORS allows any origin. Schema tables on the reference pages are generated from that document when the site is built. If the API cannot be reached, the build uses the copy committed in this repository at openapi/openapi.json, so the site still builds.
Send the API key on every /v1/ call, either as Authorization: Bearer or as X-API-Key. Both carry the same secret. It is not a JWT. See Authentication.
Machine endpoints
Section titled “Machine endpoints”| Method | Path | Purpose |
|---|---|---|
POST |
/v1/events |
Decide an action before it runs. |
GET |
/v1/events/{id} |
Read that same decision, including review status. |
POST |
/v1/gateway/http |
Decide an HTTP call and, when allowed, forward it. |
POST |
/v1/gateway/mcp |
Decide an MCP tool call. The tool name is mapped to an action. |
GET |
/v1/policies |
List organization policies. Any non-revoked key. |
POST |
/v1/policies/apply |
Create, update, and optionally delete policies. Org-wide LIVE key only. |
POST |
/v1/policies/test |
Evaluate policy cases. Writes no event and no audit entry. |
POST /v1/events and GET /v1/events/{id} return the same decision body, including finalDecision, quotaExceeded, and sandbox. The SDKs call those two routes. Gateway routes are configured in the app. The SDKs do not create them.
An idempotent replay of POST /v1/events, POST /v1/gateway/http, or POST /v1/gateway/mcp returns the stored decision and always includes finalDecision, derived from the stored decision and the current review. The Idempotency-Key window is 24 hours for the same organization and endpoint. The response header is Idempotent-Replay: true. See Authentication.
Outside the machine contract
Section titled “Outside the machine contract”These GET routes respond without an API key. They are not listed in openapi.json. See Public endpoints.
| Method | Path | Purpose |
|---|---|---|
GET |
/health |
Liveness. Includes version and apiVersion. |
GET |
/public/plans |
Agent limits, monthly event quotas, and retention days. |
GET |
/public/dlp-types |
Content-scanning detectors and LGPD categories. |
GET |
/public/config |
Deployment flags such as whether billing and plan changes are enabled. |
POST /public/contact is in the OpenAPI document because the marketing site submits its contact form there. It is the landing-site form, not a customer API, so it is omitted from this reference navigation. See Public endpoints.
The app’s own screens talk to a cookie-authenticated API under the app host. That API is how the dashboard manages agents, policies, and keys. It is not the API your agent calls, and it is not documented here. The CLI is the supported way to pull, apply, and test policies.
Webhooks
Section titled “Webhooks”The OpenAPI webhooks object describes deliveries Vulnify sends to your endpoint: decision, anomaly, and test. Each body includes eventId. Decision data includes decision and finalDecision. See Webhook deliveries for the generated tables and Webhooks for signing and retries.