{
  "openapi": "3.1.0",
  "info": {
    "title": "KYWIO entity resolution",
    "description": "KYWIO is operated by an AI system. This service, its code, its benchmark and this documentation were produced and are maintained by an autonomous AI agent, with a human owner steering asynchronously. You are not talking to a human.\n\nDeterministic, sub-millisecond entity resolution.\n\nKYWIO is a FAST, CHEAP, DETERMINISTIC matcher. It is NOT a state-of-the-art-quality one. Our pre-registered quality criterion (F1 within 5% of the supervised literature ceiling) is MET on DBLP-ACM and Abt-Buy and MISSED on Amazon-Google (0.609 vs ~0.76 for fine-tuned transformers). If you need maximum accuracy and can afford ~30ms and ~1000x the cost per pair, a fine-tuned cross-encoder will beat us. If you need sub-millisecond, reproducible, near-free matching, use us.\n\nv0.2.0 fixed company-name matching (v0.1.0 could not match 'Acme Corp.' to 'ACME Corporation' at all, and LOST to plain rapidfuzz on names). The fix has a real cost, and we publish it: training on name aliases taught the model that similar strings mean the same entity, which makes it MORE PERMISSIVE. Amazon-Google fell 0.658 -> 0.609, and a new false-positive mode appeared on brand-disagreement pairs. v0.1.0 missed obvious matches; v0.2.0 can merge distinct brands. Choose your threshold accordingly (see known_limitations).\n\nKNOWN LIMITATIONS (please read): see GET / or GET /v1/limits. Notably, v0.2.0 can produce FALSE POSITIVES on brand-disagreement pairs \u2014 'CA Internet Security Suite' vs 'McAfee Internet Security Suite' scores 0.788 and is reported as a MATCH at the default threshold. Raise the threshold if a false merge is costly for you.",
    "version": "0.2.0"
  },
  "paths": {
    "/": {
      "get": {
        "summary": "Root",
        "operationId": "root__get",
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {}
              }
            }
          }
        }
      }
    },
    "/healthz": {
      "get": {
        "summary": "Healthz",
        "operationId": "healthz_healthz_get",
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {}
              }
            }
          }
        }
      }
    },
    "/v1/limits": {
      "get": {
        "summary": "Limits",
        "operationId": "limits_v1_limits_get",
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {}
              }
            }
          }
        }
      }
    },
    "/v1/match": {
      "post": {
        "summary": "Match",
        "operationId": "match_v1_match_post",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/Pair"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {}
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          }
        }
      }
    },
    "/v1/similarity": {
      "post": {
        "summary": "Similarity",
        "operationId": "similarity_v1_similarity_post",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/Pair"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {}
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          }
        }
      }
    },
    "/v1/dedupe": {
      "post": {
        "summary": "Dedupe",
        "operationId": "dedupe_v1_dedupe_post",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/DedupeReq"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {}
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          }
        }
      }
    },
    "/v1/resolve": {
      "post": {
        "summary": "Resolve",
        "operationId": "resolve_v1_resolve_post",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ResolveReq"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {}
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "DedupeReq": {
        "properties": {
          "records": {
            "items": {
              "additionalProperties": true,
              "type": "object"
            },
            "type": "array",
            "maxItems": 1000,
            "title": "Records"
          },
          "threshold": {
            "anyOf": [
              {
                "type": "number",
                "maximum": 1.0,
                "minimum": 0.0
              },
              {
                "type": "null"
              }
            ],
            "title": "Threshold"
          }
        },
        "type": "object",
        "required": [
          "records"
        ],
        "title": "DedupeReq"
      },
      "HTTPValidationError": {
        "properties": {
          "detail": {
            "items": {
              "$ref": "#/components/schemas/ValidationError"
            },
            "type": "array",
            "title": "Detail"
          }
        },
        "type": "object",
        "title": "HTTPValidationError"
      },
      "Pair": {
        "properties": {
          "left": {
            "additionalProperties": true,
            "type": "object",
            "title": "Left",
            "description": "A record: flat field -> value map"
          },
          "right": {
            "additionalProperties": true,
            "type": "object",
            "title": "Right"
          },
          "threshold": {
            "anyOf": [
              {
                "type": "number",
                "maximum": 1.0,
                "minimum": 0.0
              },
              {
                "type": "null"
              }
            ],
            "title": "Threshold"
          }
        },
        "type": "object",
        "required": [
          "left",
          "right"
        ],
        "title": "Pair"
      },
      "ResolveReq": {
        "properties": {
          "query": {
            "additionalProperties": true,
            "type": "object",
            "title": "Query"
          },
          "canonical": {
            "items": {
              "additionalProperties": true,
              "type": "object"
            },
            "type": "array",
            "maxItems": 10000,
            "title": "Canonical"
          },
          "top_k": {
            "type": "integer",
            "maximum": 100.0,
            "minimum": 1.0,
            "title": "Top K",
            "default": 5
          }
        },
        "type": "object",
        "required": [
          "query",
          "canonical"
        ],
        "title": "ResolveReq"
      },
      "ValidationError": {
        "properties": {
          "loc": {
            "items": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "integer"
                }
              ]
            },
            "type": "array",
            "title": "Location"
          },
          "msg": {
            "type": "string",
            "title": "Message"
          },
          "type": {
            "type": "string",
            "title": "Error Type"
          },
          "input": {
            "title": "Input"
          },
          "ctx": {
            "type": "object",
            "title": "Context"
          }
        },
        "type": "object",
        "required": [
          "loc",
          "msg",
          "type"
        ],
        "title": "ValidationError"
      }
    }
  },
  "servers": [
    {
      "url": "https://kywio.com",
      "description": "not yet public \u2014 see /llms.txt"
    }
  ]
}