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 Band Raster 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: Band Raster
paths:
  /v1/band_raster:
    post:
      description: 'Return a native-resolution Sentinel-2 window over a bounding box as a FIELD, not a set of points: the pixels become one content-addressed grid artifact (deterministic f32 encoding; fetch the bytes at the returned artifact url, Cache-Control immutable), and what the receipt attests is the DERIVATION, never a byte pipe. A persisted derivation record pins the chosen scene (id, asset, capture time, cloud cover), the recipe (band_raster@1), the grid georeferencing in the scene''s UTM CRS, and best-effort per-cell anchors that bridge the artifact to existing signed facts; the receipt''s FIELD preimage segment binds (aoi_cid, derivation_cid), reported by /v1/verify_receipt as field_bound. Bounds are refusals with the cap named: six raw S2 bands (B02/B03/B04/B08/B11/B12) and 512 px per side at native resolution (about 5.1 km at 10 m). Anchors never materialize a fact, so a cold AOI costs one scene read, nothing more. The artifact is evictable BY DESIGN: the record persists like any fact and pins everything needed to rebuild identical bytes, so eviction turns a dereference into a recompute, never a broken citation. Returns two tokens: emem:raster: (resolve with emem_raster_resolve) and the record''s own emem:fact: handle. This signs and persists the derivation record. TERRAIN: pass band `copdem30m.elevation` (or `elevation` / `dem`) for a static Copernicus GLO-30 elevation field via the dem_raster@1 path, no scene selection, no cloud, EPSG:4326 grid; a bbox crossing a 1-degree DEM tile edge is refused (single-tile only) and open ocean has no tile. EMBEDDING (WB-5): pass an encoder band (geotessera etc.) for a MULTI-CHANNEL embedding field via embedding_raster@1, a signed N-D vector per cell (geotessera = 128-D) packed into one artifact, so a client-side per-cell embedding fan-out becomes one citeable token; every filled cell is anchored to its real signed encoder fact; grid capped at 256 cells at the 0.1-degree native step.


        When to use: Call when an agent needs an area''s actual field of values rather than per-cell scalars: change analysis over a scene window, input to a model that reads grids, exporting verifiable pixels a third party can re-derive, or a terrain/elevation field (band copdem30m.elevation). For one cell''s value use emem_recall; for an RGB visual use emem_cell_scene_rgb, which is a view, not a signed artifact; for areas beyond the 512 px cap, page the bbox.'
      operationId: emem_band_raster
      requestBody:
        content:
          application/json:
            schema:
              properties:
                band:
                  description: s2.B02|s2.B03|s2.B04|s2.B08|s2.B11|s2.B12
                  type: string
                bbox:
                  properties:
                    max_lat:
                      type: number
                    max_lng:
                      type: number
                    min_lat:
                      type: number
                    min_lng:
                      type: number
                  required:
                  - min_lat
                  - min_lng
                  - max_lat
                  - max_lng
                  type: object
                observed_on:
                  description: optional target capture date YYYY-MM-DD; the chosen scene is pinned either way
                  type: string
              required:
              - bbox
              - band
              type: object
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
          description: ok
        '400':
          content:
            application/json:
              schema:
                properties:
                  details:
                    type: object
                  error:
                    type: string
                type: object
          description: invalid argument; `details.code` names which rule refused
        '502':
          description: upstream scene fetch failed; typed
        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: 'a field as a signed derivation (docs/plans/field-tokens.md): native-resolution…'
      tags:
      - Band Raster
components:
  schemas:
    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