emem Ask API

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 Ask 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: Ask
paths:
  /v1/ask:
    post:
      description: 'Single-shot free-text answer about a real-world location, backed by signed satellite/elevation/water/built-up receipts. Forwards a place mention plus a question; runs the locate → recall → algorithm chain server-side; returns one packaged envelope.


        When to use: Call when the question is about a specific place and the answer should carry its own evidence. Send the user''s question verbatim as `q` plus a location as `place` (free text), `cell` (cell64), or `lat`+`lng`. One envelope comes back: `answer`, `spatial_trace` (the readings as primitives, each point indexing `fact_cids`), `facts_summary`, `receipt` and `fact_cids` at the ROOT, and `caveats` naming grid resolution and revisit cadence. Missing bands are materialised on demand. `include: ["reasoning"]` adds the ordered stages with their detail; `include_image: true` bundles a Sentinel-2 thumbnail. A question outside the corpus answers `topic_routing.matched_topic: null` with the inventory, so you can route elsewhere rather than guess.'
      operationId: emem_ask
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AskReq'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AskResp'
          description: 'application/json envelope by default; text/event-stream of emem.ask_stage.v1 events when the request sends Accept: text/event-stream'
        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: single-shot free-text answer with signed evidence.
      tags:
      - Ask
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
    AskResp:
      description: Response of /v1/ask. Single envelope combining (a) place resolution, (b) topic-router classification, (c) recalled facts under those topics, (d) applicable algorithm recipes that compose those bands into named scores, (e) optional Sentinel-2 RGB thumbnail URL, and (f) caveats. All facts are signed and content-addressed.
      properties:
        algorithms_for_question:
          items:
            properties:
              formula:
                type: string
              key:
                type: string
              topic:
                type: string
            type: object
          type: array
        answer:
          description: Short natural-language summary of what the responder found, synthesised deterministically from the structured fields (every cited value traces to a fact_cid in the receipt). On a cold cell whose bands are not yet materialized it states that plainly and points at `next_steps`; never an LLM call.
          type: string
        answer_md:
          description: Markdown variant of `answer`.
          type: string
        caveats:
          items:
            type: string
          type: array
        facts:
          properties:
            bands_already_attested_at_cell:
              items:
                type: string
              type: array
            facts:
              items:
                $ref: '#/components/schemas/Fact'
              type: array
          type: object
        foundation_embeddings:
          description: Per-encoder neighbour lists and consensus voting. Populated when the intent matches `find places like` / `what changed`.
          type: object
        materialize_notes:
          items:
            $ref: '#/components/schemas/MaterializeNote'
          type: array
        next_steps:
          description: Present when the routed algorithms could not evaluate because their input bands are not materialized at this cell. Each item is a literal follow-up call (e.g. POST /v1/recall with the exact missing bands) the agent can issue, then re-ask.
          items:
            properties:
              action:
                type: string
              body:
                type: object
              method:
                type: string
              path:
                type: string
              url:
                type: string
              why:
                type: string
            type: object
          type: array
        place_resolved:
          $ref: '#/components/schemas/LocateResp'
        receipt:
          $ref: '#/components/schemas/Receipt'
        topic_routing:
          properties:
            matched_keywords:
              items:
                type: object
              type: array
            matched_topics:
              items:
                type: string
              type: array
            out_of_scope:
              type: boolean
            routing:
              type: object
          type: object
      required:
      - topic_routing
      - facts
      - receipt
      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
    LocateResp:
      description: Response of /v1/locate. `cell64` is the canonical handle for the resolved place; `polygon_bbox` is present when the geocoder found an extent (city / park / lake / country / region), absent for point features. `via` declares which layer of the seven-tier embedded cascade answered, falling back to network (Photon → Nominatim) only when no embedded layer matched.
      properties:
        cell64:
          $ref: '#/components/schemas/Cell64'
        data_at_this_cell:
          description: Topic-grouped inventory of recallable bands and applicable algorithms at this cell. Lets the caller chain into /v1/recall without a second introspection round-trip.
          type: object
        label:
          description: Reader-friendly place label.
          type: string
        lat:
          type: number
        lng:
          type: number
        localized_names:
          additionalProperties:
            type: string
          description: Map of ISO 639 language tag (`en`, `bn`, `zh-Hans`, `ar`, …) to localized name, when the resolved entity is in Overture and carries `names.common`. Lets an agent surface the user's-language label without a second geocoder call.
          type: object
        neighborhood_cells:
          description: Eight neighbouring cell64s of the resolved centre cell.
          items:
            $ref: '#/components/schemas/Cell64'
          type: array
        overture_division:
          description: Overture-divisions provenance, present when the cascade pulled an authoritative admin polygon. `division_id` is the GERS ID (globally stable, citable in receipts). `subtype` declares the admin level (country/region/county/locality/etc). `country` is the ISO 3166-1 alpha-2 owner.
          properties:
            country:
              description: ISO 3166-1 alpha-2 (e.g. `BD`, `US`).
              type: string
            division_id:
              type: string
            schema_url:
              type: string
            subtype:
              enum:
              - country
              - region
              - county
              - localadmin
              - locality
              - borough
              - macrohood
              - neighborhood
              - microhood
              - dependency
              type: string
          type: object
        polygon_bbox:
          description: Present when the place has spatial extent.
          properties:
            max_lat:
              type: number
            max_lng:
              type: number
            min_lat:
              type: number
            min_lng:
              type: number
            source:
              description: '`overture_division_area` is authoritative (conflated OSM+Esri+Meta+TomTom polygon), preferred whenever Overture has a row for the entity. `country_table` / `admin1_table` / `admin2_table` / `admin3_table` are cities1000-aggregated approximations used when Overture is unreachable. `wide_bbox_table` is the curated wide-feature override for Sahara/Amazon/Himalayas etc.'
              enum:
              - wide_bbox_table
              - country_table
              - admin1_table
              - admin2_table
              - admin3_table
              - nominatim_boundingbox
              - overture_division_area
              - centre_cell_bbox
              type: string
          type: object
        polygon_geojson:
          description: True OSM/Overture boundary as GeoJSON `Polygon` or `MultiPolygon` when an admin tier resolved. Pass back to /v1/recall_polygon to mask the cell grid against the boundary.
          type: object
        polygon_sample_cells:
          description: Up to 64 representative cells covering the polygon, pass to /v1/recall_many or /v1/recall_polygon.
          items:
            $ref: '#/components/schemas/Cell64'
          type: array
        via:
          description: Layer of the seven-tier locate cascade that answered. `country`/`admin1`/`admin2`/`admin3` = GeoNames hierarchical-admin tables (in-process); `embedded` = cities1000 populated places (in-process); `pois` = curated GeoNames well-known landmarks (peaks/lakes/parks/airports/monuments, in-process); `wide_bbox_table` = curated wide regions (in-process); `cache` = sled hot cache; `photon`/`nominatim` = network fallback.
          enum:
          - direct_latlng
          - wide_bbox_table
          - country
          - admin1
          - admin2
          - admin3
          - embedded
          - pois
          - cache
          - photon
          - nominatim
          type: string
      required:
      - cell64
      - via
      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
    AskReq:
      properties:
        cell:
          type: string
        include_image:
          default: false
          type: boolean
        lat:
          type: number
        lng:
          type: number
        model:
          description: Optional. Compose an extra prose answer with a named model, returned as `model_answer` BESIDE the deterministic `answer` rather than instead of it. `answer` never calls a model, so every number in it traces to a fact_cid; `model_answer` carries provenance.class = model_output. Name by base_model (nvidia/Cosmos3-Edge), by family (cosmos3_edge, gemma), or by any fragment that picks out exactly one of them (cosmos). A fragment matching several is refused and names them; an unroutable name is refused with the routable list; a routable model whose service is not answering is refused as busy or down, never substituted.
          type: string
        place:
          type: string
        q:
          type: string
        verbose:
          default: false
          description: When false (default), trim per-algorithm formulas + per-fact band_metadata + long _explanation prose so the response fits MCP's 25 KB cap. The signed receipt stays intact in either mode.
          type: boolean
      required:
      - q
      type: object
    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.<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