Public REST API (v1)

The v1 API gives scripts, dashboards and CI jobs read access to your organization's data, plus deployment approval. It uses organization API keys, not user sessions.

The machine-readable spec is at /openapi/v1.yaml (OpenAPI 3.1). Import it into Postman, Insomnia or a code generator.

AuthenticationCopy Anchor Link

Create a key in Admin Console > API keys (admin role required). The full key is shown once, at creation. Send it as a bearer token:

Authorization: Bearer plk_live_xxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Production keys start with plk_live_; development keys start with plk_test_. A key issued for one environment is rejected by the other. Every key carries a fixed set of scopes, granted when it was created:

Revoking a key from Settings takes effect within about 60 seconds.

AvailabilityCopy Anchor Link

The API requires a plan with API access. A key created under a plan without it, or a plan that later drops it, gets 402 feature_not_available on every request. Requests the gateway itself rejects, before a key is ever checked against a plan, get the gateway's own body instead of the Error envelope:

• No Authorization header: 401 {"message": "Unauthorized"}
• Malformed, revoked, expired, wrong-environment, or wrong-scope key: 403 {"message": "Forbidden"}

Every other error responds with the Error envelope described below.

Pagination and time windowsCopy Anchor Link

List endpoints take limit (default 50, max 100), cursor, since and until. Responses carry next_cursor (null on the last page) and a meta block:

{
  "data": [ /* … */ ],
  "next_cursor": "eyJwayI6Ik9SRyMxMjMi...",
  "meta": {
    "since": "2026-08-01T00:00:00Z",
    "until": "2026-09-27T00:00:00Z",
    "retention_clamped": false
  }
}

Reuse the same since and until when following next_cursor. If since predates your plan's data retention window, the server moves it forward and sets meta.retention_clamped to true rather than erroring.

ErrorsCopy Anchor Link

Every non-gateway error uses the same envelope:

{
  "error": {
    "code": "not_found",
    "message": "No run with that id.",
    "details": {}
  }
}

Approving deploymentsCopy Anchor Link

POST /v1/deployments/{id}/approve and POST /v1/deployments/{id}/reject take a JSON body with a reason and an optional comment. An API key with write:deployments can answer only Prodgator's own protection rule, and must give a reason of 10-500 characters (the same rule as an admin override in the app); without one the request fails with reason_required. Prodgator audits the answer as the key, records it on the deployment with principal api_key, and posts a comment on the provider such as "Approved via Prodgator API key CI deploy (reason: Hotfix for the checkout outage)".

A deployment gated by GitHub's own required reviewers can only be approved by a reviewer's own GitHub account, in the app or on GitHub. API keys cannot act as a GitHub user, and Prodgator never falls back to the organization's token, so a key gets reviewer_gate_requires_human. When a deployment has both gates, the key answers Prodgator's rule first; the response's status stays pending_approval until a reviewer answers the GitHub gate, and a further key request returns reviewer_gate_requires_human.

curl -s -X POST \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"reason": "Hotfix for the checkout outage"}' \
  https://api.prodgator.io/v1/deployments/$DEPLOYMENT_ID/approve

Security findingsCopy Anchor Link

GET /v1/security/findings returns scan results paged with cursor. Requires read:security scope.

GET /v1/security/issues returns unique findings with member_count (scan results in the finding) and source_count (number of sources). Requires read:security scope and Business plan or higher.

Uploading reports: see Upload a report for the POST /v1/security/uploads, POST /v1/security/uploads/{id}/complete and GET /v1/security/uploads/{id} routes. Requires write:security-findings scope.

ExampleCopy Anchor Link

curl -s \
  -H "Authorization: Bearer $API_KEY" \
  "https://api.prodgator.io/v1/runs?status=failure&limit=25"