Changelog
Changes to the API contract, and the policy that governs breaking ones.
1.0.0-preview and is still being corrected against the implementation, so a change below may affect you. If you integrated before 2026-08-31, re-check three things: the organization_id format correction below, the EligibilityVerdict value removal, and the q maximum length reduction from 500 to 200./v1 surface had never been armed and that no change here could have affected a caller. That was wrong: the surface is armed and serving. We are recording the error rather than quietly deleting it, because you may have relied on it when deciding not to re-check your integration.2026-08-31: contract corrected against the implementation
Four places where the published contract described something the platform does not do. All four are the contract being corrected, not behaviour changing: nothing about how the API responds is different today than it was yesterday.
| Change | What was wrong | What to do |
|---|---|---|
organization_id is a UUID | The schema declared ^org_[0-9a-f]{24}$. Organizations have always been identified by a UUID, so every response carrying organization_id, including GET /ping, violated the published schema. The examples showed the org_… form too. | If you generated a client from this contract and it validates responses, it was rejecting valid responses. Regenerate. |
EligibilityEvaluation.id removed | Declared required and never once emitted. Evaluations are computed per request and not stored, and GET /eligibility-evaluations/{id} is still planned, so the field would have been an identifier you could not look up. | Nothing. No response ever contained it. |
POST /webhook-endpoints marked not enabled | Published as a live operation. It answers 503 UNSUPPORTED_OPERATION for every caller and always has, because webhook delivery is not switched on. Registration is refused rather than accepted-and-ignored, so that you cannot come to believe you are subscribed. | The request and response shapes are final. Watch this page for the change that enables delivery. |
| Subscription example used unregistered event types | The example offered com.gofunditnow.match.created and com.gofunditnow.opportunity.deadline_changed. Neither type exists and nothing emits either, so copying the example produced a rejected subscription. Only registered types are accepted. | The example now uses real types. CI now fails if the contract names an event type the registry does not admit. |
Preview, 2026-08
The contract was written first and then corrected against the code as each lane was built. Most changes below are the contract being made to match what actually ships, which is the direction we want that correction to run.
| Change | Why |
|---|---|
Removed GET /funders and GET /funders/{funder_id} | There is no funder entity in the system. The endpoints described a resource that does not exist, so they were removed rather than stubbed. Funder is available as a filter on the catalog instead. |
EligibilityVerdict reduced to three values | likely_eligible, not_eligible, needs_profile. A fourth draft value was a per-dimension status, not a roll-up verdict, and would have had no producer. |
Factor result now uses the shipped vocabulary | met, not_met, unknown. The draft enum was invented; these are the values the evaluator emits. |
q maximum length reduced from 500 to 200 | Matches the length the handler actually validates. The contract promised more than the code accepted. |
| Sixteen operations marked as planned | Anything not implemented now carries x-gfin-status: planned and says so in its summary. Publishing an endpoint that answers 404 as though it were live is the failure mode this closes. |
| Added webhook endpoint listing and usage | GET /webhook-endpoints and GET /usage moved from planned to live. Corrected 2026-08-31: this entry also claimed POST /webhook-endpoints had moved to live. It had not. It answers 503 with code UNSUPPORTED_OPERATION for every caller, because webhook delivery is not switched on. See the 2026-08-31 corrections at the top of this page. |
| Documented sandbox behaviour | A gfin_test_ key is served synthetic fixtures with the same schemas, pagination, filters and errors as live. The one difference, substring rather than keyword matching on q, is stated rather than left to be discovered. |
How breaking changes are handled
Every change to the contract runs through oasdiff in CI against the version on the deploy branch. A breaking change fails the build. It can only land if someone sets an explicit override variable carrying a written reason, which lands in the diff for a reviewer to see.
The point is not that a breaking change is impossible. It is that one cannot happen quietly: it takes a deliberate act that leaves a written record.
What counts as a breaking change
| Breaking | Not breaking |
|---|---|
| Removing an operation or field | Adding an optional request parameter |
| Making an optional parameter required | Adding a new operation |
| Removing an enum value from a response | Adding a new optional response field |
| Narrowing an accepted range or length | Relaxing a validation rule |
Versioning
The contract is 1.0.0-preview and the surface is /v1. While it stays in preview, corrections like the ones above are expected. Once it is generally available, the path version changes only for a change that cannot be made compatibly, and the previous version keeps working for a stated period rather than being switched off.