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 Compare Same Doy 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: Compare Same Doy
paths:
  /v1/compare_same_doy:
    post:
      description: 'Compare a band at the SAME day-of-year across several years, the honest way to measure year-over-year change on a seasonal band. For each year it finds the signed facts bracketing the target day-of-year and linearly interpolates to it, and EXCLUDES years that cannot be bracketed (with a typed reason) rather than extrapolating. This is the primitive the phenology advisory on emem_diff points at: comparing a seasonal band at two different days-of-year mixes phenology with real change (the ''4 prospered / 0 stressed'' trap), so comparing at one fixed DOY makes a year-over-year delta change rather than season. Interpolated values are model-derived, not directly signed; the bracketing fact_cids are recoverable via emem_trajectory.


        When to use: Call when the user wants a year-over-year comparison of a seasonal band (NDVI, LST, greenness) and cares that it is change, not season: ''is this field greener than last year'', ''compare the July vegetation across 2022-2025''. Pass the day-of-year and the list of years. For a raw two-date delta use emem_diff (and read its phenology block); for the full series use emem_trajectory. BRACKET WIDTH MATTERS: a year is excluded unless the record holds a sample on EACH side of the target day-of-year within that year, so the natural first attempt (a tight window around the date you care about) usually excludes most years. Measured against this responder, plus or minus 21 days failed to bracket at three cells; plus or minus 60 days bracketed reliably. Backfill that wide before comparing, and read the typed exclusion reason rather than the year count.'
      operationId: emem_compare_same_doy
      requestBody:
        content:
          application/json:
            schema:
              properties:
                band:
                  type: string
                cell:
                  description: cell64 or place name
                  type: string
                doy:
                  description: target day-of-year
                  maximum: 366
                  minimum: 1
                  type: integer
                lat:
                  type: number
                lng:
                  type: number
                place:
                  type: string
                years:
                  description: years to compare at that day-of-year
                  items:
                    type: integer
                  type: array
              required:
              - band
              - doy
              - years
              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: compare a band at the SAME day-of-year across years.
      tags:
      - Compare Same Doy
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