Skip to main content
The Ility REST API gives programs the same view of a workspace that you get in the app. Use it to pull issues and scan results into your own reports, or to start a scan from a deploy pipeline and check the results.

Base URL

Requests and responses are JSON. Field names use snake_case.

Authentication

Send an API key as a bearer token:
A key belongs to one workspace, and every request acts in that workspace.

What a key can do

A key can read everything in its workspace, and it can make the same changes a member can, such as updating an issue’s status. It acts on behalf of the owner who created it, and never with more access than that person has. Some actions need more than a key:

Domains, surfaces, and slugs

In the app you work with surfaces. In the API, most routes address the website behind a surface as a domain, by its slug, such as example-com. Get slugs from GET /v1/domains. Issues are filtered by the domain’s id.

Errors

Errors return a non-2xx status and a body with a human-readable detail. Many also carry a machine-readable reason:

Pagination

List routes return an items array.
  • Most lists use cursors. Pass the response’s next_cursor as cursor to get the next page. next_cursor is null on the last page.
  • GET /v1/issues uses page numbers: pass page and limit (up to 100). The response’s total counts every matching issue.

Rate limits

Reading data isn’t rate limited. Requests that start work, such as scans, crawls, and imports, are limited per workspace per minute. When you go over, the API returns 429 with a Retry-After header.

Next steps

Create an API key

Mint a key for a script or CI job.

Start a scan from CI

Trigger a scan after a deploy and wait for the result.