> ## Documentation Index > Fetch the complete documentation index at: https://docs.scanoss.com/llms.txt > Use this file to discover all available pages before exploring further. # Using the API > Call the Earnie API from a script or pipeline: your deployment's base URL, authenticating with an API key, choosing scopes, a first request, and how paging and errors work. 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: ```text theme={null} 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: ```text theme={null} 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](/en/latest/earnie/administration/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](/en/latest/earnie/administration/api-keys#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](/en/latest/earnie/administration/api-keys#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`. ```bash theme={null} curl https://your-company.earnie.dev/v1/projects \ -H "Authorization: Bearer $EARNIE_API_KEY" ``` The response is a JSON array of projects: ```json theme={null} [ { "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: ```bash theme={null} 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: ```json theme={null} { "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](/en/latest/earnie/administration/api-keys): create and scope a key * [Earnie CLI](/en/latest/earnie/using-earnie/earnie-cli): scan and check verdicts from a pipeline without calling the API yourself This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.