# API versions

> What each version of the API added, and which versions a Hub serves.

The API has its own version, separate from the plugin's. `hub.version` gives it; `getHub(app, wanted)` checks it for you.

## Compatibility

- A Hub serves a plugin built for the same major version and the same or an older minor.
- Before 1.0, a Hub serves only the minors it promises. The current Hub, at API **0.4**, serves plugins built for 0.1, 0.2, 0.3 and 0.4.
- Ask for the oldest version that has what you use, so your plugin works with more Hubs.

## What each version added

| Version | Added |
|---|---|
| **0.4** | Tiers of the user's own: `createTier`, `deleteTier`, and `id`, `name` and `custom` on every tier. Roles name a tier by id or by name. `registerSkills`, `skillsReady`, `onSkillsChanged`, and `files()` on each skill. The `model-hub:ready` event and `onHubReady`. `roles()` flags a role whose tier doesn't exist (`tierMissing`). |
| **0.3** | Per-call `routing` and `candidates`. `batch()`. |
| **0.2** | Roles owned by plugins: `roles()`, `setRole()`, `openRoleEditor()`. Tiers, with fallback along the user's list. `decide()`. |
| **0.1** | `getHub`, `registerRoles`, `complete`, `stream`, `embed`, `models`, `usage`. |

## Changes in behaviour to know about

- **0.4:** tier names match ignoring case, spacing, `-` and `_`. A role that says `'Quick'` now runs on `quick`; in 0.3 it fell back to `balanced`.
- **0.4:** a role naming a tier that doesn't exist still runs on `balanced`, but is now flagged. In 0.3 it became `balanced` unflagged.
- **0.4:** inside a skill folder that has a `SKILL.md`, other `.md` files are data, not skills.
- **0.4:** a skill whose `extends` names a skill that isn't loaded is flagged (`extendsMissing`) and listed as a problem.

The plugin's own changes, version by version, are in the [changelog](https://insurgently.com/docs/model-hub/changelog).

## Related

- [The API, call by call](api.md)