Create qURL
create_qurlCreate 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.
Instructions
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'] } }).
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| type | No | Resource type for integrations allowed to mint non-url qURLs (max 64 chars). Defaults to url. | |
| label | No | Human-readable label identifying who this qURL is for (max 500 chars) | |
| expires_in | No | Duration string (e.g., "1h", "24h", "7d"; the API enforces 1m to 30d) | |
| target_url | Yes | The URL to protect with qURL | |
| max_sessions | No | Maximum concurrent sessions for this qURL token (0 = unlimited when one_time_use is explicitly false; max 1000) | |
| one_time_use | No | Whether the link can only be used once | |
| access_policy | No | Access control policy for the qURL | |
| custom_domain | No | Custom domain to assign to the auto-created resource (max 253 chars, must be registered/active/owned). | |
| session_duration | No | 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. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| type | No | Resource type echoed from the create request | |
| label | No | ||
| qurl_id | Yes | Display-friendly qURL ID (q_ prefix) | |
| qurl_link | Yes | One-shot display access link — shown ONCE on creation, never returned again. Share immediately. | |
| qurl_site | No | ||
| expires_at | No | ||
| resource_id | Yes | Stable resource identifier (public key or legacy r_ ID) | |
| branded_domain | No | Bare branded hostname for anchor text when the resource has a usable custom domain | |
| email_delivery | No |