Upload data to distributed storage

POST

/api/v1/storage/upload

curl --request POST \
  --url http://localhost:8080/api/v1/storage/upload \
  --header 'Content-Type: application/json' \
  --header 'X-Signature: <X-Signature>' \
  --data '{ "userAddr": "0x1234567890123456789012345678901234567890", "chunkID": 1, "data": "SGVsbG8gV29ybGQh" }'

• Local development server
• API v1 base path

Upload encrypted data to the distributed mesh storage network. Data is automatically encrypted (if not already encrypted) and distributed across multiple nodes using Reed-Solomon erasure coding for fault tolerance.

Authentication: Requires Ethereum wallet signature (X-Signature and X-Timestamp headers)

Authorizations

• EthereumSignature
• LegacyECDSA

Request Body^required

Media typeapplication/json

object

userAddr

required

Ethereum address (42 characters, 0x prefix)

string

/^0x[a-fA-F0-9]{40}$/

chunkID

Chunk identifier (0 or positive integer)

integer

data

required

Base64-encoded data to store

string format: byte

signature

Optional wallet signature for encryption key derivation

string

password

Optional password for encryption (alternative to signature)

string

encrypted

True if data is already client-encrypted

boolean

Examples

Basic upload with wallet-derived encryption

{
  "userAddr": "0x1234567890123456789012345678901234567890",
  "chunkID": 1,
  "data": "SGVsbG8gV29ybGQh"
}

Upload with signature-based encryption

{
  "userAddr": "0x1234567890123456789012345678901234567890",
  "chunkID": 1,
  "data": "SGVsbG8gV29ybGQh",
  "signature": "0xabc..."
}

Upload pre-encrypted data

{
  "userAddr": "0x1234567890123456789012345678901234567890",
  "chunkID": 1,
  "data": "SGVsbG8gV29ybGQh",
  "encrypted": true
}

Responses

200

Upload successful

Media typeapplication/json

object

success

boolean

userAddr

string

chunkID

integer

originalSizeBytes

Original data size in bytes

integer

encryptedSizeBytes

Encrypted data size in bytes

integer

shardCount

Number of shards created

integer

shardSizeBytes

Size of each shard in bytes

integer

storageNodes

List of node IDs storing the shards

Array<string>

redundancy

Redundancy ratio

number format: float

faultTolerance

Number of shards that can be lost

integer

encrypted

Whether data is encrypted

boolean

encryptionInfo

Encryption method used

string

uploadedAt

Upload timestamp

string format: date-time

shardLocations

Array<object>

object

shardIndex

Index of the shard

integer

nodeId

Node ID storing this shard

string

addresses

Network addresses of the node

Array<string>

Example

{
  "success": true,
  "userAddr": "0x1234567890123456789012345678901234567890",
  "chunkID": 1,
  "originalSizeBytes": 1024,
  "encryptedSizeBytes": 1040,
  "shardCount": 15,
  "shardSizeBytes": 70,
  "storageNodes": [
    "QmNode1...",
    "QmNode2..."
  ],
  "redundancy": 1.5,
  "faultTolerance": 5,
  "encrypted": true,
  "encryptionInfo": "AES-256-GCM (wallet-derived)",
  "uploadedAt": "2025-12-10T12:00:00Z",
  "shardLocations": [
    {
      "shardIndex": 0,
      "nodeId": "QmNode1...",
      "addresses": [
        "/ip4/192.168.1.1/tcp/9000"
      ]
    }
  ]
}

400

Bad Request - Invalid parameters

Media typeapplication/json

object

error

Error type

string

message

Human-readable error description

string

code

Optional error code

string

Example

{
  "error": "Invalid request",
  "message": "User address must be a valid Ethereum address (0x...)"
}

401

Unauthorized - Authentication failed

Media typeapplication/json

object

error

Error type

string

message

Human-readable error description

string

code

Optional error code

string

Example

{
  "error": "Authentication failed",
  "message": "Invalid signature or expired timestamp"
}

429

Too Many Requests - Rate limit exceeded

Media typeapplication/json

object

error

Error type

string

message

Human-readable error description

string

code

Optional error code

string

Example

{
  "error": "Rate limit exceeded",
  "message": "Maximum 100 requests per minute"
}

Headers

X-RateLimit-Limit

integer

Example

100

Request limit per minute

X-RateLimit-Remaining

integer

Example

0

Remaining requests in current window

X-RateLimit-Reset

integer

Example

1702234620

Unix timestamp when rate limit resets

500

Internal Server Error

Media typeapplication/json

object

error

Error type

string

message

Human-readable error description

string

code

Optional error code

string

Example

{
  "error": "Internal server error",
  "message": "An unexpected error occurred"
}