Skip to main content

Versioning and deprecation

The version is in the path. Every published endpoint sits under a versioned prefix:

https://api.because.eco/api/v1/
https://api.because.eco/api/v2/

There is no version header, and no way to pin a minor version — the path version is the contract. Versioning is per endpoint, not per API: most endpoints live under v1, and a v2 exists where a result model had to change shape — the bulk searches, several of the bulk upserts, and the bulk task endpoints. The guarantees below hold within each version.

What we may change without a new version​

Treat these as expected, and build so they do not break you:

  • New fields in responses. Ignore fields you do not recognise rather than failing on them.
  • New optional fields in requests.
  • New endpoints, and new sections in this reference.
  • New errorCode values. Handle an unrecognised code as a generic failure of its status class.
  • Wording of message in an error, and of any human-readable text. Never parse these.

A client that deserialises strictly, rejecting unknown fields, will break on a routine addition. Deserialise leniently.

What we will not change within a version​

  • Removing an endpoint, or changing its path or method.
  • Removing a field from a response, or changing its type.
  • Making a previously optional request field required.
  • Changing what an existing errorCode means.

Deprecation​

A deprecated endpoint keeps working — deprecation never breaks a running integration. What changes is this reference: a deprecated endpoint leaves it, so the documented surface is always the recommended one. If an endpoint you call is no longer documented here, it still answers exactly as before; you should plan to move to its successor.

The endpoints currently in this state, and where to move:

No longer documented, still answeringMove to
POST /api/v1/bulk/companies/searchPOST /api/v2/bulk/companies/search and POST /api/v2/bulk/standards/holders/search
GET /api/v1/bulk/companies/search/latest-filethe v2 task's page URLs
POST /api/v1/bulk/standards/searchPOST /api/v2/bulk/standards/search
GET /api/v1/bulk/standards/search/latest-filethe v2 task's page URLs
POST /api/v1/bulk/framework-answers/searchPOST /api/v2/bulk/framework-answers/search
POST /api/v1/bulk/calculators/searchPOST /api/v2/bulk/calculators/search
POST /api/v1/bulk/performance-answers/upsertPOST /api/v2/bulk/framework-answers/upsert
POST /api/v1/bulk/consolidated/upsert-standard-holdersPOST /api/v2/bulk/companies/upsert and POST /api/v2/bulk/standards/holders/upsert
POST /api/v1/bulk/companies/upsertPOST /api/v1/bulk/company-mappings
GET /api/v1/bulk/status/{correlationId}GET /api/v2/bulk/tasks/{correlationId}
GET /api/v1/custom-properties/custom-identifiersGET /api/v1/custom-properties

If we ever need to remove something, that is a new version — an existing version will not have endpoints deleted underneath it.

The specification​

The reference on this site is generated from the OpenAPI document that the API itself produces at build time, so it cannot drift from the deployed contract. If you generate clients, generate them from that document rather than transcribing this site by hand.

Questions about a change you have spotted go to support@because.eco.