qURL

Extend qURL Expiration

extend_qurl

Instructions

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.

Input Schema

Name	Required	Description
`qurl_id`	No	The link (q_ display ID) to extend. Required when the resource has more than one active link.
`extend_by`	Yes	Duration to extend the link by (e.g., "24h", "7d"; 1m to 30d per call)
`resource_id`	Yes	Resource ID, or a link's q_ display ID; a q_ ID selects that link, and this server reads the resource to find its parent

Output Schema

Name	Required	Description	Default
`crid`	No
`slug`	No	Immutable per-owner resource identity, when one was supplied at create time
`tags`	No
`qurls`	No
`status`	Yes		unknown
`private`	No
`qurl_site`	No
`created_at`	Yes
`expires_at`	Yes
`qurl_count`	No	Number of access tokens minted for this resource
`target_url`	No	Underlying URL the qURL protects; omitted on connector-owned resources
`description`	No
`resource_id`	Yes	Stable resource identifier (public key or legacy r_ ID)
`custom_domain`	No
`preserve_host`	No	When true, the original Host header is preserved when proxying via the custom domain. Only meaningful when custom_domain is set; defaults to false on the API side.
`extend_warning`	No	Present when the resource's expiry cuts the extended link short; tell the user
`consumer_access`	No
`extended_qurl_id`	No	The link that was extended
`extended_link_expires_at`	No	The extended link's new expiry; report this, not the resource's own expires_at

Schema Changelog

Changes observed during successful MCP inspections.

Changed11 schema fields changedv0.2.2Oct 14, 2026

changedInput schema / properties / extend_by / description

Previous value: -"Duration to extend by (e.g., \"24h\", \"7d\")"New value: +"Duration to extend the link by (e.g., \"24h\", \"7d\"; 1m to 30d per call)"

addedInput schema / properties / extend_by / maxLength
```
Added value: +32
```
removedInput schema / properties / extend_by / minLength
```
Removed value: -1
```

addedInput schema / properties / qurl_id

Added value: +{
+  "description": "The link (q_ display ID) to extend. Required when the resource has more than one active link.",
+  "pattern": "^q_[0-9a-f]{11}$",
+  "type": "string"
+}

changedInput schema / properties / resource_id / description

Previous value: -"The resource public key, CRID, legacy r_ ID, or qURL display ID (q_ prefix) to extend. If a q_ ID is passed, the API resolves it to the parent resource automatically."New value: +"Resource ID, or a link's q_ display ID; a q_ ID selects that link, and this server reads the resource to find its parent"

addedOutput schema / properties / consumer_access

Added value: +{
+  "additionalProperties": false,
+  "properties": {
+    "contract_id": {
+      "type": "string"
+    },
+    "mode": {
+      "type": "string"
+    },
+    "version": {
+      "type": "number"
+    }
+  },
+  "required": [
+    "mode"
+  ],
+  "type": "object"
+}

addedOutput schema / properties / crid
```
Added value: +{
+  "type": "string"
+}
```

addedOutput schema / properties / extend_warning

Added value: +{
+  "description": "Present when the resource's expiry cuts the extended link short; tell the user",
+  "type": "string"
+}

addedOutput schema / properties / extended_link_expires_at

Added value: +{
+  "description": "The extended link's new expiry; report this, not the resource's own expires_at",
+  "type": "string"
+}

addedOutput schema / properties / extended_qurl_id

Added value: +{
+  "description": "The link that was extended",
+  "type": "string"
+}

addedOutput schema / properties / private
```
Added value: +{
+  "type": "boolean"
+}
```

Changed5 schema fields changedv0.2.1Sep 19, 2026

removedInput schema / additionalProperties
```
Removed value: -false
```

changedInput schema / properties / resource_id / description

Previous value: -"The resource ID (r_ prefix) or qURL display ID (q_ prefix) to extend. If a q_ ID is passed, the API resolves it to the parent resource automatically."New value: +"The resource public key, CRID, legacy r_ ID, or qURL display ID (q_ prefix) to extend. If a q_ ID is passed, the API resolves it to the parent resource automatically."

removedInput schema / properties / resource_id / minLength
```
Removed value: -1
```

addedInput schema / properties / resource_id / pattern

