> ## 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. # Create circuit fault location > NOTE: This API is provided by a separate service. This API endpoint searches for certain alarm determined by alarmId. If the alarm is already present in KeyCom then it is updated with the values provided in the request. If it is not, it makes a trace for specified distance from certain circuit section (and possibly port id) and using either logical or physical reservations finds the component of network affected by fault. Then the fault is created in the specified location. Available from product version 3.6.2. ## OpenAPI ````json POST /circuitFaultLocation/ { "openapi": "3.0.4", "info": { "title": "KeyCom 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": "Plan", "description": "Plan related operations." }, { "name": "FreeArea", "description": "FreeArea related operations." }, { "name": "FreeLine", "description": "FreeLine related operations." }, { "name": "FreeText", "description": "FreeText related operations." }, { "name": "FreeTextComponent", "description": "FreeText component related operations." }, { "name": "Address", "description": "Building address related operations." }, { "name": "Apartment", "description": "Building apartments related operations." }, { "name": "Extra Attribute", "description": "Extra attributes related operations." }, { "name": "Extra Value", "description": "Extra attribute values related operations." }, { "name": "EAV Enum", "description": "EAV Enum value related operations." }, { "name": "EAV Enum Group", "description": "EAV Enum group related operations." }, { "name": "External Document", "description": "External documents related operations." }, { "name": "Attached Document", "description": "Attached Documents related operations." }, { "name": "Collections", "description": "Collection related operations." }, { "name": "Source system apartment", "description": "External source system derived apartment related operations." }, { "name": "Source system address", "description": "External source system derived address related operations." }, { "name": "Address alias", "description": "Address aliases related operations" }, { "name": "TxtConstant", "description": "TxtConstants related operations." }, { "name": "Point", "description": "Point objects related operations." }, { "name": "Survey Constant", "description": "Survey Constants related operations." }, { "name": "Survey Point", "description": "Survey Points related operations." }, { "name": "Survey Line String", "description": "Survey Line Strings related operations." }, { "name": "Template Catalog", "description": "Template Catalog related operations." }, { "name": "Route Following", "description": "Route following related operations." }, { "name": "Contact Person", "description": "Contact person related operations." }, { "name": "Contact Person Connection", "description": "Contact person connection related operations." }, { "name": "Telecom premises", "description": "Telecom premises related operations." }, { "name": "Device", "description": "Device related operations." }, { "name": "Device Group", "description": "Device Group related operations." }, { "name": "Splice", "description": "Telecom Splice related operations." }, { "name": "Telecom Conduit", "description": "Telecom Conduit related operations." }, { "name": "Telecom Conduit Link", "description": "Operations related to putting Telecom Cables and Ducts into Conduits." }, { "name": "Telecom Duct", "description": "Telecom Duct related operations." }, { "name": "Telecom Duct Link", "description": "Operations related to putting Telecom Cables into Ducts." }, { "name": "Telecom Conduit Connection", "description": "Operations related to connecting Conduits and endpoints." }, { "name": "Telecom Cable Connection", "description": "Operations related to connecting Cables and endpoints" }, { "name": "Telecom Thread/Port Connection", "description": "Operations related to connecting and disconnecting telecom cable threads and device ports" }, { "name": "Telecom Duct Connection", "description": "Operations related to connecting Telecom Ducts to Telecom Premises or Manhole." }, { "name": "Manhole", "description": "Telecom Manhole related operations." }, { "name": "Cable", "description": "Telecom Cable related operations." }, { "name": "Cable Appendix", "description": "Cable Appendix operations for connecting Cables to loops. Manages the relationship between Cables and loops, automatically adjusting Cable extra_length when appendixes are created, updated, or deleted." }, { "name": "Supercable", "description": "Telecom Supercable related operations." }, { "name": "Cross connection point", "description": "Cross connection point related operations." }, { "name": "Service Area", "description": "Service Area related operations." }, { "name": "Exchange Area", "description": "Exchange Area related operations." }, { "name": "Telecom Area", "description": "Telecom Area related operations." }, { "name": "Routefollower", "description": "Routefollower related operations." }, { "name": "Circuit", "description": "Circuit related operations." }, { "name": "Circuit Location", "description": "Circuit installation location related operations." }, { "name": "Circuit Section", "description": "Circuit section related operations." }, { "name": "Circuit Reservation Data", "description": "Circuit reservation data view and search operations." }, { "name": "Customer", "description": "Customer data related operations." }, { "name": "Passed Services", "description": "Passed Services related operations." }, { "name": "Circuit Connection", "description": "Circuit logical reservations related operations." }, { "name": "Circuit Physical Reservation", "description": "Circuit physical reservations related operations." }, { "name": "Create connections", "description": "Operation used to create new connections." }, { "name": "Terminal type", "description": "Terminal types related operations." }, { "name": "Logical connections", "description": "Logical connections related operations." }, { "name": "Circuit Services", "description": "Operations provided by micro services." }, { "name": "Contract", "description": "Contract related operations." }, { "name": "Contract Link", "description": "Contract link related operations." }, { "name": "Pole", "description": "Pole related operations." }, { "name": "Circuit faults", "description": "Circuit faults related operations." }, { "name": "Duct groups", "description": "Duct groups related operations." }, { "name": "Duct group rows", "description": "Duct group rows related operations." }, { "name": "Threads", "description": "Cable thread related operations." }, { "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." } ], "paths": { "/circuitFaultLocation/": { "post": { "tags": [ "Circuit Services" ], "summary": "Create circuit fault location", "description": "NOTE: This API is provided by a separate service.\n\nThis API endpoint searches for certain alarm determined by alarmId.\nIf the alarm is already present in KeyCom then it is updated with the values\nprovided in the request. If it is not, it makes a trace for specified distance\nfrom certain circuit section (and possibly port id) and using either logical or\nphysical reservations finds the component of network affected by fault. Then the\nfault is created in the specified location.\n\nAvailable from product version 3.6.2.\n", "operationId": "createCircuitFaultLocation", "parameters": [ { "$ref": "#/components/parameters/srsParam" }, { "$ref": "#/components/parameters/langParam" } ], "requestBody": { "description": "circuit fault to be traced and created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FlatCircuitFaultLocation" } } }, "required": true, "x-bodyName": "create circuit fault body" }, "responses": { "201": { "description": "created circuit fault and fault location", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCircuitFaultLocationResponse" }, "example": { "alarmId": "123456", "description": "test", "distance": 30.0, "faultState": { "availability_end_ts": null, "availability_start_ts": null, "available": true, "groupname": "CIRCUIT_LOG_STATE", "id": 6770, "logical_txt": "Ilmoitettu", "num_value": null, "num_value2": null, "num_value3": null, "num_value4": null, "txt": "Ilmoitettu" }, "faultType": { "availability_end_ts": null, "availability_start_ts": null, "available": true, "groupname": "CIRCUIT_LOG_ENTRY", "id": 6690, "logical_txt": "Rätisee", "num_value": null, "num_value2": null, "num_value3": null, "num_value4": null, "txt": "Rätisee" }, "id": 15650, "location": "SRID=4326;POINT Z (60.54678877583297 26.17476424505218 -7.941480726003647e-05)", "loss": 3.1, "objectId": 152255, "objectType": "threaddetail", "routeEndReached": false, "routeLocation": "SRID=4326;LINESTRING Z (60.54676895577271 26.17497882752768 -7.941573858261108e-05, 60.62600056457995 26.20147963427254 -7.953960448503494e-05, 60.54676871806093 26.17494091868807 -7.941387593746185e-05, 60.54676415016116 26.17478779664355 -7.941294461488724e-05, 60.54677229193739 26.17476404222064 -7.941573858261108e-05, 60.54678877583297 26.17476424505218 -7.941480726003647e-05)", "sectionId": 561 } } } }, "400": { "description": "There was an error in request. Usually field validation failed.", "content": { "application/json": { "schema": { "minProperties": 1, "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string", "description": "Validation error" }, "description": "List of validation errors for this fieldname" }, "description": "Fields which failed validation" } } } }, "401": { "$ref": "#/components/responses/Http401" } }, "security": [ { "Token": [] } ] } } }, "components": { "parameters": { "srsParam": { "name": "srs", "in": "query", "description": "Coordinate system used to transform location fields in API responses.\nThis parameter does not apply to locations sent in request query parameters or request bodies.\n\nFor locations in requests, use EWKT with SRID.\nIf EWKT is provided without SRID, the system default SRID will be used.\n\n**Example:** `srs=epsg:4326`\n", "schema": { "type": "string" } }, "langParam": { "name": "Accept-Language", "in": "header", "description": "Two-letter language code to use for interface translation.\n**Example:** `Accept-Language=en`\n", "schema": { "type": "string" } } }, "schemas": { "FlatCircuitFaultLocation": { "required": [ "sectionId", "distance" ], "type": "object", "properties": { "alarmId": { "type": "string", "description": "id of the external object describing the fault, i.e. alarm" }, "description": { "type": "string", "description": "circuit fault description" }, "direction": { "enum": [ "asc", "desc" ], "type": "string", "description": "the direction to go through the reservations as of the reservation order to avoid ambiguous results" }, "distance": { "type": "number", "description": "optical distance for locating the fault", "format": "float" }, "faultState": { "type": "integer", "description": "id of circuit fault state, used for Alarm state (New, Updated or Cleared)" }, "faultType": { "type": "integer", "description": "id of circuit fault type, used for Severity (Break or Degradation)" }, "loss": { "type": "number", "description": "Loss (dB) caused by fault", "format": "float" }, "portId": { "type": "integer", "description": "port (cross-connection point) to be traced" }, "reservation": { "enum": [ "logical", "physical" ], "type": "string", "description": "specifies if logical or physical reservations of the circuit section are used for locating the fault" }, "sectionId": { "type": "integer", "description": "circuit section to be traced" } } }, "CreateCircuitFaultLocationResponse": { "allOf": [ { "$ref": "#/components/schemas/CircuitFaultLocation" }, { "type": "object", "properties": { "alarmId": { "type": "string", "description": "id of the external object describing the fault, i.e. alarm" }, "description": { "type": "string", "description": "circuit fault description" }, "faultState": { "$ref": "#/components/schemas/CircuitFaultState" }, "faultType": { "$ref": "#/components/schemas/CircuitFaultType" }, "id": { "type": "integer", "description": "id of circuit fault in KeyCom" }, "loss": { "type": "number", "description": "Loss (dB) caused by fault", "format": "float" } } } ] }, "CircuitFaultLocation": { "type": "object", "properties": { "distance": { "type": "number", "description": "calculated distance from all objects along the route found (cross-connections, device internal connections, cable total lengths)", "format": "float" }, "location": { "type": "string", "description": "calculated location of the fault, taking into account possible loops and coils along the route", "format": "ewkt" }, "objectId": { "type": "integer", "description": "id of object affected by fault" }, "objectType": { "enum": [ "threaddetail", "crossconnectionpoint" ], "type": "string", "description": "type of object affected by fault" }, "routeEndReached": { "type": "boolean", "description": "is route end reached or route ended preliminary" }, "routeLocation": { "type": "string", "description": "route from start of trace to object affected by fault (including object affected by fault)", "format": "ewkt" } } }, "CircuitFaultState": { "required": [ "id", "groupname", "logical_txt", "txt", "list_url" ], "type": "object", "properties": { "availability_end_ts": { "type": "string", "description": "Ending date time for availability", "format": "date-time" }, "availability_start_ts": { "type": "string", "description": "Beginning date time for availability", "format": "date-time" }, "available": { "type": "boolean", "description": "Is object deemed as available. Based on availability_start_ts and availability_end_ts values.", "readOnly": true }, "groupname": { "enum": [ "CIRCUIT_LOG_STATE" ], "description": "Group name of constant" }, "id": { "type": "integer", "description": "Unique id of constant" }, "list_url": { "type": "string", "description": "Url to fetch all constants from this group", "format": "url" }, "logical_txt": { "type": "string", "description": "Logical textual value" }, "num_value": { "type": "number", "description": "Numeric value", "format": "float" }, "num_value2": { "type": "number", "description": "Numeric value 2", "format": "float" }, "num_value3": { "type": "number", "description": "Numeric value 3", "format": "float" }, "num_value4": { "type": "number", "description": "Numeric value 4", "format": "float" }, "txt": { "type": "string", "description": "Human readable textual representation" } }, "description": "Circuit fault state" }, "CircuitFaultType": { "required": [ "id", "groupname", "logical_txt", "txt", "list_url" ], "type": "object", "properties": { "availability_end_ts": { "type": "string", "description": "Ending date time for availability", "format": "date-time" }, "availability_start_ts": { "type": "string", "description": "Beginning date time for availability", "format": "date-time" }, "available": { "type": "boolean", "description": "Is object deemed as available. Based on availability_start_ts and availability_end_ts values.", "readOnly": true }, "groupname": { "enum": [ "CIRCUIT_LOG_ENTRY" ], "description": "Group name of constant" }, "id": { "type": "integer", "description": "Unique id of constant" }, "list_url": { "type": "string", "description": "Url to fetch all constants from this group", "format": "url" }, "logical_txt": { "type": "string", "description": "Logical textual value" }, "num_value": { "type": "number", "description": "Numeric value", "format": "float" }, "num_value2": { "type": "number", "description": "Numeric value 2", "format": "float" }, "num_value3": { "type": "number", "description": "Numeric value 3", "format": "float" }, "num_value4": { "type": "number", "description": "Numeric value 4", "format": "float" }, "txt": { "type": "string", "description": "Human readable textual representation" } }, "description": "Circuit fault type" }, "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" } } } } }, "securitySchemes": { "Token": { "type": "apiKey", "description": "Token issued for API consumer.", "name": "Authorization", "in": "header" } } } } ````