# Physical AI — canonical API (v1)

The machine contract behind `physicalai.santismm.com`. The web pages, this REST
API and the federated MCP tools on `santismm.com/mcp` (`santismm-knowledge-mcp`
0.6.0) are three projections of **one** dataset and **one** set of engines:

| Engine | Module | Used by |
| --- | --- | --- |
| ROI / TCO, 36-month model + sensitivity | `src/lib/roi.ts` | `/roi-calculator`, `POST /api/calculate/roi` |
| Readiness assessment (areas, yes/partial/no weights, bands) | `src/lib/readiness.ts` | `/deployment-guide` checklist, `POST /api/assess-fit` |
| Platform comparison (published fields only) | `src/lib/compare.ts` | `POST /api/compare` |
| Search over platforms, cases, guides, taxonomy, methodology | `src/lib/search.ts` | `GET /api/search` |

Nothing is computed twice. A change to a formula changes the page, the API and
the MCP answer together, and `model_version` says which formula produced a
result. Serialization, validation and the HTTP layer live in `src/lib/api/*`;
the route handlers in `src/app/api/*` are thin.

## Conventions

- Base URL: `https://physicalai.santismm.com/api`. Read-only data is `GET`;
  the three engines are `POST` with a JSON body. No authentication.
  `GET /api` lists every endpoint.
- Every response is `application/json; charset=utf-8` with
  `Access-Control-Allow-Origin: *`. `OPTIONS` answers the CORS preflight
  (`204`, `Access-Control-Allow-Methods: GET, POST, OPTIONS`,
  `Access-Control-Allow-Headers: Content-Type`).
- `?locale=` selects the language of localized text, on `GET` and `POST` alike:
  `en` (default), `es` (reference edition), `pt`, `fr`, `de`, `ja`, `zh`. An
  unknown locale is a 400, never a silent fallback; an empty `?locale=` means
  `en`. API-specific notes and warnings (`{code, message}`) are in English;
  their `code` is stable.
- Every successful response starts with an envelope:
  `api_version` (`1.0.0`), `dataset_version` (the catalogue review month,
  `datasetReviewedAt`), `generated` (ISO timestamp of the build), `locale` and
  `license` (always `null`, see below). Error responses carry only the error.
- Stable identifiers: `{type}:{slug}` — e.g. `platform:spot`,
  `case_study:{slug}`, `guide:deployment-guide`, `taxonomy:family-quadruped`,
  `methodology:evidence-levels`, `source:{id}`. Slugs never change; a renamed
  item keeps its slug. Inside `sources` arrays, source ids appear bare
  (`"plat-spot-specsheet"`).
- Every item carries `canonical_url` (the human page, localized) and
  `api_url` (its JSON resource, with `?locale=` unless `en`).
- **Unknown is a value.** A field the maker or operator has not published is
  `null` with `status: "unpublished"`. It is never filled in, estimated or
  dropped silently. This holds for spec values, case metrics, `payback`,
  `deployed_on` and solution facts.
- Provenance travels with every claim: spec values, case facts and metrics carry
  the source ids behind them; sources resolve to `{id, title, publisher, url,
  date, accessed, provenance, review, support, checked_via, evidence_level,
  note, api_url}`. `evidence_level` is derived by `levelOf` (A–D, see
  `/methodology`), never set by hand.
- Licence: the site does not state a content licence. The API reports
  `license: null` rather than inventing one.
- Versioning: `api_version` follows semver. Additive changes — a new endpoint,
  a new field, a new enum value — raise the minor version on the same paths, so
  clients must ignore fields they do not know. A breaking change would ship
  under a new path prefix, with the current one kept and the change announced
  here first. `dataset_version` changes when the catalogue is re-reviewed.
- Rate limits: none enforced by the application today. Unfiltered reads are
  prerendered static files. Please keep sustained traffic to a few requests per
  second and cache by `dataset_version`; if a limit is ever introduced it will
  answer `429` with `Retry-After` and be documented here first.
- Unknown query parameters are ignored. Unknown **body** fields are rejected
  (400), so a typo never becomes a silent default.

### Errors

