Header Limits: Headers (metadata) are constrained not only by Swarm but by all services, proxies, and clients (such as Elasticsearch, Twisted, Jetty, HAProxy) handling objects. A Swarm object may have any number of annotations associated with it, but each annotation object is subject to these limits. The persisted metadata on Swarm objects must fall within these limits by default:

500 - The total number of headers on an object
32 KB - The combined length of all headers (key/value pairs); exceeding this returns a 400 (Bad Request) error
16 KB - The maximum length for a given header (key/value pair)

The following tables list all headers supported or used by Swarm. The headers described apply to buckets, named objects, and aliased objects unless otherwise noted.

Methods are the SCSP methods to which the header applies.
Request (signified by X)
Response (signified by X)
- V means it appears only with verbose=true
- T means it appears in a trailing response
Writable (signified by W)
- R means it is read-only
Persisted indicates whether the header is persisted with the object. Note: some persisted headers are not writable (signified by P).

Best Practice

Always use case-insensitive header matching.

Swarm-Specific Headers

Header	Description	_Method	_Request	_{Response [Trailing] [Verbose]}	_{Writable [Read-only]}	_Persisted

Header	Description	_Method	_Request	_{Response [Trailing] [Verbose]}	_{Writable [Read-only]}	_Persisted
Castor-System-Accessed	Used on GET/HEAD requests to indicate the time the object was last accessed (written or GET).	GET, HEAD		X V
Castor-System-CompositeMD5	Multipart-written objects only. This composite value, stored with the completed object, is computed on the multipart complete as the sum of the Content-MD5 values of all parts. This header value is reused on subsequent COPY operations but removed on other updates (PUT, APPEND).	GET, HEAD, POST		T
Castor-System-Decorates	Set to the ETag of a Swarm object to be decorated. When the decorated object is deleted or overwritten, the object with this header is reclaimed by the health processor.	All	X	X	W	P
Castor-System-Headers-Filtered	If response headers are filtered by a whitelist or blacklist, this header is added.	GET, HEAD		X	R
Castor-System-InProgress	Returned with value yes on a verbose request when the inprogress flag is set on a stream. Not returned at all when the flag is not set.	GET, HEAD		X V
Castor-System-Result	Reports the response code, such as 201 (Created) or 404 (Not Found), as a trailing header for a multipart write completion.	POST		T
Castor-System-Tiered	Audit headers for objects restored by an S3 Backup feed. One copy captures the date and source cluster of the backup, and another captures the date and S3 host/bucket of the restore. Dates are same format as Last-Modified.	GET, HEAD		X V	R	P
Castor‑{anything}	{anything} cannot start with "system". Uninterpreted; meant for client customization.	All			W	P
Castor‑Authorization	Content‑level authorization.	All	X		W	P
Castor‑System-Bytes‑Used	With bucket list du, the number of bytes in the query without replicas.	GET (listing)		X
Castor‑System-Bytes‑Used‑With‑Reps	With bucket list du / withreps requests, the number of bytes in the query with replicas.	GET (listing)		X
Castor‑System-Object‑Count	In a bucket listing request, the number of objects returned by the query.			X
Castor‑System‑Alias	The alias UUID of an alias object, bucket, or domain. This UUID cannot be used in any SCSP method on a domain, bucket, or named object. Use it to execute SCSP methods on an aliased object or to delete an unnamed immutable object.	GET, HEAD, DELETE		X	R	P
Castor‑System‑Auth	Special headers for a GET/retrieve request. The username:password for an administrative account on the remote cluster, only if it differs from the source cluster.	SEND	X
Castor‑System‑CID	For named and tenanted unnamed objects, the alias UUID of the owning context.	GET, HEAD, DELETE		X	R	P
Castor‑System‑Cluster	Name of the cluster where the object was created or last updated. For SEND, The value of the cluster.name setting of the destination cluster.	GET, HEAD, DELETE, SEND		X	R	P
Castor‑System‑Created	A timestamp that specifies when the object was created or last updated. Uses HTTP time, an ASCII format based on GMT.	GET, HEAD, DELETE		X	R	P
Castor‑System‑Domain	Named objects only. Shows the name of the domain where the object was created. The domain name in which this object is tenanted. Computed on GET and HEAD. Returns <domain>.	GET, HEAD		X V	R	P
Castor‑System‑EnforceTenancy	True or False depending on cluster.enforceTenancy. A response header on the status page.	GET		X
Castor‑System‑Error‑Code	Sent with any error response. The request error code (if applicable). This code is usually a 4xx or 5xx HTTP response code. May appear as a trailing header on multipart write complete requests.	All		X
Castor‑System‑Error‑Text	Sent with any error response. The request error description (if applicable). Provides a description of the error. May appear as a trailing header on multipart write complete requests.	All		X
Castor‑System‑Error‑Token	Sent with any error response. A unique error token (if applicable). Provides a parsed token that uniquely identifies the error. May appear as a trailing header on multipart write complete requests.	All		X
Castor‑System‑IsVersioned	Header indicating the object versioning state in effect at the time the object was written. May only appear on alias or named objects. True if the object was written in the versioning‑Enabled state. "False" if the object was written in the versioning‑Suspended state. There is no header otherwise. A flag for the object's Swarm versioning status, which does not appear on objects created in a versioning‑disabled context. True means it was created in the versioning‑Enabled state. False means it was created in the versioning‑Suspended state. 9.6.a: Maps to "versioned" (boolean) search query argument.	GET, HEAD			R	P
Castor‑System‑LicenseCapacityTB	Return on a cluster status request. Indicates the licensed capacity, in TB.			X
Castor‑System‑LicenseSerialNumber	Returned on a cluster status request. Indicates the license serial number, or 'unregistered.'			X
Castor‑System‑Name	Named objects only. Symbolic name of the object, which is the user‑Specified (partial) name for this object.	GET, HEAD, DELETE		X	R	P
Castor‑System‑Next‑Version	Appears only on admin or administrative GET or HEAD responses. When object versioning is enabled or suspended, named and alias objects include these headers if there is a previous or next version in the version chain for the object.	GET, HEAD		X V
Castor‑System‑Owner	The user id of the authenticated user who wrote the object. Name of the user who created or last modified the object. If the object was created anonymously (that is, without authenticating), this header is absent.	All			R	P
Castor‑System‑PartNumber	Special headers for multipart write requests. Identifies the part number of a part in the temporary manifest for a multipart write.	POST, PUT	X		W	P
Castor‑System‑Path	For named objects only, shows the full path of the object in /domain/bucket/object format. Example: /cluster.example.com/mybucket/mypath/myobject.html. Computed on GET and HEAD. Returns <domain>/<bucket>/<name>.	GET, HEAD		X V	R	P
Castor‑System‑Persisted-Headers	Indicates which of the other headers on the response are persisted.	GET, HEAD		X V
Castor‑System‑Previous‑Version	Appears only on admin or administrative GET or HEAD responses. When object versioning is enabled or suspended, named and alias objects include these headers if there is a previous or next version in the version chain for the object.	GET, HEAD		X V
Castor‑System‑TotalGBAvailable	A response header on the status page.	GET		X
Castor‑System‑TotalGBCapacity	A response header on the status page.	GET		X
Castor‑System‑UploadID	Special header for multipart write requests. As a response header, it identifies the multipart write request for all subsequent requests relating to the upload. As a persisted header, it associates a stream with a multipart upload, either as the init stream or a part, based on its Castor-System-PartNumber value.	GET, HEAD	X		R	P
Castor‑System‑Version	A numerical version number associated with mutable objects. This is a UNIX‑Style floating point time since GMT epoch with millisecond accuracy. The timestamp (in seconds since epoch) when the object was written, which corresponds to Last‑Modified. Not writable: Although it is persisted, this header cannot be supplied on any non‑admin requests.	All		X	R	P
Composite-Content-MD5	Provides an end‑to‑end integrity check of the content (excluding metadata) of a parallel write request at the time of completion. The supplied value is a base-64 encoding of the concatenation of the binary Content-MD5 hashes of the parts (in order) followed by a dash, followed by the number of parts as text value. On the complete request, Swarm computes the value for the overall request and reject the request with a 409 error if the values do not match.	POST	X	X	W	P
Content-MD5	Users can compute the md5 sum of the object prior to write. The header is preserved and checked on GET. A persisted Content-MD5 can also be generated by Swarm.	POST, PUT, GET, HEAD	X	X	W	P
Content-type: application/castorcontext	Required to create a context. Content-Type is a standard HTTP header.	POST, PUT	X
Content‑UUID	One header per UUID specified. Indicates the alias or primary uuid from a diskless countrep HEAD request. Also on a write request indicating the new content uuid. Unnamed objects only. COPY and PUT are invalid methods for immutable objects. Not writable: Although it is persisted, this header cannot be supplied on any non‑admin requests. Is returned as a trailing header on multipart write completes.	All		X	W	P
Feed‑{id}‑Status	On a verbose GET or HEAD, returns the status of each defined feed, one per header. The {id} is the ID field from the feed definition. The value is 0 for success (no writes remaining), 1 for timeout, or else the number of attempts made to write the object.	GET, HEAD		X V
Feed‑{id}‑StatusTime	On a verbose GET or HEAD, returns the status time of each defined feed, one per header. Time is HTTP time.	GET, HEAD		X V
Lifepoint	Time‑based SCSP and HP directives. Returned for an object created with a lifepoint header.	All	X	X	W	P
Manifest	Indicates the object is erasure coded. Indicates the manifest type of the object being created or queried. Internal. Used with replica transfer. Currently, "ec" is the only value used. Indicates the manifest type of the object being created or queried. Also returned on a verbose GET/HEAD for EC objects.	All		X V
Node-Status	Return on a cluster status request. Indicates the current node status.			X
Overlay‑IPs	A list of space‑separated IP addresses associated with the overlay key. Only on a countreps HEAD request. Up to two IP headers may appear.			X
Overlay‑Key	An overlay index key used for this object. Only on a countreps HEAD request. Up to two keys may appear.			X
Policy-*	Include Policy-* headers in the header inclusion list or use the preserve query argument for COPY.	COPY			W	P
Policy-ECEncoding	Optional; context objects only. Stores the encoding policy for erasure coding named objects in this context. Valid values: unspecified, disabled, k:p (a tuple such as 5:2 that specifies the data and parity encoding to use). For a domain, appending "anchored" cancels any policies on its buckets.	All	X	X	W	P
Policy-ECEncoding-Unnamed	Optional; domain objects only. Stores the encoding policy for erasure coding unnamed objects tenanted in this domain. Valid values: unspecified, disabled, k:p (a tuple such as 5:2 that specifies the data and parity encoding to use).	All	X	X	W	P
Policy-ECMinStreamSize	Optional; context objects only. Stores the minimum object size that triggers erasure coding of named objects in this context. In units of megabytes (MB) or gigabytes (GB); must be 1MB (default) or greater. For a domain, appending "anchored" cancels any policies on its buckets.

Swarm Documentation

SCSP Headers

Best Practice

Swarm-Specific Headers