Created

Overview

201 Created means the request succeeded and, as a result, a new resource was created. It is typically returned for POST or PUT, and the URL of the new resource is given in the Location header.

The response body commonly includes a representation of the created resource (for example a server-assigned id and creation time) so the client can reference it immediately.

When it happens

• Return it when a REST API POSTs to a collection to make a new record, or a PUT to a specific URL creates a resource at that location.
• It fits any write that adds a new item to server state — sign-ups, order creation, file uploads, and so on.

Request / Response example

POST /api/articles HTTP/1.1
Host: api.example.com
Content-Type: application/json

{"title":"Hello","body":"First post"}

HTTP/1.1 201 Created
Location: /api/articles/1024
Content-Type: application/json

{"id":1024,"title":"Hello"}

In code

app.post('/api/articles', (req, res) => {
  const id = db.insert(req.body);
  res.status(201).location(`/api/articles/${id}`).json({ id });
});

@app.post('/api/articles')
def create():
    aid = db.insert(request.json)
    return {'id': aid}, 201, {'Location': f'/api/articles/{aid}'}

Notes

• By convention the Location header carries the new resource's URL, letting the client do a follow-up GET right away.
• If the resource is accepted but processed asynchronously, 202 Accepted is more accurate than 201.
• To avoid creating a new resource on every retry, consider PUT or an Idempotency-Key pattern when creation must be idempotent.

Related status codes

Related headers

Specification