# DataStore API

Store JSON or files for AI agents. No account, no API key. Every paid call is
$0.01 USDC on base via the x402 protocol (HTTP 402).
Use an x402 client (for example @x402/fetch for TypeScript, or the x402 Python
package) with a wallet that holds USDC, and every 402 is handled for you.

## Prices and limits
- Upload (JSON or file, up to 26214400 bytes, kept 1 to 365 days, includes 100 reads): $0.01
- Extend expiry (up to 365 days from now): $0.01
- 1000 extra reads for one item: $0.01
- Everything else is free. Early delete gives no refund.
- Allowed content: application/json, text/html, image/svg+xml, text/plain, text/markdown, text/csv, application/pdf, image/png, image/jpeg, image/webp, image/gif. Type is detected from the content.

## Store
POST https://fileshareforagents.online/v1/items?ttl_days=7&label=my-result
Body: the raw content. Content-Type is optional.
Response 201: {"id","secret","expires_at","reads_remaining","links":{...}}
Keep the secret. It is shown once and cannot be recovered.

## Retrieve
GET https://fileshareforagents.online/v1/items/{id}
Authorization: Bearer {secret}
JSON comes back inline; files come back as attachments. Each read counts.
When reads run out you get 402; paying on the same request adds 1000 reads and returns the content.

## Status (free, does not count as a read)
GET https://fileshareforagents.online/v1/items/{id}/status  (Bearer secret)

## Extend
POST https://fileshareforagents.online/v1/items/{id}/extend  (Bearer secret)  {"ttl_days": 30}

## Buy reads in advance (no secret needed; do this before sharing with a human)
POST https://fileshareforagents.online/v1/items/{id}/reads

## Delete
DELETE https://fileshareforagents.online/v1/items/{id}  (Bearer secret)

## Share with a human or another agent (free)
Two ways, both without giving away the secret:
1. Signed link: POST https://fileshareforagents.online/v1/items/{id}/links  (Bearer secret)  {"expires_in": 3600}
   Response: {"url","expires_at"}. Anyone with the URL reads the item until it expires (each open
   counts one read). The URL is the credential: it bypasses any password, so send it only to the
   intended reader. Revoke all links issued so far: POST https://fileshareforagents.online/v1/items/{id}/links/revoke.
2. Password: PUT https://fileshareforagents.online/v1/items/{id}/password  (Bearer secret)  {"password": "12 to 128 chars"}
   Then the item's public address (links.public in every item response, on the share domain)
   serves it to anyone who has the password: browsers get a form, agents send an x-password
   header. Send the address and the password over different channels. Remove with
   DELETE https://fileshareforagents.online/v1/items/{id}/password; without a password the public address answers 404.
Buy reads first (above) if many people will open the item: the included 100 reads run out.

## Errors
Every error is JSON with "error", "message", "action" (what to do next, with a URL),
"request_id" and "feedback". 404 covers not found, expired and wrong credentials alike.

## Tools
https://fileshareforagents.online/tools.json has function-calling definitions. https://fileshareforagents.online/openapi.json is the full spec.
MCP: npx -y fileshareforagents-mcp (env WALLET_KEY, FILESHARE_NETWORK=testnet|mainnet) exposes
every operation above as MCP tools and pays automatically. https://www.npmjs.com/package/fileshareforagents-mcp
Missing something? POST https://fileshareforagents.online/v1/feedback {"type":"missing","message":"..."}
Terms: https://fileshareforagents.online/terms