Proof Packages

A proof package is a compliance-grade evidence bundle assembled from a vault: a frozen selection of files, optionally their signatures and on-chain proofs, a branded Proof of Attestation PDF and a machine-readable manifest, zipped and shared through a token-protected link.

Use it when someone outside Filedgr — an auditor, a regulator, a customer — needs verifiable evidence about specific files without being given access to the vault.

Packages and links

A proof package is its share link — one package, one token, one set of counters. Creating a package produces exactly one shareable link; there is no way to issue a second link for the same package. To share the same files on different terms, create another package.

A package therefore carries both the bundle (which files, whether signatures are included, how big it is) and the link's terms (expiry, optional password, optional download cap, view and download counters). Building the bundle is asynchronous, so two independent status fields track it:

Field	Values	Meaning
package_status	PENDING READY FAILED	Has the bundle finished building
status	ACTIVE USED EXPIRED REVOKED	Is the link still usable

A package is only downloadable when package_status is READY and status is ACTIVE.

Creating a package

curl -X POST https://api.filedgr.network/proof-packages \
  -H "x-api-key: $FILEDGR_API_KEY" \
  -H "x-api-secret: $FILEDGR_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "vault_id": "<uuid>",
    "file_ids": ["<uuid>", "<uuid>"],
    "include_signatures": true,
    "expires_in_days": 7,
    "download_limit": 1,
    "password": "optional-passphrase"
  }'

Field	Required	Notes
vault_id	yes	The vault the files belong to
file_ids	yes	1 to 1000 file ids. Selection is per file, not per attachment
include_signatures	no	Defaults to true
expires_in_days	no	Defaults to 7. Maximum 90
download_limit	no	null = unlimited, 1 = single use, N = capped
password	no	Only its hash is stored

The response is a 201 containing proof_package_id, share_url and a token.

danger

The token is returned exactly once, at creation. Only a hash of it is stored, so it cannot be recovered afterwards. Capture it from the create response or the link becomes unusable.

Building is asynchronous — expect package_status: "PENDING" immediately after creation, and poll until it becomes READY.

Managing your packages

Endpoint	Purpose
GET /me/proof-packages	List your packages (cursor paginated: limit, cursor)
GET /me/proof-packages/{id}	Detail for one package
POST /me/proof-packages/{id}/extend	Push the expiry out, up to 90 days
POST /me/proof-packages/{id}/download	Owner download, no token required

What the recipient does

Redemption is a public, two-step flow that needs no Filedgr account — the link is the credential.

1. Landing. Fetching the package returns metadata only: file count, total size, both statuses, whether a password is required, and per-file summaries. It never exposes the token, the password or storage internals.
2. Redeem. Presenting the token — plus the password when one is set — returns a short-lived download_url and expires_in_seconds.

These two routes live on the Explorer API, not the partner API. They are unauthenticated by design and are not reachable at api.filedgr.network:

GET  /proof-packages/{proof_package_id}          landing metadata (public)
POST /proof-packages/{proof_package_id}/redeem   body: {"token": "...", "password": "..."}

Redeem returns {proof_package_id, download_url, expires_in_seconds}; the download URL is a presigned link valid for one hour.

Each redemption increments the link's download counter and, once download_limit is reached, the link moves to USED and stops working.

Limits

Limit	Value
Files per package	1000
Maximum expiry	90 days
Cursor page size	1–200 (default 50)

Security model

• Only sha256(token) and, when set, sha256(password) are stored.
• The token is returned once and never again.
• Landing responses are served with Cache-Control: no-store, because view and download counters change on access.
• Download URLs are short-lived and expire independently of the link.