openapi: 3.2.0 info: description: emem is shared memory for AI agents working together in the real world. license: name: Apache-2.0 title: emem Boring API version: 2.4.0 x-emem-surface-asymmetry: memory_notes: MCP only reach_them_at: POST /mcp, method tools/call read_side_is_here: - /v1/memory/search - /v1/memory/sse - /memories/{path} tools: - emem_memory_create - emem_memory_view - emem_memory_delete - emem_memory_rename - emem_memory_str_replace - emem_memory_supersede why_not_here: These write the agent correspondence plane, which is prose and untrusted-by-declaration. It is deliberately not part of the REST fact surface, and the two planes are kept apart rather than merged for convenience. servers: - description: Hosted instance (HTTPS-only) url: https://emem.dev tags: - name: boring paths: /v1/agent_quickref: get: description: 'agent-targeted intent map: which endpoint to call for which user intent, with usage priority + trust language' operationId: emem_agent_quickref responses: '200': content: application/json: schema: type: object description: ok summary: 'agent-targeted intent map: which endpoint to call for which user intent, with…' tags: - boring /v1/air: get: description: 'Recall the signed Copernicus CAMS air-quality facts (PM2.5 + NO2 + O3) at a place''s cell64, attesting on a miss. Composes locate → recall → aggregate; each band carries a citeable fact_cid. When to use: Use when the user names a place and asks about air quality, pollution, or emissions exposure. CAMS is the European reanalysis, global coverage, ~0.4° native (resampled). For finer-grained urban PM2.5, pair with /v1/at-style stations data when available.' operationId: emem_air_get parameters: - in: query name: lat required: false schema: type: number - in: query name: lon required: false schema: type: number - in: query name: place required: false schema: type: string responses: '200': content: application/json: schema: $ref: '#/components/schemas/SignedResponse' description: ok summary: GET /v1/air?lat=&lon=, CAMS PM2.5 + NO2 + O3 + aerosol optical depth at 550 nm… tags: - boring post: description: 'Recall the signed Copernicus CAMS air-quality facts (PM2.5 + NO2 + O3) at a place''s cell64, attesting on a miss. Composes locate → recall → aggregate; each band carries a citeable fact_cid. When to use: Use when the user names a place and asks about air quality, pollution, or emissions exposure. CAMS is the European reanalysis, global coverage, ~0.4° native (resampled). For finer-grained urban PM2.5, pair with /v1/at-style stations data when available.' operationId: emem_air_post requestBody: content: application/json: schema: $ref: '#/components/schemas/BoringPostReq' required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/SignedResponse' description: ok default: content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' description: 'error, the emem.error.v1 envelope. Branch on the stable `code` (see GET /v1/errors), not the message. A malformed or missing-field request body returns `code: invalid_argument` with the offending field named in `message`.' summary: POST /v1/air {place|lat,lng} tags: - boring /v1/at: get: description: 'One-shot recall of the signed facts at a place''s cell64 (or lat/lng); each band carries a citeable fact_cid. Defaults to emem''s standard at-a-glance band set; pass `band` / `bands` to override. Polygon-resolved places stay at the centroid by default (`n_cells: 1`) to keep multi-band calls cheap; pass `n_cells: 2..=64` to fan out. When to use: Use when the user names a place and wants the standard situational readout (vegetation + elevation + landcover + recent weather) without picking bands. Polygon-aware: `place` that resolves to a polygon (park, lake, district) lands at the centroid unless `n_cells` widens it. For a single band, use the domain-specific shortcuts (emem_ndvi, emem_air, …) or emem_recall directly.' operationId: emem_at_get parameters: - in: query name: lat required: false schema: type: number - in: query name: lon required: false schema: type: number - in: query name: place required: false schema: type: string - in: query name: band required: false schema: description: e.g. indices.ndvi, soilgrids.soc_0_30cm, weather.temperature_2m type: string - in: query name: bands required: false schema: description: CSV of bands, applied alongside `band` type: string - in: query name: tslot required: false schema: type: integer responses: '200': content: application/json: schema: $ref: '#/components/schemas/SignedResponse' description: ok summary: GET /v1/at?lat=&lon=&band=, boring lat/lng lookup of any of the 101… tags: - boring post: description: 'One-shot recall of the signed facts at a place''s cell64 (or lat/lng); each band carries a citeable fact_cid. Defaults to emem''s standard at-a-glance band set; pass `band` / `bands` to override. Polygon-resolved places stay at the centroid by default (`n_cells: 1`) to keep multi-band calls cheap; pass `n_cells: 2..=64` to fan out. When to use: Use when the user names a place and wants the standard situational readout (vegetation + elevation + landcover + recent weather) without picking bands. Polygon-aware: `place` that resolves to a polygon (park, lake, district) lands at the centroid unless `n_cells` widens it. For a single band, use the domain-specific shortcuts (emem_ndvi, emem_air, …) or emem_recall directly.' operationId: emem_at_post requestBody: content: application/json: schema: $ref: '#/components/schemas/BoringPostReq' required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/SignedResponse' description: ok default: content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' description: 'error, the emem.error.v1 envelope. Branch on the stable `code` (see GET /v1/errors), not the message. A malformed or missing-field request body returns `code: invalid_argument` with the offending field named in `message`.' summary: POST /v1/at {place|lat,lng[,band|bands,tslot]} → multi-band at a point tags: - boring /v1/elevation: get: description: 'One-shot elevation answer that fuses Cop-DEM 30 m (land), GMRT (ocean topobathy), and ESA WorldCover (water mask) into a single signed scalar at a place or coordinate. Returns `elevation_m`, the source actually used, and a `coherence_note` when the two surfaces disagree at the coast. When to use: Use when the user asks ''how high is X'' or ''what''s the elevation at this lat/lng'' and you want the correct answer regardless of whether the cell is land, water, or coastline, the handler picks Cop-DEM for land and GMRT for water and surfaces the choice. Pass `place` (free text), `lat`+`lng`, OR `cell`. Otherwise, prefer emem_recall with `copdem30m.elevation_mean` / `gmrt.topobathy_mean` individually.' operationId: emem_elevation_get parameters: - in: query name: lat required: false schema: type: number - in: query name: lon required: false schema: type: number - in: query name: place required: false schema: type: string responses: '200': content: application/json: schema: $ref: '#/components/schemas/SignedResponse' description: ok summary: GET /v1/elevation?lat=&lon=, boring lat/lng lookup, returns Cop-DEM elevation… tags: - boring post: description: 'One-shot elevation answer that fuses Cop-DEM 30 m (land), GMRT (ocean topobathy), and ESA WorldCover (water mask) into a single signed scalar at a place or coordinate. Returns `elevation_m`, the source actually used, and a `coherence_note` when the two surfaces disagree at the coast. When to use: Use when the user asks ''how high is X'' or ''what''s the elevation at this lat/lng'' and you want the correct answer regardless of whether the cell is land, water, or coastline, the handler picks Cop-DEM for land and GMRT for water and surfaces the choice. Pass `place` (free text), `lat`+`lng`, OR `cell`. Otherwise, prefer emem_recall with `copdem30m.elevation_mean` / `gmrt.topobathy_mean` individually.' operationId: emem_elevation requestBody: content: application/json: schema: $ref: '#/components/schemas/ElevationPostReq' required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/SignedResponse' description: ok default: content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' description: 'error, the emem.error.v1 envelope. Branch on the stable `code` (see GET /v1/errors), not the message. A malformed or missing-field request body returns `code: invalid_argument` with the offending field named in `message`.' summary: POST /v1/elevation {place|lat,lng|cell64} → Cop-DEM elevation read-through tags: - boring /v1/forest: get: description: 'Recall the signed forest facts at a place''s cell64: Hansen Global Forest Change (tree cover 2000 baseline + year-of-loss) + ESA WorldCover 2021 land class, attested on a miss; each carries a citeable fact_cid. When to use: Use when the user asks about deforestation, canopy cover, forest loss, or wants a forest-vs-not classification. Hansen gives year-of-loss for any cell with disturbance since 2001; WorldCover gives the current land class.' operationId: emem_forest_get parameters: - in: query name: lat required: false schema: type: number - in: query name: lon required: false schema: type: number - in: query name: place required: false schema: type: string responses: '200': content: application/json: schema: $ref: '#/components/schemas/SignedResponse' description: ok summary: GET /v1/forest?lat=&lon=, Hansen tree_cover_2000 + loss_year + ESA WorldCover… tags: - boring post: description: 'Recall the signed forest facts at a place''s cell64: Hansen Global Forest Change (tree cover 2000 baseline + year-of-loss) + ESA WorldCover 2021 land class, attested on a miss; each carries a citeable fact_cid. When to use: Use when the user asks about deforestation, canopy cover, forest loss, or wants a forest-vs-not classification. Hansen gives year-of-loss for any cell with disturbance since 2001; WorldCover gives the current land class.' operationId: emem_forest_post requestBody: content: application/json: schema: $ref: '#/components/schemas/BoringPostReq' required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/SignedResponse' description: ok default: content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' description: 'error, the emem.error.v1 envelope. Branch on the stable `code` (see GET /v1/errors), not the message. A malformed or missing-field request body returns `code: invalid_argument` with the offending field named in `message`.' summary: POST /v1/forest {place|lat,lng} tags: - boring /v1/lst: get: description: 'Recall the signed MODIS land surface temperature facts (day-8day + night-8day composites, 1 km native) at a place''s cell64, attesting on a miss; each carries a citeable fact_cid. When to use: Use when the user asks about surface heat, urban heat island, thermal anomalies, or wants day/night LST. Returns both fluxes so the agent can derive day–night spread.' operationId: emem_lst_get parameters: - in: query name: lat required: false schema: type: number - in: query name: lon required: false schema: type: number - in: query name: place required: false schema: type: string responses: '200': content: application/json: schema: $ref: '#/components/schemas/SignedResponse' description: ok summary: GET /v1/lst?lat=&lon=, MODIS LST day + night 8-day composite (signed). tags: - boring post: description: 'Recall the signed MODIS land surface temperature facts (day-8day + night-8day composites, 1 km native) at a place''s cell64, attesting on a miss; each carries a citeable fact_cid. When to use: Use when the user asks about surface heat, urban heat island, thermal anomalies, or wants day/night LST. Returns both fluxes so the agent can derive day–night spread.' operationId: emem_lst_post requestBody: content: application/json: schema: $ref: '#/components/schemas/BoringPostReq' required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/SignedResponse' description: ok default: content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' description: 'error, the emem.error.v1 envelope. Branch on the stable `code` (see GET /v1/errors), not the message. A malformed or missing-field request body returns `code: invalid_argument` with the offending field named in `message`.' summary: POST /v1/lst {place|lat,lng} tags: - boring /v1/ndvi: get: description: 'Recall the signed Sentinel-2 NDVI fact (indices.ndvi, 10 m native) at a place''s canonical cell64, attesting it into the shared memory on a miss. Composes locate → cell64 → recall in one call; the value returns with its citeable fact_cid. When to use: Use when the user names a place (or lat/lng) and just wants the NDVI number. Polygon-resolved places default to a 16-cell fan-out aggregated as mean/median. Set `n_cells: 1` for point behaviour. For multi-band batches use emem_recall.' operationId: emem_ndvi_get parameters: - in: query name: lat required: false schema: type: number - in: query name: lon required: false schema: type: number - in: query name: place required: false schema: type: string responses: '200': content: application/json: schema: $ref: '#/components/schemas/SignedResponse' description: ok summary: GET /v1/ndvi?lat=&lon=, Sentinel-2 NDVI at a point (signed). tags: - boring post: description: 'Recall the signed Sentinel-2 NDVI fact (indices.ndvi, 10 m native) at a place''s canonical cell64, attesting it into the shared memory on a miss. Composes locate → cell64 → recall in one call; the value returns with its citeable fact_cid. When to use: Use when the user names a place (or lat/lng) and just wants the NDVI number. Polygon-resolved places default to a 16-cell fan-out aggregated as mean/median. Set `n_cells: 1` for point behaviour. For multi-band batches use emem_recall.' operationId: emem_ndvi_post requestBody: content: application/json: schema: $ref: '#/components/schemas/BoringPostReq' required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/SignedResponse' description: ok default: content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' description: 'error, the emem.error.v1 envelope. Branch on the stable `code` (see GET /v1/errors), not the message. A malformed or missing-field request body returns `code: invalid_argument` with the offending field named in `message`.' summary: POST /v1/ndvi {place|lat,lng} tags: - boring /v1/soil: get: description: 'Recall the signed SoilGrids 250 m profile at a place''s cell64 (SOC, pH, clay/sand/silt fractions, bulk density, nitrogen, all at 0–30 cm depth), attesting on a miss; each band carries a citeable fact_cid. When to use: Use when the user asks about soil quality, agricultural suitability, or carbon stocks at a location. Six bands returned in one envelope.' operationId: emem_soil_get parameters: - in: query name: lat required: false schema: type: number - in: query name: lon required: false schema: type: number - in: query name: place required: false schema: type: string responses: '200': content: application/json: schema: $ref: '#/components/schemas/SignedResponse' description: ok summary: GET /v1/soil?lat=&lon=, SoilGrids 2.0 0–30 cm topsoil pack (SOC, pH, clay… tags: - boring post: description: 'Recall the signed SoilGrids 250 m profile at a place''s cell64 (SOC, pH, clay/sand/silt fractions, bulk density, nitrogen, all at 0–30 cm depth), attesting on a miss; each band carries a citeable fact_cid. When to use: Use when the user asks about soil quality, agricultural suitability, or carbon stocks at a location. Six bands returned in one envelope.' operationId: emem_soil_post requestBody: content: application/json: schema: $ref: '#/components/schemas/BoringPostReq' required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/SignedResponse' description: ok default: content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' description: 'error, the emem.error.v1 envelope. Branch on the stable `code` (see GET /v1/errors), not the message. A malformed or missing-field request body returns `code: invalid_argument` with the offending field named in `message`.' summary: POST /v1/soil {place|lat,lng} tags: - boring /v1/water: get: description: 'Recall the signed surface-water facts at a place''s cell64: JRC Global Surface Water recurrence (1984–2021) + Sentinel-1 SAR backscatter (current), attested on a miss and citeable by fact_cid. The pair detects standing water through clouds. When to use: Use when the user asks about flooding, wetlands, surface-water dynamics, or wants a robust water-presence check. JRC alone gives historical baseline; Sentinel-1 gives current flood detection.' operationId: emem_water_get parameters: - in: query name: lat required: false schema: type: number - in: query name: lon required: false schema: type: number - in: query name: place required: false schema: type: string responses: '200': content: application/json: schema: $ref: '#/components/schemas/SignedResponse' description: ok summary: GET /v1/water?lat=&lon=, JRC Global Surface Water recurrence + Sentinel-1 VV… tags: - boring post: description: 'Recall the signed surface-water facts at a place''s cell64: JRC Global Surface Water recurrence (1984–2021) + Sentinel-1 SAR backscatter (current), attested on a miss and citeable by fact_cid. The pair detects standing water through clouds. When to use: Use when the user asks about flooding, wetlands, surface-water dynamics, or wants a robust water-presence check. JRC alone gives historical baseline; Sentinel-1 gives current flood detection.' operationId: emem_water_post requestBody: content: application/json: schema: $ref: '#/components/schemas/BoringPostReq' required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/SignedResponse' description: ok default: content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' description: 'error, the emem.error.v1 envelope. Branch on the stable `code` (see GET /v1/errors), not the message. A malformed or missing-field request body returns `code: invalid_argument` with the offending field named in `message`.' summary: POST /v1/water {place|lat,lng} tags: - boring /v1/weather: get: description: 'Recall the signed met.no/CAMS weather facts at a place''s cell64 (2 m temperature + total cloud cover + precipitation + 10 m wind speed), attesting on a miss; each value carries a citeable fact_cid. When to use: Use when the user names a place and asks ''what''s the weather'' or wants a now-cast snapshot. weather.* bands are now-only (no backfill); for climatology use terraclimate.*.' operationId: emem_weather_get parameters: - in: query name: lat required: false schema: type: number - in: query name: lon required: false schema: type: number - in: query name: place required: false schema: type: string responses: '200': content: application/json: schema: $ref: '#/components/schemas/SignedResponse' description: ok summary: GET /v1/weather?lat=&lon=, met.no nowcast (t2m + precip + wind + RH) (signed). tags: - boring post: description: 'Recall the signed met.no/CAMS weather facts at a place''s cell64 (2 m temperature + total cloud cover + precipitation + 10 m wind speed), attesting on a miss; each value carries a citeable fact_cid. When to use: Use when the user names a place and asks ''what''s the weather'' or wants a now-cast snapshot. weather.* bands are now-only (no backfill); for climatology use terraclimate.*.' operationId: emem_weather_post requestBody: content: application/json: schema: $ref: '#/components/schemas/BoringPostReq' required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/SignedResponse' description: ok default: content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' description: 'error, the emem.error.v1 envelope. Branch on the stable `code` (see GET /v1/errors), not the message. A malformed or missing-field request body returns `code: invalid_argument` with the offending field named in `message`.' summary: POST /v1/weather {place|lat,lng} tags: - boring components: schemas: Cost: description: 'Self-declared cost block on every receipt. Honest accounting: latencies are observed, freshness is the age of the stalest source cited (null when undatable, never 0 as a stand-in), `was_cached` is true when the hot cache served the read.' properties: credits: description: Conceptual cost units; 0 for L0/L1 read endpoints on the hosted responder. type: number latency_p50_ms: type: number latency_p99_ms: type: number source_freshness_s: description: 'Age of the STALEST source this response cites: now minus the earliest captured_at across the returned facts'' sources. null when nothing in the response carries a dated source, which is the honest answer for a primitive that reads no observation. Was a hardcoded 0 until 2026-08-05, so a 2021 DEM tile reported as 0 s old; a null here means unknown, never fresh.' type: - integer - 'null' was_cached: type: boolean type: object Fact: description: A primary attestation at (cell, band, tslot). `value` is the band's typed reading (number, array of numbers for vector bands, or a categorical class id). `unit` is the band's declared unit (e.g. `m_msl`, `degC`, `mm`). properties: absence_reason: description: Present only when kind=`absence`. enum: - unavailable_capability - outside_coverage - archetype_seed_unavailable - gpu_unavailable - upstream_error - upstream_timeout type: string band: type: string cell: $ref: '#/components/schemas/Cell64' fact_cid: $ref: '#/components/schemas/FactCid' kind: description: '`primary` = signed measurement; `absence` = signed "we don''t have this here" with a typed reason.' enum: - primary - absence type: string provenance: description: Upstream source key (e.g. `copdem30m`, `s2_l2a`, `cams_eu`). type: string receipt: $ref: '#/components/schemas/Receipt' tslot: $ref: '#/components/schemas/Tslot' unit: type: string value: description: Number, array of numbers, or class id depending on band type. required: - kind - cell - band - tslot - value - fact_cid - receipt type: object MaterializeNote: description: 'One entry in the response''s `materialize_notes[]`, recording what the lazy materializer did during this call. status:"materialized" means a signed fact was minted and persisted (a Primary observation OR a confirmed, evidence-backed Absence - both are signed and citeable by fact_cid). status:"skipped" means nothing was signed: `reason_class` says why (transient `timeout`/`upstream_error`, retryable; or structural `unknown_band`/`no_materializer`/`capability_unavailable`, not retryable here) and `absence` is always false, because a skip is ''unknown'', never a confirmed absence.' properties: absence: description: Always false on a skip; a confirmed absence is a signed fact with status:materialized, not a skip. type: boolean band: type: string cell: $ref: '#/components/schemas/Cell64' fact_cid: type: string latency_ms: type: number ok: type: boolean reason: type: string reason_class: enum: - timeout - upstream_error - unknown_band - no_materializer - capability_unavailable type: string retryable: type: boolean status: enum: - materialized - skipped type: string type: object ErrorEnvelope: description: The `emem.error.v1` failure envelope returned by every endpoint on a 4xx/5xx. Branch on the stable `code` (not the human `message`). See GET /v1/errors for the full code catalog. properties: code: description: Stable machine-readable error code. One of the codes in GET /v1/errors. example: invalid_argument type: string details: description: Optional structured recovery hints; present on errors that ship machine-readable next-steps. type: object message: description: Human-readable detail. For invalid_argument this names the offending field (e.g. "missing field `q`"). type: string path: description: Request path that produced the error. example: /v1/ask type: string schema: const: emem.error.v1 type: string required: - code - message - schema type: object PubKey: description: Ed25519 32-byte public key, base32-nopad-lowercase encoded (52 chars). Returned in receipts and `/.well-known/emem.json`. example: 777er3yihgifqmv5hmc2wwmyszgddzderzhsx6rex4yoakwomvka type: string Cell64: description: 'cell64 wire form: four base-65,536 bigrams separated by dots, e.g. `defi.zb4d9.pefa.zf619`. Encoded resolution is ~9.55 m at the equator. Each bigram is either a CVCV quad, consonant `[bcdfghjklmnpqrstvwxyz]` followed by vowel `[aeiouAEIOU]` repeated twice, OR a synthetic 5-char `z[0-9a-f]{4}` slot used for the unused pad cells in the 65,536-entry alphabet. The regex pin matches `pattern` below byte-for-byte and is also surfaced under `Cell64Pattern` so agents can validate before sending.' example: defi.zb4d9.pefa.zf619 maxLength: 23 minLength: 19 pattern: ^(?:(?:[bcdfghjklmnpqrstvwxyz][aeiouAEIOU]){2}|z[0-9a-f]{4})(?:\.(?:(?:[bcdfghjklmnpqrstvwxyz][aeiouAEIOU]){2}|z[0-9a-f]{4})){3}$ type: string ElevationPostReq: description: 'Body for POST /v1/elevation. Supply `place` OR `lat`+`lng` (`lon` accepted as an alias) OR `cell64`. Deliberately NOT BoringPostReq: this route reads a narrower type and hardcodes band / bands / tslot / n_cells to None, so those four knobs are not offered here.' properties: cell: description: Alias for `cell64`. type: string cell64: type: string lat: type: number lng: type: number lon: description: Alias for `lng`. type: number name: description: Alias for `place`. type: string place: type: string q: description: Alias for `place`. type: string query: description: Alias for `place`. type: string type: object BoringPostReq: description: 'Body for POST /v1/{ndvi,air,lst,soil,water,forest,weather,at,elevation}. Supply `place` (free-text geocoded via /v1/locate) OR `lat`+`lng` (or `lon`); /v1/at and /v1/elevation also accept optional `band`/`bands`/`tslot` and `cell64` respectively. When `place` resolves to an OSM feature with extent (airport, park, lake, region) the response includes a `polygon` block + per-band `stats` (mean/median/min/max/std for numeric bands, mode + class distribution for categorical bands like esa_worldcover.lc_2021); pass `n_cells: 1` to force point behaviour at the centroid instead. Single-band endpoints default to 16 sample cells when polygon detected; /v1/at defaults to 1 (multi-band × multi-cell explodes upstream fetch count). Use POST /v1/recall_polygon for raw per-cell facts.' properties: band: description: Single band key (used by /v1/at). type: string bands: description: CSV of band keys (used by /v1/at). type: string lat: type: number lng: type: number lon: description: Alias for `lng`. type: number n_cells: description: 'Polygon-aggregation knob. When `place` resolves to a feature with extent and `n_cells` is unset, single-band endpoints fan out to 16 sample cells; /v1/at defaults to 1. `n_cells: 1` forces point behaviour at the centroid; values in 2..=64 are honoured. Anything else returns 400, heavy queries belong on POST /v1/recall_polygon.' maximum: 64 minimum: 1 type: integer name: description: Alias for `place`. type: string place: description: Free-text place name; resolved via embedded gazetteer → cache → Photon → Nominatim. type: string q: description: Alias for `place`. type: string query: description: Alias for `place`. type: string tslot: type: integer type: object SignedResponse: description: Standard recall envelope. `facts` is the array of signed facts touched by this call (subset of `bands_already_attested_at_cell` after auto-materialization). `receipt` is the responder's signature over the call. `materialize_notes` lists any lazy-materializer activity that happened to satisfy the request, empty for purely warm reads. properties: bands_already_attested_at_cell: description: Bands the cell already has facts for, regardless of whether they were requested. Useful for follow-up calls without a second /v1/coverage_matrix hit. items: type: string type: array caveats: description: Plain-language constraints the caller should fold into their answer (grid resolution, revisit cadence, sample-size warnings). items: type: string type: array facts: items: $ref: '#/components/schemas/Fact' type: array materialize_notes: items: $ref: '#/components/schemas/MaterializeNote' type: array receipt: $ref: '#/components/schemas/Receipt' required: - facts - receipt type: object FactCid: description: 'Content id of a fact: base32-nopad-lowercase encoding of `blake3(canonical_cbor(fact))`, the FULL 32-byte digest with no truncation. Always 52 characters, alphabet `[a-z2-7]`. A cid of any other length is a damaged citation, not a shorter address: /v1/memory_token/resolve rejects it as `fact_cid_malformed_length` rather than guessing. Note that `entity_cid` and `bundle_cid` are NOT this shape; both truncate to 16 bytes (26 characters) and hash an identity anchor or a citation list rather than a complete body.' example: qtv2bco56qw4pmlohk56dotoxyl3atmnjpmzrijj2kazw2mj57oq maxLength: 52 minLength: 52 pattern: ^[a-z2-7]{52}$ type: string Tslot: description: Band-tempo-relative integer offset from the emem epoch. Each band declares its tempo (`fast` / `medium` / `slow` / `static`); tslot is the rounded count of that tempo's unit since the epoch. minimum: 0 type: integer Receipt: description: 'Ed25519-signed receipt. The browser-side verifier at /verify reconstructs the preimage from the receipt fields alone, no callback to the issuer. **A receipt is byte-for-byte or nothing.** Current receipts carry `preimage_version: 2`, whose preimage binds request_id, served_at, primitive, cells, fact_cids AND, when present, the scope / as_of / edges / source_versions / field digests and the `merkle_proof` segment. Reshaping a receipt — dropping a field an SDK considers redundant, re-keying it, summarising it, round-tripping it through a lossy model — invalidates the signature BY DESIGN, and the result is indistinguishable on the wire from tampering. Store and forward the responder''s exact bytes. POST /v1/verify_receipt names which of the two it is where it can prove the difference (`reason: receipt_reshaped_after_signing` with a `failure_detail`). What is NOT signed: the caller''s `place`/`q` string, raw `lat`/`lng`, requested `bands[]`, requested `tslot`, and `intent` — a wrong-place geocode produces a valid signature for the wrong cell. Branch on /v1/locate `selected.is_high_confidence` before trusting place-anchored answers. Also: `fact_cid` is per-replica (signed_at differs across responders even for byte-identical upstream pixels); cross-replica join key is the tuple (cell, band, tslot). /v1/recall_polygon emits one independently signed receipt per cell under `by_cell..receipt`, `merged_facts[]` is convenience flattening and is NOT covered by an aggregate signature.' properties: cells: items: $ref: '#/components/schemas/Cell64' type: array cost: $ref: '#/components/schemas/Cost' fact_cids: items: $ref: '#/components/schemas/FactCid' type: array intent: description: Optional natural-language hint. Populated when served via /v1/intent. type: string merkle_proof: description: 'Inclusion proof for `fact_cids[0]` when persisted. Omitted from JSON when the cited facts pre-date the proof tree; under preimage_version 2 that absence is itself signed (an explicit ABSENT marker), so it is a statement rather than a gap. Do not strip this field: v2 binds it into the signature and removing it makes an authentic receipt report `signature_valid: false`.' properties: leaf_index: description: u32 leaf index in the canonical-sorted batch. type: integer path: description: Sibling hashes leaf→root. items: description: 32-byte sibling hash as a byte array items: type: integer type: array type: array root: description: The expected 32-byte batch root as a byte array. items: type: integer type: array version: description: 'Merkle hashing rule: 0 (omitted) = legacy unprefixed, 1 = RFC 6962-style prefixed.' type: integer required: - leaf_index - path - root type: object primitive: description: 'Namespaced wire form: `emem.recall`, `emem.find_similar`, `emem.verify`, …' type: string registry_cid: description: CID of the function registry version in force. type: string request_id: description: ULID generated per request. type: string responder: $ref: '#/components/schemas/PubKey' responder_key_epoch: description: u32 rotation counter; bumps when the operator rotates keys. type: integer responder_pubkey_b32: $ref: '#/components/schemas/PubKey' schema_cid: description: CID of the active CDDL profile. type: string served_at: description: ISO 8601 UTC, second precision. type: string signature: description: Ed25519 signature, 64 bytes base32-nopad-lowercase encoded. type: string source_versions: additionalProperties: type: string description: Per-source freshness map. type: object required: - request_id - served_at - primitive - cells - fact_cids - schema_cid - responder - responder_key_epoch - responder_pubkey_b32 - signature - registry_cid type: object