Skip to main content

Quick Start Guide

This walks through creating a vault from a template, adding a stream, and uploading a file to it.

Prerequisites​

  • A Filedgr account
  • An API key and secret — see API Keys
export FILEDGR_API=https://api.filedgr.network
export FILEDGR_API_KEY=<your-key>
export FILEDGR_API_SECRET=<your-secret>

All examples below assume these headers:

-H "x-api-key: $FILEDGR_API_KEY" -H "x-api-secret: $FILEDGR_API_SECRET"

1. Pick a template​

curl "$FILEDGR_API/templates?public=true&page=1&page_size=10" \
  -H "x-api-key: $FILEDGR_API_KEY" -H "x-api-secret: $FILEDGR_API_SECRET"

Supports search_term, sort_by and sort_type. Remember that an empty result is a 204, not an empty page.

2. Create a vault​

curl -X POST "$FILEDGR_API/vaults" \
  -H "x-api-key: $FILEDGR_API_KEY" -H "x-api-secret: $FILEDGR_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "template_id": "<template-uuid>",
    "name": "Delivery 2026-08-26",
    "description": "Batch shipment record",
    "ledger": "XRPL"
  }'

Vault creation is asynchronous and consumes credits — a 402 means you are out. Poll GET /vaults/{vault_id} and watch status and progress until it reaches FILEDGR_VAULT_COMPLETED.

3. Add a stream​

Streams are created within a vault, because the vault is what pays for them:

curl -X POST "$FILEDGR_API/vaults/<vault-uuid>/streams" \
  -H "x-api-key: $FILEDGR_API_KEY" -H "x-api-secret: $FILEDGR_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"mapping": "sensor-data", "description": "Temperature readings", "required": true}'
note

There is no POST /streams. Templates with required_streams create their streams automatically when the vault is built.

4. Upload a data attachment​

Create the attachment to receive presigned upload URLs:

curl -X POST "$FILEDGR_API/attachments" \
  -H "x-api-key: $FILEDGR_API_KEY" -H "x-api-secret: $FILEDGR_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "readings.csv",
    "description": "Morning batch",
    "stream_id": "<stream-uuid>",
    "ledger": "XRPL",
    "filename": "readings.csv",
    "estimated_size": 20480
  }'

name, stream_id, ledger and estimated_size are required, and estimated_size must be greater than zero. When filename is given it must end in a 2–4 letter extension.

note

The key holder needs an Ethereum wallet credential on their account, or this returns 422 MissingWalletCredentialError — the wallet is what the file is notarised against.

The response carries presigned_urls, a list of {part, link} objects. What you do next depends on the size, and the threshold is 150 MB.

Attachments of 150 MB or less​

You get a single entry with part: 1. PUT the whole file to its link and you are done — ingestion starts automatically from the storage event.

curl -X PUT "<link-from-presigned_urls>" --upload-file readings.csv
warning

Do not call PUT /attachments/{id} for a single-part upload. No multipart upload exists to finalise, and the call will fail.

Attachments over 150 MB​

The file is split into 150 MB parts, one entry per part. Upload each part to its link, keep the ETag each response returns, then finalise:

curl -X PUT "$FILEDGR_API/attachments/<attachment-uuid>" \
  -H "x-api-key: $FILEDGR_API_KEY" -H "x-api-secret: $FILEDGR_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '[{"part": 1, "etag": "\"abc...\""}, {"part": 2, "etag": "\"def...\""}]'

The body is a bare JSON array, not an object. Each element carries exactly one of link or etag — send etag. Until this call succeeds the attachment stays in its uploading state and is never notarised.

Re-posting the same attachment returns already-completed parts and re-presigns only the outstanding ones, so an interrupted upload can be resumed.

5. Watch for completion​

Poll GET /attachments/{id}, or register a webhook for data_attachment.completed and let Filedgr call you instead.

Next Steps​