Documentation

{
  "research": "1.1", "composition": "1.1", "engine": "0.1", "api": "v1",
  "supports": { "compose": true, "compose_bulk": true, "lookup": true, "search": true,
                "explain": true, "validate": true, "health": true, "pairing": false },
  "explain_levels": ["minimal","standard","debug"],
  "search_kinds": ["descriptor","mechanism","identity","grape","region","style","alias","canonical_id"],
  "async": { "supported": false, "ready": true }
}

The contract does not scope error codes per endpoint (API_CONTRACT_v1.md:90-92, :100-110 define one global typed-error taxonomy and HTTP-status mapping, not a per-endpoint list). Shown below is that global taxonomy; which subset a given endpoint can actually raise is not stated in the contract, so none is asserted here beyond it.

{
  "snapshot_id": "sha256:…",
  "handle": "[email protected]/1.1",
  "identity": "Barolo",
  "version": { "research":"1.1","composition":"1.1","engine":"0.1","api":"v1" },
  "profile": {
    "descriptors": [ { "descriptor":"tar","confidence":0.9,"dominant_mechanism":"varietal_aroma" } ],
    "axes": { "acidity": {"value":0.8}, ... },
    "confidence": { "final":0.85 },
    "warnings": [],
    "is_blend": false,
    "vintage_available": false,
    "bottle_evolution_available": false
  }
}

Contract's own example truncates `axes` with `...`; not filled in here to avoid fabricating a shape the contract doesn't give. `snapshot_id = sha256(identity + version triple + args + resolved profile)` (API_CONTRACT_v1.md:48).

The contract does not scope error codes per endpoint (API_CONTRACT_v1.md:90-92, :100-110 define one global typed-error taxonomy and HTTP-status mapping, not a per-endpoint list). Shown below is that global taxonomy; which subset a given endpoint can actually raise is not stated in the contract, so none is asserted here beyond it.

{
  "mode": "sync",
  "job": null,
  "count": 200,
  "results": [ { "ok": true, "snapshot_id":"…", "identity":"…", "profile":{…} },
               { "ok": false, "identity":"Xyz", "error":"UnknownIdentity" } ]
}

Async-ready: when async lands, `mode:"async"` + `job:{id,status,poll_url}` and `results:null` until ready — same envelope, no client break (API_CONTRACT_v1.md:61-62).

The contract does not scope error codes per endpoint (API_CONTRACT_v1.md:90-92, :100-110 define one global typed-error taxonomy and HTTP-status mapping, not a per-endpoint list). Shown below is that global taxonomy; which subset a given endpoint can actually raise is not stated in the contract, so none is asserted here beyond it. Note the response envelope's own per-item `error` field (e.g. "UnknownIdentity") reuses the global taxonomy's codes (API_CONTRACT_v1.md:58).

{
  "snapshot_id": "sha256:…", "handle": "[email protected]/1.1", "identity": "Barolo",
  "version": { "research":"1.1","composition":"1.1","engine":"0.1","api":"v1" },
  "profile": { "descriptors":[...], "axes":{...}, "confidence":{"final":0.85}, "warnings":[],
               "is_blend": false, "vintage_available": false, "bottle_evolution_available": false }
}

"(no vintage/bottle args)" (API_CONTRACT_v1.md:64) scopes the REQUEST, not the response — the contract states the response is identical to POST /compose's.

The contract does not scope error codes per endpoint (API_CONTRACT_v1.md:90-92, :100-110 define one global typed-error taxonomy and HTTP-status mapping, not a per-endpoint list). Shown below is that global taxonomy; which subset a given endpoint can actually raise is not stated in the contract, so none is asserted here beyond it.

{ "query":"oxidative","kind":null,"version":{…},
  "results": { "descriptors":{…}, "identities":[…], "by_style":{…} },
  "match_count": 3 }

The contract itself abbreviates nested fields with `{…}`/`[…]` — not filled in here to avoid fabricating structure the contract doesn't provide.

The contract does not scope error codes per endpoint (API_CONTRACT_v1.md:90-92, :100-110 define one global typed-error taxonomy and HTTP-status mapping, not a per-endpoint list). Shown below is that global taxonomy; which subset a given endpoint can actually raise is not stated in the contract, so none is asserted here beyond it.

{ "descriptor": "tar", "dominant_mechanism": "varietal_aroma", "confidence": 0.9 }

The contract gives no JSON example for /explain, only prose per level (API_CONTRACT_v1.md:76-78): minimal = {descriptor, dominant_mechanism, confidence}; standard = minimal + supporting_mechanisms and an evidence summary; debug = full mechanism graph (paths, suppressed duplicates, disagreement). This illustrative example covers only the minimal shape using field names the contract states; standard/debug are not JSON-ized here since the contract gives no field-level shape for either.

The contract does not scope error codes per endpoint (API_CONTRACT_v1.md:90-92, :100-110 define one global typed-error taxonomy and HTTP-status mapping, not a per-endpoint list). Shown below is that global taxonomy; which subset a given endpoint can actually raise is not stated in the contract, so none is asserted here beyond it.

{ "ok": true, "errors": [], "version": { "research":"1.1","composition":"1.1","engine":"0.1","api":"v1" } }

Contract states the shape as prose (`{ok, errors[], version}`, API_CONTRACT_v1.md:81) but gives no JSON example and does not state what strings populate `errors[]` on a failed validation.

This endpoint's own `errors[]` response field (API_CONTRACT_v1.md:81) is a generic array whose contents the contract does not specify — it is not stated to reuse the global typed-error taxonomy below. The contract does not scope error codes per endpoint (API_CONTRACT_v1.md:90-92, :100-110 define one global typed-error taxonomy and HTTP-status mapping, not a per-endpoint list). Shown below is that global taxonomy; which subset a given endpoint can actually raise is not stated in the contract, so none is asserted here beyond it.

{ "status": "ready",
  "version": { "research":"1.1","composition":"1.1","engine":"0.1","api":"v1" },
  "registry": { "loaded": true, "identities": 125, "registries": 1, "caps": {} },
  "cache": {}, "tests": { "composition": "pass", "cross_layer_audit": "pass", "integration": "pass", "golden": "pass" } }

Contract states the field list as prose (API_CONTRACT_v1.md:85-86), not a JSON example. Field names are transcribed as given; nested value shapes (`registry.identities` count, `cache`/`tests` contents) are illustrative placeholders, not contract-stated values.

Explicitly stated in contract, unlike other endpoints: returns HTTP 200 when ready, 503 when not ready; readiness = knowledge+registries+golden+active bundle (API_CONTRACT_v1.md:110). The contract does not scope error codes per endpoint (API_CONTRACT_v1.md:90-92, :100-110 define one global typed-error taxonomy and HTTP-status mapping, not a per-endpoint list). Shown below is that global taxonomy; which subset a given endpoint can actually raise is not stated in the contract, so none is asserted here beyond it.