Base URL
Each organization has its own Earnie deployment at its own address. It’s the address you use to sign in, for example:/v1/ on that address. In the API reference, set the tenant field to your organization’s part of the address to send requests to your own deployment.
Authenticating
Send an API key in theAuthorization header of every request:
Choosing Scopes
A key’s scopes decide which operations it can call. For example, listing projects needsprojects:read, and submitting a scan needs scans:write. Give each key only the scopes its job needs.
Three presets cover the common jobs:
- CI pipeline: submit scans and read verdicts
- Coding agent (MCP): read posture, findings, and policies, and submit scans
- Read-only reporter: read posture without changing anything
Your First Request
List the projects in your organization. The key needsprojects:read.
id in the paths of other operations, for example GET /v1/projects/{projectId}. To find a project’s id from its slug or repository, use GET /v1/projects:resolve.
Paging Through Lists
Earnie pages lists that can grow large. There are two styles, and each operation’s reference shows which one it uses. Offset paging. Sendlimit and offset. The response carries the page in items and the full count in total. For example, the findings list returns 20 findings by default and up to 1000 per page:
limit, and leave out cursor for the first page. Each response carries a next_cursor. Pass it as cursor to get the next page. On the last page, next_cursor is null or absent. The audit log, policy violations, and policy evaluations use cursors.
Some short lists, such as the projects list, return everything in one response.
Errors
Every error response has the same JSON body:code in your scripts. It is a fixed, machine-readable value. message is for people to read and can change. A few validation errors add fields that explain what to fix, and each operation’s reference documents them.
Failed Authentication Attempts
Earnie limits how quickly one client address can retry after failed authentication. After a burst of rejected keys it answers429 with the code rate_limited and a Retry-After header. Earnie doesn’t count requests made with a valid key. If you see 429, check the key before you retry.
Importing Repositories by Script
A script can import repositories from GitHub or GitLab as projects, for example to onboard every repository of a new team. It needs:- a connection to GitHub or GitLab that a person already made. A key can never connect a provider. See Connecting a repository.
- a key for All projects that holds
projects:import. Addintegrations:readto look up connections, andprojects:readto read the projects it creates.
Finding the Connection
List the connections and note theid of the one to import from:
Importing One Repository
repo_full_name is owner/name on GitHub, and the full namespace path on GitLab. connection_id is optional when only one connection can see the repository. Earnie creates the project, connects the repository, and starts its first scan, then answers 201 with the project. If the repository already has a project, it answers 200 with that project, so running the script again is safe.
Importing Many Repositories
Preview first. It reports how many repositories would be imported and why the rest are left out, and creates nothing:name_pattern is optional. * matches any run of characters, so acme/* takes everything under acme. Forks are left out unless you send "include_forks": true, and archived repositories are always left out.
The import runs in the background. Earnie answers 202 with the batch, whose id you poll for progress:
counts says how many repositories are in each state, failures gives the reason for each one that failed, and finished turns true when every repository is done. POST /v1/projects/import-batches/{batchId}:retry-failed imports the failed ones again, and POST /v1/projects/import-batches/{batchId}:cancel skips those not started yet. Importing All Repositories at Once describes the same import in the console.
When Earnie Refuses an Import
What’s Next
- API keys: create and scope a key
- Earnie CLI: scan and check verdicts from a pipeline without calling the API yourself