> 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 well in advance
2. Provide migration guidance
3. Maintain the old behavior alongside the new one when possible
4. 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://hub.equipme.io/development/versioning-and-compatibility.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.