Skip to main content
Route Handlers let you create custom HTTP endpoints for a route using the Web Request and Response APIs.
route.ts
export async function GET() {
  return Response.json({ message: 'Hello World' })
}

​
HTTP methods

The following HTTP methods are supported: GET, POST, PUT, PATCH, DELETE, HEAD, and OPTIONS.
route.ts
export async function GET(request: Request) {}
export async function HEAD(request: Request) {}
export async function POST(request: Request) {}
export async function PUT(request: Request) {}
export async function DELETE(request: Request) {}
export async function PATCH(request: Request) {}
export async function OPTIONS(request: Request) {}
If OPTIONS is not defined, Next.js automatically implements it and sets the Allow response header based on the other defined methods.

​
Parameters

​
request
NextRequest
A NextRequest object, which extends the Web Request API with convenience methods for cookies and a parsed nextUrl object.
route.ts
import type { NextRequest } from 'next/server'

export async function GET(request: NextRequest) {
  const url = request.nextUrl
}
​
context
object
An optional second parameter containing route context.context.params — a promise that resolves to the dynamic route parameters for the current route.
app/dashboard/[team]/route.ts
export async function GET(
  request: Request,
  { params }: { params: Promise<{ team: string }> }
) {
  const { team } = await params
}
RouteURLparams
app/dashboard/[team]/route.js/dashboard/1Promise<{ team: '1' }>
app/shop/[tag]/[item]/route.js/shop/1/2Promise<{ tag: '1', item: '2' }>
app/blog/[...slug]/route.js/blog/1/2Promise<{ slug: ['1', '2'] }>

​
TypeScript helper

Use the global RouteContext helper for strongly typed route params:
app/users/[id]/route.ts
import type { NextRequest } from 'next/server'

export async function GET(_req: NextRequest, ctx: RouteContext<'/users/[id]'>) {
  const { id } = await ctx.params
  return Response.json({ id })
}
Types are generated during next dev, next build, or next typegen. RouteContext is globally available and does not need to be imported.

​
Examples

​
Reading and setting cookies

route.ts
import { cookies } from 'next/headers'

export async function GET(request: Request) {
  const cookieStore = await cookies()
  const token = cookieStore.get('token')

  return new Response('Hello', {
    headers: { 'Set-Cookie': `token=${token?.value}` },
  })
}

​
Reading request headers

route.ts
import { headers } from 'next/headers'

export async function GET(request: Request) {
  const headersList = await headers()
  const referer = headersList.get('referer')

  return new Response('Hello', {
    headers: { referer: referer ?? '' },
  })
}

​
Reading the request body

app/items/route.ts
export async function POST(request: Request) {
  const body = await request.json()
  return Response.json({ received: body })
}

​
Reading form data

app/items/route.ts
export async function POST(request: Request) {
  const formData = await request.formData()
  const name = formData.get('name')
  const email = formData.get('email')
  return Response.json({ name, email })
}

​
URL query parameters

app/api/search/route.ts
import { type NextRequest } from 'next/server'

export function GET(request: NextRequest) {
  const searchParams = request.nextUrl.searchParams
  const query = searchParams.get('query')
  // query is "hello" for /api/search?query=hello
}

​
Dynamic route segments

app/items/[slug]/route.ts
export async function GET(
  request: Request,
  { params }: { params: Promise<{ slug: string }> }
) {
  const { slug } = await params
  return Response.json({ slug })
}

​
Redirects

app/api/route.ts
import { redirect } from 'next/navigation'

export async function GET(request: Request) {
  redirect('https://nextjs.org/')
}

​
Streaming responses

app/api/route.ts
export async function GET() {
  const encoder = new TextEncoder()

  const stream = new ReadableStream({
    async start(controller) {
      controller.enqueue(encoder.encode('<p>One</p>'))
      await new Promise(r => setTimeout(r, 200))
      controller.enqueue(encoder.encode('<p>Two</p>'))
      controller.close()
    },
  })

  return new Response(stream)
}

​
CORS headers

app/api/route.ts
export async function GET(request: Request) {
  return new Response('Hello', {
    headers: {
      'Access-Control-Allow-Origin': '*',
      'Access-Control-Allow-Methods': 'GET, POST, PUT, DELETE, OPTIONS',
      'Access-Control-Allow-Headers': 'Content-Type, Authorization',
    },
  })
}

​
Webhooks

app/api/webhook/route.ts
export async function POST(request: Request) {
  try {
    const text = await request.text()
    // process the webhook payload
  } catch (error) {
    return new Response(`Webhook error: ${error.message}`, { status: 400 })
  }

  return new Response('Success!', { status: 200 })
}

​
Non-UI responses

app/rss.xml/route.ts
export async function GET() {
  return new Response(
    `<?xml version="1.0" encoding="UTF-8" ?>
<rss version="2.0">
  <channel>
    <title>My Site</title>
    <link>https://example.com</link>
  </channel>
</rss>`,
    { headers: { 'Content-Type': 'text/xml' } }
  )
}

​
Revalidating cached data

app/posts/route.ts
export const revalidate = 60

export async function GET() {
  const data = await fetch('https://api.vercel.app/blog')
  const posts = await data.json()
  return Response.json(posts)
}

​
Version history

VersionChanges
v15.0.0-RCcontext.params is now a promise
v15.0.0-RCDefault caching for GET handlers changed from static to dynamic
v13.2.0Route Handlers introduced

Build docs developers (and LLMs) love

Get started for freeTalk to us