Proof Packages

A proof package is a shareable evidence bundle built from a vault: a frozen selection of files, optionally their signatures and on-chain proofs, a Proof of Attestation PDF and a machine-readable manifest — zipped and handed over through a token-protected link.

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

Creating one

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": "9b1d7c40-5e2a-4c33-9f10-77a0b3c4d5e6",
    "file_ids": ["c31f8a92-77bd-4a01-9d34-0b5e6f7a8b90"],
    "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

Returns 201 with 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. Capture it from the create response or the link is unusable.

Two statuses, not one

Building the bundle is asynchronous, so a package tracks its build and its link separately:

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 downloadable only when package_status is READY and status is ACTIVE. Expect PENDING immediately after creation, and poll before handing the link over.

Managing packages

Endpoint	Purpose
`GET /me/proof-packages`	List your packages (cursor pagination: `limit` 1–200, default 50)
`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

One package means one link, one token, one set of counters — there is no way to issue a second link for the same package. To share the same files on different terms, create another package.

What the recipient does

Redemption needs no Filedgr account; the link is the credential. Both routes live on the Explorer API, not the partner API:

GET  https://explorer-api.filedgr.network/proof-packages/{proof_package_id}
POST https://explorer-api.filedgr.network/proof-packages/{proof_package_id}/redeem

Fetching returns metadata only — file count, total size, both statuses, whether a password is required. Redeeming with the token (and password, if set) returns {proof_package_id, download_url, expires_in_seconds}, a presigned link valid for one hour.

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

Choosing between a package and publishing

A proof package is scoped to files you pick, expires, and can be download-limited. Publishing to the Explorer is open to everyone, indefinitely. Use a package for a named counterparty, and publishing when the record should be publicly checkable.

Full reference

Proof Packages — concepts and limits
Signatures — what include_signatures bundles up
API Reference

Creating one​

Two statuses, not one​

Managing packages​

What the recipient does​

Choosing between a package and publishing​

Full reference​