> 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/actions.md).

# Actions

Cedana API for actions

## GET /v1/actions

> List actions

```json
{"openapi":"3.1.0","info":{"title":"Cedana API","version":"0.0.0-dev"},"tags":[{"description":"Cedana API for actions","name":"Actions"}],"security":[{"Token":[]}],"components":{"securitySchemes":{"Token":{"scheme":"bearer","type":"http"}},"schemas":{"Action":{"properties":{"action_id":{"format":"uuid","type":"string"},"action_timestamp":{"format":"date-time","type":["string","null"]},"checkpoint_completed_timestamp":{"format":"date-time","type":["string","null"]},"checkpoint_id":{"format":"uuid","type":"string"},"checkpoint_name":{"description":"The checkpoint's CEDANA_CHECKPOINT name (the env value it restores from),\nused to group automatic/named checkpoints. Null for unnamed checkpoints.","type":["string","null"]},"delta":{"description":"Whether the checkpoint is a (GPU delta) increment. Authoritative even\nwhen parent_checkpoint_id is null (malformed id at ingest, parent deleted)","type":["boolean","null"]},"details":{},"gpu":{"type":"string"},"node_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"},"reason":{"type":["string","null"]},"status":{"type":"string"},"total_duration":{"format":"int64","type":["integer","null"]},"total_io":{"format":"int64","type":["integer","null"]},"type":{"type":"string"},"workload_kind":{"description":"Owning workload kind of the checkpointed pod: \"DynamoGraphDeployment\" when\nthe pod belongs to a Dynamo deployment, else the pod's immediate\nownerReferences kind (ReplicaSet/Job/StatefulSet…). Null if unknown.","type":["string","null"]}},"required":["action_id","checkpoint_id","status","type","details","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/actions":{"get":{"operationId":"list","parameters":[{"in":"query","name":"type","required":false,"schema":{"type":["string","null"]}}],"responses":{"200":{"content":{"application/json":{"schema":{"items":{"$ref":"#/components/schemas/Action"},"type":"array"}}},"description":"Returns the actions with status"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}},"description":"Failed list"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}},"description":"Failed to connect/fetch from jobs table 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 actions","tags":["Actions"]}}}}
```

## GET /v1/actions/from\_pod/{id}

> Get latest action belonging to a pod

```json
{"openapi":"3.1.0","info":{"title":"Cedana API","version":"0.0.0-dev"},"tags":[{"description":"Cedana API for actions","name":"Actions"}],"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/actions/from_pod/{id}":{"get":{"operationId":"latest_pod_action_id","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"text/plain":{"schema":{"type":"string"}}},"description":"The action_id of the given pod_id has been fetched successfully"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}},"description":"Failed to get action_id for the given pod_id"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}},"description":"Failed to connect/fetch from pods_to_actions table 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":"Get latest action belonging to a pod","tags":["Actions"]}}}}
```

## POST /v1/actions/upload

> Upload pod spec

```json
{"openapi":"3.1.0","info":{"title":"Cedana API","version":"0.0.0-dev"},"tags":[{"description":"Cedana API for actions","name":"Actions"}],"security":[{"Token":[]}],"components":{"securitySchemes":{"Token":{"scheme":"bearer","type":"http"}},"schemas":{"CheckpointStatusWithPodSpec":{"properties":{"action_id":{"type":"string"},"persistent_volume_claim":{},"pod_id":{"type":["string","null"]},"pod_metadata_spec":{},"pod_spec":{},"status":{"type":"string"}},"required":["status","action_id"],"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/actions/upload":{"post":{"operationId":"upload_podspec","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckpointStatusWithPodSpec"}}},"required":true},"responses":{"200":{"content":{"text/plain":{"schema":{"type":"string"}}},"description":"Success"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}},"description":"Failed to get action_id within the db"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}},"description":"Failed to connect/fetch from pods_to_actions table 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":"Upload pod spec","tags":["Actions"]}}}}
```

## Get action details by ID

> Returns detailed information about a specific action including associated checkpoint data

```json
{"openapi":"3.1.0","info":{"title":"Cedana API","version":"0.0.0-dev"},"tags":[{"description":"Cedana API for actions","name":"Actions"}],"security":[{"Token":[]}],"components":{"securitySchemes":{"Token":{"scheme":"bearer","type":"http"}},"schemas":{"ActionDetails":{"description":"Action details response for a single action","properties":{"action_id":{"description":"The action ID","format":"uuid","type":"string"},"action_timestamp":{"description":"When the action was created","format":"date-time","type":["string","null"]},"checkpoint_completed_timestamp":{"description":"When checkpoint completed (if any)","format":"date-time","type":["string","null"]},"checkpoint_id":{"description":"Associated checkpoint ID (if any)","format":"uuid","type":["string","null"]},"checkpoint_info":{"description":"Full checkpoint profiling info (JSON)"},"checkpoint_name":{"description":"Checkpoint name/image","type":["string","null"]},"checkpoint_size":{"description":"Checkpoint size in bytes","format":"int64","type":["integer","null"]},"details":{"description":"Original request details (JSONB)"},"gpu":{"description":"GPU type used","type":["string","null"]},"node_name":{"description":"Node where the pod was running","type":["string","null"]},"platform":{"description":"Platform (e.g., containerd)","type":["string","null"]},"reason":{"description":"Reason for the action (heartbeat, manual, nodeTermination, etc.)","type":["string","null"]},"restore_path":{"description":"Restore path for the checkpoint","type":["string","null"]},"status":{"description":"Current status of the action","type":"string"},"total_duration":{"description":"Checkpoint duration in nanoseconds (from profiling)","format":"int64","type":["integer","null"]},"total_io":{"description":"Total I/O in bytes (from profiling)","format":"int64","type":["integer","null"]},"type":{"description":"Action type (checkpoint_pod, restore_pod, heartbeat)","type":"string"}},"required":["action_id","type","status","details"],"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/actions/{id}":{"get":{"description":"Returns detailed information about a specific action including associated checkpoint data","operationId":"get_action","parameters":[{"description":"Action UUID","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ActionDetails"}}},"description":"Action details retrieved successfully"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}},"description":"Invalid action ID format"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}},"description":"Action not found"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}},"description":"Database error"},"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":"Get action details by ID","tags":["Actions"]}}}}
```

