# Unif API API versioning and deprecation policy

UnifAPI exposes a public-data HTTP API and MCP tool surface generated from the same OpenAPI route metadata. This page tells agents how to interpret API lifecycle signals before adding version prefixes, retrying old paths, or assuming a deprecated operation is still safe to call.

- Last updated: 2026-06-02
- OpenAPI source: https://unifapi.com/openapi.json
- API base URL: https://api.unifapi.com
- MCP server: https://mcp.unifapi.com
- Support: support@unifapi.com

## Current versioning model

- Current public HTTP paths are the canonical paths published in `openapi.json`. Do not invent `/v1` or `/api/v1` prefixes unless they appear in the current OpenAPI document.
- Agents should treat the `openapi.json` `info.version`, operation path, HTTP method, request schema, response schema, and error schema as the runtime contract.
- The marketing-domain `/openapi.json` route mirrors the API contract for discovery; direct calls still use the API host shown in that operation's server/base URL guidance.
- MCP clients should prefer `list_operations` and `get_operation` before calling `call_api`; those tools expose the current operation catalog without guessing paths.

## Deprecation policy

- Additive changes, new optional fields, new endpoints, and new enum values may ship without a deprecation window.
- Breaking changes to a shipped public-data operation should be announced in docs, `llms.txt`/`llms-full.txt`, and the affected API/Skill pages before removal.
- The normal minimum deprecation window is 30 days for public endpoints that appear in the catalog, unless a security, legal, abuse, or upstream-provider emergency requires faster action.
- Deprecated operations should keep returning the documented shared error envelope until they are removed.
- When runtime support is available, HTTP deprecations should use standard `Deprecation`, `Sunset`, and `Link` headers. Until then, agents should rely on this page, the OpenAPI document, docs, and status guidance.

## Agent behavior

- Fetch `openapi.json` or call MCP `list_operations` before generating code.
- Do not call old guessed slugs after a 404; check the current catalog first.
- Do not migrate users to `/v1` paths unless the OpenAPI contract exposes those paths.
- On `not_found`, `validation_error`, or `invalid_id`, correct the request instead of retrying the same path.
- On repeated `upstream_unavailable` or `internal_error`, check `status.md` before looping.

## Related resources

- [OpenAPI spec](https://unifapi.com/openapi.json)
- [Developer resources](https://unifapi.com/developers.md)
- [Auth guide](https://unifapi.com/auth.md)
- [Status and recovery](https://unifapi.com/status.md)
- [Docs](https://docs.unifapi.com)