Alias Objects

alias

yes/true to activate

On write requests, indicates an alias object is 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 Integrity Assurance. 

On GET, validates data read from disk has not been corrupted. Swarm closes the connection before all data is sent if this check fails.

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.

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. The domain argument can be supplied by the client to explicitly override any value from the Host request header when the Host header does not match the domain name. A domain argument always has precedence over the Host header in the HTTP/1.1 request.

The sole situation domain is required is for an SCSP method on a domain object itself. Neither domain nor Host are 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 may otherwise be erasure-coded.

Using erasurecoded without encoding or when the cluster is not configured for EC results 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 enabling 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.

sync

now or wait to activate, no/false to inhibit

Appears on Gateway requests when enabling the Gateway Configuration option EnhancedListingConsistency. (v9.3)

Optionally used on a listing query GET request to force consistency of results 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 to provide Elasticsearch time to refresh the index.

Metadata

preserve

yes/true to activate

Works with COPY, PUT, and APPEND requests to verify custom metadata existing on the object is carried over on the write (See Custom Metadata Headers). Include the header name with the new value on the request to overwrite an existing value. Cannot be used with replace. (v9.2, v9.5)

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). Include the header name with the new value on the request to add new metadata. Cannot be used with preserve. (v9.5)

Named Objects

newname

{new name for object, bucket, domain}

Provides a new name (within the same bucket) for an update request (PUT, COPY, APPEND) on a named object. Requests for the original name return a 404 Not Found and the prior search metadata is removed after renaming an object.

'Subdirectory' names are part of the object name, so they must be included as part of a newname query argument. The bucket name stops at the first slash. Everything after the first slash, including other slashes, is part of the object name.

newname also allows renaming domains and buckets. See Renaming Domains and Buckets.

putcreate

yes/true to activate, no/false to inhibit

Allows use of HTTP PUT Create to create new named objects if set to yes. There is no need to add the putcreate query argument if the scsp.allowPutCreate storage setting is enabled.

Directs Swarm to treat the request as a regular PUT if set to no, generating a 404 Not Found error if the named object does not exist.

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 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.

This request creates a grace period based on the health.recursiveDeleteDelay Storage setting (the default is one week) unless using recursive=now. This grace period allows recreation of a bucket or domain before the content is lost. The health processor begins deleting all content contained in the deleted domain or bucket after the grace period ends. A critical error is logged indicating the object can be neither deleted nor accessed without the parent context if the deleted domain or bucket contains indelible objects. Added in v7.0. 

Replicate on Write (ROW)

count

integer

Used to affect the replicate=immediate behavior.

replicate

immediate, full, integer

Controls the response behavior to a POST, PUT, COPY, or APPEND request for a replicated object.

• immediate – 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 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. Swarm uses the smaller of those values if policy.replicas max or the lifepoint reps is less than this integer. 

The above rules apply with scsp.maxContextReplicas taking the place of policy.replicas max if the object in the request is a bucket or a domain.

SEND

feedid

feedtype

all | integer

all | search | replication | s3backup

Specifies one or more specific feeds (feedid=1&feedid=3) as the replication destination. Open the Swarm UI, select Cluster > Feeds, and locate the ID column to find existing feed IDs.

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 provided arguments; if neither are provided, SEND reverts to the SCSP SEND - Legacy. 

timeout

true | number of seconds | false

Sets how long to wait for replication to complete; if disabled (false; not recommended), feed processing can 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.

force

true | false | yes | no

If the value is true or yes, Swarm forces re-processing of the object though any associated feeds for objects previously processed.

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}

Operations referencing the current version proceed normally if used in contexts where versioning is disabled, but any other ETag results in a 404 - Not Found. (v9.2)

The query succeeds if the query argument value is the UUID (and ETag) of the object if used on GET or HEAD requests of an immutable object (which cannot be versioned). (v9.5)

suspendversioning

Allows temporary suspension of 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)

admin

yes/true to activate

Use 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 on an administrative override COPY request to specify the alias UUID (CID) of an existing domain or bucket for the purpose of changing the 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 may occur during replication. 

See Resolving Duplicate Domain and Bucket 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 the 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 all segments exist before executing a GET.

Swarm responds with 200 (OK) if it finds enough segments to recreate the object; else it returns 412 (Precondition Failed) and error text in the body of the response 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 the HEAD return the number and location of online replicas in the cluster. The count returned is for the object manifest for an erasure-coded object.

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 the normal cycle.

ignoreerrors

yes/true to activate

Used on an erasure-coded GET request to step over any broken EC sets and generate any data it can. Use of this query argument activates chunked transfer encoding.

recreatecid

domain or bucket alias UUID

Used for certain administrative actions, such as a special POST request to recreate a particular domain or bucket with the specified alias UUID. This is often performed after deleting a domain or bucket that orphans contents. See Restoring Domains and Buckets.

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 exist (applies to wholly replicated objects and segments).