Skip to main content

Quick Start

This walks through a working integration end to end: authenticate, pick a template, create a vault and a stream, upload a file, and share it.

Prerequisites​

Step 1: Get API credentials​

API keys are issued from the web app: sign in, open your credentials, and generate an API key.

Copy the secret now

The plaintext secret is returned once, on that response, and is stored nowhere else. If you lose it, issue a new key — it cannot be recovered.

export FILEDGR_API="https://api.filedgr.network"
export FILEDGR_API_KEY="your-api-key"
export FILEDGR_API_SECRET="your-api-secret"

Other environments: https://api.test.filedgr.network, https://api.dev.filedgr.network. Credentials are per-environment and are not interchangeable.

Step 2: Verify authentication​

Every request carries both headers. There is no token exchange and no Authorization header.

curl "$FILEDGR_API/balances" \
  -H "x-api-key: $FILEDGR_API_KEY" -H "x-api-secret: $FILEDGR_API_SECRET"
{ "balance": 25.0, "created_at": "2026-01-10T09:00:00Z", "updated_at": "2026-01-15T08:12:00Z" }

A {"detail": "Not authenticated"} response means a header is missing or the secret is wrong.

warning

Server-to-server only: these headers are not in the CORS allowlist, so browser calls fail preflight.

Step 3: 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"

Returns {total_records, current_page, total_pages, content}, or 204 No Content if there are no results. Copy a content[].id — template ids are UUIDs.

Step 4: Create a vault (1 credit)​

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": "3f6c2b1e-9a4d-4f1b-8c77-1d2e3f4a5b6c",
    "name": "My First Vault",
    "description": "Testing the Filedgr API",
    "ledger": "XRPL"
  }'

Returns the vault with id, status: "FILEDGR_RECEIVED" and a progress array. Creation is asynchronous — poll GET /vaults/{id} until status is FILEDGR_VAULT_COMPLETED. A 402 means you are out of credits.

Step 5: Create a stream (1 credit)​

Data always lands in a stream inside a vault.

curl -X POST "$FILEDGR_API/vaults/$VAULT_ID/streams" \
  -H "x-api-key: $FILEDGR_API_KEY" -H "x-api-secret: $FILEDGR_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{ "mapping": "documents", "description": "Certificates", "required": true }'

Save the returned id as $STREAM_ID.

Step 6: Register a data attachment (1 credit)​

Uploads are three calls: register, PUT the bytes, then confirm.

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": "Quality certificate",
    "stream_id": "'"$STREAM_ID"'",
    "ledger": "XRPL",
    "estimated_size": 248311,
    "filename": "certificate.pdf"
  }'

The response carries the attachment id and a presigned_urls array. estimated_size is in bytes and must be greater than 0.

warning

The key holder needs an ETHEREUM WALLET credential — the attachment is notarised against it. Without one this returns 422 MissingWalletCredentialError. Complete wallet setup in the web app first.

Step 7: Upload the bytes, then confirm​

PUT each part to its link and keep the ETag the response returns:

ETAG=$(curl -s -X PUT --upload-file certificate.pdf -D - "$PART_1_LINK" \
        | grep -i '^etag:' | tr -d '\r' | cut -d' ' -f2)

Then close the upload — skip this and the attachment is never notarised:

curl -X PUT "$FILEDGR_API/attachments/$ATTACHMENT_ID" \
  -H "x-api-key: $FILEDGR_API_KEY" -H "x-api-secret: $FILEDGR_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '[{ "part": 1, "etag": '"$ETAG"' }]'

Poll GET /attachments/$ATTACHMENT_ID until status is FILEDGR_DATA_ATTACHMENT_COMPLETED. ERROR means it failed, and error_message says why.

Step 8: Share it​

Grant someone access to the vault:

curl -X POST "$FILEDGR_API/vaults/$VAULT_ID/permissions" \
  -H "x-api-key: $FILEDGR_API_KEY" -H "x-api-secret: $FILEDGR_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "credentials_key": "auditor@example.com",
    "credentials_type": "EMAIL",
    "vault_id": "'"$VAULT_ID"'",
    "type": "VIEWER",
    "action": "ADD",
    "network": "XRPL"
  }'

type is one of OWNER, ADMIN, EDITOR, VIEWER, CUSTOM. Revoking is action: "REMOVE", not a permission level.

Or produce a portable, verifiable evidence bundle with POST /proof-packages — see Proof Packages.

Next steps​