> For the complete documentation index, see [llms.txt](https://docs.cedana.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.cedana.ai/references/api/checkpoints.md).

# Checkpoints

Cedana API for checkpoints

## List checkpoints

> Paginated. \`ids\` (comma-separated UUIDs) and \`cluster\_id\` (the cluster the checkpoint action\
> ran on) filter the list; \`total\_count\` is the number of matches before paging.

```json
{"openapi":"3.1.0","info":{"title":"Cedana API","version":"0.0.0-dev"},"tags":[{"description":"Cedana API for checkpoints","name":"Checkpoints"}],"security":[{"Token":[]}],"components":{"securitySchemes":{"Token":{"scheme":"bearer","type":"http"}},"schemas":{"PaginatedCheckpointResponse":{"properties":{"checkpoints":{"items":{"$ref":"#/components/schemas/Checkpoint"},"type":"array"},"total_count":{"format":"int64","type":"integer"}},"required":["checkpoints","total_count"],"type":"object"},"Checkpoint":{"description":"Checkpoint is basic unit for cedana service operation\nit stores all the information regarding the snapshot we can use to save and then restore state","properties":{"checksum":{"type":["string","null"]},"delta":{"description":"Whether this checkpoint is a (GPU delta) increment. Authoritative even\nwhen parent_checkpoint_id is null (malformed id at ingest, parent deleted)","type":"boolean"},"gpu":{"type":"string"},"id":{"format":"uuid","type":"string"},"info":{},"name":{"type":["string","null"]},"parent_checkpoint_id":{"description":"Checkpoint this one is an increment of; null for full checkpoints and\nfor deltas whose parent is unknown or deleted","format":"uuid","type":["string","null"]},"platform":{"type":"string"},"status":{"$ref":"#/components/schemas/CheckpointStatus"}},"required":["id","status","gpu","platform","delta"],"type":"object"},"CheckpointStatus":{"enum":["initializing","updated_info","possibly_uploaded","ready","deprecated"],"type":"string"},"HttpError":{"description":"Standard JSON error body for all 4xx/5xx responses.\n\nHandlers return plain-text errors internally; [`normalize_error_response`]\nconverts anything the stack produces (handlers, extractors, the auth layer)\nto this shape, so generated SDK clients can rely on a single error schema.","properties":{"message":{"description":"Human-readable description of what went wrong","type":"string"}},"required":["message"],"type":"object"}}},"paths":{"/v1/checkpoints":{"get":{"description":"Paginated. `ids` (comma-separated UUIDs) and `cluster_id` (the cluster the checkpoint action\nran on) filter the list; `total_count` is the number of matches before paging.","operationId":"list","parameters":[{"description":"Comma-separated list of checkpoint UUIDs to filter by","in":"query","name":"ids","required":false,"schema":{"type":["string","null"]}},{"description":"Only return checkpoints whose checkpoint action ran on this cluster","in":"query","name":"cluster_id","required":false,"schema":{"format":"uuid","type":["string","null"]}},{"description":"Page size (default 50, max 500)","in":"query","name":"limit","required":false,"schema":{"format":"int64","type":["integer","null"]}},{"description":"Row offset (default 0)","in":"query","name":"offset","required":false,"schema":{"format":"int64","type":["integer","null"]}},{"description":"Sort column: `id`, `name`, `status`, `platform` or `gpu` (default `id`)","in":"query","name":"sort","required":false,"schema":{"type":["string","null"]}},{"description":"Sort ascending (default false)","in":"query","name":"ascending","required":false,"schema":{"type":["boolean","null"]}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedCheckpointResponse"}}},"description":"Returns checkpoints with total count"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}},"description":"Invalid query parameters"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}},"description":"Failed to connect/fetch from database"},"4XX":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}},"description":"Client error"},"5XX":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}},"description":"Server error"}},"summary":"List checkpoints","tags":["Checkpoints"]}}}}
```

## Create checkpoint

> Builds a new checkpoint without the metadata and information about the checkpoint with status initializing

```json
{"openapi":"3.1.0","info":{"title":"Cedana API","version":"0.0.0-dev"},"tags":[{"description":"Cedana API for checkpoints","name":"Checkpoints"}],"security":[{"Token":[]}],"components":{"securitySchemes":{"Token":{"scheme":"bearer","type":"http"}},"schemas":{"HttpError":{"description":"Standard JSON error body for all 4xx/5xx responses.\n\nHandlers return plain-text errors internally; [`normalize_error_response`]\nconverts anything the stack produces (handlers, extractors, the auth layer)\nto this shape, so generated SDK clients can rely on a single error schema.","properties":{"message":{"description":"Human-readable description of what went wrong","type":"string"}},"required":["message"],"type":"object"}}},"paths":{"/v1/checkpoints":{"post":{"description":"Builds a new checkpoint without the metadata and information about the checkpoint with status initializing","operationId":"add","responses":{"200":{"content":{"text/plain":{"schema":{"type":"string"}}},"description":"Returns the checkpoint ID for the new checkpoint"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}},"description":"Failed to create checkpoint in database"},"4XX":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}},"description":"Client error"},"5XX":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}},"description":"Server error"}},"summary":"Create checkpoint","tags":["Checkpoints"]}}}}
```

## Deprecate checkpoint

> Has a helper on the checkpoint's cluster delete its files (chosen as for the files\
> endpoints: any helper for a remote checkpoint, the node holding it for a local one),\
> then marks the checkpoint deprecated. A checkpoint without a path has no files to\
> delete and is just deprecated. One with files but no cluster to ask (not taken\
> through a checkpoint action) is kept, with a 409, rather than deprecated with its\
> files left behind. If the helper fails to delete, the checkpoint is left as it was\
> and the helper's error is returned. Concurrent requests for the same checkpoint may\
> both ask for the delete; whichever marks it deprecated first wins, the other gets 404.

```json
{"openapi":"3.1.0","info":{"title":"Cedana API","version":"0.0.0-dev"},"tags":[{"description":"Cedana API for checkpoints","name":"Checkpoints"}],"security":[{"Token":[]}],"components":{"securitySchemes":{"Token":{"scheme":"bearer","type":"http"}},"schemas":{"HttpError":{"description":"Standard JSON error body for all 4xx/5xx responses.\n\nHandlers return plain-text errors internally; [`normalize_error_response`]\nconverts anything the stack produces (handlers, extractors, the auth layer)\nto this shape, so generated SDK clients can rely on a single error schema.","properties":{"message":{"description":"Human-readable description of what went wrong","type":"string"}},"required":["message"],"type":"object"}}},"paths":{"/v1/checkpoints/deprecate/{id}":{"patch":{"description":"Has a helper on the checkpoint's cluster delete its files (chosen as for the files\nendpoints: any helper for a remote checkpoint, the node holding it for a local one),\nthen marks the checkpoint deprecated. A checkpoint without a path has no files to\ndelete and is just deprecated. One with files but no cluster to ask (not taken\nthrough a checkpoint action) is kept, with a 409, rather than deprecated with its\nfiles left behind. If the helper fails to delete, the checkpoint is left as it was\nand the helper's error is returned. Concurrent requests for the same checkpoint may\nboth ask for the delete; whichever marks it deprecated first wins, the other gets 404.","operationId":"deprecate","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"text/plain":{"schema":{"type":"string"}}},"description":"Successfully deprecated checkpoint and returns id"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}},"description":"Invalid UUID provided"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}},"description":"Checkpoint not found or already deprecated"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}},"description":"Checkpoint has files but no cluster to delete them from"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}},"description":"Database operation failed"},"502":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}},"description":"Helper could not delete the checkpoint"},"504":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}},"description":"No helper on the cluster answered in time"},"4XX":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}},"description":"Client error"},"5XX":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}},"description":"Server error"}},"summary":"Deprecate checkpoint","tags":["Checkpoints"]}}}}
```

## Put checkpoint info

> Add information about the checkpoint

```json
{"openapi":"3.1.0","info":{"title":"Cedana API","version":"0.0.0-dev"},"tags":[{"description":"Cedana API for checkpoints","name":"Checkpoints"}],"security":[{"Token":[]}],"components":{"securitySchemes":{"Token":{"scheme":"bearer","type":"http"}},"schemas":{"CheckpointInfo":{"properties":{"gpu":{"type":"string"},"info":{},"platform":{"type":"string"}},"required":["gpu","platform"],"type":"object"},"HttpError":{"description":"Standard JSON error body for all 4xx/5xx responses.\n\nHandlers return plain-text errors internally; [`normalize_error_response`]\nconverts anything the stack produces (handlers, extractors, the auth layer)\nto this shape, so generated SDK clients can rely on a single error schema.","properties":{"message":{"description":"Human-readable description of what went wrong","type":"string"}},"required":["message"],"type":"object"}}},"paths":{"/v1/checkpoints/info/{id}":{"put":{"description":"Add information about the checkpoint","operationId":"update_info","parameters":[{"in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckpointInfo"}}},"required":true},"responses":{"200":{"content":{"text/plain":{"schema":{"type":"string"}}},"description":"Successfully updated checkpoint info and returns ID"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}},"description":"Failed to execute request against database"},"4XX":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}},"description":"Client error"},"5XX":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}},"description":"Server error"}},"summary":"Put checkpoint info","tags":["Checkpoints"]}}}}
```

## Uploaded checkpoint

> Marks checkpoint as successfully uploaded and ready for restore

```json
{"openapi":"3.1.0","info":{"title":"Cedana API","version":"0.0.0-dev"},"tags":[{"description":"Cedana API for checkpoints","name":"Checkpoints"}],"security":[{"Token":[]}],"components":{"securitySchemes":{"Token":{"scheme":"bearer","type":"http"}},"schemas":{"CheckpointSuccessInfo":{"properties":{"restore_path":{"type":["string","null"]}},"type":"object"},"HttpError":{"description":"Standard JSON error body for all 4xx/5xx responses.\n\nHandlers return plain-text errors internally; [`normalize_error_response`]\nconverts anything the stack produces (handlers, extractors, the auth layer)\nto this shape, so generated SDK clients can rely on a single error schema.","properties":{"message":{"description":"Human-readable description of what went wrong","type":"string"}},"required":["message"],"type":"object"}}},"paths":{"/v1/checkpoints/uploaded/{id}":{"post":{"description":"Marks checkpoint as successfully uploaded and ready for restore","operationId":"uploaded","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckpointSuccessInfo"}}},"required":true},"responses":{"200":{"content":{"text/plain":{"schema":{"type":"string"}}},"description":"Marks the checkpoint as successfully uploaded"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}},"description":"Invalid request parameters"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}},"description":"Failed to update checkpoint in database"},"4XX":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}},"description":"Client error"},"5XX":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}},"description":"Server error"}},"summary":"Uploaded checkpoint","tags":["Checkpoints"]}}}}
```

## List checkpoint files

> Asks a helper on the checkpoint's cluster to read the checkpoint and returns the files\
> inside it (the members of the checkpoint archive).

```json
{"openapi":"3.1.0","info":{"title":"Cedana API","version":"0.0.0-dev"},"tags":[{"description":"Cedana API for checkpoints","name":"Checkpoints"}],"security":[{"Token":[]}],"components":{"securitySchemes":{"Token":{"scheme":"bearer","type":"http"}},"schemas":{"CheckpointFileEntry":{"description":"A file inside a checkpoint: an archive member, or a child of a checkpoint directory","properties":{"is_dir":{"type":"boolean"},"mod_time":{"description":"Modification time, Unix ms","format":"int64","type":"integer"},"name":{"type":"string"},"size":{"description":"Size in bytes","format":"int64","type":"integer"}},"required":["name","size","mod_time","is_dir"],"type":"object"},"HttpError":{"description":"Standard JSON error body for all 4xx/5xx responses.\n\nHandlers return plain-text errors internally; [`normalize_error_response`]\nconverts anything the stack produces (handlers, extractors, the auth layer)\nto this shape, so generated SDK clients can rely on a single error schema.","properties":{"message":{"description":"Human-readable description of what went wrong","type":"string"}},"required":["message"],"type":"object"}}},"paths":{"/v1/checkpoints/{id}/files":{"get":{"description":"Asks a helper on the checkpoint's cluster to read the checkpoint and returns the files\ninside it (the members of the checkpoint archive).","operationId":"files","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"items":{"$ref":"#/components/schemas/CheckpointFileEntry"},"type":"array"}}},"description":"Files inside the checkpoint"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}},"description":"Invalid UUID provided"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}},"description":"Checkpoint not found or deprecated"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}},"description":"Checkpoint has no path or cluster yet"},"502":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}},"description":"Helper could not read the checkpoint"},"504":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}},"description":"No helper on the cluster answered in time"},"4XX":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}},"description":"Client error"},"5XX":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}},"description":"Server error"}},"summary":"List checkpoint files","tags":["Checkpoints"]}}}}
```

## Download a checkpoint file

> Asks a helper on the checkpoint's cluster to copy one file out of the checkpoint into\
> Cedana managed storage, then returns a signed URL it can be downloaded from. Blocks\
> until the helper has uploaded the file.

```json
{"openapi":"3.1.0","info":{"title":"Cedana API","version":"0.0.0-dev"},"tags":[{"description":"Cedana API for checkpoints","name":"Checkpoints"}],"security":[{"Token":[]}],"components":{"securitySchemes":{"Token":{"scheme":"bearer","type":"http"}},"schemas":{"DownloadCheckpointFile":{"properties":{"entry":{"description":"Name of the file inside the checkpoint, as returned by the file listing","type":"string"}},"required":["entry"],"type":"object"},"HttpError":{"description":"Standard JSON error body for all 4xx/5xx responses.\n\nHandlers return plain-text errors internally; [`normalize_error_response`]\nconverts anything the stack produces (handlers, extractors, the auth layer)\nto this shape, so generated SDK clients can rely on a single error schema.","properties":{"message":{"description":"Human-readable description of what went wrong","type":"string"}},"required":["message"],"type":"object"}}},"paths":{"/v1/checkpoints/{id}/files/download":{"post":{"description":"Asks a helper on the checkpoint's cluster to copy one file out of the checkpoint into\nCedana managed storage, then returns a signed URL it can be downloaded from. Blocks\nuntil the helper has uploaded the file.","operationId":"download_file","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DownloadCheckpointFile"}}},"required":true},"responses":{"200":{"content":{"text/plain":{"schema":{"type":"string"}}},"description":"Returns the URL to download the file from"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}},"description":"Invalid UUID or file entry provided"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}},"description":"Checkpoint not found or deprecated"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}},"description":"Checkpoint has no path or cluster yet"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}},"description":"Failed to generate signed URL"},"502":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}},"description":"Helper could not read or upload the file"},"504":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}},"description":"No helper on the cluster answered in time"},"4XX":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}},"description":"Client error"},"5XX":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}},"description":"Server error"}},"summary":"Download a checkpoint file","tags":["Checkpoints"]}}}}
```