Skip to main content
The code security API serves what the project’s Code security tab and the code security settings pages show. Use it to pull records into your own tracker, record your team’s decisions from another tool, start a scan from a script, or turn code security on for many repositories at once. For what code security does, see Code security of your repositories.

Base URL

Every path on this page starts with /v1. Requests and responses are JSON. Times are ISO 8601 strings in UTC.

Authentication

Send one credential with each request: Code security takes an owner or an admin. The account API key always passes. An OAuth token passes when its user is an owner or an admin of the account, checked on every request, so a token whose user became a member is refused from then on. A member’s or a billing admin’s token is refused with 403 FORBIDDEN on every route here, reads included. Use the API key for scripts and CI, and keep it in a secret store. If a request carries both a token and the API key, the token is used, and a token that isn’t valid is refused even when the key is.
The examples on this page use these two variables. The record examples also use RECORD_ID, set under Get a record.

IDs

  • Project ID: a project’s ID is in its address in the console, https://console.ironbee.ai/projects/<project-id>/.... Only a project of a connected GitHub, GitLab or Bitbucket repository has code security.
  • Record ID: each record’s id, 64 hexadecimal characters, from List records.
  • Scan ID: each scan’s id, or jobId in a run.
A project ID that doesn’t belong to your account, isn’t a connected repository, or belongs to an archived project answers 404 NOT_FOUND, and so does an ID that isn’t well formed.

Responses and errors

A response can carry fields this page doesn’t list, and a field with a closed list of values can gain new values. Ignore the fields you don’t know, and treat an unknown value as a later addition. An error answers with a status and a JSON body:
The examples below show credit amounts as "…". The rates are on the rate card on Credit usage.

Where a repository stands

What the top of the project’s Code security tab shows: whether code security is on, where the scans stand, the open records and what the next scans cost.
lastRun is shortened here. It’s a whole run. status matches the band at the top of the tab:

The scan object

job here, and the answer of Start a scan, describe one scan:

List records

A page of the repository’s records. With no filter, the list holds what the console’s Records tab opens on: the confirmed findings and the leads to validate whose decision is Open. To list every record, pass every value of verdict and disposition:
The records come confirmed first, from critical to informational, then the leads to validate, then the rejected ones, newest first within each. While nextCursor isn’t null, pass it as cursor for the next page.

Get a record

One record, with everything the console’s record panel shows.
The answer has the fields of List records, and these: record is the record’s content as the scan wrote it: what the problem is, its root cause, the trace from the entry point, the reproduction, the fix, the evidence and the conditions, and for a lead how to validate it, or for a rejected record why it doesn’t hold. It’s the object the console shows under Show it as data. Its keys aren’t a fixed schema and can change between scans, so read the ones you need and ignore the rest. Secrets found in it are replaced before it’s saved. The paths inside it aren’t checked: check one yourself before you build a link from it, the way location.file already is.

Set a decision

Sets your team’s decision on a record, as Save decision does in the console.
The answer is the record after the change, as in Get a record. A decision holds while the record keeps the verdict and severity it was set on: a scan that changes either sets it back to none. The verdict and severity you send guard against that. If a scan changed the record since you read it, the request is refused with 409 SECURITY_RECORD_CHANGED and nothing is written. Read the record again and decide again. A verdict and severity that no record can hold together, such as confirmed with no severity, are refused with 400.

List runs

A page of the repository’s scans that ended, newest first, as on the console’s Runs tab.

The run object

The console’s Scan column reads the kind from these fields: Follow-up when credits.reason is free_action, No scan when scan is null, and otherwise Full or Incremental from scan. The Units in the console’s run details add up counts.units this way: Read is covered and candidate, Put off to a follow-up run is deferred, Outside this scan is out_of_scope and not_applicable, and Blocked is blocked, planned and in_progress. Among the errorType values a failed scan can have: Other values can appear. A failed scan is never charged.

Start a scan

Asks for a scan of the repository’s default branch now. The body is optional:
It answers 202 Accepted with the waiting scan:
  • The scan waits its turn: your account runs one code security scan at a time. See One scan at a time.
  • If a scan of the repository is already waiting, it’s brought forward and answered instead of a second one. full makes it a full scan.
  • If a scan of the repository is running, the new one waits for it to end. The console’s Run full scan isn’t offered then, but the API takes the request.
  • A repository can be started by hand once an hour, the console and the API counted together. Sooner, the request is refused with 429 REFRESH_TOO_SOON, and the Retry-After header gives the seconds until the next one can start.
  • With no credits left this month, the request is refused with 402 CREDITS_EXHAUSTED, and nothing is queued. error.details holds left, the credits left, purchased ones included; allowance, the monthly allowance; resetsAt, when the credits reset; and topUp, how the team can get more: add_seats, upgrade, pay_invoice, contact, or null.
  • The scan’s price is counted when it starts. If it’s more than the credits left, the scan is refused then, free: it ends failed with credits_exhausted, and the repository’s status reads waiting_for_credits.
To follow the scan, call Where a repository stands every minute or so. While job.id is the scan’s ID, job.status says where it is. While an earlier scan of the repository runs, job.id names that one, and the scan waits behind it. The scan has ended once job.status is succeeded or failed while job.id is its ID, once job.id names a scan queued after it, or once its ID appears as jobId in List runs. Find it there, and its records in List records. A scan takes up to two hours. Follow-up runs can come after it, each a scan of its own. The scan shows API under the Scan column on the console’s Runs tab.

Settings

The settings routes read and change what Code security settings shows. They’re served whether code security is on or off, so you can turn it on through them. Each setting is answered with its value and its source: repository (set for this repository), account (the account’s default) or default (IronBee’s default). IronBee’s defaults are weekly, auto and false. A change applies at each repository’s next scan. A scan already running keeps the settings it started with.

Get the account’s settings

repositoriesDiffering counts the repositories that set their own value.

Change the account’s settings

Send the settings to change under settings, at least one. null puts one back to IronBee’s default.
The answer is the account’s settings after the change. There’s no account setting that turns code security on: each repository has its own switch.

Get a repository’s settings

Change a repository’s settings

Send the fields to change, at least one:
The answer is the repository’s settings after the change. A change that’s refused changes nothing.
  • Turning code security on queues no scan by itself. A repository that has never been scanned is due at once, so its first scheduled scan comes within minutes, in its turn. See The schedule.
  • Turning it off keeps the records, and the runs within your plan’s retention. While it’s off, the records, runs, decision and start routes for the repository answer 409 CODE_SECURITY_DISABLED, and Where a repository stands answers with status off.
  • Changing ignorePaths makes the repository’s next scan a full scan, at a full scan’s price.

What’s next?

Code security overview

What code security is, where it runs, and what it costs.

How a scan works

What a scan reads, when it runs, and what running your code means.

Account API key

The shared key scripts and CI use.

OAuth tokens

Personal tokens that act with your role.