Security

Start a security scan

POST /api/projects/{projectId}/security/scan-profiles/{profileId}/run

Queues a scan for the given profile and returns immediately with the tracking id, because a scan runs in the background. Poll the scan run endpoint until its status leaves queued and running.

Parameters

Responses

202 — The scan was queued.

400 — The request was malformed or failed validation.

401 — The API key is missing, invalid, expired or revoked. A US organization calling

without X-RB-Region: us also lands here, because the request reached the wrong region.

403 — The key is valid but lacks the permission or the project scope for this call.

A scoped key is also refused on organization level operations by design.

404 — The resource does not exist, or it belongs to another organization or project.

Both cases answer the same way on purpose, so the API cannot be used to probe for foreign identifiers.

409 — A request with this Idempotency-Key is still running, or its response was too large to keep. The code is IDEMPOTENCY_KEY_IN_PROGRESS or IDEMPOTENCY_RESPONSE_NOT_STORED, and in the second case the request is not run again.

422 — This Idempotency-Key was already used with a different request body, so use a new key. The code is IDEMPOTENCY_KEY_REUSED.

429 — The rate limit was exceeded. The Retry-After header gives the seconds to wait.

Get a scan run

GET /api/projects/{projectId}/security/scan-runs/{runId}

Returns the state of a scan, including how many scanners have finished and which one is running. Once status is completed, securityScore and openFindingsCount are final and a pipeline can gate on them.

Parameters

Responses

200 — The scan run.

401 — The API key is missing, invalid, expired or revoked. A US organization calling

without X-RB-Region: us also lands here, because the request reached the wrong region.

403 — The key is valid but lacks the permission or the project scope for this call.

A scoped key is also refused on organization level operations by design.

404 — The resource does not exist, or it belongs to another organization or project.

Both cases answer the same way on purpose, so the API cannot be used to probe for foreign identifiers.

429 — The rate limit was exceeded. The Retry-After header gives the seconds to wait.

List security findings

GET /api/projects/{projectId}/security/findings

Returns the findings of a project across all scans, filtered as you need them. A pipeline that only wants to know whether anything new broke should filter on status=open and on the severities it cares about.

Parameters

Responses

200 — A page of findings.

401 — The API key is missing, invalid, expired or revoked. A US organization calling

without X-RB-Region: us also lands here, because the request reached the wrong region.

403 — The key is valid but lacks the permission or the project scope for this call.

A scoped key is also refused on organization level operations by design.

404 — The resource does not exist, or it belongs to another organization or project.

Both cases answer the same way on purpose, so the API cannot be used to probe for foreign identifiers.

429 — The rate limit was exceeded. The Retry-After header gives the seconds to wait.

Export findings as SARIF

GET /api/projects/{projectId}/security/findings/export/sarif

Returns the findings of a project as a SARIF 2.1.0 document, which GitHub code scanning and comparable tools ingest directly. Upload it from your pipeline and the findings show up next to the code they concern. Without a status filter it returns the open ones, which is what a build gate wants.

Parameters

Responses

200 — The SARIF document.

401 — The API key is missing, invalid, expired or revoked. A US organization calling

without X-RB-Region: us also lands here, because the request reached the wrong region.

403 — The key is valid but lacks the permission or the project scope for this call.

A scoped key is also refused on organization level operations by design.

404 — The resource does not exist, or it belongs to another organization or project.

Both cases answer the same way on purpose, so the API cannot be used to probe for foreign identifiers.

429 — The rate limit was exceeded. The Retry-After header gives the seconds to wait.