# API

Vulnerability-Lookup exposes a REST API under the `/api` path of every
instance. The same instance also serves an **interactive Swagger UI at
`/api/`**, where you can browse the endpoints and try them out live.
[PyVulnerabilityLookup](https://github.com/vulnerability-lookup/PyVulnerabilityLookup)
is the official Python client for the API.

```{note}
Building a mirror, scanner, or other automated consumer? Read
[Access patterns for automated consumers](access-patterns.md) first — it
covers the canonical sync path (`since=` + the pub/sub stream),
identification expectations, and the rate-limit posture. The same
guidance is exposed in machine-readable form at
`/.well-known/api-policy.json`.
```

## Quick start

The examples below use the public CIRCL instance
(`https://vulnerability.circl.lu`); replace the host with your own. Responses
are JSON.

Look up a vulnerability by ID:

```bash
$ curl 'https://vulnerability.circl.lu/api/vulnerability/CVE-2024-38063'
```

Filter comments by metadata — for example those flagged as a Proof of Concept.
The `meta` parameter is a JSON value matched against the comment's `meta` field
(JSONB containment). Use `-G`/`--data-urlencode` so curl URL-encodes the JSON
for you instead of escaping it by hand:

```bash
$ curl -G 'https://vulnerability.circl.lu/api/comment/' \
    --data-urlencode 'meta=[{"tags":["vulnerability:information=PoC"]}]'
```

Tags are matched exactly, so use the full machine-tag value (for example
`vulnerability:information=PoC`, not just `PoC`).

Paginate any list endpoint with `page` and `per_page` (see
[Response format](#response-format) for the envelope):

```bash
$ curl 'https://vulnerability.circl.lu/api/sighting/?vuln_id=CVE-2024-38063&per_page=50'
```

For the full list of endpoints, parameters, and response models, see the
[OpenAPI specification](#openapi-specification) below.

## Response format

All list endpoints return a paginated response with the following structure:

```json
{
    "metadata": {
        "count": 42,
        "page": 1,
        "per_page": 10
    },
    "data": []
}
```

(OpenAPI)=

## OpenAPI specification

The complete reference below is generated from the API's OpenAPI (Swagger)
specification — the same spec that powers the interactive Swagger UI at
`/api/`.

```{eval-rst}
.. openapi:: _static/files/swagger.sanitized.json
```