{
  "openapi": "3.1.0",
  "info": {
    "title": "Butterfly Delta Verified Change Feed",
    "version": "1.0.0-test",
    "description": "A cursor-based, reconstructable record of verified changes, affected entities, possible consequences, invalidating evidence, and causal chains. All endpoints are free during product testing; the payment register is disabled."
  },
  "servers": [{ "url": "https://butterflydelta.com" }],
  "paths": {
    "/api/delta/head": {
      "get": {
        "operationId": "deltaHead",
        "summary": "Read the latest retained Delta cursor",
        "responses": { "200": { "description": "Current feed head and test-mode status" } }
      }
    },
    "/api/delta/changes-since": {
      "get": {
        "operationId": "deltaChangesSince",
        "summary": "Read verified changes after a cursor",
        "parameters": [
          { "name": "since", "in": "query", "schema": { "type": "string", "default": "delta:origin" } },
          { "name": "event_id", "in": "query", "schema": { "type": "array", "items": { "type": "string" } } },
          { "name": "category", "in": "query", "schema": { "type": "array", "items": { "type": "string" } } },
          { "name": "term", "in": "query", "schema": { "type": "array", "items": { "type": "string" } } },
          { "name": "place", "in": "query", "schema": { "type": "array", "items": { "type": "string" } } }
        ],
        "responses": { "200": { "description": "Change packets and a reconstructable response hash" } }
      },
      "post": {
        "operationId": "deltaChangesSincePost",
        "summary": "Read verified changes for a structured watchlist",
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangeRequest" } } }
        },
        "responses": { "200": { "description": "Change packets and next cursor" } }
      }
    },
    "/api/delta/impact": {
      "post": {
        "operationId": "deltaImpact",
        "summary": "Map relevant verified changes to ranked possible consequences",
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImpactRequest" } } }
        },
        "responses": { "200": { "description": "Relevant change packets, ranked consequences, and known unknowns" } }
      }
    },
    "/api/delta/chain": {
      "get": {
        "operationId": "deltaChain",
        "summary": "Inspect the evidence-bound upstream observations and downstream branches for one change",
        "parameters": [
          { "name": "change_id", "in": "query", "required": true, "schema": { "type": "string" } }
        ],
        "responses": { "200": { "description": "Causal chain with working weights and truth boundaries" } }
      }
    }
  },
  "components": {
    "schemas": {
      "Watchlist": {
        "type": "object",
        "properties": {
          "event_ids": { "type": "array", "items": { "type": "string" } },
          "categories": { "type": "array", "items": { "type": "string" } },
          "terms": { "type": "array", "items": { "type": "string" } },
          "places": { "type": "array", "items": { "type": "string" } }
        }
      },
      "ChangeRequest": {
        "type": "object",
        "required": ["since"],
        "properties": {
          "since": { "type": "string", "examples": ["delta:origin", "delta:4"] },
          "watchlist": { "$ref": "#/components/schemas/Watchlist" }
        }
      },
      "ImpactRequest": {
        "type": "object",
        "required": ["watchlist"],
        "properties": { "watchlist": { "$ref": "#/components/schemas/Watchlist" } }
      }
    }
  },
  "x-butterfly-delta": {
    "contract": "delta_verified_change_feed.v1",
    "test_mode": true,
    "payment_required": false,
    "register_enabled": false,
    "truth_boundary": "Working weights are inspectable judgments, not certainty or calibrated guarantees."
  }
}