Catch-all API routes in NextJS - Step-by-Step Execution

Concept Flow - Catch-all API routes

Request comes in

↓

Check API routes folder

↓

Match specific route?

No→Match catch-all route?

↓

Run specific handler

↓

Send response

When a request arrives, Next.js first looks for a specific API route match. If none is found, it checks for a catch-all route to handle multiple paths dynamically.

Execution Sample

NextJS

export function GET(request, { params }) {
  const { slug } = params;
  return new Response(JSON.stringify({ slug }), { status: 200 });
}

// File path: /app/api/[[...slug]]/route.js

This catch-all API route captures all paths under /api and returns the path segments as JSON.

Execution Table

Step	Request URL	Route Matched	slug value	Response Body
1	/api	/api/[[...slug]]	undefined	{"slug":null}
2	/api/a	/api/[[...slug]]	["a"]	{"slug":["a"]}
3	/api/a/b	/api/[[...slug]]	["a","b"]	{"slug":["a","b"]}
4	/api/a/b/c	/api/[[...slug]]	["a","b","c"]	{"slug":["a","b","c"]}
5	/api/specific	/api/specific (if exists)	N/A	Specific handler response
6	/api/unknownroute	/api/[[...slug]]	["unknownroute"]	{"slug":["unknownroute"]}
7	/other	No match	N/A	404 Not Found

💡 Execution stops when a matching route is found or no route matches, resulting in 404.

Variable Tracker

Variable	Start	After 1	After 2	After 3	After 4	After 5	After 6	After 7
slug	undefined	undefined	["a"]	["a","b"]	["a","b","c"]	N/A	["unknownroute"]	N/A
Route Matched	N/A	/api/[[...slug]]	/api/[[...slug]]	/api/[[...slug]]	/api/[[...slug]]	/api/specific or N/A	/api/[[...slug]]	No match

Key Moments - 3 Insights

Why is slug undefined when requesting /api without extra path?

Because the catch-all route [[...slug]] captures path segments after /api. If no extra segment exists, slug is undefined as shown in execution_table row 1.

What happens if a more specific route like /api/specific exists?

Next.js matches the specific route first before the catch-all. So /api/specific triggers its own handler, not the catch-all, as shown in execution_table row 5.

Why does /other return 404?

Because it does not match any API route under /api, so no handler runs and Next.js returns 404, as shown in execution_table row 7.

Visual Quiz - 3 Questions

Look at the execution table, what is the slug value when requesting /api/a/b?

A ["a","b"]

B ["a"]

C undefined

D ["a","b","c"]

💡 Hint

Check execution_table row 3 under slug value column.

At which step does the route /api/specific get matched if it exists?

A Step 6

B Step 2

C Step 5

D Step 7

💡 Hint

Look at execution_table row 5 under Route Matched column.

If you request /api with no extra path, what will the response body be?

A {"slug":[""]}

B {"slug":null}

C {"slug":[]}

D 404 Not Found

💡 Hint

See execution_table row 1 for response body.

Concept Snapshot

Catch-all API routes use [[...slug]] in file names to capture multiple path segments.
The slug parameter is an array of path parts or undefined if none.
Specific routes take priority over catch-all.
Requests not matching any route return 404.
Use params.slug to access path segments in handler.

Full Transcript

Catch-all API routes in Next.js let you handle many paths with one file using [[...slug]]. When a request comes in, Next.js first looks for a specific route. If none matches, it uses the catch-all route. The slug parameter contains the path parts as an array or is undefined if no extra path is given. For example, /api/a/b sets slug to ["a","b"]. If a specific route like /api/specific exists, it runs instead of the catch-all. Requests outside /api return 404. This lets you build flexible APIs that handle many URLs with one handler.