API

HTTP API v1

Query compatibility metadata as JSON. Start with the project index, inspect a project for its version and dependency keys, then run single or compound compatibility checks.

Quickstart

Discover, inspect, check

Dependency keys are project-specific. Use the project document as the source of truth before calling the check endpoint.

1. List projects

Find the stable project id to use in later requests.

curl https://compatibility.fyi/api/v1/projects

2. Inspect one project

Read the available versions, dependency keys, constraints, evidence, and sources.

curl https://compatibility.fyi/api/v1/projects/red-hat-advanced-cluster-management

3. Check compatibility

Ask whether one dependency version is compatible with one project version.

curl "https://compatibility.fyi/api/v1/check?project=keycloak&version=26.7&dependency=postgresql&dependencyVersion=17"

Endpoints

Method	Path	Purpose
GET	`/api/v1/projects`	Discover project ids and high-level metadata.
GET	`/api/v1/projects/{project}`	Inspect versions, dependency keys, constraints, and evidence.
GET	`/api/v1/check`	Check one project/dependency version pair.
POST	`/api/v1/check`	Check a full project version combination.

List projects

Returns the public project index. Use this endpoint to discover stable project ids for tools and integrations.

GET/api/v1/projects

curl https://compatibility.fyi/api/v1/projects

{
  "projects": [
    {
      "id": "cloudnativepg",
      "name": "CloudNativePG",
      "categories": ["Databases"],
      "website": "https://cloudnative-pg.io/",
      "versions": ["1.30", ">=1.29.2 <1.30", ">=1.29.0 <1.29.2"]
    }
  ]
}

Get project compatibility data

Returns the complete compatibility document for one project, including known versions, dependency keys, constraints, evidence basis, confidence, notes, sources, and verification dates.

GET/api/v1/projects/{project}

Name	In	Required	Description
`project`	path	yes	Project id from /api/v1/projects.

curl https://compatibility.fyi/api/v1/projects/red-hat-advanced-cluster-management

{
  "id": "red-hat-advanced-cluster-management",
  "name": "Red Hat Advanced Cluster Management for Kubernetes",
  "categories": ["Cluster Management"],
  "versions": {
    "2.16": {
      "dependencies": {
        "multicluster-engine": {
          "ranges": ["2.11"],
          "basis": "bundled",
          "relationship": "bundled"
        },
        "openshift-management-cluster": {
          "ranges": [">=4.19 <4.22"],
          "basis": "supported",
          "relationship": "hub runtime"
        }
      }
    }
  }
}

Check one dependency

Checks one dependency version against one project version. This is the simplest endpoint for Renovate-style compatibility decisions.

GET/api/v1/check

Name	In	Required	Description
`project`	query	yes	Project id from the project index, for example keycloak.
`version`	query	yes	Project version to evaluate.
`dependency`	query	yes	Dependency key from the project document.
`dependencyVersion`	query	yes	Dependency version to test against the documented constraints.

curl "https://compatibility.fyi/api/v1/check?project=keycloak&version=26.7&dependency=postgresql&dependencyVersion=17"

{
  "project": "keycloak",
  "version": "26.7",
  "dependency": "postgresql",
  "dependencyVersion": "17",
  "compatible": "compatible",
  "reason": null,
  "basis": "supported",
  "matchedRange": ">=14.0.0 <19.0.0",
  "matchedConstraint": null,
  "relationship": "database",
  "confidence": "high",
  "lastVerified": "2026-09-11",
  "notes": [
    "Keycloak 26.7 supported configurations list PostgreSQL 18.x, 17.x, 16.x, 15.x, and 14.x."
  ],
  "sources": [
    {
      "title": "Keycloak 26.7.3 supported database versions",
      "url": "https://raw.githubusercontent.com/keycloak/keycloak/26.7.3/docs/guides/server/templates/databases.adoc",
      "accessedAt": "2026-09-11"
    }
  ]
}

Check a combination

Checks a project version against multiple dependencies in one request and returns an aggregate result plus individual checks.

POST/api/v1/check

Name	In	Required	Description
`project`	body	yes	Project id from the project index.
`version`	body	yes	Project version to evaluate.
`dependencies`	body	yes	JSON object where keys are dependency ids and values are dependency versions.

curl -X POST https://compatibility.fyi/api/v1/check \
  -H "content-type: application/json" \
  -d '{
    "project": "red-hat-advanced-cluster-management",
    "version": "2.16",
    "dependencies": {
      "multicluster-engine": "2.11",
      "openshift-management-cluster": "4.21.22"
    }
  }'

