[Breaking change] List contracts API improvements

Overview

We're introducing a breaking change to the GET /contracts API to align with the Torii web console:

All Contract Details seen in the UI will now be supported in the new API
Pagination will be supported for the API
Advanced filtering will be supported for the API
Aggregations will be supported for the API

Timeline:

April 26th, 2026: new version (1.1) is available for use alongside the default 1.0 version.
(in between): Users of the API will need to opt-in to the new version.
August 1st, 2026: API Keys created on or after this date will be opted-into version 1.1 by default.
October 1st, 2026: the new version (1.1) becomes the default and version 1.0 is removed.

We suggest using the new header to opt-in to the new version 1.1 starting today for new developments.

Opt-in to the new API

The API now supports a new header X-API-Version: 1.1. This new version supports pagination, aggregations and filtering. It also introduces a new response body that provides more data on nested objects.

To opt-in to the new version, use the following header in your API request:

{  
	"headers": {  
		"X-API-Version": "1.1"  
  }  
}

To learn more about pagination and sorting, please refer to the API reference here: https://developers.toriihq.com/reference/pagination.