> For the complete documentation index, see [llms.txt](https://docs.i3d.net/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.i3d.net/api-references/inventory/server-1.md).

# Server

CRUD for servers

## Find a server by ID

> Returns a single server with basic details

```json
{"openapi":"3.0.3","info":{"title":"Inventory Service - OpenAPI 3.0","version":"0.1.0"},"tags":[{"name":"Server","description":"CRUD for servers"}],"security":[{"ApiKeyAuth":["read:server"]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","name":"X-Api-Key","in":"header"}},"schemas":{"Server":{"type":"object","properties":{"server":{"$ref":"#/components/schemas/ServerModel"}}},"ServerModel":{"type":"object","required":["ipAddresses","macAddresses","disks"],"properties":{"serverId":{"type":"integer","format":"int","minimum":0},"machineUuid":{"type":"string"},"serial":{"type":"string"},"name":{"type":"string"},"hostname":{"type":"string"},"locationId":{"type":"integer","format":"int","minimum":0},"locationName":{"type":"string"},"instanceTypeId":{"type":"integer","format":"int","minimum":0},"instanceTypeName":{"type":"string"},"clientId":{"type":"integer","format":"int","minimum":0,"description":"The K number of the client this server is allocated to. Or 0 if unallocated."},"contractId":{"type":"string","pattern":"^[A-Z0-9_\\-.]{0,240}$","description":"Can be empty or null for on-demand client quota"},"state":{"type":"string","enum":["new","isolated","backToBaseline","available","allocated","decommissioned"]},"subState":{"type":"string"},"vendor":{"type":"string"},"chassis":{"type":"string"},"firmwareVersion":{"type":"number","format":"double"},"ipmiVersion":{"type":"number","format":"double"},"ipAddresses":{"type":"array","items":{"$ref":"#/components/schemas/IpAddressSum"}},"macAddresses":{"type":"array","items":{"$ref":"#/components/schemas/MacAddressSum"}},"disks":{"type":"array","items":{"$ref":"#/components/schemas/DiskSum"}},"isolationReason":{"$ref":"#/components/schemas/IsolationReason"}}},"IpAddressSum":{"type":"object","properties":{"ipAddress":{"type":"string"},"ipType":{"type":"string"},"ipVersion":{"type":"string"}}},"MacAddressSum":{"type":"object","properties":{"macAddress":{"type":"string"},"macType":{"type":"string"}}},"DiskSum":{"type":"object","properties":{"name":{"type":"string"},"interface":{"type":"string"},"type":{"type":"string"}}},"IsolationReason":{"type":"object","properties":{"operationUuid":{"type":"string","format":"uuid"},"reason":{"type":"string"},"createdAt":{"type":"string","format":"date-time"}}}}},"paths":{"/api/server/{serverId}":{"get":{"tags":["Server"],"summary":"Find a server by ID","description":"Returns a single server with basic details","operationId":"getServerById","parameters":[{"name":"serverId","in":"path","description":"ID of the server to return","required":true,"schema":{"type":"integer","format":"int"}}],"responses":{"200":{"description":"Successful operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Server"}},"application/xml":{"schema":{"$ref":"#/components/schemas/Server"}}}},"400":{"description":"Invalid ID supplied"},"401":{"description":"Invalid authentication"},"404":{"description":"Server not found"}}}}}}
```

## Update a server's main properties by ID

> Update a server's locationId and instsanceTypeId properties by server ID.

```json
{"openapi":"3.0.3","info":{"title":"Inventory Service - OpenAPI 3.0","version":"0.1.0"},"tags":[{"name":"Server","description":"CRUD for servers"}],"security":[{"ApiKeyAuth":["read:server"]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","name":"X-Api-Key","in":"header"}},"schemas":{"PatchRequest":{"type":"object","required":["items"],"properties":{"items":{"type":"array","items":{"oneOf":[{"$ref":"#/components/schemas/JSONPatchRequestReplace"}]}}}},"JSONPatchRequestReplace":{"type":"object","additionalProperties":false,"required":["op","path","value"],"properties":{"op":{"description":"The operation to perform.","type":"string","enum":["replace"]},"path":{"description":"A JSON Pointer path.","type":"string","enum":["instanceTypeId","locationId"]},"value":{"description":"The value to add, replace or test."}}},"Server":{"type":"object","properties":{"server":{"$ref":"#/components/schemas/ServerModel"}}},"ServerModel":{"type":"object","required":["ipAddresses","macAddresses","disks"],"properties":{"serverId":{"type":"integer","format":"int","minimum":0},"machineUuid":{"type":"string"},"serial":{"type":"string"},"name":{"type":"string"},"hostname":{"type":"string"},"locationId":{"type":"integer","format":"int","minimum":0},"locationName":{"type":"string"},"instanceTypeId":{"type":"integer","format":"int","minimum":0},"instanceTypeName":{"type":"string"},"clientId":{"type":"integer","format":"int","minimum":0,"description":"The K number of the client this server is allocated to. Or 0 if unallocated."},"contractId":{"type":"string","pattern":"^[A-Z0-9_\\-.]{0,240}$","description":"Can be empty or null for on-demand client quota"},"state":{"type":"string","enum":["new","isolated","backToBaseline","available","allocated","decommissioned"]},"subState":{"type":"string"},"vendor":{"type":"string"},"chassis":{"type":"string"},"firmwareVersion":{"type":"number","format":"double"},"ipmiVersion":{"type":"number","format":"double"},"ipAddresses":{"type":"array","items":{"$ref":"#/components/schemas/IpAddressSum"}},"macAddresses":{"type":"array","items":{"$ref":"#/components/schemas/MacAddressSum"}},"disks":{"type":"array","items":{"$ref":"#/components/schemas/DiskSum"}},"isolationReason":{"$ref":"#/components/schemas/IsolationReason"}}},"IpAddressSum":{"type":"object","properties":{"ipAddress":{"type":"string"},"ipType":{"type":"string"},"ipVersion":{"type":"string"}}},"MacAddressSum":{"type":"object","properties":{"macAddress":{"type":"string"},"macType":{"type":"string"}}},"DiskSum":{"type":"object","properties":{"name":{"type":"string"},"interface":{"type":"string"},"type":{"type":"string"}}},"IsolationReason":{"type":"object","properties":{"operationUuid":{"type":"string","format":"uuid"},"reason":{"type":"string"},"createdAt":{"type":"string","format":"date-time"}}}}},"paths":{"/api/server/{serverId}":{"patch":{"tags":["Server"],"summary":"Update a server's main properties by ID","description":"Update a server's locationId and instsanceTypeId properties by server ID.","operationId":"patchServerById","parameters":[{"name":"serverId","in":"path","description":"ID of the server to patch and return","required":true,"schema":{"type":"integer","format":"int"}}],"requestBody":{"description":"Provide the properties that should be patch-replaced. Only locationId and instanceTypeId can be replaced atm.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PatchRequest"}}}},"responses":{"200":{"description":"Successful operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Server"}},"application/xml":{"schema":{"$ref":"#/components/schemas/Server"}}}},"400":{"description":"Invalid ID supplied"},"401":{"description":"Invalid authentication"},"404":{"description":"Server not found"}}}}}}
```

## GET /api/server

> Find servers by IDs

```json
{"openapi":"3.0.3","info":{"title":"Inventory Service - OpenAPI 3.0","version":"0.1.0"},"tags":[{"name":"Server","description":"CRUD for servers"}],"security":[{"ApiKeyAuth":["read:server"]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","name":"X-Api-Key","in":"header"}},"schemas":{"ServerCollection":{"type":"object","properties":{"servers":{"type":"array","items":{"$ref":"#/components/schemas/Server"}}}},"Server":{"type":"object","properties":{"server":{"$ref":"#/components/schemas/ServerModel"}}},"ServerModel":{"type":"object","required":["ipAddresses","macAddresses","disks"],"properties":{"serverId":{"type":"integer","format":"int","minimum":0},"machineUuid":{"type":"string"},"serial":{"type":"string"},"name":{"type":"string"},"hostname":{"type":"string"},"locationId":{"type":"integer","format":"int","minimum":0},"locationName":{"type":"string"},"instanceTypeId":{"type":"integer","format":"int","minimum":0},"instanceTypeName":{"type":"string"},"clientId":{"type":"integer","format":"int","minimum":0,"description":"The K number of the client this server is allocated to. Or 0 if unallocated."},"contractId":{"type":"string","pattern":"^[A-Z0-9_\\-.]{0,240}$","description":"Can be empty or null for on-demand client quota"},"state":{"type":"string","enum":["new","isolated","backToBaseline","available","allocated","decommissioned"]},"subState":{"type":"string"},"vendor":{"type":"string"},"chassis":{"type":"string"},"firmwareVersion":{"type":"number","format":"double"},"ipmiVersion":{"type":"number","format":"double"},"ipAddresses":{"type":"array","items":{"$ref":"#/components/schemas/IpAddressSum"}},"macAddresses":{"type":"array","items":{"$ref":"#/components/schemas/MacAddressSum"}},"disks":{"type":"array","items":{"$ref":"#/components/schemas/DiskSum"}},"isolationReason":{"$ref":"#/components/schemas/IsolationReason"}}},"IpAddressSum":{"type":"object","properties":{"ipAddress":{"type":"string"},"ipType":{"type":"string"},"ipVersion":{"type":"string"}}},"MacAddressSum":{"type":"object","properties":{"macAddress":{"type":"string"},"macType":{"type":"string"}}},"DiskSum":{"type":"object","properties":{"name":{"type":"string"},"interface":{"type":"string"},"type":{"type":"string"}}},"IsolationReason":{"type":"object","properties":{"operationUuid":{"type":"string","format":"uuid"},"reason":{"type":"string"},"createdAt":{"type":"string","format":"date-time"}}}}},"paths":{"/api/server":{"get":{"tags":["Server"],"summary":"Find servers by IDs","operationId":"getServerByIds","parameters":[{"name":"serverIds","in":"query","description":"Comma-separated list of server IDs","required":true,"schema":{"type":"string","pattern":"^\\d+(,\\d+)*$"}}],"responses":{"200":{"description":"Successful operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServerCollection"}}}},"400":{"description":"Invalid IDs supplied"},"401":{"description":"Invalid authentication"},"404":{"description":"Servers not found"}}}}}}
```

## Find a server's lshw dump by ID

> Returns a single server's lshw dump

```json
{"openapi":"3.0.3","info":{"title":"Inventory Service - OpenAPI 3.0","version":"0.1.0"},"tags":[{"name":"Server","description":"CRUD for servers"}],"security":[{"ApiKeyAuth":["read:server"]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","name":"X-Api-Key","in":"header"}},"schemas":{"ServerLshw":{"type":"object","required":["serverLshw"],"properties":{"serverLshw":{"type":"object","required":["createdAt"],"properties":{"createdAt":{"type":"integer","format":"uint","description":"Unix timestamp of when this lshw dump was created"},"lshw":{"type":"string","description":"The lshw json dump in string format (manually unmarshall it if needed)"}}}}}}},"paths":{"/api/server/{serverId}/lshw":{"get":{"tags":["Server"],"summary":"Find a server's lshw dump by ID","description":"Returns a single server's lshw dump","operationId":"getServerLshwById","parameters":[{"name":"serverId","in":"path","description":"ID of the server to return","required":true,"schema":{"type":"integer","format":"int"}}],"responses":{"200":{"description":"Successful operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServerLshw"}}}},"400":{"description":"Invalid ID supplied"},"401":{"description":"Invalid authentication"},"404":{"description":"Server not found"}}}}}}
```

## Find a server's memory details by ID

> Returns a single server's memory details

```json
{"openapi":"3.0.3","info":{"title":"Inventory Service - OpenAPI 3.0","version":"0.1.0"},"tags":[{"name":"Server","description":"CRUD for servers"}],"security":[{"ApiKeyAuth":["read:server"]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","name":"X-Api-Key","in":"header"}},"schemas":{"ServerMemory":{"type":"object","properties":{"serverMemory":{"type":"array","items":{"$ref":"#/components/schemas/ServerMemoryModule"}}}},"ServerMemoryModule":{"type":"object","properties":{"size":{"description":"Module size in MiB","type":"integer","format":"int","minimum":0}}}}},"paths":{"/api/server/{serverId}/memory":{"get":{"tags":["Server"],"summary":"Find a server's memory details by ID","description":"Returns a single server's memory details","operationId":"getServerMemoryById","parameters":[{"name":"serverId","in":"path","description":"ID of the server to return","required":true,"schema":{"type":"integer","format":"int"}}],"responses":{"200":{"description":"Successful operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServerMemory"}}}},"400":{"description":"Invalid ID supplied"},"401":{"description":"Invalid authentication"},"404":{"description":"Server not found"}}}}}}
```

## Find a server's disk details by ID

> Returns a single server's disk details

```json
{"openapi":"3.0.3","info":{"title":"Inventory Service - OpenAPI 3.0","version":"0.1.0"},"tags":[{"name":"Server","description":"CRUD for servers"}],"security":[{"ApiKeyAuth":["read:server"]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","name":"X-Api-Key","in":"header"}},"schemas":{"ServerStorage":{"type":"object","properties":{"serverStorage":{"type":"array","items":{"$ref":"#/components/schemas/ServerStorageDisk"}}}},"ServerStorageDisk":{"type":"object","properties":{"size":{"description":"Module size in MB","type":"integer","format":"int","minimum":0}}}}},"paths":{"/api/server/{serverId}/disks":{"get":{"tags":["Server"],"summary":"Find a server's disk details by ID","description":"Returns a single server's disk details","operationId":"getServerDisksById","parameters":[{"name":"serverId","in":"path","description":"ID of the server to return","required":true,"schema":{"type":"integer","format":"int"}}],"responses":{"200":{"description":"Successful operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServerStorage"}}}},"400":{"description":"Invalid ID supplied"},"401":{"description":"Invalid authentication"},"404":{"description":"Server not found"}}}}}}
```

## Find a server's network interface details by ID

> Returns a single server's network interface details

```json
{"openapi":"3.0.3","info":{"title":"Inventory Service - OpenAPI 3.0","version":"0.1.0"},"tags":[{"name":"Server","description":"CRUD for servers"}],"security":[{"ApiKeyAuth":["read:server"]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","name":"X-Api-Key","in":"header"}},"schemas":{"ServerIface":{"type":"object","properties":{"serverInterfaces":{"type":"array","items":{"$ref":"#/components/schemas/ServerIfaceNic"}}}},"ServerIfaceNic":{"type":"object","properties":{"vendor":{"type":"string"}}}}},"paths":{"/api/server/{serverId}/interfaces":{"get":{"tags":["Server"],"summary":"Find a server's network interface details by ID","description":"Returns a single server's network interface details","operationId":"getServerInterfacesById","parameters":[{"name":"serverId","in":"path","description":"ID of the server to return","required":true,"schema":{"type":"integer","format":"int"}}],"responses":{"200":{"description":"Successful operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServerIface"}}}},"400":{"description":"Invalid ID supplied"},"401":{"description":"Invalid authentication"},"404":{"description":"Server not found"}}}}}}
```

## GET /api/server/availability/verify

> Checks if any server can be delivered to the client

```json
{"openapi":"3.0.3","info":{"title":"Inventory Service - OpenAPI 3.0","version":"0.1.0"},"tags":[{"name":"Server","description":"CRUD for servers"}],"paths":{"/api/server/availability/verify":{"get":{"tags":["Server"],"summary":"Checks if any server can be delivered to the client","operationId":"serverAvailabilityVerify","parameters":[{"name":"instanceTypeId","in":"query","description":"instance type id","required":true,"schema":{"type":"integer","format":"int"}},{"name":"locationId","in":"query","description":"location id","schema":{"type":"integer","format":"int"}},{"name":"clientId","in":"query","description":"client id","required":true,"schema":{"type":"integer","format":"int"}},{"name":"contractId","in":"query","required":false,"description":"contract id","schema":{"type":"string","pattern":"^[A-Z0-9_\\-.]{0,240}$"}},{"name":"overflow","in":"query","description":"overflow","required":false,"schema":{"type":"boolean","default":false,"description":"If true, the allocation will be allowed to overflow the client's quota and use on-demand quota"}}],"responses":{"200":{"description":"Successful operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServerAvailabilityVerifyResponse"}}}}}}}},"components":{"schemas":{"ServerAvailabilityVerifyResponse":{"type":"object","properties":{"result":{"type":"boolean"},"details":{"type":"array","items":{"$ref":"#/components/schemas/ServerAvailabilityVerifyDetail"}}}},"ServerAvailabilityVerifyDetail":{"type":"object","properties":{"name":{"type":"string"},"result":{"type":"boolean"},"message":{"type":"string"}}}}}}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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, and the optional `goal` query parameter:

```
GET https://docs.i3d.net/api-references/inventory/server-1.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.