HTTP 201 Created — Resource Creation Response & Best Practices
A new resource was successfully created as a result of the request. The response should include a Location header pointing to the URL of the newly created resource, and optionally the resource itself in the body.
When to Return 201
Use 201 for successful POST requests that create a new resource. Include a Location header with the URL of the new resource (e.g., Location: /users/123). Returning the created resource in the body is optional but common.
HTTP Response Example
HTTP/1.1 201 Created
Location: /users/123
Content-Type: application/json
{"id": 123, "name": "Bob", "email": "bob@example.com"}Code Examples
Express.js
app.post('/users', async (req, res) => {
const user = await db.users.create(req.body)
res
.status(201)
.location(`/users/${user.id}`)
.json(user)
})Next.js App Router
// app/api/users/route.ts
export async function POST(request: Request) {
const body = await request.json()
const user = await db.users.create(body)
return Response.json(user, {
status: 201,
headers: { Location: `/api/users/${user.id}` },
})
}Related Status Codes
Frequently Asked Questions
What does HTTP 201 Created mean?
A new resource was successfully created as a result of the request. The response should include a Location header pointing to the URL of the newly created resource, and optionally the resource itself in the body.
When should an API return 201?
Use 201 for successful POST requests that create a new resource. Include a Location header with the URL of the new resource (e.g., Location: /users/123). Returning the created resource in the body is optional but common.
When should I NOT use 201?
Returning 201 from a GET request or from a POST that doesn't create a new resource.