PUT request method

The PUT HTTP method creates a new resource or replaces a representation of the target resource with the request {{Glossary("HTTP Content", "content")}}.

The difference between PUT and {{HTTPMethod("POST")}} is that PUT is {{Glossary("idempotent")}}: calling it once is no different from calling it several times successively (there are no side effects).

Syntax

PUT <request-target>["?"<query>] HTTP/1.1

• <request-target>
  • : Identifies the target resource of the request when combined with the information provided in the {{HTTPHeader("Host")}} header. This is an absolute path (e.g., /path/to/file.html) in requests to an origin server, and an absolute URL in requests to proxies (e.g., http://www.example.com/path/to/file.html).
• <query> {{optional_inline}}
  • : An optional query component preceded by a question-mark ?. Often used to carry identifying information in the form of key=value pairs.

Examples

Successfully creating a resource

The following PUT request asks to create a resource at example.com/new.html with the content <p>New File</p>:

PUT /new.html HTTP/1.1
Host: example.com
Content-type: text/html
Content-length: 16

<p>New File</p>

If the target resource does not have a current representation and the PUT request successfully creates one, then the origin server must send a {{HTTPStatus("201", "201 Created")}} response:

HTTP/1.1 201 Created
Content-Location: /new.html

If the target resource does have a current representation and that representation is successfully modified with the state in the request, the origin server must send either a {{HTTPStatus("200", "200 OK")}} or a {{HTTPStatus("204", "204 No Content")}} to indicate successful completion of the request:

HTTP/1.1 204 No Content
Content-Location: /existing.html

Specifications

{{Specifications}}

Browser compatibility

The browser doesn't use the PUT method for user-initiated actions, so "browser compatibility" doesn't apply. Developers can set this request method using fetch().

See also

• HTTP request methods
• HTTP response status codes
• HTTP headers
• {{HTTPStatus("201", "201 Created")}}, {{HTTPStatus("204", "204 No Content")}} response statuses