Skip to content
HackIndex Ladon
Menu

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 /rules and POST /endpoints take an optional project. Leave it out and Ladon uses the default project 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

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"
}
400

Invalid JSON

#invalid-json

The body is not valid JSON.

400

Invalid Idempotency-Key

#invalid-idempotency-key

The key is longer than 255 characters.

401

Unauthenticated

#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

#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

#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

#missing-scope

The token does not have the scope this request needs. Create a token with that scope.

403

Missing role

#missing-role

Channels and the delivery log are for owners and admins of the team.

403

Two-factor authentication required

#two-factor-required

The team requires two-factor authentication. Turn it on in your HackIndex account.

403

Forbidden

#forbidden

The request is not allowed.

404

Not found

#not-found

It does not exist, or it belongs to another team.

405

Method not allowed

#method-not-allowed

The path exists, but not with this method.

409

Conflict

#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

#validation

One or more fields are not valid. errors lists the messages per field.

422

Idempotency-Key reused

#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

#rate-limited

Wait the number of seconds in Retry-After and try again.

500

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

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.