# Nas.com Public Discovery API Versioning

The public REST discovery contract is **1.0.0**. Use these versioned URLs for new clients:

- `GET https://nas.com/api/v1/agent-mode`
- `GET https://nas.com/api/v1/agent/page-context?path=/`

The existing `/api/agent-mode` and `/api/agent/page-context` URLs remain supported
aliases with the same implementation, JSON responses, method handling, public-path
guards, and cache behavior. The homepage `/?mode=agent` discovery view remains
supported. No current endpoint is deprecated or scheduled for removal.

## Compatibility within v1

Additive changes may extend v1: new optional fields, optional query parameters,
resources, and endpoints. Clients should ignore unknown response fields. Changes
that remove or rename fields, change existing field types or meanings, add required
inputs, or change authentication requirements require a new major path such as
`/api/v2`. Corrections that preserve the contract may ship as patch revisions.

The contract version in OpenAPI `info.version` is separate from the OpenAPI format
version (`openapi`) and the document revision (`info.x-document-revision`). The
OpenAPI description is available at [openapi.json](https://nas.com/openapi.json).

## Deprecation and removal

Nas.com will announce a planned endpoint removal at least **180 days** before the
removal date and provide a migration guide identifying the replacement and required
client changes. Support continues during that notice period. A new major version
does not by itself deprecate v1 or its unversioned aliases.

When an actual deprecation and removal date are approved, affected responses will
carry the [RFC 9745 Deprecation](https://www.rfc-editor.org/rfc/rfc9745.html) and
[RFC 8594 Sunset](https://www.rfc-editor.org/rfc/rfc8594.html) headers and link to
migration guidance. These headers are not emitted for the current supported routes.
The OpenAPI document and both URL forms of the discovery endpoints expose
`Link: <https://nas.com/api-versioning.md>; rel="deprecation"; type="text/markdown"`
to make this policy discoverable. [RFC 9745 section 3](https://www.rfc-editor.org/rfc/rfc9745.html#section-3)
allows this policy link before any actual deprecation; the link does not declare
that a supported endpoint is deprecated or assign a removal date.
Urgent security fixes may require expedited changes, accompanied by an advisory.

## Public boundaries and MCP

Both URL forms are anonymous and read-only. Private, authenticated, checkout,
payment, admin, member-only and API implementation paths remain excluded from page
context. Unsupported public context returns a structured JSON `404` error;
unsupported methods return a structured JSON `405` error. Successful responses
retain `Cache-Control: s-maxage=300, stale-while-revalidate=3600`.

The hosted MCP transport remains `https://mcp.nas.com/mcp`. MCP protocol negotiation
and server release versions are independent of this REST contract. See the
[MCP guide](https://nas.com/mcp.md) for authentication and tool discovery.
