# 201 Created

> https://http-status.org/docs/201

**Family:** 2xx Success

## Rationale

Request succeeded and created a new resource.

## In Plain Terms

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

## Description

The HTTP 201 Created status code indicates that the request has been fulfilled and resulted in one or more new resources being created. The primary new resource is typically identified by a Location header or by the target URI itself.

## Server Perspective

### Usage
- 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

### Implementation
- 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

### Common Headers
- 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.

### Body
- Optionally include the created resource or creation result in the response body

### 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

## Client Perspective

### Pitfalls
- Do not assume every 201 response includes a full resource body

## Examples

### Creating a new blog post

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

**Request:**
```
POST https://api.example.test/api/posts
```

**Response:**
```
201 Created
Location: https://api.example.test/api/posts/456
Content-Type: application/json

{
  "id": 456,
  "status": "created"
}
```

## Related Codes

- [200 OK](/docs/200.md)
- [202 Accepted](/docs/202.md)
- [204 No Content](/docs/204.md)