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.