Container Snapshots

Container snapshots are point-in-time captures of a container’s filesystem and configuration. Use these endpoints to list, create, restore, rename, and delete snapshots for any container you own. Each container is subject to a snapshot limit that depends on the server it runs on — free-tier servers allow fewer snapshots than paid servers and rentals.

List snapshots

GET /api/v1/containers/{id}/snapshots

Returns every snapshot stored on the container, along with the snapshot count and the maximum allowed for the container’s current server.

Parameters

Name	In	Type	Required	Description
id	path	string	Yes	Unique identifier of the container to retrieve snapshots for

cURL

curl -X GET https://api.hoody.icu/api/v1/containers/507f1f77bcf86cd799439011/snapshots \
  -H "Authorization: Bearer <token>"

SDK

await client.api.containers.listSnapshotsIterator("507f1f77bcf86cd799439011")

Response 200

{
  "statusCode": 200,
  "message": "Snapshots retrieved successfully",
  "data": {
    "container_id": "507f1f77bcf86cd799439011",
    "project_id": "507f1f77bcf86cd799439033",
    "snapshot_count": 2,
    "max_snapshots": 10,
    "snapshots": [
      {
        "name": "snap-20250115-103000",
        "alias": "backup-2025-01-15",
        "created_at": "2025-01-15T10:30:00.000Z",
        "last_used_at": "2025-01-15T14:00:00.000Z",
        "expires_at": "2025-02-15T10:30:00.000Z",
        "stateful": false,
        "size": 2147483648
      },
      {
        "name": "snap-20250110-080000",
        "alias": "weekly-backup",
        "created_at": "2025-01-10T08:00:00.000Z",
        "last_used_at": null,
        "expires_at": null,
        "stateful": false,
        "size": 1073741824
      }
    ]
  }
}

Response 400

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Invalid container id format"
}

Response 401

{
  "statusCode": 401,
  "error": "Unauthorized",
  "message": "Authentication required"
}

Response 403

{
  "statusCode": 403,
  "error": "Forbidden",
  "message": "You do not have access to this container"
}

Response 404

{
  "statusCode": 404,
  "error": "Not Found",
  "message": "Container not found"
}

Response 500

{
  "statusCode": 500,
  "error": "Internal Server Error",
  "message": "Unexpected server error"
}

Create snapshot

POST /api/v1/containers/{id}/snapshots

Captures the current state of the container and registers a new snapshot. Optionally accepts a friendly alias and an expiry in days.

Parameters

Name	In	Type	Required	Description
id	path	string	Yes	Unique identifier of the container to create snapshot for

Request Body

Field	Type	Required	Description
alias	string	No	Optional user-friendly alias for the snapshot. Max length 100.
expiry	integer	No	Expiry in days (1–3650). Values outside this range are rejected before the snapshot is created.

cURL

curl -X POST https://api.hoody.icu/api/v1/containers/507f1f77bcf86cd799439011/snapshots \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "alias": "pre-deployment-backup",
    "expiry": 30
  }'

SDK

await client.api.containers.createSnapshot("507f1f77bcf86cd799439011", {
  alias: "pre-deployment-backup",
  expiry: 30
})

Response 200

{
  "statusCode": 200,
  "message": "Snapshot created successfully",
  "data": {
    "container_id": "507f1f77bcf86cd799439011",
    "project_id": "507f1f77bcf86cd799439033",
    "snapshot": {
      "name": "snap-20250115-145500",
      "alias": "pre-deployment-backup",
      "created_at": "2025-01-15T14:55:00.000Z",
      "last_used_at": null,
      "expires_at": "2025-02-14T14:55:00.000Z",
      "stateful": false,
      "size": 2147483648
    }
  }
}

Response 400

{
  "statusCode": 400,
  "error": "CONTAINER_SNAPSHOT_LIMIT",
  "message": "This container has reached its snapshot limit.",
  "data": {
    "field": "container_snapshot_limit",
    "container_id": "507f1f77bcf86cd799439011",
    "server_id": "507f1f77bcf86cd799439022",
    "current_count": 10,
    "limit": 10
  }
}

