4.2 Working With Hosts Via API

URI: https://myIsoraURL/api/hosts

Verb	Address	Notes	Additional Details
GET	/hosts /hosts?page=X &page_size=Y	Retrieves a paginated list of all hosts, Y at a time (by default 25). Each array entry includes details about the host.	The beginning of each response includes a count and a link to the next page. Each entry in the list has a link to itself.
GET	/hosts/<id>	Retrieves an individual host. If an invalid host id is given, a “Not found” error is returned.
POST	/hosts	Creates a new host. Only the sheets field is required, which must be specified by ID. You must be a sheet owner to add a host to any specific sheet. The new host is returned. If a location is specified, the individual components of the location object are verified to try to find a matching location ID. If an exact match cannot be found, then an error is returned and the host will not be added. The format of the location field is { “site”: string, “building”: string, “floor”: string, “room”: string }	body { “names”: array of strings, “sheets”: array of strings (sheet IDs), “description”: string, “ips”: string, “macs”: string, “aco”: string, “location”: {location object},¹ “off_premises”: Boolean (true/false)² “classification”: string (implementation-dependent code), “categories”: array of strings (implementation-dependent codes), “priority”: string (code), “system_type”: string (code), “free_fields”: json, “owners”: array of strings³, “it_contacts”: array of strings³, “users”: array of strings³ } ¹The location field is handled in a special way, detailed at left. ²If true, location notes must be included. ³You can specify usernames, email addresses, groups and/or organizational unit code.
PUT	/hosts/<id>	Updates (replaces) an existing host. Returns the updated host object.	Include the sheets field, along with any other fields you want to change.
DELETE	/hosts/<id>	Removes the host. No content is returned.
GET	/hosts?sheet=<id> &page_size=Y	Retrieves a paginated list of hosts belonging to the sheet in arrays of up to Y (by default 25) at a time. Each entry includes some details about the host.	The beginning of each response includes a count and a link to the previous and next pages Each entry in the array has a link to itself.
GET	/hosts?search=string &page_size=Y	Returns host objects matching the search string.	Useful for testing. Only host objects are searched.