> 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 associated with the authenticated user's organization

```json
{"openapi":"3.1.0","info":{"title":"Cedana API","version":"0.0.0-staging"},"tags":[{"name":"Clusters","description":"Cedana API for clusters"}],"security":[{"Token":[]}],"components":{"securitySchemes":{"Token":{"type":"http","scheme":"bearer"}},"schemas":{"Cluster":{"type":"object","required":["id","name","status"],"properties":{"id":{"type":"string","format":"uuid"},"last_sync":{"type":["string","null"],"format":"date-time"},"metadata":{},"name":{"type":"string"},"status":{"type":"string"}}},"ApiError":{"type":"object","description":"Standard error response for API endpoints","required":["message"],"properties":{"code":{"type":["string","null"],"description":"HTTP status code"},"details":{"description":"Optional additional error details"},"message":{"type":"string","description":"Error message describing what went wrong"}}}}},"paths":{"/v2/cluster":{"get":{"tags":["Clusters"],"summary":"List clusters","description":"Returns all clusters associated with the authenticated user's organization","operationId":"list","responses":{"200":{"description":"Returns a list of clusters","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Cluster"}}}}},"500":{"description":"Failed to fetch clusters from database","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}}}}
```

## Create cluster

> Creates or updates info regarding a Kubernetes cluster

```json
{"openapi":"3.1.0","info":{"title":"Cedana API","version":"0.0.0-staging"},"tags":[{"name":"Clusters","description":"Cedana API for clusters"}],"security":[{"Token":[]}],"components":{"securitySchemes":{"Token":{"type":"http","scheme":"bearer"}},"schemas":{"CreateClusterRequest":{"type":"object","description":"CreateClusterRequest is the request body for creating a cluster","required":["cluster_name"],"properties":{"cluster_name":{"type":"string"}}},"ApiError":{"type":"object","description":"Standard error response for API endpoints","required":["message"],"properties":{"code":{"type":["string","null"],"description":"HTTP status code"},"details":{"description":"Optional additional error details"},"message":{"type":"string","description":"Error message describing what went wrong"}}}}},"paths":{"/v2/cluster":{"post":{"tags":["Clusters"],"summary":"Create cluster","description":"Creates or updates info regarding a Kubernetes cluster","operationId":"create","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateClusterRequest"}}},"required":true},"responses":{"200":{"description":"Returns the cluster id for the newly created or updated cluster","content":{"text/plain":{"schema":{"type":"string"}}}},"400":{"description":"Bad request or missing cluster name","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Failed to create cluster in database","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}}}}
```

## Sync cluster

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

```json
{"openapi":"3.1.0","info":{"title":"Cedana API","version":"0.0.0-staging"},"tags":[{"name":"Clusters","description":"Cedana API for clusters"}],"security":[{"Token":[]}],"components":{"securitySchemes":{"Token":{"type":"http","scheme":"bearer"}},"schemas":{"ClusterSyncRequest":{"type":"object","properties":{"cluster_id":{"type":["string","null"],"format":"uuid"},"metadata":{},"resource":{"$ref":"#/components/schemas/K8sResource"}}},"K8sResource":{"oneOf":[{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["None"]}}},{"allOf":[{"$ref":"#/components/schemas/Pod"},{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["Pod"]}}}]},{"allOf":[{"$ref":"#/components/schemas/Node"},{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["Node"]}}}]},{"allOf":[{"$ref":"#/components/schemas/Job"},{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["Job"]}}}]}]},"Pod":{"type":"object","title":"Pod","description":"Entire json for the Kubernetes "},"Node":{"type":"object","title":"Node","description":"Entire json for the Kubernetes Node"},"Job":{"type":"object","title":"Job","description":"Entire json for the Kubernetes Job"},"ApiError":{"type":"object","description":"Standard error response for API endpoints","required":["message"],"properties":{"code":{"type":["string","null"],"description":"HTTP status code"},"details":{"description":"Optional additional error details"},"message":{"type":"string","description":"Error message describing what went wrong"}}}}},"paths":{"/v2/cluster/sync":{"post":{"tags":["Clusters"],"summary":"Sync cluster","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":{"description":"Resource id registered internally","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Cluster or node not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Failed to sync resource to database","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}}}}
```

## 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-staging"},"tags":[{"name":"Clusters","description":"Cedana API for clusters"}],"paths":{"/v2/cluster/workload":{"post":{"tags":["Clusters"],"summary":"Create workload","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":{"description":"Added workload to queue","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"400":{"description":"Error parsing body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}}},"components":{"schemas":{"WorkloadReq":{"type":"object","required":["cluster_id"],"properties":{"cluster_id":{"type":"string"},"cluster_name":{"type":["string","null"],"deprecated":true},"deployment":{},"job":{},"pod":{}}},"ApiError":{"type":"object","description":"Standard error response for API endpoints","required":["message"],"properties":{"code":{"type":["string","null"],"description":"HTTP status code"},"details":{"description":"Optional additional error details"},"message":{"type":"string","description":"Error message describing what went wrong"}}}}}}
```

## 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-staging"},"tags":[{"name":"Clusters","description":"Cedana API for clusters"}],"security":[{"Token":[]}],"components":{"securitySchemes":{"Token":{"type":"http","scheme":"bearer"}},"schemas":{"ApiError":{"type":"object","description":"Standard error response for API endpoints","required":["message"],"properties":{"code":{"type":["string","null"],"description":"HTTP status code"},"details":{"description":"Optional additional error details"},"message":{"type":"string","description":"Error message describing what went wrong"}}}}},"paths":{"/v2/cluster/{id}":{"delete":{"tags":["Clusters"],"summary":"Delete cluster","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":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Delete the given cluster, and return Status OK"},"404":{"description":"Cluster not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Failed to delete cluster from database","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}}}}
```