# API specs

The Resolve Platform inventory of your OpenAPI and Swagger descriptions, how each one is scored for robustness, and the sources Vulnesis reads them from.

**Configuration › API Specs** (`/resolve/api-specs`) lists every OpenAPI and Swagger description Vulnesis holds for your organisation, scores how well each one defends its routes, and manages the places Vulnesis reads specs from.

## How specs arrive

| Way in | What it does |
|---|---|
| `vulnetix api discover` | Finds the specs in a working tree and uploads them. Repository files need no source on this page. See [vulnetix api](/cli/commands/api.md). |
| `vulnetix api upload <file>` | Uploads one spec, such as one a build step generates. |
| URL source | Fetches one published spec file, such as `https://api.example.com/openapi.json`. |
| Host source | Looks for a spec at the usual paths on a hostname. |
| Cloudflare connector | Reads API Shield operations and proxied hosts from your Cloudflare account. |

Sources can also be declared as code with the [ApiSpecSource](/platform-iac/kinds/api-spec-source.md) kind.

## Specs tab

The list is sorted lowest score first. A spec not yet scored goes last.

| Control | Does |
|---|---|
| **Active**, **Discovered**, **All** | Status chips, each with a count |
| Search | Matches title, path or repository |

Score bands: 85 and above is **Strong**, 60 to 84 is **Needs work**, below 60 is **At risk**.

Selecting a spec opens the inspector: its score, the top fixes by points gained, and **Download** for the latest stored version. **Run now** scores the stored contract again and saves the result to Activity.

### Full breakdown

**Full breakdown** lists every check with its status: **Defended**, **Open** or **Not applicable**. A check that does not apply is left out of the score, never counted as zero. Each open check says what fixing it gains. Where the spec names a repository, an open check offers a button that opens a Software Factory session on that repository with the fix written as the request.

## Discovered tab

Specs that discovery found and nobody has accepted yet, newest first, with their operation count. **Accept** tracks and scores a spec on the Specs tab. **Ignore** stops it appearing here. Both work on one spec or on a selection.

## Sources tab

Add a source with a kind (**URL**, **Host** or **Connector**) and a target. A host source asks how far it may probe:

| Probe mode | Behaviour |
|---|---|
| **Exact URL** | Fetches only the address given |
| **Owned host** | Probes common spec paths. Needs ownership verified. |
| **Authorized host** | Probes a host you may test but do not own. You must tick **I am authorized to test this host.** |

Ownership is verified by publishing a token Vulnesis gives you, either as a TXT record at `_vulnetix-surface.<host>` or as the file `https://<host>/.well-known/vulnetix-surface.txt`. Either is enough.

**Connect Cloudflare** takes an API token with Read access to API Gateway and DNS. The token is stored write-only and never shown again. A Cloudflare source runs on a schedule, daily by default.

Each source row shows the state of its last run and has **Run** and remove actions. Removing a source keeps the specs already found from it.

## Activity tab

Every scoring run and new spec version, filterable by **Run now**, **Re-evaluated** and **New version**, and a chart of saved scores over 30 days, 90 days or a year.

## Plan

Listing specs, routes, scores and the Activity tab work on every plan. Remote discovery needs **Business** or above: a host source, a connector, any probe mode other than exact, ownership verification, running a source and connecting Cloudflare. The server refuses these below Business.

Specs feed [internet exposure](/vulnerability-management/prioritisation/internet-exposure.md) by matching routes to findings.
