Using the API

The Earnie API lets a script, pipeline, or internal tool do what a person does in Earnie: submit scans, read findings and posture, triage, manage policies, and export SBOMs. You can call every operation in this API reference with an Earnie API key.

Base URL

Each organization has its own Earnie deployment at its own address. It’s the address you use to sign in, for example:

https://your-company.earnie.dev

Every API path starts with /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 the Authorization header of every request:

Authorization: Bearer sk_earnie_...

An admin or operator creates keys under Settings → API keys. Earnie shows the key only once, so store it in your pipeline’s secret store as soon as you generate it. See API keys for how to create one. Every key expires, after 365 days at most. When a key stops working, the error code says why:

Status	Error code	Meaning
`401`	`unauthenticated`	The request carried no key
`401`	`invalid_key`	The key isn’t a valid Earnie key
`401`	`key_expired`	The key has expired. Generate a new one
`401`	`key_revoked`	The key was revoked. Ask an admin why before replacing it

Choosing scopes

A key’s scopes decide which operations it can call. For example, listing projects needs projects: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

The scope reference lists every scope and what it allows. A key can also be limited to specific projects. See How a project-scoped key is refused for the errors that limit produces. A key can never perform some actions, such as approving a policy request, managing members, or connecting an integration. Those operations aren’t in this reference.

Your first request

List the projects in your organization. The key needs projects:read.

curl https://your-company.earnie.dev/v1/projects \
  -H "Authorization: Bearer $EARNIE_API_KEY"

The response is a JSON array of projects:

[
  {
    "id": "0198f0c2-6a2e-7b1c-9d3e-2f4a5b6c7d8e",
    "org_id": "0198f0c2-1b2c-7d3e-8f4a-5b6c7d8e9f0a",
    "slug": "billing-service",
    "name": "Billing Service",
    "is_default": false,
    "created_at": "2026-09-14T10:22:31Z",
    "updated_at": "2026-09-30T08:05:12Z"
  }
]

Use a project’s 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. Send limit 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:

curl "https://your-company.earnie.dev/v1/findings?project_id=$PROJECT_ID&limit=100&offset=200" \
  -H "Authorization: Bearer $EARNIE_API_KEY"

Cursor paging. Send 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": "project_out_of_scope",
  "message": "project 0198f0c2-6a2e-7b1c-9d3e-2f4a5b6c7d8e is outside the API key scope"
}

Use 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.

Status	What it means
`400`	The request is malformed, for example a parameter has the wrong type
`401`	The key is missing, invalid, expired, or revoked
`403`	The key is valid but not allowed to do this: a missing scope, a project outside the key’s projects, or a scanner your organization hasn’t enabled
`404`	The item doesn’t exist, or it belongs to a project the key can’t reach
`409`	The request conflicts with the item’s current state, for example editing a policy revision that has since changed
`422`	The request is well-formed but its content isn’t valid
`429`	Too many failed authentication attempts. Wait for the number of seconds in the `Retry-After` header, then retry

Failed authentication attempts

Earnie limits how quickly one client address can retry after failed authentication. After a burst of rejected keys it answers 429 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.

What’s next

API keys: create and scope a key
Earnie CLI: scan and check verdicts from a pipeline without calling the API yourself

Get started

Development

Pull requests & CI

Governance

Evidence & audit

Administration

Migrating

API reference

Base URL

Authenticating

Choosing scopes

Your first request

Paging through lists

Errors

Failed authentication attempts

What’s next

​Base URL

​Authenticating

​Choosing scopes

​Your first request

​Paging through lists

​Errors

​Failed authentication attempts

​What’s next

Base URL

Authenticating

Choosing scopes

Your first request

Paging through lists

Errors

Failed authentication attempts

What’s next