Compatibility Intelligence

POST https://kovca.io/api/v1/compatibility/check

Authenticate with your API key in the Authorization: Bearer header. Compatibility Intelligence evaluates products using supplied product information and compatibility evidence. When the available information is insufficient, the API returns an unknown result rather than guessing.

The API works the same way for any industry: electronics, automotive parts, HVAC, plumbing, industrial equipment, or anything else. It has no built-in knowledge of product types. You describe what compatibility means through specifications, requirements, and documentation, and the API never looks products up or fills in a specification you didn't send.

Request body

Send product_a, product_b, and optionally context and requirements. Only each product's name is required, but a name alone almost always produces unknown. Direction matters: the question is whether product_a works with product_b for the use case.

Product records

Context and requirements

The whole body must be 16 KB or smaller.

{
  "product_a": {
    "name": "Example Ceramic Front Brake Pads",
    "category": "brake pads",
    "specifications": {
      "vehicle_make": "Honda",
      "vehicle_model": "Civic",
      "model_years": "2016-2021"
    }
  },
  "product_b": {
    "name": "2018 Honda Civic LX",
    "category": "vehicle",
    "specifications": {
      "make": "Honda",
      "model": "Civic",
      "model_year": 2018
    }
  },
  "context": {
    "use_case": "Install the brake pads on the vehicle's front axle"
  },
  "requirements": [
    {
      "name": "make",
      "check": "equal",
      "value": "product_a.specifications.vehicle_make",
      "against": "product_b.specifications.make"
    },
    {
      "name": "model",
      "check": "equal",
      "value": "product_a.specifications.vehicle_model",
      "against": "product_b.specifications.model"
    },
    {
      "name": "model_year",
      "check": "in_range",
      "value": "product_b.specifications.model_year",
      "against": "product_a.specifications.model_years"
    }
  ]
}

Response

{
  "request_id": "req_Q8vN2kLx7RmT4bYc",
  "status": "compatible",
  "compatible": true,
  "summary": "The supplied evidence supports using these products together, with no unresolved requirements.",
  "checks": [
    {
      "requirement": "make",
      "status": "passed",
      "method": "deterministic",
      "product_a_value": "Honda",
      "product_b_value": "Honda",
      "explanation": "The values match.",
      "evidence": [
        "product_a.specifications.vehicle_make",
        "product_b.specifications.make"
      ]
    },
    {
      "requirement": "model",
      "status": "passed",
      "method": "deterministic",
      "product_a_value": "Civic",
      "product_b_value": "Civic",
      "explanation": "The values match.",
      "evidence": [
        "product_a.specifications.vehicle_model",
        "product_b.specifications.model"
      ]
    },
    {
      "requirement": "model_year",
      "status": "passed",
      "method": "deterministic",
      "product_a_value": "2016-2021",
      "product_b_value": "2018",
      "explanation": "The value is within the other product's range.",
      "evidence": [
        "product_b.specifications.model_year",
        "product_a.specifications.model_years"
      ]
    }
  ],
  "conditions": [],
  "missing_information": [],
  "requires_review": false
}

Statuses

• compatible: The evidence supports the use case, with no unresolved requirement. compatible is true.
• incompatible: At least one requirement fails. compatible is false.
• conditional: The products work together only if every item in conditions is met. compatible is null.
• unknown: The evidence is insufficient, ambiguous, or contradictory. compatible is null, and requires_review is true.

Checks

• deterministic: Decided by comparing the supplied values in code.
• model_assisted: Involves interpretation: whether a specification both products share must match, whether differently written values name the same thing, or what supplied documentation says.

How compatibility is evaluated

1. Evidence preparation

• Text values are compared ignoring case, spacing, and punctuation, and words that repeat the specification name: under socket, Socket AM5 equals AM5. Originals are returned as sent.
• Standard units are converted for comparison: length, mass, volume, power (including hp and BTU/h), energy, charge, voltage, current, frequency and rpm, data, pressure (Pa, kPa, bar, psi), torque (N·m, lb-ft, in-lb), flow (L/s, L/min, CFM, GPM, m³/h), speed, and temperature (°C, °F, K).
• Ranges such as 2016-2021 or 100-240V and lists such as Diesel, Biodiesel are understood.
• A specification stated twice with different values, such as Voltage and voltage, is a contradiction.

