API
All docs
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.
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
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:
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 |
| 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
Watches, CVE rules and channels live in a project. In answers they have a project field with the public id of their project, such as prj_01JB8Z7R4M2N6P8Q0S2U4W6Y8A.
POST /watches,PUT /watches,POST /rulesandPOST /endpointstake an optionalproject. Leave it out and Ladon uses the default project of the team, so existing scripts keep working.GET /watches,GET /rules,GET /endpointsandGET /eventstake 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_filteron 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
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. 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). 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.
{
"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 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:
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.
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.
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). type links to the explanation below, detail says what went wrong in this case.
{
"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"
}
Invalid JSON
#invalid-jsonThe body is not valid JSON.
Invalid Idempotency-Key
#invalid-idempotency-keyThe key is longer than 255 characters.
Unauthenticated
#unauthenticatedNo 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.
Plan limit reached
#plan-limitThe team uses every watch, project or channel its plan allows. limit says which, upgrade_url where to upgrade.
Not in your plan
#plan-featureThe plan does not include this, for example the API on the free plan or the events API before Business. feature says which.
Missing scope
#missing-scopeThe token does not have the scope this request needs. Create a token with that scope.
Missing role
#missing-roleChannels and the delivery log are for owners and admins of the team.
Two-factor authentication required
#two-factor-requiredThe team requires two-factor authentication. Turn it on in your HackIndex account.
Forbidden
#forbiddenThe request is not allowed.
Not found
#not-foundIt does not exist, or it belongs to another team.
Method not allowed
#method-not-allowedThe path exists, but not with this method.
Conflict
#conflictThe request clashes with the current state, for example a watch that already exists or sending a message again that was delivered.
Validation failed
#validationOne or more fields are not valid. errors lists the messages per field.
Idempotency-Key reused
#idempotency-key-reusedThe key was used for a different request in the last 24 hours. Use a new key for every new request.
Too many requests
#rate-limitedWait the number of seconds in Retry-After and try again.
Server error
#server-errorSomething 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.
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.