> For the complete documentation index, see [llms.txt](https://hub.equipme.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://hub.equipme.io/development/versioning-and-compatibility.md). # Versioning and Compatibility ### Current Version Our API is currently at **version 1** (`/v1/`). All endpoints are accessed through this version prefix in the base URL: ``` https://api.equipme.io/v1/ ``` *** ### Compatibility Commitment We are committed to maintaining backward compatibility and avoiding breaking changes wherever possible. Our approach to API evolution: #### Additive Changes The API evolves primarily through additive changes that don't break existing integrations: **What we add:** * New endpoints * New optional fields in request bodies * New fields in response bodies * New optional query parameters * New error codes with descriptive messages **Your integration should:** * Ignore unknown fields in responses * Not rely on field order in JSON responses * Handle new optional parameters gracefully * Be prepared for new error codes #### Non-Breaking Changes These changes are considered safe and may be introduced without notice: * Adding new endpoints * Adding new optional request parameters * Adding new fields to responses * Adding new values to enums (where documented as extensible) * Changing error messages (error codes remain stable) * Adding new error codes * Performance improvements #### Breaking Changes We actively avoid breaking changes. If a breaking change becomes necessary, we will: 1. Announce it and provide migration guidance 2. Maintain the old behavior alongside the new one when possible 3. Mark deprecated endpoints clearly in the API Reference **Examples of breaking changes we avoid:** * Removing endpoints * Removing fields from responses * Making optional parameters required * Changing field data types * Changing authentication mechanisms *** ### Deprecated Endpoints Some endpoints are marked as **obsolete** in the API Reference. These are typically older endpoints that have been replaced with improved alternatives. **Current obsolete endpoints:** * Several PUT endpoints have been replaced with PATCH alternatives using JSON Patch * Obsolete endpoints continue to work but are not recommended for new integrations Check the API Reference for specific deprecation notices and recommended alternatives. *** ### API Changes & Release Notes API changes are documented in our general Release Notes. **What's included:** * New endpoints and features * Changes to existing endpoints * Deprecation notices * Bug fixes affecting API behavior We recommend subscribing to release notes updates to stay informed about API improvements. *** #### Version Your Integration Document which API version and features your integration uses. This helps with troubleshooting and planning updates. --- # 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 by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://hub.equipme.io/development/versioning-and-compatibility.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. 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.