The Pentrova REST API exposes everything the product UI does: targets, scans, findings, chains, and the replayable PoC bundles attached to each finding. This overview describes the resources, the authentication model, and the conventions every endpoint follows. Individual endpoint pages document the exact request and response shapes.
Base URL#
All endpoints are served from https://api.pentrova.ai/v1/. Version is part of the path; breaking changes ship as a new version with a deprecation window for the prior one.
Authentication#
Every request authenticates with an API key issued from the workspace settings page. Keys are scoped to a workspace and carry one of three roles: reader, operator, or admin. Include the key in the Authorization header:
Authorization: Bearer pk_live_...
Rotating a key is safe; the old key stays valid for a configurable grace window so automation has time to cut over.
Resources#
The API is organised around five primary resources:
targets— the logical applications Pentrova scans.scans— one execution of the agent catalog against a target.findings— the verified results of a scan, each carrying a PoC bundle.chains— static or dynamic escalation paths that link multiple findings.bundles— the evidence bundles attached to each finding. Each bundle includes a reproducible command and a response hash a recipient can re-check.
Every resource has the standard REST verbs (GET, POST, PATCH, DELETE) with a consistent pagination and filter model.
Pagination and filters#
List endpoints page on cursor, not offset, to keep pagination stable across live mutations. Pass limit to cap the page size (default 50, maximum 200). Pass filter as a JSON-encoded object to narrow the result set.
GET /v1/findings?filter={"severity":"high","status":"open"}&limit=100
The filter grammar is the same across every resource and documented on each endpoint’s reference page.
Errors#
Errors return a structured JSON body with code, message, docs_url, and an optional details object. Status codes follow the usual conventions: 400 for invalid input, 401 for missing credentials, 403 for insufficient role, 404 for unknown resources, 429 for rate-limit hits, and 5xx for server failures.
Rate limits#
API keys are rate-limited at the workspace level. Default limits are 600 requests per minute sustained, 60 requests per second burst. Exceeded limits return 429 Too Many Requests with a Retry-After header. Burst limits reset every second; sustained limits reset every minute.
Next steps#
Individual endpoint pages cover the exact fields on each resource. The targets reference documents the full TargetConfig schema, the findings reference covers filter semantics, and the bundles reference explains how to download and verify a PoC bundle locally.