# Hub API Overview
Source: https://docs.treeship.dev/api/overview

> API reference for the Treeship Hub at api.treeship.dev. Authentication, endpoints, and error format.

## Base URL

```
https://api.treeship.dev
```

All endpoints are prefixed with `/v1/`.

## What Hub does

Hub is optional infrastructure. Artifact validity never depends on it -- the signatures are the trust. Hub provides three things:

1. **Artifact storage** for signed envelopes pushed from local Treeships
2. **Shareable verification URLs** at `treeship.dev/verify/{artifact_id}`
3. **Transparency log anchoring** via Sigstore Rekor

Hub does not sign, modify, or interpret artifacts. It stores and serves the DSSE envelopes created locally. The WASM verifier on the verification page runs client-side, so Hub cannot forge a passing result.

## Authentication

Hub uses DPoP (Demonstration of Proof-of-Possession) for write endpoints. There are no API keys, session tokens, or bearer tokens.

**Authenticated requests require two headers:**

| Header          | Value                                      |
| --------------- | ------------------------------------------ |
| `Authorization` | `DPoP {dock_id}`                           |
| `DPoP`          | A fresh JWT signed by the dock private key |

The DPoP JWT contains:

```json
{
  "iat": 1711500000,
  "jti": "unique-random-hex",
  "htm": "POST",
  "htu": "https://api.treeship.dev/v1/artifacts"
}
```

Hub verifies:

* `iat` is within 60 seconds of the current time
* `jti` has not been seen before (replay protection)
* `htm` matches the HTTP method of the request
* `htu` matches the request URL
* The JWT signature matches the dock public key stored during login

**Read endpoints** require no authentication.

## Endpoints

| Method | Path                                 | Auth | Description                                                |
| ------ | ------------------------------------ | ---- | ---------------------------------------------------------- |
| `GET`  | `/v1/dock/challenge`                 | None | Start device flow login                                    |
| `GET`  | `/v1/dock/authorized`                | None | Poll device flow status                                    |
| `POST` | `/v1/dock/authorize`                 | None | Complete device flow login                                 |
| `POST` | `/v1/artifacts`                      | DPoP | Push a signed artifact                                     |
| `GET`  | `/v1/artifacts/:id`                  | None | Retrieve an artifact                                       |
| `GET`  | `/v1/workspace/:dock_id`             | DPoP | List artifacts in a workspace                              |
| `POST` | `/v1/session`                        | DPoP | Mint a short-lived share token for browser workspace reads |
| `GET`  | `/v1/verify/:id`                     | None | **Retired.** Returns `410 Gone`; verify locally instead    |
| `POST` | `/v1/merkle/checkpoint`              | DPoP | Publish a Merkle checkpoint                                |
| `POST` | `/v1/merkle/proof`                   | DPoP | Publish a Merkle inclusion proof                           |
| `POST` | `/v1/merkle/consistency`             | DPoP | Publish a Merkle consistency proof                         |
| `GET`  | `/v1/merkle/checkpoint/latest`       | None | Get the latest Merkle checkpoint                           |
| `GET`  | `/v1/merkle/checkpoint/:id`          | None | Get a specific Merkle checkpoint                           |
| `GET`  | `/v1/merkle/consistency`             | None | Get a Merkle consistency proof                             |
| `GET`  | `/v1/merkle/:artifactId`             | None | Get a Merkle inclusion proof                               |
| `PUT`  | `/v1/receipt/:session_id`            | DPoP | Publish a session receipt                                  |
| `GET`  | `/v1/receipt/:session_id`            | None | Fetch a session receipt (permanent URL)                    |
| `GET`  | `/v1/ship/agents`                    | DPoP | List this ship's registered agents                         |
| `GET`  | `/v1/ship/sessions`                  | DPoP | List this ship's sessions                                  |
| `GET`  | `/v1/agents`                         | None | Resolve an agent URI to its verifiable bundle              |
| `GET`  | `/v1/agents/log`                     | None | Agent transparency log (metadata + Merkle anchors)         |
| `GET`  | `/v1/agents/history`                 | None | Agent receipt history                                      |
| `GET`  | `/v1/agents/match`                   | None | Match agents in the registry                               |
| `GET`  | `/v1/stats`                          | None | Public adoption metrics (counts only, cached 5 min)        |
| `GET`  | `/.well-known/treeship/revoked.json` | None | Revoked key list                                           |

## Error format

All errors return JSON:

```json
{
  "error": "artifact not found"
}
```

HTTP status codes:

* `200` -- Success
* `201` -- Created (artifact stored)
* `202` -- Accepted (pending, used during device flow polling)
* `400` -- Bad request
* `401` -- Authentication failed (DPoP invalid)
* `404` -- Not found
* `409` -- Conflict (device code already used)
* `410` -- Gone (expired device code, or the retired `/v1/verify/:id` endpoint)
* `500` -- Server error

## OpenAPI spec

The full OpenAPI 3.1 spec is available at [hub-openapi.yaml](/docs/api/hub-openapi.yaml) for code generation and tooling.