```json
{ "error": "invalid_input", "details": [{ "field": "fleet.quadruped.count", "message": "must be an integer between 0 and 10000" }] }
{ "error": "not_found", "type": "platform", "slug": "nope" }
{ "error": "method_not_allowed", "allowed": ["GET"] }
{ "error": "payload_too_large", "limit_bytes": 32768 }
```

`400` invalid input (every failing field listed; also an unknown locale, a body
that is not a JSON object), `404` unknown slug or id (`type` is `platform`,
`case_study`, `guide`, `source`, or `endpoint` for an unknown `/api` path),
`405` other methods (with an `Allow` header), `413` bodies over 32 KiB.

## Read endpoints

| Method & path | Returns |
| --- | --- |
| `GET /api` | `{ name, description, openapi, documentation, endpoints[{method, path, url, description}] }` |
| `GET /api/platforms` | `{ count, items: PlatformSummary[] }`; filters `family`, `environment`, `sector`, `access`, `lifecycle` (comma-separated) |
| `GET /api/platforms/{slug}` | `{ platform: Platform }` with resolved `sources` and related `case_studies` |
| `GET /api/case-studies` | `{ count, items: CaseStudySummary[] }`; filters `family`, `sector`, `environment`, `stage` |
| `GET /api/case-studies/{slug}` | `{ case_study: CaseStudy }` with resolved `sources` |
| `GET /api/guides` | `{ count, items: GuideSummary[] }` — `deployment-guide`, `swarms` |
| `GET /api/guides/{slug}` | `{ guide: Guide }` — sections as structured text, readiness areas and vendor questions where the guide has them |
| `GET /api/taxonomy` | `{ taxonomy }`: families, autonomy levels 0–5, coordination, control modes, sensors, environments, sectors — ids, names and descriptions (`null` where the taxonomy has none) — plus the access, lifecycle, evidence-stage and case-stage enums |
| `GET /api/methodology` | `{ methodology }`: evidence levels A–D and how they are derived (prose and machine rules), source fields, spec-condition policy, documented vs modelled, review, corrections and independence policies |
| `GET /api/sources` | `{ count, items: ResolvedSource[] }`: the whole bibliography, resolved, in bibliography order — including sources no platform, case or guide cites |
| `GET /api/sources/{id}` | `{ source }`: one resolved source |
| `GET /api/search` | see below |

Filters: OR within a parameter, AND across parameters; an unknown value is a 400.

`PlatformSummary`: `id, slug, name, maker, country, family, year, autonomy,
coordination, primary_control, environments, sectors, summary, access,
lifecycle, evidence_stage, evidence_date, canonical_url, api_url`.

`Platform` adds: `ideal_case`, `control`, `perception`, `compute` (or `null`),
`specs` (`weight_kg`, `payload_kg`, `runtime_min`, `speed_ms`, `height_m`, `ip`,
`temp_c`; see *Spec values*), `price_usd` (a spec value), `profile` (`task`,
`autonomy {alone, human, sources}`, `evidence {stage, date, text, sources}`,
`access`, `access_note`, `lifecycle`, `lifecycle_note`, `sources`),
`configurations [{name, text, sources}]`, `dual_use`, `source_quality`,
`source_url`, `evidence_level` (strongest level among the spec sources),
`limitations` (e.g. `"payload_kg unpublished"`), `sources` (every source the
sheet cites, resolved), `case_studies [{id, slug, canonical_url, api_url}]`.

`CaseStudySummary`: `id, slug, title, headline, entity, sector, environment,
family, location, stage, deployed_on {value, status}, evidence_level,
platforms (slugs), canonical_url, api_url`.

`CaseStudy` adds: `kind` (`documented`), `platform_note`,
`related_platforms [{id, slug, canonical_url, api_url}]`, `autonomy`,
`coordination`, `challenge [Fact]`, `solution {hardware, perception, navigation,
coordination}` (each a `Fact`), `metrics [{label, value, status, context,
sources}]`, `payback {value, unit: "months", status, sources}`,
`roi_statement` (`Fact` or `null`), `lessons {integration, maintenance,
scaling}` (`Fact[]`), `limitations`, `sources` (resolved). A `Fact` is
`{text, status, sources}` with `status` `published` (sourced), `editorial`
(analysis, no sources) or `unpublished` (`text: null`).

