Changelog

Changes to the API contract, and the policy that governs breaking ones.

Preview, and the surface is live. The contract is versioned 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.
Correction, 2026-08-30. This page previously stated that the /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.

Corrections, 2026-08-31
ChangeWhat was wrongWhat to do
organization_id is a UUIDThe 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 removedDeclared 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 enabledPublished 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 typesThe 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.

Contract changes in the preview period
ChangeWhy
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 valueslikely_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 vocabularymet, not_met, unknown. The draft enum was invented; these are the values the evaluator emits.
q maximum length reduced from 500 to 200Matches the length the handler actually validates. The contract promised more than the code accepted.
Sixteen operations marked as plannedAnything 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 usageGET /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 behaviourA 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 gate
# Fails the build on any breaking change:
oasdiff breaking --fail-on ERR <base> api/openapi/gfin-v1.yaml

# Overriding requires stating why, in the commit:
OPENAPI_ALLOW_BREAKING="<reason>" bash scripts/check-openapi.sh

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

What counts as a breaking change
BreakingNot breaking
Removing an operation or fieldAdding an optional request parameter
Making an optional parameter requiredAdding a new operation
Removing an enum value from a responseAdding a new optional response field
Narrowing an accepted range or lengthRelaxing a validation rule
Adding an enum value to a response is not flagged as breaking, but it can still surprise a client that switches exhaustively over the current set. Treat unknown enum values as a case you handle, not a case that cannot happen.

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.