Error Code	Title	Description	Resolution
CONTAINER_SNAPSHOT_LIMIT	Container snapshot limit reached	The container already holds the maximum number of snapshots allowed for its server. Containers on free-tier servers are capped lower than those on paid servers and rentals; the applicable limit is returned as max_snapshots when listing snapshots.	Delete an existing snapshot on this container before creating a new one.
SNAPSHOT_PRESPAWN_FORBIDDEN	Snapshots not allowed on a prespawn container	A prespawn container is not yet bound to the server it will finally run on, so a snapshot taken now could not be counted against the limits that will apply to it.	Claim the container first, then create snapshots on the claimed container.
VALIDATION_ERROR	Invalid input parameters	One or more request parameters failed validation.	Check the error message for specific field requirements and correct your input.

Response 401

{
  "statusCode": 401,
  "error": "Unauthorized",
  "message": "Authentication required"
}

Response 403

{
  "statusCode": 403,
  "error": "Forbidden",
  "message": "You do not have access to this container"
}

Response 404

{
  "statusCode": 404,
  "error": "Not Found",
  "message": "Container not found"
}

Response 409

{
  "statusCode": 409,
  "error": "SNAPSHOT_OPERATION_IN_PROGRESS",
  "message": "Another snapshot operation may be running for this container, or the service is temporarily unavailable. Nothing was created; retry shortly."
}

Error Code	Title	Description	Resolution
SNAPSHOT_OPERATION_IN_PROGRESS	Snapshot creation already running	Another snapshot creation is already in flight for this container. Concurrent creations are rejected so the snapshot limit cannot be exceeded.	Retry after a few seconds (see the Retry-After header).
container_finalizing	Container is being finalized	The container is still being claimed and refuses changes until that completes.	Retry in a few seconds.

Response 500

{
  "statusCode": 500,
  "error": "Internal Server Error",
  "message": "Unexpected server error"
}

Response 503

{
  "statusCode": 503,
  "error": "SNAPSHOT_INVENTORY_UNAVAILABLE",
  "message": "Unable to verify this container's snapshot inventory. No changes were made.",
  "data": {
    "field": "container_snapshot_limit",
    "container_id": "507f1f77bcf86cd799439011",
    "server_id": "507f1f77bcf86cd799439022",
    "current_count": 10,
    "limit": 10
  }
}

Error Code	Title	Description	Resolution
SNAPSHOT_INVENTORY_UNAVAILABLE	Snapshot inventory could not be verified	The container’s live snapshot list could not be read, so the snapshot limit could not be checked. The request is refused rather than creating a snapshot that might exceed it.	Retry shortly. If it persists, contact support.

Restore snapshot

PUT /api/v1/containers/{id}/snapshots/{name}

Rolls the container back to the named snapshot. The container’s current state is replaced by the snapshot’s contents.

Parameters

Name	In	Type	Required	Description
id	path	string	Yes	Unique identifier of the container to restore
name	path	string	Yes	Name of the snapshot to restore

cURL

curl -X PUT https://api.hoody.icu/api/v1/containers/507f1f77bcf86cd799439011/snapshots/snap-20250115-103000 \
  -H "Authorization: Bearer <token>"

SDK

await client.api.containers.restoreSnapshot(
  "507f1f77bcf86cd799439011",
  "snap-20250115-103000"
)

Response 200

{
  "statusCode": 200,
  "message": "Container restored from snapshot successfully",
  "data": {
    "success": true,
    "message": "Container restored from snapshot successfully",
    "snapshot": {
      "name": "snap-20250115-103000",
      "alias": "backup-2025-01-15",
      "created_at": "2025-01-15T10:30:00.000Z",
      "last_used_at": "2025-01-15T15:00:00.000Z",
      "expires_at": "2025-02-15T10:30:00.000Z",
      "stateful": false,
      "size": 2147483648
    }
  }
}

Response 400

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Invalid container or snapshot name"
}

Response 401

{
  "statusCode": 401,
  "error": "Unauthorized",
  "message": "Authentication required"
}

Response 403

{
  "statusCode": 403,
  "error": "Forbidden",
  "message": "You do not have access to this container"
}

Response 404

{
  "statusCode": 404,
  "error": "Not Found",
  "message": "Snapshot not found"
}

Response 500

