Skip to main content

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#

MethodPathPurpose
POST/api/ci/scanStart a CI check
GET/api/ci/scan/{scan_id}/statusPoll progress and the pass/fail verdict
GET/api/ci/scan/{scan_id}/sarifDownload findings as SARIF 2.1.0
GET/api/ci/scan/{scan_id}/junitDownload findings as JUnit XML
GET/api/ci/scan/{scan_id}/exportExport the scan’s data as JSON or CSV
GET/api/ci/scan/{scan_id}/evidence-bundleDownload the evidence bundle, a zip of every confirmed finding’s proof, where the plan includes it
GET/api/ci/scansList recent CI checks
GET/api/ci/verifyCheck that the key and connection work
GET/api/ci/templatesList 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.

FieldTypeDefaultDescription
target_urlstringrequiredURL 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_urlstringnoneWhere to fetch the OpenAPI or Swagger spec; required when scan_type is "api"
api_base_urlstringfrom the specWhere the API is hosted, when the spec is served from somewhere else
scan_modestring"UNAUTHENTICATED""AUTH_LLM_LOGIN" to sign in before testing
login_urlstringnoneSign-in page; required with AUTH_LLM_LOGIN
usernamestringnoneTest account username for signed-in checks
passwordstringnoneTest account password for signed-in checks
fail_onobject{"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
waitbooleantruetrue holds the request until the check ends; false returns at once (recommended)
timeoutinteger3600Seconds to wait when wait is true, from 60 to 14400
callback_urlstringnoneURL that receives a POST with the results when the check ends
callback_signing_secretstringnoneWhen set, callbacks carry an X-Signature-256 header with the HMAC-SHA256 of the body, so the receiver can verify them
tagsstring arraynoneLabels such as "pr-123" or "branch:main"
auth_configobjectnoneAPI check credentials: bearer (token), api_key (header, value), basic (username, password) or oauth2 (client_id, client_secret, token_url)
custom_headersobjectnoneHeaders added to every request of an API check
spec_auth_headersobjectnoneHeaders used to fetch spec_url, when the spec is in a private repository or behind authentication
scope_regexstringnoneOnly 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 with github/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#

CodeMeaning
202Accepted 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.
402No 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.
400The request cannot run as given, for example a scope_regex that does not bound the scan.
401The API key is missing, invalid, expired or revoked.
403The 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.
404Scan ID not found.
409DOMAIN_RECHECK_FAILED: the domain’s verification record is gone. Put it back, then verify the domain again on the Targets page.
422Invalid body: missing target_url, invalid scan_type or a malformed fail_on.
429Too many requests. Retry after the Retry-After header’s seconds.
503The ownership check could not run (DOMAIN_RECHECK_UNAVAILABLE) or a service is briefly unavailable. Retry after the Retry-After header’s seconds.

Last updated: November 20, 2026

Was this page helpful?

Site search

↑↓ navigateEnter openEsc close