diff --git a/src/content/changelog/cloudflare-tunnel/2025-09-02-tunnel-networks-list-endpoints-new-default.mdx b/src/content/changelog/cloudflare-tunnel/2025-09-02-tunnel-networks-list-endpoints-new-default.mdx new file mode 100644 index 00000000000000..419dcfcbfa35c6 --- /dev/null +++ b/src/content/changelog/cloudflare-tunnel/2025-09-02-tunnel-networks-list-endpoints-new-default.mdx @@ -0,0 +1,55 @@ +--- +title: Cloudflare Tunnel and Networks API will no longer return deleted resources by default starting December 1, 2025 +description: The is_deleted parameter for specific Cloudflare Tunnel and Zero Trust Networks list API endpoints will default to false. To retrieve deleted resources, you must explicitly set this parameter to true. +products: + - cloudflare-one +hidden: false +date: 2025-09-02 +--- + +Starting **December 1, 2025**, list endpoints for the [Cloudflare Tunnel API](/api/resources/zero_trust/subresources/tunnels/) and [Zero Trust Networks API](/api/resources/zero_trust/subresources/networks/) will no longer return deleted tunnels, routes, subnets and virtual networks by default. This change makes the API behavior more intuitive by only returning active resources unless otherwise specified. + +No action is required if you already explicitly set `is_deleted=false` or if you only need to list active resources. + +This change affects the following API endpoints: +* List all tunnels: [`GET /accounts/{account_id}/tunnels`](/api/resources/zero_trust/subresources/tunnels/methods/list/) +* List [Cloudflare Tunnels](/cloudflare-one/connections/connect-networks/): [`GET /accounts/{account_id}/cfd_tunnel`](/api/resources/zero_trust/subresources/tunnels/subresources/cloudflared/methods/list/) +* List [WARP Connector](/cloudflare-one/connections/connect-networks/private-net/warp-connector/) tunnels: [`GET /accounts/{account_id}/warp_connector`](/api/resources/zero_trust/subresources/tunnels/subresources/warp_connector/methods/list/) +* List tunnel routes: [`GET /accounts/{account_id}/teamnet/routes`](/api/resources/zero_trust/subresources/networks/subresources/routes/methods/list/) +* List subnets: [`GET /accounts/{account_id}/zerotrust/subnets`](/api/resources/zero_trust/subresources/networks/subresources/subnets/methods/list/) +* List virtual networks: [`GET /accounts/{account_id}/teamnet/virtual_networks`](/api/resources/zero_trust/subresources/networks/subresources/virtual_networks/methods/list/) + +## What is changing? + +The default behavior of the `is_deleted` query parameter will be updated. + +| Scenario | Previous behavior (before December 1, 2025) | New behavior (from December 1, 2025) | +| :--- | :--- | :--- | +| `is_deleted` parameter is omitted | Returns **active & deleted** tunnels, routes, subnets and virtual networks | Returns **only active** tunnels, routes, subnets and virtual networks | + + +## Action required + +If you need to retrieve deleted (or all) resources, please update your API calls to explicitly include the `is_deleted` parameter before **December 1, 2025**. + +To get a list of only deleted resources, you must now explicitly add the `is_deleted=true` query parameter to your request: + +```bash +# Example: Get ONLY deleted Tunnels +curl "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/tunnels?is_deleted=true" \ + -H "Authorization: Bearer $API_TOKEN" + +# Example: Get ONLY deleted Virtual Networks +curl "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/teamnet/virtual_networks?is_deleted=true" \ + -H "Authorization: Bearer $API_TOKEN" +``` + +Following this change, retrieving a complete list of both active and deleted resources will require two separate API calls: one to get active items (by omitting the parameter or using `is_deleted=false`) and one to get deleted items (`is_deleted=true`). + +## Why we’re making this change +This update is based on user feedback and aims to: +* **Create a more intuitive default:** Aligning with common API design principles where list operations return only active resources by default. +* **Reduce unexpected results:** Prevents users from accidentally operating on deleted resources that were returned unexpectedly. +* **Improve performance:** For most users, the default query result will now be smaller and more relevant. + +To learn more, please visit the [Cloudflare Tunnel API](/api/resources/zero_trust/subresources/tunnels/) and [Zero Trust Networks API](/api/resources/zero_trust/subresources/networks/) documentation. \ No newline at end of file