SCSP Query Arguments

To use arguments, put a question mark (?) after the URI, add the query argument, and put an ampersand (&) before any and all subsequent arguments. See RFC 3986, section 3.4.

http։//yourURI?arg1=value&arg2=value&arg3=value

See Search Query Arguments, which are specific to Swarm's Elasticsearch integration.

Query Arguments by Area

The following table describes all of the SCSP query arguments, which are grouped by feature or purpose.

Query argument names are case-insensitive, as are most values.
A valueless query argument (with no =) is changed internally to true.
Write requests include POST, PUT, APPEND, and COPY.
Read requests include GET and INFO.
Booleans have equivalent forms: alias, alias=yes, alias=true

Applies to	Name	Value(s)	Description and usage
Alias Objects	alias	`yes/true` to activate	On write requests, indicates that an alias object should be created. The alias argument must be used with a POST method on an alias object and can optionally be included for other operations on alias objects.
Content Integrity	gencontentmd5	`yes/true` to activate	Computes the Content-MD5 for the body data of the request, returning the Content-MD5 as a header in the 201 Created response. Replaces the `Expect: Content-MD5` header, which is deprecated. (v9.2)
	hash	hash value	A content integrity hash value provided on the request for validation. The case of this argument does not matter.
	hashtype newhashtype	{ md5 \| sha1 \| sha256 \| sha384 \| sha512 }	Specifies the value of an object's hash. The `hashtype` query argument may appear on a variety of requests to generate or validate a content hash value. The `newhashtype` query argument is used to "re-seal" the content hash with one hash value while simultaneously checking another.
	validate	`yes/true` to activate	Validate On Read (VOR). Reads an object with an integrity seal. See Content Seals and Validation. On GET, validates that the data read from disk has not been corrupted. If this check fails, Swarm closes the connection before all of the data is sent.
Domains	createdomain	value ignored	[Deprecated: v9.2] Add to a WRITE to create the domain specified by `domain=domain-name`. See Manually Creating and Renaming Domains.
Domains	domain	domain-name	Represents the domain name in some SCSP requests. Client applications most often send the domain name as the Host in the request. When the Host header does not match the domain name, the domain argument can be supplied by the client to explicitly override any value from the Host request header. A domain argument always has precedence over the Host header in the HTTP/1.1 request. The only time domain is required is for an SCSP method on a domain object itself. Neither domain nor Host is required for requests within the default cluster domain.
Erasure Coding (EC)	encoding	k`:`p	The integer values for the data (k) and parity (p) segment counts when specifying erasure coding.
	erasurecoded	`yes/true` to override, `no/false` to inhibit	Used on EC writes to override the cluster's `policy.ecMinStreamSize` value. YES forces EC encoding for objects smaller than the cluster's minimum. NO prevents EC encoding on objects that might otherwise be erasure-coded. Using `erasurecoded` without `encoding` or when the cluster is not configured for EC will result in a 400 Bad Request.
	segmentsize	integer	The maximum size (in bytes) of a segment in any erasure-encoded set for this object, overriding the `ec.SegmentSize` configuration setting. This value cannot be smaller than 100 MB.
	segmentwidth	integer	Number of bytes. Allows `ec.segmentWidth` configuration value to be modified per request.
