{
  "openapi": "3.1.0",
  "info": {
    "title": "Overa Agency Insights API",
    "version": "1.0.0",
    "description": "Private, tenant-scoped aggregate Insights API. Real collection and release are default-off."
  },
  "servers": [{ "url": "https://46.101.75.242" }],
  "security": [{ "backendBearer": [] }, { "staffSession": [] }],
  "paths": {
    "/api/insights/v1/integrations/{integrationId}/observations": {
      "post": {
        "summary": "Submit a bounded browser observation",
        "security": [
          { "visitorCapability": [] },
          { "backendBearer": ["insights:observe"] }
        ],
        "parameters": [{ "$ref": "#/components/parameters/IntegrationId" }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/Observation" }
            }
          }
        },
        "responses": {
          "202": { "$ref": "#/components/responses/Receipt" },
          "200": { "$ref": "#/components/responses/Receipt" },
          "4XX": { "$ref": "#/components/responses/Problem" }
        }
      }
    },
    "/api/insights/v1/integrations/{integrationId}/conversions": {
      "post": {
        "summary": "Submit a backend-confirmed conversion receipt",
        "security": [{ "backendBearer": ["insights:conversion-write"] }],
        "parameters": [{ "$ref": "#/components/parameters/IntegrationId" }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/Conversion" }
            }
          }
        },
        "responses": {
          "202": { "$ref": "#/components/responses/Receipt" },
          "200": { "$ref": "#/components/responses/Receipt" },
          "4XX": { "$ref": "#/components/responses/Problem" }
        }
      }
    },
    "/api/insights/v1/integrations/{integrationId}/reports/{surface}": {
      "get": {
        "summary": "Read one released report surface",
        "security": [
          { "backendBearer": ["insights:read"] },
          { "staffSession": ["insights:read"] }
        ],
        "parameters": [
          { "$ref": "#/components/parameters/IntegrationId" },
          { "$ref": "#/components/parameters/Surface" },
          { "$ref": "#/components/parameters/Days" },
          { "$ref": "#/components/parameters/Limit" },
          { "$ref": "#/components/parameters/Cursor" },
          { "$ref": "#/components/parameters/Cells" },
          { "$ref": "#/components/parameters/PriceBands" },
          { "$ref": "#/components/parameters/BedroomBands" },
          { "$ref": "#/components/parameters/PropertyTypes" },
          { "$ref": "#/components/parameters/Outcomes" }
        ],
        "responses": {
          "200": {
            "description": "Released report",
            "headers": {
              "Cache-Control": { "schema": { "const": "private, no-store" } }
            },
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Report" }
              }
            }
          },
          "4XX": { "$ref": "#/components/responses/Problem" }
        }
      }
    },
    "/api/insights/v1/integrations/{integrationId}/exports/{surface}.csv": {
      "get": {
        "summary": "Export the same released report snapshot as bounded CSV",
        "security": [
          { "backendBearer": ["insights:export"] },
          { "staffSession": ["insights:export"] }
        ],
        "parameters": [
          { "$ref": "#/components/parameters/IntegrationId" },
          { "$ref": "#/components/parameters/Surface" },
          { "$ref": "#/components/parameters/Days" },
          { "$ref": "#/components/parameters/Cells" },
          { "$ref": "#/components/parameters/PriceBands" },
          { "$ref": "#/components/parameters/BedroomBands" },
          { "$ref": "#/components/parameters/PropertyTypes" },
          { "$ref": "#/components/parameters/Outcomes" }
        ],
        "responses": {
          "200": {
            "description": "Spreadsheet-safe CSV",
            "content": {
              "text/csv": { "schema": { "type": "string" } }
            }
          },
          "4XX": { "$ref": "#/components/responses/Problem" }
        }
      }
    },
    "/api/insights/v1/integrations/{integrationId}/policy": {
      "get": {
        "summary": "Read current scoped policy",
        "security": [{ "staffSession": ["insights:policy:read"] }],
        "parameters": [{ "$ref": "#/components/parameters/IntegrationId" }],
        "responses": {
          "200": {
            "description": "Policy",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Policy" }
              }
            }
          },
          "4XX": { "$ref": "#/components/responses/Problem" }
        }
      },
      "put": {
        "summary": "Update a scoped policy within current fixture or operator pilot authority",
        "security": [{ "staffSession": ["insights:policy:write"] }],
        "parameters": [{ "$ref": "#/components/parameters/IntegrationId" }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/PolicyUpdate" }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Policy",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Policy" }
              }
            }
          },
          "4XX": { "$ref": "#/components/responses/Problem" }
        }
      }
    },
    "/api/insights/v1/integrations/{integrationId}/data": {
      "delete": {
        "summary": "Delete scoped Insights data and disable collection/release",
        "security": [{ "staffSession": ["insights:policy:write"] }],
        "parameters": [{ "$ref": "#/components/parameters/IntegrationId" }],
        "responses": {
          "200": {
            "description": "Deletion receipt",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "required": ["deleted"],
                  "properties": {
                    "deleted": {
                      "type": "object",
                      "additionalProperties": { "type": "integer" }
                    }
                  }
                }
              }
            }
          },
          "4XX": { "$ref": "#/components/responses/Problem" }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "backendBearer": { "type": "http", "scheme": "bearer" },
      "staffSession": {
        "type": "apiKey",
        "in": "cookie",
        "name": "overa_staff"
      },
      "visitorCapability": {
        "type": "apiKey",
        "in": "header",
        "name": "X-Overa-Visitor"
      }
    },
    "parameters": {
      "IntegrationId": {
        "name": "integrationId",
        "in": "path",
        "required": true,
        "schema": { "type": "string", "pattern": "^[a-z][a-z0-9-]{0,63}$" }
      },
      "Surface": {
        "name": "surface",
        "in": "path",
        "required": true,
        "schema": {
          "type": "string",
          "enum": [
            "overview",
            "demand",
            "stock-gaps",
            "engagement",
            "conversions"
          ]
        }
      },
      "Days": {
        "name": "days",
        "in": "query",
        "schema": { "type": "integer", "enum": [7, 31], "default": 7 }
      },
      "Limit": {
        "name": "limit",
        "in": "query",
        "description": "Released rows per page.",
        "schema": {
          "type": "integer",
          "minimum": 1,
          "maximum": 5000,
          "default": 250
        }
      },
      "Cursor": {
        "name": "cursor",
        "in": "query",
        "description": "Opaque continuation bound to the same scope, snapshot, policy, normalized filters and page size.",
        "schema": { "type": "string", "pattern": "^page-[a-f0-9]{16,64}$" }
      },
      "Cells": {
        "name": "cells",
        "in": "query",
        "schema": {
          "type": "array",
          "maxItems": 32,
          "items": { "type": "string" }
        }
      },
      "PriceBands": {
        "name": "priceBands",
        "in": "query",
        "schema": {
          "type": "array",
          "maxItems": 32,
          "items": { "type": "string" }
        }
      },
      "BedroomBands": {
        "name": "bedroomBands",
        "in": "query",
        "schema": {
          "type": "array",
          "maxItems": 32,
          "items": { "type": "string" }
        }
      },
      "PropertyTypes": {
        "name": "propertyTypes",
        "in": "query",
        "schema": {
          "type": "array",
          "maxItems": 32,
          "items": { "type": "string" }
        }
      },
      "Outcomes": {
        "name": "outcomes",
        "in": "query",
        "schema": {
          "type": "array",
          "maxItems": 32,
          "items": { "type": "string" }
        }
      }
    },
    "schemas": {
      "Observation": {
        "type": "object",
        "additionalProperties": false,
        "required": ["schemaVersion", "eventId", "eventType", "occurredAt"],
        "properties": {
          "schemaVersion": { "const": "insights-observation-v1" },
          "eventId": { "type": "string", "maxLength": 128 },
          "eventType": {
            "enum": [
              "result_exposed",
              "detail_opened",
              "shortlist_added",
              "shortlist_removed",
              "comparison_opened",
              "listing_handoff"
            ]
          },
          "occurredAt": { "type": "string", "format": "date-time" },
          "sourceId": { "type": "string" },
          "sourceRevision": { "type": "string", "maxLength": 160 },
          "itemId": { "type": "string" },
          "evaluationId": { "type": "string" },
          "correlationId": { "type": "string" }
        }
      },
      "Conversion": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "schemaVersion",
          "externalEventId",
          "conversionType",
          "occurredAt"
        ],
        "properties": {
          "schemaVersion": { "const": "insights-conversion-v1" },
          "externalEventId": { "type": "string", "maxLength": 128 },
          "conversionType": {
            "enum": ["enquiry_confirmed", "viewing_request_confirmed"]
          },
          "occurredAt": { "type": "string", "format": "date-time" },
          "sourceId": { "type": "string" },
          "sourceRevision": { "type": "string", "maxLength": 160 },
          "itemId": { "type": "string" },
          "correlationId": { "type": "string" },
          "correctionOf": { "type": "string" }
        }
      },
      "ReportCoverage": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "observationStartedAt",
          "qualifiedSessionDays",
          "evaluations",
          "observationEvents",
          "confirmedConversions",
          "suppressionApplied",
          "excludedBeforeObservation"
        ],
        "properties": {
          "observationStartedAt": {
            "type": ["string", "null"],
            "format": "date-time"
          },
          "qualifiedSessionDays": { "type": ["integer", "null"], "minimum": 0 },
          "evaluations": {
            "type": "null",
            "description": "Evaluation-event histograms are internal diagnostics and are not released publicly."
          },
          "observationEvents": { "type": ["integer", "null"], "minimum": 0 },
          "confirmedConversions": { "type": ["integer", "null"], "minimum": 0 },
          "suppressionApplied": { "type": "boolean" },
          "excludedBeforeObservation": { "type": "boolean" }
        }
      },
      "Report": {
        "type": "object",
        "additionalProperties": true,
        "required": [
          "schemaVersion",
          "snapshotId",
          "integrationId",
          "surface",
          "status",
          "window",
          "metricVersion",
          "policyVersion",
          "geographyVersion",
          "coverage",
          "source",
          "release",
          "filters",
          "pagination",
          "rows"
        ],
        "properties": {
          "schemaVersion": { "const": "insights-report-v1" },
          "snapshotId": { "type": "string" },
          "integrationId": { "type": "string" },
          "surface": { "$ref": "#/components/parameters/Surface/schema" },
          "status": {
            "enum": ["ready", "empty", "suppressed", "partial", "unavailable"]
          },
          "rows": {
            "type": "array",
            "maxItems": 5000,
            "items": { "type": "object" }
          },
          "coverage": { "$ref": "#/components/schemas/ReportCoverage" },
          "filters": { "type": "object", "required": ["applied", "available"] },
          "pagination": {
            "type": "object",
            "additionalProperties": false,
            "required": ["limit", "returned", "complete", "nextCursor"],
            "properties": {
              "limit": { "type": "integer", "minimum": 1, "maximum": 5000 },
              "returned": { "type": "integer", "minimum": 0, "maximum": 5000 },
              "complete": { "type": "boolean" },
              "nextCursor": { "type": ["string", "null"] }
            }
          }
        }
      },
      "Policy": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "schemaVersion",
          "customerId",
          "integrationId",
          "synthetic",
          "collectionEnabled",
          "releaseEnabled",
          "policyVersion",
          "revision",
          "activation"
        ],
        "properties": {
          "schemaVersion": { "const": "insights-policy-state-v1" },
          "customerId": { "type": "string" },
          "integrationId": { "type": "string" },
          "synthetic": { "type": "boolean" },
          "collectionEnabled": { "type": "boolean" },
          "releaseEnabled": { "type": "boolean" },
          "minimumCohort": { "type": ["integer", "null"] },
          "policyVersion": { "type": "string" },
          "revision": { "type": "integer" },
          "observationStartedAt": { "type": ["string", "null"] },
          "updatedAt": { "type": ["string", "null"] },
          "activation": { "$ref": "#/components/schemas/PilotCapability" }
        }
      },
      "PilotOperationCapability": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "configured",
          "authorized",
          "active",
          "authorizationRevision",
          "validUntil",
          "eligibilityMode"
        ],
        "properties": {
          "configured": { "type": "boolean" },
          "authorized": { "type": "boolean" },
          "active": { "type": "boolean" },
          "authorizationRevision": { "type": ["integer", "null"] },
          "validUntil": { "type": ["string", "null"], "format": "date-time" },
          "eligibilityMode": {
            "type": ["string", "null"],
            "enum": ["not-required", null]
          }
        }
      },
      "PilotCapability": {
        "type": "object",
        "additionalProperties": false,
        "required": ["schemaVersion", "mode", "collection", "release"],
        "properties": {
          "schemaVersion": { "const": "insights-pilot-capability-v1" },
          "mode": { "enum": ["off", "isolated-synthetic", "real-pilot"] },
          "collection": {
            "$ref": "#/components/schemas/PilotOperationCapability"
          },
          "release": { "$ref": "#/components/schemas/PilotOperationCapability" }
        }
      },
      "PolicyUpdate": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "synthetic",
          "collectionEnabled",
          "releaseEnabled",
          "minimumCohort",
          "expectedRevision"
        ],
        "properties": {
          "synthetic": {
            "type": "boolean",
            "description": "False requires a matching, current operator pilot authorization for every enabled operation; the request cannot create that authority."
          },
          "collectionEnabled": { "type": "boolean" },
          "releaseEnabled": { "type": "boolean" },
          "minimumCohort": { "type": "integer", "minimum": 2, "maximum": 100 },
          "expectedRevision": { "type": "integer", "minimum": 0 }
        }
      },
      "Problem": {
        "type": "object",
        "required": ["code", "status", "title"],
        "properties": {
          "code": { "type": "string" },
          "status": { "type": "integer" },
          "title": { "type": "string" },
          "field": { "type": ["string", "null"] }
        }
      }
    },
    "responses": {
      "Receipt": {
        "description": "Accepted or idempotently replayed",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "required": ["accepted", "replayed"],
              "properties": {
                "accepted": { "type": "boolean" },
                "replayed": { "type": "boolean" }
              }
            }
          }
        }
      },
      "Problem": {
        "description": "Structured rejection",
        "content": {
          "application/problem+json": {
            "schema": { "$ref": "#/components/schemas/Problem" }
          },
          "application/json": {
            "schema": { "$ref": "#/components/schemas/Problem" }
          }
        }
      }
    }
  }
}