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

# Versions and restore

> List, download, restore, and delete file versions, including the nested response format.

## Endpoints

| Operation | Endpoint | Capability |
| - | - | - |
| List versions | `GET /files/{fileId}/versions` | `file:read` |
| Download a version | `GET /files/{fileId}/versions/{versionId}/download` | `file:download` |
| Restore a version | `POST /files/{fileId}/versions/{versionId}/restore` | `file:restore` |
| Delete a version | `DELETE /files/{fileId}/versions/{versionId}` | `file:delete` |

All four require the file to be visible to the caller's company and permissions.

## List versions

```bash theme={null}
curl "https://api.everabyte.io/api/files/FILE_ID/versions" \
  -H "X-Public-Key: $EVB_PUBLIC_KEY" \
  -H "X-Secret-Key: $EVB_SECRET_KEY"
```

The response is nested: the controller wraps a service result, which itself has `status`, `message`, and `data`.

```json theme={null}
{
  "status": 200,
  "message": "Versions retrieved",
  "data": {
    "status": 200,
    "message": "Versions retrieved",
    "data": [
      {
        "id": "b3f1f8a4-2c0e-4f6a-9a11-8b7c6d5e4f30",
        "fileId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
        "versionId": "3HL4kqtJlcpXroDTDmJ+rmSpXd3dIbrHY+MTRCxf3vjVBH40Nr8X8gdRQBpUMLUo",
        "sizeByte": 482133,
        "createdAt": "2026-10-21T14:03:11.000Z",
        "isDeleted": false,
        "name": "contract",
        "extFile": "pdf",
        "action": "upload",
        "isCurrent": true
      }
    ],
    "maxVersions": 10
  }
}
```

Read `data.data` for the array. Each version includes:

| Field | Meaning |
| - | - |
| `id` | Version row identifier, or `current_<fileId>` for the synthesized live object |
| `versionId` | Storage version identifier used by restore, delete, and download |
| `sizeByte` | Version size |
| `createdAt` | Creation time |
| `isDeleted` | Soft-deleted flag |
| `name`, `extFile` | Display name at that version |
| `action` | What produced the version, such as `upload` |
| `isCurrent` | True for the live object |
| `authorName`, `authorEmail` | Present when resolvable |
| `maxVersions` | Plan cap, when resolvable |

The current live object is synthesized into the list because it has no separate version row. Use its `versionId`, not the synthetic `id`, when calling version endpoints.

> [!NOTE]
>
> A missing file does not produce an HTTP 404 here. The controller returns HTTP `200` with `data.status: 404` and an empty array. Check the inner status on list responses.

## Download a version

```bash theme={null}
curl -L "https://api.everabyte.io/api/files/FILE_ID/versions/VERSION_ID/download" \
  -H "X-Public-Key: $EVB_PUBLIC_KEY" \
  -H "X-Secret-Key: $EVB_SECRET_KEY" \
  --output ./old-version.bin
```

This is a binary stream with the same headers as a current-file download. Use it for audit and recovery, not for routine reads.

If the key envelope or user keys are incomplete, the request fails with a decryption error. That is a state problem, not a transient failure.

## Restore a version

```http theme={null}
POST /files/{fileId}/versions/{versionId}/restore
```

Optional body:

```json theme={null}
{
  "description": "Restored before audit",
  "changeReason": "customer request"
}
```

The request restores the selected version as the current object. Restoration promotes the version's stored encrypted content as it is; the platform does not decrypt or re-encrypt during a restore, and each version carries its own key envelope. Decryption is not part of a restore: to read the restored content you download it, and that download is the operation during which the content is decrypted. Restrictions:

* restoring the already-current version returns an inner `400`,
* a missing file or version returns an inner `404`,
* an incomplete key envelope returns an inner `400`,
* permission failures throw normal HTTP errors.

Like the list, the service result is nested. A successful response has an inner `200` and a message such as "Version restored".

## Delete a version

```http theme={null}
DELETE /files/{fileId}/versions/{versionId}
```

Deleting a version permanently removes that archived object. It cannot delete the current live version: that returns an inner `400` with the instruction to delete the file instead.

A missing file or version returns an inner `404`. Permission and ownership checks can throw normal HTTP errors.

> [!WARNING]
>
> Version deletion is permanent and is not the same as deleting a file. Deleting the current content belongs to the file delete flow.

## Version limits

The number of versions retained depends on the plan. `maxVersions` reports the cap when available. When a new version exceeds the cap, the platform retires older versions according to its retention policy.

Do not assume that every upload keeps an eternal history. If you need immutable long-term copies, use retention or store an independent copy.

## Recommended patterns

1. **Recovery UI** — list versions, show timestamps and sizes, and require confirmation before restore.
2. **Audit** — download the specific version and store its hash alongside the audit record.
3. **Cleanup** — never delete the current version through the version endpoint; use the file delete endpoints.
4. **Error handling** — decode the nested `data.status` before treating a response as a failure or success.

## Example: decode the nested result

```typescript theme={null}
async function listVersions(fileId: string) {
  const response = await fetch(
    `https://api.everabyte.io/api/files/${fileId}/versions`,
    {
      headers: {
        "X-Public-Key": process.env.EVB_PUBLIC_KEY!,
        "X-Secret-Key": process.env.EVB_SECRET_KEY!,
      },
    },
  );

  const outer = await response.json();
  if (!response.ok) {
    throw new Error(`HTTP ${response.status}: ${outer.code ?? outer.message}`);
  }

  if (outer.data.status !== 200) {
    throw new Error(`Version service: ${outer.data.status} ${outer.data.message}`);
  }

  return outer.data.data as Array<{ versionId: string; isCurrent: boolean }>;
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.