qURL

Create up to 100 qURLs in a single request. The single-call alternative to looping `create_qurl` — saves round trips and returns a single envelope of per-item results. **Not transactional:** items succeed or fail independently (see `succeeded`/`failed` counts and per-item `error`). Use this when you need to mint many qURLs at once (e.g. provisioning a vendor list, distributing per-customer share links). Use `create_qurl` for a single resource. **Response shape:** `{ succeeded: number, failed: number, results: BatchItemResult[], request_id?: string }`. Each `results[i]` carries `index` (matching the input position), `success`, plus either `qurl_link` + `resource_id` + `qurl_site` + `expires_at` (success) OR `error: { code, message }` (failure). Successful items may also carry `branded_domain` for custom-domain anchor text. **Partial failure signaling:** the handler sets `isError: true` on the tool response whenever `failed > 0`, so agents can branch without parsing JSON. The HTTP layer also returns 400 when every item fails — that's surfaced through the same shape (read `data.results[*].error`). **One-shot links:** like `create_qurl`, every `qurl_link` in the response is shown ONCE. Don't lose them.

Create a qURL — a policy-bound, expiring access link that gates a target URL with optional IP/geo/UA/AI-agent filters and time or session limits. **When to use:** minting a fresh protected access link for share-once or time-limited access (e.g. send a customer a 24-hour download link, gate a doc behind an IP allowlist, distribute a one-time-use credential to a contractor). **When NOT to use:** use `mint_link` when you already have a resource (`r_…`) and just need an additional access token under it — `create_qurl` identifies the resource by target URL and may return an existing same-type resource grouping. Use `batch_create_qurls` to create many in one round-trip. Use `update_qurl` to retag or extend an existing resource without minting a new one. **Behavior:** not idempotent — calling twice produces two distinct qURL tokens, though both may share the same `resource_id` when the target URL groups to an existing same-type resource (this tool doesn't surface the underlying API's `Idempotency-Key` header). The returned `qurl_link` is shown ONCE in this response and is never recoverable through `get_qurl` or `list_qurls`; persist or share it immediately. A returned resource is in `active` status with the policy and per-token limits applied. If `expires_in` is omitted the API defaults to **24h** — do not assume the link is permanent. `max_sessions` is per minted qURL, not resource-wide; set `one_time_use: false` explicitly when you need `max_sessions: 0` to mean unlimited visitors. **Returns:** `{ qurl_id: string (q_…), resource_id: string (r_…), qurl_link: string (shown once), branded_domain?: string, qurl_site: string, expires_at: string (RFC 3339), label?: string, type?: string }`. `qurl_id` is the only `q_…` display ID an agent gets in this response — keep it if you plan a follow-up against `get_qurl`/`update_qurl`/`mint_link` (which accept either prefix). Example: `create_qurl({ target_url: 'https://example.com/private', expires_in: '24h', one_time_use: true, acces…

Permanently revoke a qURL — the link and every access token under it stop working immediately. **This action is irreversible.** Use this when you want to cut off access entirely (compromised link, departed user, end-of-engagement). Use `update_qurl` instead when you only need to shorten/extend the expiration, retag, or rename — those preserve the existing access tokens. Use `extend_qurl` when you only need to push the expiration out. **Idempotent:** the API returns 404 for re-deletes, never-existed IDs, and resources owned by another API key (ownership-mismatch is collapsed into 404 server-side to avoid existence disclosure); this tool swallows all three. Branch on `was_already_revoked` to distinguish the no-op case from a successful revoke on this call. When the ID came from user input and ownership matters, call `get_qurl` first — a 200 confirms ownership; a thrown 404 is equally ambiguous on that endpoint too. Returns a confirmation payload. By default the resource is excluded from `list_qurls`; pass `status: "revoked"` to see it.

Push out the expiration of an active qURL by a relative duration. Convenience wrapper for the most common update — equivalent to `update_qurl({ resource_id, extend_by })`. Use this when the only change you need is more time on the clock. Use `update_qurl` instead when you also need to change tags, description, or set an absolute `expires_at`. Use `delete_qurl` when you want to cut off access entirely. Accepts both `r_` and `q_` IDs (q_ is auto-resolved to its parent resource). **Not idempotent:** calling twice with the same `extend_by` extends the expiration twice. If you need an absolute target, use `update_qurl` with `expires_at` so retries on transient errors don't double-push. Returns the updated resource with the new `expires_at` (same shape as `get_qurl`).

Fetch a single qURL resource by ID and return its current state plus a bounded preview of access tokens. Use this when you have a specific resource ID (r_ prefix) or qURL display ID (q_ prefix) — q_ IDs are auto-resolved to their parent resource. Use `list_qurls` instead when you need to discover qURLs by status, date range, or search query. Use `resolve_qurl` instead when you have an end-user access token (at_ prefix) and need to redeem it for the underlying URL. `qurls[]` is an unordered preview capped by the API at 100 rows and may be omitted on list views, preview lookup failure, or redacted connector-owned resources; use `qurl_count` to detect that more token rows may exist. The one-shot `qurl_link` from creation is never returned here.

List active access sessions for a qURL resource. Use this to inspect who currently has live access before rotating, revoking, or terminating sessions. Use `terminate_qurl_sessions` when active sessions should be ended, and use `get_qurl` when you need token/resource metadata instead of active session state. **Behavior:** read-only and idempotent. Empty `data[]` means no active sessions for the resource.

List qURL resources, paginated and optionally filtered by status, date range, or search text. **When to use:** discovery — finding qURLs by status (e.g. everything still active), auditing date ranges, or full-text search across descriptions and target URLs (via the `q` parameter). Filters AND together (e.g. `status: 'active'` + `expires_before: '2026-05-01T00:00:00Z'` returns active qURLs about to expire). **When NOT to use:** use `get_qurl` instead when you already have a specific resource ID — it returns the same per-resource shape more cheaply and includes the `qurls[]` per-token detail that `list_qurls` omits. Use `resolve_qurl` to actually open access to a target URL. **Behavior:** read-only and idempotent. An empty `data[]` with `meta.has_more: false` means no resource matched the filters (not an error). Pagination is cursor-based: when `meta.has_more` is `true`, pass `meta.next_cursor` as `cursor` on the next call to fetch the following page. Default page size is 20, configurable via `limit` up to 100. By default only `active` qURLs are returned; pass `status: 'revoked'` to see only revoked qURLs or `'active,revoked'` to see both. Sort defaults to `created_at:desc`; override with `sort: 'expires_at:asc'` etc. **Returns:** `{ data: QURL[], meta: { has_more: boolean, next_cursor?: string, page_size?: number, request_id?: string } }` — each `data[]` item is the same stable resource shape returned by `get_qurl` minus per-token detail. Example: `list_qurls({ status: "active", sort: "expires_at:asc", limit: 10 })` returns the 10 active qURLs expiring soonest.

Mint a fresh access link for an existing qURL resource — same one-shot display semantics as `create_qurl.qurl_link`. Use this to issue additional access links to a resource without creating a brand-new qURL (e.g. a second recipient, a replacement after the original was lost). Use `create_qurl` instead when you want a brand-new resource with its own target_url and policy. Use `update_qurl` when you only want to change expiration/tags/description on the existing resource. Accepts both `r_` and `q_` IDs. **Constraints:** `expires_in` and `expires_at` are mutually exclusive (handler returns an `isError: true` content block before any API call if both are set). If neither expiry field is specified, the API defaults to 24 hours from now. **Output:** the new `qurl_link` is shown ONCE — no subsequent call returns it. Capture `qurl_id` if you need to correlate future access events or update this specific token.

Redeem a qURL access token (the `at_` prefix you pulled out of a `qurl_link`) to reveal the underlying URL and obtain a time-bound, IP-bound network access grant. Use this when an agent has been handed an access token and needs to fetch the protected resource — after a successful resolve, requests from `access_grant.src_ip` are permitted to the `target_url` for `access_grant.expires_in` seconds. Use `get_qurl` instead when you have a resource ID (`r_`) or qURL display ID (`q_`) and want admin-side details rather than end-user redemption. **Side-effects:** consumes one use on `one_time_use` tokens, decrements `max_sessions`, and may trip access policies (IP/geo/UA/AI-agent denylists). **`idempotentHint: false`** because one-time-use tokens consume on each call; for non-one-time tokens within an active grant window, repeats are effectively no-ops, but the conservative annotation reflects worst-case behavior.

Revoke one qURL token under a resource without revoking the whole resource. Use this when a single recipient/link should stop working but sibling qURLs on the same `resource_id` must remain active. Use `delete_qurl` instead when you want to revoke the resource and every token under it. **Constraints:** requires the parent `resource_id` (`r_…`) and the token display ID (`q_…`). Re-revoking an inactive token returns an API error rather than being treated as idempotent.

Terminate active access sessions for a qURL resource. Use this after shortening access, rotating a link, or responding to a suspected leak when already-open sessions should end immediately. Pass `session_id` to terminate one active session; omit it to terminate all active sessions for the resource. Use `list_qurl_sessions` first when you need to inspect current sessions before taking action. **Side-effects:** existing access sessions are closed; qURL tokens themselves are not revoked.

Update a qURL's expiration, tags, description, custom domain, or proxy host-header behavior. The richer alternative to `extend_qurl` — use `update_qurl` whenever you need anything beyond a relative time push. Accepts both `r_` and `q_` IDs for expiration, tags, and description updates (q_ is auto-resolved); custom domain and preserve_host updates require an `r_` resource ID because the qURL API now serves them from `PATCH /v1/resources/{id}`. **Constraints:** `extend_by` and `expires_at` are mutually exclusive; `custom_domain`/`preserve_host` cannot be combined with expiration changes in one call; at least one update field (`extend_by`, `expires_at`, `tags`, `description`, `custom_domain`, `preserve_host`) must be set. **Clearing fields:** pass `description: ""`, `tags: []`, or `custom_domain: ""` to clear those fields explicitly. Use `extend_qurl` when the only change is a relative time push. Use `delete_qurl` when you want to revoke entirely. **Errors:** if the input fails schema refinements (both extend_by + expires_at, or no fields set), the handler returns an `isError: true` content block before any API call. Other API errors throw with the API's `code`/`statusCode`. Returns the updated resource (same shape as `get_qurl`).

Update one qURL token under a resource: expiration, label, access policy, max sessions, or session duration. Use this when you need to change a specific `q_…` token without changing sibling tokens or resource-level metadata. Use `update_qurl` instead for resource-level description/tags/custom-domain changes, and use `revoke_qurl_token` when the token should stop working entirely. **Constraints:** `extend_by` and `expires_at` are mutually exclusive; at least one token update field must be set. Returns the updated token summary.