ToolRouter versions its public REST contract in the URL. The current stable base path is /v1, served from https://api.toolrouter.com. A versioned path covers request and response shapes, authentication behavior, status codes, and documented headers. Tool manifests and individual skill schemas can evolve within that contract as the catalog changes, so agents should read the live manifest before constructing a call.
What changes can happen within v1?
Backward-compatible additions can ship within /v1. These include new endpoints, new optional request fields, new response fields, new tools and skills, new enum values where the schema documents extensibility, and clearer error details. Clients should ignore response fields they do not understand and should not depend on object-key ordering.
ToolRouter does not intentionally remove a documented field, change its meaning, make an optional field required, or reuse a stable error code for a different condition within the same API version without a deprecation period.
How does ToolRouter announce deprecation?
When a REST resource is scheduled for deprecation, its responses will include a Deprecation header using the structured date syntax from RFC 9745. Responses will also include a Link header with rel="deprecation" pointing to migration guidance. These headers apply only to the resource that sends them unless the linked notice explicitly defines a wider scope.
Example:
Deprecation: @1798761600
Link: <https://toolrouter.com/docs/api-lifecycle>; rel="deprecation"; type="text/html"ToolRouter does not send a Deprecation header on active endpoints merely to say that they are current.
How does ToolRouter announce shutdown?
If a deprecated resource will stop responding, ToolRouter will add the Sunset header from RFC 8594 with an HTTP date. The sunset date will not be earlier than the deprecation date. The linked migration guide will name the replacement route or explain why no replacement exists.
Deprecation: @1798761600
Sunset: Thu, 01 Jul 2027 00:00:00 GMT
Link: <https://toolrouter.com/docs/api-lifecycle>; rel="deprecation"; type="text/html"What notice period should clients expect?
ToolRouter targets at least 90 days between the first deprecation signal and sunset for stable public REST endpoints. A longer period may be used for widely adopted endpoints. A shorter period may be necessary for an actively exploited security issue, provider shutdown, legal requirement, or behavior that risks customer data or funds; the migration notice will explain that exception.
How should an agent integrate safely?
Use the versioned /v1 paths from the live OpenAPI specification. Inspect Deprecation, Sunset, and Link response headers. Branch on documented status codes and machine-readable error codes rather than message text. Refresh tool and skill manifests before calls instead of caching catalog schemas indefinitely.
Questions about a migration can be sent to support@toolrouter.com with the affected endpoint and a request ID, if available.