W3Stor

Documentation

Persistent agent memory and decentralized storage. Upload to IPFS instantly, replicate across Filecoin SPs permanently, build knowledge graphs with semantic search. Pay per request with x402 micropayments.

Quick Start

Upload a file with a single cURL command. Include an x402 payment header for paid endpoints.

curl -X POST https://api.w3s.storage/upload \  -H "Content-Type: multipart/form-data" \  -F "file=@photo.jpg"

REST API

Storage, agent memory, and auth endpoints power the entire lifecycle. Endpoints marked x402 require micropayment. Agent memory reads require a SIWE JWT session.

POST/upload

Upload a file to IPFS + Filecoin. Requires x402 payment header.

fileFilerequired

The file to upload (multipart/form-data)

tagsstring

Comma-separated tags for organization

replicationTargetnumber

Number of SP replicas (default: 3)

cidstringrequired

Content identifier (CIDv1)

sizenumberrequired

File size in bytes

pinataUrlstringrequired

IPFS gateway URL

statusstringrequired

Initial status: pinned

GET/status/{cid}

Check storage and replication status for a CID.

cidstringpathrequired

Content identifier to check

cidstringrequired

The queried CID

statusstringrequired

pinned | storing | stored | failed

providersarray

List of SP providers storing this CID

replicationCountnumber

Number of confirmed SP replicas

GET/files

List all files for the authenticated wallet.

statusstringquery

Filter by status: pinned | storing | stored

limitnumberquery

Max results (default: 50)

offsetnumberquery

Pagination offset

filesarrayrequired

Array of file objects

totalnumberrequired

Total file count

POST/attest/{cid}

Create an on-chain attestation for a stored file. Requires x402 payment.

cidstringpathrequired

CID to attest

attestationIdstringrequired

On-chain attestation identifier

txHashstringrequired

Transaction hash

timestampnumberrequired

Unix timestamp of attestation

POST/graph/files

Add a file to your agent memory graph. Generates semantic embeddings from metadata. Requires x402 payment.

cidstringrequired

CID of the file to add

descriptionstring

Description for semantic search

tagsstring[]

Tags for organization and search

successbooleanrequired

Whether the file was added

nodeobjectrequired

The created graph node

POST/graph/connections

Create a relationship between two files in your memory graph. Requires x402 payment.

fromCidstringrequired

Source file CID

toCidstringrequired

Target file CID

relationshipstringrequired

Freeform label (e.g. references, derived_from)

successbooleanrequired

Whether the connection was created

edgeobjectrequired

The created graph edge

GET/graph/search

Semantic search across your agent memory. Requires SIWE JWT auth.

qstringqueryrequired

Natural language search query

limitnumberquery

Max results (default: 10)

thresholdnumberquery

Similarity threshold 0-1 (default: 0.5)

resultsarrayrequired

Array of {cid, filename, score, gatewayUrl}

GET/graph/traverse/{cid}

Traverse connected files from a starting point. Requires SIWE JWT auth.

cidstringpathrequired

Starting file CID

depthnumberquery

Max traversal depth (default: 2)

nodesarrayrequired

Discovered file nodes

edgesarrayrequired

Relationships between nodes

POST/upload/batch

Upload multiple files with graph connections in one x402 payment. Max 10 files, 100MB total, 50 connections.

file_0...file_NFilerequired

Files as multipart form fields

metadatastringrequired

JSON with per-file descriptions, tags, and connections

filesarrayrequired

Array of uploaded files with CIDs and graph status

connectionsarrayrequired

Created graph connections with success status