Use Privatefile from your app or agent
Choose where your file lives, store it through the API, and keep signed evidence of its placement and deletion. Your account manages credit and API keys; file operations happen in your app or agent.
1. Create an API key and choose a placement
Create an operational API key in your account. For the full example below, choose Delete capable. Its permissions cover uploading, reading, receipts, and deletion. Copy the secret when it appears; it is shown once.
Use a narrower profile when your caller needs fewer permissions. Account management keys cannot store files.
Run the examples in Bash, with curl, jq, and openssl available. The key prompt hides your input. These commands create hello.txt in your current directory.
Set up the example
export PRIVATEFILE_API_URL=https://api.privatefile.sh
PLACEMENT=country:CH
REQUEST_ID="$(openssl rand -hex 12)"
read -r -s -p 'API key: ' PRIVATEFILE_API_KEY
printf '\n'
printf 'Hello, Privatefile!\n' > hello.txt
curl --fail-with-body --silent --show-error \
"$PRIVATEFILE_API_URL/v1/availability" | jq
Choose country:IS, country:CH, country:US, or zone:EU. The EU zone constrains storage to the European Union; it does not select an EU country.
Continue only when your chosen placement reports write_enabled: true. Check current availability. Credit and a price quote do not make an unavailable placement writable.
2. Review the maximum cost
Request a quote for this file and seven days of retention. A quote does not upload bytes or reserve credit.
Quote the upload
SIZE_BYTES="$(wc -c < hello.txt | tr -d '[:space:]')"
curl --fail-with-body --silent --show-error \
"$PRIVATEFILE_API_URL/v1/files/preflight" \
-H "Authorization: Bearer $PRIVATEFILE_API_KEY" \
-H 'Content-Type: application/json' \
--data "{\"placement\":\"$PLACEMENT\",\"size_bytes\":$SIZE_BYTES,\"retention\":\"7d\",\"encryption_mode\":\"privatefile_managed\",\"fallback\":\"deny\"}" \
> quote.json
jq '{maximum_cost_usd, currently_affordable, expires_at}' quote.json
Review maximum_cost_usd and check that currently_affordable is true before continuing. If needed, add prepaid credit. Quotes expire within ten minutes; request another if yours expires.
3. Upload and keep the file ID
This example uses Privatefile-managed encryption and an explicit placement with no fallback. The same inputs from the quote are sent with the file.
Store the file
PREFLIGHT_ID="$(jq -er '.preflight_id' quote.json)"
curl --fail-with-body --silent --show-error \
"$PRIVATEFILE_API_URL/v1/files" \
-H "Authorization: Bearer $PRIVATEFILE_API_KEY" \
-H "Idempotency-Key: hello-put-$REQUEST_ID" \
-F 'file=@hello.txt' \
-F "placement=$PLACEMENT" \
-F 'retention=7d' \
-F 'encryption_mode=privatefile_managed' \
-F 'fallback=deny' -F 'mode=real' \
-F "preflight_id=$PREFLIGHT_ID" \
> upload.json
FILE_ID="$(jq -er '.file_id' upload.json)"
jq '{file_id, residency_receipt}' upload.json
A successful upload returns file_id and a signed residency_receipt. Save the file ID in your own system, together with the original filename or record it belongs to. Privatefile does not retain that filename for you.
Use the same idempotency key when retrying the same upload with unchanged inputs. Use a new key for another operation. Files can be up to 1 GiB; retention is between 1 and 365 days.
4. Download and check the receipt
Use the returned file ID to download the bytes. The comparison below confirms that the downloaded example matches the original.
Read the file and its evidence
curl --fail-with-body --silent --show-error \
"$PRIVATEFILE_API_URL/v1/files/$FILE_ID" \
-H "Authorization: Bearer $PRIVATEFILE_API_KEY" \
--output "downloaded-$REQUEST_ID.txt"
cmp hello.txt "downloaded-$REQUEST_ID.txt"
curl --fail-with-body --silent --show-error \
"$PRIVATEFILE_API_URL/v1/files/$FILE_ID/receipt?type=residency" \
-H "Authorization: Bearer $PRIVATEFILE_API_KEY" | jq
Keep your API key in your secret manager. Send it to the API host in the authorization header, never in a URL.
5. Delete and verify the result
Deletion returns a signed receipt covering the primary and replica results. You can retrieve that receipt after the file has been deleted.
Delete the example
curl --fail-with-body --silent --show-error \
-X DELETE "$PRIVATEFILE_API_URL/v1/files/$FILE_ID" \
-H "Authorization: Bearer $PRIVATEFILE_API_KEY" \
-H "Idempotency-Key: hello-delete-$REQUEST_ID" | jq
curl --fail-with-body --silent --show-error \
"$PRIVATEFILE_API_URL/v1/files/$FILE_ID/receipt?type=deletion" \
-H "Authorization: Bearer $PRIVATEFILE_API_KEY" | jq
Retention expiry also triggers deletion. Keep the deletion receipt when your workflow needs evidence of the result.
API reference and agent clients
The complete OpenAPI specification describes request fields, response schemas, key scopes, receipts, pricing, and public errors.
OpenAPI specificationCurrent rate cardManage API keys
CLI and MCP use this same HTTP API. An MCP client follows get_availability, preflight_file, put_file, get_file, get_receipt, and delete_file. Give each agent a key with the permissions it needs.