REST API v0.1

Base URL https://api.sizeguide.ai. No key is required for the reference charts during v0.1. Requests and responses are JSON. Lengths are integer millimetres everywhere; unit conversion is a presentation concern and happens only at the edge of the engine.

Route	What it does	State
GET /health	Engine version and number of published charts.	live
POST /v1/recommend	Body measurements in, size recommendation or an honest decline out.	live
POST /v1/convert	Table-driven size conversion with provenance riding along.	live
GET /v1/charts/:slug	A published chart version: rows, semantic, provenance, version number.	live
MCP · mcp.sizeguide.ai	recommend_size, convert_size, get_size_chart, explain_fit as native agent tools.	live
API keys	Scoped read access to private charts via Authorization: Bearer. Issued by hand.	live
Schema · /developers/schema/	The typed contract as JSON Schema draft 2020-12, six documents.	live
Merchant chart ingestion	Your own chart graph behind your key.	planned

AuthenticationAuthorization: Bearer

Reference charts (the demo/ set and the verified blanks corpus) are public and need no key: every example on this page works as written. Any other chart slug requires a key, sent as a standard bearer header. A missing or invalid key returns 401, a key not scoped to that slug returns 403, both in the standard error envelope with engineVersion.

curl https://api.sizeguide.ai/v1/charts/your/private/chart \
  -H 'Authorization: Bearer sg_live_...'

Keys are issued by hand, scoped to named charts, and stored only as hashes: request one via contact. There is no self-serve signup on purpose. The MCP server passes your bearer header through unchanged.

Schema/developers/schema/

The engine's typed contract is published as the Open Sizing Schema, v0.1: six JSON Schema documents (draft 2020-12) generated from the code they describe, so the two cannot drift. Charts, recommendation request and response, conversion request and response, and the error envelope, each with a stable $id under /schema/v0.1/. Every golden vector, every served chart, and the live responses on this page validate against them in the build gates. Subject to change until 1.0.

HealthGET /health

curl https://api.sizeguide.ai/health

{ "ok": true, "engineVersion": "0.1.0", "charts": 1 }

RecommendPOST /v1/recommend

chart is a published chart slug and defaults to demo/tshirts/us-mens. input.measurements is required and may be empty: with no measurements the engine returns chart-level guidance instead of inventing a size.

curl -X POST https://api.sizeguide.ai/v1/recommend \
  -H 'Content-Type: application/json' \
  -d '{
    "chart": "demo/tshirts/us-mens",
    "input": { "measurements": [
      { "slug": "chest_body", "value": 1003,
        "variance": 0, "source": "self_reported" }
    ] }
  }'

A recommendation carries kind: "recommendation", the size label, a confidence value with its band, per-zone fit, an alternative when the shopper sits between sizes, and the chart block naming the slug, version number, and provenance tier the answer was computed from. Out-of-range or under-specified input returns kind: "guidance" with the reason. The engine does not guess.

Field	Meaning
slug	Measurement definition, for example chest_body, waist_body, height.
value	Integer millimetres.
variance	Known measurement uncertainty in mm. Widens the confidence band; never narrows it.
source	self_reported or estimated. Estimated inputs can never yield a high band.

ConvertPOST /v1/convert

Conversions are table-driven, never formulaic. Send a value and the table to convert against; the response names the table's provenance. A value outside the table's bounds returns a decline rather than an interpolated guess.

ChartsGET /v1/charts/:slug

curl https://api.sizeguide.ai/v1/charts/demo/tshirts/us-mens

Returns the current published version of a chart: its rows, the row semantic (body or garment), units, provenance tier, version number, and content hash. Chart versions are immutable; a corrected chart is a new version, and every logged recommendation names the version it used.

Errors

Non-2xx responses are { "error": "...", "engineVersion": "0.1.0" }. 400 for malformed input, 404 for an unpublished chart slug or unknown route.