# Remote Rocketship API versioning policy

The public REST API uses the `RR-API-Version` request header. The current version
is `1`. Send `RR-API-Version: 1` to select it explicitly. Existing clients that
omit the header continue to use version 1. The response includes
`RR-API-Version: 1`, including on errors. Unsupported versions return HTTP 400
with the JSON code `UNSUPPORTED_API_VERSION` and a resolution hint.

This policy covers `/api/openclaw/jobs/` and `/api/openclaw/sandbox/`. It does not
version internal website endpoints. MCP negotiates its protocol version separately;
its job-search tool uses the version 1 REST contract.

## Compatibility

Breaking changes to existing request fields, response fields, authentication, or
error meanings require a new API version. Version 1 clients will not silently
move to a new version. Additive optional fields may be introduced within a version;
clients should ignore unknown response fields.

## Deprecation and retirement

Version 1 is supported and has no scheduled retirement date. No Deprecation or
Sunset response header is sent while that remains the case.

Before retiring a version, we will publish a migration guide and the relevant
dates here. Affected responses will include `Deprecation` using the structured
date syntax defined in RFC 9745, and `Sunset` using the HTTP-date syntax defined
in RFC 8594 when a retirement date is set. The retirement date will not precede
the deprecation date. Responses link to this policy using `Link` with
`rel="deprecation"`. A deprecation notice does not itself change endpoint behavior.

See the [OpenAPI contract](https://www.remoterocketship.com/openapi.json),
[developer portal](https://www.remoterocketship.com/developers/),
[RFC 9745](https://www.rfc-editor.org/rfc/rfc9745.html), and
[RFC 8594](https://www.rfc-editor.org/rfc/rfc8594.html).