Using cURL Commands with Swarm Storage and Gateway

1 Creating Domains and Buckets
2 Uploading Objects
3 Managing Objects and Domains
4 Setting Cluster and Node Configurations
5 Additional Operations
6 General Tips

Note

If you are using Gateway instead of a Swarm Storage node, remove the --post301 --location-trusted cURL options and you must add -u '<gateway username>:<password>' for Gateway authentication.

This document provides instructions for using cURLcommands to interact with SWARM Storage. Commands are organized into categories for creating and managing domains, buckets, objects, and configurations.

Creating Domains and Buckets

Create a Domain

To create a new domain in SWARM Storage, use the following command:

curl -i --location-trusted --post301 --data-binary "" "http://ipaddress/api?domain=domain&createdomain"

Notes: Replace domain with the desired domain name.

Create a Bucket

To create a bucket within a specified domain, use this command:

curl -i --location-trusted --post301 -XPOST --data-binary "" "http://ipaddress/api/testbucket?domain=domain"

Notes: Replace domain with the appropriate domain and testbucket with the bucket name.

Uploading Objects

Upload Multiple Objects

To upload multiple objects to a bucket, use the following loop:

for i in {1..10}; do curl -i --location-trusted -XPOST --post301 --data-binary @yourFileName "http://ipaddress/api/testbucket/NamedObject-$i.txt?domain=domain" -u "admin:admin"; done

Notes: Replace yourFileName with the file you are uploading, and domain with the domain. Adjust the number of iterations ({1..10}) as needed.

Upload a Single Object

To upload a single object to a bucket:

curl -i --location-trusted --post301 -XPOST --data-binary @yourFileName "http://ipaddress/api/testbucket/NamedObject.txt?domain=domain"

Notes: Replace yourFileName with the file you are uploading, and domain with the domain.

Managing Objects and Domains

Enable Policy Versioning on a Domain

To enable policy versioning on a domain:

curl -i --location-trusted -XPUT --post301 --data-binary '' -H "Policy-Versioning: enabled" "http://ipaddress/api?domain=domain&replicate=immediate&admin" -u "admin:password"

Notes: Replace domain with the target domain.

Check Object Integrity

To check the integrity of an object:

curl -i --location-trusted "http://ipaddress/api/testbucket/ObjectName.txt?domain=domain&checkintegrity"

Notes: Replace ObjectName.txt with the object's name, and domain with the domain.

Capture Manifest of a Version

To retrieve the manifest of a specific version of an object:

curl -i --location-trusted "http://ipaddress/api/testbucket/ObjectName.txt?domain=domain&readmanifest&version=versionID"

Notes: Replace versionID with the version identifier.

List All Information of an EC Object

To get the detailed information about an erasure-coded object:

curl -i --location-trusted "http://ipaddress/api/testbucket?domain=domain&format=json&name=ObjectName.txt&versions&field=all"

Notes: Replace ObjectName.txt with the object's name, and domain with the domain.

Setting Cluster and Node Configurations

Update Cluster Setting

To update a cluster setting, such as erasure coding conversion percentage:

curl -X PUT --header "Content-Type: application/json" --header "Accept: text/plain" -d "{}" "http://ipaddress:port/api/storage/clusters/_self/settings/ec.conversionPercentage?value=40" --digest -u "admin:password"

Notes: Replace ec.conversionPercentage?value=40 with the desired setting and its value, and ipaddress:port with your cluster's address.

Configure Node Setting

To configure node-level settings, such as health limits:

curl -i --location-trusted -X PUT --header "Content-Type: application/json" --header "Accept: text/plain" -d "{}" "http://ipaddress:port/api/storage/nodes/_self/settings/health.neonatalAgeLimit?value=30" -u "admin:password"

Notes: Replace health.neonatalAgeLimit?value=30 with the desired cluster setting and its value, and ipaddress:port with the node's address.

Additional Operations

Change Admin Password

To update the admin password for a cluster:

curl -X PUT --header 'Content-Type: application/json' --header 'Accept: text/plain' 'http://ipaddress:port/api/storage/clusters/_self/administrators/admin?password=newPassword' -u admin:oldPassword

Notes: Replace newPassword and oldPassword with the appropriate values.

Set Lifepoint

To configure the lifepoint for an object:

curl -v --post301 -XPOST -H 'Content-type: text/html' -H 'lifepoint: [Date] reps=2, deletable=False, [] delete' --location-trusted 'http://ipaddress/api/bucket/lifePointObject?domain=domain'

Notes: Replace [Date] with the desired date format like [Wed, 20 Oct 2025 11:08:00 GMT] and domain with the domain.

Delete a Bucket

To remove a bucket and all its contained objects:

curl -i --location-trusted -XDELETE "http://ipaddress/api/testbucket?domain=domain&recursive=now"

Notes: Replace domain with the domain.

Create an EC Object

To create an erasure-coded object wih the specified encoding:

curl -i --location-trusted --post301 --data-binary @yourFileName "http://ipaddress/api/testbucket/ec-named-1.txt?domain=domain&erasurecoded=yes&encoding=2:2"

Notes: Replace yourFileName with the file to be used and domain with the domain.

General Tips

Replace Placeholders: Always replace ipaddress, domain, yourFileName, and other placeholders with actual values relevant to your environment.
Permissions: Ensure that you have the necessary permissions for performing these operations.
Security: Use secure methods for handling sensitive information like passwords.

This document provides a structured approach to managing SWARM Storage and Gateway using cURL commands. For further details or troubleshooting, refer to the SWARM Storage documentation or your internal support resources.

For Waggle API documentation, please refer to https://docs.cloud.caringo.com/internal/swarm-storage-api.html

Knowledge Base