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 Cells In Bbox 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: Cells In Bbox
paths:
  /v1/cells_in_bbox:
    post:
      description: 'Enumerate every cell64 whose centre falls in a bounding box, paged, in stable row-major order (north row first, then west column first). Pure geometry: it reads no facts and signs no receipt, because the answer is a deterministic function of the bbox and the active grid that anyone can reproduce. It walks the integer lat/lng grid directly, so it never skips or double-counts a cell the way a float-stepped lattice does. Returns `cells`, the exact `total`, and `next_cursor` (null when exhausted). This is the paging loop as emem''s job instead of every client reimplementing a lattice; a London-scale AOI is tens of thousands of cells, so page it. page_size defaults 1024, caps at 4096.


        When to use: Call when you need the actual cell list over an area rather than a sample: building a world, a dense recall over an AOI, or a deterministic sample frame. Feed each page''s `cells` straight to emem_recall_many with a budget_ms to read them under the partial-results contract, and page with next_cursor until it is null. For a coarse sample (not every cell) emem_query_region or emem_recall_polygon subsample to max_cells instead.'
      operationId: emem_cells_in_bbox
      requestBody:
        content:
          application/json:
            schema:
              properties:
                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
                cursor:
                  description: row-major offset to resume from; use the previous response's next_cursor
                  minimum: 0
                  type: integer
                page_size:
                  default: 1024
                  maximum: 4096
                  minimum: 1
                  type: integer
              required:
              - bbox
              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
        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: enumerate the cell64s in a bounding box, paged (row-major, north row first).
      tags:
      - Cells In Bbox
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