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

# Hosts

Cedana API for hosts

## List hosts

> Use query params to filter hosts. Supports filtering by \`ids\` (comma-separated strings for single or multiple hosts)

```json
{"openapi":"3.1.0","info":{"title":"Cedana API","version":"0.0.0-dev"},"tags":[{"description":"Cedana API for hosts","name":"Hosts"}],"security":[{"Token":[]}],"components":{"securitySchemes":{"Token":{"scheme":"bearer","type":"http"}},"schemas":{"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/hosts":{"get":{"description":"Use query params to filter hosts. Supports filtering by `ids` (comma-separated strings for single or multiple hosts)","operationId":"list","parameters":[{"description":"Comma-separated list of host IDs to filter by","in":"query","name":"ids","required":false,"schema":{"type":["string","null"]}}],"responses":{"200":{"content":{"application/json":{"schema":{"items":{"$ref":"#/components/schemas/Host"},"type":"array"}}},"description":"Returns hosts"},"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 hosts","tags":["Hosts"]}}}}
```

## PUT /v1/hosts/{id}

> Create or update a host

```json
{"openapi":"3.1.0","info":{"title":"Cedana API","version":"0.0.0-dev"},"tags":[{"description":"Cedana API for hosts","name":"Hosts"}],"security":[{"Token":[]}],"components":{"securitySchemes":{"Token":{"scheme":"bearer","type":"http"}},"schemas":{"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/hosts/{id}":{"put":{"operationId":"put","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Host"}}},"required":true},"responses":{"200":{"description":"Host 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 host","tags":["Hosts"]}}}}
```

## DELETE /v1/hosts/{id}

> Delete a host

```json
{"openapi":"3.1.0","info":{"title":"Cedana API","version":"0.0.0-dev"},"tags":[{"description":"Cedana API for hosts","name":"Hosts"}],"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/hosts/{id}":{"delete":{"operationId":"delete","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Host 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 host","tags":["Hosts"]}}}}
```