# Model Intelligence API

The Model Intelligence API (`/api/mi/v1`, served from `upcube.ai`) is the public, anonymous surface over the model publication plane. No account, no API key. Responses are cacheable (`public, max-age=300, s-maxage=3600`).

:::note
The examples below execute live against production in the docs example gate. When the gate has no network, it falls back to recorded fixtures and still contract-checks every response.
:::

## GET /api/mi/v1/health

Plane seed status. No database reads; safe to poll.

```bash exec GET https://upcube.ai/api/mi/v1/health expect:200 schema:mi-health
curl -sS https://upcube.ai/api/mi/v1/health
```

Response shape:

```json
{
  "ok": true,
  "seeded_models": 120,
  "generated_at": "2026-10-03T00:00:00.000Z",
  "pointers": "static-seed",
  "objects": "static-assets"
}
```

`pointers` is `d1` when the pointer store is bound (else `static-seed`); `objects` is `r2` when the object store is bound (else `static-assets`).

## GET /api/mi/v1/models

The public model index. Only HIT-state models are listed — removed, quarantined, and missing entries never appear here.

```bash exec GET https://upcube.ai/api/mi/v1/models expect:200 schema:mi-models
curl -sS https://upcube.ai/api/mi/v1/models
```

Response shape:

```json
{
  "models": [
    {
      "slug": "example-model",
      "name": "Example Model",
      "provider": "example",
      "entityId": "mi_example",
      "contentVersion": "2026-10-03.1"
    }
  ],
  "total": 1,
  "generated_at": "2026-10-03T00:00:00.000Z"
}
```

## GET /api/mi/v1/models/:slug

One model's envelope. The five publication states map to HTTP semantics:

| State | HTTP | Meaning |
|---|---|---|
| HIT | 200 + `ETag: "<contentVersion>"` | The full envelope |
| REDIRECT | 301 to the canonical slug | Slug moved |
| REMOVED | 410 `{"error":"removed"}` | Gone, deliberately |
| QUARANTINED | 500 `{"error":"quarantined","reason"}` | Held for review |
| MISS | 404 `{"error":"not found"}` | Unknown slug |

```bash
curl -sS https://upcube.ai/api/mi/v1/models/<slug>
```

Use a `slug` from the index above. Slugs are canonical keys; redirects resolve to the current canonical slug.

## Errors

Errors are small JSON objects with an `error` string and, where useful, a `reason`. There is no envelope beyond that: `{ "error": "not found" }`.

## Next steps

- [Quickstart](/docs/get-started/quickstart)
- [Flow API reference](/docs/api/flow)
- [Model Intelligence](/model-intelligence)