tus resumable upload protocol: specification and OpenAPI implementation guide

What tus specifies for interrupted file transfers

tus addresses a specific file-transfer problem: an upload does not have to restart from the beginning after a connection interruption. The project describes itself as an open protocol for resumable file uploads and presents it as a cross-platform, HTTP-oriented specification. Its intended users are developers who need clients and servers to agree on upload behavior, especially where transfers may be interrupted by an unreliable network, a browser navigation, or a restarted client process.

The important boundary is that this repository is a protocol definition, not a transfer application. It does not advertise a server, client library, executable, storage backend, or command-line uploader. An adopting team must implement or select those parts separately and make them conform to the protocol. That division makes tus useful as a shared contract between independently built components. It also places substantial responsibility on the implementer, because the repository cannot supply the networking, persistence, validation, authorization, or file assembly behavior needed in a production upload service.

The protocol is intended to be language agnostic. That can help organizations support uploaders written in different programming languages, provided each implementation follows the same HTTP contract. However, the repository metadata does not identify a primary implementation language, and the repository listing contains protocol, licensing, workflow, and OpenAPI files rather than an application source tree. This should be treated as a specification project rather than a turnkey upload package.

Repository structure and specification workflow

The canonical written definition is stored in `protocol.md`. The README points implementers to that file instead of summarizing the HTTP exchange in the repository landing page. HTML documentation is produced from Markdown through Jekyll and Kramdown by the separate tus.io repository. According to the README, the preview command is `make preview`, but that command is explicitly run there rather than being presented as an installation or build command for this repository.

The repository also includes an `OpenAPI/` directory containing OpenAPI 3.0.1 definitions for the tus protocol. This gives machine-readable input for tools that can generate clients, servers, or other API-access components. The README names go-swagger as one such tool and points to the Swagger tools collection for additional generators. It also names API Spec Converter when a different OpenAPI version is needed.

There is a qualification that matters during adoption. Since implementers are free to use different endpoints, the endpoints in the OpenAPI definitions are examples rather than mandatory deployment paths. A client generator may produce useful structures from those definitions, but teams should not assume that every endpoint is a compulsory production URL. They still need to consult `protocol.md` for the actual protocol requirements and compare those requirements with their chosen implementation.

OpenAPI definitions and generation boundaries

OpenAPI 3.0.1 provides the machine-readable part of the repository. The README describes OpenAPI as a standard, language-agnostic interface definition for REST APIs that lets humans and computers inspect declared service capabilities without reading source code, consulting separate documentation, or inspecting network traffic. In this repository, that representation covers tus protocol operations.

The intended generation flow is straightforward on paper. Start with the definitions under `OpenAPI/`, choose a compatible generator, and use its output as a starting point for client or server code. A generated result is not automatically a complete tus implementation. Endpoint paths are illustrative, and the README gives no instructions for adapting generated code to a real upload destination.

Version conversion introduces another adoption decision. The checked-in specification is OpenAPI 3.0.1. If a selected generator requires another specification version, the README names API Spec Converter as a possible option. It does not state which generators support which versions, nor does it claim that conversion preserves all semantics. This makes the converter a documented option rather than a guaranteed compatibility layer.

For engineering teams, the OpenAPI directory can reduce repetitive interface work, but it should not replace protocol review. Generated models and request definitions reflect the example endpoints. Resumption behavior, HTTP semantics, and any extension rules remain the responsibility of the implementation and its validation against `protocol.md`.

Reading the protocol before the first implementation

The repository does not document an installation procedure because there is no packaged application to install. The practical first use is protocol review: open `protocol.md`, identify the required upload interaction, and compare it with the operations under `OpenAPI/`. The reader should confirm that the written protocol and the machine-readable definitions agree on the fields and HTTP behavior needed by the intended client and server.

The README provides no runnable client example, sample request sequence, sample response, or deployment configuration. Consequently, there is no documented command in this repository that can perform a first file upload. Creating such an example would go beyond the available documentation. A team that needs a demonstrable upload before writing an implementation must choose its own client or server stack and verify it against the specification.

Documentation rendering is possible only through the separate website repository. The tus.io project renders `protocol.md` as HTML with Jekyll and Kramdown, and its README states that `make preview` is run there. This is relevant to documentation maintainers rather than uploader users. It does not install a service, configure an endpoint, or persist uploaded files.

The first engineering checkpoint should therefore be explicit: identify which protocol requirements will be mandatory, which may be extensions, and how the chosen storage backend represents an in-progress upload. The repository can define the interoperability target, but it does not answer deployment-specific questions about persistence, access control, file names, quotas, or cleanup.

Protocol contract versus alternative upload APIs

A conventional single-request upload sends a file in one HTTP operation. tus is based on a protocol designed for resumable upload behavior, so its value lies in defining agreement across transfer participants rather than providing one particular endpoint or backend. That is a different approach from adding resumability privately to an application-specific API: a tus-oriented implementation can target a common protocol instead of requiring every client to understand a vendor-specific route and payload convention.

This abstraction is useful when multiple clients or independent services must interoperate. It also creates a real limitation for teams seeking a small, self-contained solution. There is no bundled client, server, database schema, or transfer daemon here. Choosing tus means accepting the integration cost of implementing or obtaining those components.

The protocol may not be the right tool for a simple one-off upload feature whose transport is reliably short and does not need interruption recovery. In that case, a basic HTTP upload API could avoid protocol-specific integration work. Conversely, if an application already exposes nonstandard resume behavior and has no requirement for tus interoperability, adopting this specification may add a contract that provides little practical value. The decision should be based on interoperability and interruption requirements, not merely on the availability of OpenAPI definitions.

Maintenance, licensing, and implementation ownership

The repository is not archived, and its last push was on 2026-06-08. That indicates recent repository activity, but it does not by itself establish that every client or server ecosystem around the protocol is actively maintained. The only listed release is `v0.2.2`, dated 2014-06-22. The gap between the old release entry and the recent push means teams should not equate the available release listing with the full maintenance history.

The repository is licensed under the MIT license, with copyright attributed to Transloadit Ltd and Contributors for 2013 through 2016. That license permits reuse and modification under its conditions, although this review is not legal advice. Organizations should inspect `LICENSE.txt` for the exact terms and notices.

Upgrade cost depends mainly on the selected tus implementation, not this specification repository alone. Changes to the protocol can require coordinated client, server, OpenAPI definition, and conformance work. The repository does not provide compatibility matrices, release notes beyond the listed version, or a server upgrade guide. Before depending on it, implementers should compare `protocol.md` with the OpenAPI operations, identify unsupported protocol areas, and confirm whether their chosen client or server tracks the same contract.

Editorial conclusion

Developers building compatible upload clients or servers should adopt the protocol after confirming how their implementation handles uploads that stop and resume. Organizations looking for a ready-made uploader, a command-line transfer tool or a complete service should first verify that tus is the wrong level of abstraction for their deployment.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. tus/tus-resumable-upload-protocol on GitHub