{
  "openapi": "3.1.0",
  "info": {
    "title": "BizHedge Kalshi Demand Intelligence API",
    "version": "1.1.0",
    "summary": "Grouped Demand evidence for partner market design",
    "description": "The API returns modeled gaps plus customer evidence released only in scheduled cohorts of five. Customer counts and dates remain unchanged between releases; release dates are Monday 00:00 UTC publication buckets, never member-event times. Weekly trend rows are sums of append-only +5 releases. Raw owner input, notes, identifiers, addresses and traces are excluded. This is the first safe v1 sync generation: complete a full gaps snapshot and retain its terminal opaque checkpoint before calling changes.",
    "contact": { "name": "BizHedge" },
    "x-versioning-policy": "Breaking contract changes use a new URL version. Additive fields may be introduced within v1 after documentation. A deprecated version receives at least 90 days notice through the partner change process."
  },
  "servers": [{ "url": "https://bizhedge.app" }],
  "security": [{ "PartnerBearer": [] }],
  "paths": {
    "/api/partner/v1/health": {
      "get": {
        "operationId": "getPartnerDemandHealth",
        "summary": "Check partner API and Demand view availability",
        "responses": {
          "200": { "$ref": "#/components/responses/Health" },
          "304": { "$ref": "#/components/responses/NotModified" },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "409": { "$ref": "#/components/responses/SyncRequired" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "429": { "$ref": "#/components/responses/RateLimited" },
          "503": { "$ref": "#/components/responses/Unavailable" }
        }
      }
    },
    "/api/partner/v1/demand/summary": {
      "get": {
        "operationId": "getDemandSummary",
        "summary": "Get grouped Demand totals and request trend",
        "description": "Record totals apply from/to to each current public record's last_seen timestamp. request_trend independently applies the same inclusive timestamps to immutable scheduled cohort release buckets (Monday 00:00 UTC), so a historical release remains in its window after the record later advances. Exact timestamp boundaries are honored; a Monday 00:00 bucket is excluded by from=MondayT12:00:00Z.",
        "parameters": [
          { "$ref": "#/components/parameters/RiskType" },
          { "$ref": "#/components/parameters/EvidenceClass" },
          { "$ref": "#/components/parameters/BusinessSegment" },
          { "$ref": "#/components/parameters/CoarseGeography" },
          { "$ref": "#/components/parameters/From" },
          { "$ref": "#/components/parameters/To" }
        ],
        "responses": {
          "200": { "$ref": "#/components/responses/Summary" },
          "304": { "$ref": "#/components/responses/NotModified" },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "409": { "$ref": "#/components/responses/SyncRequired" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "429": { "$ref": "#/components/responses/RateLimited" },
          "503": { "$ref": "#/components/responses/Unavailable" }
        }
      }
    },
    "/api/partner/v1/demand/gaps": {
      "get": {
        "operationId": "listDemandGaps",
        "summary": "List stable partner-safe Demand records",
        "parameters": [
          { "$ref": "#/components/parameters/RiskType" },
          { "$ref": "#/components/parameters/EvidenceClass" },
          { "$ref": "#/components/parameters/BusinessSegment" },
          { "$ref": "#/components/parameters/CoarseGeography" },
          { "$ref": "#/components/parameters/From" },
          { "$ref": "#/components/parameters/To" },
          { "$ref": "#/components/parameters/PageSize" },
          { "$ref": "#/components/parameters/Cursor" }
        ],
        "responses": {
          "200": { "$ref": "#/components/responses/GapList" },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "409": { "$ref": "#/components/responses/SyncRequired" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "429": { "$ref": "#/components/responses/RateLimited" },
          "503": { "$ref": "#/components/responses/Unavailable" }
        }
      }
    },
    "/api/partner/v1/demand/gaps/{id}": {
      "get": {
        "operationId": "getDemandGap",
        "summary": "Get one partner-safe Demand record",
        "parameters": [{ "$ref": "#/components/parameters/DemandId" }],
        "responses": {
          "200": { "$ref": "#/components/responses/GapDetail" },
          "304": { "$ref": "#/components/responses/NotModified" },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "409": { "$ref": "#/components/responses/SyncRequired" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "404": { "$ref": "#/components/responses/NotFound" },
          "429": { "$ref": "#/components/responses/RateLimited" },
          "503": { "$ref": "#/components/responses/Unavailable" }
        }
      }
    },
    "/api/partner/v1/demand/changes": {
      "get": {
        "operationId": "listDemandChanges",
        "summary": "Pull stable incremental Demand changes",
        "description": "Date-window filters are intentionally unsupported because window membership is defined by the current public row snapshot. To change a date window, discard incremental state, fetch a new complete /gaps snapshot with from/to, and retain its terminal checkpoint. A 409 response likewise requires this full-resync recovery.",
        "parameters": [
          { "$ref": "#/components/parameters/RiskType" },
          { "$ref": "#/components/parameters/EvidenceClass" },
          { "$ref": "#/components/parameters/BusinessSegment" },
          { "$ref": "#/components/parameters/CoarseGeography" },
          { "$ref": "#/components/parameters/PageSize" },
          { "$ref": "#/components/parameters/Cursor" }
        ],
        "responses": {
          "200": { "$ref": "#/components/responses/ChangeList" },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "409": { "$ref": "#/components/responses/SyncRequired" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "429": { "$ref": "#/components/responses/RateLimited" },
          "503": { "$ref": "#/components/responses/Unavailable" }
        }
      }
    },
    "/api/partner/v1/demand/taxonomy": {
      "get": {
        "operationId": "getDemandTaxonomy",
        "summary": "Get v1 bounded Demand taxonomies",
        "responses": {
          "200": { "$ref": "#/components/responses/Taxonomy" },
          "304": { "$ref": "#/components/responses/NotModified" },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "409": { "$ref": "#/components/responses/SyncRequired" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "429": { "$ref": "#/components/responses/RateLimited" },
          "503": { "$ref": "#/components/responses/Unavailable" }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "PartnerBearer": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "opaque scoped token",
        "description": "Use the dedicated Kalshi Demand token. Query string credentials are rejected."
      }
    },
    "parameters": {
      "DemandId": {
        "name": "id",
        "in": "path",
        "required": true,
        "schema": { "type": "string", "format": "uuid" }
      },
      "RiskType": {
        "name": "risk_type",
        "in": "query",
        "schema": { "$ref": "#/components/schemas/RiskType" }
      },
      "EvidenceClass": {
        "name": "evidence_class",
        "in": "query",
        "schema": { "$ref": "#/components/schemas/EvidenceClass" }
      },
      "BusinessSegment": {
        "name": "business_segment",
        "in": "query",
        "schema": { "$ref": "#/components/schemas/BusinessSegment" }
      },
      "CoarseGeography": {
        "name": "coarse_geography",
        "in": "query",
        "schema": { "$ref": "#/components/schemas/CoarseGeography" }
      },
      "From": {
        "name": "from",
        "in": "query",
        "description": "Inclusive UTC timestamp. For gaps and summary totals this filters current public last_seen; for summary request_trend it independently filters the immutable Monday 00:00 UTC release bucket using the full timestamp.",
        "schema": { "type": "string", "format": "date-time" }
      },
      "To": {
        "name": "to",
        "in": "query",
        "description": "Inclusive UTC timestamp. For gaps and summary totals this filters current public last_seen; for summary request_trend it independently filters the immutable Monday 00:00 UTC release bucket using the full timestamp.",
        "schema": { "type": "string", "format": "date-time" }
      },
      "PageSize": {
        "name": "page_size",
        "in": "query",
        "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 }
      },
      "Cursor": {
        "name": "cursor",
        "in": "query",
        "description": "Opaque cursor returned by the same resource",
        "schema": { "type": "string", "maxLength": 700 }
      }
    },
    "schemas": {
      "RiskType": {
        "type": "string",
        "enum": [
          "input_cost_energy",
          "input_cost_food_ag",
          "input_cost_metals_materials",
          "input_cost_technology",
          "ops_disruption_weather",
          "demand_macro",
          "demand_local_event",
          "financing_rates",
          "fx_import_export",
          "promo_marketing",
          "idiosyncratic_supplier",
          "regulatory_policy_cost",
          "equity_market",
          "crypto_price",
          "election_outcome",
          "unmapped"
        ]
      },
      "EvidenceClass": {
        "type": "string",
        "enum": ["modeled_gap", "observed_gap", "explicit_request"]
      },
      "CustomerEvidenceClass": {
        "type": "string",
        "enum": ["observed_gap", "explicit_request"]
      },
      "BusinessSegment": {
        "type": "string",
        "enum": [
          "food_hospitality",
          "retail",
          "construction_trades",
          "manufacturing",
          "agriculture",
          "transport_logistics",
          "professional_services",
          "technology_crypto",
          "sports_promotion",
          "other",
          "unspecified"
        ]
      },
      "CoarseGeography": {
        "type": "string",
        "enum": [
          "us_national",
          "us_northeast",
          "us_south",
          "us_midwest",
          "us_west",
          "non_us",
          "multi_region",
          "unspecified"
        ]
      },
      "HarmDirection": {
        "type": "string",
        "enum": [
          "cost_up",
          "revenue_down",
          "availability_down",
          "rate_up",
          "price_down",
          "price_up",
          "event_occurs",
          "event_does_not_occur",
          "two_sided",
          "unspecified"
        ]
      },
      "TimeHorizon": {
        "type": "string",
        "enum": [
          "days_0_30",
          "days_31_90",
          "months_4_12",
          "over_12_months",
          "unspecified"
        ]
      },
      "AtRiskAmountBand": {
        "type": "string",
        "enum": [
          "under_10k",
          "10k_49k",
          "50k_249k",
          "250k_999k",
          "1m_plus",
          "unspecified"
        ]
      },
      "Count": {
        "type": "object",
        "additionalProperties": false,
        "description": "A modeled-evidence total over visible cells.",
        "required": ["count", "suppressed"],
        "properties": {
          "count": { "type": "integer", "minimum": 0 },
          "suppressed": { "const": false }
        }
      },
      "CustomerCount": {
        "type": "object",
        "additionalProperties": false,
        "description": "A customer-evidence total. Zero means no published cohort; positive totals are released only in groups of five.",
        "required": ["count", "suppressed"],
        "properties": {
          "count": {
            "oneOf": [
              { "const": 0 },
              { "type": "integer", "minimum": 5, "multipleOf": 5 }
            ]
          },
          "suppressed": { "const": false }
        }
      },
      "Freshness": {
        "type": "object",
        "additionalProperties": false,
        "required": ["as_of", "status"],
        "properties": {
          "as_of": { "type": ["string", "null"], "format": "date-time" },
          "status": { "type": "string", "enum": ["current", "stale", "no_data"] },
          "age_seconds": { "type": "integer", "minimum": 0 }
        }
      },
      "Meta": {
        "type": "object",
        "additionalProperties": false,
        "required": ["public_generation"],
        "properties": {
          "public_generation": { "type": "integer", "minimum": 0, "description": "Public ledger high-water used to detect and retry mixed-generation reads. This is not a raw-event count or timestamp." },
          "generated_at": { "type": "string", "format": "date-time" },
          "freshness": { "$ref": "#/components/schemas/Freshness" },
          "privacy": {
            "type": "object",
            "additionalProperties": false,
            "required": ["minimum_group_size", "small_cell_behavior", "customer_count_unit", "customer_trend_behavior"],
            "properties": {
              "minimum_group_size": { "type": "integer", "minimum": 5 },
              "small_cell_behavior": { "const": "omitted" },
              "customer_count_unit": { "const": 5 },
              "customer_trend_behavior": { "const": "weekly_cohort_releases" }
            }
          },
          "pagination": {
            "type": "object",
            "additionalProperties": false,
            "required": ["page_size", "next_cursor"],
            "properties": {
              "page_size": { "type": "integer", "minimum": 1, "maximum": 100 },
              "next_cursor": { "type": ["string", "null"] }
            }
          },
          "sync": {
            "type": "object",
            "additionalProperties": false,
            "required": ["mode", "initial_sync", "checkpoint", "complete"],
            "properties": {
              "mode": { "type": "string", "enum": ["full_snapshot", "incremental"] },
              "initial_sync": { "const": "full_snapshot_required" },
              "checkpoint": { "type": ["string", "null"], "description": "Opaque durable terminal checkpoint. It encodes no timestamp, revision or count." },
              "complete": { "type": "boolean" }
            }
          },
          "rate_limit_mode": { "type": "string", "enum": ["durable", "instance"] }
        }
      },
      "DemandRecord": {
        "type": "object",
        "additionalProperties": false,
        "allOf": [
          {
            "oneOf": [
              {
                "type": "object",
                "required": ["evidence_class", "evidence_count"],
                "properties": {
                  "evidence_class": { "const": "modeled_gap" },
                  "evidence_count": { "type": "integer", "minimum": 0 }
                }
              },
              {
                "type": "object",
                "required": ["evidence_class", "evidence_count"],
                "properties": {
                  "evidence_class": { "$ref": "#/components/schemas/CustomerEvidenceClass" },
                  "evidence_count": { "type": "integer", "minimum": 5, "multipleOf": 5 }
                }
              }
            ]
          }
        ],
        "required": [
          "id",
          "evidence_class",
          "risk_type",
          "desired_business_outcome",
          "harm_direction",
          "time_horizon",
          "business_segment",
          "coarse_geography",
          "at_risk_amount_band",
          "closest_existing_series",
          "reason_no_fit",
          "proposed_contract_shape",
          "first_seen",
          "last_seen",
          "evidence_count",
          "count_suppressed",
          "source_version",
          "privacy_classification",
          "lifecycle_status",
          "changed_at"
        ],
        "properties": {
          "id": { "type": "string", "format": "uuid" },
          "evidence_class": { "$ref": "#/components/schemas/EvidenceClass" },
          "risk_type": { "$ref": "#/components/schemas/RiskType" },
          "desired_business_outcome": { "type": "string", "minLength": 3, "maxLength": 240 },
          "harm_direction": { "$ref": "#/components/schemas/HarmDirection" },
          "time_horizon": { "$ref": "#/components/schemas/TimeHorizon" },
          "business_segment": { "$ref": "#/components/schemas/BusinessSegment" },
          "coarse_geography": { "$ref": "#/components/schemas/CoarseGeography" },
          "at_risk_amount_band": {
            "oneOf": [
              { "$ref": "#/components/schemas/AtRiskAmountBand" },
              { "type": "null" }
            ]
          },
          "closest_existing_series": { "type": ["string", "null"], "maxLength": 240 },
          "reason_no_fit": { "type": "string", "minLength": 3, "maxLength": 500 },
          "proposed_contract_shape": { "type": "string", "minLength": 3, "maxLength": 600 },
          "first_seen": { "type": "string", "format": "date-time" },
          "last_seen": { "type": "string", "format": "date-time" },
          "evidence_count": { "type": "integer", "minimum": 0 },
          "count_suppressed": { "const": false },
          "source_version": { "type": "string", "maxLength": 120 },
          "privacy_classification": { "const": "partner_aggregate" },
          "lifecycle_status": { "type": "string", "enum": ["unmet", "candidate_found", "mapped", "resolved"] },
          "changed_at": { "type": "string", "format": "date-time" }
        }
      },
      "TrendRow": {
        "type": "object",
        "additionalProperties": false,
        "required": ["date", "evidence_class", "risk_type", "count", "suppressed"],
        "properties": {
          "date": { "type": "string", "format": "date" },
          "evidence_class": { "$ref": "#/components/schemas/CustomerEvidenceClass" },
          "risk_type": { "$ref": "#/components/schemas/RiskType" },
          "count": { "type": "integer", "minimum": 5, "multipleOf": 5 },
          "suppressed": { "const": false }
        }
      },
      "SummaryData": {
        "type": "object",
        "additionalProperties": false,
        "required": ["totals", "by_risk_type", "request_trend"],
        "properties": {
          "totals": {
            "type": "object",
            "additionalProperties": false,
            "required": ["modeled_gap", "observed_gap", "explicit_request"],
            "properties": {
              "modeled_gap": { "$ref": "#/components/schemas/Count" },
              "observed_gap": { "$ref": "#/components/schemas/CustomerCount" },
              "explicit_request": { "$ref": "#/components/schemas/CustomerCount" }
            }
          },
          "by_risk_type": {
            "type": "array",
            "maxItems": 16,
            "items": {
              "type": "object",
              "additionalProperties": false,
              "required": ["risk_type", "evidence"],
              "properties": {
                "risk_type": { "$ref": "#/components/schemas/RiskType" },
                "evidence": {
                  "type": "object",
                  "additionalProperties": false,
                  "required": ["modeled_gap", "observed_gap", "explicit_request"],
                  "properties": {
                    "modeled_gap": { "$ref": "#/components/schemas/Count" },
                    "observed_gap": { "$ref": "#/components/schemas/CustomerCount" },
                    "explicit_request": { "$ref": "#/components/schemas/CustomerCount" }
                  }
                }
              }
            }
          },
          "request_trend": {
            "type": "array",
            "maxItems": 5000,
            "items": { "$ref": "#/components/schemas/TrendRow" }
          }
        }
      },
      "TaxonomyOption": {
        "type": "object",
        "additionalProperties": false,
        "required": ["value", "label"],
        "properties": {
          "value": { "type": "string" },
          "label": { "type": "string" }
        }
      },
      "TaxonomyData": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "version",
          "source_version",
          "minimum_partner_group_size",
          "risk_types",
          "evidence_classes",
          "harm_directions",
          "time_horizons",
          "business_segments",
          "coarse_geographies",
          "at_risk_amount_bands",
          "lifecycle_statuses"
        ],
        "properties": {
          "version": { "const": 1 },
          "source_version": { "type": "string" },
          "minimum_partner_group_size": { "type": "integer", "minimum": 5 },
          "risk_types": { "type": "array", "items": { "$ref": "#/components/schemas/TaxonomyOption" } },
          "evidence_classes": { "type": "array", "items": { "$ref": "#/components/schemas/TaxonomyOption" } },
          "harm_directions": { "type": "array", "items": { "$ref": "#/components/schemas/TaxonomyOption" } },
          "time_horizons": { "type": "array", "items": { "$ref": "#/components/schemas/TaxonomyOption" } },
          "business_segments": { "type": "array", "items": { "$ref": "#/components/schemas/TaxonomyOption" } },
          "coarse_geographies": { "type": "array", "items": { "$ref": "#/components/schemas/TaxonomyOption" } },
          "at_risk_amount_bands": { "type": "array", "items": { "$ref": "#/components/schemas/TaxonomyOption" } },
          "lifecycle_statuses": { "type": "array", "items": { "$ref": "#/components/schemas/TaxonomyOption" } }
        }
      },
      "Error": {
        "type": "object",
        "additionalProperties": false,
        "required": ["code", "message"],
        "properties": {
          "code": { "type": "string" },
          "message": { "type": "string" }
        }
      },
      "ErrorEnvelope": {
        "type": "object",
        "additionalProperties": false,
        "required": ["api_version", "error"],
        "properties": {
          "api_version": { "const": "v1" },
          "error": { "$ref": "#/components/schemas/Error" }
        }
      }
    },
    "responses": {
      "Health": {
        "description": "Partner API is available",
        "headers": { "ETag": { "description": "Weak semantic validator over privacy-stable fields; volatile timestamps and opaque cursors are excluded.", "schema": { "type": "string" } } },
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "additionalProperties": false,
              "required": ["api_version", "data", "meta"],
              "properties": {
                "api_version": { "const": "v1" },
                "data": {
                  "type": "object",
                  "additionalProperties": false,
                  "required": ["status", "schema_version", "checked_at", "record_view_available"],
                  "properties": {
                    "status": { "const": "ok" },
                    "schema_version": { "type": "string" },
                    "checked_at": { "type": "string", "format": "date-time" },
                    "record_view_available": { "type": "boolean" }
                  }
                },
                "meta": { "$ref": "#/components/schemas/Meta" }
              }
            }
          }
        }
      },
      "Summary": {
        "description": "Grouped Demand summary over visible cells only. Small observed and explicit cells are absent and do not contribute to totals.",
        "headers": { "ETag": { "description": "Weak semantic validator over privacy-stable fields; volatile timestamps and opaque cursors are excluded.", "schema": { "type": "string" } } },
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "additionalProperties": false,
              "required": ["api_version", "data", "meta"],
              "properties": {
                "api_version": { "const": "v1" },
                "data": { "$ref": "#/components/schemas/SummaryData" },
                "meta": { "$ref": "#/components/schemas/Meta" }
              }
            },
            "examples": {
              "zeroExplicitRequests": {
                "externalValue": "/docs/partner-demand-v1.summary.sample.json"
              }
            }
          }
        }
      },
      "GapList": {
        "description": "Stable Demand record page. Observed and explicit cells below five are absent.",
        "headers": { "ETag": { "description": "Weak semantic validator over privacy-stable fields; volatile timestamps and opaque cursors are excluded.", "schema": { "type": "string" } } },
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "additionalProperties": false,
              "required": ["api_version", "data", "meta"],
              "properties": {
                "api_version": { "const": "v1" },
                "data": { "type": "array", "maxItems": 100, "items": { "$ref": "#/components/schemas/DemandRecord" } },
                "meta": { "$ref": "#/components/schemas/Meta" }
              }
            }
          }
        }
      },
      "GapDetail": {
        "description": "One visible Demand record. An identifier for a small observed or explicit cell returns the same 404 as a missing record.",
        "headers": { "ETag": { "description": "Weak semantic validator over privacy-stable fields; volatile timestamps and opaque cursors are excluded.", "schema": { "type": "string" } } },
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "additionalProperties": false,
              "required": ["api_version", "data", "meta"],
              "properties": {
                "api_version": { "const": "v1" },
                "data": { "$ref": "#/components/schemas/DemandRecord" },
                "meta": { "$ref": "#/components/schemas/Meta" }
              }
            }
          }
        }
      },
      "ChangeList": {
        "description": "Stable incremental change page. Small observed and explicit cells produce no change item.",
        "headers": { "ETag": { "description": "Weak semantic validator over privacy-stable fields; volatile timestamps and opaque cursors are excluded.", "schema": { "type": "string" } } },
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "additionalProperties": false,
              "required": ["api_version", "data", "meta"],
              "properties": {
                "api_version": { "const": "v1" },
                "data": {
                  "type": "array",
                  "maxItems": 100,
                  "items": {
                    "oneOf": [
                      {
                        "type": "object",
                        "additionalProperties": false,
                        "required": ["change_type", "record"],
                        "properties": {
                          "change_type": { "const": "upsert" },
                          "record": { "$ref": "#/components/schemas/DemandRecord" }
                        }
                      },
                      {
                        "type": "object",
                        "additionalProperties": false,
                        "required": ["change_type", "id", "evidence_class", "risk_type", "business_segment", "coarse_geography", "cohort_count", "cohort_delta", "release_week", "record_url"],
                        "properties": {
                          "change_type": { "const": "cohort_release" },
                          "id": { "type": "string", "format": "uuid" },
                          "evidence_class": { "$ref": "#/components/schemas/CustomerEvidenceClass" },
                          "risk_type": { "$ref": "#/components/schemas/RiskType" },
                          "business_segment": { "$ref": "#/components/schemas/BusinessSegment" },
                          "coarse_geography": { "$ref": "#/components/schemas/CoarseGeography" },
                          "cohort_count": { "type": "integer", "minimum": 5, "multipleOf": 5 },
                          "cohort_delta": { "const": 5 },
                          "release_week": { "type": "string", "format": "date-time" },
                          "record_url": { "type": "string", "pattern": "^/api/partner/v1/demand/gaps/" }
                        }
                      },
                      {
                        "type": "object",
                        "additionalProperties": false,
                        "required": ["change_type", "id"],
                        "properties": {
                          "change_type": { "const": "tombstone" },
                          "id": { "type": "string", "format": "uuid" }
                        }
                      }
                    ]
                  }
                },
                "meta": { "$ref": "#/components/schemas/Meta" }
              }
            },
            "examples": {
              "incrementalPull": {
                "externalValue": "/docs/partner-demand-v1.changes.sample.json"
              }
            }
          }
        }
      },
      "Taxonomy": {
        "description": "Bounded v1 taxonomy",
        "headers": { "ETag": { "description": "Weak semantic validator over privacy-stable fields; volatile timestamps and opaque cursors are excluded.", "schema": { "type": "string" } } },
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "additionalProperties": false,
              "required": ["api_version", "data", "meta"],
              "properties": {
                "api_version": { "const": "v1" },
                "data": { "$ref": "#/components/schemas/TaxonomyData" },
                "meta": { "$ref": "#/components/schemas/Meta" }
              }
            }
          }
        }
      },
      "NotModified": { "description": "The weak semantic ETag matches under weak comparison. Response has no body." },
      "BadRequest": {
        "description": "Invalid parameter or cursor",
        "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }
      },
      "SyncRequired": {
        "description": "A full initial sync or reset is required before incremental pulls can continue.",
        "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }
      },
      "Unauthorized": {
        "description": "Missing or invalid scoped bearer token",
        "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }
      },
      "NotFound": {
        "description": "Demand record does not exist",
        "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }
      },
      "RateLimited": {
        "description": "Request limit reached",
        "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }
      },
      "Unavailable": {
        "description": "Partner Demand service is temporarily unavailable",
        "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }
      }
    }
  }
}