Skip to content

Commit f44537f

Browse files
authored
Add Versioning section to Environments docs page (#668)
## Summary Adds a **Versioning** section to the Environments page in the Mintlify docs, right after the Base API URL it explains. Integrator-facing policy it documents: - The date in the base URL (`2025-10-13`) is the API's major version; a pinned version's behavior doesn't change. - Backwards-compatible (additive) changes land in the current version — with tolerant-reader guidance (ignore unknown fields, handle new enum values). - Breaking changes ship only in a new dated version; existing versions are unaffected and you upgrade on your own schedule. - Deprecation: notice to the account contact email with migration steps, and at least **three months** of continued support after notice. The three-month window and notice mechanism deliberately match the MSA (`mintlify/legal/msa.mdx` §7.1–7.2, three-month Migration Period) and the existing "notify the account contact email" language used for Service IP changes on the same page — no new commitments invented. ## Rendered page ![Environments page with new Versioning section](https://lightspark-dev-bolt-logs.s3.us-west-2.amazonaws.com/jobs/forked-diode/pr-media/1783470100665271180-environments.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=ASIAZ2JZJ7A7UKEDQJWU%2F20260708%2Fus-west-2%2Fs3%2Faws4_request&X-Amz-Date=20260708T002141Z&X-Amz-Expires=604800&X-Amz-SignedHeaders=host&X-Amz-Security-Token=IQoJb3JpZ2luX2VjELH%2F%2F%2F%2F%2F%2F%2F%2F%2F%2FwEaCXVzLXdlc3QtMiJGMEQCICu4gT6FiqnC4uhnJyvc0OQWbJDgTlaGtkRRYcMhrL5NAiBlcIXK2cjEMX5zUO9MVUnPPZhtimtupDWqRDADaQYXiir7BAh5EAAaDDY3NDk2NjkyNzQyMyIMMz1VLbGuOyK9%2FTxXKtgEfVhpEMqLiN5jboQDQkingDyv7%2FrRbyw7BsI%2FLkKTjjLKIn8Lj6NbceKRStv8oXNnkLz1gZkujsZipkWffDAiH7be2hL6%2FMf9efIRr5ZIyRXczS8DX9j29mbBmUVN4t0poaBu%2FXUQ8gXy%2FC7dWVgEqWMk2fiEYK9QdHhVgRdtTNP6%2FLAqKMH65qFK1it690RU3Cktufv1HP%2BAmsBErYNoEnKjsfg6Z2ObyggB0ZpeoruqSX7luxx7cfxyEXbhd%2BgULQgObXdFk0DdVL2OmMoygLWUco9O0arneSBpPkOlvsT1OZ%2ByL6H%2BLlfoeB9vH%2FE4fhuLAhd7BQBI8Tlj9f3tn7gQ%2FcBSuZ4lOYGh%2FO2Cy9OixttevMUNND2HrlGGg8z9e9oL%2FzLppkIs28nMTopZMn4ZJTHW8m0A5XVqu5mrDh4grM8sb%2FgwqJAvT3w1N9GQQmtMnhUqwz6evrQWQwvGs6dUNylTQEb5uQkIW1rorBfxPME73%2FHSuNdkqt1ImizJM4Dy2jlUMYTVsp7E3tZOxR2b7SY5Qs2Tc6c9hQkFRwx39pbfNXwotZibYWeea4XJZfAzYH8ScRsJfBadA0pTZMu11VLXcag1YgP73KoiVTd5kxLQkvcQUlhWf1QfPxszGXnFS4UtMp5%2F1Z8TL25fGUsaxVc4rY0Rrr2vyy3EJ8GraFpZ9N56htieHKMWUo%2Bv0RVobt8wyeleD5d58fR0HnS1Yc58auyvSRujWo6XPq%2FMyg6madI77deYEF%2BlIYN%2FpkDtUDhTv4sr1IsMolmELN6bERyuJXfkMJWwttIGOpkB61XkrezUSRxMSRvc7CYQAUFkV5p%2B6a7UthfnLov0gtYQxqmgyApfTDKB6XqxMOXmg02yqgK4Crx77oW0BiqGoF%2FE%2B2Kff4oWhE%2FiAVSlsC3MVPti0tF6UfxXXC8FqCDfzMCIn757jwYbOIlxc9V8vpd%2FwK6Z%2FeyKMqtB0WnVi2K4fvoa7B3fDNglPeoHp0Gb3SPjGPmLp7GR&X-Amz-Signature=e4bae1e4e75e16435af5eaa847027804bbc2c6c96b04b12eba6495b445300372) ## Test plan - Rendered locally with `mint dev` (pinned CLI 4.2.284) — screenshot above. - `mint broken-links`: no new findings (pre-existing broken links in untouched files only). - Docs-only change; OpenAPI spec untouched. Slack thread: https://lightsparkgroup.slack.com/archives/D0AHLSKKV8R/p1783469743603179 --- 🤖 [forked-diode](https://zeus.dev.dev.sparkinfra.net/#/arc?id=forked-diode)[(#1)](https://zeus.dev.dev.sparkinfra.net/#/instance?id=forked-diode) | [Feedback](https://zeus.dev.dev.sparkinfra.net/feedback) Original PR: #667 --------- Co-authored-by: Jeremy <jeremy@lightspark.com>
1 parent b98f162 commit f44537f

1 file changed

Lines changed: 10 additions & 0 deletions

File tree

mintlify/api-reference/environments.mdx

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,16 @@ import { topLevelProductName } from '/snippets/variables.mdx'
1010
## Base API URL
1111
`https://api.lightspark.com/grid/2025-10-13`
1212

13+
## Versioning
14+
15+
The date in the base URL is the API's major version. Your integration pins a version through the URL it calls, and that version's behavior does not change underneath you.
16+
17+
**Backwards-compatible changes.** We may extend the current version without changing the date: new endpoints, new optional request parameters, new response fields, and new enum values or webhook event types. Build your integration to ignore unrecognized response fields and to handle unfamiliar enum values gracefully.
18+
19+
**Major version changes.** Breaking changes — removing or renaming fields or endpoints, changing types, or making optional parameters required — ship only in a new dated version. Releasing a new version does not affect existing ones; you upgrade by changing the date in the URL whenever you are ready.
20+
21+
**Deprecation.** When we deprecate a version, we notify your account contact email with the migration steps and a deadline. The migration window is normally at least three months; updates critical to security or compliance may require faster action. After the window, deprecated versions are no longer supported.
22+
1323
## Sandbox
1424
Sandbox enables you to test your integration without making real payments. In sandbox, we expose sandbox specific APIs to trigger specific test cases like incoming payments. Additionally you'll find test UMA addresses to simulate different sending scenarios. For more information, see [Sandbox Testing](sandbox-testing).
1525

0 commit comments

Comments
 (0)