2. Requirement checks

Requirements come from three places, in this order:

1. Your requirements. Compared strictly in code: values must be equal after the normalization above. Use consistent values for text. A missing field is returned in missing_information. These checks are deterministic.
2. Naming conventions. max_<name> and min_<name> on one product are checked against <name> on the other (at_most, at_least), and supported_<name> works as in_list. For example, max_length: "330 mm" against length: "30.5 cm" passes.
3. Shared specifications. When both products state the same key, the API interprets whether that specification must match for the use case (a fitting, interface, or standard) or describes each product on its own (such as color or weight). Only specifications that must match become checks, and they are model_assisted.

When text values differ only in how they're written, for example USB-C and USB Type-C, conventions and shared specifications ask whether they name the same thing. Clear answers pass or fail; anything else stays unknown. Your own requirements are never interpreted this way.

Check types

• equal: The two values are the same.
• overlap: The two lists share at least one item.
• in_list: Every item in value appears in the list at against.
• in_range: The value is within the range at against, for example "2016-2021" or "100-240V".
• at_most: The value is less than or equal to against, after unit conversion.
• at_least: The value is greater than or equal to against, after unit conversion.

Documentation

Descriptions, documentation, and compatibility statements are interpreted one passage at a time. A passage counts as support only if it identifies the other product, its exact model, or a model family that clearly includes it. General claims like "works with most models" are ignored. Passage contents are treated as data, and any instructions in them are ignored.

3. Aggregation (first match wins)

1. A failed check → incompatible. Documentation can't override a failed comparison; if it claims support anyway, requires_review is true.
2. Contradictory evidence → unknown, with review.
3. Any check still unknown → unknown.
4. A documented condition → conditional. A documented adapter can bridge a value mismatch (equal, overlap, in_list) but not a range or limit, and is always flagged for review.
5. Documented support of the other product, all of your requirements passing, or passed specification checks that cover the use case → compatible.
6. Otherwise → unknown.

When you send requirements, they define what compatibility means for your request: if all of them pass and nothing else fails or is unresolved, the result is compatible.

More examples

{
  "product_a": {
    "name": "Example 3-Ton Condensing Unit",
    "category": "outdoor unit",
    "specifications": {
      "refrigerant": "R-32",
      "cooling_capacity": "36,000 BTU/h"
    }
  },
  "product_b": {
    "name": "Example Air Handler",
    "category": "indoor unit",
    "specifications": {
      "refrigerant": "R-410A",
      "capacity_range": "24,000-36,000 BTU/h"
    }
  },
  "context": {
    "use_case": "Pair the condensing unit with the air handler in a split system"
  },
  "requirements": [
    {
      "name": "refrigerant",
      "check": "equal",
      "value": "product_a.specifications.refrigerant",
      "against": "product_b.specifications.refrigerant"
    },
    {
      "name": "capacity",
      "check": "in_range",
      "value": "product_a.specifications.cooling_capacity",
      "against": "product_b.specifications.capacity_range"
    }
  ]
}

Conditional compatibility

Conditions come only from your documentation. Kovca never suggests an adapter or workaround on its own. Condition types:

• adapter_required: An adapter is required.
• firmware_update_required: A firmware update, or a minimum firmware version, is required.
• software_version_required: A specific operating system, app, or software version is required.
• additional_component_required: An additional part, component, cable, or connection is required.
• configuration_change_required: A setting, configuration, or installation change is required.
• reduced_functionality: The products work together with some features, capacity, or performance reduced.

{
  "product_a": {
    "name": "Canon EF 50mm f/1.8 STM Lens",
    "category": "camera lens",
    "specifications": {
      "lens_mount": "Canon EF"
    }
  },
  "product_b": {
    "name": "Canon EOS R6 Camera Body",
    "category": "camera",
    "specifications": {
      "lens_mount": "Canon RF"
    },
    "compatibility_statements": [
      "EF and EF-S lenses can be used on EOS R series cameras with the Mount Adapter EF-EOS R."
    ]
  },
  "context": {
    "use_case": "Mount the lens on the camera body"
  }
}

