qURL

Get qURL

get_qurl

Read-onlyIdempotent

Instructions

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.

Input Schema

Name	Required	Description	Default
`resource_id`	Yes	The resource public key, CRID, legacy r_ ID, or qURL display ID (q_ prefix) to fetch. If a q_ ID is passed, the API resolves it to the parent resource automatically.

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.
`consumer_access`	No

Schema Changelog

Changes observed during successful MCP inspections.

Changed3 schema fields changedv0.2.2Oct 14, 2026

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 / 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 fetch. 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 fetch. 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?

Annotations already cover readOnly/idempotent/destructive, and the description goes well beyond them: q_ IDs auto-resolve to their parent, qurls[] is an unordered preview capped at 100 rows, may be omitted on list views or redacted connector resources, and the one-shot qurl_link is never returned. It also tells the agent to use qurl_count to detect truncation.

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?

Purpose is front-loaded and all sentences are functional rather than filler, but the paragraph is dense and mixes usage routing with output caveats, which slightly dilutes scanability. Every clause still earns its place.

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?

Despite an existing output schema, the description proactively explains the non-obvious return semantics (unordered/capped preview, possible omission, qurl_link never returned) plus ID resolution behavior, leaving nothing an agent needs in order to call it correctly.

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% with a single required param, so the baseline is 3. The description adds genuine value beyond the schema by clarifying the accepted ID families and that q_ IDs auto-resolve to the parent resource, which the schema regex only implies.

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+resource: fetch a single qURL by ID, return current state plus bounded token preview. It explicitly differentiates from siblings (list_qurls, resolve_qurl, create_qurl, upload_file_data_qurl), so an agent can distinguish it without opening any schema.

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?

Gives explicit when-to-use (you have a resource_id or q_ display ID), when-not (creating a qURL for a fresh upload; fetching chat-uploaded file content), and names three alternatives with the exact condition that selects each (discovery, token redemption, file content).

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

Deploy Server