About

load-s3-agent is a data agent built on top of HyperBEAM ~s3@1.0 temporal data storage device. This agent orchestrates the location of the data moving it from temporal to permanent (Arweave).

N.B: beta testing release, unstable and subject to breaking changes, use in testing enviroments only.

Agent API

• GET / : agent info
• GET /provenance/{id} : return the onchain provenance proof of an offchain ANS-104 dataitem (only for dataitems that enabled the onchain provenance flag at upload).
• GET /{dataitem_id} : generate a presigned get_object URL to access the ANS-104 DataItem data - DEPRECATED since v0.7.0 - use gateway.s3-node-1.load.network/resolve/$DATAITEM_ID instead
• GET /agg/daily?days=N : return the sum-per-day new added data size and dataitems count. N default to 30.
• GET /agg/daily/mime : return the aggregated content-type frequency per day.
• GET /agg/daily/anchored : return the aggregated count of anchored LS3 dataitems to Arweave.
• POST /tags/query : query dataitems for a given tags KV pairs.
• POST /query/dataitem : fetch full metadata for a specific dataitem_id.
• POST /upload : post data (or signed dataitem) to store a public offchain DataItem on ~s3@1.0
• POST /upload/private : post data (or signed dataitem) to store a private offchain DataItem on ~s3@1.0
• POST /post/{dataitem_id} : post an ~s3@1.0 public DataItem to Arweave via Turbo (N.B: Turbo covers any dataitem cost with size <= 100KB).

Upload data and return an agent public signed DataItem

echo -n "hello world" | curl -X POST https://load-s3-agent.load.network/upload \
  -H "Authorization: Bearer $load_acc_api_key" \
  -F "file=@-;type=text/plain" \
  -F "content_type=text/plain"

Or optionally add custom tags KVs that will be included in the ANS-104 DataItem construction

echo -n "hello custom tagged world"  | curl -X POST https://load-s3-agent.load.network/upload \
    -H "Authorization: Bearer $load_acc_api_key" \
    -F "file=@-;type=text/plain" \
    -F 'tags=[{"key":"tag1","value":"tag1"},{"key":"tag2","value":"tag2"}]'

Optional: have the agent publish an offchain provenance record for the uploaded DataItem (the API returns the provenance transaction id in offchain_provenance_proof):

echo -n "hello provenance world" | curl -X POST https://load-s3-agent.load.network/upload \
  -H "Authorization: Bearer $load_acc_api_key" \
  -H "offchain-provenance: true" \
  -F "file=@-;type=text/plain"

• onchain provenance example: https://viewblock.io/arweave/tx/fnmmd6pqOOQFFpscH8AB4CyGDsGSt_fG5VCPJioBG3c
• offchain dataitem: https://gateway.s3-node-1.load.network/resolve/gT03XTtL0GCfb2AxJFjg8OVkhMuLQvwQVi7KvrbKYF8
• provenance receipt (including settlement): https://load-s3-agent.load.network/provenance/gT03XTtL0GCfb2AxJFjg8OVkhMuLQvwQVi7KvrbKYF8

Upload data and return an agent private signed DataItem

*** N.B: any private DataItem does not have the tags indexed nor is queryable ***

echo -n "hello world" | curl -X POST https://load-s3-agent.load.network/upload/private \
  -H "Authorization: Bearer $load_acc_api_key" \
  -H "x-bucket-name: $bucket_name" \
  -H "x-dataitem-name: $dataitem_name" \
  -H "x-folder-name": $folder_name" \ 
  -H "signed: false" \  
  -F "file=@-;type=text/plain" \
  -F "content_type=text/plain"

Upload signed dataitem to a private bucket (private dataitem)

curl -X POST https://load-s3-agent.load.network/upload/private \
  -H "Authorization: Bearer $load_acc_api_key" \
  -H "signed: true" \
  -H "bucket_name: $bucket_name" \
  -H "x-dataitem-name: $dataitem_name" \
  -H "x-folder-name": $folder_name" \ 
  -F "file=@path-signed-dataitem.ans104" \
  -F "content_type=application/octet-stream"

Upload a signed DataItem and store it in Load S3

Tags are extracted from the ANS-104 DataItem, indexed and queryable

curl -X POST https://load-s3-agent.load.network/upload \
  -H "Authorization: Bearer $load_acc_api_key" \
  -H "signed: true" \
  -F "file=@your-signed-dataitem.bin"

Post offchain DataItem to Arweave