Listing Consistency	index	`yes/true` to activate, `no/false` to inhibit	Appears on Gateway requests when you enable the Gateway Configuration option `EnhancedListingConsistency`. (v9.3) Optionally supplied on a POST, PUT, COPY, APPEND, or DELETE request. Performs synchronous search indexing of the newly written/deleted object.
Listing Consistency	sync	`now` or `wait` to activate, `no/false` to inhibit	Appears on Gateway requests when you enable the Gateway Configuration option `EnhancedListingConsistency`. (v9.3) Optionally used on a listing query GET request to force consistency of results that are returned on the listing. `now` performs a refresh on the index in Elasticsearch immediately before preforming the listing query. `wait` delays execution of the listing query in order to give Elasticsearch time to refresh its index.
Metadata	preserve	`yes/true` to activate	Works with COPY, PUT, and APPEND requests to ensure that any custom metadata existing on the object is carried over on the write (see Custom Metadata Headers). To overwrite an existing value, include the header name with the new value on the request. Cannot be used with `replace`. (v9.2, v9.5)
Metadata	replace	`yes/true` to activate	Works with APPEND requests to remove any custom metadata existing on the object on the write, overriding the default APPEND behavior to preserve them (see Custom Metadata Headers). To add new metadata, include the header name with the new value on the request. Cannot be used with `preserve`. (v9.5)
Named Objects	newname	{new name for object, bucket, domain}	Provides a new name (within the same bucket only) for an update request (PUT, COPY, APPEND) on a named object. After you rename an object, requests for the original name return a 404 Not Found and the prior search metadata is removed. Remember that 'subdirectory' names are part of the object name, so they must be included as part of a `newname` query arg. The bucket name stops at the first slash, and everything after the first slash, including other slashes, are part of the object name. `newname` also lets you rename domains and buckets. See Renaming Domains and Buckets.
Named Objects	putcreate	`yes/true` to activate, `no/false` to inhibit	If set to yes, lets you use HTTP PUT Create to create new named objects. If the `scsp.allowPutCreate` storage setting is enabled, you do not need to add the `putcreate` query argument. If set to no, directs Swarm to treat the request as a regular PUT, generating a 404 Not Found error if the named object does not exist. Note Although domains and buckets are named, Swarm applies all PUT requests on these objects as updates, regardless of the setting. If `putcreate=yes` is used on a domain or bucket, Swarm fails the request with a 400 Bad Request error. See SCSP WRITE.
Multipart Write	inprogress	`yes/true` to activate	On a multipart PATCH complete, postpones HP segment consolidation until the object is completed again without the query argument, or by another method, such as COPY. (v9.4)
	shrink		On a multipart PATCH, required if the patch reduces the size of the object. (v9.4)
	partnumber	integer	On a multipart POST, indicates the part number of a multipart upload in progress. (v7.0)
	uploadid	upload id	On a multipart POST or DELETE, identifies all requests associated with a single multipart upload. It returns the ID as a 98-byte string. (v7.0)
	uploads	`yes/true` to activate	On a multipart POST, PUT, or APPEND, indicates that the request is a multipart upload write initiate. (v7.0)
Recursive Delete	recursive	`yes/true` to flag for deletion `now` for immediate reclamation	Required on DELETE of a bucket or domain (context). Indicates when the health process may begin asynchronously reclaiming any content contained in the deleted context. Unless you use `recursive=now`, this request creates a grace period based on the `health.recursiveDeleteDelay` Storage setting (the default is one week). This grace period lets you recreate a bucket or domain before its content is lost. After the grace period ends, the health processor will begin deleting all of the content contained in the deleted domain or bucket. If the deleted domain or bucket contains undeletable objects, a critical error is logged that the object can be neither deleted nor accessed without its parent context. Added in v7.0.
Replicate on Write (ROW)	count	integer	Used to affect the `replicate=immediate` behavior.
Replicate on Write (ROW)	replicate	`immediate`, `full`, integer	Controls the response behavior to a POST, PUT, COPY, or APPEND request for a replicated object. `immediate` – Only two replicas must be created before Swarm sends the response; if more replicas are required, those additional replicas are created after the response. `full` – All of the required replicas must be created before Swarm sends the response. `integer` – Specifies the number of replicas to be created. As with `immediate`, two replicas must be created before Swarm sends the response. However, if `policy.replicas max` or the lifepoint reps is less than this integer, then Swarm uses the smaller of those values. If the object in the request is a bucket or a domain, the above rules apply with `scsp.maxContextReplicas` taking the place of `policy.replicas max`.
SEND	feedid feedtype	all \| integer all \| search \| replication \| s3backup	Specifies one or more specific feeds (`feedid=1&feedid=3`) as the replication destination. To find existing feed IDs, open the Swarm UI, select Cluster > Feeds, and locate the ID column. Specifies one or more types of feeds as the replication destination, from among these values: search, replication, s3backup. Use the special value “all” to refer to all feed IDs or types, including no feed. The SEND request needs query arguments for feedid, feedtype, or both, which is a union of all of those provided arguments; if you do not provide either, SEND reverts to the legacy behavior.
	timeout	true \| number of seconds \| false	Sets how long to wait for replication to complete; if disabled (false; not recommended), feed processing could go on indefinitely if a feed is blocked. Using timeout=true waits for the Swarm setting scsp.defaultFeedSendTimeout time in seconds, which defaults to 30. Specifying a positive number for the timeout overrides the value in the Swarm setting.
