qURL

Batch Create qURLs

batch_create_qurls

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.

Instructions

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.

Input Schema

Name	Required	Description	Default
`items`	Yes	Array of qURL creation requests (1-100 items)

Output Schema

Name	Required	Description	Default
`failed`	Yes
`results`	Yes
`succeeded`	Yes
`request_id`	No

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedv0.2.2Oct 14, 2026

changedInput schema / properties / items / items / properties / expires_in / description

Previous value: -"Duration string (e.g., \"1h\", \"24h\", \"7d\")"New value: +"Duration string (e.g., \"1h\", \"24h\", \"7d\"; the API enforces 1m to 30d)"

Changed38 schema fields changedv0.2.1Sep 19, 2026

removedInput schema / additionalProperties
```
Removed value: -false
```
removedInput schema / properties / items / items / additionalProperties
```
Removed value: -false
```
removedInput schema / properties / items / items / properties / access_policy / additionalProperties
```
Removed value: -false
```
removedInput schema / properties / items / items / properties / access_policy / properties / ai_agent_policy / additionalProperties
```
Removed value: -false
```

changed

Input schema / properties / items / items / properties / access_policy / properties / ai_agent_policy / properties / allow_categories / description

Previous value: -"AI agent categories to permit (all others blocked)"New value: +"AI agent categories to permit (all others blocked; max 20 entries, 128 chars each)"

addedInput schema / properties / items / items / properties / access_policy / properties / ai_agent_policy / properties / allow_categories / items / maxLength
```
Added value: +128
```
addedInput schema / properties / items / items / properties / access_policy / properties / ai_agent_policy / properties / allow_categories / items / minLength
```
Added value: +1
```
addedInput schema / properties / items / items / properties / access_policy / properties / ai_agent_policy / properties / allow_categories / maxItems
```
Added value: +20
```

changed

Input schema / properties / items / items / properties / access_policy / properties / ai_agent_policy / properties / deny_categories / description

Previous value: -"AI agent categories to block (e.g., gptbot, commoncrawl)"New value: +"AI agent categories to block (e.g., gptbot, commoncrawl; max 20 entries, 128 chars each)"

addedInput schema / properties / items / items / properties / access_policy / properties / ai_agent_policy / properties / deny_categories / items / maxLength
```
Added value: +128
```
addedInput schema / properties / items / items / properties / access_policy / properties / ai_agent_policy / properties / deny_categories / items / minLength
```
Added value: +1
```
addedInput schema / properties / items / items / properties / access_policy / properties / ai_agent_policy / properties / deny_categories / maxItems
```
Added value: +20
```

changedInput schema / properties / items / items / properties / access_policy / properties / geo_allowlist / description

Previous value: -"Allowed country codes (ISO 3166-1 alpha-2)"New value: +"Allowed country codes (ISO 3166-1 alpha-2; max 50 entries, 8 chars each)"

addedInput schema / properties / items / items / properties / access_policy / properties / geo_allowlist / items / maxLength
```
Added value: +8
```
addedInput schema / properties / items / items / properties / access_policy / properties / geo_allowlist / items / minLength
```
Added value: +1
```
addedInput schema / properties / items / items / properties / access_policy / properties / geo_allowlist / maxItems
```
Added value: +50
```

changedInput schema / properties / items / items / properties / access_policy / properties / geo_denylist / description

Previous value: -"Denied country codes (ISO 3166-1 alpha-2)"New value: +"Denied country codes (ISO 3166-1 alpha-2; max 50 entries, 8 chars each)"

addedInput schema / properties / items / items / properties / access_policy / properties / geo_denylist / items / maxLength
```
Added value: +8
```
addedInput schema / properties / items / items / properties / access_policy / properties / geo_denylist / items / minLength
```
Added value: +1
```
addedInput schema / properties / items / items / properties / access_policy / properties / geo_denylist / maxItems
```
Added value: +50
```

changedInput schema / properties / items / items / properties / access_policy / properties / ip_allowlist / description

Previous value: -"Allowed IP addresses or CIDR ranges"New value: +"Allowed IP addresses or CIDR ranges (max 100 entries, 64 chars each)"

addedInput schema / properties / items / items / properties / access_policy / properties / ip_allowlist / items / maxLength
```
Added value: +64
```
addedInput schema / properties / items / items / properties / access_policy / properties / ip_allowlist / items / minLength
```
Added value: +1
```
addedInput schema / properties / items / items / properties / access_policy / properties / ip_allowlist / maxItems
```
Added value: +100
```

changedInput schema / properties / items / items / properties / access_policy / properties / ip_denylist / description

Previous value: -"Denied IP addresses or CIDR ranges"New value: +"Denied IP addresses or CIDR ranges (max 100 entries, 64 chars each)"

