You are helping me build a bulk device unlinking tool against the Tenovi Hardware Integration API.

GOAL

Produce a script that takes a list of HWI Device IDs, unlinks each one from its Gateway, verifies the result, and reports which Gateways are now fully cleared and available for reuse.

REFERENCE

Before writing any code, fetch /llms.txt and use it to ground yourself in the current Tenovi API documentation rather than your training data. The recipe this prompt accompanies is at /recipes/bulk-unlinking/.

Do not invent endpoints, query parameters, or response fields. If something you need is not in the documentation, tell me rather than guessing.

ASK ME FIRST

Before writing any code, ask me these questions and wait for my answers:

1. Which client domain should this tool send API calls against? I can find mine in the Tenovi web app on the HWI settings page for the account I intend to use. See /hwi-api/api-url-config/ for background on client domains and how they shape the request URL.
2. What language and runtime do you want this tool written in?
3. Where does the list of devices come from? For example a CSV exported from the Tenovi web app, a list of Gateway UUIDs to expand via the API, a list of patient external IDs, or a hardcoded list of HWI Device IDs.
4. Am I scoping this by Gateway or by patient? Read the CONSTRAINTS section on Gateway occupancy before I answer, and explain the tradeoff to me.
5. What output do you want this tool to produce? For example CSV, JSON, a console table, or a log file.
6. Do you want the dry run and the execution as one script with a flag, or as two separate scripts?

Do not assume answers to these. If I skip one, ask again.

CONFIGURATION

Base URL: https://api2.tenovi.com
Client domain: CLIENT_DOMAIN (placeholder, I will supply this)
Authentication: an Authorization header in the form "Api-Key API_KEY_HERE"

ENDPOINTS

List devices, paginated and filterable:

curl --location 'https://api2.tenovi.com/clients/CLIENT_DOMAIN/hwi/hwi-devices/?device__hardware_uuid=GATEWAY_UUID&page=1&page_size=100' \
--header 'Authorization: Api-Key API_KEY_HERE'

Available query parameters on hwi-devices: device__hardware_uuid, device__hardware_uuid__iexact, patient__external_id, properties__key, properties__value, search, page, page_size. There is no status filter.

Unlink a single device from its Gateway:

curl --location 'https://api2.tenovi.com/clients/CLIENT_DOMAIN/hwi/unlink-gateway/HWI_DEVICE_ID/' \
--header 'Authorization: Api-Key API_KEY_HERE'

CONSTRAINTS

Unlinking is permanent. An unlinked HWI Device cannot be reactivated. Recovery requires activating a new HWI Device, which produces a new hwi_device_id. Measurement data already collected is retained.

The unlink call is a GET request that changes state. Do not allow it to be issued speculatively, prefetched, or retried blindly.

The unlink call is idempotent. A device that is already unlinked returns 200. A rerun of a partial batch is safe. A 200 therefore does not prove this call performed the change.

A device ID that does not exist or belongs to another account returns 404 with a descriptive body. Surface that body rather than swallowing it.

Rate limit is 1 request per second per API key. Pace requests deliberately, at roughly 1.2 seconds between calls rather than exactly 1 second, because firing on the boundary triggers 429 responses in practice. Do not rely on retry logic to absorb rate limit rejections.

Requests to hwi-devices without a page parameter are truncated at 1,000 results. Always paginate when building a list.

A Gateway can host multiple HWI Devices and is only available for reuse once every device on it is unlinked. Unlinking by patient can leave a Gateway partially occupied if another device on the same Gateway is assigned to a different patient record. Always verify Gateway occupancy after the run.

A successful unlink returns the HWI Device object with the nested device.hardware_uuid field set to null. Use this field for verification.

CUSTOMIZE

Input source: [I will specify in answer to question 3]
Scoping: [Gateway or patient, my answer to question 4]
Output format: [my answer to question 5]
Language and runtime: [my answer to question 2]

REQUIREMENTS

Read the API key from an environment variable or a secret store. Never hardcode it and never write it to logs or output files.

Implement a dry run mode that resolves and prints the full target list, with a count, without calling the unlink endpoint. Make this the default behaviour and require an explicit flag to execute.

Log every request and response, including failures, to a file with a timestamp so an interrupted batch can be resumed and audited.

After execution, re-query each affected Gateway and report which are fully cleared and which still have devices attached.

Print a summary at the end: devices attempted, devices confirmed unlinked, devices already unlinked before the run, failures with their status codes, Gateways fully cleared, and Gateways still occupied.

Comment the code so I can modify the filtering and output logic later.