# File Upload Server – Agent Guide

Upload a file, get back a download link. Base URL: `https://fordl.hiamnet.ir`

- No token or login needed.
- **Files are deleted automatically 60 minutes after upload.** Give the link to whoever needs it right away.
- Anyone with the link can download the file, so don't upload secrets.

## Upload (pick one)

### 1. curl multipart (most common)

```bash
curl -X POST https://fordl.hiamnet.ir/upload -F "file=@./report.pdf"
```

Multiple files: repeat `-F "file=@a.txt" -F "file=@b.txt"`.

### 2. Raw PUT (simplest, streams any size)

```bash
curl -T ./report.pdf https://fordl.hiamnet.ir/upload/report.pdf
```

### 3. Raw POST with name

```bash
curl -X POST "https://fordl.hiamnet.ir/upload?name=report.pdf" --data-binary @./report.pdf
```

### Python

```python
import requests
r = requests.post("https://fordl.hiamnet.ir/upload", files={"file": open("report.pdf", "rb")})
print(r.json()["url"])
```

### Node.js (18+)

```js
const form = new FormData();
form.append("file", new Blob([await fs.promises.readFile("report.pdf")]), "report.pdf");
const r = await fetch("https://fordl.hiamnet.ir/upload", { method: "POST", body: form });
console.log((await r.json()).url);
```

### PowerShell

```powershell
curl.exe -X POST https://fordl.hiamnet.ir/upload -F "file=@C:\path\report.pdf"
```

## Response (HTTP 201)

```json
{
  "id": "3f9a1c0e5b7d4a2c8e6f1b09",
  "name": "report.pdf",
  "size": 120394,
  "type": "application/pdf",
  "sha256": "…",
  "uploadedAt": 1767225600000,
  "expiresAt": 1767229200000,
  "url": "https://fordl.hiamnet.ir/f/3f9a1c0e5b7d4a2c8e6f1b09/report.pdf"
}
```

**Give the `url` field to the user/other agent.** That is the download link. Multiple files return `{"files": [ ... ]}`. `expiresAt` is a Unix timestamp in milliseconds.

## Download

```bash
curl -L -O -J "https://fordl.hiamnet.ir/f/<id>/<name>"
```

Supports `Range` requests. Add `?inline=1` to view in a browser instead of downloading.

## List all current files

```bash
curl https://fordl.hiamnet.ir/api/files
```

Returns `{"files": [...]}` (newest first), each with `name`, `size`, `expiresAt` and `url`. Also shown on the web page at `https://fordl.hiamnet.ir/`.

## Delete early (optional)

```bash
curl -X DELETE https://fordl.hiamnet.ir/f/<id>
```

## Errors

| Code | Meaning |
|---|---|
| 400 | Bad request (no file, missing filename) |
| 404 | File not found or expired |
| 413 | File too large |

Errors are JSON: `{"error": "message"}`.

## Rules for agents

1. Upload only the files you were asked to share. Never upload secrets, keys or `.env` files.
2. Always report the returned `url` (and file name/size) in your final answer, and mention it expires in 60 minutes.
3. If the link expired, just upload the file again.
4. Delete files you uploaded by mistake.
5. Verify integrity if needed: compare `sha256` in the response with `sha256sum <file>`.
6. This guide is always available at `https://fordl.hiamnet.ir/guide` (HTML) and `https://fordl.hiamnet.ir/guide.md` (Markdown).
