CI API reference
Reference for Pentrova's CI API: X-API-Key authentication, POST /api/ci/scan request fields, status polling, SARIF and JUnit exports, and status codes.
Reading mode
Pentrova’s API for pipelines starts CI checks and returns their results. It is the same API the CI/CD integration guide uses.
Base URL and authentication#
All endpoints are served from https://app.pentrova.ai. Every request carries an organization API key in the X-API-Key header:
curl -H "X-API-Key: $PENTROVA_API_KEY" \
https://app.pentrova.ai/api/ci/scan/$SCAN_ID/status
Create keys under Profile & Settings → API keys. New keys have Read (scan:read) and Create scans (scan:create) selected; a pipeline key needs exactly those two. A key acts with its creator’s role, stops working if that person leaves the organization, and needs its creator to have multi-factor authentication set up. Revoke keys from the same page.
Endpoints#
| Method | Path | Purpose |
|---|---|---|
POST | /api/ci/scan | Start a CI check |
GET | /api/ci/scan/{scan_id}/status | Poll progress and the pass/fail verdict |
GET | /api/ci/scan/{scan_id}/sarif | Download findings as SARIF 2.1.0 |
GET | /api/ci/scan/{scan_id}/junit | Download findings as JUnit XML |
GET | /api/ci/scan/{scan_id}/export | Export the scan’s data as JSON or CSV |
GET | /api/ci/scan/{scan_id}/evidence-bundle | Download the evidence bundle, a zip of every confirmed finding’s proof, where the plan includes it |
GET | /api/ci/scans | List recent CI checks |
GET | /api/ci/verify | Check that the key and connection work |
GET | /api/ci/templates | List the CI templates; /api/ci/templates/{provider} returns one |
POST /api/ci/scan#
Starts a CI check. CI checks are part of the Continuous plan for the target.
| Field | Type | Default | Description |
|---|---|---|---|
target_url | string | required | URL to test, for example https://staging.example.com; must be on a verified domain |
scan_type | "web" or "api" | "web" | "web" crawls a website; "api" tests the endpoints in an OpenAPI or Swagger spec |
spec_url | string | none | Where to fetch the OpenAPI or Swagger spec; required when scan_type is "api" |
api_base_url | string | from the spec | Where the API is hosted, when the spec is served from somewhere else |
scan_mode | string | "UNAUTHENTICATED" | "AUTH_LLM_LOGIN" to sign in before testing |
login_url | string | none | Sign-in page; required with AUTH_LLM_LOGIN |
username | string | none | Test account username for signed-in checks |
password | string | none | Test account password for signed-in checks |
fail_on | object | {"critical": 0, "high": 0} | Maximum allowed findings per severity (critical, high, medium, low); 0 fails on any, null ignores. A missing critical or high stays 0; a missing medium or low is ignored |
wait | boolean | true | true holds the request until the check ends; false returns at once (recommended) |
timeout | integer | 3600 | Seconds to wait when wait is true, from 60 to 14400 |
callback_url | string | none | URL that receives a POST with the results when the check ends |
callback_signing_secret | string | none | When set, callbacks carry an X-Signature-256 header with the HMAC-SHA256 of the body, so the receiver can verify them |
tags | string array | none | Labels such as "pr-123" or "branch:main" |
auth_config | object | none | API check credentials: bearer (token), api_key (header, value), basic (username, password) or oauth2 (client_id, client_secret, token_url) |
custom_headers | object | none | Headers added to every request of an API check |
spec_auth_headers | object | none | Headers used to fetch spec_url, when the spec is in a private repository or behind authentication |
scope_regex | string | none | Only URLs matching this regular expression are tested |
Example:
curl -sS -X POST https://app.pentrova.ai/api/ci/scan \
-H "X-API-Key: $PENTROVA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"target_url": "https://staging.example.com",
"scan_type": "api",
"spec_url": "https://staging.example.com/openapi.json",
"auth_config": {"type": "bearer", "token": "'"$TEST_TOKEN"'"},
"fail_on": {"critical": 0, "high": 0},
"wait": false
}'
Response#
The start call (with "wait": true) and the status endpoint return the verdict in the same shape:
{
"scan_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"status": "completed",
"pass": false,
"reason": "2 CRITICAL findings exceed threshold (max 0)",
"severity_counts": {"critical": 2, "high": 5, "medium": 3, "low": 1, "info": 8},
"total_findings": 19,
"scan_url": "https://app.pentrova.ai/scans/a1b2c3d4-.../detail",
"sarif_url": "https://app.pentrova.ai/api/ci/scan/a1b2c3d4-.../sarif"
}
status ends as completed, failed, cancelled or incomplete. incomplete means the check finished but did not run cleanly; treat it as final. Shortly after starting, the status can briefly be unknown or queued; keep polling. With "wait": true, the start call can also return timeout when the check outlasts timeout; poll the status endpoint for the verdict.
Exports#
- SARIF 2.1.0 (
/sarif) uploads to GitHub code scanning withgithub/codeql-action/upload-sarif. - JUnit XML (
/junit) shows as a native test report in Jenkins and GitLab CI, with one test case per finding.
SARIF and JUnit come with a Pentest or a plan. When a check does not include them, the endpoint answers 402 with a message and a link to unlock the report.
Status codes and errors#
| Code | Meaning |
|---|---|
202 | Accepted but not started: the check is queued. The body has scan_id, status: "queued" and start_state.reason; fair_use_review means this month’s CI checks for the target are used up and the request is reviewed within one working day. Poll the status endpoint. |
402 | No plan pays for the check. detail.code is CI_REQUIRES_PLAN (CI checks need a Continuous plan for the target), PLAN_PAUSED (the plan is paused until its invoice is paid) or PLAN_ENDED. detail.options lists plans that would. |
400 | The request cannot run as given, for example a scope_regex that does not bound the scan. |
401 | The API key is missing, invalid, expired or revoked. |
403 | The key lacks scan:create, the target is outside your verified domains, or the account needs action first (MFA_SETUP_REQUIRED, API_ACCESS_DISABLED, LEGAL_ACCEPTANCE_REQUIRED). On the status and export endpoints: the scan belongs to another organization. |
404 | Scan ID not found. |
409 | DOMAIN_RECHECK_FAILED: the domain’s verification record is gone. Put it back, then verify the domain again on the Targets page. |
422 | Invalid body: missing target_url, invalid scan_type or a malformed fail_on. |
429 | Too many requests. Retry after the Retry-After header’s seconds. |
503 | The ownership check could not run (DOMAIN_RECHECK_UNAVAILABLE) or a service is briefly unavailable. Retry after the Retry-After header’s seconds. |