example: for offchain dataitem = eoNAO-HlYasHJt3QFDuRrMVdLUxq5B8bXe4N_kboNWs

curl -X POST \
  "https://load-s3-agent.load.network/post/eoNAO-HlYasHJt3QFDuRrMVdLUxq5B8bXe4N_kboNWs" \
  -H "Authorization: Bearer REACH_OUT_TO_US" \
  -H "Content-Type: application/json"

Querying DataItems by Tags

all dataitems pushed after agent's v0.6.0 release are queryable by the dataitem's tags KVs:

curl -X POST https://load-s3-agent.load.network/tags/query \
  -H "Content-Type: application/json" \
  -d '{
    "filters": [
      {
        "key": "tag1",
        "value": "tag1"
      },
      {
        "key": "tag2",
        "value": "tag2"
      }
    ]
  }'

• Pagination follows Arweave's GQL schema: optional first (default 25, max 100) and a cursor after.

• full_metadata flag (Optional<bool>) to return the full tags associated with a query's dataitem

• owner / target filters are supported (can be used with or without filters)

• Tip: owner / target query support is available from agent v0.10.0

• each returned item includes dataitem_size (bytes) when available (v0.9.1 and onwards)

• created_after / created_before (ISO-8601/RFC3339 strings) filter items by their created_at timestamp (inclusive bounds).

curl -X POST https://load-s3-agent.load.network/tags/query \
  -H "Content-Type: application/json" \
  -d '{
    "filters": [
      {
        "key": "tag1",
        "value": "tag1"
      }
    ],
    "full_metadata": true,
    "owner": "2BBwe2pSXn_Tp-q_mHry0Obp88dc7L-eDIWx0_BUfD0",
    "target": null,
    "created_after": "2025-12-01T00:00:00Z",
    "created_before": "2025-12-05T00:00:00Z",
    "first": 25,
    "after": null
  }'

Owner-only query:

curl -X POST https://load-s3-agent.load.network/tags/query \
  -H "Content-Type: application/json" \
  -d '{
    "filters": [],
    "owner": "2BBwe2pSXn_Tp-q_mHry0Obp88dc7L-eDIWx0_BUfD0"
  }'

Owner + tags query:

curl -X POST https://load-s3-agent.load.network/tags/query \
  -H "Content-Type: application/json" \
  -d '{
    "filters": [
      {
        "key": "Content-Type",
        "value": "text/plain"
      }
    ],
    "owner": "2BBwe2pSXn_Tp-q_mHry0Obp88dc7L-eDIWx0_BUfD0",
    "full_metadata": true
  }'

if page_info.has_next_page returns true, reuse the page_info.next_cursor string as the next after.

count reflects the number of items returned in the current page, while total_count includes every dataitem that matches the filters across all pages.

Querying a DataItem by ID

Retrieve the latest indexed metadata (content type, size, tags, timestamps) for a single dataitem:

curl -X POST https://load-s3-agent.load.network/query/dataitem \
  -H "Content-Type: application/json" \
  -d '{
    "dataitem_id": "87uRZNA6YiaK0jhUMSBtspSCvmZnPPchkMkpXJzA4Gk"
  }'

Load S3 Agent library

Adding load-s3-agent library

[dependencies]
load-s3-agent = { git = "https://github.com/loadnetwork/lcp-uploader-api.git", branch = "main" }

Example

Codec helpers (owner/target derivation) are available under load_s3_agent::codec.

use load_s3_agent::create_dataitem;
use load_s3_agent::{get_dataitem_provenance_record, DataItemProvenanceRecord};

fn build_item() -> anyhow::Result<()> {
    // ensure UPLOADER_JWK is available in the environment (or .env)
    std::env::set_var("UPLOADER_JWK", include_str!("../wallet.json"));

    let item = create_dataitem(
        b"hello world".to_vec(),
        "text/plain",
        &[("My-Tag".into(), "tag-value".into())],
    )?;

    println!("Signed data item id: {}", item.id());
    Ok(())
}

use load_s3_agent::{codec::derive_owner_address, create_dataitem};

fn owner_from_item() -> anyhow::Result<()> {
    std::env::set_var("UPLOADER_JWK", include_str!("../wallet.json"));
    let item = create_dataitem(b"hello world".to_vec(), "text/plain", &[])?;
    let owner = derive_owner_address(&item).unwrap_or_default();
    println!("owner: {owner}");
    Ok(())
}

License

This agent is licensed under the MIT License