{
  "statusCode": 500,
  "error": "Internal Server Error",
  "message": "Unexpected server error"
}

Update snapshot alias

PUT /api/v1/containers/{id}/snapshots/{name}/alias

Renames the alias of an existing snapshot, or removes it by sending null.

Parameters

Name	In	Type	Required	Description
id	path	string	Yes	Unique identifier of the container
name	path	string	Yes	Name of the snapshot

Request Body

Field	Type	Required	Description
alias	string | null	Yes	New alias for the snapshot (set to null to remove alias). Max length 100.

cURL

curl -X PUT https://api.hoody.icu/api/v1/containers/507f1f77bcf86cd799439011/snapshots/snap-20250115-103000/alias \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "alias": "production-baseline"
  }'

SDK

await client.api.containers.updateSnapshotAlias(
  "507f1f77bcf86cd799439011",
  "snap-20250115-103000",
  { alias: "production-baseline" }
)

Response 200

{
  "statusCode": 200,
  "message": "Snapshot alias updated successfully",
  "data": {
    "container_id": "507f1f77bcf86cd799439011",
    "project_id": "507f1f77bcf86cd799439033",
    "snapshot": {
      "name": "snap-20250115-103000",
      "alias": "production-baseline",
      "created_at": "2025-01-15T10:30:00.000Z",
      "last_used_at": "2025-01-15T14:00:00.000Z",
      "expires_at": "2025-02-15T10:30:00.000Z",
      "stateful": false,
      "size": 2147483648
    }
  }
}

Response 400

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Invalid alias value"
}

Response 401

{
  "statusCode": 401,
  "error": "Unauthorized",
  "message": "Authentication required"
}

Response 403

{
  "statusCode": 403,
  "error": "Forbidden",
  "message": "You do not have access to this container"
}

Response 404

{
  "statusCode": 404,
  "error": "Not Found",
  "message": "Snapshot not found"
}

Response 500

{
  "statusCode": 500,
  "error": "Internal Server Error",
  "message": "Unexpected server error"
}

Response 503

{
  "statusCode": 503,
  "error": "SNAPSHOT_INVENTORY_UNAVAILABLE",
  "message": "Unable to verify this container's snapshot inventory. No changes were made.",
  "data": {
    "field": "container_snapshot_limit",
    "container_id": "507f1f77bcf86cd799439011",
    "server_id": "507f1f77bcf86cd799439022",
    "current_count": 10,
    "limit": 10
  }
}

Error Code	Title	Description	Resolution
SNAPSHOT_INVENTORY_UNAVAILABLE	Snapshot inventory could not be verified	The container’s live snapshot list could not be read, so the snapshot limit could not be checked. The request is refused rather than allowing a state that might exceed it.	Retry shortly. If it persists, contact support.

Delete snapshot

DELETE /api/v1/containers/{id}/snapshots/{name}

Permanently removes a snapshot from the container. This action cannot be undone.

Parameters

Name	In	Type	Required	Description
id	path	string	Yes	Unique identifier of the container
name	path	string	Yes	Name of the snapshot

cURL

curl -X DELETE https://api.hoody.icu/api/v1/containers/507f1f77bcf86cd799439011/snapshots/snap-20250110-080000 \
  -H "Authorization: Bearer <token>"

SDK

await client.api.containers.deleteSnapshot(
  "507f1f77bcf86cd799439011",
  "snap-20250110-080000"
)

Response 200

{
  "statusCode": 200,
  "message": "Snapshot deleted successfully",
  "data": {
    "container_id": "507f1f77bcf86cd799439011",
    "project_id": "507f1f77bcf86cd799439033",
    "snapshot_name": "snap-20250110-080000"
  }
}

Response 400

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Invalid container or snapshot name"
}

Response 401

{
  "statusCode": 401,
  "error": "Unauthorized",
  "message": "Authentication required"
}

Response 403

{
  "statusCode": 403,
  "error": "Forbidden",
  "message": "You do not have access to this container"
}

Response 404

{
  "statusCode": 404,
  "error": "Not Found",
  "message": "Snapshot not found"
}

Response 500

{
  "statusCode": 500,
  "error": "Internal Server Error",
  "message": "Unexpected server error"
}