{
  "request_id": "req_Zp4tR8cJw1MnB6yE",
  "status": "conditional",
  "compatible": null,
  "summary": "The products work together only if the listed conditions are met.",
  "checks": [
    {
      "requirement": "lens_mount",
      "status": "conditional",
      "method": "model_assisted",
      "product_a_value": "Canon EF",
      "product_b_value": "Canon RF",
      "explanation": "The values differ, and the products work together only through the documented adapter.",
      "evidence": [
        "product_a.specifications.lens_mount",
        "product_b.specifications.lens_mount",
        "product_b.compatibility_statements[0]"
      ]
    },
    {
      "requirement": "documented_condition",
      "status": "conditional",
      "method": "model_assisted",
      "explanation": "Supplied documentation states a condition for using the products together.",
      "evidence": [
        "product_b.compatibility_statements[0]"
      ]
    }
  ],
  "conditions": [
    {
      "type": "adapter_required",
      "description": "An adapter is required.",
      "requirement": "EF and EF-S lenses can be used on EOS R series cameras with the Mount Adapter EF-EOS R.",
      "evidence": [
        "product_b.compatibility_statements[0]"
      ]
    }
  ],
  "missing_information": [],
  "requires_review": true
}

Insufficient information

• specifications: One or both products have no specifications, or none that could be compared.
• model_number: A product has no model number or identifier, so its exact identity is ambiguous.
• compatibility_documentation: No supplied passage states whether these products work together.
• use_case_requirements: The compared specifications don't cover everything this use case depends on. Add requirements or documentation.

{
  "product_a": {
    "name": "Acme Smart Bulb"
  },
  "product_b": {
    "name": "HomeLink Hub"
  }
}

{
  "request_id": "req_Hk3mW9pQz2LsV7xN",
  "status": "unknown",
  "compatible": null,
  "summary": "There is insufficient information to establish compatibility.",
  "checks": [
    {
      "requirement": "technical_requirements",
      "status": "unknown",
      "method": "model_assisted",
      "explanation": "The supplied information doesn't establish every requirement for this use case.",
      "evidence": []
    }
  ],
  "conditions": [],
  "missing_information": [
    "specifications",
    "model_number",
    "compatibility_documentation"
  ],
  "requires_review": true
}

Code

curl https://kovca.io/api/v1/compatibility/check \
  -H "Authorization: Bearer $KOVCA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "product_a": {
    "name": "Example Ceramic Front Brake Pads",
    "category": "brake pads",
    "specifications": {
      "vehicle_make": "Honda",
      "vehicle_model": "Civic",
      "model_years": "2016-2021"
    }
  },
  "product_b": {
    "name": "2018 Honda Civic LX",
    "category": "vehicle",
    "specifications": {
      "make": "Honda",
      "model": "Civic",
      "model_year": 2018
    }
  },
  "context": {
    "use_case": "Install the brake pads on the vehicle'\''s front axle"
  },
  "requirements": [
    {
      "name": "make",
      "check": "equal",
      "value": "product_a.specifications.vehicle_make",
      "against": "product_b.specifications.make"
    },
    {
      "name": "model",
      "check": "equal",
      "value": "product_a.specifications.vehicle_model",
      "against": "product_b.specifications.model"
    },
    {
      "name": "model_year",
      "check": "in_range",
      "value": "product_b.specifications.model_year",
      "against": "product_a.specifications.model_years"
    }
  ]
}'

Errors

• 400 INVALID_REQUEST: a field is missing, too long, the wrong type, or not allowed, or a requirement path doesn't point at product_a or product_b specifications. The message names the field.
• 413 PAYLOAD_TOO_LARGE: the body is larger than 16 KB.
• 401 UNAUTHORIZED, 429 RATE_LIMITED, 503 SERVICE_UNAVAILABLE, 504 TIMEOUT: see Errors and limits.

Limitations

• Evaluates only what you send. There is no product database, web research, or document retrieval.
• Without requirements or documentation, results depend on interpreting shared specifications and are often unknown. For dependable results, send requirements.
• Your requirements compare text exactly after normalization; synonyms in your own data aren't merged.
• Not a guarantee. Treat unknown and requires_review: true as a signal for a person.
• Two products per request, with no multi-product configurations.
• Product information is processed to produce the result and is not stored or shared by Kovca.