# API v3 inventory workflows and idempotent creation

> 2026-11-11 · Cursor pagination, richer filters, scoped summaries and tags, address lookup, targets, stored health status, bulk updates and creation replay on the dev branch.

Development of API v3 continues on `dev` with new integration workflows. V2 remains the stable integration default.

- **Cursor traversal:** opt into authenticated, credential/query-bound cursors with stable ordering, forward/backward URLs and 24-hour expiry. Existing page pagination stays the default.
- **Inventory filters:** filter by creation origin, selected IDs, creation/update dates, password protection, health checking and user tracking; choose stable sort order.
- **Scoped summaries and tags:** inspect inventory status counts and discover tags without exporting every link. Large tag aggregations require narrower filters.
- **Address lookup:** retrieve an authorized link by hostname and exact slug without storing its ID separately.
- **Health status:** read stored status, HTTP code, response time and check timestamp without triggering an outbound probe or exposing diagnostics.
- **Target collections:** list and replace targeting rules directly, preserving IDs and analytics for retained targets.
- **Bulk updates:** PATCH up to 50 links with independent outcomes, normal safety checks, transactions, audit and cache invalidation.
- **Idempotent creation:** optional `Idempotency-Key` support for single and bulk link creation, with database reservations, encrypted 24-hour response retention and explicit payload/pending conflicts. Replays still require current authentication and permissions. Failed bulk items roll back partial database writes.

All workflows retain the existing token/account permissions and JSON envelope. Discovery, OpenAPI, executable examples and regression tests cover the new routes.

Deploy the new replay-table migration with the code, keep the scheduler running for expiry pruning, and test locking on the production database engine before a concurrency-sensitive rollout. See the [API v3 reference](https://docs.ternis.link/api-v3) for requests, responses, limits and deployment details.
