> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ycloud.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API versioning and compatibility

> Handle compatible API changes, opaque identifiers, new event types, and URI versions.

YCloud uses URI versions for breaking API changes. The current API base URL is
`https://api.ycloud.com/v2`.

## Backward-compatible changes

Your integration must tolerate these changes within the same API version:

* New API resources.
* New optional request parameters on existing operations.
* New response properties, or a different order of response properties.
* Changes to the length or format of opaque strings, including object IDs,
  error messages, and other human-readable strings.
* New enum values, including new webhook event types.

Ignore response properties you do not use. Handle unfamiliar event types
without failing your entire webhook receiver. Use documented error codes for
control flow instead of matching a human-readable error message.

## Store opaque identifiers

Treat object IDs as opaque, case-sensitive strings. Do not infer meaning from
an ID's length or a prefix such as `evt_`; prefixes can be added or removed.
YCloud-generated object IDs do not exceed 255 characters. Allow that full
length in your storage.

For example, a MySQL column can use `VARCHAR(255) COLLATE utf8_bin` to preserve
case-sensitive comparisons.

## Breaking changes

A breaking change uses a different version in the request URI. For example:

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
https://api.ycloud.com/v1/balance
https://api.ycloud.com/v2/balance
```

Use the version documented for your integration. Do not change the version
segment without checking the request, response, and webhook contracts.

See the [API changelog](/en/api-reference/getting-started/changelog) for historical changes.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.