Partner API

The partner API is the HTTP API for clients that authenticate with an API key. It is served under /api/v1 on the same host as the console: requests to https://<pentr-host>/api/v1/… are routed to the partner API server, and every other path on that host is not. Request and response bodies are JSON, with the exceptions listed in Errors.

A call made with an API key acts for the key's organization. See Authentication.

Endpoints¶

Method	Path	Purpose	Page
POST	/api/v1/assets	Register an asset	Assets
GET	/api/v1/assets	List the organization's assets	Assets
DELETE	/api/v1/assets/{asset_id}	Delete an asset with no verification history	Assets
POST	/api/v1/assets/{asset_id}/verify	Run the automated ownership check	Assets
GET	/api/v1/assets/{asset_id}/verifications	Read an asset's verification log	Assets
POST	/api/v1/engagements	Create an engagement	Engagements
GET	/api/v1/engagements	List the organization's engagements	Engagements
GET	/api/v1/engagements/{engagement_id}	Read one engagement	Engagements
GET	/api/v1/engagements/{engagement_id}/findings	Read an engagement's findings	Engagements
POST	/api/v1/engagements/{engagement_id}/submit	Submit an engagement through the launch gate	Engagements
GET	/api/v1/engagements/{engagement_id}/report	Read the newest report's record	Reports
POST	/api/v1/schedules/preview	Preview a cadence's next three run times	Schedules
POST	/api/v1/schedules	Create a schedule	Schedules
GET	/api/v1/schedules	List the organization's schedules	Schedules
GET	/api/v1/schedules/{schedule_id}	Read one schedule	Schedules
PATCH	/api/v1/schedules/{schedule_id}	Change a schedule's name, cadence, timezone or enabled flag	Schedules
DELETE	/api/v1/schedules/{schedule_id}	Delete a schedule	Schedules
POST	/api/v1/webhooks	Register a webhook	Webhooks
GET	/api/v1/webhooks	List registered webhooks	Webhooks
DELETE	/api/v1/webhooks/{webhook_id}	Delete a webhook	Webhooks
GET	/api/v1/usage	Count the organization's engagements by status	Usage and limits

Status codes and error bodies are described in Errors.

The UI API¶

The console calls a second API, the UI API: routes under /api/… without the v1 segment, authenticated by the console's sign-in session rather than by an API key. Several operator pages in these docs use UI API routes for tasks the console has no screen for. The UI API is not documented as an integration surface, and an API key is not accepted on it.

Where to start¶

Read Authentication, then Assets. An engagement is refused at submit unless every target and every in-scope entry is covered by an asset whose ownership is proven.