addedInput schema / properties / items / items / properties / access_policy / properties / ip_denylist / items / maxLength
```
Added value: +64
```
addedInput schema / properties / items / items / properties / access_policy / properties / ip_denylist / items / minLength
```
Added value: +1
```
addedInput schema / properties / items / items / properties / access_policy / properties / ip_denylist / maxItems
```
Added value: +100
```
changedInput schema / properties / items / items / properties / access_policy / properties / user_agent_allow_regex / description
```
Previous value: -"Regex to allow matching user agents"New value: +"Regex to allow matching user agents (max 256 chars)"
```
addedInput schema / properties / items / items / properties / access_policy / properties / user_agent_allow_regex / maxLength
```
Added value: +256
```
changedInput schema / properties / items / items / properties / access_policy / properties / user_agent_deny_regex / description
```
Previous value: -"Regex to deny matching user agents"New value: +"Regex to deny matching user agents (max 256 chars)"
```
addedInput schema / properties / items / items / properties / access_policy / properties / user_agent_deny_regex / maxLength
```
Added value: +256
```

changedInput schema / properties / items / items / properties / custom_domain / description

Previous value: -"Custom domain to assign to the auto-created resource"New value: +"Custom domain to assign to the auto-created resource (max 253 chars, must be registered/active/owned)."

addedInput schema / properties / items / items / properties / custom_domain / maxLength
```
Added value: +253
```

changedInput schema / properties / items / items / properties / max_sessions / description

Previous value: -"Maximum concurrent sessions (0 = unlimited, max 1000)"New value: +"Maximum concurrent sessions for this qURL token (0 = unlimited when one_time_use is explicitly false; max 1000)"

changedInput schema / properties / items / items / properties / session_duration / description

Previous value: -"How long access lasts after clicking (e.g., \"1h\")"New value: +"How long access lasts after the recipient reaches the content (e.g., \"1h\"). This anchors the resource-level session-duration cap when a new resource is created."

addedInput schema / properties / items / items / properties / type

Added value: +{
+  "description": "Resource type for integrations allowed to mint non-url qURLs (max 64 chars). Defaults to url.",
+  "maxLength": 64,
+  "type": "string"
+}

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "additionalProperties": {},
+  "properties": {
+    "failed": {
+      "type": "number"
+    },
+    "request_id": {
+      "type": "string"
+    },
+    "results": {
+      "items": {
+        "description": "Per-item result. Discriminated on `success`.",
+        "oneOf": [
+          {
+            "additionalProperties": {},
+            "properties": {
+              "branded_domain": {
+                "description": "Bare branded hostname for anchor text when the resource has a usable custom domain",
+                "type": "string"
+              },
+              "expires_at": {
+                "type": "string"
+              },
+              "index": {
+                "description": "Index of the corresponding item in the input `items` array",
+                "type": "number"
+              },
+              "qurl_link": {
+                "description": "One-shot display access link — shown ONCE on creation",
+                "type": "string"
+              },
+              "qurl_site": {
+                "type": "string"
+              },
+              "resource_id": {
+                "type": "string"
+              },
+              "success": {
+                "const": true,
+                "type": "boolean"
+              }
+            },
+            "required": [
+              "index",
+              "success",
+              "resource_id",
+              "qurl_link",
+              "qurl_site",
+              "expires_at"
+            ],
+            "type": "object"
+          },
+          {
+            "additionalProperties": {},
+            "properties": {
+              "error": {
+                "additionalProperties": {},
+                "properties": {
+                  "code": {
+                    "type": "string"
+                  },
+                  "message": {
+                    "type": "string"
+                  }
+                },
+                "required": [
+                  "code",
+                  "message"
+                ],
+                "type": "object"
+              },
+              "index": {
+                "description": "Index of the corresponding item in the input `items` array",
+                "type": "number"
+              },
+              "success": {
+                "const": false,
+                "type": "boolean"
+              }
+            },
+            "required": [
+              "index",
+              "success",
+              "error"
+            ],
+            "type": "object"
+          }
+        ]
+      },
+      "type": "array"
+    },
+    "succeeded": {
+      "type": "number"
+    }
+  },
+  "required": [
+    "succeeded",
+    "failed",
+    "results"
+  ],
+  "type": "object"
+}

First observedv0.2.0Apr 27, 2026

TDQS

A4.6/5.0

Behavior5/5

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

Goes well beyond the annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=false): discloses that the operation is NOT transactional, that isError is set when failed>0, that the HTTP layer returns 400 on total failure, and critically that qurl_link values are shown only ONCE. These are exactly the traits an agent needs before calling.

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 and the single-call alternative are front-loaded, and the bolded subsections (Not transactional, Response shape, Partial failure signaling, One-shot links) are skimmable. It is somewhat over-stuffed and repeats response details that the output schema already covers, which keeps it short of a 5.

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 batch mint tool with nested item schemas and real failure modes, the description covers scope, routing, failure semantics, and the irreversible one-shot link behavior. Nothing an agent needs in order to invoke it correctly is missing.

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

Parameters3/5

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

Schema description coverage is 100% and the single top-level parameter (items) is fully documented in the schema, including maxItems 100 and all nested fields. The description adds the 1-100 bound and per-item independence but no parameter-level syntax beyond that, so the baseline 3 applies.

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 (Create), resource (qURLs), and scope (up to 100 in a single request), and explicitly positions itself against `create_qurl` and the upload tools. An agent can distinguish it from all listed siblings without opening a 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 ('when the user explicitly wants multiple qURLs in one request', 'provisioning a vendor list'), when-not-to-use ('never for a single URL/file/image/attachment'), and names the correct alternatives for uploaded files and base64 content, including mode-specific tools.

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

Deploy Server