From 0f194eeec7361882ea2e86f92d696bb0eabb30fd Mon Sep 17 00:00:00 2001
From: Thomas <31560900+0xtlt@users.noreply.github.com>
Date: Mon, 6 Jul 2026 11:45:56 +0200
Subject: [PATCH] docs: document signed URL pattern lookup opt-out

---
 content/guides/basics/url_builder.md | 22 ++++++++++++++++++++++
 1 file changed, 22 insertions(+)

diff --git a/content/guides/basics/url_builder.md b/content/guides/basics/url_builder.md
index 74c551c..5456072 100644
--- a/content/guides/basics/url_builder.md
+++ b/content/guides/basics/url_builder.md
@@ -213,6 +213,28 @@ export default class NewsletterMail extends BaseMail {
 
 The `expiresIn` option sets when the signed URL expires. After expiration, the signature is no longer valid. The `prefixUrl` option is required when the URL will be shared externally, such as in emails or external notifications, to ensure the URL includes the full domain. For internal app navigation, relative URLs without the domain are sufficient.
 
+### Creating signed URLs from route patterns
+
+By default, `signedUrlFor` looks up the route by its name and uses the route definition to build the URL. You may disable the lookup when you need to sign a URL from a route pattern that is not registered in the router.
+
+```ts
+import { signedUrlFor } from '@adonisjs/core/services/url_builder'
+
+const url = signedUrlFor(
+  '/files/:key',
+  { key: 'invoice.pdf' },
+  {
+    disableRouteLookup: true,
+    prefixUrl: 'https://example.com',
+    qs: {
+      download: true,
+    },
+  }
+)
+```
+
+When `disableRouteLookup` is enabled, the first argument is parsed as a route pattern and signed directly. Regular `signedUrlFor` calls continue to use route lookup and keep their route-name type safety.
+
 The generated signed URL includes a signature query parameter appended to the URL.
 
 ```text