201 Created

A new resource created as a result of the request is confirmed by the 201 Created status code.

Table of Contents

Usage
Example
Code references
See also

Usage

The 201 Created status code is returned when a request creates one or more new resources. This commonly follows a POST or PUT request. The server includes a Location header pointing to the newly created resource. When the Location header is absent, the created resource lives at the path specified in the original request.

Note

A PUT request creating a resource at a specific URI also returns 201 Created. The distinction is the client specifies the target URI directly with PUT, while the server determines the URI with POST.

The spec allows a body in a 201 response. REST convention is to return the created resource representation, including server-assigned fields such as id, timestamps, and URIs. This avoids a follow-up GET request to retrieve the new resource. The Location header points to the new resource URI.

Note

201 means the resource is created immediately and available at the Location URI. 202 means the request is accepted but processing is not yet complete, which is common for async workflows and queued jobs.

SEO impact

Google waits briefly for content from 201 responses, then passes received content to the indexing pipeline. Indexing is not guaranteed.

Example

The client uploads XML data to the server, specifying /incoming/xml as the destination path. The server responds confirming the data was accepted and a file named article_1.xml was created.

Request

POST /incoming/xml HTTP/1.1
Host: www.example.re
Content-Type: application/xml
Content-Length: 105

<?xml version="1.0"?>
<article>
  <title>Test XML article</title>
  <author>Anonymous</author>
</article>

Response

HTTP/1.1 201 Created
Location: /incoming/xml/article_1.xml
Content-Type: application/json
Content-Length: 18

{"success":"true"}

Code references

.NET

HttpStatusCode.Created

Rust

http::StatusCode::CREATED

Rails

:created

http.StatusCreated

Symfony

Response::HTTP_CREATED

Python3.5+

http.HTTPStatus.CREATED

Java

java.net.HttpURLConnection.HTTP_CREATED

Apache HttpComponents Core

org.apache.hc.core5.http.HttpStatus.SC_CREATED

Angular

@angular/common/http/HttpStatusCode.Created