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

# Jobs

Cedana API for legacy jobs

## List checkpoints for Cedana jobs

> Supports filtering by \`ids\` and/or \`jids\` (comma-separated lists)

```json
{"openapi":"3.1.0","info":{"title":"Cedana API","version":"0.0.0-dev"},"tags":[{"description":"Cedana API for legacy jobs","name":"Jobs"}],"security":[{"Token":[]}],"components":{"securitySchemes":{"Token":{"scheme":"bearer","type":"http"}},"schemas":{"CedanaJobCheckpoint":{"properties":{"ID":{"type":"string"},"JID":{"type":"string"},"Path":{"type":"string"},"Size":{"format":"int64","type":"integer"},"Time":{"format":"int64","type":"integer"}},"required":["JID","Path","Time","Size"],"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/cedana/job/checkpoints":{"get":{"description":"Supports filtering by `ids` and/or `jids` (comma-separated lists)","operationId":"list_checkpoints","parameters":[{"description":"Comma-separated list of checkpoint UUIDs to filter by","in":"query","name":"ids","required":false,"schema":{"type":["string","null"]}},{"description":"Comma-separated list of job IDs to filter by","in":"query","name":"jids","required":false,"schema":{"type":["string","null"]}}],"responses":{"200":{"content":{"application/json":{"schema":{"items":{"$ref":"#/components/schemas/CedanaJobCheckpoint"},"type":"array"}}},"description":"Returns checkpoints"},"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 for Cedana jobs","tags":["Jobs"]}}}}
```

## PUT /v1/cedana/job/checkpoints/{id}

> Create or update a checkpoint for a Cedana job

```json
{"openapi":"3.1.0","info":{"title":"Cedana API","version":"0.0.0-dev"},"tags":[{"description":"Cedana API for legacy jobs","name":"Jobs"}],"security":[{"Token":[]}],"components":{"securitySchemes":{"Token":{"scheme":"bearer","type":"http"}},"schemas":{"CedanaJobCheckpoint":{"properties":{"ID":{"type":"string"},"JID":{"type":"string"},"Path":{"type":"string"},"Size":{"format":"int64","type":"integer"},"Time":{"format":"int64","type":"integer"}},"required":["JID","Path","Time","Size"],"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/cedana/job/checkpoints/{id}":{"put":{"operationId":"put_checkpoint","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CedanaJobCheckpoint"}}},"required":true},"responses":{"200":{"content":{"text/plain":{"schema":{"type":"string"}}},"description":"Checkpoint created or updated successfully, returns the generated checkpoint ID"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}},"description":"Invalid request payload"},"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":"Create or update a checkpoint for a Cedana job","tags":["Jobs"]}}}}
```

## DELETE /v1/cedana/job/checkpoints/{id}

> Delete a checkpoint for a Cedana job

```json
{"openapi":"3.1.0","info":{"title":"Cedana API","version":"0.0.0-dev"},"tags":[{"description":"Cedana API for legacy jobs","name":"Jobs"}],"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/cedana/job/checkpoints/{id}":{"delete":{"operationId":"delete_checkpoint","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Checkpoint deleted successfully"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}},"description":"Invalid UUID"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}},"description":"Failed to delete checkpoint"},"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":"Delete a checkpoint for a Cedana job","tags":["Jobs"]}}}}
```

## List jobs

> Use query params to filter jobs. Supports filtering by \`jids\` or \`host\_ids\` (comma-separated lists)

```json
{"openapi":"3.1.0","info":{"title":"Cedana API","version":"0.0.0-dev"},"tags":[{"description":"Cedana API for legacy jobs","name":"Jobs"}],"security":[{"Token":[]}],"components":{"securitySchemes":{"Token":{"scheme":"bearer","type":"http"}},"schemas":{"Job":{"properties":{"Details":{},"JID":{"type":"string"},"Log":{"type":"string"},"State":{"$ref":"#/components/schemas/ProcessState"},"Type":{"type":"string"}},"required":["Type","State"],"type":"object"},"ProcessState":{"properties":{"Cmdline":{"type":"string"},"GIDs":{"items":{"format":"int32","minimum":0,"type":"integer"},"type":"array"},"GPUEnabled":{"type":"boolean"},"Groups":{"items":{"format":"int32","minimum":0,"type":"integer"},"type":"array"},"Host":{"$ref":"#/components/schemas/Host"},"IsRunning":{"type":"boolean"},"PID":{"format":"int32","minimum":0,"type":"integer"},"StartTime":{"format":"int64","minimum":0,"type":"integer"},"Status":{"type":"string"},"UIDs":{"items":{"format":"int32","minimum":0,"type":"integer"},"type":"array"},"WorkingDir":{"type":"string"}},"required":["PID","Cmdline","StartTime","WorkingDir","Status","IsRunning","Host"],"type":"object"},"Host":{"properties":{"CPU":{"$ref":"#/components/schemas/HostCpu"},"Hostname":{"type":"string"},"ID":{"type":"string"},"KernelArch":{"type":"string"},"KernelVersion":{"type":"string"},"MAC":{"type":"string"},"Memory":{"$ref":"#/components/schemas/HostMemory"},"OS":{"type":"string"},"Platform":{"type":"string"}},"type":"object"},"HostCpu":{"properties":{"Count":{"format":"int32","type":"integer"},"Family":{"type":"string"},"PhysicalID":{"type":"string"},"VendorID":{"type":"string"}},"type":"object"},"HostMemory":{"properties":{"Total":{"format":"int64","minimum":0,"type":"integer"}},"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/cedana/jobs":{"get":{"description":"Use query params to filter jobs. Supports filtering by `jids` or `host_ids` (comma-separated lists)","operationId":"list","parameters":[{"description":"Comma-separated list of job IDs to filter by","in":"query","name":"jids","required":false,"schema":{"type":["string","null"]}},{"description":"Comma-separated list of host IDs to filter by","in":"query","name":"host_ids","required":false,"schema":{"type":["string","null"]}}],"responses":{"200":{"content":{"application/json":{"schema":{"items":{"$ref":"#/components/schemas/Job"},"type":"array"}}},"description":"Returns jobs"},"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 jobs","tags":["Jobs"]}}}}
```

## PUT /v1/cedana/jobs/{jid}

> Create or update a job

```json
{"openapi":"3.1.0","info":{"title":"Cedana API","version":"0.0.0-dev"},"tags":[{"description":"Cedana API for legacy jobs","name":"Jobs"}],"security":[{"Token":[]}],"components":{"securitySchemes":{"Token":{"scheme":"bearer","type":"http"}},"schemas":{"Job":{"properties":{"Details":{},"JID":{"type":"string"},"Log":{"type":"string"},"State":{"$ref":"#/components/schemas/ProcessState"},"Type":{"type":"string"}},"required":["Type","State"],"type":"object"},"ProcessState":{"properties":{"Cmdline":{"type":"string"},"GIDs":{"items":{"format":"int32","minimum":0,"type":"integer"},"type":"array"},"GPUEnabled":{"type":"boolean"},"Groups":{"items":{"format":"int32","minimum":0,"type":"integer"},"type":"array"},"Host":{"$ref":"#/components/schemas/Host"},"IsRunning":{"type":"boolean"},"PID":{"format":"int32","minimum":0,"type":"integer"},"StartTime":{"format":"int64","minimum":0,"type":"integer"},"Status":{"type":"string"},"UIDs":{"items":{"format":"int32","minimum":0,"type":"integer"},"type":"array"},"WorkingDir":{"type":"string"}},"required":["PID","Cmdline","StartTime","WorkingDir","Status","IsRunning","Host"],"type":"object"},"Host":{"properties":{"CPU":{"$ref":"#/components/schemas/HostCpu"},"Hostname":{"type":"string"},"ID":{"type":"string"},"KernelArch":{"type":"string"},"KernelVersion":{"type":"string"},"MAC":{"type":"string"},"Memory":{"$ref":"#/components/schemas/HostMemory"},"OS":{"type":"string"},"Platform":{"type":"string"}},"type":"object"},"HostCpu":{"properties":{"Count":{"format":"int32","type":"integer"},"Family":{"type":"string"},"PhysicalID":{"type":"string"},"VendorID":{"type":"string"}},"type":"object"},"HostMemory":{"properties":{"Total":{"format":"int64","minimum":0,"type":"integer"}},"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/cedana/jobs/{jid}":{"put":{"operationId":"put","parameters":[{"in":"path","name":"jid","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Job"}}},"required":true},"responses":{"200":{"description":"Job created or updated successfully"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}},"description":"Invalid request payload"},"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":"Create or update a job","tags":["Jobs"]}}}}
```

## DELETE /v1/cedana/jobs/{jid}

> Delete a job

```json
{"openapi":"3.1.0","info":{"title":"Cedana API","version":"0.0.0-dev"},"tags":[{"description":"Cedana API for legacy jobs","name":"Jobs"}],"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/cedana/jobs/{jid}":{"delete":{"operationId":"delete","parameters":[{"in":"path","name":"jid","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Job deleted successfully"},"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":"Delete a job","tags":["Jobs"]}}}}
```