# info.description
Public, unauthenticated discovery and health endpoints for Gitera, the GitHub Actions observability platform. This specification intentionally excludes authenticated product APIs until they are supported as stable public integrations.

## Versioning

Gitera versions the public API in the URL path. `/api/v1` is the canonical base path for the current major version and is the path agents should integrate against. `/api` is a permanent alias that always resolves to the current major version; it is convenient for discovery but its response shape follows the current version and can therefore change when a new major version ships.

Every response carries the `Gitera-Api-Version` header (currently `v1`) so a client can assert which version served it. A breaking change to request or response shapes, removal of a field, or removal of an endpoint is only released under a new path segment (`/api/v2`). Additive, backwards-compatible changes such as new optional response fields are released within the current version.

## Deprecation policy

When a version is scheduled for retirement, every response from that version carries:

- `Deprecation` (RFC 9745) with the timestamp at which the version was declared deprecated.
- `Sunset` (RFC 8594) with the HTTP-date after which the version stops responding.
- `Link` with `rel="deprecation"` pointing at the written policy, and `rel="successor-version"` pointing at the replacement base URL.

A deprecated version keeps responding for at least 183 days (about six months) after the `Deprecation` header first appears. While a version is current, no `Deprecation` or `Sunset` header is sent and responses carry `Link` with `rel="version-history"`. The machine-readable statement of this policy is the `versioning` object in the `/api/v1` response; the written policy is published at https://gitera.io/developers#versioning.

# tags[].description
Machine-readable information about the supported Gitera API surface, including the versioning and deprecation policy.

# tags[].externalDocs.description
Gitera API versioning and deprecation policy

# paths./api/v1.get.summary
Get the Gitera public API index (version 1)

# paths./api/v1.get.description
Canonical versioned entry point. Returns stable links to Gitera developer documentation, this OpenAPI specification, service health, and the machine-readable versioning and deprecation policy.

# paths./api/v1.get.responses.405.description
The method is not supported for this endpoint

# paths./api/v1.head.summary
Check versioned Gitera public API availability without a response body

# paths./api/v1.head.responses.200.description
The Gitera public API index is available

# paths./api/v1/health.get.description
Returns the current application and dependency health. A 503 response is valid JSON and indicates that at least one dependency is unhealthy.

# paths./api/v1/health.get.responses.503.description
The service or a dependency is unhealthy

# paths./api/v1/health.head.summary
Check versioned Gitera service health without a response body

# paths./api/v1/health.head.responses.503.description
The service or a dependency is unhealthy

# paths./api.get.description
Unversioned alias for the current major version. Returns stable links to Gitera developer documentation, this OpenAPI specification, service health, and discovery documents. Integrate against /api/v1 for a path whose response shape is pinned to a major version.

# paths./api.get.responses.405.description
The method is not supported for this endpoint

# paths./api.head.summary
Check Gitera public API availability without a response body

# paths./api.head.responses.200.description
The Gitera public API index is available

# paths./api/health.get.description
Unversioned alias for /api/v1/health. Returns the current application and dependency health. A 503 response is valid JSON and indicates that at least one dependency is unhealthy.

# paths./api/health.get.responses.503.description
The service or a dependency is unhealthy

# paths./api/health.head.summary
Check Gitera service health without a response body

# paths./api/health.head.responses.503.description
The service or a dependency is unhealthy

# components.headers.GiteraApiVersion.description
Major version of the Gitera public API that produced this response.

# components.headers.Deprecation.description
RFC 9745 deprecation signal, sent as @<unix-seconds>. Absent while the version is current.

# components.headers.Sunset.description
RFC 8594 HTTP-date after which this API version stops responding. Absent while the version is current. Sent at least 183 days before the sunset date.

# components.schemas.SupportedVersion.properties.deprecated_at.description
Set when the version is declared deprecated; null while it is current.

# components.schemas.SupportedVersion.properties.sunset_at.description
Set when a retirement date is scheduled; null while the version is current.

# components.schemas.Versioning.description
Machine-readable statement of the Gitera public API versioning and deprecation policy.

# components.schemas.Versioning.properties.strategy.description
Breaking changes are released under a new URL path segment.

# components.schemas.Versioning.properties.versioned_base_url.description
Canonical base URL for the current major version.

# components.schemas.Versioning.properties.unversioned_alias_url.description
Permanent alias that always resolves to the current major version.

# components.schemas.Versioning.properties.version_header.description
Response header carrying the version that served the request.

# components.schemas.Versioning.properties.deprecation_headers.description
Headers used to announce a retiring version.

# components.schemas.Versioning.properties.minimum_deprecation_notice_days.description
Minimum days a version keeps responding after the Deprecation header first appears.

# components.schemas.Problem.description
RFC 9457 Problem Details with Gitera resolution extensions.