# API versioning and deprecation

> The Gobare Agent API is versioned in the URL path. This page states what is stable within a version, what counts as a breaking change, and how a change that would break a caller is signalled.

## Versioning

Every endpoint is served under a version segment in the path: `https://api.gobare.dev/v1/...`. There is no version header and no implicit "latest" — a request names the version it was written against, so a caller that pins a URL is pinned to a contract.

The machine-readable description of that contract is published as OpenAPI 3.1 and is advertised on every API response through a `Link: </v1/openapi.json>; rel="service-desc"` header, as described in RFC 8631. It is generated from the service rather than maintained alongside it.

- [OpenAPI description](https://api.gobare.dev/v1/openapi.json)

## What is additive within a version

Within `v1`, the following can appear without notice, and a correct client tolerates all of them: new endpoints, new optional request fields, new fields on a response object, new values in an event stream, and new members of an enumeration. Clients should ignore response fields they do not recognise and should not fail on an unknown event type or an unknown error code.

- New endpoints and new optional parameters
- New properties on existing response objects
- New event types on the event stream
- New members of an enumerated value, including new error codes

## What counts as a breaking change

Removing an endpoint, removing or renaming a response field, making an optional request field required, narrowing an accepted value, or changing the meaning of an existing field are breaking changes. They do not happen inside a version: they arrive as a new version segment, and the previous version keeps serving.

## Errors

Every refusal has the same shape, so a client can handle failure without parsing prose. The body is a JSON object with a single `error` member carrying a machine-readable `code`, a human-readable `message`, and a `request_id` that identifies the request in our logs. The set of codes is enumerated in the OpenAPI description; treat an unrecognised code as a generic failure of its HTTP status class rather than as a parse error.