## Get path of latest checkpoint

> Returns the path of the latest successful checkpoint for a given checkpoint name

```json
{"openapi":"3.1.0","info":{"title":"Cedana API","version":"0.0.0-dev"},"tags":[{"description":"Cedana API for actions","name":"Actions"}],"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/checkpoint/path":{"get":{"description":"Returns the path of the latest successful checkpoint for a given checkpoint name","operationId":"get_latest_checkpoint_for_container_in_action","parameters":[{"in":"query","name":"name","required":false,"schema":{"type":["string","null"]}}],"responses":{"200":{"content":{"text/plain":{"schema":{"type":"string"}}},"description":"Returns the restore path"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}},"description":"Failed to get action for request"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}},"description":"Failed to connect/fetch from jobs table 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":"Get path of latest checkpoint","tags":["Actions"]}}}}
```

## POST /v1/checkpoint/pod

> Checkpoint pod

```json
{"openapi":"3.1.0","info":{"title":"Cedana API","version":"0.0.0-dev"},"tags":[{"description":"Cedana API for actions","name":"Actions"}],"security":[{"Token":[]}],"components":{"securitySchemes":{"Token":{"scheme":"bearer","type":"http"}},"schemas":{"CheckpointPod":{"properties":{"action_id":{"readOnly":true,"type":["string","null"]},"cluster_id":{"type":["string","null"]},"kind":{"$ref":"#/components/schemas/CheckpointKind"},"namespace":{"type":["string","null"]},"overrides":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/CheckpointOverrides"}]},"pod_id":{"type":["string","null"]},"pod_name":{"type":["string","null"]},"reason":{"$ref":"#/components/schemas/CheckpointReason"}},"type":"object"},"CheckpointKind":{"enum":["simple","rootfs","rootfsonly"],"type":"string"},"CheckpointOverrides":{"properties":{"asynchronous":{"type":"boolean"},"compression":{"type":["string","null"]},"criu_opts":{"type":["string","null"]},"directory":{"type":["string","null"]},"incremental":{"description":"GPU delta (incremental) checkpoint; None = cluster default","type":["boolean","null"]},"streams":{"format":"int32","type":"integer"}},"type":"object"},"CheckpointReason":{"enum":["heartbeat","manual"],"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/checkpoint/pod":{"post":{"operationId":"checkpoint_pod","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckpointPod"}}},"required":true},"responses":{"200":{"content":{"text/plain":{"schema":{"type":"string"}}},"description":"Returns the ID for the task"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}},"description":"Invalid request parameters"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}},"description":"Failed to find checkpointable resource"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}},"description":"Failed to create checkpoint or connect to eventstream"},"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":"Checkpoint pod","tags":["Actions"]}}}}
```

## Get status of checkpoint action

> Returns the current status of a checkpoint action

```json
{"openapi":"3.1.0","info":{"title":"Cedana API","version":"0.0.0-dev"},"tags":[{"description":"Cedana API for actions","name":"Actions"}],"security":[{"Token":[]}],"components":{"securitySchemes":{"Token":{"scheme":"bearer","type":"http"}},"schemas":{"StatusResponse":{"properties":{"details":{"type":["string","null"]},"status":{"$ref":"#/components/schemas/CheckpointOperationStatus"}},"required":["status"],"type":"object"},"CheckpointOperationStatus":{"enum":["initialized","processing","checkpoint_created","ready","error","not_found"],"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/checkpoint/status/{action_id}":{"get":{"description":"Returns the current status of a checkpoint action","operationId":"get_checkpoint_status","parameters":[{"in":"path","name":"action_id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StatusResponse"}}},"description":"Returns the current status of the checkpoint operation"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}},"description":"Action ID not found"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}},"description":"Failed to retrieve status 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":"Get status of checkpoint action","tags":["Actions"]}}}}
```

## POST /v1/restore/pod

> Restore pod

```json
{"openapi":"3.1.0","info":{"title":"Cedana API","version":"0.0.0-dev"},"tags":[{"description":"Cedana API for actions","name":"Actions"}],"security":[{"Token":[]}],"components":{"securitySchemes":{"Token":{"scheme":"bearer","type":"http"}},"schemas":{"RestorePod":{"properties":{"action_id":{"type":"string"},"cluster_id":{"type":"string"},"overrides":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/RestoreOverrides"}]},"reason":{"$ref":"#/components/schemas/RestoreReason"}},"required":["action_id","reason"],"type":"object"},"RestoreOverrides":{"properties":{"criu_opts":{"type":["string","null"]},"pod_name":{"type":["string","null"]}},"type":"object"},"RestoreReason":{"enum":["nodeTermination","nodeUnschedulable","manual"],"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/restore/pod":{"post":{"operationId":"restore_pod","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RestorePod"}}},"required":true},"responses":{"200":{"content":{"text/plain":{"schema":{"type":"string"}}},"description":"Returns the action ID for the new restore"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}},"description":"Invalid action_id or request parameters"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}},"description":"Failed to create restore or connect to eventstream"},"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":"Restore pod","tags":["Actions"]}}}}
```