> ## Documentation Index > Fetch the complete documentation index at: https://support.keypro.fi/llms.txt > Use this file to discover all available pages before exploring further. # Compare a manhole inspection connection against the duct it refers to > Operation is used to compare one BRTilslutning connection of a manhole inspection against the KeyAqua duct the network holds for it - whether the pipes the inspection found at a manhole are the pipes the network claims. The manhole is resolved from the inspection's confirmed link, then its position identifier (Broendnr), then the nearest manhole to its own coordinates. The duct is resolved from that manhole's connected ducts, narrowed by flow direction. A single candidate is used as is. Where several remain, a Tilloebspunkt naming a manhole the network holds selects the duct running between the two; otherwise dimension is the tiebreak, and a still ambiguous result returns the candidates for the caller to pick from. A connection the network holds no duct for is a result rather than an error: the response carries a null `matched_snsewerduct_id`. ## OpenAPI ````json POST /manhole-connection-comparison/ { "openapi": "3.0.4", "info": { "title": "Keyduct REST API", "termsOfService": "https://www.keypro.fi/en/terms-of-service", "contact": { "name": "Keypro Oy", "url": "https://keypro.fi/", "email": "keypro@keypro.fi" }, "license": { "name": "Copyright (C) Keypro Oy. All rights reserved.", "url": "https://www.keypro.fi/" }, "version": "2.0.0" }, "servers": [ { "url": "/api/v2" } ], "tags": [ { "name": "Task", "description": "Task related operations." }, { "name": "Subregion", "description": "Subregion related operations." }, { "name": "SAttribute", "description": "SAttribute related operations." }, { "name": "Fault", "description": "Fault related operations." }, { "name": "Maintenance history", "description": "Maintenance history related operations." }, { "name": "Deflection", "description": "Deflection related operations." }, { "name": "Fault Component", "description": "Fault Component related operations." }, { "name": "Task Comment", "description": "Task comment related operations." }, { "name": "FaultComponentFault", "description": "FaultComponentFault related operations." }, { "name": "Collections", "description": "Collection related operations." }, { "name": "Contact Person", "description": "ContactPerson related operations" }, { "name": "Contact Person Connection", "description": "ContactPersonConnection related operations" }, { "name": "Plan", "description": "Plan related operations." }, { "name": "FreeArea", "description": "FreeArea related operations." }, { "name": "Address", "description": "Building address related operations." }, { "name": "Apartment", "description": "Building apartments related operations." }, { "name": "Customer", "description": "Customer data related operations." }, { "name": "Customer Contract", "description": "Customer contract related operations." }, { "name": "Extra Attribute", "description": "Extra attributes related operations." }, { "name": "Extra Value", "description": "Extra attribute values related operations." }, { "name": "Consumer Point", "description": "Consumer point related operations." }, { "name": "Consumer Point Linked Address", "description": "Consumer point address link related operations." }, { "name": "Flow Meter", "description": "Flow Meter related operations." }, { "name": "Text Constant", "description": "Text Constant related operations." }, { "name": "Sn Constant", "description": "Sn Constant related operations." }, { "name": "Gas Meter", "description": "Gas Meter related operations." }, { "name": "Junction", "description": "Junction related operations." }, { "name": "Junction Connection", "description": "Junction Connection related operations." }, { "name": "External Document", "description": "External documents related operations." }, { "name": "Water Duct Renovation", "description": "Water duct renovation related operations." }, { "name": "Sewer Duct Renovation", "description": "Sewer duct renovation related operations." }, { "name": "Water Duct", "description": "Water duct related operations." }, { "name": "Water Other Node", "description": "Water other node related operations." }, { "name": "Water Hydrant", "description": "Water hydrant related operations." }, { "name": "Water Branch", "description": "Water branch related operations." }, { "name": "Water Measuring Point", "description": "Water measuring point related operations." }, { "name": "Fire Water Station", "description": "Fire water station related operations." }, { "name": "Water Fireplug", "description": "Water fireplug related operations." }, { "name": "Sewer Duct", "description": "Sewer duct related operations." }, { "name": "Flow Meter Reading", "description": "Flow Meter Reading related operations." }, { "name": "Gas Meter Reading", "description": "Gas meter reading related operations." }, { "name": "Gas Cable", "description": "Gas cable related operations." }, { "name": "Gas Other Node", "description": "Gas other node related operations." }, { "name": "Gas Valve", "description": "Gas valve related operations." }, { "name": "Water Node", "description": "Water node related operations." }, { "name": "Consumer Point Property", "description": "Consumer point property related operations." }, { "name": "Dh Manhole", "description": "Dh manhole related operations." }, { "name": "Dh Manhole Link Connection", "description": "Dh Manhole Link Connection related operations." }, { "name": "Dh Cable", "description": "Dh cable related operations." }, { "name": "Error Report", "description": "Error report related operations." }, { "name": "Failure Report", "description": "Failure report related operations." }, { "name": "DCCTV Comparison", "description": "DCCTV comparison (nearest object lookup + manual pick) related operations." }, { "name": "TV Inspection", "description": "CCTV TV inspection related operations." }, { "name": "Manhole Inspection", "description": "Manhole inspection related operations." }, { "name": "Dh Duct", "description": "Dh duct related operations." }, { "name": "Dh Conduit", "description": "Dh conduit related operations." }, { "name": "Dh Division", "description": "Dh division related operations." }, { "name": "Dh Valve", "description": "Dh valve related operations." }, { "name": "Consumer Point User", "description": "Consumer Point User related operations." }, { "name": "Consumer Point Real Estate", "description": "Consumer point real estate related operations." }, { "name": "Consumer Point User Email", "description": "Consumer point user email related operations." }, { "name": "Water Pumping Station", "description": "Water pumping station related operations." }, { "name": "Dh Meter Reading", "description": "Dh Meter Reading related operations." }, { "name": "Consumer Point Connection", "description": "Consumer point connection related operations." }, { "name": "Modeling Data", "description": "Modeling data related operations.\n\n*NOTE:* Contrary to what is described in chapter 1.5, the base path for all of these operations is `/keyaqua_modeling`\n" }, { "name": "Gas Manhole", "description": "Gas manhole related operations." }, { "name": "KeyDh Observation", "description": "KeyDh Observation related operations." }, { "name": "KeyDh Supply Interruption", "description": "KeyDh Supply Interruption related operations." }, { "name": "KeyDh Supply Interruption Connection", "description": "KeyDh Supply Interruption Connection related operations." }, { "name": "Keydh Node", "description": "Keydh Node related operations." }, { "name": "Keygas Duct", "description": "Keygas Duct related operations." }, { "name": "Real Estate", "description": "Real Estate related operations." }, { "name": "Keydh Connection", "description": "Keydh Connection related operations." }, { "name": "Water Tank", "description": "Water Tank related operations." }, { "name": "Water Valve", "description": "Water Valve related operations." }, { "name": "Point", "description": "Point related operations." }, { "name": "Sn Modeling", "description": "Sn Modeling related operations." }, { "name": "Sewer Manholes v2", "description": "Sewer Manholes v2 related operations." }, { "name": "Sewer Ducts", "description": "Sewer Ducts related operations." }, { "name": "Sewer Valves", "description": "Sewer Valves related operations." }, { "name": "Sewer Pumping Stations", "description": "Sewer Pumping Stations related operations." }, { "name": "Sewer Branches", "description": "Sewer Branches related operations." }, { "name": "Sewer Measuring Poins", "description": "Sewer Measuring Poins related operations." }, { "name": "Sewer Other Nodes", "description": "Sewer Other Nodes related operations." }, { "name": "Keydh Conduit Link", "description": "Keydh Conduit Link related operations." }, { "name": "Duct Condition Detail", "description": "Duct condition detail related operations." }, { "name": "KeyDh Conduit Error", "description": "KeyDh Conduit Error related operations." }, { "name": "AquaObjectType", "description": "AquaObjectType related operations." }, { "name": "AquaMeasuringPointTypes", "description": "AquaMeasuringPointTypes related operations." }, { "name": "AquaPumpType", "description": "AquaPumpType related operations." }, { "name": "AquaBranchType", "description": "AquaBranchType related operations." }, { "name": "AquaValveType", "description": "AquaValveType related operations." }, { "name": "AquaManholeType", "description": "AquaManholeType related operations." }, { "name": "AquaDuctType", "description": "AquaDuctType related operations." }, { "name": "SnDuctType", "description": "SnDuctType related operations." }, { "name": "SnManholeType", "description": "SnManholeType related operations." }, { "name": "SnLidType", "description": "SnLidType related operations." }, { "name": "Sewer Nodes", "description": "Sewer Node related operations." }, { "name": "Sn Control", "description": "Sn Control related operations." }, { "name": "KeyDh Shell Type", "description": "KeyDh Shell Type related operations." }, { "name": "Sewer Branch Type", "description": "Sewer Branch Type related operations." }, { "name": "Sewer Valve Type", "description": "Sewer Valve Type related operations." } ], "paths": { "/manhole-connection-comparison/": { "post": { "tags": [ "DCCTV Comparison" ], "summary": "Compare a manhole inspection connection against the duct it refers to", "description": "Operation is used to compare one BRTilslutning connection of a manhole\ninspection against the KeyAqua duct the network holds for it - whether the\npipes the inspection found at a manhole are the pipes the network claims.\n\nThe manhole is resolved from the inspection's confirmed link, then its\nposition identifier (Broendnr), then the nearest manhole to its own\ncoordinates. The duct is resolved from that manhole's connected ducts,\nnarrowed by flow direction. A single candidate is used as is. Where several\nremain, a Tilloebspunkt naming a manhole the network holds selects the duct\nrunning between the two; otherwise dimension is the tiebreak, and a still\nambiguous result returns the candidates for the caller to pick from.\n\nA connection the network holds no duct for is a result rather than an error:\nthe response carries a null `matched_snsewerduct_id`.\n", "operationId": "postManholeConnectionComparison", "requestBody": { "content": { "application/json": { "schema": { "required": [ "tilslutning_guid" ], "type": "object", "properties": { "snsewerduct_id": { "type": "integer", "description": "Optional manual pick - if provided, this duct is compared instead of the resolved one. Must be connected to the resolved manhole." }, "snsewernode_id": { "type": "integer", "description": "Optional manual pick - if provided, this snsewernode is used instead of the resolved one." }, "tilslutning_guid": { "type": "string", "description": "GUID of the BRTilslutning connection to compare" }, "tolerance": { "type": "number", "description": "Maximum auto-match distance in meters when the manhole is resolved by proximity. Defaults to 0.2 (20 cm).", "format": "float" } } } } }, "required": true, "x-bodyName": "comparison" }, "responses": { "200": { "description": "Comparison result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManholeConnectionComparisonResponse" } } } }, "400": { "description": "There was an error in request. Usually field validation failed, or no manhole could be resolved for the inspection.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": { "type": "array", "description": "List of validation errors for this fieldname" }, "description": "Fields which failed validation" } } } }, "401": { "$ref": "#/components/responses/Http401" }, "404": { "$ref": "#/components/responses/Http404" } }, "security": [ { "Token": [] } ] } } }, "components": { "schemas": { "ManholeConnectionComparisonResponse": { "type": "object", "properties": { "candidate_snsewerduct_ids": { "type": "array", "items": { "type": "integer" }, "description": "Ducts at the manhole this connection could refer to, returned when none resolved outright." }, "fields": { "type": "array", "items": { "$ref": "#/components/schemas/ComparisonField" } }, "matched_snsewerduct_id": { "type": "integer", "description": "Id of the duct this connection refers to. Null when the network holds no duct for it, or when several candidates fit." }, "review_state": { "enum": [ "updated", "reviewed", "disabled_from_update" ], "type": "string", "description": "What a user decided about this connection, or null while nobody has\njudged it. `updated` is set by /manhole-connection-duct-diff/ when a\nwrite succeeds; the other two are recorded by\n/manhole-connection-review/ and write nothing to the network.\n", "nullable": true }, "reviewed_by": { "type": "string", "description": "Username of the user who judged the connection; null while unreviewed.", "nullable": true }, "reviewed_ts": { "type": "string", "description": "When the connection was judged; null while unreviewed.", "format": "date-time", "nullable": true }, "snsewernode_id": { "type": "integer", "description": "Id of the manhole the inspection was resolved to." } } }, "ComparisonField": { "type": "object", "properties": { "differs": { "type": "boolean", "description": "Whether the two values disagree. Null when no verdict can be reached -\nthe inspector recorded nothing, or the comparison returns a placeholder -\nso \"not comparable\" is never rendered as agreement.\n" }, "field": { "type": "string", "description": "Field name being compared" }, "inspection_value": { "type": "object", "description": "Value from the inspection record. FK fields are shown as a nested {id, txt} object." }, "keyaqua_value": { "type": "object", "description": "Value from the matched KeyAqua network object. The connection comparison\nreturns the duct's own value here; the inspection and observation\ncomparisons still return a placeholder null.\n" } } }, "ErrorDetailsResponse": { "required": [ "details" ], "type": "object", "properties": { "details": { "type": "string", "description": "Detailed description of error" } }, "description": "Standard error response payload" } }, "responses": { "Http401": { "description": "Authentication credentials are missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetailsResponse" }, "example": { "details": "Authentication credentials were not provided" } } } }, "Http404": { "description": "Object was not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetailsResponse" }, "example": { "details": "Not found." } } } } }, "securitySchemes": { "Token": { "type": "apiKey", "description": "Token issued for API consumer.", "name": "Authorization", "in": "header" } } } } ````