Back to list
201

Created

2xx Success

.md

ELI5

Something new was created! Like adding a new post, user account, or file - the server made it and it now exists.

Server perspective

Use 201 when the request succeeded and created a new resource.

When to use

  • •Return 201 after POST creates a resource
  • •Use it for PUT when the target URI did not exist and the request created it
  • •POST requests that successfully create new resources
  • •PUT requests that create a new resource at a specific URI
  • •File uploads that create new files
  • •User registration that creates new accounts

How to respond

  • •Include a Location header when it helps identify the newly created resource
  • •Return a representation of the created resource when that makes the API easier to use

Headers to consider

  • •Include a Location header pointing to the new resource URI when it differs from the request URI.
  • •Include ETag if the API returns a validator with the created resource.

Response body

  • •Optionally include the created resource or creation result in the response body

Server-side pitfalls

  • •Do not use 201 for ordinary updates that did not create anything new
  • •Do not omit the resource identity when clients need to know where the new resource lives
  • •Updates that do not create a new resource
  • •Accepted-but-not-finished async work (use 202 Accepted)
  • •Successful requests with no representation or useful body when 204 fits better

Examples

Creating a new blog post

Request:POST https://api.example.test/api/posts
Response:201 Created # Headers Location: https://api.example.test/api/posts/456 Content-Type: application/json # Body { "id": 456, "status": "created" }

The server created a new blog post and points the client to the canonical URI for it.

References

Related Status Codes

200

OK

Everything worked perfectly! The server understood your request and sent back exactly what you asked for.

202

Accepted

We got your request and we're working on it! We'll process it later, but don't wait around - check back later to see if it's done.

204

No Content

Success. The server did what you asked, but there’s nothing useful to send back in the body.