# HiveLogistics API — `/api/logistics/solve`

**Status:** v0.1 · pre-GA · auth: `X-Hive-Key` bearer or `Authorization: Bearer <hive-jwt>`
**Last updated:** 2026 Q4

Submit a [NVIDIA cuOpt](https://docs.nvidia.com/cuopt/user-guide/25.02/managed-client/cli-api.html) problem; receive a solution with a **Hive signed receipt** anchored on Base 8453.

---

## `POST /api/logistics/solve`

### Request

```http
POST /api/logistics/solve HTTP/1.1
Host: api.thehiveryiq.com
Content-Type: application/json
X-Hive-Key: hk_live_...
Idempotency-Key: <ulid>  (optional, strongly recommended)
```

```json
{
  "problem_type": "CVRP-TW",
  "solver": {
    "engine": "nvidia_cuopt",
    "version": "25.02",
    "max_solve_ms": 5000,
    "objective": "minimize_distance"
  },
  "data": {
    "depot": [37.7749, -122.4194],
    "stops": [
      {"id": "s1", "lat": 37.78, "lon": -122.41, "demand": 12, "window": ["09:00","12:00"], "service_min": 4},
      "..."
    ],
    "vehicles": [
      {"id": "v1", "capacity": 200, "shift": ["08:00","18:00"], "max_distance_km": 220}
    ],
    "matrix": "auto"   // or inline cost/time matrices
  },
  "attestation": {
    "actor": "did:hive:agent:dispatcher-acme-001",
    "purpose": "fmcsa-eld-audit",
    "tags": ["last-mile","wave-04","2026-11-04"]
  }
}
```

**Accepted `problem_type` values:** `TSP`, `VRP`, `CVRP`, `CVRP-TW`, `PDP`, `MIP`, `LP`. See the cuOpt schema for full constraints (precedence, breaks, soft windows, multi-depot).

**Constraints**

| Field            | Type            | Required | Notes                                                                       |
| ---------------- | --------------- | -------- | --------------------------------------------------------------------------- |
| `problem_type`   | enum            | yes      | One of the values above                                                     |
| `solver.engine`  | enum            | no       | Defaults to `nvidia_cuopt`. `fallback_cpu` available on outage              |
| `data.stops`     | array           | yes      | ≤ 500 (Fleet) · ≤ 5,000 (Operator) · ≤ 50,000 (Enterprise)                  |
| `data.vehicles`  | array           | yes      | ≥ 1                                                                         |
| `attestation.actor` | did:hive     | yes      | Signing identity — must be an active did:hive:agent under your tenant       |

### Response — `200 OK`

```json
{
  "solution": {
    "routes": [
      {"vehicle": "v1", "stops": ["s1","s14","s22","..."], "distance_km": 138.4, "time_min": 412}
    ],
    "objective_km": 412.7,
    "feasible": true,
    "solver": {
      "engine": "nvidia_cuopt",
      "version": "25.02",
      "gpu_class": "H100-SXM",
      "nvcf_function_id": "fn_8f3a...c7",
      "solve_ms": 287
    }
  },
  "receipt": {
    "receipt_id": "rcpt_8f3ac7d122ee",
    "input_hash": "sha3-256:0xa1b2...",
    "output_hash": "sha3-256:0xc4d5...",
    "signed_at": "2026-11-04T18:22:11.482Z",
    "signature_alg": "ML-DSA-65",
    "signature": "pq:0x83f1...",
    "anchor": {
      "chain": "base-8453",
      "tx_hash": "0x9aa2...",
      "block": 14982331
    }
  },
  "receipt_verification_url": "https://thehiveryiq.com/verify/rcpt_8f3ac7d122ee"
}
```

### Status codes

| Code | Meaning                                                                              |
| ---- | ------------------------------------------------------------------------------------ |
| 200  | Solved and signed                                                                    |
| 202  | Accepted for async solve (large problems > 5,000 stops); poll the returned `job_id`  |
| 400  | Malformed cuOpt payload — see `errors[]` for field-level detail                      |
| 401  | Invalid or expired `X-Hive-Key`                                                      |
| 402  | Plan exceeded — Fleet/Operator/Enterprise stop-count or rate limit                   |
| 422  | Infeasible problem — solver returned no feasible solution within `max_solve_ms`      |
| 503  | cuOpt/NVCF upstream unavailable — receipt is still issued with `solver:fallback_cpu` |

### Idempotency

If `Idempotency-Key` is present, the API stores the receipt for **24 hours** and returns the identical signed receipt on retry. Idempotency keys must be ULIDs or UUIDv7; collisions across tenants are impossible.

### Webhooks (optional)

Subscribe at `/api/logistics/webhooks`. Events: `solve.completed`, `solve.failed`, `receipt.anchored` (fires after Base 8453 confirms, typically < 2s).

---

## Verification

Anyone can verify a receipt offline using the open-source verifier at <https://github.com/thehiveryiq/verifier>:

```bash
hive-verify rcpt_8f3ac7d122ee
```

Or HTTP:

```http
GET /api/v1/receipts/rcpt_8f3ac7d122ee
```

Returns the receipt body plus the on-chain anchor proof.

---

## Attribution

All HiveLogistics solves are powered by [NVIDIA cuOpt](https://www.nvidia.com/en-us/ai-data-science/products/cuopt/) via [NVIDIA Cloud Functions](https://docs.nvidia.com/cuopt/user-guide/25.02/managed-client/cli-api.html). cuOpt is open source on [GitHub/NVIDIA/cuopt](https://github.com/NVIDIA/cuopt). NVIDIA, cuOpt, and the NVIDIA logo are trademarks of NVIDIA Corporation.

Hive operates as an independent integrator; HiveLogistics is not an NVIDIA product. Receipts attribute the solver explicitly via `solution.solver.engine` and the Hive receipt's `optimization_engine` / `nvidia_attribution` fields.