# Discovery

Find a TEA server from a domain through /.well-known/tea, choose a version, and resolve a TEI or a Package URL to the product release it names with /discovery.

Every request on this page is public. No account or key is needed.

## 1. Fetch the discovery document

Start from a domain: the domain in a TEI, a purl, or a vendor contact. Fetch its discovery document.

```bash
curl -sL https://vulnes.is/.well-known/tea
```

`vulnes.is` redirects to `www.vulnes.is`, so follow redirects (`-L`). The API host also answers `/.well-known/tea` itself.

```json
{
  "schemaVersion": 1,
  "endpoints": [
    {
      "url": "https://www.vulnes.is/tea",
      "versions": ["1.0.0", "0.4.0"],
      "priority": 1
    }
  ]
}
```

| Field | Meaning |
|---|---|
| `url` | The API base, without a version |
| `versions` | The specification versions served, as full SemVer |
| `priority` | Orders endpoints when a server lists several |

Append `/v` and a version to `url`: `https://www.vulnes.is/tea/v1.0.0`. Choose the greatest version you and the server both support, and use `priority` only between endpoints that offer it equally. `https://www.vulnes.is/tea/v1` is a stable alias that serves 1.0.0.

## 2. Resolve an identifier

A TEI names a product release. `/discovery` says which release it is and which servers can answer for it.

```bash
curl -s 'https://www.vulnes.is/tea/v1.0.0/discovery?tei=tei%3A%2F%2Fvulnes.is%2Fuuid%2F54e8820d-0803-5a4f-858d-88a279486564'
```

```json
[
  {
    "productReleaseUuid": "9a5e1b46-ee87-5238-bd1f-80424b7414f9",
    "servers": [
      { "rootUrl": "https://www.vulnes.is/tea", "versions": ["1.0.0", "0.4.0"] }
    ]
  }
]
```

Here the TEI names the product `Vulnesis/cli`, and the answer is a product release of it. A release's own TEI resolves to that release. Percent-encode the TEI; it contains `:` and `/`.

### TEI spelling

| Version | Form | Example |
|---|---|---|
| 1.0.0 | `tei://<domain>/<type>/<id>` | `tei://vulnes.is/uuid/54e8820d-0803-5a4f-858d-88a279486564` |
| 0.4.0 | `urn:tei:<type>:<domain>:<id>` | `urn:tei:uuid:vulnes.is:54e8820d-0803-5a4f-858d-88a279486564` |

The Vulnesis server accepts both spellings at either version. In 1.0.0 a purl inside a TEI is base64url encoded: `tei://vulnes.is/purl/cGtnOmdpdGh1Yi9WdWxuZXRpeC9jbGlAdjMuODIuMg`.

### By Package URL

A 1.0.0 server also resolves a purl directly. Pass exactly one of `tei` or `purl`.

```bash
curl -s 'https://www.vulnes.is/tea/v1.0.0/discovery?purl=pkg%3Agithub%2FVulnetix%2Fcli%40v3.82.2'
```

## With the CLI

```bash
vulnetix tea discover vulnes.is
vulnetix tea resolve tei://vulnes.is/uuid/54e8820d-0803-5a4f-858d-88a279486564
vulnetix tea resolve pkg:github/Vulnesis/cli@v3.82.2
```

See [Reading with the CLI](/tea/cli/reading.md).

Next: [Walk the object graph](/tea/consume/walk-the-graph.md).
