> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zkterm.io/llms.txt
> Use this file to discover all available pages before exploring further.

# zkStorage API

> API reference for encrypted file storage with ZK proofs

## Upload File

Upload an encrypted file to IPFS via Pinata with Groth16 ZK proof.

```bash theme={null}
POST /api/storage/upload
Content-Type: multipart/form-data
```

**Form Data:**

* `file`: File to upload (max 100MB)
* `proof`: Groth16 proof JSON
* `publicSignals`: Public signals array
* `commitment`: Password commitment hash
* `checksum`: SHA-256 file checksum

**Response:**

```json theme={null}
{
  "success": true,
  "id": "file_uuid",
  "cid": "QmXyz123abc456def789...",
  "filename": "document.pdf",
  "size": 1234567,
  "checksum": "sha256:abc123..."
}
```

***

## List Files

Get list of uploaded files for current user.

```bash theme={null}
GET /api/storage/list
```

**Response:**

```json theme={null}
{
  "success": true,
  "files": [
    {
      "id": "file_uuid",
      "cid": "QmXyz123...",
      "filename": "document.pdf",
      "size": 1234567,
      "createdAt": "2025-12-01T10:00:00Z",
      "checksum": "sha256:abc123..."
    }
  ]
}
```

***

## Download File

Download a file from IPFS.

```bash theme={null}
GET /api/storage/download/:cid
```

**Response:** Binary file data with headers:

```
Content-Type: application/octet-stream
Content-Disposition: attachment; filename="document.pdf"
```

***

## Delete File

Unpin a file from IPFS (removes from Pinata).

```bash theme={null}
DELETE /api/storage/:id
```

**Response:**

```json theme={null}
{
  "success": true,
  "deleted": true
}
```

***

## Create Share Link

Generate a shareable link for a file.

```bash theme={null}
POST /api/storage/share
```

**Request:**

```json theme={null}
{
  "fileId": "file_uuid",
  "expiresIn": 48
}
```

**Response:**

```json theme={null}
{
  "success": true,
  "shareToken": "abc123token",
  "shareUrl": "https://zkterm.io/share/abc123token",
  "expiresAt": "2025-12-03T10:00:00Z"
}
```

***

## Access Shared File

Access a file via share link.

```bash theme={null}
GET /api/storage/shared/:token
```

**Response:**

```json theme={null}
{
  "success": true,
  "file": {
    "cid": "QmXyz123...",
    "filename": "document.pdf",
    "size": 1234567
  }
}
```

***

## Verify ZK Proof

Verify Groth16 proof for a file.

```bash theme={null}
POST /api/storage/verify
```

**Request:**

```json theme={null}
{
  "proof": {
    "pi_a": [...],
    "pi_b": [...],
    "pi_c": [...]
  },
  "publicSignals": ["commitment_hash"],
  "commitment": "expected_commitment"
}
```

**Response:**

```json theme={null}
{
  "success": true,
  "valid": true
}
```

***

## Error Codes

| Code                | Description                   |
| ------------------- | ----------------------------- |
| `FILE_TOO_LARGE`    | File exceeds max size (100MB) |
| `INVALID_PROOF`     | ZK proof verification failed  |
| `CID_NOT_FOUND`     | File not found on IPFS        |
| `CHECKSUM_MISMATCH` | File integrity check failed   |
| `SHARE_EXPIRED`     | Share link has expired        |
| `PINATA_ERROR`      | Pinata API error              |