# API

Met de Ladon-API zoek je in de catalogus, beheer je watches, projecten en kanalen, lees je het bezorglog en haal je events op. Alles is JSON over HTTPS. Elk endpoint, veld en antwoord staat in de [referentie](https://ladon.hackindex.io/docs/api/reference).

De API hoort bij de betaalde abonnementen. Tokens van een team met het gratis abonnement krijgen `402` met het type `plan-feature`, en werken weer na een upgrade.

## Adres

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

Alle paden op deze pagina zijn relatief aan dat adres, dus `GET /me` betekent `GET https://ladon.hackindex.io/api/v1/me`.

## Tokens

Maak een token aan op het tabblad **API** van een team in Ladon.

- Een token hoort bij jou en bij één team. Het kan nooit meer dan je rol in dat team toestaat.
- Het wordt één keer getoond, bij het aanmaken. Ladon bewaart alleen een hash. Tokens beginnen met `hi_ladon_`, zodat secret-scanners een gelekt token herkennen.
- Voor je een token maakt, bevestig je in je HackIndex-account dat jij het bent: met een passkey, je wachtwoord, een code uit je authenticator-app of een gemailde code. Je komt direct terug en hebt dan 15 minuten. Je krijgt ook een mail bij elk nieuw token.
- Kies wanneer het verloopt: over 30 dagen, 90 dagen, een jaar of nooit.
- Het tabblad **API** toont de verzoeken van de laatste 30 dagen: per dag, het aandeel fouten en de drukste endpoints, en per token hoe vaak het gebruikt is. Ladon telt per uur en endpoint, niet elk verzoek, en bewaart de tellingen 90 dagen.
- Het werkt niet meer als je het intrekt, als het verloopt, als je het team verlaat of alleen nog de facturatie doet, en als het team tweestapsverificatie verplicht en je account die niet heeft.

Stuur het mee in de header `Authorization`:

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

## Scopes

Een token doet alleen wat de scopes toestaan. Kies er zo min mogelijk.

| Scope                  | Staat toe                                     | Vereist                |
| ---------------------- | --------------------------------------------- | ---------------------- |
| `software:read`        | Zoeken in de catalogus                        |                        |
| `vulnerabilities:read` | Kwetsbaarheden lezen                          |                        |
| `watches:read`         | Watches lezen                                 |                        |
| `watches:write`        | Watches toevoegen, wijzigen, verwijderen      |                        |
| `projects:read`        | Projecten en hun rapporten lezen              |                        |
| `projects:write`       | Projecten toevoegen en lockfiles sturen       |                        |
| `rules:read`           | CVE-regels en hun matches lezen               |                        |
| `rules:write`          | CVE-regels toevoegen, wijzigen en verwijderen |                        |
| `cves:read`            | CVE's lezen en doorzoeken                     |                        |
| `endpoints:read`       | Kanalen lezen                                 | Owner of admin         |
| `endpoints:write`      | Kanalen toevoegen, wijzigen, verwijderen      | Owner of admin         |
| `deliveries:read`      | Het bezorglog lezen                           | Owner of admin         |
| `deliveries:write`     | Berichten opnieuw versturen                   | Owner of admin         |
| `events:read`          | De events van het team ophalen                | Business of Enterprise |

In de API heten kanalen `endpoints`.

## Wat je kunt doen

| Onderdeel      | Endpoints                                                                                                                                                                                                                |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Meta           | `GET /me`: het token, team, abonnement en de limieten                                                                                                                                                                    |
| Software       | `GET /software?search=&type=`, `GET /software/{type}/{slug}`, `GET /software/{type}/{slug}/vulnerabilities`                                                                                                              |
| Kwetsbaarheden | `GET /vulnerabilities/{id}`                                                                                                                                                                                              |
| Watches        | `GET /watches`, `POST /watches`, `PUT /watches`, `GET /watches/{id}`, `PATCH /watches/{id}`, `DELETE /watches/{id}`                                                                                                      |
| Projecten      | `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-regels     | `GET /rules`, `POST /rules`, `POST /rules/preview`, `GET /rules/{id}`, `PATCH /rules/{id}`, `DELETE /rules/{id}`, `GET /rules/{id}/matches`, zie [CVE-regels](https://ladon.hackindex.io/nl/docs/cve-rules.md)                                          |
| CVE's          | `GET /cves?search=&severity=&kev=&published_after=`, `GET /cves/{id}`                                                                                                                                                    |
| Kanalen        | `GET /endpoints`, `POST /endpoints`, `GET /endpoints/{id}`, `PATCH /endpoints/{id}`, `DELETE /endpoints/{id}`, `POST /endpoints/{id}/test`, `POST /endpoints/{id}/rotate-secret`                                         |
| Bezorglog      | `GET /endpoints/{id}/messages`, `GET /messages/{id}/attempts`, `POST /messages/{id}/retry`, `POST /endpoints/{id}/recover`                                                                                               |
| Events         | `GET /events?after=`                                                                                                                                                                                                     |

## Projecten {#projects}

Watches, CVE-regels en kanalen leven in een [project](https://ladon.hackindex.io/nl/docs/projects.md). In antwoorden hebben ze een veld `project` met de publieke id van hun project, zoals `prj_01JB8Z7R4M2N6P8Q0S2U4W6Y8A`.

- `POST /watches`, `PUT /watches`, `POST /rules` en `POST /endpoints` nemen een optioneel `project`. Laat je het weg, dan gebruikt Ladon het [standaardproject](https://ladon.hackindex.io/nl/docs/projects.md#default) van het team, dus bestaande scripts blijven werken.
- `GET /watches`, `GET /rules`, `GET /endpoints` en `GET /events` nemen een optioneel `?project=` om één project te tonen. Laat je het weg, dan krijg je elk project van het team.
- Een kanaal krijgt alleen de meldingen van het eigen project. `project_filter` op kanalen bestaat niet meer en wordt genegeerd als je het meestuurt. Wil je de meldingen van meerdere projecten op één adres, voeg dan in elk project een kanaal met dat adres toe.

## Een plugin volgen

```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"}'
```

Noem de software met `type` (`plugin`, `theme`, `core`, `npm`, `composer`, `pypi`, `gem`, `cargo`, `golang`, `maven` of `github`) en `slug`. Voor pakketten is de slug de pakketnaam, zoals `@angular/core`, `laravel/framework`, `django`, het Go-modulepad `github.com/gin-gonic/gin` of de Java-`groupId:artifactId` `org.apache.logging.log4j:log4j-core`, en `version_constraint` gebruikt de bereiken van die taal, zie [Software volgen](https://ladon.hackindex.io/nl/docs/watches.md#ecosystems). Een premium plugin of theme die nog niet in de catalogus staat, voeg je toe met de slug, de mapnaam in `wp-content`. Die blijft privé voor de teams die hem volgen, tot WordPress.org of een kwetsbaarheidsfeed hem kent. Core moet in de catalogus staan. Laat `events` weg voor de standaardmeldingen, en `project` om de watch aan het standaardproject toe te voegen. Geef `tags` mee, bijvoorbeeld `["client-acme"]`, om de meldingen naar kanalen met een passende `tag_filter` te sturen (zie [Kanalen](https://ladon.hackindex.io/nl/docs/channels.md#tags)). Het antwoord is `201` met de watch. Iets twee keer volgen in hetzelfde project geeft `409`, een vol abonnement geeft `402`. Dezelfde software in een ander project is een eigen watch, en telt één keer mee voor je abonnement.

## Alle watches in één keer vervangen

`PUT /watches` krijgt de volledige lijst van wat één project moet volgen. Noem het project in `project` naast `watches`, of laat het weg voor het standaardproject. Software in de lijst wordt toegevoegd of bijgewerkt, software die er niet in staat wordt in dat project niet meer gevolgd. Andere projecten blijven zoals ze zijn. Premium plugins en themes werken hetzelfde als bij `POST /watches`. Dezelfde lijst nog een keer sturen verandert niets, dus het past in een CI-job. Wil je elk pakket in een lockfile volgen, stuur die dan als project, zie hieronder.

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

Elk item kent `software`, `version_constraint`, `events`, `include_informational` en `tags`. Gepauzeerde watches blijven gepauzeerd en ernstfilters blijven zoals ze zijn. Een item zonder `tags` houdt de tags die de watch al heeft, een lege lijst haalt ze weg. Het antwoord bevat alle watches, en `meta` zegt hoeveel er `created`, `updated` en `removed` zijn. Een lijst kan maximaal 2000 items hebben.

## Een lockfile sturen

Een [project](https://ladon.hackindex.io/nl/docs/projects.md) is een repository die Ladon kent aan de lockfiles. Maak er een met `POST /projects`, met `name` en de lockfile als upload in `lockfile`. Stuur daarna elke nieuwe lockfile naar `POST /projects/{id}/lockfile`. Die vervangt de lockfile van het project met dezelfde naam, de andere lockfiles van het project blijven. Een project met meer lockfiles krijgt één aanroep 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"
```

In plaats van uploads kun je de tekst sturen in `content`, met de bestandsnaam in `filename`, en de tekst van het manifest in `manifest_content`. Voeg het manifest, zoals `package.json` of `Gemfile`, toe in `manifest` om directe en dev-afhankelijkheden uit elkaar te houden waar de lockfile dat niet doet. `include_dev` en `tags` werken bij aanmaken en met `PATCH /projects/{id}`. Een project kiest niet welke meldingen het stuurt, de kanalen doen dat. Projecten hebben dus geen `events`, `severity` of `include_informational` in hun antwoorden, en die velden worden genegeerd als je ze naar een project of naar `POST /projects/{id}/software` stuurt. Het antwoord bevat het project met `summary` en `findings`, zoals `npm audit`, zodat CI de build erop kan laten falen. Watches die projecten maken, blijven buiten de watches-endpoints.

## Meldingen routeren op tag

Een kanaal met een `tag_filter` krijgt alleen de meldingen van watches die minstens één van die tags hebben. Een lege lijst, of het veld weglaten, betekent elke watch van het project van het kanaal.

```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 bestaan uit kleine letters, cijfers, punten, streepjes en underscores, maximaal 32 tekens per tag en 10 per watch of kanaal.

## Mislukte meldingen opnieuw versturen

Na een storing bij jou stuurt `POST /endpoints/{id}/recover` met `since` (ISO 8601, maximaal 30 dagen geleden) elk bericht van het kanaal dat sindsdien mislukte of werd opgegeven nog een keer, binnen ongeveer 10 seconden. Tests blijven buiten beschouwing. Het antwoord is `202` met het aantal in `data.requeued`. Het kanaal moet aan staan, anders krijg je `409`. `POST /messages/{id}/retry` doet hetzelfde voor één bericht. In Ladon heet dit **Opnieuw versturen** op de kanaalpagina.

## Events ophalen

In plaats van webhooks te ontvangen, kun je om nieuwe meldingen vragen. `GET /events` geeft de events die op de watches van het team pasten, of met `?project=` van één project, oudste eerst, in dezelfde vorm als een webhook. Geef het `id` van het laatste event dat je verwerkte mee als `after`, en `limit` tot 100.

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

`meta.next_cursor` is het id voor de volgende keer, `meta.has_more` zegt of je meteen opnieuw moet vragen. De events-API hoort bij Business en Enterprise.

## Lijsten en pagina's

Lijsten geven `data`, `links` en `meta` met `current_page`, `last_page`, `per_page` en `total`. Vraag tot 100 items met `per_page` en de volgende pagina met `page`. Events gebruiken een cursor, zie hierboven.

## Wijzigingen

`PATCH` wijzigt alleen de velden die je meestuurt. Stuur `"paused": true` of `false` om een watch of kanaal te pauzeren of te hervatten.

Elke `POST` accepteert een header `Idempotency-Key` van maximaal 255 tekens, bijvoorbeeld een UUID. Komt hetzelfde verzoek met dezelfde sleutel binnen 24 uur nog eens, dan krijg je het eerste antwoord terug, met de header `Idempotent-Replayed: true`, en gebeurt er niets dubbel. De sleutel gebruiken voor een ander verzoek is een fout.

## Limieten

Elk token kan 300 verzoeken per minuut doen bij Pro en Business en 1000 bij Enterprise. Een heel team kan drie keer zoveel. Antwoorden op een geldig token hebben `X-RateLimit-Limit` en `X-RateLimit-Remaining`. Boven de limiet krijg je `429` met `Retry-After` in seconden.

Advisories voor pakketten veranderen elke 15 minuten en WordPress-gegevens ongeveer elk half uur, dus vaker dan om de paar minuten vragen levert zelden iets nieuws op.

## Fouten

Fouten gebruiken `application/problem+json` ([RFC 9457](https://www.rfc-editor.org/rfc/rfc9457)). `type` linkt naar de uitleg hieronder, `detail` zegt wat er in dit geval misging. De teksten in de antwoorden zijn Engels.

```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 Ongeldige JSON** (`#error-invalid-json`): De body is geen geldige JSON.
- **400 Ongeldige Idempotency-Key** (`#error-invalid-idempotency-key`): De sleutel is langer dan 255 tekens.
- **401 Niet ingelogd** (`#error-unauthenticated`): Geen token, een token dat niet bestaat, of een token dat is ingetrokken of verlopen. Ook als de eigenaar van het token niet meer in het team zit.
- **402 Limiet van het abonnement bereikt** (`#error-plan-limit`): Het team gebruikt alle watches, projecten of kanalen die het abonnement toestaat. `limit` zegt welke, `upgrade_url` waar je upgradet.
- **402 Niet in je abonnement** (`#error-plan-feature`): Het abonnement heeft dit niet, bijvoorbeeld de API bij het gratis abonnement of de events-API vóór Business. `feature` zegt welke.
- **403 Scope ontbreekt** (`#error-missing-scope`): Het token heeft niet de scope die dit verzoek nodig heeft. Maak een token met die scope.
- **403 Rol ontbreekt** (`#error-missing-role`): Kanalen en het bezorglog zijn voor owners en admins van het team.
- **403 Tweestapsverificatie vereist** (`#error-two-factor-required`): Het team verplicht tweestapsverificatie. Zet die aan in je HackIndex-account.
- **403 Niet toegestaan** (`#error-forbidden`): Het verzoek is niet toegestaan.
- **404 Niet gevonden** (`#error-not-found`): Het bestaat niet, of het hoort bij een ander team.
- **405 Methode niet toegestaan** (`#error-method-not-allowed`): Het pad bestaat, maar niet met deze methode.
- **409 Conflict** (`#error-conflict`): Het verzoek botst met de huidige stand, bijvoorbeeld een watch die al bestaat of een bericht opnieuw sturen dat al bezorgd is.
- **422 Ongeldige velden** (`#error-validation`): Een of meer velden kloppen niet. `errors` geeft de meldingen per veld.
- **422 Idempotency-Key hergebruikt** (`#error-idempotency-key-reused`): De sleutel is in de laatste 24 uur gebruikt voor een ander verzoek. Gebruik voor elk nieuw verzoek een nieuwe sleutel.
- **429 Te veel verzoeken** (`#error-rate-limited`): Wacht het aantal seconden uit `Retry-After` en probeer het opnieuw.
- **500 Serverfout** (`#error-server-error`): Er ging iets mis aan onze kant. Probeer het later opnieuw. Een `POST` met een `Idempotency-Key` kun je veilig herhalen.

## Versies

De versie staat in het pad: `v1`. Nieuwe velden en endpoints kunnen altijd bijkomen, dus negeer velden die je niet kent. Wijzigingen die een koppeling kunnen breken, komen met een nieuwe versie en worden aangekondigd in de changelog. Webhook-payloads hebben hun eigen `api_version`, zie [Events en payloads](https://ladon.hackindex.io/nl/docs/events.md).

## Gegevens en licenties

Kwetsbaarheden hebben `source`, met een link naar het record en de copyrightvermeldingen van de gegevens. Houd die bij elke kopie die je maakt, bijvoorbeeld in een ticket of rapport. Alle licenties staan op de [licentiepagina](https://ladon.hackindex.io/licenties).
