Snapshots

Snapshots allow you to create a read-only archive of files at a specific point in time. You can define a snapshot, add files to it, and then finalize it. Once finalized, the snapshot’s contents are immutable.

Each snapshot may have an expiration date. When the expiration date is reached, the snapshot is automatically deleted from the Files.com platform.

List Snapshots

Endpoint

GET/snapshots

Return Object

Snapshot[]

Authorization Requirement

Available to all authenticated keys or sessions.

Additional Arguments

Example Request

curl https://app.files.com/api/rest/v1/snapshots.json \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

Example Response

[
  {
    "id": 1,
    "expires_at": "2000-01-01T01:00:00Z",
    "finalized_at": "2000-01-01T01:00:00Z",
    "name": "My Snapshot",
    "user_id": 1,
    "bundle_id": 1,
    "workspace_id": 1
  }
]

Show Snapshot

Endpoint

GET/snapshots/{id}

Return Object

Snapshot

Authorization Requirement

Available to all authenticated keys or sessions.

Request Parameters

ParameterDescription
id
int64
Required		Snapshot ID.

Example Request

curl https://app.files.com/api/rest/v1/snapshots/{id}.json \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

Example Response

{
  "id": 1,
  "expires_at": "2000-01-01T01:00:00Z",
  "finalized_at": "2000-01-01T01:00:00Z",
  "name": "My Snapshot",
  "user_id": 1,
  "bundle_id": 1,
  "workspace_id": 1
}

Create Snapshot

Endpoint

POST/snapshots

Return Object

Snapshot

Authorization Requirement

Available to all authenticated keys or sessions.

Request Parameters

ParameterDefaultDescription
expires_at
string		When the snapshot expires.
name
string		A name for the snapshot.
paths
array(string)		An array of paths to add to the snapshot.
workspace_id
int64		0Workspace ID. 0 means the default workspace.

Example Request

curl https://app.files.com/api/rest/v1/snapshots.json \
  -X POST \
  -H 'Content-Type: application/json' \
  -d '{"expires_at":"2000-01-01T01:00:00Z","name":"My Snapshot","workspace_id":0}' \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

Example Response

{
  "id": 1,
  "expires_at": "2000-01-01T01:00:00Z",
  "finalized_at": "2000-01-01T01:00:00Z",
  "name": "My Snapshot",
  "user_id": 1,
  "bundle_id": 1,
  "workspace_id": 1
}

Finalize Snapshot

Endpoint

POST/snapshots/{id}/finalize

Return Object

No return value.

Authorization Requirement

Available to all authenticated keys or sessions.

Request Parameters

ParameterDescription
id
int64
Required		Snapshot ID.

Example Request

curl https://app.files.com/api/rest/v1/snapshots/{id}/finalize.json \
  -X POST \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

Update Snapshot

Endpoint

PATCH/snapshots/{id}

Return Object

Snapshot

Authorization Requirement

Available to all authenticated keys or sessions.

Request Parameters

ParameterDescription
id
int64
Required		Snapshot ID.
expires_at
string		When the snapshot expires.
name
string		A name for the snapshot.
paths
array(string)		An array of paths to add to the snapshot.

Example Request

curl https://app.files.com/api/rest/v1/snapshots/{id}.json \
  -X PATCH \
  -H 'Content-Type: application/json' \
  -d '{"expires_at":"2000-01-01T01:00:00Z","name":"My Snapshot"}' \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

Example Response

{
  "id": 1,
  "expires_at": "2000-01-01T01:00:00Z",
  "finalized_at": "2000-01-01T01:00:00Z",
  "name": "My Snapshot",
  "user_id": 1,
  "bundle_id": 1,
  "workspace_id": 1
}

Delete Snapshot

Endpoint

DELETE/snapshots/{id}

Return Object

No return value.

Authorization Requirement

Available to all authenticated keys or sessions.

Request Parameters

ParameterDescription
id
int64
Required		Snapshot ID.

Example Request

curl https://app.files.com/api/rest/v1/snapshots/{id}.json \
  -X DELETE \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

The Snapshot Object

Some of the endpoints above return a Snapshot object. The attributes of this object are listed below.

AttributeDescription
id
int64		The snapshot's unique ID.
expires_at
date-time		When the snapshot expires.
finalized_at
date-time		When the snapshot was finalized.
name
string		A name for the snapshot.
user_id
int64		The user that created this snapshot, if applicable.
bundle_id
int64		The bundle using this snapshot, if applicable.
workspace_id
int64		Workspace ID. 0 means the default workspace.

Example Snapshot Object

{
  "id": 1,
  "expires_at": "2000-01-01T01:00:00Z",
  "finalized_at": "2000-01-01T01:00:00Z",
  "name": "My Snapshot",
  "user_id": 1,
  "bundle_id": 1,
  "workspace_id": 1
}