Documentation

Overview

Releo is a change verification platform for APIs. When an API you publish or depend on ships a breaking change, Releo finds every affected call site across your repositories, writes the migration, and proves with replayed traffic that behavior did not change before the pull request can merge.

It is built for API providers migrating their customers, SaaS teams that depend on third-party APIs, agencies and integrators that maintain many client codebases, and teams running AI agents on top of changing schemas.

How Releo works

Every change moves through four stages. Each stage produces an artifact you can inspect.

1. Detect

Releo watches the upstream API descriptions you care about and diffs every release. Changes that would break existing callers are classified and summarized: what changed, which endpoints, and how. See what counts as a breaking change.

2. Scan

Releo maps the change onto your code: every repository, file and call site that touches an affected endpoint, field or SDK method. The result is the blast radius of the change across your fleet.

3. Generate

For each affected repository, Releo writes a patch and opens it as a pull request. It never pushes directly to a protected branch; your normal review process stays in charge.

4. Verify

Before a pull request can merge, Releo replays real requests against the old and new behavior and compares the full response envelope. If anything diverges, the pull request is blocked and the divergence report shows the exact request and field. See traffic replay testing.

Core concepts

Upstream: an API Releo watches for changes, whether you publish it or depend on it.
Change: a set of differences between two versions of an upstream, classified as breaking or non-breaking.
Blast radius: the repositories, files and call sites a change affects.
Migration: the set of pull requests Releo opens to absorb one change across your fleet.
Behavioral replay: sending the same recorded requests to the baseline and the candidate and comparing results.
Envelope: everything compared on each response: status code, headers, body and timing.
Divergence: any unexplained difference between baseline and candidate envelopes.
Policy: the rule that decides what happens on divergence. The default blocks the pull request.

Why verification is deterministic

The verdict on a migration never comes from a model grading its own output. It comes from running the same inputs through both versions and comparing the results field by field. The same requests produce the same verdict on every run, and every verdict comes with evidence a reviewer can check.

Fields that legitimately differ between runs, such as timestamps and generated IDs, are normalized before comparison so they do not hide real divergences.

Safety model

Changes arrive as pull requests; nothing merges without your review and passing verification.
Replay targets isolated environments, not production systems of record.
Sensitive values are redacted before traffic is stored for replay.
Enterprise plans can run replay workers inside your own infrastructure.

See Security for how we approach data handling during the beta.

Onboarding, step by step

Beta teams are onboarded with the founders. The flow below is what that looks like today; self-serve setup follows the same steps.

Connect your code host. Releo needs read access to the repositories in scope and permission to open pull requests and post status checks. It never needs write access to protected branches.
Choose your upstreams. Pick the APIs and SDKs to watch: ones you publish, ones you depend on, or both. Each upstream is described by its API description (for example an OpenAPI document) or its SDK release stream.
Provide a replay sample. Share a set of recorded requests for the endpoints in scope, with sensitive values redacted. You choose what is recorded and for how long it is kept.
Set a policy. Decide what happens on divergence (block, which is the default, or warn) and which fields are expected to differ.
Make the check required. In your branch protection rules, mark the Releo status check as required so a pull request with a divergence cannot merge.

Supported inputs

During the beta, Releo starts from machine-readable API descriptions (OpenAPI documents are the common case) and SDK releases for the languages our design partners use. Other formats and languages are prioritised by demand: tell us yours when you join the waitlist.

If an upstream publishes no description at all, detection can still work from recorded traffic, but the change summary is less precise. See OpenAPI diff for why a description is worth having.

Policies and normalization

A policy decides what counts as a divergence and what happens when one is found. Most of a policy is normalization: telling the diff which differences are expected.

Volatile fields such as timestamps, request IDs and generated identifiers are ignored or compared by format instead of value.
Unordered collections can be compared as sets when order carries no meaning.
Headers that vary per response (dates, tracing headers) are excluded by default.
Timing is compared against a latency budget rather than exactly.
Intended changes that are part of the migration (a renamed field, for example) are declared, so they are expected rather than flagged.

The default action on any remaining divergence is to block the pull request. A warn-only mode exists for rolling Releo out to a new repository. For a deeper treatment, read inside a behavioral diff.

Reading a divergence report

When verification fails, the status check links to a report that names the request, the field and both values. An illustrative excerpt:

{
  "pull_request": 4821,
  "replayed": 2418,
  "divergences": 1,
  "first": {
    "request": "POST /v2/charges",
    "field": "body.amount",
    "baseline": 4999,
    "candidate": 49,
    "hint": "amount is in minor units in v2"
  }
}

Fix the patch (or declare the change as intended if it is), push, and verification runs again on the new commit.

Integrations

Code host: pull requests and a required status check carrying the verification result.
Chat: a summary when a migration opens, and an alert when one is blocked.
Self-hosted replay (Enterprise): replay workers that run inside your infrastructure so recorded traffic never leaves it.

Exact integrations available during the beta are agreed per design partner.

Getting access

Releo is invite-only while in beta. Join the waitlist and tell us whether you publish an API, depend on APIs, run an agency, or build AI agents. When you are invited, we will ask which upstream APIs, spec formats and languages matter most to you; that shapes the onboarding.

Questions in the meantime: [email protected].

Releo documentation