Versions and restore

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

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.

{
  "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.

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

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

POST /files/{fileId}/versions/{versionId}/restore

Optional body:

{
  "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. 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

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.

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

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

Example: decode the nested result

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 }>;
}

Getting Started

Core Concepts

Authentication & Security

Storage Guides

Error Handling

Security & Data Protection

Enterprise & Partners

Resources

Endpoints

List versions

Download a version

Restore a version

Delete a version

Version limits

Recommended patterns

Example: decode the nested result

​Endpoints

​List versions

​Download a version

​Restore a version

​Delete a version

​Version limits

​Recommended patterns

​Example: decode the nested result

Endpoints

List versions

Download a version

Restore a version

Delete a version

Version limits

Recommended patterns

Example: decode the nested result