Publish a URL with private access. Choose keys for approved credentials, invite_only for publisher email invitations with no access requests, email_capture for verified email capture with consent, review for verified email requests, or contract for a publisher backend entitlement receipt. This tool does not verify payment. Use version 1 for creation. Repeating this call creates another resource; after an uncertain result use get_qurl or list_qurls before retrying. For local apps use the qURL CLI. Public sharing uses create_qurl.

Publisher access control. Invite takes only action, resource_id and email; omit expected_version, approval and policy. Report the exact invited email addresses without shortening them. Check every page of list_invitations before claiming nobody else was invited. If listing is denied, report the send receipts and say the list is unconfirmed; do not resend. Accepted delivery does not prove enrollment. Configure the next policy version, send or resend an email invitation, list invitations or consumer grants, approve or deny a request, approve a credential with id new, or revoke access. Read the current version before a decision; configuring the first policy on an existing private resource uses expected_version 0. For approve, put expected_version inside approval; zero is allowed only for id new. Existing requests use the listed decision id and version without credential fields. A six-digit code alone never authorizes approval on a resource with consumer_access. Ask which listed request the user wants to approve (the verified email for review); keys needs the intended public credential and contract needs a trusted entitlement receipt. Wait for that instruction. After an uncertain invite result, list invitations before retrying. Invite-only access has no consumer requests. Contract approval requires a trusted publisher entitlement receipt and expiry, not an unverified payment claim. A removal is complete only when session_cleanup is complete; retry the same removal/version while pending. Email proves mailbox control, not legal identity. Only listed fields are returned; invitation secrets and bearer links are never returned.

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). Do NOT use this for chat-uploaded images, PDFs, screenshots, or file attachments. In HTTP MCP mode, those should go through upload_file_data_qurl; in stdio mode, use upload_file_qurl. When NOT to use: use mint_link when you already have a resource identifier 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. If the user says 'give me the qURL of this image/file' and the content was uploaded in chat, this is the wrong tool. 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. Set expires_in explicitly for a predictable lifetime; otherwise the service uses its defaults. Read expires_at in the response. 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, 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, access_policy: { geo_allowlist: ['US'] } }).

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 identifier (public key, CRID, or legacy r_ ID) 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.

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. A past resource expires_at does not change its status; individual access tokens can expire. status: 'expired' is not a valid resource filter. 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.

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 (public key, CRID, or legacy r_ ID) or qURL display ID (q_ prefix) — q_ IDs are auto-resolved to their parent resource. Do not use this to create a new qURL for a freshly uploaded image, PDF, screenshot, or file attachment. For chat-uploaded file content in HTTP MCP mode, use upload_file_data_qurl instead. 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. If the user asks for 'the qURL of this image/file', this tool is only correct when you already know the existing resource_id or qurl_id. 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.

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). It does not revoke links minted by the upload tools, which belong to the file connector; those cannot be revoked from this server. Use update_qurl instead when you only need to shorten the resource's expiration, retag, or rename, and extend_qurl to keep a link open longer — those preserve the existing access tokens. 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.

Keep a qURL link open longer by pushing out the link's expiration by a relative duration. Pass a link's q_ display ID as resource_id, or a resource ID plus qurl_id; a resource with exactly one active link needs no qurl_id (unless it has more than the 100 links a read lists). Use this when the only change you need is more time on the clock. Use update_qurl_token instead to set an absolute expires_at or change the link's label, policy, or sessions. Use revoke_qurl_token or delete_qurl when you want to cut off access. Links minted by the upload tools belong to the file connector and cannot be extended from this server. Not idempotent: calling twice with the same extend_by extends the link twice; use update_qurl_token with expires_at when retries must not double-push. Requires qurl:write and qurl:read: it reads the resource before updating, to check the link and to return it, so each extend costs two API calls (three when the read does not list the link). A link cannot outlive its resource: if the resource's own expires_at is sooner, raise it with update_qurl first; the result then carries extend_warning. Link-selection problems return an error result; a rejected update throws with its HTTP status and error code. Returns the resource (same shape as get_qurl); the extended link's new expiry is in extended_link_expires_at (and qurls[].expires_at), not the resource's own expires_at.

Update a qURL resource's expiration ceiling, tags, description, custom domain, or proxy host-header behavior. extend_by/expires_at here move the resource's own expiry, which does not keep an individual link open longer; use extend_qurl or update_qurl_token to change a link's expiry. Accepts resource public keys, CRIDs, legacy r_ IDs, and q_ display IDs for expiration, tags, and description updates (q_ is auto-resolved); custom domain and preserve_host updates require a resource identifier (public key, CRID, or legacy r_ 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 delete_qurl when you want to revoke entirely. Errors: a malformed or out-of-range extend_by is rejected by input validation; if the input fails schema refinements (both extend_by + expires_at, or no fields set), the handler returns an isError: true content block. Both happen before any API call. Other API errors throw with the API's code/statusCode. Returns the updated resource (same shape as get_qurl).

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). Not for files from the upload tools: their links come from the file connector, so a link minted here on an upload's resource_id does not open the file; run the upload tool again instead. 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 resource public keys, CRIDs, legacy r_ IDs, and q_ display 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.

Only for legacy resources without consumer_access; use manage_crid_access and the policy's invitation or grant flow for consumer_access resources. Use the known resource policy. If qurl:read is available, get_qurl (without the leading $ marker) can check consumer_access. A resolve-only key can share a known legacy resource without that read; if the policy is unknown, ask the publisher, and never treat a denied read as proof that it is legacy. Request a temporary qURL access link for a resource identified by its CRID. When the user supplies a legacy resource CRID with a leading $ marker, remove the marker and use this tool. Set ttl to request a lifetime using Go duration syntax; the total must be a positive whole number of seconds. The service may adjust the lifetime. The link is minted by the qURL API and includes its expiration and single-use metadata.

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. Only use this when the user explicitly wants multiple qURLs in one request. Never use it for a single URL, a single file, a single image, or a single attachment. Do not use this tool for uploaded files, image attachments, PDFs, or base64 file content — use upload_file_data_qurl (HTTP mode) or upload_file_qurl (stdio mode) instead. 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.

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 (public key, CRID, or legacy r_ ID) and the token display ID (q_…). Re-revoking an inactive token returns an API error rather than being treated as idempotent.

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.

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.

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.