Added value: +"(?:^(r_[a-z0-9_-]{11}|(?:[A-Za-z0-9_-]{4}){27,53}|(?:[A-Za-z0-9_-]{4}){27,53}[A-Za-z0-9_-]{2}|(?:[A-Za-z0-9_-]{4}){26,52}[A-Za-z0-9_-]{3}|[a-z2-7]{47}|[a-z2-7]{60})$)|(?:^q_[0-9a-f]{11}$)"

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "additionalProperties": {},
+  "properties": {
+    "created_at": {
+      "type": "string"
+    },
+    "custom_domain": {
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "description": {
+      "type": "string"
+    },
+    "expires_at": {
+      "type": "string"
+    },
+    "preserve_host": {
+      "description": "When true, the original Host header is preserved when proxying via the custom domain. Only meaningful when custom_domain is set; defaults to false on the API side.",
+      "type": "boolean"
+    },
+    "qurl_count": {
+      "description": "Number of access tokens minted for this resource",
+      "type": "number"
+    },
+    "qurl_site": {
+      "type": "string"
+    },
+    "qurls": {
+      "items": {
+        "additionalProperties": {},
+        "description": "Single access token belonging to a qURL resource",
+        "properties": {
+          "access_policy": {
+            "additionalProperties": {},
+            "description": "Access control policy snapshot for this token",
+            "properties": {
+              "ai_agent_policy": {
+                "additionalProperties": {},
+                "properties": {
+                  "allow_categories": {
+                    "items": {
+                      "type": "string"
+                    },
+                    "type": "array"
+                  },
+                  "block_all": {
+                    "type": "boolean"
+                  },
+                  "deny_categories": {
+                    "items": {
+                      "type": "string"
+                    },
+                    "type": "array"
+                  }
+                },
+                "type": "object"
+              },
+              "geo_allowlist": {
+                "items": {
+                  "type": "string"
+                },
+                "type": "array"
+              },
+              "geo_denylist": {
+                "items": {
+                  "type": "string"
+                },
+                "type": "array"
+              },
+              "ip_allowlist": {
+                "items": {
+                  "type": "string"
+                },
+                "type": "array"
+              },
+              "ip_denylist": {
+                "items": {
+                  "type": "string"
+                },
+                "type": "array"
+              },
+              "user_agent_allow_regex": {
+                "type": "string"
+              },
+              "user_agent_deny_regex": {
+                "type": "string"
+              }
+            },
+            "type": "object"
+          },
+          "created_at": {
+            "type": "string"
+          },
+          "expires_at": {
+            "type": "string"
+          },
+          "label": {
+            "type": "string"
+          },
+          "max_sessions": {
+            "type": "number"
+          },
+          "one_time_use": {
+            "type": "boolean"
+          },
+          "qurl_id": {
+            "type": "string"
+          },
+          "qurl_site": {
+            "type": "string"
+          },
+          "session_duration": {
+            "description": "Seconds of access granted after a successful resolve",
+            "type": "number"
+          },
+          "status": {
+            "default": "unknown",
+            "description": "Per-token status (wider than resource status — tokens may be consumed/expired independently)",
+            "enum": [
+              "active",
+              "consumed",
+              "expired",
+              "revoked",
+              "unknown"
+            ],
+            "type": "string"
+          },
+          "use_count": {
+            "type": "number"
+          }
+        },
+        "required": [
+          "qurl_id",
+          "status"
+        ],
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "resource_id": {
+      "description": "Stable resource identifier (public key or legacy r_ ID)",
+      "type": "string"
+    },
+    "slug": {
+      "description": "Immutable per-owner resource identity, when one was supplied at create time",
+      "type": "string"
+    },
+    "status": {
+      "default": "unknown",
+      "enum": [
+        "active",
+        "revoked",
+        "expired",
+        "unknown"
+      ],
+      "type": "string"
+    },
+    "tags": {
+      "items": {
+        "type": "string"
+      },
+      "type": "array"
+    },
+    "target_url": {
+      "description": "Underlying URL the qURL protects; omitted on connector-owned resources",
+      "type": "string"
+    }
+  },
+  "required": [
+    "resource_id",
+    "expires_at",
+    "created_at",
+    "status"
+  ],
+  "type": "object"
+}

First observedv0.2.0Apr 27, 2026

TDQS

A4.8/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Goes well beyond the annotations: discloses required scopes (qurl:write and qurl:read), the two-to-three API call cost, the resource-expires_at constraint plus extend_warning, error-vs-throw behavior, and the non-idempotent double-push consequence with a retry-safe alternative. This is exactly the actionable context annotations cannot carry.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Dense but front-loaded, with the core mechanic first and constraints grouped afterward. It is long, and a few clauses (e.g. the 100-links parenthetical, the returned-field enumeration) could be trimmed, but each sentence carries substantive information rather than filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a non-idempotent mutation with an output schema, the description covers prerequisites, side effects, retry safety, error semantics, and which return field holds the new expiry (extended_link_expires_at vs the resource's own expires_at). Nothing an agent needs to call it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: it explains that resource_id can be a q_ display ID selecting a link, that qurl_id is only needed for multi-link resources, and adds the sub-100-link nuance and extend_by's relative-duration semantics and range.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (extend) and resource (qURL link expiration) with the precise mechanism: pushing out expiration by a relative duration. It cleanly distinguishes itself from update_qurl_token, revoke_qurl_token, and delete_qurl by naming what each of those does instead.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly says when to use it ('when the only change you need is more time on the clock'), names the alternatives for adjacent needs (absolute expiry, label/policy/sessions via update_qurl_token), and flags the exclusion (upload-tool links belong to the file connector and cannot be extended here). Nothing is left to inference.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server