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

# Clusters

Cedana API for clusters

## List clusters

> Returns all clusters. Optional \`?kind=kubernetes|slurm\` filter.

```json
{"openapi":"3.1.0","info":{"title":"Cedana API","version":"0.0.0-dev"},"tags":[{"description":"Cedana API for clusters","name":"Clusters"}],"security":[{"Token":[]}],"components":{"securitySchemes":{"Token":{"scheme":"bearer","type":"http"}},"schemas":{"Cluster":{"properties":{"id":{"format":"uuid","type":"string"},"kind":{"type":"string"},"last_sync":{"format":"date-time","type":["string","null"]},"metadata":{},"name":{"type":"string"},"status":{"type":"string"}},"required":["id","name","status","kind"],"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/cluster":{"get":{"description":"Returns all clusters. Optional `?kind=kubernetes|slurm` filter.","operationId":"list","parameters":[{"description":"Filter by cluster kind: \"kubernetes\" or \"slurm\"","in":"query","name":"kind","required":false,"schema":{"type":["string","null"]}}],"responses":{"200":{"content":{"application/json":{"schema":{"items":{"$ref":"#/components/schemas/Cluster"},"type":"array"}}},"description":"Returns a list of clusters"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}},"description":"Invalid kind filter"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}},"description":"Failed to fetch clusters 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 clusters","tags":["Clusters"]}}}}
```

## Create cluster

> Creates or updates info regarding a Kubernetes cluster

```json
{"openapi":"3.1.0","info":{"title":"Cedana API","version":"0.0.0-dev"},"tags":[{"description":"Cedana API for clusters","name":"Clusters"}],"security":[{"Token":[]}],"components":{"securitySchemes":{"Token":{"scheme":"bearer","type":"http"}},"schemas":{"CreateClusterRequest":{"description":"CreateClusterRequest is the request body for creating a cluster","properties":{"cluster_name":{"type":"string"},"kind":{"description":"Cluster kind: \"kubernetes\" (default) or \"slurm\"","type":["string","null"]}},"required":["cluster_name"],"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/cluster":{"post":{"description":"Creates or updates info regarding a Kubernetes cluster","operationId":"create","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateClusterRequest"}}},"required":true},"responses":{"200":{"content":{"text/plain":{"schema":{"type":"string"}}},"description":"Returns the cluster id for the newly created or updated cluster"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}},"description":"Bad request or missing cluster name"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}},"description":"Failed to create cluster 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 cluster","tags":["Clusters"]}}}}
```

## Sync cluster

> Syncs cluster resources such as pods, jobs, and nodes

```json
{"openapi":"3.1.0","info":{"title":"Cedana API","version":"0.0.0-dev"},"tags":[{"description":"Cedana API for clusters","name":"Clusters"}],"security":[{"Token":[]}],"components":{"securitySchemes":{"Token":{"scheme":"bearer","type":"http"}},"schemas":{"ClusterSyncRequest":{"properties":{"cluster_id":{"format":"uuid","type":["string","null"]},"metadata":{},"resource":{"$ref":"#/components/schemas/K8sResource"}},"type":"object"},"K8sResource":{"description":"A Kubernetes resource tagged by \"type\", with the resource's raw JSON fields alongside the tag","properties":{"type":{"enum":["None","Pod","Node","Job","DynamoGraphDeployment","DynamoService"],"type":"string"}},"required":["type"],"title":"K8sResource","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/cluster/sync":{"post":{"description":"Syncs cluster resources such as pods, jobs, and nodes","operationId":"sync","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClusterSyncRequest"}}},"required":true},"responses":{"200":{"content":{"text/plain":{"schema":{"type":"string"}}},"description":"Resource id registered internally"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}},"description":"Bad request"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}},"description":"Cluster or node not found"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}},"description":"Failed to sync resource to 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":"Sync cluster","tags":["Clusters"]}}}}
```

## Create workload

> Takes a cluster name and workload specification, then creates a Kubernetes job\
> on the specified cluster

```json
{"openapi":"3.1.0","info":{"title":"Cedana API","version":"0.0.0-dev"},"tags":[{"description":"Cedana API for clusters","name":"Clusters"}],"paths":{"/v1/cluster/workload":{"post":{"description":"Takes a cluster name and workload specification, then creates a Kubernetes job\non the specified cluster","operationId":"create_workload","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkloadReq"}}},"required":true},"responses":{"200":{"content":{"text/plain":{"schema":{"type":"string"}}},"description":"Added workload to queue"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}},"description":"Error parsing body"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}},"description":"Server 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":"Create workload","tags":["Clusters"]}}},"components":{"schemas":{"WorkloadReq":{"properties":{"cluster_id":{"type":"string"},"cluster_name":{"deprecated":true,"type":["string","null"]},"deployment":{},"job":{},"pod":{}},"required":["cluster_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"}}}}
```

## Delete cluster

> This endpoint deletes a cluster and all its dependent entities in a single transaction\
> which is rolled back if any part of the deletion fails

```json
{"openapi":"3.1.0","info":{"title":"Cedana API","version":"0.0.0-dev"},"tags":[{"description":"Cedana API for clusters","name":"Clusters"}],"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/cluster/{id}":{"delete":{"description":"This endpoint deletes a cluster and all its dependent entities in a single transaction\nwhich is rolled back if any part of the deletion fails","operationId":"delete","parameters":[{"in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"description":"Delete the given cluster, and return Status OK"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}},"description":"Cluster not found"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}},"description":"Failed to delete cluster 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":"Delete cluster","tags":["Clusters"]}}}}
```