{
  "openapi": "3.1.0",
  "info": {
    "title": "Overa managed experience API",
    "version": "1.2.0",
    "description": "The implemented managed API. Hosted Overa, separate-origin embeds and confidential backend clients consume these same operations. Browser capabilities are memory-held and integration scoped; backend and preview credentials are confidential. Provider-bearing requests are not automatically replayed after cancellation or authority failure. Evidence references are caller-, integration-, revision- and lifetime-bound. Unknown outcomes are represented in versioned evaluation/comparison payloads rather than coerced to matches. Evaluation and assessed-comparison payloads name the canonical travel decision policy independently from the provider evidence algorithm version."
  },
  "servers": [
    {
      "url": "https://46.101.75.242/api/managed/v1/integrations/{integrationId}",
      "variables": {
        "integrationId": {
          "default": "managed-customer-a-property",
          "description": "Operator-issued managed integration identifier."
        }
      }
    }
  ],
  "tags": [
    { "name": "sessions" },
    { "name": "profile" },
    { "name": "naming" },
    { "name": "decisions" },
    { "name": "street-level" },
    { "name": "inputs" }
  ],
  "paths": {
    "/presentation": {
      "get": {
        "operationId": "getManagedPresentation",
        "tags": ["profile"],
        "summary": "Read current scoped client presentation without reading inventory",
        "description": "Private Goal 13 candidate extension, not yet publicly deployed. Requires runtime:read and current visitor/preview or backend authority. Returns sanitized client colours and configuration/policy identity only; no source reads, provider work or cached authority. Published consumers cannot read drafts.",
        "security": [{ "VisitorCapability": [] }, { "BackendBearer": [] }],
        "responses": {
          "200": {
            "description": "Current source-independent presentation. Cache-Control: no-store.",
            "content": { "application/json": { "schema": { "$ref": "./schemas/managed-api-schemas-v1.json#/$defs/ManagedPresentation" } } }
          },
          "401": { "$ref": "#/components/responses/Problem" },
          "403": { "$ref": "#/components/responses/Problem" },
          "404": { "$ref": "#/components/responses/Problem" },
          "409": { "$ref": "#/components/responses/Problem" },
          "410": { "$ref": "#/components/responses/Problem" },
          "423": { "$ref": "#/components/responses/Problem" },
          "503": { "$ref": "#/components/responses/Problem" }
        }
      }
    },
    "/bootstrap": {
      "post": {
        "operationId": "bootstrapPublishedVisitor",
        "tags": ["sessions"],
        "summary": "Issue an origin-bound capability for a published public integration",
        "security": [],
        "requestBody": { "$ref": "#/components/requestBodies/Bootstrap" },
        "responses": {
          "201": { "$ref": "#/components/responses/CapabilityCreated" },
          "400": { "$ref": "#/components/responses/Problem" },
          "403": { "$ref": "#/components/responses/Problem" },
          "404": { "$ref": "#/components/responses/Problem" },
          "423": { "$ref": "#/components/responses/Problem" },
          "429": { "$ref": "#/components/responses/Problem" },
          "503": { "$ref": "#/components/responses/Problem" }
        }
      }
    },
    "/preview/bootstrap": {
      "post": {
        "operationId": "bootstrapPreviewVisitor",
        "tags": ["sessions"],
        "summary": "Exchange a draft-bound preview credential for a browser capability",
        "security": [{ "PreviewBearer": [] }],
        "requestBody": { "$ref": "#/components/requestBodies/Bootstrap" },
        "responses": {
          "201": { "$ref": "#/components/responses/CapabilityCreated" },
          "401": { "$ref": "#/components/responses/Problem" },
          "403": { "$ref": "#/components/responses/Problem" },
          "409": { "$ref": "#/components/responses/Problem" },
          "410": { "$ref": "#/components/responses/Problem" },
          "423": { "$ref": "#/components/responses/Problem" },
          "429": { "$ref": "#/components/responses/Problem" },
          "503": { "$ref": "#/components/responses/Problem" }
        }
      }
    },
    "/renew": {
      "post": {
        "operationId": "renewVisitorCapability",
        "tags": ["sessions"],
        "summary": "Rotate a current visitor or preview capability within its absolute bound",
        "security": [{ "VisitorCapability": [] }],
        "responses": {
          "200": { "$ref": "#/components/responses/Capability" },
          "401": { "$ref": "#/components/responses/Problem" },
          "403": { "$ref": "#/components/responses/Problem" },
          "409": { "$ref": "#/components/responses/Problem" },
          "410": { "$ref": "#/components/responses/Problem" },
          "423": { "$ref": "#/components/responses/Problem" },
          "429": { "$ref": "#/components/responses/Problem" }
        }
      }
    },
    "/": {
      "get": {
        "operationId": "getManagedProfile",
        "tags": ["profile"],
        "summary": "Read the current profile, capabilities, source revision and public items",
        "security": [{ "VisitorCapability": [] }, { "BackendBearer": [] }],
        "parameters": [{ "$ref": "#/components/parameters/InputRef" }],
        "responses": {
          "200": {
            "description": "Current managed profile.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "./schemas/managed-api-schemas-v1.json#/$defs/ExperienceProfile"
                }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Problem" },
          "403": { "$ref": "#/components/responses/Problem" },
          "409": { "$ref": "#/components/responses/Problem" },
          "410": { "$ref": "#/components/responses/Problem" },
          "423": { "$ref": "#/components/responses/Problem" },
          "503": { "$ref": "#/components/responses/Problem" }
        }
      }
    },
    "/status": {
      "get": {
        "operationId": "getManagedSourceStatus",
        "tags": ["profile"],
        "summary": "Read current source health and revision without travel work",
        "security": [{ "VisitorCapability": [] }, { "BackendBearer": [] }],
        "parameters": [{ "$ref": "#/components/parameters/InputRef" }],
        "responses": {
          "200": {
            "description": "Current source status.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "./schemas/managed-api-schemas-v1.json#/$defs/SourceStatus"
                }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Problem" },
          "403": { "$ref": "#/components/responses/Problem" },
          "409": { "$ref": "#/components/responses/Problem" },
          "410": { "$ref": "#/components/responses/Problem" },
          "423": { "$ref": "#/components/responses/Problem" },
          "503": { "$ref": "#/components/responses/Problem" }
        }
      }
    },
    "/items/{itemId}": {
      "get": {
        "operationId": "getManagedCurrentItem",
        "tags": ["profile"],
        "summary": "Resolve one current item and its current permitted action",
        "security": [{ "VisitorCapability": [] }, { "BackendBearer": [] }],
        "parameters": [
          {
            "name": "itemId",
            "in": "path",
            "required": true,
            "schema": { "type": "string" }
          },
          { "$ref": "#/components/parameters/InputRef" }
        ],
        "responses": {
          "200": {
            "description": "Current item and action authority.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "./schemas/managed-api-schemas-v1.json#/$defs/CurrentItem"
                }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Problem" },
          "403": { "$ref": "#/components/responses/Problem" },
          "404": { "$ref": "#/components/responses/Problem" },
          "409": { "$ref": "#/components/responses/Problem" },
          "410": { "$ref": "#/components/responses/Problem" },
          "423": { "$ref": "#/components/responses/Problem" },
          "503": { "$ref": "#/components/responses/Problem" }
        }
      }
    },
    "/places": {
      "post": {
        "operationId": "searchManagedPlaces",
        "tags": ["naming"],
        "summary": "Search configured place names within the admitted region",
        "description": "May consume one naming-provider start. Attribution returned by the configured provider remains part of the response. Cancellation does not authorize an automatic retry.",
        "security": [{ "VisitorCapability": [] }, { "BackendBearer": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "./schemas/managed-api-schemas-v1.json#/$defs/PlaceSearchRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Place candidates and provider attribution.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "./schemas/managed-api-schemas-v1.json#/$defs/PlaceSearchResponse"
                }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Problem" },
          "403": { "$ref": "#/components/responses/Problem" },
          "409": { "$ref": "#/components/responses/Problem" },
          "422": { "$ref": "#/components/responses/Problem" },
          "429": { "$ref": "#/components/responses/Problem" },
          "503": { "$ref": "#/components/responses/Problem" }
        }
      }
    },
    "/places/reverse": {
      "post": {
        "operationId": "reverseManagedPlace",
        "tags": ["naming"],
        "summary": "Resolve a display name for a supported geometry",
        "description": "May consume one naming-provider start. Unsupported depth or surface selection remains unavailable rather than inventing a location.",
        "security": [{ "VisitorCapability": [] }, { "BackendBearer": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "./schemas/managed-api-schemas-v1.json#/$defs/PlaceReverseRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Resolved place name or an explicitly unavailable result.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "./schemas/managed-api-schemas-v1.json#/$defs/PlaceReverseResponse"
                }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Problem" },
          "403": { "$ref": "#/components/responses/Problem" },
          "409": { "$ref": "#/components/responses/Problem" },
          "422": { "$ref": "#/components/responses/Problem" },
          "429": { "$ref": "#/components/responses/Problem" },
          "503": { "$ref": "#/components/responses/Problem" }
        }
      }
    },
    "/evaluations": {
      "post": {
        "operationId": "evaluateManagedItems",
        "tags": ["decisions"],
        "summary": "Evaluate current source items using canonical spatial and domain rules",
        "description": "A successful response may include decision evidence that expires within the caller lifetime and is bound to caller, integration, source/data revision and normalized requirements. decisionPolicyVersion displayed-area-authority-v1 means valid displayed-area membership decides canonical travel fit: inside and boundary pass, outside and provider-empty areas miss, and unavailable area membership falls back to the typed provider metric. Supporting metric status/reason and area consistency remain separate; domain rules remain independently decisive. Unknown provider or source outcomes are not coerced to matches.",
        "security": [{ "VisitorCapability": [] }, { "BackendBearer": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "./schemas/managed-api-schemas-v1.json#/$defs/EvaluationRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Canonical outcomes, explanations, evidence and attribution.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "./schemas/managed-api-schemas-v1.json#/$defs/EvaluationResponse"
                }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Problem" },
          "403": { "$ref": "#/components/responses/Problem" },
          "409": { "$ref": "#/components/responses/Problem" },
          "422": { "$ref": "#/components/responses/Problem" },
          "429": { "$ref": "#/components/responses/Problem" },
          "503": { "$ref": "#/components/responses/Problem" }
        }
      }
    },
    "/comparisons": {
      "post": {
        "operationId": "compareManagedItems",
        "tags": ["decisions"],
        "summary": "Compare current facts and optional current decision evidence",
        "description": "Comparison starts no travel or naming provider work. Evaluated comparisons repeat the evaluation's decisionPolicyVersion and expose named travel requirement rows; clients use row.status as canonical fit and metricStatus only as supporting route evidence. Missing, expired or mismatched evidence produces a facts-only/unknown-qualified comparison rather than hidden reevaluation.",
        "security": [{ "VisitorCapability": [] }, { "BackendBearer": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "./schemas/managed-api-schemas-v1.json#/$defs/ComparisonRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Current comparison.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "./schemas/managed-api-schemas-v1.json#/$defs/ComparisonResponse"
                }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Problem" },
          "403": { "$ref": "#/components/responses/Problem" },
          "409": { "$ref": "#/components/responses/Problem" },
          "422": { "$ref": "#/components/responses/Problem" },
          "503": { "$ref": "#/components/responses/Problem" }
        }
      }
    },
    "/street-level/admissions": {
      "post": {
        "operationId": "admitManagedStreetLevelAction",
        "tags": ["street-level"],
        "summary": "Issue a durable, replay-safe action receipt before one browser-direct street-level action",
        "description": "Available only to a live, owner-approved Google-photorealistic capability. Idempotency-Key identifies one logical request: exact replay returns the same receipt and changed content conflicts. Panorama admission must link to a current ready coverage receipt. Coverage and panorama have independent UTC-day limits and remain unbilled.",
        "security": [{ "VisitorCapability": [] }, { "BackendBearer": [] }],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": true,
            "schema": { "type": "string", "minLength": 8, "maxLength": 128 }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "./schemas/managed-api-schemas-v1.json#/$defs/StreetLevelAdmissionRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "One separately accounted street-level action was admitted.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "./schemas/managed-api-schemas-v1.json#/$defs/StreetLevelAdmission"
                }
              }
            }
          },
          "200": {
            "description": "Exact replay returned the original action receipt without another accounting effect.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "./schemas/managed-api-schemas-v1.json#/$defs/StreetLevelAdmission"
                }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Problem" },
          "403": { "$ref": "#/components/responses/Problem" },
          "409": { "$ref": "#/components/responses/Problem" },
          "422": { "$ref": "#/components/responses/Problem" },
          "429": { "$ref": "#/components/responses/Problem" },
          "503": { "$ref": "#/components/responses/Problem" }
        }
      }
    },
    "/street-level/outcomes": {
      "post": {
        "operationId": "recordManagedStreetLevelOutcome",
        "tags": ["street-level"],
        "summary": "Record a bounded non-identifying street-level lifecycle outcome",
        "description": "Records a valid lifecycle transition against the current tenant-, integration-, actor-, profile- and policy-bound action receipt. Event and repeated-outcome deduplication prevent telemetry inflation. Client observations remain separate from provider invoices and never invoke a provider retry.",
        "security": [{ "VisitorCapability": [] }, { "BackendBearer": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "./schemas/managed-api-schemas-v1.json#/$defs/StreetLevelOutcome"
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "Outcome accepted.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "./schemas/managed-api-schemas-v1.json#/$defs/StreetLevelOutcomeReceipt"
                }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Problem" },
          "403": { "$ref": "#/components/responses/Problem" },
          "409": { "$ref": "#/components/responses/Problem" },
          "422": { "$ref": "#/components/responses/Problem" }
        }
      }
    },
    "/inputs": {
      "get": {
        "operationId": "describeManagedInput",
        "tags": ["inputs"],
        "summary": "Read admitted request-input setup before submitting the first snapshot",
        "description": "Additive managed-v1 operation. Only a backend credential with runtime:input for a currently published neutral request-input integration is admitted. This returns source identities, schemas, capacity and process-local retention limits, without reading a submitted snapshot. It grants no property upload or visitor submission authority.",
        "security": [{ "BackendBearer": [] }],
        "responses": {
          "200": {
            "description": "Current admitted input descriptor.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "./schemas/managed-api-schemas-v1.json#/$defs/InputDescriptor"
                }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Problem" },
          "403": { "$ref": "#/components/responses/Problem" },
          "409": { "$ref": "#/components/responses/Problem" },
          "503": { "$ref": "#/components/responses/Problem" }
        }
      },
      "post": {
        "operationId": "submitManagedInput",
        "tags": ["inputs"],
        "summary": "Submit bounded request-scoped items to a configured request-input integration",
        "description": "Only backend credentials with runtime:input can call this route. Read GET /inputs first: use its sourceId in the envelope and snapshotSourceId in the snapshot. Visitor and preview capabilities cannot submit input. The returned reference and identical client input IDs are caller-, integration-, publication-, source- and expiry-bound.",
        "security": [{ "BackendBearer": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "./schemas/managed-api-schemas-v1.json#/$defs/InputSubmission"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Bound temporary input receipt.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "./schemas/managed-api-schemas-v1.json#/$defs/InputReceipt"
                }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Problem" },
          "403": { "$ref": "#/components/responses/Problem" },
          "409": { "$ref": "#/components/responses/Problem" },
          "410": { "$ref": "#/components/responses/Problem" },
          "422": { "$ref": "#/components/responses/Problem" },
          "429": { "$ref": "#/components/responses/Problem" },
          "503": { "$ref": "#/components/responses/Problem" }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "VisitorCapability": {
        "type": "apiKey",
        "in": "header",
        "name": "X-Overa-Visitor",
        "description": "Short-lived in-memory browser capability for one integration, origin and policy generation."
      },
      "BackendBearer": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "Opaque managed backend credential",
        "description": "Confidential server-to-server credential with explicit runtime grants."
      },
      "PreviewBearer": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "Opaque managed preview credential",
        "description": "Confidential short-lived credential bound to one current draft."
      }
    },
    "parameters": {
      "InputRef": {
        "name": "inputRef",
        "in": "query",
        "required": false,
        "description": "Temporary backend-submitted input reference; valid only for its original caller/integration and lifetime.",
        "schema": { "type": "string" }
      }
    },
    "requestBodies": {
      "Bootstrap": {
        "required": true,
        "content": {
          "application/json": {
            "schema": {
              "$ref": "./schemas/managed-api-schemas-v1.json#/$defs/BootstrapRequest"
            }
          }
        }
      }
    },
    "responses": {
      "CapabilityCreated": {
        "description": "New visitor capability. Never persist it in a URL, cookie or browser storage.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "./schemas/managed-api-schemas-v1.json#/$defs/VisitorCapability"
            }
          }
        }
      },
      "Capability": {
        "description": "Rotated visitor capability.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "./schemas/managed-api-schemas-v1.json#/$defs/VisitorCapability"
            }
          }
        }
      },
      "Problem": {
        "description": "Safe typed failure. Retry only when the operation and returned category explicitly permit it; provider-bearing requests are not automatically replayed.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "./schemas/managed-api-schemas-v1.json#/$defs/Problem"
            }
          }
        }
      }
    }
  },
  "x-overa-cors": {
    "preflight": "OPTIONS is available for registered browser origins on all managed paths.",
    "allowedRequestHeaders": ["Content-Type", "X-Overa-Visitor"],
    "credentials": false
  },
  "x-overa-compatibility": {
    "namespace": "Breaking route or authority changes require a new /api/managed/vN namespace.",
    "payloads": "Additive optional fields may appear in v1. Contract/schema version fields govern domain payload changes. Existing fields retain meaning within v1.",
    "decisionPolicy": "evaluationVersion continues to identify the provider evidence algorithm family. decisionPolicyVersion independently identifies canonical fit semantics and is required on evaluations and evaluated comparisons. Clients that understand displayed-area-authority-v1 use area membership status as canonical travel fit and keep metric status as supporting evidence. A future incompatible canonical policy requires a new decisionPolicyVersion and documented negotiation or a new managed namespace; it must not silently reuse displayed-area-authority-v1.",
    "deprecation": "Published v1 operations are not removed without a documented replacement and owner-approved migration window.",
    "targetDesign": "docs/architecture/contracts/openapi.json remains a non-deployed target design and is not this contract."
  },
  "x-overa-usage": {
    "units": "API operations, source reads/cache hits, journey starts, naming starts, Street View coverage admissions and Street View panorama admissions are separate operational units, not invoices.",
    "attribution": "Provider attribution returned in naming/evaluation payloads must be retained by clients.",
    "browser3d": "Browser-direct Cesium requests are outside server routing counters. Browser-direct Street View actions require a preceding conservative admission and separate outcome reporting."
  }
}