# API

With the Ladon API you search the catalog, manage watches, projects and channels, read the delivery log and poll for events. Everything is JSON over HTTPS. Every endpoint, field and answer is in the [reference](https://ladon.hackindex.io/docs/api/reference).

The API is part of the paid plans. Tokens of a team on the free plan get `402` with the type `plan-feature`, and work again after an upgrade.

## Address

```text
https://ladon.hackindex.io/api/v1
```

All paths on this page are relative to that address, so `GET /me` means `GET https://ladon.hackindex.io/api/v1/me`.

## Tokens

Create a token on the **API** tab of a team in Ladon.

- A token belongs to you and to one team. It can never do more than your role in that team allows.
- It is shown once, when you create it. Ladon only stores a hash of it. Tokens start with `hi_ladon_`, so secret scanners can recognise a leaked one.
- Before you create a token, you confirm it's you in your HackIndex account with a passkey, your password, an authenticator code or an emailed code. You come straight back and have 15 minutes. You also get an email for every new token.
- Choose when it expires: in 30 days, 90 days, a year, or never.
- The **API** tab shows the requests of the last 30 days: per day, the share of errors and the busiest endpoints, and per token how often it was used. Ladon counts per hour and endpoint, not every request, and keeps the counts for 90 days.
- It stops working when you revoke it, when it expires, when you leave the team or only handle its billing, and when the team requires two-factor authentication and your account has none.

Send it in the `Authorization` header:

```bash
curl https://ladon.hackindex.io/api/v1/me \
  -H "Authorization: Bearer $LADON_TOKEN"
```

## Scopes

A token only does what its scopes allow. Pick the fewest you need.

| Scope                  | Allows                           | Needs                  |
| ---------------------- | -------------------------------- | ---------------------- |
| `software:read`        | Search the catalog               |                        |
| `vulnerabilities:read` | Read vulnerabilities             |                        |
| `watches:read`         | Read watches                     |                        |
| `watches:write`        | Add, change and remove watches   |                        |
| `projects:read`        | Read projects and their reports  |                        |
| `projects:write`       | Add projects and send lockfiles  |                        |
| `rules:read`           | Read CVE rules and their matches |                        |
| `rules:write`          | Add, change and remove CVE rules |                        |
| `cves:read`            | Read and search CVEs             |                        |
| `endpoints:read`       | Read channels                    | Owner or admin         |
| `endpoints:write`      | Add, change and remove channels  | Owner or admin         |
| `deliveries:read`      | Read the delivery log            | Owner or admin         |
| `deliveries:write`     | Send messages again              | Owner or admin         |
| `events:read`          | Poll the events of the team      | Business or Enterprise |

In the API, channels are called `endpoints`.

## What you can do

| Area            | Endpoints                                                                                                                                                                                                                |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Meta            | `GET /me`: the token, team, plan and limits                                                                                                                                                                              |
| Software        | `GET /software?search=&type=`, `GET /software/{type}/{slug}`, `GET /software/{type}/{slug}/vulnerabilities`                                                                                                              |
| Vulnerabilities | `GET /vulnerabilities/{id}`                                                                                                                                                                                              |
| Watches         | `GET /watches`, `POST /watches`, `PUT /watches`, `GET /watches/{id}`, `PATCH /watches/{id}`, `DELETE /watches/{id}`                                                                                                      |
| Projects        | `GET /projects`, `POST /projects`, `GET /projects/{id}`, `PATCH /projects/{id}`, `POST /projects/{id}/lockfile`, `POST /projects/{id}/software`, `DELETE /projects/{id}/software/{type}/{slug}`, `DELETE /projects/{id}` |
| CVE rules       | `GET /rules`, `POST /rules`, `POST /rules/preview`, `GET /rules/{id}`, `PATCH /rules/{id}`, `DELETE /rules/{id}`, `GET /rules/{id}/matches`, see [CVE rules](https://ladon.hackindex.io/docs/cve-rules.md)                                           |
| CVEs            | `GET /cves?search=&severity=&kev=&published_after=`, `GET /cves/{id}`                                                                                                                                                    |
| Channels        | `GET /endpoints`, `POST /endpoints`, `GET /endpoints/{id}`, `PATCH /endpoints/{id}`, `DELETE /endpoints/{id}`, `POST /endpoints/{id}/test`, `POST /endpoints/{id}/rotate-secret`                                         |
| Delivery log    | `GET /endpoints/{id}/messages`, `GET /messages/{id}/attempts`, `POST /messages/{id}/retry`, `POST /endpoints/{id}/recover`                                                                                               |
| Events          | `GET /events?after=`                                                                                                                                                                                                     |

## Projects {#projects}

Watches, CVE rules and channels live in a [project](https://ladon.hackindex.io/docs/projects.md). In answers they have a `project` field with the public id of their project, such as `prj_01JB8Z7R4M2N6P8Q0S2U4W6Y8A`.

- `POST /watches`, `PUT /watches`, `POST /rules` and `POST /endpoints` take an optional `project`. Leave it out and Ladon uses the [default project](https://ladon.hackindex.io/docs/projects.md#default) of the team, so existing scripts keep working.
- `GET /watches`, `GET /rules`, `GET /endpoints` and `GET /events` take an optional `?project=` to list one project. Leave it out and you get every project of the team.
- A channel only gets the alerts of its own project. `project_filter` on channels no longer exists and is ignored when you send it. To get the alerts of several projects at one address, add a channel with that address in each project.

## Watch a plugin

```bash
curl -X POST https://ladon.hackindex.io/api/v1/watches \
  -H "Authorization: Bearer $LADON_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6f1c2a9e-0d4b-4c8e-9a51-3b7e2f0c8d14" \
  -d '{"software": {"type": "plugin", "slug": "contact-form-7"}, "version_constraint": ">=5.8"}'
```

Name the software by `type` (`plugin`, `theme`, `core`, `npm`, `composer`, `pypi`, `gem`, `cargo`, `golang`, `maven` or `github`) and `slug`. For packages the slug is the package name, such as `@angular/core`, `laravel/framework`, `django`, the Go module path `github.com/gin-gonic/gin` or the Java `groupId:artifactId` `org.apache.logging.log4j:log4j-core`, and `version_constraint` uses the range syntax of that language, see [Watching software](https://ladon.hackindex.io/docs/watches.md#ecosystems). A premium plugin or theme that is not in the catalog yet is added by its slug, the folder name in `wp-content`. It stays private to the teams that watch it until WordPress.org or a vulnerability feed knows it. Core has to be in the catalog. Leave out `events` to get the default alerts, and `project` to add the watch to the default project. Add `tags`, for example `["client-acme"]`, to route its alerts to channels with a matching `tag_filter` (see [Channels](https://ladon.hackindex.io/docs/channels.md#tags)). The answer is `201` with the watch. Watching something twice in the same project answers `409`, a full plan answers `402`. The same software in another project is a watch of its own, and counts once for your plan.

## Replace all watches at once

`PUT /watches` takes the complete list of what one project should watch. Name the project in `project` next to `watches`, or leave it out for the default project. Software in the list is added or updated, software that is not in it stops being watched in that project. Other projects stay as they are. Premium plugins and themes work the same as with `POST /watches`. Sending the same list again changes nothing, so it fits a CI job. To watch every package in a lockfile, send it as a project instead, see below.

```json
{
    "project": "prj_01JB8Z7R4M2N6P8Q0S2U4W6Y8A",
    "watches": [
        {
            "software": { "type": "plugin", "slug": "contact-form-7" },
            "version_constraint": ">=5.8"
        },
        { "software": { "type": "theme", "slug": "twentytwentyfour" } }
    ]
}
```

Each entry takes `software`, `version_constraint`, `events`, `include_informational` and `tags`. Paused watches stay paused and severity filters stay as they are. An entry without `tags` keeps the tags the watch already has, an empty list removes them. The answer lists every watch, and `meta` says how many were `created`, `updated` and `removed`. A list can hold up to 2000 entries.

## Send a lockfile

A [project](https://ladon.hackindex.io/docs/projects.md) is a repository known by its lockfiles. Create one with `POST /projects`, with `name` and the lockfile as an upload in `lockfile`. After that, send each new lockfile to `POST /projects/{id}/lockfile`. It replaces the lockfile of the project with the same name, the other lockfiles of the project stay. A project with more lockfiles gets one call per lockfile:

```bash
curl -X POST https://ladon.hackindex.io/api/v1/projects/prj_01JB8Z7R4M2N6P8Q0S2U4W6Y8A/lockfile \
  -H "Authorization: Bearer $LADON_TOKEN" \
  -F "lockfile=@composer.lock"
```

Instead of uploads you can send the text in `content`, with the file name in `filename`, and the manifest text in `manifest_content`. Add the manifest, such as `package.json` or `Gemfile`, in `manifest` to tell direct and dev dependencies apart where the lockfile does not. `include_dev` and `tags` work on create and with `PATCH /projects/{id}`. A project does not choose which alerts it sends, its channels do. So projects have no `events`, `severity` or `include_informational` in their answers, and those fields are ignored when you send them to a project or to `POST /projects/{id}/software`. The answer holds the project with its `summary` and `findings`, like `npm audit`, so CI can fail the build on it. Watches that projects make stay out of the watches endpoints.

## Route alerts by tag

A channel with a `tag_filter` only gets the alerts of watches that have at least one of those tags. An empty list, or leaving it out, means every watch of the project of the channel.

```bash
curl -X PATCH https://ladon.hackindex.io/api/v1/endpoints/we_01JB8Z6Q3K9W7XWJ5V2N4M8T1R \
  -H "Authorization: Bearer $LADON_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"tag_filter": ["client-acme"]}'
```

Tags are lowercase letters, digits, dots, dashes and underscores, up to 32 characters each and 10 per watch or channel.

## Send failed alerts again

After an outage on your side, `POST /endpoints/{id}/recover` with `since` (ISO 8601, at most 30 days ago) sends every message of the channel that failed or was given up since then once more, within about 10 seconds. Tests are left out. The answer is `202` with the number in `data.requeued`. The channel has to be on, otherwise you get `409`. `POST /messages/{id}/retry` does the same for one message. In Ladon this is **Send again** on the channel page.

## Poll for events

Instead of receiving webhooks, you can ask for new alerts. `GET /events` returns the events that matched the watches of the team, or of one project with `?project=`, oldest first, in the same shape as a webhook. Pass the `id` of the last event you processed as `after`, and `limit` up to 100.

```bash
curl "https://ladon.hackindex.io/api/v1/events?after=evt_01JB8Z5X2C7Q4R9T6Y3W1M0N8P" \
  -H "Authorization: Bearer $LADON_TOKEN"
```

`meta.next_cursor` is the id to send next time, `meta.has_more` tells whether to ask again right away. The events API is part of Business and Enterprise.

## Lists and pages

Lists return `data`, `links` and `meta` with `current_page`, `last_page`, `per_page` and `total`. Ask for up to 100 items with `per_page` and the next page with `page`. Events use a cursor instead, see above.

## Changes

`PATCH` only changes the fields you send. Send `"paused": true` or `false` to pause or resume a watch or channel.

Every `POST` accepts an `Idempotency-Key` header of up to 255 characters, for example a UUID. When the same request with the same key comes again within 24 hours, you get the first answer again, with the header `Idempotent-Replayed: true`, and nothing happens twice. Using the key for a different request is an error.

## Rate limits

Each token can make 300 requests a minute on Pro and Business and 1000 on Enterprise. A whole team can make three times that. Answers to a valid token have `X-RateLimit-Limit` and `X-RateLimit-Remaining`. Above the limit you get `429` with `Retry-After` in seconds.

Package advisories change every 15 minutes and WordPress data about every half hour, so polling more often than every few minutes rarely finds anything new.

## Errors

Errors use `application/problem+json` ([RFC 9457](https://www.rfc-editor.org/rfc/rfc9457)). `type` links to the explanation below, `detail` says what went wrong in this case.

```json
{
    "type": "https://ladon.hackindex.io/docs/api#error-plan-limit",
    "title": "Plan limit reached",
    "status": 402,
    "detail": "Your plan allows 25 active watches. Pause or remove one, or upgrade the plan, to add more.",
    "instance": "/api/v1/watches",
    "limit": "watches",
    "upgrade_url": "https://account.hackindex.io/settings/teams/acme"
}
```

- **400 Invalid JSON** (`#error-invalid-json`): The body is not valid JSON.
- **400 Invalid Idempotency-Key** (`#error-invalid-idempotency-key`): The key is longer than 255 characters.
- **401 Unauthenticated** (`#error-unauthenticated`): No token, a token that does not exist, or one that was revoked or expired. Also when the owner of the token is no longer in the team.
- **402 Plan limit reached** (`#error-plan-limit`): The team uses every watch, project or channel its plan allows. `limit` says which, `upgrade_url` where to upgrade.
- **402 Not in your plan** (`#error-plan-feature`): The plan does not include this, for example the API on the free plan or the events API before Business. `feature` says which.
- **403 Missing scope** (`#error-missing-scope`): The token does not have the scope this request needs. Create a token with that scope.
- **403 Missing role** (`#error-missing-role`): Channels and the delivery log are for owners and admins of the team.
- **403 Two-factor authentication required** (`#error-two-factor-required`): The team requires two-factor authentication. Turn it on in your HackIndex account.
- **403 Forbidden** (`#error-forbidden`): The request is not allowed.
- **404 Not found** (`#error-not-found`): It does not exist, or it belongs to another team.
- **405 Method not allowed** (`#error-method-not-allowed`): The path exists, but not with this method.
- **409 Conflict** (`#error-conflict`): The request clashes with the current state, for example a watch that already exists or sending a message again that was delivered.
- **422 Validation failed** (`#error-validation`): One or more fields are not valid. `errors` lists the messages per field.
- **422 Idempotency-Key reused** (`#error-idempotency-key-reused`): The key was used for a different request in the last 24 hours. Use a new key for every new request.
- **429 Too many requests** (`#error-rate-limited`): Wait the number of seconds in `Retry-After` and try again.
- **500 Server error** (`#error-server-error`): Something went wrong on our side. Try again later. A `POST` with an `Idempotency-Key` is safe to repeat.

## Versions

The version is in the path: `v1`. New fields and endpoints can be added at any time, so ignore fields you do not know. Changes that could break an integration come with a new version, announced in the changelog. Webhook payloads have their own `api_version`, see [Events and payloads](https://ladon.hackindex.io/docs/events.md).

## Data and licenses

Vulnerabilities carry `source`, with a link to the record and the copyright notices of the data. Keep them with every copy you make, for example in a ticket or a report. All licenses are on the [licenses page](https://ladon.hackindex.io/licenties).
