Created
ActiveHTTP 201 Created indicates the request has been fulfilled and a new resource has been created. Defined in RFC 9110 §15.3.2. The response should include a Location header with the URI of the new resource.
Description
The 201 Created status code indicates that the request has been fulfilled and has resulted in one or more new resources being created. The primary resource created by the request is identified by either a Location header field in the response or, if no Location header is received, by the target URI.
The 201 response content typically describes and links to the resource(s) created.
Examples
POST /api/users HTTP/1.1
Host: api.example.com
Content-Type: application/json
{"name": "Bob", "email": "[email protected]"}HTTP/1.1 201 Created
Location: /api/users/43
Content-Type: application/json
{"id": 43, "name": "Bob", "email": "[email protected]", "created_at": "2024-01-15T10:30:00Z"}Edge Cases
- •The Location header should point to the newly created resource's canonical URL.
- •If multiple resources are created, only the primary one should be in Location.
- •201 should only be sent after the resource is fully created, not for async creation (use 202).
When You'll See This
- →Creating a new user account
- →Adding an item to a collection via POST
- →Uploading a file and receiving the file's new URL
Implementation References
| Language | Constant |
|---|---|
| Go | http.StatusCreated |
| Rust | http::StatusCode::CREATED |
| Python | http.HTTPStatus.CREATED |
| Node.js | http.STATUS_CODES[201] |
| .NET | HttpStatusCode.Created |
| Java | HttpURLConnection.HTTP_CREATED |
History
Introduced in HTTP/1.0 (RFC 1945, 1996). Essential to RESTful API design where POST creates resources.
Related Status Codes
Related Headers
FAQ
What does HTTP 201 Created mean?
HTTP 201 Created means the request succeeded and a new resource was created. The Location header typically contains the URL of the new resource.
Should POST always return 201?
POST should return 201 when it creates a new resource. If POST processes data without creating a resource (like a search), use 200 instead.