# DurableFile

DurableFile hosts public files for agents and automation.
It returns one live, content-addressed download URL.

## Contract

- Storage costs $1 per 1 GiB. Purchases are one-time and stack.
- A new account has zero quota. There is no free upload tier.
- An account needs no email, password, CAPTCHA, or dashboard.
- Files are public. Do not upload secrets or sensitive personal data.
- The file limit is 25 MiB.
- Accepted files: PDF, UTF-8 plain text, Markdown, CSV, and valid JSON.
- Direct images return HTTP 415. Upload images to https://imgd.dev.

## Start

1. Create an account.

   curl -X POST https://durablefile.com/v1/accounts

Save the returned API key. The service shows it once.

2. Buy storage.

   curl -X POST https://durablefile.com/v1/credit \
     -H "Authorization: Bearer $DURABLEFILE_KEY" \
     -H "Content-Type: application/json" \
     -d '{"gb":1}'

The response has a Stripe checkout URL for a person.
It also has usevig payment options when usevig is configured.

3. Upload a file.

   curl -X POST https://durablefile.com/v1/upload \
     -H "Authorization: Bearer $DURABLEFILE_KEY" \
     -F "file=@report.pdf"

For raw bytes, set Content-Type and X-Filename.
You can also set the filename query parameter.

## Lifecycle

Omit expiry fields for no automatic expiry.
Set unpublish_after_hours or unpublish_at, but never both.
The maximum window is 8,760 hours.
Expiry and manual unpublish retain the bytes and quota use.
POST /v1/files/:hash/publish restores the same URL.
DELETE /v1/files/:hash frees the caller's quota.
The global object stays while another account has a claim.

## Endpoints

POST   /v1/accounts
GET    /v1/me
POST   /v1/credit
POST   /v1/upload
GET    /v1/files
GET    /v1/files/:hash
POST   /v1/files/:hash/publish
POST   /v1/files/:hash/unpublish
DELETE /v1/files/:hash
GET    /f/:hash/:filename
GET    /health
GET    /openapi.json
GET    /evaluate.md
GET    /integrate.md

Every actionable 4xx response has an exact fix field.