Integration Readiness Reviewer

Find where your API docs will lose a developer, before they do.

Integration Readiness Reviewer reads your OpenAPI file and guide pages, then hands back a report where every finding points to the exact place it came from. No AI model in the loop: the same input always gives the same report.

Ask for a free first review See a real sample report

A few organisations at a time get a free first review. We reply within one working day.

Three things come back, and each one holds up when someone asks why.

A report that says what, where and why it matters

Each finding names the operation, says whether the thing is missing or contradicts itself, explains the impact in plain words and suggests a fix. Findings with the same cause are grouped, so 53 missing error responses read as one problem to fix, not 53 tickets.

Read the full sample report

Biggest causes in the sample review

CausePlaces
Mediumno error response documented53
Mediumrequired parameter without description42
Lowweak description: restates its name9
Mediumno pagination5
Lowresponse without description4

A teardown you can print and hand to a lead

One self-contained page: counts, causes, coverage, and the checks that could not be made. No grade, no generated prose, no pass or fail stamp. Every figure is a count, a sum or a sort, so you can check it.

Open the sample teardown

What ran, in the sample review

41 rulesCount
Ran21
Did not apply to this API14
Could not be assessed4
Switched off by default2

A diff that only claims a fix when it can show one

Review the next release and see what was resolved, what is still there and what is new. A fix counts only when the same check ran again over the whole input, so a rule that could not run is never reported as fixed. The diff also catches what a fix broke.

Look at the sample diff

Sample revision, compared with the first review

Resolved56Still there71New1

Built to be argued with.

A documentation review is only useful if the people receiving it can check it. Everything here is designed for that.

  • Evidence on every finding

    The exact place in your file, what was looked for and not found, and a confidence. No finding without a pointer.

  • Same input, same report

    Fixed rules and local text checks. Nothing is sampled, nothing varies from run to run, and nothing about your documentation goes to a model.

  • It tells you what it could not check

    A check that needs input you did not give is reported as "could not be assessed". It is never a pass and never takes points off.

  • Examples are checked, not skimmed

    Every example in your specification is validated against its own schema by computation. Any example it cannot check is listed in the report, not skipped quietly.

  • It reads the guide too

    Give it a specification and a guide site or a folder of Markdown. A gap your guide already answers is not reported as a gap.

  • No single score

    Each area has its own sub-score, with coverage and a trace of every deduction. One number would hide where the documentation actually hurts.

All features

Every finding shows its work.

This is one finding from the sample review, exactly as the reviewer wrote it.

HighCC-SCHEMA-01 Request or response declares a structured content type but no schema

GET /api/fulfilment-capacity/resources/carrier@{capacityType}@{shippingPolicyId}/time-frames/{windowDay}F{windowStartTime}T{windowEndTime}: response declares application/json but no schema

Operation
GET /api/fulfilment-capacity/resources/carrier@{capacityType}@{shippingPolicyId}/time-frames/{windowDay}F{windowStartTime}T{windowEndTime}
State
Not in the specification
Evidence
Not found: a schema for application/json. Looked at fulfilment-api.json#/paths/~1api~1fulfilment-capacity~1resources~1carrier@{capacityType}@{shippingPolicyId}~1time-frames~1{windowDay}F{windowStartTime…
Impact
Developers cannot know the fields, types or required properties, and generated clients fall back to untyped data.
Recommendation
Add a schema to each structured media type, or remove the media type if no body is exchanged.

Confidence 1.00 · fingerprint 3793ec222369

We tested whether this is just a prompt. Mostly, it is not, and sometimes it is.

We gave the same documentation faults to our rules, to a popular linter and to an AI assistant. The assistant did very well on a small file. On very large files, reading alone missed most invalid examples, and it matched the reviewer only when told exactly what to compute.

We publish the numbers with their limits: our own faults, one model, small samples, one labeller. If your team can build this yourselves, you will see how.

How we measureRead the write-up

35 of 35seeded faults found by the rules, on one small specification. Written by us, so read it as a floor, not a claim.
34 of 35found by an AI assistant reading the same file, with one run each.
6 of 78invalid examples found by an assistant that only read two very large files. Told to compute, it matched the reviewer.

Questions people ask first

Does it use AI?

No. This version uses fixed rules and small local text checks, with no language model. That is why the same input always gives the same report, and why nothing about your documentation is sent to a model. It is a design choice with a cost, and we write about that cost in the study linked below.

What do you need from me?

An OpenAPI 3.0 or 3.1 file or a Swagger 2.0 file. If you have a developer guide, add its web address or a folder of Markdown files. The reviewer then also checks links, code samples and whether the guide and the specification agree, and it will not report a gap that your guide already answers.

What happens to my files?

For a free first review we run the reviewer ourselves, send you the report, and delete your files afterwards unless you ask us to keep them. The reviewer fetches only public web addresses, follows robots.txt, and runs without a model. If you need it inside your own network, it can run on one machine with Docker Compose.

How is this different from an API linter?

A linter checks that the file is well formed. This reads it the way a new integrator would: are errors documented, are retries safe, how do you page, what are the rate limits, does every example match its own schema. In our test, a popular linter reported on the same cause as only 8 of 35 seeded faults. That test has limits, which the study spells out.

Could an AI assistant do the same?

For many checks, yes, if it is prompted well. In our test an assistant that read a small file found 34 of 35 seeded faults. On very large files, reading alone missed most invalid examples, and a script-driven assistant matched the reviewer only when told exactly what to compute. The difference is repeatability, speed and an explicit statement of what was not checked. We would rather you read the numbers than take our word for it.

What does it not do yet?

It does not call your live API, monitor your documentation over time, comment on pull requests, or block a merge. It does not score documentation with a single grade, and it does not judge whether a description is true, only whether it exists, is consistent and checks out against the file.

How do I get a free first review?

Use the contact form and say you would like a review. We reply within one working day. A few organisations at a time get a free first review.

Want your API reviewed?

Send us your OpenAPI file, or the address of your docs. We will run the review and send you the report, the teardown and what we would fix first. A few organisations at a time get this free, and we reply within one working day.

Ask for a free first review