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, ranges, 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&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, ranges, 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", "1.28"]
    }
  ]
}

Get project compatibility data

Returns the complete compatibility document for one project, including known versions, dependency keys, ranges, 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"],
          "relationship": "bundled"
        },
        "openshift-management-cluster": {
          "ranges": [">=4.19 <4.22"],
          "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 ranges.

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

{
  "project": "keycloak",
  "version": "26",
  "dependency": "postgresql",
  "dependencyVersion": "17",
  "compatible": "compatible",
  "matchedRange": ">=14.0.0 <19.0.0",
  "relationship": "database",
  "confidence": "high",
  "lastVerified": "2026-07-08",
  "notes": [
    "Keycloak current 26.x supported configurations list PostgreSQL 18.x, 17.x, 16.x, 15.x, and 14.x."
  ],
  "sources": [
    {
      "title": "Keycloak Supported Configurations - Supported Databases",
      "url": "https://www.keycloak.org/server/supported-configurations",
      "accessedAt": "2026-07-08"
    }
  ]
}

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",
      "openshift-hosted-cluster": "4.21.22"
    }
  }'

{
  "project": "red-hat-advanced-cluster-management",
  "version": "2.16",
  "dependencies": {
    "multicluster-engine": "2.11",
    "openshift-management-cluster": "4.21.22",
    "openshift-hosted-cluster": "4.21.22"
  },
  "compatible": "compatible",
  "checks": [
    {
      "dependency": "multicluster-engine",
      "dependencyVersion": "2.11",
      "compatible": "compatible",
      "matchedRange": "2.11",
      "relationship": "bundled"
    },
    {
      "dependency": "openshift-management-cluster",
      "dependencyVersion": "4.21.22",
      "compatible": "compatible",
      "matchedRange": ">=4.19 <4.22",
      "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 a documented compatible range.

incompatible

The dependency is known for that project version, but the requested version did not match any documented compatible range.

unknown

The project, project version, dependency, or evidence is not known.

Response fields

Field	Description
`compatible`	Aggregate or single check result: compatible, incompatible, or unknown.
`matchedRange`	The documented range that matched the requested dependency version, or null.
`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.

Evidence model

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.