HTTP Working Group M. Kleidl, Ed.
Internet-Draft Transloadit
Intended status: Standards Track G. Zhang, Ed.
Expires: May 14, 2027 Apple Inc.
L. Pardue, Ed.
Apple
November 10, 2026
Resumable Uploads for HTTP
draft-ietf-httpbis-resumable-upload-latest
Abstract
HTTP data transfers can encounter interruption due to reasons such as
canceled requests or dropped connections. If the intended recipient
can indicate how much of the data was processed prior to
interruption, a sender can resume data transfer at that point instead
of attempting to transfer all of the data again. HTTP range requests
support this concept of resumable downloads from server to client.
This document describes a mechanism that supports resumable uploads
from client to server using HTTP.
About This Document
This note is to be removed before publishing as an RFC.
Status information for this document may be found at
.
Discussion of this document takes place on the HTTP Working Group
mailing list (), which is archived at
. Working Group
information can be found at .
Source for this draft and an issue tracker can be found at
.
Status of This Memo
This Internet-Draft is submitted in full conformance with the
provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet-
Drafts is at https://datatracker.ietf.org/drafts/current/.
Kleidl, et al. Expires May 14, 2027 [Page 1]
Internet-Draft Resumable Uploads November 2026
Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress."
This Internet-Draft will expire on May 14, 2027.
Copyright Notice
Copyright (c) 2026 IETF Trust and the persons identified as the
document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents
(https://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents
carefully, as they describe your rights and restrictions with respect
to this document. Code Components extracted from this document must
include Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License.
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4
2. Conventions and Definitions . . . . . . . . . . . . . . . . . 5
3. Overview . . . . . . . . . . . . . . . . . . . . . . . . . . 6
3.1. Example 1: Complete Upload of Representation Data with
Known Size . . . . . . . . . . . . . . . . . . . . . . . 6
3.2. Example 2: Upload as a Series of Parts . . . . . . . . . 8
4. Upload Resource . . . . . . . . . . . . . . . . . . . . . . . 11
4.1. Offset . . . . . . . . . . . . . . . . . . . . . . . . . 11
4.1.1. Upload-Offset . . . . . . . . . . . . . . . . . . . . 12
4.2. Completeness . . . . . . . . . . . . . . . . . . . . . . 12
4.2.1. Upload-Complete . . . . . . . . . . . . . . . . . . . 12
4.3. Length . . . . . . . . . . . . . . . . . . . . . . . . . 13
4.3.1. Upload-Length . . . . . . . . . . . . . . . . . . . . 14
5. Upload Limits . . . . . . . . . . . . . . . . . . . . . . . . 14
5.1. Upload-Limit . . . . . . . . . . . . . . . . . . . . . . 14
5.1.1. max-size . . . . . . . . . . . . . . . . . . . . . . 15
5.1.2. min-size . . . . . . . . . . . . . . . . . . . . . . 15
5.1.3. max-append-size . . . . . . . . . . . . . . . . . . . 15
5.1.4. min-append-size . . . . . . . . . . . . . . . . . . . 16
5.1.5. max-age . . . . . . . . . . . . . . . . . . . . . . . 16
5.2. Use with OPTIONS . . . . . . . . . . . . . . . . . . . . 16
5.3. Limit Changes . . . . . . . . . . . . . . . . . . . . . . 17
5.4. Limit Violations . . . . . . . . . . . . . . . . . . . . 17
6. Upload Creation . . . . . . . . . . . . . . . . . . . . . . . 18
Kleidl, et al. Expires May 14, 2027 [Page 2]
Internet-Draft Resumable Uploads November 2026
6.1. Client Behavior . . . . . . . . . . . . . . . . . . . . . 18
6.2. Server Behavior . . . . . . . . . . . . . . . . . . . . . 19
6.3. Examples . . . . . . . . . . . . . . . . . . . . . . . . 21
7. Offset Retrieval . . . . . . . . . . . . . . . . . . . . . . 23
7.1. Client Behavior . . . . . . . . . . . . . . . . . . . . . 23
7.2. Server Behavior . . . . . . . . . . . . . . . . . . . . . 23
7.3. Examples . . . . . . . . . . . . . . . . . . . . . . . . 24
8. Upload Append . . . . . . . . . . . . . . . . . . . . . . . . 24
8.1. Client Behavior . . . . . . . . . . . . . . . . . . . . . 24
8.2. Server Behavior . . . . . . . . . . . . . . . . . . . . . 25
8.3. Examples . . . . . . . . . . . . . . . . . . . . . . . . 27
9. Upload Cancellation . . . . . . . . . . . . . . . . . . . . . 28
9.1. Client Behavior . . . . . . . . . . . . . . . . . . . . . 28
9.2. Server Behavior . . . . . . . . . . . . . . . . . . . . . 28
9.3. Example . . . . . . . . . . . . . . . . . . . . . . . . . 29
10. Concurrency . . . . . . . . . . . . . . . . . . . . . . . . . 29
11. Retry . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
12. Status Code 104 (Upload Resumption Supported) . . . . . . . . 31
13. Media Type application/partial-upload . . . . . . . . . . . . 31
14. Problem Types . . . . . . . . . . . . . . . . . . . . . . . . 31
14.1. Mismatching Offset . . . . . . . . . . . . . . . . . . . 31
14.2. Inconsistent Length . . . . . . . . . . . . . . . . . . 32
15. Content Codings . . . . . . . . . . . . . . . . . . . . . . . 33
16. Transfer Codings . . . . . . . . . . . . . . . . . . . . . . 33
17. Upload Strategies . . . . . . . . . . . . . . . . . . . . . . 33
17.1. Optimistic Upload Creation . . . . . . . . . . . . . . . 33
17.1.1. Upgrading to Resumable Uploads . . . . . . . . . . . 34
17.2. Careful Upload Creation . . . . . . . . . . . . . . . . 35
18. Incremental Transfer, Processing, and Forwarding . . . . . . 35
19. Request Cancellation . . . . . . . . . . . . . . . . . . . . 36
20. Security Considerations . . . . . . . . . . . . . . . . . . . 36
20.1. Upload Resource URIs . . . . . . . . . . . . . . . . . . 36
20.2. Untrusted Input . . . . . . . . . . . . . . . . . . . . 37
20.3. Content Scanning . . . . . . . . . . . . . . . . . . . . 37
20.4. Time-of-Check to Time-of-Use . . . . . . . . . . . . . . 37
20.5. Resource Exhaustion . . . . . . . . . . . . . . . . . . 37
20.6. Message Size Limits . . . . . . . . . . . . . . . . . . 37
20.7. Different Origins . . . . . . . . . . . . . . . . . . . 38
21. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 38
21.1. HTTP Fields . . . . . . . . . . . . . . . . . . . . . . 38
21.2. HTTP Status Code . . . . . . . . . . . . . . . . . . . . 39
21.3. Media Type . . . . . . . . . . . . . . . . . . . . . . . 39
21.4. HTTP Problem Types . . . . . . . . . . . . . . . . . . . 40
22. References . . . . . . . . . . . . . . . . . . . . . . . . . 41
22.1. Normative References . . . . . . . . . . . . . . . . . . 41
22.2. Informative References . . . . . . . . . . . . . . . . . 42
Appendix A. Changes . . . . . . . . . . . . . . . . . . . . . . 42
A.1. Since draft-ietf-httpbis-resumable-upload-14 . . . . . . 42
Kleidl, et al. Expires May 14, 2027 [Page 3]
Internet-Draft Resumable Uploads November 2026
A.2. Since draft-ietf-httpbis-resumable-upload-13 . . . . . . 43
A.3. Since draft-ietf-httpbis-resumable-upload-12 . . . . . . 43
A.4. Since draft-ietf-httpbis-resumable-upload-11 . . . . . . 43
A.5. Since draft-ietf-httpbis-resumable-upload-10 . . . . . . 44
A.6. Since draft-ietf-httpbis-resumable-upload-09 . . . . . . 44
A.7. Since draft-ietf-httpbis-resumable-upload-08 . . . . . . 44
A.8. Since draft-ietf-httpbis-resumable-upload-07 . . . . . . 45
A.9. Since draft-ietf-httpbis-resumable-upload-06 . . . . . . 45
A.10. Since draft-ietf-httpbis-resumable-upload-05 . . . . . . 45
A.11. Since draft-ietf-httpbis-resumable-upload-04 . . . . . . 45
A.12. Since draft-ietf-httpbis-resumable-upload-03 . . . . . . 46
A.13. Since draft-ietf-httpbis-resumable-upload-02 . . . . . . 46
A.14. Since draft-ietf-httpbis-resumable-upload-01 . . . . . . 46
A.15. Since draft-ietf-httpbis-resumable-upload-00 . . . . . . 47
A.16. Since draft-tus-httpbis-resumable-uploads-protocol-02 . . 47
A.17. Since draft-tus-httpbis-resumable-uploads-protocol-01 . . 47
A.18. Since draft-tus-httpbis-resumable-uploads-protocol-00 . . 47
Appendix B. Draft Version Identification . . . . . . . . . . . . 47
Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 48
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 49
1. Introduction
HTTP data transfers can encounter interruption due to reasons such as
canceled requests or dropped connections. If the intended recipient
can indicate how much of the data was processed prior to
interruption, a sender can resume data transfer at that point instead
of attempting to transfer all of the data again. HTTP range requests
(see Section 14 of [HTTP]) support this concept of resumable data
transfers for downloads from server to client. While partial PUT is
one method for uploading a partial representation (via the "Content-
Range" header field in the request), there are caveats that affect
its deployability; see Section 14.5 of [HTTP].
Upload requests can be canceled for various reasons, including but
not limited to:
explicit client cancellation: e.g., terminating a user-agent process
implicit client cancellation: e.g., terminating a tab, garbage
collecting a process, or an internal error
explicit server cancellation: e.g., scheduled maintenance
implicit server cancellation: e.g., denial-of-service mitigation or
an internal error
Kleidl, et al. Expires May 14, 2027 [Page 4]
Internet-Draft Resumable Uploads November 2026
Connections can be dropped due to a variety of network or transport
layer reasons triggered by endpoints or on-path elements.
This specification defines a new mechanism for resumable uploads from
client to server that can seamlessly fall back to conventional
uploads. When an upload is interrupted, clients can send subsequent
requests to query the server state and use this information to send
the remaining representation data. Alternatively, they can cancel
the upload entirely. Unlike ranged downloads, this protocol does not
support transferring an upload as multiple requests in parallel.
With resumable uploads, applications can recover from unintended
interruptions. They can also interrupt an upload on purpose and
resume it later, for example, when a user wants to pause the upload,
the device's network connectivity changes, or bandwidth is needed for
higher-priority tasks.
This document introduces the concept of an upload resource to
facilitate resumable uploads (Section 4). It defines new header
fields to communicate the state of the upload (Section 4.1.1,
Section 4.2.1, Section 4.3.1, and Section 5.1) and the "104 (Upload
Resumption Supported)" status code to indicate the resource's support
for resumable uploads (Section 12). It also defines the
"application/partial-upload" media type to label partial
representation data when resuming an upload (Section 13).
2. Conventions and Definitions
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
"OPTIONAL" in this document are to be interpreted as described in
BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all
capitals, as shown here.
Some examples in this document contain long lines that are folded, as
described in [RFC8792].
This document uses the following terminology from Section 3 of
[STRUCTURED-FIELDS] to specify syntax and parsing: Item, Dictionary,
Integer, and Boolean.
This document uses the following terms from Section 3 of [HTTP]:
"representation", "representation data", "representation metadata",
"content", "client", and "server".
This document uses the term "URI" as defined in [URI].
This document uses the term "patch document" from [PATCH].
Kleidl, et al. Expires May 14, 2027 [Page 5]
Internet-Draft Resumable Uploads November 2026
An _upload resource_ is a temporary resource on the server that
facilitates the resumable upload of one representation (Section 4).
A _104 interim response_ is an interim response with the "104 (Upload
Resumption Supported)" status code (Section 12).
3. Overview
Resumable uploads are supported in HTTP by a temporary resource, an
_upload resource_ (Section 4), that is separate from the resource
being uploaded to and specific to that upload. By interacting with
the upload resource, a client can retrieve the current offset of the
upload (Section 7), append to the upload (Section 8), and cancel the
upload (Section 9).
The remainder of this section uses examples to illustrate different
interactions with the upload resource. HTTP message exchanges, and
thereby resumable uploads, use representation data (see Section 8.1
of [HTTP]). This means that resumable uploads can be used with many
forms of content, such as static files, in-memory buffers, data from
streaming sources, or on-demand generated data. Examples are purely
illustrative and non-normative. Implementations follow the normative
requirements in the other sections and the security considerations in
Section 20.
3.1. Example 1: Complete Upload of Representation Data with Known Size
In this example, the client first attempts to upload representation
data with a known size in a single HTTP request to the resource at
"/project/123/files". An interruption occurs and the client then
attempts to resume the upload using subsequent HTTP requests to the
upload resource at "/uploads/abc".
1) The client notifies the server that it wants to begin an upload
(Section 6). The server reserves the required resources to accept
the upload from the client and then sends an interim response to the
client, signaling support for resumable uploads and the upload
resource's URI via the "Location" header field (Section 10.2.2 of
[HTTP]). The client can start sending the representation data in the
request content immediately after the request header section.
Alternatively, it can wait for the interim response first.
Kleidl, et al. Expires May 14, 2027 [Page 6]
Internet-Draft Resumable Uploads November 2026
Client Server
| |
| POST /project/123/files |
| Upload-Complete: ?1 |
| |
| [representation] |
|------------------------------------------->|
| |
| | Reserve resources
| | for upload
| |-----------------.
| | |
| |<----------------'
| |
| 104 Upload Resumption Supported |
| Location: /uploads/abc |
|<-------------------------------------------|
| |
X--------------Flow Interrupted--------------X
Figure 1: Upload Creation
2) If the connection to the server is interrupted, the client might
want to resume the upload. However, before this is possible, the
client needs to know the amount of representation data that the
server processed before the interruption. It does so by retrieving
the offset (Section 7) from the upload resource.
Client Server
| |
| HEAD /uploads/abc |
|------------------------------------------------>|
| |
| 204 No Content |
| Upload-Offset: X |
|<------------------------------------------------|
| |
Figure 2: Offset Retrieval
3) The client can resume the upload by sending the remaining
representation data to the upload resource (Section 8), appending to
the already stored representation data in the upload using the
"application/partial-upload" media type. The "Upload-Offset" header
field is included to ensure that the client and server agree on the
offset that the upload resumes from. Once the remaining
representation data is transferred, the server processes the entire
representation and responds with whatever the initial request to
Kleidl, et al. Expires May 14, 2027 [Page 7]
Internet-Draft Resumable Uploads November 2026
"/project/123/files" would have produced if it had not been
interrupted, e.g., a "201 (Created)" response.
Client Server
| |
| PATCH /uploads/abc |
| Upload-Complete: ?1 |
| Upload-Offset: X |
| Content-Type: application/partial-upload |
| |
| [representation from offset X] |
|------------------------------------------------>|
| |
| 201 Created |
| Upload-Complete: ?1 |
|<------------------------------------------------|
| |
Figure 3: Upload Append
4) If the client is not interested in completing the upload, it can
cancel the upload (Section 9). The server can then release the
upload resource and any associated representation data.
Client Server
| |
| DELETE /uploads/abc |
|------------------------------------------------>|
| |
| 204 No Content |
|<------------------------------------------------|
| |
Figure 4: Upload Cancellation
3.2. Example 2: Upload as a Series of Parts
In some cases, clients might prefer to upload a representation as a
series of parts sent serially across multiple HTTP messages. One use
case is to overcome server limits on HTTP message content size.
Another use case is where the client does not know the final size of
the representation data, such as when the data originates from a
streaming source.
This example shows how the client, communicating with a resource
known to support resumable uploads, can upload parts of a
representation incrementally.
Kleidl, et al. Expires May 14, 2027 [Page 8]
Internet-Draft Resumable Uploads November 2026
1) The client is aware that the target resource supports resumable
uploads and therefore starts the upload with the "Upload-Complete"
header field set to false and the first part of the representation.
Client Server
| |
| POST /project/123/files |
| Upload-Complete: ?0 |
| |
| [partial representation] |
|------------------------------------------------>|
| |
| 201 Created |
| Location: /uploads/abc |
|<------------------------------------------------|
| |
Figure 5: Upload Creation with Partial Representation Data
2) Next, intermediate parts are appended (Section 8) with the
"Upload-Complete" header field set to false, indicating that they are
not the last part of the representation data.
Client Server
| |
| PATCH /uploads/abc |
| Upload-Complete: ?0 |
| Upload-Offset: X |
| Content-Type: application/partial-upload |
| |
| [partial representation from offset X] |
|------------------------------------------------>|
| |
| 204 No Content |
|<------------------------------------------------|
| |
Figure 6: Appending Partial Representation Data to Upload
3) If the connection was interrupted, the client might want to resume
the upload, similar to the previous example (Section 3.1). The
client retrieves the offset (Section 7) to learn the amount of
representation data processed by the server and then continues
appending the remaining parts to the upload as in the previous step.
Kleidl, et al. Expires May 14, 2027 [Page 9]
Internet-Draft Resumable Uploads November 2026
Client Server
| |
| HEAD /uploads/abc |
|------------------------------------------------>|
| |
| 204 No Content |
| Upload-Offset: Y |
|<------------------------------------------------|
| |
| PATCH /uploads/abc |
| Upload-Complete: ?0 |
| Upload-Offset: Y |
| Content-Type: application/partial-upload |
| |
| [partial representation from offset Y] |
|------------------------------------------------>|
| |
| 204 No Content |
|<------------------------------------------------|
| |
Figure 7: Resuming an Interrupted Upload
4) The request to append the last part of the representation data has
the "Upload-Complete" header field set to true to indicate the
complete transfer. Once the remaining representation data is
transferred, the server processes the entire representation and
responds with whatever the initial request to "/project/123/files"
would have produced if its representation had been fully transferred
and processed, e.g., a "201 (Created)" response.
Client Server
| |
| PATCH /uploads/abc |
| Upload-Complete: ?1 |
| Upload-Offset: Z |
| Content-Type: application/partial-upload |
| |
| [remaining representation from offset Z] |
|------------------------------------------------>|
| |
| 201 Created |
| Upload-Complete: ?1 |
|<------------------------------------------------|
| |
Figure 8: Appending Remaining Representation Data
Kleidl, et al. Expires May 14, 2027 [Page 10]
Internet-Draft Resumable Uploads November 2026
4. Upload Resource
A resumable upload is enabled through interaction with an upload
resource. When a resumable upload begins, the server is asked to
create an upload resource through a request to another resource
(Section 6). Using this upload resource, the client can query the
upload progress (Section 7), append representation data (Section 8),
or cancel the upload (Section 9). The server is responsible for
persisting the state of the upload resource (see below) and updating
it as the upload progresses. Limits (Section 5) can also apply to
the upload resource.
An upload resource is specific to the upload of one representation.
For uploading multiple representations, multiple upload resources
have to be used.
Server implementations need to decide how long to retain an upload
resource after the upload is complete. The server can clean up the
upload resource and make it inaccessible immediately. Keeping it
longer lets a client that missed the final response verify the
upload's state, at a cost to the server.
An upload resource SHOULD be unique. Reuse of a URI for a different
upload resource SHOULD be avoided in order to reduce the chance of
misdirected or corrupted upload resources, as well as the potential
security issues described in Section 20.1.
If the client receives a "3xx (Redirection)" response to a request to
the upload resource, and the response does not complete the upload
(Section 20.7), the client is not expected to follow the redirect,
because this protocol does not define how an upload continues at a
different URI.
The state of an upload includes the following properties that are
tracked by the server.
4.1. Offset
The offset is the number of bytes from the representation data that
have been processed, either during the creation of the upload
resource (Section 6) or by appending to it (Section 8). The offset
is required when appending representation data to synchronize the
client and resource regarding the amount of transferred
representation data.
The offset reflects application-level processing for the upload.
Data might have been delivered and acknowledged at the transport
layer without yet being reflected in the offset.
Kleidl, et al. Expires May 14, 2027 [Page 11]
Internet-Draft Resumable Uploads November 2026
Representation data processed by the upload resource cannot be
removed again and, therefore, the offset as seen by the client MUST
NOT decrease. Clients can use this guarantee to free resources
associated with transferred representation data, as no retransmission
of it will be necessary. If the server loses any part of the state,
it MUST deactivate the upload resource and reject further interaction
with it.
4.1.1. Upload-Offset
The "Upload-Offset" request and response header field is an Item
Structured Header Field of type Integer (Section 3.3.1 of
[STRUCTURED-FIELDS]). Its value is a non-negative Integer and
indicates the current offset, as viewed by the message sender. Other
values MUST cause the entire header field to be ignored. This
document does not define parameters for "Upload-Offset"; unknown
parameters MUST be ignored.
The client can learn the current offset in three ways:
o The offset can be explicitly retrieved from the upload resource
(Section 7).
o Interim responses for creating the upload (Section 6) or appending
(Section 8), and their final responses with a non-"2xx" status
code and the "Upload-Complete: ?0" header field, can include the
"Upload-Offset" header field.
o Final responses for appending representation data (Section 8) with
a "2xx (Successful)" status code and the "Upload-Complete: ?0"
header field acknowledge that the entire request content was
received and the offset increased by the length of the appended
representation data. If present, the "Upload-Offset" header field
value MUST match this inferred offset.
4.2. Completeness
An upload is incomplete until it is explicitly marked as complete by
the client or the server. After this point, no more representation
data can be appended.
4.2.1. Upload-Complete
The "Upload-Complete" request and response header field is an Item
Structured Header Field of type Boolean (Section 3.3.6 of
[STRUCTURED-FIELDS]). Other values MUST cause the entire header
field to be ignored. This document does not define parameters for
"Upload-Complete"; unknown parameters MUST be ignored.
Kleidl, et al. Expires May 14, 2027 [Page 12]
Internet-Draft Resumable Uploads November 2026
An upload is marked as complete either when a request for creating
the upload resource (Section 6) or appending to it (Section 8)
includes the "Upload-Complete" header field set to true and the
request content was fully processed, or when a response includes the
field set to true.
In an upload creation response (Section 6) or an upload append
response (Section 8), the "Upload-Complete" header field indicates
where the response comes from: true means the target resource of the
initial request, and false means the resumable upload protocol.
After a response with the "Upload-Complete" header field set to true,
the client SHOULD NOT resume the upload.
Note that the "Upload-Complete" header field can be true even when
the full representation data was not transmitted, because the target
resource can generate an early response. Also note that it can be
false in response to an invalid request to a completed upload.
4.3. Length
The length is the number of bytes of the representation data. It
might not be known when starting the transfer, for example, because
the representation is taken from a streaming source. The length
will, however, be known at the latest when the client completes the
upload (Section 4.2).
A client SHOULD communicate the representation's length to the server
as soon as it becomes known, without waiting for the upload to
complete. This aids resource management and allows early validation.
A request that creates the upload resource (Section 6) or appends to
it (Section 8) has two possible indicators of the length:
1. If the request includes the "Upload-Complete" header field set to
true, the request content is the remaining representation data.
The representation's length is then the sum of the current offset
(Section 4.1) and the request content's length, which might be
announced in the "Content-Length" header field.
2. The request can include the "Upload-Length" header field defined
below.
If indicators (1) and (2) are both present in the same request, their
indicated lengths MUST match. The representation's length, if known,
MUST stay consistent across subsequent requests. A server SHOULD
respond to a request with inconsistent length indicators with a "400
(Bad Request)" status code, and can use the problem type [PROBLEM] of
"https://iana.org/assignments/http-problem-types#inconsistent-upload-
length" (Section 14.2) to indicate why.
Kleidl, et al. Expires May 14, 2027 [Page 13]
Internet-Draft Resumable Uploads November 2026
Note that the length and offset values do not determine whether an
upload is complete. Instead, the client uses the "Upload-Complete"
header field (Section 4.2.1) to indicate that a request completes the
upload. The offset could match the length, but the upload can still
be incomplete.
4.3.1. Upload-Length
The "Upload-Length" request and response header field is an Item
Structured Header Field of type Integer (Section 3.3.1 of
[STRUCTURED-FIELDS]). Its value is a non-negative Integer and
indicates the representation's length. Other values MUST cause the
entire header field to be ignored. This document does not define
parameters for "Upload-Length"; unknown parameters MUST be ignored.
The "Upload-Length" field can be used in response to an offset
retrieval; see Section 7.2.
5. Upload Limits
A server can limit an upload, for example, in its total size, in the
size of each request, or in how long the upload resource remains
available. The server announces these limits to the client in the
"Upload-Limit" header field (Section 5.1), so the client can adhere
to them.
A client usually learns the limits when the upload resource is
created (Section 6). It can learn them before that through an
"OPTIONS" request (Section 5.2).
5.1. Upload-Limit
The "Upload-Limit" response header field is a Dictionary Structured
Header Field (Section 3.2 of [STRUCTURED-FIELDS]). Other values MUST
cause the entire header field to be ignored. Receivers of the
"Upload-Limit" header field parse the Dictionary as described in
Section 4.2 of [STRUCTURED-FIELDS]. Where the Dictionary is
successfully parsed, this document places the following additional
requirements on Dictionary members.
A member with an unknown key MUST be ignored. A member with a known
key is only valid if it has the expected type and its value is within
the permitted range. Some members are related and their values can
specify a combined range, which has its own definition of validity.
Receiving an invalid member or members that specify an invalid
combined range is an error. It MUST cause the entire "Upload-Limit"
Kleidl, et al. Expires May 14, 2027 [Page 14]
Internet-Draft Resumable Uploads November 2026
header field to be ignored, or alternatively the complete HTTP
message MUST be treated as malformed.
This document does not define parameters for Dictionary member
values; unknown parameters MUST be ignored.
The following key-value pairs are defined.
5.1.1. max-size
The "max-size" limit specifies a maximum size, in bytes, for the
representation data. The value is an Integer greater than zero; a
value of zero would only permit empty uploads.
The server might not create an upload resource if the
representation's length (Section 4.3) deduced from the upload
creation request is larger than the maximum size. The server might
also deactivate the upload resource if the offset (Section 4.1)
exceeds the maximum size.
5.1.2. min-size
The "min-size" limit specifies a minimum size, in bytes, for the
representation data. The value is a non-negative Integer. It MUST
NOT be greater than the "max-size" value, if present.
The server might not create an upload resource if the
representation's length (Section 4.3) deduced from the upload
creation request is smaller than the minimum size or no length can be
deduced at all. Resumable uploads impose additional overhead on the
server, which might not be acceptable for small representations.
Requests with representation data below this value might still be
accepted by the server, although without the ability to resume them.
5.1.3. max-append-size
The "max-append-size" limit specifies a maximum size, in bytes, for
the request content in a single upload append (Section 8) or upload
creation (Section 6) request. The value is an Integer greater than
zero; a value of zero would only permit requests with no content.
The server might reject requests exceeding this limit. A client that
is aware of this limit MUST NOT send larger upload append or upload
creation requests.
Kleidl, et al. Expires May 14, 2027 [Page 15]
Internet-Draft Resumable Uploads November 2026
5.1.4. min-append-size
The "min-append-size" limit specifies a minimum size, in bytes, for
the request content in a single upload append (Section 8) or upload
creation (Section 6) request. The value is a non-negative Integer.
It MUST NOT be greater than the "max-append-size" or "max-size"
values, if present. This limit does not apply to upload creation
requests with no content, or to requests completing the upload by
including the "Upload-Complete: ?1" header field.
The server might reject requests below this limit. A client that is
aware of this limit MUST NOT send smaller upload append or upload
creation requests.
5.1.5. max-age
The "max-age" limit specifies the remaining lifetime, in seconds, of
the upload resource, counted from the generation of the response.
The value is a non-negative Integer.
After the resource's lifetime is reached, the server might make the
upload resource inaccessible.
5.2. Use with OPTIONS
Before creating an upload resource, a client can send an "OPTIONS"
request to discover whether the resource supports resumable uploads
and to learn potential limits. The request does not include the
"Upload-Complete" header field; otherwise, it would be a request to
create an upload resource (Section 6).
When responding to such a request, if the target resource supports
the creation of a resumable upload resource (Section 6), the server
MUST include the "Upload-Limit" header field with the corresponding
limits in the response. If a server is configured such that all of
its resources support the creation of upload resources with identical
limits, it SHOULD include the "Upload-Limit" header field in response
to an "OPTIONS" request for the target "*" (if this target is
supported).
In an "OPTIONS" response, the presence of the "Upload-Limit" header
field signals support for resumable uploads, even when the server
applies no limits. An empty Dictionary is equivalent to omitting the
field (Section 3.2 of [STRUCTURED-FIELDS]), so it cannot carry this
signal. If the server does not apply any limits, it MUST send "min-
size=0".
Kleidl, et al. Expires May 14, 2027 [Page 16]
Internet-Draft Resumable Uploads November 2026
To reduce the likelihood of failing requests, the limits announced in
an "OPTIONS" response SHOULD NOT be less restrictive than the limits
applied to an upload once the upload resource has been created,
unless the request to create an upload resource included additional
information that warrants different limits. For example, a server
might announce a general maximum size limit of 1 GB, but reduce it to
100 MB when the media type indicates an image.
5.3. Limit Changes
Throughout the lifetime of the upload resource, limits SHOULD NOT
change in a way that causes failures for clients adhering to the
initially discovered limits. If the client discovers that it cannot
continue the upload while adhering to the limits, it SHOULD stop the
current request immediately (Section 19) and cancel the upload
(Section 9).
The following recommendations for limit changes can minimize the risk
of causing upload failures:
o "max-size" and "max-append-size" SHOULD NOT decrease.
o "min-size" and "min-append-size" SHOULD NOT increase.
o Between subsequent responses, the end of the upload resource's
lifetime as implied by "max-age" SHOULD NOT decrease.
5.4. Limit Violations
When a request is rejected because limits were violated, the response
SHOULD include the "Upload-Limit" header field carrying all limits of
the corresponding upload if possible. This might not be possible if
intermediaries enforce limits.
Servers, including intermediaries, can (and often do) apply
restrictions on the size of individual request message content.
There is no standard mechanism to communicate such existing size
restriction. A server that implements one can respond with a "413
(Content Too Large)" status code; see Section 15.5.14 of [HTTP].
Appending to an upload resource, as a series of appends, can be used
to upload data up to the "max-size" limit (Section 5.1.1) without
encountering per-message limits. Servers might apply restrictions
that are smaller than the append limits, which would also result in a
failed request.
When a client receives a response with a "413 (Content Too Large)"
status code during upload creation (Section 6) or append (Section 8),
it SHOULD retry the request with a smaller size residing between
Kleidl, et al. Expires May 14, 2027 [Page 17]
Internet-Draft Resumable Uploads November 2026
"min-append-size" (Section 5.1.4) and "max-append-size"
(Section 5.1.3). If these limits are unknown at the time of
receiving such a response, the client can attempt to discover them
through an "OPTIONS" request (Section 5.2). Retrying with the same
request content size will likely yield the same error response.
Cases where the request content size matches the "min-append-size"
limit yet fails with a "413 (Content Too Large)" response might
indicate a deployment mismatch that cannot be recovered from.
6. Upload Creation
6.1. Client Behavior
A client can start a resumable upload from any request that can carry
content by including the "Upload-Complete" header field
(Section 4.2.1). Any method that allows content can be used, such as
"POST", "PUT", and "PATCH". The request can benefit from incremental
delivery; see Section 18.
The "Upload-Complete" header field is set to true if the request
content includes the entire representation data that the client
intends to upload. This is also a requirement for transparently
upgrading to resumable uploads from conventional uploads
(Section 17.1.1).
If the client knows the representation's length, it SHOULD indicate
the length in the request to help the server allocate necessary
resources for the upload and provide early feedback if the
representation violates a limit (Section 5), as described in
Section 4.3.
Clients are not required to discover limits (Section 5) before
starting the upload and might therefore be initially unaware of
limits enforced by the server. However, the client SHOULD respect
any limits announced during the upload process in the "Upload-Limit"
header field in interim or final responses. In particular, if the
allowed maximum size is less than the amount of representation data
the client intends to upload, the client SHOULD stop the current
request immediately (Section 19) and cancel the upload (Section 9).
If the client knows that the representation data is smaller than
"min-size" (Section 5.1.2), it cannot expect resumability to be
offered. The client might still attempt to transfer the
representation in a single request, either in a request with the
"Upload-Complete" header field set to true (see Section 17.1.1) or
via a conventional upload.
The request content can be empty. If the "Upload-Complete" header
field is then set to true, the client intends to upload an empty
Kleidl, et al. Expires May 14, 2027 [Page 18]
Internet-Draft Resumable Uploads November 2026
representation. An "Upload-Complete" header field set to false is
also valid. This can be used to retrieve the upload resource's URI
before transferring any representation data. Since interim responses
are optional, this technique provides another mechanism to learn the
URI, at the cost of an additional round trip before data upload can
commence.
Representation metadata included in the initial request (see
Section 8 of [HTTP]) can affect how servers act on the uploaded
representation data. The "Content-Type" header field indicates the
media type of the representation. The "Content-Encoding" header
field names the content codings applied to the representation.
If the client receives a final response that marks the upload as
complete, the response comes from the target resource of the initial
request (Section 4.2.1). Note that this does not necessarily
indicate success. "4xx (Client Error)" or "5xx (Server Error)" status
codes indicate in this case an error occurred while processing the
representation, and therefore, resuming the upload would not resolve
this error.
If the client sent the "Upload-Complete" header field set to false
and receives a "2xx (Successful)" final response that does not mark
the upload as complete, the "Location" header field points the client
to the created upload resource. The client can continue appending
representation data to it (Section 8).
If the client receives a "4xx (Client Error)" or "5xx (Server Error)"
final response that does not mark the upload as complete, or if it
did not receive a final response, it can apply the heuristics
described in Section 11 to retry or resume the upload.
6.2. Server Behavior
Upon receiving a request with the "Upload-Complete" header field, the
server can choose to offer resumption support for this request by
creating an upload resource. If so, the server SHOULD announce the
upload resource by sending an interim response with the "104 (Upload
Resumption Supported)" status code unless the server is not capable
of sending interim responses. The interim response allows the client
to resume the upload even if the message exchange gets later
interrupted. When sent, it MUST include "Location" header field
pointing to the upload resource and MUST include the "Upload-Limit"
header field with the corresponding limits (Section 5) if any.
The target resource of the initial request is responsible for
processing the representation data transferred in the resumable
upload according to the method and header fields in the initial
Kleidl, et al. Expires May 14, 2027 [Page 19]
Internet-Draft Resumable Uploads November 2026
request. The upload resource, on the other hand, enables resuming
the transfer.
If the "Upload-Complete" request header field is set to true, the
client intends to transfer the entire representation data in one
request. If the request content was fully processed, no resumable
upload is needed and the server proceeds to process the request and
generate a response. Any "2xx (Successful)" response that the server
generates for such a request MUST mark the upload as complete.
If the "Upload-Complete" request header field is set to false, the
client intends to transfer the representation over multiple requests.
If the request content was fully processed, the server MUST include
the "Location" header field pointing to the upload resource and MUST
include the "Upload-Limit" header field with the corresponding limits
if any. Servers are RECOMMENDED to use the "201 (Created)" status
code.
The server MUST record the representation's length according to
Section 4.3 if the "Upload-Length" or "Upload-Complete: ?1" header
fields are included in the request.
While the request content is being processed, the server SHOULD send
interim responses with a "104 (Upload Resumption Supported)" status
code and the "Upload-Offset" header field set to the current offset
to inform the client about the upload progress.
Every response to the same request that identifies the upload
resource in the "Location" header field MUST use the same URI. A
final response with "Upload-Complete: ?1" is the result of processing
the representation, so its "Location" header field can identify a
different resource. Clients SHOULD check that the upload resource
URI does not change, and SHOULD stop the current request immediately
(Section 19) and cancel the upload (Section 9) if it does.
The server SHOULD include the "Upload-Complete" header field
(Section 4.2.1) in the response to indicate whether it is the result
of processing the uploaded representation.
The server SHOULD NOT generate a response with a "3xx (Redirection)"
status code and the "Upload-Complete: ?0" header field because the
upload resource's URI is expected to remain the same for the lifetime
of the upload. See Section 20.7 for redirecting a response that
completes the upload.
The server might not process the entire request content when the
upload is interrupted, for example, because of a dropped connection
or a canceled request. In this case, the server SHOULD append as
Kleidl, et al. Expires May 14, 2027 [Page 20]
Internet-Draft Resumable Uploads November 2026
much of the request content as possible to the upload resource,
allowing the client to resume the upload from where it was
interrupted. The upload resource MUST NOT be considered complete in
this case.
6.3. Examples
A) The following example shows an upload creation, where all
123456789 bytes are transferred in the initial request. The server
sends multiple interim responses and one final response from
processing the uploaded representation.
POST /project/123/files HTTP/1.1
Host: example.com
Content-Length: 123456789
Upload-Length: 123456789
Upload-Complete: ?1
[content (123456789 bytes)]
HTTP/1.1 104 Upload Resumption Supported
Location: https://example.com/upload/b530ce8ff
Upload-Limit: max-size=1234567890
HTTP/1.1 104 Upload Resumption Supported
Upload-Offset: 23456789
HTTP/1.1 201 Created
Upload-Complete: ?1
Location: https://example.com/project/123/files/b530ce8ff
Content-Type: application/json
{"attachmentId": "b530ce8ff"}
B) The following example shows an upload creation, where only the
first 23456789 bytes of a 123456789-byte upload are transferred. The
server acknowledges the processed representation data and that the
upload is not complete yet. The client can continue appending data.
POST /upload HTTP/1.1
Host: example.com
Upload-Complete: ?0
Content-Length: 23456789
Upload-Length: 123456789
[partial content (23456789 bytes)]
Kleidl, et al. Expires May 14, 2027 [Page 21]
Internet-Draft Resumable Uploads November 2026
HTTP/1.1 104 Upload Resumption Supported
Location: https://example.com/upload/3fd4994ad
Upload-Limit: max-size=1234567890
HTTP/1.1 201 Created
Location: https://example.com/upload/3fd4994ad
Upload-Complete: ?0
Upload-Limit: max-size=1234567890
C) The following example shows an upload creation, where the server
responds with a "5xx (Server Error)" status code. Thanks to the
interim response containing the upload resource URI, the client can
resume the upload.
POST /upload HTTP/1.1
Host: example.com
Upload-Complete: ?1
Content-Length: 123456789
Upload-Length: 123456789
[content (123456789 bytes)]
HTTP/1.1 104 Upload Resumption Supported
Location: https://example.com/upload/0587fa44b
HTTP/1.1 500 Internal Server Error
D) The following example shows an upload creation being rejected by
the server because the request content cannot be decoded. The
"Upload-Complete" header field in the response is set to true
because, after the decoding failure, the server does not want the
rest of the representation and considers the upload complete. The
client cannot continue the upload.
POST /upload-gzip HTTP/1.1
Host: example.com
Upload-Complete: ?0
Content-Length: 23456789
Upload-Length: 123456789
Content-Encoding: gzip
[corrupted gzip content]
HTTP/1.1 104 Upload Resumption Supported
Location: https://example.com/upload/6723cdf37
HTTP/1.1 400 Bad Request
Upload-Complete: ?1
Kleidl, et al. Expires May 14, 2027 [Page 22]
Internet-Draft Resumable Uploads November 2026
7. Offset Retrieval
7.1. Client Behavior
If the client wants to resume the upload after an interruption, it
has to know the amount of representation data processed by the upload
resource so far. It can fetch the offset by sending a "HEAD" or
"GET" request to the upload resource. Using "HEAD" is RECOMMENDED,
since response content is not required for resumption. In a
successful response, the "Upload-Offset" header field indicates the
offset from which the client can continue the upload by appending
representation data (Section 8).
The offset can be less than or equal to the number of bytes of
representation data that the client has already sent. The client is
expected to handle backtracking of a reasonable length. On the other
hand, the offset can be greater than the amount of sent
representation data, for example, if the server already has data from
an earlier attempt to upload the same representation. If the client
is not able to provide the representation data at the given offset,
the upload MUST be considered a failure. The client then MUST NOT
continue the upload and SHOULD cancel the upload (Section 9).
The client MUST NOT retrieve the offset while it is still creating
(Section 6) or appending to (Section 8) the same upload resource,
because the server might terminate the in-progress request
(Section 10).
If the client receives a "2xx (Successful)" response with a valid
"Upload-Offset" header field, the client can continue appending
representation data to it (Section 8).
If the client receives a "2xx (Successful)" response without a valid
"Upload-Offset" header field, a "4xx (Client Error)" or "5xx (Server
Error)" response, or if it did not receive a response, the client MAY
retry retrieving the offset. Otherwise, the upload is considered a
failure.
7.2. Server Behavior
A successful response to a "HEAD" or "GET" request to an upload
resource
o MUST include the offset in the "Upload-Offset" header field
(Section 4.1.1),
o MUST indicate the limits in the "Upload-Limit" header field
(Section 5) if any, and
Kleidl, et al. Expires May 14, 2027 [Page 23]
Internet-Draft Resumable Uploads November 2026
o SHOULD include the "Cache-Control" header field with the value
"no-store" to prevent HTTP caching ([HTTP-CACHING]).
The server SHOULD NOT generate a response with a "3xx (Redirection)"
status code because the upload resource's URI is expected to remain
the same for the lifetime of the upload.
A client does not require response content for an offset retrieval
request in order to successfully resume an upload. Therefore,
serving response content for a "GET" request is unexpected. Its
meaning is not defined by this protocol.
7.3. Examples
The following example shows an offset retrieval request. The server
indicates the current offset and that the upload is not complete yet.
The client can continue to append representation data.
HEAD /upload/c35e2cd29 HTTP/1.1
Host: example.com
HTTP/1.1 204 No Content
Upload-Complete: ?0
Upload-Offset: 25000000
Upload-Length: 100000000
Upload-Limit: max-age=3600
Cache-Control: no-store
8. Upload Append
8.1. Client Behavior
A client can continue the upload and append representation data by
sending a "PATCH" request with the "application/partial-upload" media
type (Section 13) to the upload resource. The request content is the
representation data to append. The request can benefit from
incremental delivery; see Section 18.
The client MUST indicate the offset of the request content inside the
representation data by including the "Upload-Offset" header field.
To ensure that the upload resource accepts the request, the client
SHOULD take the offset from the most recent offset retrieval
(Section 7), upload creation (Section 6), or upload append response.
The request content is the representation data to append, so the
patch document has no content coding of its own. A content coding
would make the request content differ from the representation data
that the offset (Section 4.1) and length (Section 4.3) count.
Kleidl, et al. Expires May 14, 2027 [Page 24]
Internet-Draft Resumable Uploads November 2026
Therefore, the request MUST NOT include a "Content-Encoding" header
field (see Section 8.4 of [HTTP]). Content codings of the
representation, if any, are announced only in the upload creation
request (Section 6).
The request MUST include the "Upload-Complete" header field. Its
value is true in two cases:
o the request has content that is the end of the representation
data. Once the content is fully processed by the server, the
upload is complete.
o the request has no content. Once the request is processed by the
server, the upload is complete. This usage requires the full
representation data to have been processed during prior requests.
If the client receives a final response that marks the upload as
complete, the response comes from the target resource of the initial
request (Section 4.2.1). Note that this does not necessarily
indicate success. "4xx (Client Error)" or "5xx (Server Error)" status
codes indicate in this case an error occurred while processing the
representation, and therefore, resuming the upload would not resolve
this error.
If the client receives a "4xx (Client Error)" or "5xx (Server Error)"
final response that does not mark the upload as complete, or if it
did not receive a final response, it can apply the heuristics
described in Section 11 to retry or resume the upload. Otherwise,
the upload is considered a failure.
8.2. Server Behavior
A server applies a "PATCH" request with the "application/partial-
upload" media type (Section 13) to an upload resource by appending
the patch document in the request content.
The server might not process the entire patch document when the
upload is interrupted, for example, because of a dropped connection
or a canceled request. In this case, the server SHOULD append as
much of the patch document as possible to the upload resource,
starting at its beginning and without discontinuities. Appending a
continuous section starting at the patch document's beginning
constitutes a successful PATCH as defined in Section 2 of [PATCH].
Saving the processed data allows the client to resume the upload from
where it was interrupted. The upload resource MUST NOT be considered
complete in this case.
Kleidl, et al. Expires May 14, 2027 [Page 25]
Internet-Draft Resumable Uploads November 2026
If the "Upload-Offset" request header field value does not match the
current offset (Section 4.1), the server MUST reject the request with
a "409 (Conflict)" status code and the "Upload-Complete" header field
set to false. The response MUST include the correct offset in the
"Upload-Offset" header field. The response can use the problem type
[PROBLEM] of "https://iana.org/assignments/http-problem-
types#mismatching-upload-offset" (Section 14.1).
If an upload append request is missing a valid "Upload-Offset" header
field, a valid "Upload-Complete" header field, or both, the server
SHOULD respond with a "400 (Bad Request)" status code.
The patch document cannot have a content coding of its own. A
content coding would make the request content differ from the
representation data that the offset (Section 4.1) and length
(Section 4.3) count. Therefore, if the request includes a "Content-
Encoding" header field, the server SHOULD respond with a "415
(Unsupported Media Type)" status code and the "Upload-Complete"
header field set to false.
If the "Upload-Complete" request header field is set to true, the
client intends to transfer the remaining representation data in one
request. If the request content was fully processed, the upload is
marked as complete and the server SHOULD generate the response that
matches what the target resource of the initial upload creation
request (Section 6) would have generated if it had processed the
entire representation in the initial request. However, the response
MUST include the "Upload-Complete" header field set to true, allowing
clients to identify whether a response, in particular error
responses, is related to the resumable upload itself or the
processing of the uploaded representation. Any "2xx (Successful)"
response that the server generates for such a request MUST mark the
upload as complete.
If the "Upload-Complete" request header field is set to false, the
client intends to transfer the remaining representation data over
multiple requests. If the request content was fully processed, the
server acknowledges the appended data by sending a "2xx (Successful)"
response with the "Upload-Complete" header field set to false.
Even if the upload is complete (Section 4.2) from the server's
perspective and the final response from the target resource of the
initial request has already been sent, the client might still perform
an upload append after an offset retrieval (Section 7) due to the
response being lost during transmission. The server can choose to
replay the final response to the client if the request to append to
the completed upload is valid.
Kleidl, et al. Expires May 14, 2027 [Page 26]
Internet-Draft Resumable Uploads November 2026
The server MUST record the representation's length according to
Section 4.3 if the "Upload-Length" or "Upload-Complete: ?1" header
fields are included in the request. If the representation's length
is known, the server MUST NOT let the offset exceed it: if appending
a request's content would take the offset past the length, the server
MUST reject the request, deactivate the upload resource, and reject
any further interaction with it. It is not sufficient to rely on the
"Content-Length" header field for enforcement because this header
field might not be present.
While the request content is being processed, the server SHOULD send
interim responses with a "104 (Upload Resumption Supported)" status
code and the "Upload-Offset" header field set to the current offset
to inform the client about the upload progress. These interim
responses MUST NOT include the "Location" header field.
The server SHOULD include the "Upload-Complete" header field
(Section 4.2.1) in the response to indicate whether it is the result
of processing the uploaded representation.
The server SHOULD NOT generate a response with a "3xx (Redirection)"
status code and the "Upload-Complete: ?0" header field because the
upload resource's URI is expected to remain the same for the lifetime
of the upload. See Section 20.7 for redirecting a response that
completes the upload.
8.3. Examples
A) The following example shows an upload append request. The client
transfers the next 3456789 bytes at an offset of 20000000 and does
not indicate that the upload is then completed. The server generates
one interim response, when the offset reached 21728394 bytes, and
finally acknowledges the new offset:
PATCH /upload/37a504d87 HTTP/1.1
Host: example.com
Upload-Complete: ?0
Upload-Offset: 20000000
Content-Length: 3456789
Content-Type: application/partial-upload
[content (3456789 bytes)]
HTTP/1.1 104 Upload Resumption Supported
Upload-Offset: 21728394
HTTP/1.1 204 No Content
Upload-Complete: ?0
Kleidl, et al. Expires May 14, 2027 [Page 27]
Internet-Draft Resumable Uploads November 2026
B) The following example shows an upload append, where the client
transfers the remaining 4567890 bytes and completes the upload with a
length of 1234567890 bytes. The server processes the uploaded
representation and generates the corresponding response, in this
example containing extracted metadata:
PATCH /upload/d38d6ffe8 HTTP/1.1
Host: example.com
Upload-Complete: ?1
Upload-Offset: 1230000000
Content-Length: 4567890
Content-Type: application/partial-upload
[content (4567890 bytes)]
HTTP/1.1 200 OK
Upload-Complete: ?1
Content-Type: application/json
{
"metadata": {
[...]
}
}
9. Upload Cancellation
9.1. Client Behavior
If the client wants to cancel the upload, it can send a "DELETE"
request to the upload resource. Doing so is an indication that the
client is no longer interested in continuing the upload, and that the
server can release any resources associated with it.
9.2. Server Behavior
Upon receiving a "DELETE" request, the server SHOULD deactivate the
upload resource.
The server SHOULD terminate any in-flight requests to the upload
resource before sending the response by abruptly terminating their
HTTP connection(s) or stream(s), as described in Section 10.
The server SHOULD NOT generate a response with a "3xx (Redirection)"
status code because the upload resource's URI is expected to remain
the same for the lifetime of the upload.
Kleidl, et al. Expires May 14, 2027 [Page 28]
Internet-Draft Resumable Uploads November 2026
9.3. Example
The following example shows an upload cancellation:
DELETE /upload/5688a431c HTTP/1.1
Host: example.com
HTTP/1.1 204 No Content
10. Concurrency
This document does not support parallel requests that transfer
representation data to the same upload resource. The client MUST NOT
send an upload append request (Section 8) while an upload creation
request (Section 6) or another upload append request for the same
upload resource is still in progress.
Even if the client is well-behaved and does not send concurrent
requests, network interruptions can occur in such a way that the
client considers a request as failed while the server is unaware of
the problem and considers the request still ongoing. The client
might then try to resume the upload with the best intentions,
resulting in concurrent requests from the server's perspective.
Therefore, the server MUST take measures to prevent race conditions,
data loss, and corruption from concurrent append (Section 8) or
cancellation (Section 9) requests to the same upload resource. In
addition, the server MUST NOT send outdated information in responses.
This means that if a client appends at an offset from a final
response (Section 4.1.1), the server MUST NOT reject that request for
having the wrong offset, unless another append or a cancellation
arrived in between.
The RECOMMENDED approach is as follows: If a server receives a new
request to retrieve the offset (Section 7), append representation
data (Section 8), or cancel the upload (Section 9) while a previous
request for creating the upload (Section 6) or appending
representation data to the same upload resource is still ongoing, the
server SHOULD prevent race conditions, data loss, and corruption by
terminating the previous request before processing the new request.
Due to network delay and reordering, the server might still be
receiving representation data from an ongoing transfer for the same
upload resource, which from the client's perspective has failed.
Since the client is not allowed to perform multiple transfers for the
same upload resource in parallel, the server can assume that the
previous attempt has already failed. Therefore, the server MAY
abruptly terminate the previous HTTP connection or stream.
Kleidl, et al. Expires May 14, 2027 [Page 29]
Internet-Draft Resumable Uploads November 2026
Since implementing this approach is not always technically possible
or feasible, other measures can be considered as well. A simpler
approach is that the server only processes a new request to retrieve
the offset (Section 7), append representation data (Section 8), or
cancel the upload (Section 9) once all previous requests have been
processed. This effectively implements exclusive access to the
upload resource through an access lock. However, since network
interruptions can occur in ways that cause the request to hang from
the server's perspective, it might take the server significant time
to realize the interruption and time out the request. During this
period, the client will be unable to access the resource and resume
the upload, causing friction for the end users. Therefore, the
recommended approach is to terminate previous requests to enable
quick resumption of uploads.
11. Retry
If the client receives a "4xx (Client Error)" or "5xx (Server Error)"
response that does not mark the upload as complete (Section 4.2.1)
when creating the upload resource (Section 6) or appending to it
(Section 8), it can apply the heuristics described below to retry or
resume the upload.
o "409 (Conflict)" with the "Upload-Complete" header field set to
false: the upload can be resumed with the correct offset
(Section 4.1). If no "Upload-Offset" header field is provided,
the client SHOULD retrieve the offset (Section 7) before resuming.
o "413 (Content Too Large)": the upload can be resumed after
applying appropriate limits (Section 5).
o "429 (Too Many Requests)": the request can be retried after an
appropriate delay.
o "5xx (Server Error)": the request can be retried.
If no final response was received at all due to connectivity issues,
the client MAY automatically attempt upload resumption by retrieving
the current offset (Section 7).
The client SHOULD limit the number of retries it performs before
considering the upload a failure, and SHOULD then cancel the upload
(Section 9) if it can still reach the upload resource.
Kleidl, et al. Expires May 14, 2027 [Page 30]
Internet-Draft Resumable Uploads November 2026
12. Status Code 104 (Upload Resumption Supported)
The "104 (Upload Resumption Supported)" status code can be used for
two purposes:
o When responding to requests to create uploads, a 104 interim
response can be sent to indicate the resource's support for
resumable uploads, as well as the URI and limits of the
corresponding upload resource in the "Location" and "Upload-Limit"
header fields, respectively (see Section 6). This notifies the
client early about the ability to resume the upload in case of
network interruptions.
o While processing the content of a request to append representation
data or create an upload, the server can regularly send 104
interim responses to indicate the current upload progress in the
"Upload-Offset" header field (see Section 6 and Section 8). This
allows the client to show more accurate progress information about
the amount of data processed by the server. In addition, clients
can use this information to release representation data that was
buffered, knowing that it does not have to be retransmitted.
When creating or appending resumable uploads, the client can generate
a "100-continue" expectation because it wants an indication that the
resource is willing to accept the upload. The client MAY treat a 104
interim response as fulfilling the "100-continue" expectation and
start sending the request content. However, the server MUST NOT omit
the "100 (Continue)" response because it has sent a 104 interim
response.
13. Media Type application/partial-upload
The "application/partial-upload" media type describes a contiguous
block from the representation data to be uploaded to a resource.
There is no minimum block size and the block might be empty. The
block can be a subset of the representation data, where the start
and/or end of the block do not line up with the start and/or end of
the representation data respectively.
14. Problem Types
14.1. Mismatching Offset
This section defines the "https://iana.org/assignments/http-problem-
types#mismatching-upload-offset" problem type [PROBLEM]. A server
can use this problem type when responding to an upload append request
(Section 8) to indicate that the "Upload-Offset" header field in the
request does not match the upload resource's offset.
Kleidl, et al. Expires May 14, 2027 [Page 31]
Internet-Draft Resumable Uploads November 2026
Two problem type extension members are defined: the "expected-offset"
and "provided-offset" members. Both are non-negative integers. A
response using this problem type SHOULD populate both members, with
the value of "expected-offset" taken from the upload resource and the
value of "provided-offset" taken from the upload append request.
The following example shows a response, where the resource's offset
was 12500000, but the client attempted to append at offset 25000000:
# NOTE: '\' line wrapping per RFC 8792
HTTP/1.1 409 Conflict
Content-Type: application/problem+json
Upload-Offset: 12500000
Upload-Complete: ?0
{
"type":"https://iana.org/assignments/http-problem-types#\
mismatching-upload-offset",
"title": "offset from request does not match offset of resource",
"expected-offset": 12500000,
"provided-offset": 25000000
}
14.2. Inconsistent Length
This section defines the "https://iana.org/assignments/http-problem-
types#inconsistent-upload-length" problem type [PROBLEM]. A server
can use this problem type when responding to an upload creation
(Section 6) or upload append request (Section 8) to indicate that the
request includes inconsistent length values, as described in
Section 4.3.
The following example shows a response:
# NOTE: '\' line wrapping per RFC 8792
HTTP/1.1 400 Bad Request
Content-Type: application/problem+json
Upload-Complete: ?0
{
"type":"https://iana.org/assignments/http-problem-types#\
inconsistent-upload-length",
"title": "inconsistent length values for upload"
}
Kleidl, et al. Expires May 14, 2027 [Page 32]
Internet-Draft Resumable Uploads November 2026
15. Content Codings
Since the codings listed in the "Content-Encoding" header field are a
characteristic of the representation (see Section 8.4 of [HTTP]),
both the client and the server always compute the values for the
"Upload-Offset" and optionally "Upload-Length" header fields on the
content coded data (that is, the representation data). Moreover, the
content codings are retained throughout the entire upload, meaning
that the server is not required to decode the representation data to
support resumable uploads. The content codings, if any, are
announced in the upload creation request (Section 6) and not repeated
when appending representation data (Section 8).
16. Transfer Codings
Unlike content codings (see Section 8.4.1 of [HTTP]), transfer
codings (see Section 6.1 of [RFC9112]) are a property of the message,
not of the representation. Moreover, transfer codings can be applied
in transit (e.g., by proxies). This means that a client does not
have to consider the transfer codings to compute the upload offset,
while a server is responsible for transfer decoding the message
before computing the upload offset. The same applies to the "Upload-
Length" header field value. See Section 6.2 of [RFC9112] for how the
"Content-Length" and "Transfer-Encoding" header fields interact.
17. Upload Strategies
The definition of the upload creation request (Section 6) provides
the client with flexibility to choose whether the representation data
is fully or partially transferred in the first request, or if no
representation data is included at all. Which behavior is best
largely depends on the client's capabilities, its desire to avoid
data retransmission, and its knowledge about the resource's support
for resumable uploads.
The following subsections describe two typical upload strategies that
are suited for common environments. Note that these strategies are
never explicitly communicated to the server, and clients are not
required to use only one strategy but can mix and adapt them to their
needs.
17.1. Optimistic Upload Creation
An "optimistic upload creation" can be used regardless of the
client's knowledge about the resource's support for resumable
uploads. However, the client needs to be able to process interim
responses. An upload creation request then includes the full
representation data because the client anticipates that it will be
Kleidl, et al. Expires May 14, 2027 [Page 33]
Internet-Draft Resumable Uploads November 2026
transferred without interruptions or resumed if an interruption
occurs.
The benefit of this strategy is that if the upload creation request
succeeds, the representation data is transferred in a single request
without additional round trips.
A possible drawback is that the client might be unable to resume an
upload. If an upload is interrupted before the client receives a
"104 (Upload Resumption Supported)" interim response with the upload
resource's URI, the client cannot resume that upload due to the
missing URI. The interim response might not be received if the
interruption happens too early in the message exchange, the target
resource of the initial request does not support resumable uploads,
the server is not capable of sending the 104 interim response, or an
intermediary dropped the interim response. Without a 104 interim
response, the client needs to either treat the upload as failed or
retry the entire upload creation request if this is allowed by the
application.
A client might wait for a limited duration to receive a 104 interim
response before starting to transmit the request content. This way,
the client can learn about the resource's support for resumable
uploads and/or the upload resource's URI. This is conceptually
similar to how a client might wait for a "100 (Continue)" interim
response (see Section 10.1.1 of [HTTP]) before committing to work.
17.1.1. Upgrading to Resumable Uploads
Optimistic upload creation allows clients and servers to
automatically upgrade non-resumable uploads to resumable ones. In a
non-resumable upload, the representation is transferred in a single
request, usually "POST" or "PUT", without any ability to resume from
interruptions. The client can invite the server to upgrade such a
request to a resumable upload by adding the "Upload-Complete: ?1"
header field to the original request. The "Upload-Length" header
field SHOULD be added if the representation's length is known
upfront. The request is not changed otherwise.
If the target resource of the initial request supports resumable
uploads, the server can create an upload resource and send its URI in
a 104 interim response for the client to resume the upload after
interruptions. A resource that does not support resumable uploads or
does not want to upgrade to a resumable upload for this request
ignores the "Upload-Complete: ?1" header field. The transfer then
falls back to a non-resumable upload without additional cost.
Kleidl, et al. Expires May 14, 2027 [Page 34]
Internet-Draft Resumable Uploads November 2026
This upgrade can also be performed transparently by a library or
program that acts as an HTTP client by sending requests on behalf of
a user. When the user instructs the client to send a non-resumable
request, the client can perform the upgrade transparently and handle
potential interruptions and resumptions under the hood without
involving the user. The last response received by the client is
considered the response for the entire upload and needs to be
provided to the user.
17.2. Careful Upload Creation
For a "careful upload creation" the client knows that the target
resource of the initial request supports resumable uploads and sends
an empty upload creation request without including any representation
data. Upon successful response reception, the client can use the
included upload resource URI to transmit the representation data
(Section 8) and resume the upload at any stage if an interruption
occurs. The response can include the "Upload-Limit" header field,
which indicates limits for the rest of the upload (Section 5).
The retransmission of representation data or the ultimate upload
failure that can happen with an "optimistic upload creation" is
therefore avoided at the expense of an additional request that does
not carry representation data.
This approach is best suited if the client cannot receive interim
responses, e.g., due to a limitation in the provided HTTP interface,
or if large representations are transferred where the cost of the
additional request is minuscule compared to the effort of
transferring the representation itself.
18. Incremental Transfer, Processing, and Forwarding
The resumable upload design is most effective when a server processes
request message portions as they arrive, which ensures the greatest
chance that data is processed before a possible transfer
interruption.
To support incremental processing, it is RECOMMENDED that clients
send request content incrementally and minimize buffering.
As described in [INCREMENTAL], intermediaries might interfere with
the incremental delivery of data to a server. Clients can use the
"Incremental" header field defined in Section 3 of [INCREMENTAL] to
signal their preference for incremental forwarding by intermediaries.
Kleidl, et al. Expires May 14, 2027 [Page 35]
Internet-Draft Resumable Uploads November 2026
19. Request Cancellation
A client or server might want to interrupt an in-flight message
transfer intentionally for various reasons (see Section 1). The
mechanism to do so depends on the HTTP version in use:
HTTP/1.1: close the underlying transport connection (Section 9.5 of
[RFC9112])
HTTP/2: reset the stream (Section 6.4 of [RFC9113])
HTTP/3: abruptly terminate the request stream (Section 4.1.1 of
[RFC9114])
Version-specific mechanisms place requirements on clients or servers
for carrying out the cancellation. However, for all versions of
HTTP, resumable uploads allow the server to process received
representation data and expose the upload offset via the upload
resource, enabling continuation of the upload after interruption.
20. Security Considerations
20.1. Upload Resource URIs
The upload resource URI is the identifier used for modifying the
upload. Without further protection of this URI, an attacker can
perform any operation on the upload resource: obtain information
about it, append data to it, or cancel it. Each of these requests
can also cause a server to terminate an in-flight request from a
legitimate client (Section 10).
To mitigate these risks, the server SHOULD ensure that only
authorized clients can access the upload resource. It is also
RECOMMENDED that upload resource URIs be hard to guess.
Servers might embed information in the upload resource URI, such as a
storage or processing location, to make request routing more
efficient. Because the URI is visible to the client and to anyone
else who obtains it, servers MUST NOT include information in it that
is not intended to be exposed. Routing information could, for
instance, be encoded so that only the server can interpret it.
If knowing the upload resource URI is enough to access the upload,
the URI is in effect a credential. Like other credentials, it needs
to be protected in transit (see Section 17.16.1 of [HTTP]). URIs are
also often logged or displayed by servers, proxies, and user agents,
so the URI can be disclosed to third parties (see Section 17.9 of
[HTTP]).
Kleidl, et al. Expires May 14, 2027 [Page 36]
Internet-Draft Resumable Uploads November 2026
20.2. Untrusted Input
Upload creation and upload append requests carry untrusted input; see
Section 17.3 of [HTTP] and Section 17.4 of [HTTP].
20.3. Content Scanning
Some servers or intermediaries provide scanning of content uploaded
by clients. Any scanning mechanism that relies on receiving a
complete representation in a single request message can be defeated
by resumable uploads because content can be split across multiple
messages. Servers or intermediaries wishing to perform content
scanning SHOULD consider how resumable uploads can circumvent
scanning and take appropriate measures. Possible strategies include
waiting for the upload to complete before scanning the entire
representation, or disabling resumable uploads.
20.4. Time-of-Check to Time-of-Use
There can be a significant delay between the creation of an upload
resource and its completion. Policy decisions or authorization
checks performed on the initial request might become outdated or
invalid by the time the upload completes. To mitigate
vulnerabilities arising from time-of-check to time-of-use (TOCTOU)
conditions, the server SHOULD validate that the user is still allowed
to perform the requested action before finalizing the upload. This
includes, for example, validating access privileges and quota
policies associated with the upload resource.
20.5. Resource Exhaustion
Resumable uploads are vulnerable to Slowloris-style attacks
[SLOWLORIS]. A malicious client can create upload resources and keep
them alive by regularly sending "PATCH" requests with no or small
content to the upload resources. This could be abused to exhaust
server resources by creating and holding open uploads indefinitely
with minimal work. Servers SHOULD provide mitigations for Slowloris
attacks, such as increasing the maximum number of clients the server
will allow, limiting the number of uploads a single client is allowed
to make, imposing restrictions on the minimum transfer speed an
upload is allowed to have, and restricting the length of time an
upload resource can exist.
20.6. Message Size Limits
Uploads performed as a series of appends can be used to upload data
up to the "max-size" limit (Section 5.1.1), which could be a larger
size than a server or intermediary might normally permit in
Kleidl, et al. Expires May 14, 2027 [Page 37]
Internet-Draft Resumable Uploads November 2026
conventional single upload request message content. Servers or
intermediaries need to consider that relying solely on message
content limits to constrain resources allocated to uploads might not
be an effective strategy when using resumable uploads.
20.7. Different Origins
The target resource of the initial request (Section 6) and the upload
resource might have different origins ([ORIGIN]). For example, the
initial request might be sent to an application server, while the
upload resource is hosted by a dedicated storage service.
Clients have to consider this change of origin when following the
"Location" header field to the upload resource. Credentials and
other per-origin state associated with the target resource of the
initial request are not necessarily applicable to the upload
resource, and remain scoped to their respective origins. Clients
also have to consider that disclosing an upload resource URI to a
different origin can leak the capability to read, append to, or
cancel the upload.
Because the upload can be completed either by the initial request or
by an upload append request, the final response might come from a
different origin depending on whether the upload was resumed. To
avoid this, the server MAY respond to the request that completes the
upload with a "303 (See Other)" status code, redirecting the user
agent to the origin of the target resource of the initial request.
21. IANA Considerations
21.1. HTTP Fields
IANA is asked to register the following entries in the "Hypertext
Transfer Protocol (HTTP) Field Name Registry":
Kleidl, et al. Expires May 14, 2027 [Page 38]
Internet-Draft Resumable Uploads November 2026
+-----------------+-----------+---------------+---------------------+
| Field Name | Status | Structured | Reference |
| | | Type | |
+-----------------+-----------+---------------+---------------------+
| Upload-Offset | permanent | Item | Section 4.1.1 of |
| | | | RFC nnnn |
| | | | |
| Upload-Complete | permanent | Item | Section 4.2.1 of |
| | | | RFC nnnn |
| | | | |
| Upload-Length | permanent | Item | Section 4.3.1 of |
| | | | RFC nnnn |
| | | | |
| Upload-Limit | permanent | Dictionary | Section 5.1 of RFC |
| | | | nnnn |
+-----------------+-----------+---------------+---------------------+
21.2. HTTP Status Code
IANA is asked to register the following entry in the "Hypertext
Transfer Protocol (HTTP) Status Code Registry":
Value: 104 (suggested value)
Description: Upload Resumption Supported
Specification: Section 12 of RFC nnnn
21.3. Media Type
IANA is asked to register the following entry in the "Media Types"
registry:
Type name: application
Subtype name: partial-upload
Required parameters: N/A
Optional parameters: N/A
Encoding considerations: binary
Security considerations: see Section 20 of RFC nnnn
Interoperability considerations: N/A
Published specification: Section 13 of RFC nnnn
Kleidl, et al. Expires May 14, 2027 [Page 39]
Internet-Draft Resumable Uploads November 2026
Applications that use this media type: Applications that transfer
files over unreliable networks or want pausable and resumable
uploads.
Fragment identifier considerations: N/A
Additional information:
o Deprecated alias names for this type: N/A
o Magic number(s): N/A
o File extension(s): N/A
o Macintosh file type code(s): N/A
o Windows Clipboard Name: N/A
Person and email address to contact for further information: See the
Authors' Addresses section of this document.
Intended usage: COMMON
Restrictions on usage: N/A
Author: See the Authors' Addresses section of this document.
Change controller: IETF
21.4. HTTP Problem Types
IANA is asked to register the following entry in the "HTTP Problem
Types" registry:
Type URI: https://iana.org/assignments/http-problem-
types#mismatching-upload-offset
Title: Mismatching Upload Offset
Recommended HTTP status code: 409
Reference: Section 14.1 of RFC nnnn
IANA is asked to register the following entry in the "HTTP Problem
Types" registry:
Type URI: https://iana.org/assignments/http-problem-
types#inconsistent-upload-length
Kleidl, et al. Expires May 14, 2027 [Page 40]
Internet-Draft Resumable Uploads November 2026
Title: Inconsistent Upload Length Values
Recommended HTTP status code: 400
Reference: Section 14.2 of RFC nnnn
22. References
22.1. Normative References
[HTTP] Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke,
Ed., "HTTP Semantics", STD 97, RFC 9110,
DOI 10.17487/RFC9110, June 2022,
.
[HTTP-CACHING]
Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke,
Ed., "HTTP Caching", STD 98, RFC 9111,
DOI 10.17487/RFC9111, June 2022,
.
[PATCH] Dusseault, L. and J. Snell, "PATCH Method for HTTP",
RFC 5789, DOI 10.17487/RFC5789, March 2010,
.
[PROBLEM] Nottingham, M., Wilde, E., and S. Dalal, "Problem Details
for HTTP APIs", RFC 9457, DOI 10.17487/RFC9457, July 2023,
.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119,
DOI 10.17487/RFC2119, March 1997,
.
[RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
May 2017, .
[RFC9112] Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke,
Ed., "HTTP/1.1", STD 99, RFC 9112, DOI 10.17487/RFC9112,
June 2022, .
[RFC9113] Thomson, M., Ed. and C. Benfield, Ed., "HTTP/2", RFC 9113,
DOI 10.17487/RFC9113, June 2022,
.
[RFC9114] Bishop, M., Ed., "HTTP/3", RFC 9114, DOI 10.17487/RFC9114,
June 2022, .
Kleidl, et al. Expires May 14, 2027 [Page 41]
Internet-Draft Resumable Uploads November 2026
[STRUCTURED-FIELDS]
Nottingham, M. and P. Kamp, "Structured Field Values for
HTTP", RFC 9651, DOI 10.17487/RFC9651, September 2024,
.
[URI] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
Resource Identifier (URI): Generic Syntax", STD 66,
RFC 3986, DOI 10.17487/RFC3986, January 2005,
.
22.2. Informative References
[INCREMENTAL]
Oku, K., Pauly, T., and M. Thomson, "Incremental
Forwarding of HTTP Messages", RFC 10036,
DOI 10.17487/RFC10036, August 2026,
.
[ORIGIN] Barth, A., "The Web Origin Concept", RFC 6454,
DOI 10.17487/RFC6454, December 2011,
.
[RFC8792] Watsen, K., Auerswald, E., Farrel, A., and Q. Wu,
"Handling Long Lines in Content of Internet-Drafts and
RFCs", RFC 8792, DOI 10.17487/RFC8792, June 2020,
.
[SLOWLORIS]
"RSnake" Hansen, R., "Welcome to Slowloris - the low
bandwidth, yet greedy and poisonous HTTP client!", June
2009, .
22.3. URIs
[1] https://tus.io/
Appendix A. Changes
This section is to be removed before publishing as an RFC.
A.1. Since draft-ietf-httpbis-resumable-upload-14
o State that unknown Structured Fields parameters MUST be ignored.
o Discourage change of upload URLs.
o Append request cannot use different content codings.
Kleidl, et al. Expires May 14, 2027 [Page 42]
Internet-Draft Resumable Uploads November 2026
o Define ranges for integer values in "Upload-Limit" and problem
type members.
A.2. Since draft-ietf-httpbis-resumable-upload-13
Editorial changes only.
A.3. Since draft-ietf-httpbis-resumable-upload-12
o Upload-Complete and Upload-Length are no longer required on offset
retrieval responses.
o Remove discouragement against sending requests after expiration.
o Clarify how upload offset is inferred from responses.
o Disallow successful responses indicating an incomplete upload when
the request indicated completion.
o Describe considerations for the initially targeted resource and
the upload resource having different origins.
A.4. Since draft-ietf-httpbis-resumable-upload-11
o Clear up different responsibilities of server and upload resource.
o Relax recommendations on client handling greater offsets.
o Clarify client behavior for 413 responses.
o Remove Accept-Patch from OPTIONS responses.
o Allow upload creation requests with no content regardless of the
"min-append-size" limit.
o Remove nominative languages addressing the lost final response.
o Allow "max-age" limit to decrease as expected.
o Redefine Upload-Complete on the server side.
o Recommend incremental delivery.
o Clarify "min-size" limit and its client behavior.
o Describe "GET" requests against upload resource.
Kleidl, et al. Expires May 14, 2027 [Page 43]
Internet-Draft Resumable Uploads November 2026
o Replace uses of term "upload length" with "representation's
length".
o Include "Upload-Limit" in response to limit violation.
o Clarify that clients might not know limits when starting upload.
o Remove section covering integrity digests.
o Increase the draft interop version.
o Add version-specific details on cancelling in-flight transfers.
o Clarify client retry strategies.
A.5. Since draft-ietf-httpbis-resumable-upload-10
o Add recommended disposition type for file name indication.
A.6. Since draft-ietf-httpbis-resumable-upload-09
o Requires Accept-Patch in OPTIONS.
o Add security consideration regarding time-of-check to time-of-use.
o Lift requirement on Upload-Complete for all final responses.
o Relax requirements on limit changes.
o Describe the interaction between 100 and 104 responses.
o Numerous editorial improvements.
A.7. Since draft-ietf-httpbis-resumable-upload-08
o Clarify definitions of new header fields.
o Make handling of OPTIONS * optional.
o Require server to announce limits using Upload-Limit.
o Require clients to adhere to known limits.
o Rephrase requirements for concurrency handling, focusing on the
outcome.
o Remove requirement for 204 status code for DELETE responses.
Kleidl, et al. Expires May 14, 2027 [Page 44]
Internet-Draft Resumable Uploads November 2026
o Increase the draft interop version.
o Add section about 104 status code.
o Rephrase recommendation for sending information back to client.
A.8. Since draft-ietf-httpbis-resumable-upload-07
o Clarify server handling when upload length is exceeded.
o Extend security considerations about upload resource URIs,
representation metadata, and untrusted inputs.
o Allow clients to retry for appropriate 4xx responses.
A.9. Since draft-ietf-httpbis-resumable-upload-06
o Minor editorial improvements to introduction and examples.
o Define structured types for new header fields.
A.10. Since draft-ietf-httpbis-resumable-upload-05
o Increase the draft interop version.
o Numerous editorial changes.
o Rename "expires" limit to "max-age".
o Require "Upload-Complete", but not "Upload-Offset" or "Upload-
Limit", for append responses.
o Add problem type for inconsistent length values.
o Reduce use of "file" in favor of "representation".
A.11. Since draft-ietf-httpbis-resumable-upload-04
o Clarify implications of "Upload-Limit" header.
o Allow client to fetch upload limits upfront via "OPTIONS".
o Add guidance on upload creation strategy.
o Add "Upload-Length" header to indicate length during creation.
o Describe possible usage of "Want-Repr-Digest".
Kleidl, et al. Expires May 14, 2027 [Page 45]
Internet-Draft Resumable Uploads November 2026
A.12. Since draft-ietf-httpbis-resumable-upload-03
o Add note about "Content-Location" for referring to subsequent
resources.
o Require "application/partial-upload" for appending to uploads.
o Explain handling of content and transfer codings.
o Add problem types for mismatching offsets and completed uploads.
o Clarify that completed uploads must not be appended to.
o Describe interaction with Digest Fields from RFC9530.
o Require that upload offset does not decrease over time.
o Add Upload-Limit header field.
o Increase the draft interop version.
A.13. Since draft-ietf-httpbis-resumable-upload-02
o Add upload progress notifications via informational responses.
o Add security consideration regarding request filtering.
o Explain the use of empty requests for creation uploads and
appending.
o Extend security consideration to include resource exhaustion
attacks.
o Allow 200 status codes for offset retrieval.
o Increase the draft interop version.
A.14. Since draft-ietf-httpbis-resumable-upload-01
o Replace Upload-Incomplete header with Upload-Complete.
o Replace terminology about procedures with HTTP resources.
o Increase the draft interop version.
Kleidl, et al. Expires May 14, 2027 [Page 46]
Internet-Draft Resumable Uploads November 2026
A.15. Since draft-ietf-httpbis-resumable-upload-00
o Remove Upload-Token and instead use Server-generated upload URL
for upload identification.
o Require the Upload-Incomplete header field in Upload Creation
Procedure.
o Increase the draft interop version.
A.16. Since draft-tus-httpbis-resumable-uploads-protocol-02
None
A.17. Since draft-tus-httpbis-resumable-uploads-protocol-01
o Clarifying backtracking and preventing skipping ahead during the
Offset Receiving Procedure.
o Clients auto-retry 404 is no longer allowed.
A.18. Since draft-tus-httpbis-resumable-uploads-protocol-00
o Split the Upload Transfer Procedure into the Upload Creation
Procedure and the Upload Appending Procedure.
Appendix B. Draft Version Identification
This section is to be removed before publishing as an RFC.
To assist the development of implementations and interoperability
testing while this document is still a draft, an interop version is
defined. Implementations of this draft use the interop version to
identify the iteration of the draft that they implement. The interop
version is bumped for breaking changes.
The current interop version is 10.
Client implementations of draft versions of the protocol MUST send a
header field "Upload-Draft-Interop-Version" with the interop version
as its value to its requests. The "Upload-Draft-Interop-Version"
field value is an Integer.
Server implementations of draft versions of the protocol MUST NOT
send a "104 (Upload Resumption Supported)" interim response when the
interop version indicated by the "Upload-Draft-Interop-Version"
header field in the request is missing or mismatching.
Kleidl, et al. Expires May 14, 2027 [Page 47]
Internet-Draft Resumable Uploads November 2026
Server implementations of draft versions of the protocol MUST also
send a header field "Upload-Draft-Interop-Version" with the interop
version as its value to the "104 (Upload Resumption Supported)"
interim response.
Client implementations of draft versions of the protocol MUST ignore
a "104 (Upload Resumption Supported)" interim response with missing
or mismatching interop version indicated by the "Upload-Draft-
Interop-Version" header field.
The reason both the client and the server are sending and checking
the draft version is to ensure that implementations of the final RFC
will not accidentally interop with draft implementations, as they
will not check the existence of the "Upload-Draft-Interop-Version"
header field.
Acknowledgments
This document is based on an Internet-Draft specification written by
Jiten Mehta, Stefan Matsson, and the authors of this document.
The tus v1 protocol [1] is a specification for a resumable file
upload protocol over HTTP. It inspired the early design of this
protocol. Members of the tus community helped significantly in the
process of bringing this work to the IETF.
The authors would like to thank Mark Nottingham for substantive
contributions to the text, along with the following in alphabetical
order for their thorough reviews of the document:
o Daniel Resnick
o Glenn Strauss
o Grant Gryczan
o Julian Reschke
o Mert Alev
o Mike Bishop
o Roy T. Fielding
o Willy Tarreau
Kleidl, et al. Expires May 14, 2027 [Page 48]
Internet-Draft Resumable Uploads November 2026
Authors' Addresses
Marius Kleidl (editor)
Transloadit
Email: ietf@mariuskleidl.net
Guoye Zhang (editor)
Apple Inc.
Email: guoye_zhang@apple.com
Lucas Pardue (editor)
Apple
Email: lucas@lucaspardue.com
Kleidl, et al. Expires May 14, 2027 [Page 49]