> For the complete documentation index, see [llms.txt](https://docs.growsurf.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.growsurf.com/developer-tools/rest-api/api-lifecycle.md). # API Lifecycle Policy Learn how GrowSurf versions the REST API and guarantees notice before breaking removals. GrowSurf versions the REST API in the URL. The current base URL is `https://api.growsurf.com/v2`. This policy takes effect on August 25, 2026. ## Compatible changes GrowSurf can add backward-compatible functionality within an existing API version. Examples include new endpoints, new optional request fields, and new response fields. Clients should ignore response fields they do not use. A breaking contract change requires a new API version. GrowSurf can make an urgent breaking change with less notice only when security, privacy, legal, or service-integrity requirements make the existing behavior unsafe or unlawful. ## Minimum notice GrowSurf gives at least 12 calendar months of public notice before a planned breaking removal. The notice period starts when GrowSurf marks the affected surface as deprecated in the public OpenAPI schema and publishes the migration guidance. The removal date cannot be earlier than the same calendar date 12 months later. The 12-month minimum does not apply to an urgent security, privacy, legal, or service-integrity change. GrowSurf will explain the exception and publish a migration path as early as practical. ## Deprecation signals When GrowSurf schedules a breaking removal, it uses these signals: * The OpenAPI operation, parameter, or schema field has `deprecated: true`. * Responses from the affected resource include an RFC 9745 `Deprecation` header with the deprecation timestamp. * If GrowSurf has set a removal date, responses include an RFC 8594 `Sunset` header with that date. * The API documentation identifies the replacement, migration steps, and known compatibility differences. Every REST API response carries a `Link` header with `rel="deprecation"` pointing to this policy, whether or not anything is deprecated. Per RFC 9745, that link on its own says where the policy lives; it does not mark the resource as deprecated. Read the `Deprecation` header to tell the difference: no `Deprecation` header means the resource is not deprecated. When GrowSurf schedules a removal, the linked documentation adds the migration guidance for it. A deprecated feature can remain available without a scheduled removal. In that case, GrowSurf can mark it in OpenAPI and documentation without sending a `Sunset` header. The 12-month removal window starts when GrowSurf publishes the migration guidance and planned removal. ## Client guidance Check the [OpenAPI schema](https://growsurf.com/openapi.json) during development and before dependency updates. Treat `Deprecation` as a migration signal. If a response also has `Sunset`, complete the migration before that date. Contact [GrowSurf Support](https://growsurf.com/settings#contact_support) if a published migration path does not cover your integration. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.growsurf.com/developer-tools/rest-api/api-lifecycle.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.