# 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"}}}}}}}}}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.cedana.ai/references/api/clusters.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.