How can Vercel build a response header from a captured URL segment?

Definition: A Vercel header rule matches an incoming pathname and sets one or more response header key/value pairs. A named path parameter can be reused in a configured header value, so a URL segment becomes part of the emitted header.

Key facts

• Vercel supports custom headers in vercel.json; its system headers reference points to the project configuration documentation for this feature. Vercel's System Headers documentation describes custom headers as application-specific metadata.
• The headers property is an array of header objects. Each object has a source pattern and a non-empty headers array containing response header key/value pairs. Vercel's vercel.json reference defines both fields.
• A source pattern matches the incoming pathname without the query string. The same Vercel reference shows /service-worker.js, /(.*), and /:path* as source patterns.
• In the official headers configuration syntax, a matched parameter can be placed in a header value. The example /blog/:slug uses value: ':slug'. Next.js's headers reference documents this substitution.
• The *, +, and ? modifiers control how many path segments a named parameter may match. The :slug* form can match zero or more segments, including /blog, /blog/a, and /blog/a/b/c. The same headers reference lists these forms.

How do you capture the URL segment?

Put a named parameter in the rule's source, then repeat the parameter name in the response header's value. Vercel's headers configuration uses a source pattern and nested response header objects. The documented header syntax uses the captured value in both header keys and values.

{
  "headers": [
    {
      "source": "/blog/:slug",
      "headers": [
        {
          "key": "x-slug",
          "value": ":slug"
        }
      ]
    }
  ]
}

With this rule, a request for /blog/first-post supplies first-post to :slug, producing x-slug: first-post. The path form matches one segment. The official example also shows /blog/post-1 as a match and /blog/a/b as outside the pattern.

How do wildcard and regex captures work?

Use :slug* when the header should contain a nested path. The documented wildcard example uses source: '/blog/:slug*' and value: ':slug*'; it matches /blog, /blog/a, and /blog/a/b/c. A + modifier requires one or more segments, while ? allows zero or one segment.

For a constrained segment, put a regular expression in parentheses after the parameter name. The official example uses source: '/blog/:post(\\d{1,})' and value: ':post'. It matches /blog/123 and does not match /blog/abc.

The Vercel configuration reference also describes regular expressions in its lower-level routes syntax. There, src matches each incoming pathname and dest can embed numbered capture groups such as $1 or a named capture value such as $name. That destination substitution is a separate route feature from the headers array's path parameter syntax.

Which request data can a header rule inspect?

The source pattern operates on the path. Vercel's header object reference also supports optional has and missing arrays for conditional matching. Their type can be header, cookie, host, or query, and Vercel specifies that these conditions apply to request data sent by clients.

The header reference gives a further example of named captures from request conditions: a header value matching (?<authorized>yes|true) can be reused as :authorized in a configured header value. A plain condition such as value: 'home' supplies a match condition without a named capture for the header key or value.

Related terms

• How do I add an X-Robots-Tag header on Vercel?
• How do I read Vercel's request and cache response headers?
• How do I redirect a whole URL section on Vercel?
• Can Vercel serve content from another origin while retaining the public URL?

FAQ

Can a query string supply the captured value?

No. Vercel defines source as a pattern for the incoming pathname excluding the query string, so the path parameter comes from the URL path.

Can one capture include several path segments?

Yes. Use a wildcard parameter such as :slug*, then reference :slug* in the header value. The documented form includes zero or more segments.

How can a rule accept only digits?

Vercel's route reference defines src as a PCRE-compatible regular expression and dest as supporting numbered or named capture groups. For a header value, use the parameter form shown in the regex example above and repeat :post in value.

Sources

1. Vercel, "System Headers", 11 August 2026
2. Vercel, "Static Configuration with vercel.json", 14 August 2026
3. Vercel, "Build Output Configuration", 27 July 2026
4. Next.js, "headers", 15 April 2025

---

Check how a page reads to answer engines. Open the GEO score analyzer