Versioning	version	ETag of desired object version	Used on GET, HEAD, DELETE, COPY, APPEND, or SEND requests to specify a previous version to target on the request: `version={etag}` If used in contexts where versioning is disabled, operations that reference the current version proceed normally, but any other ETag results in a 404 - Not Found. (v9.2) If used on GET or HEAD requests of an immutable object (which cannot be versioned), the query will succeed if the query argument value is the UUID (and ETag) of the object. (v9.5)
	suspendversioning		Lets you temporarily suspend version creation on POST, PUT, COPY, APPEND, and DELETE requests for versioned objects. It has the effect of updating the current version without adding to the versioning chain. (v9.5)

Support and Administration Arguments

Name	Value(s)	Description and usage
admin	`yes/true` to activate	Use only with requests by the 'admin' user. An override used to rescue content from being stranded with no ability to delete or update it due to an overly restrictive Allow header.
aliasuuid	domain-UUID	Used only on an administrative override COPY request to specify the alias UUID (CID) of an existing domain or bucket for the purpose of changing its name. It must be used with the `newname` argument, which provides the new domain or bucket name. This is used to resolve name collisions that might occur during replication. See Resolving Duplicate Domain Names.
checkintegrity	`yes/true` to activate	Used on a GET of an erasure-coded object to get a summary of what segments exist in the manifest and their locations in the cluster. The body of the request has this information instead of the object. `checkintegrity` is a fast and efficient way to check the integrity of an erasure-coded object, for verifying that all segments exist before executing a GET. Swarm responds with 200 (OK) if it finds enough segments to recreate the object; if not, it returns 412 (Precondition Failed) and error text in the body of the response that lists the missing segments.
cid	UUID	A Context Identifier (CID) can be used to access an otherwise inaccessible object. See Accessing Inaccessible Objects with CID.
countreps	`yes/true` to activate or `diskless`	Used to have that HEAD return the number and location of replicas that are online in the cluster. For an erasure-coded object, the count returned is for the object manifest.
examine	`yes/true` to activate	On a GET or HEAD request, triggers an immediate health processor examination of the request object rather than waiting for the health processor to revisit the object as part of its normal cycle.
ignoreerrors	`yes/true` to activate	Used on an erasure-coded GET request to step over any EC sets that may be broken and, in effect, generate any data it can. Use of this query argument activates chunked transfer encoding.
recreatecid	domain or bucket alias UUID	Used only for certain administrative actions, such as a special POST request to recreate a particular domain or bucket with the specified alias UUID. Often, this is done after deleting a domain or bucket that orphans contents. See Restoring Domains and Buckets. Warning Do not attempt to use `recreatecid` as a way to move bucket contents across domains within the cluster.
redir	`yes/true` to activate, `no/false` to inhibit	Asks the request PAN to encourage or inhibit redirection on the request.
verbose	`yes/true` to activate	Used on a GET or HEAD request to have all relevant headers returned in the response. (v8.1) Includes a `MinReps` header that reports the number of replicas that should exist (applies to wholly replicated objects and segments).