`GuideSummary`: `id, slug, title, summary, canonical_url, api_url, updated`.
`Guide` adds `editorial_note`, `sections [{id, title, canonical_url, text[],
sources[]}]` (the page's own sections; `canonical_url` has the anchor),
`readiness` (deployment guide only, else `null`: `lead`, `states`, `weights`,
`bands [{id, min, label, text}]`, `areas [{id, name, items [{id, text}]}]`,
`item_ids`, `item_count`, `assess_url`), `vendor_questions [{group,
questions[]}]` and `sources`.

### Spec values

Every spec (`weight_kg`, `payload_kg`, `runtime_min`, `speed_ms`, `height_m`,
`ip`, `temp_c`, `price_usd`) is an object, so a number never travels without
its standing:

```json
{
  "value": 90,
  "unit": "min",
  "status": "published",
  "provenance": "manufacturer",
  "conditions": "average; about 60 min when powering attachments; varies with payloads and environment",
  "sources": ["plat-spot-product", "plat-spot-ifu", "plat-spot-specsheet", "plat-spot-devdocs", "plat-spot-dock", "plat-spot-price"]
}
```

- `status`: `published` · `unpublished` (`value: null`, `provenance: null`,
  `conditions: null`, `sources: []`) · `estimate` (the sheet marks it as an
  editorial estimate; `sources: []`, because no source states the figure).
- `provenance`: `manufacturer` · `press` · `editorial_estimate`, from the sheet's
  `source` quality and its `estimated` list. Provenance and `sources` are per
  sheet (the records the sheet was checked against), not per figure; per-figure
  caveats are in `conditions`.
- `unit`: `kg`, `kg`, `min`, `m/s`, `m`, `null` (`ip`), `°C`, `USD`. `temp_c`
  is `[min, max]`.
- Manufacturer maxima are **not simultaneous**; `conditions` says under what
  test conditions each was published (`null` when the sheet states none).

### Search — `GET /api/search`

Parameters: `q` (required, ≤ 200 chars), `types` (`platform`, `case_study`,
`guide`, `taxonomy`, `methodology`), `families`, `environments`, `sectors`
(comma-separated taxonomy ids; an item without that facet — a guide, say — is
excluded when the filter is given), `locale`, `limit` (1–50, default 10).

Returns `{ query {q, types, families, environments, sectors, limit}, total,
count, results }`. Each result:

```json
{
  "id": "platform:spot",
  "type": "platform",
  "slug": "spot",
  "title": "Spot",
  "summary": "Quadruped on sale since June 2020. …",
  "family": "quadruped",
  "sectors": ["inspection", "energy", "security", "public-safety"],
  "environments": ["industrial", "offshore", "confined", "disaster", "urban"],
  "canonical_url": "https://physicalai.santismm.com/en/platforms/spot",
  "api_url": "https://physicalai.santismm.com/api/platforms/spot",
  "updated": "2026-11",
  "evidence_level": "B",
  "sources": [{ "id": "plat-spot-specsheet", "date": "2020-05", "evidence_level": "B" }],
  "limitations": ["height_m unpublished"],
  "score": 3
}
```

`family` is `null` for items without one; `evidence_level` is `null` for
editorial framework items (guides, taxonomy terms, methodology sections), the
case's own level for a case, and the strongest spec-source level for a
platform. `updated` is the dataset review month.

Ranking is lexical and deterministic: the same query returns the same order.
Per query token, the best matching field counts (title 3, keywords 2, summary
1.5, body 1; an exact token scores the weight, a prefix half), the sum is
scaled by the share of tokens matched, and the whole phrase adds 3 in the title
or 1 elsewhere. Ties break by type (platform, case_study, guide, taxonomy,
methodology), then id. Text is lower-cased and stripped of diacritics; Chinese
and Japanese are matched by character bigrams. `limitations` lists unpublished
or estimated fields and, for cases, unpublished metrics, payback and deployment
date — so an agent can say what is *not* known.

## Engines

### `POST /api/calculate/roi`

Body: the `RoiInputs` of `src/lib/roi.ts` in snake_case, every field optional.
Missing fields take the published defaults; `use_case` (`last-mile`,
`inspection`, `manipulation`, `security`) applies the matrix preset first, then
the caller's fields override it.

```json
{ "use_case": "inspection", "hourly_cost": 41, "fleet": { "quadruped": { "count": 3 } }, "horizon_months": 36 }
```

| Field | Bounds |
| --- | --- |
| `operators_per_shift` | integer 0–10 000 |
| `hourly_cost` | 0–10 000 |
| `shifts_per_day` | integer 1–24 |
| `hours_per_shift` | 1–24, and `shifts_per_day × hours_per_shift ≤ 24` |
| `days_per_year` | integer 1–366 |
| `error_rate_pct`, `uptime_pct` | 0–100 |
| `cost_per_incident` | 0–10 000 000 |
| `risk` | `low` · `medium` · `high` |
| `robots_per_supervisor` | 1–1 000 |
| `integration_cost` | 0–1 000 000 000 |
| `horizon_months` | integer 1–120 (default 36) |
| `fleet.{quadruped,humanoid,ugv,uav}.count` | integer 0–10 000 |
| `fleet.*.capex` | 0–100 000 000 |
| `fleet.*.maintenance_pct` | 0–100 |
| `fleet.*.software_per_year` | 0–10 000 000 |
| `fleet.*.hours_per_day` | 0–24 |

Numbers must be finite JSON numbers (strings, `NaN` and `Infinity` are
rejected). Money is in the single currency of the inputs (defaults in euros).

Returns:

- `model_version`, `discounting: "none"`, `use_case` (or `null`).
- `inputs` — the fully resolved inputs actually used (same shape as the body,
  every field present).
- `result` — `RoiResult` in snake_case: `horizon`, `manual_cumulative[]`,
  `robotic_cumulative[]` (month 0…horizon), `manual_monthly`,
  `robotic_monthly`, `upfront`, `payback_month` (fractional, or `null` if it
  does not pay back within the horizon), `manual_tco`, `robotic_tco`,
  `tco_reduction_pct`, `roi_pct`, `net_savings`, `robots`,
  `covered_hours_per_year`, `demand_hours_per_year`, `coverage_share_pct`,
  `supervisor_hours_per_year`, `manual_incidents_per_year`,
  `robotic_incidents_per_year`, `manual_operating_hours`,
  `hybrid_operating_hours`, `uptime_increase_pct`, `breakdown {manual {labor,
  incidents, risk_premium}, robotic {residual_labor, supervision, maintenance,
  software, incidents, risk_premium}}`. Unrounded: equal to `computeRoi`.
- `annual_savings` — manual minus robotic annual cost.
- `sensitivity` — `{delta_pct: 20, cap_months: 120, base_payback_months,
  rows [{driver, label, payback_minus_months, payback_plus_months,
  swing_months}]}`: payback when each driver (`hourly_cost`, `capex`,
  `coverage`, `integration`, `maintenance`, `uptime`) moves ±20 %, ranked by
  swing (capped at 120 months). A `null` payback means it never pays back.
- `assumptions` — every default with its evidence level and resolved sources:
  `[{key, label, default_value, evidence_level, sources}]`.
- `fields_to_validate` — `[{field, value, assumption, evidence_level: "D"}]`:
  the inputs the caller did not supply whose current value rests on a level-D
  default and that the user should replace with their own figures. Fleet
  fields are listed only for classes with at least one robot; values a preset
  set are listed under `assumption: "presets"`; `horizon_months` is a choice
  and never listed.
- `model_constants` (`robot_error_share`, `supervisor_premium`,
  `manual_effective_share`, `tasks_per_labor_hour`, `risk_factors`,
  `sensitivity_delta`), `warnings` (`no_robots`, `coverage_capped_by_demand`,
  `payback_beyond_horizon`, `never_pays_back`) and `notes` (`undiscounted`,
  `orientative`, `single_currency`), each `{code, message}`.

Orientative model, not a quote. There is no discounting: the model compares
undiscounted cumulative costs over the horizon, and the response says so.

### `POST /api/assess-fit`

The deployment guide's readiness assessment, executed:

```json
{
  "answers": { "infra-maps": "yes", "conn-cover": "no", "safety-risk": "partial" },
  "environment": "industrial",
  "sector": "inspection",
  "family": "quadruped"
}
```

`answers` maps readiness item ids (24, listed by
`GET /api/guides/deployment-guide` under `readiness.item_ids`) to `yes`,
`partial` or `no`; every field is optional. Weights yes 1, partial 0.5, no 0;
an unanswered item counts 0, exactly as on the page.

Returns `model_version`, `score` (0–100), `band` (`{id, min, label, text}`;
ids `exploration`, `controlled-pilot`, `ready-to-pilot`), `answered`,
`total_items`, `areas` (`[{id, name, score, answered, total}]`),
`weakest_area` (`{id, name, score}`, `null` until something is answered),
`unanswered` (item ids and texts — the data still missing), `blockers` (items
answered `no`) and `partial` (each `[{id, area, area_name, text}]`), `context`,
and the catalogue evidence that matches the context: `platforms`
(`PlatformSummary[]`) and `case_studies` (`CaseStudySummary[]`) filtered by
`environment` / `sector` / `family` (AND). Platforms are ordered by evidence
stage (operational → pilot → demonstration), case studies by deployment stage
(scaling → commercial → pilot → trial → retired), then slug; each has
`canonical_url`. `notes` state that the score is not a certification and that
the matches are not a recommendation. It never recommends a purchase.

### `POST /api/compare`

```json
{ "platforms": ["spot", "anymal-d"], "criteria": ["payload_kg", "runtime_min", "evidence_stage", "access"] }
```

2–5 distinct platforms. Criteria are spec keys plus `autonomy`, `coordination`,
`control`, `perception`, `environments`, `sectors`, `evidence_stage`,
`evidence_date`, `access`, `lifecycle`; omitted means all, in that order.

Returns `platforms [{id, slug, name, maker, family, canonical_url, api_url}]`,
`criteria`, `rows [{criterion, kind: "spec" | "profile", cells}]` and `notes`.
For every criterion and platform a cell gives:

```json
{ "platform": "digit", "value": 1.5, "label": null, "unit": "m/s", "status": "estimate", "provenance": "editorial_estimate", "conditions": null, "sources": [] }
```

Spec cells are the spec values above. Profile cells have `status:
"published"`, a localized `label`, and `provenance` `editorial_classification`
(autonomy, coordination, environments, sectors: this site's classification) or
`sheet` (control, perception, evidence stage and date, access, lifecycle: from
the platform sheet, with its sources; `conditions` holds the access or
lifecycle note). `notes` (`{code, message}`) always include `no_ranking`, plus
`maxima_not_simultaneous`, `estimates_are_editorial`,
`unpublished_is_unknown` and `editorial_classification` where they apply.
There is no ranking, winner or score: the comparison is a table of published
facts.

## Discovery

This document is served verbatim at
`https://physicalai.santismm.com/docs/api.md` (`text/markdown`); `GET /api`,
`/ai-index.json` and `/openapi.json` point to that URL. Every OpenAPI
operation has a stable camelCase `operationId` (`listPlatforms`,
`getPlatform`, `listSources`, `calculateRoi`, …) for function generation.

`/openapi.json` (OpenAPI 3.1) describes every endpoint above with typed request
and response schemas, error responses and examples, generated from the same
code (`src/lib/api/openapi.ts`); the test suite validates real responses
against it. `/ai-index.json` (an `api` block with every endpoint), `/llms.txt`,
`/llms-full.txt` and `/robots.txt` list the API next to the discovery files.

## Implementation notes

- `GET` reads with no filter and at most a valid `?locale=` are served from
  responses prerendered at build time, one per locale (and slug):
  `src/proxy.ts` rewrites them to `src/app/api/prerendered/[locale]/…`. Filters,
  search and the engines run on demand. Both paths call the same handlers
  (`src/lib/api/handlers.ts`), so the bytes are identical.
- `npm run test:api` checks serializers, engines, UI parity, validation and the
  OpenAPI schemas in-process; `npm run test:api:http` starts the production
  build and checks every endpoint over HTTP. Both run in CI.
