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.

The endpoint reference lists every route with its parameters, request and response schemas, required scope, and curl, JavaScript and Python samples. It is read-only: nothing on these pages sends a request. To try read operations from the app, use the API explorer.

• Runs: list and read pipeline runs.
• Deployments: list, read, approve and reject deployments.
• Security: alerts, findings, issues and report uploads.
• Compliance: policy results.
• Provenance: signing keys and signed statements.
• Any CI: record runs, reports, attestations and artifacts from any CI system, and open release gates.

AuthenticationCopy Anchor Link

Create a key in Organization > API keys (Org 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 in Organization > API keys takes effect within about 60 seconds.

AvailabilityCopy Anchor Link

The API requires a plan with API access, except the CI operations below, which every plan can use. 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": {}
  }
}

Rate limitsCopy Anchor Link

Every /v1 route counts requests per minute for your organization and for each API key, in fixed one-minute windows. A request over either limit gets 429 with the rate_limited code and a Retry-After header with the seconds until the next window. One key cannot use the whole organization's allowance, and each organization is counted apart from every other. A per-route limit at the API gateway, shared by all callers, also applies; its 429 is a plain message without the rate_limited envelope or Retry-After.

All numbers are requests per minute. Back off on 429, or spread requests over the minute. Cache the attestation keys from /v1/provenance/keys: they change rarely.

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)".

When a Block compliance policy covers the deployment's environment, the answer overrides a compliance decision, so the key also needs the write:compliance-override scope. The same applies when Prodgator cannot read the compliance policies at that moment. Without the scope the request fails before anything is sent to the provider:

{
  "error": {
    "code": "insufficient_scope",
    "message": "A blocking compliance policy governs this environment, or its policies could not be read. Overriding it needs an API key with the write:compliance-override scope.",
    "details": { "requiredScope": "write:compliance-override" }
  }
}

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

CI operationsCopy Anchor Link

The /v1/ci operations let a pipeline in any CI system record a run, send its reports and open a release gate. The prodgator-report command line calls them for you. They do not use the other routes' gateway authorizer: Prodgator checks the credential itself, which is one of:

• An API key with the write:ci scope (see CI keys), sent as Authorization: Bearer plk_.... It works on every plan and does not need API access. If the key has a repository allowlist, a run for another repository is refused with repository_not_allowed.
• An OIDC token from an issuer your organization trusts (see Integrations), sent as Authorization: Bearer <jwt>. A request that disagrees with a mapped claim is refused with claim_mismatch.

GET /v1/ci/gates/{gate_id} takes neither. It takes the poll token that POST /v1/ci/gates returns (pcg_..., valid for 12 hours), sent as a bearer token. That token reads one gate and nothing else, so a build log that leaks it cannot record runs.

Everything these routes store is self-reported (trust: self_reported): policies ignore it unless a rule opts in, and it never counts as provider provenance. A gate answer is one of pending, approved, rejected, closed or expired; deploy only on approved and treat anything else as a refusal. Runs count toward your plan's run and pipeline limits. Requests are limited per credential (120 a minute) and per organization, and polling a gate to 12 a minute; a 429 carries Retry-After.

Further error codes: repository_not_allowed, claim_mismatch, run_finished, quota_exceeded, payload_too_large, kind_not_allowed, gate_not_configured, gate_token_invalid, gate_token_expired and provider_unavailable (503, safe to retry).

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.

Signed attestationsCopy Anchor Link

GET /v1/provenance/keys lists the public keys that verify Prodgator's signed attestations. It needs the read:attestations scope and a plan with API access. The three statement routes return a signed in-toto statement in a DSSE envelope, as { "data": { "envelope": { ... }, "statement_digest": "..." } }:

• GET /v1/provenance/changes/{id}/statement: the change record.
• GET /v1/provenance/deployments/{id}/lineage/statement: the promotion path.
• GET /v1/provenance/deployments/{id}/verification: a SLSA verification summary of the deployment.

They need read:attestations and the Enterprise plan. A statement that cannot be signed in the record's current state answers 409 conflict with the cause in error.details.reason. If signing or storage is unavailable the answer is 503 and nothing unsigned is returned. Attestations lists the causes and shows how to verify a statement offline.

ExampleCopy Anchor Link

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