{
  "project": "red-hat-advanced-cluster-management",
  "version": "2.16",
  "dependencies": {
    "multicluster-engine": "2.11",
    "openshift-management-cluster": "4.21.22"
  },
  "compatible": "unknown",
  "checks": [
    {
      "dependency": "multicluster-engine",
      "dependencyVersion": "2.11",
      "compatible": "unknown",
      "reason": "bundle-only",
      "basis": "bundled",
      "matchedRange": "2.11",
      "matchedConstraint": null,
      "relationship": "bundled"
    },
    {
      "dependency": "openshift-management-cluster",
      "dependencyVersion": "4.21.22",
      "compatible": "compatible",
      "reason": null,
      "basis": "supported",
      "matchedRange": ">=4.19 <4.22",
      "matchedConstraint": null,
      "relationship": "hub runtime"
    }
  ]
}

A GET variant is also accepted by passing a URL-encoded JSON object in the dependencies query parameter. POST is recommended for compound checks because it is easier to read and avoids URL length limits.

Result semantics

compatible

The dependency version matched supported or tested compatibility evidence.

incompatible

The requested version matched an explicit, source-backed incompatibility entry. Missing a supported range never produces this result.

unknown

No compatibility evidence covers the requested combination, or the matching evidence is only a recommendation, a bundle, or explicitly unverified.

For compound checks, any explicit incompatibility makes the aggregate incompatible. Otherwise, any unknown check makes it unknown. All checks must be compatible for a compatible aggregate. Unknown is not evidence that an upgrade will fail or succeed.

Response fields

Field	Description
`compatible`	Aggregate or single check result: compatible, incompatible, or unknown.
`reason`	Machine-readable explanation for an unknown single check, or null for compatible/incompatible. Included on each compound checks item, not the aggregate. Older responses may omit it.
`basis`	Evidence kind: supported, tested, recommended, or bundled. Null when no entry or only explicitly unknown evidence is available. A basis alone does not establish compatibility.
`matchedRange`	The evidence range that matched the requested version, or null. A match may be only a recommendation or bundle.
`matchedConstraint`	Set to same-version when an exact-version constraint matched; otherwise null. Check compatible and basis to interpret the match.
`relationship`	How the project uses the dependency, such as runtime, bundled, or installer.
`confidence`	Evidence quality: high, medium, or low.
`lastVerified`	Date when the compatibility evidence was last verified, or null.
`sources`	Source documents used to verify the entry.

Unknown reasons

Field	Description
`project-not-found`	The project id is absent from the catalog.
`project-version-not-found`	The project exists, but no version row covers the requested project version.
`dependency-not-found`	The selected project version has no entry for this dependency key.
`dependency-version-not-covered`	The dependency entry exists, but none of its version constraints match.
`recommendation-only`	The requested versions match recommended alignment, not support or test evidence.
`bundle-only`	The requested versions match a bundle, which does not establish compatibility.
`explicitly-unknown`	The dependency entry explicitly records an unknown or unverified state.

Missing project, project version, or dependency metadata is reported at the first failed lookup. An explicitly unknown entry returns explicitly-unknown. Otherwise, a version outside the entry’s constraints returns dependency-version-not-covered, even for recommended or bundled evidence. recommendation-only and bundle-only require a matching constraint. These diagnostics do not change the compatibility verdict.

Evidence model

supported: upstream documents support. This is the default when basis is omitted in project data.
tested: upstream explicitly tests these versions; this is distinct from a vendor support policy.
recommended: upstream recommends these versions, without establishing full compatibility.
bundled: upstream ships these versions together, without establishing general compatibility.

A matched range or same-version constraint identifies evidence, not necessarily a compatible result. Recommendations and bundles return unknown even when they match. The relationship field describes how the dependency is used; it does not determine the evidence basis. Notes and sources may describe an existing entry even when its constraints do not match the request.

High confidence means the entry is backed by official project documentation or tagged upstream source and includes a verification date. Compatibility data can still become stale, so clients should expose sources and verification dates where possible.

Input limits and errors

Required values must be non-empty strings of at most 128 characters. Compound checks accept between 1 and 32 dependency entries. POST bodies must use application/json and are limited to 16 KiB.

400 — missing, malformed, empty, or out-of-range input.
404 — unknown API route or project document.
405 — unsupported HTTP method.
413 — POST body exceeds 16 KiB.
415 — POST body is not declared as JSON.