Chaya's REST V2 Usage

Task Annotations

The hosts resource defines a running machine instance in Evergreen.

Objects

Host

Name	Type	Description
host_id	string	Unique identifier of a specific host
distro	distro_info	Object containing information about the distro type of this host
started_by	string	Name of the process or user that started this host
host_type	string	The instance type requested for the provider, primarily used for ec2 dynamic hosts
user	string	The user associated with this host. Set if this host was spawned for a specific user
status	string	The current state of the host
running_task	task_info	Object containing information about the task the host is currently running

Distro Info

Name	Type	Description
distro_id	string	Unique Identifier of this distro. Can be used to fetch more informaiton about this distro
provider	string	The service which provides this type of machine

Task Info

Name	Type	Description
task_id	string	Unique Identifier of this task. Can be used to fetch more informaiton about this task
name	string	The name of this task
dispatch_time	time	Time that this task was dispatched to this host
version_id	string	Unique identifier for the version of the project that this task is run as part of
build_id	string	Unique identifier for the build of the project that this task is run as part of

Endpoints

Fetch All Hosts

GET /hosts

Returns a paginated list of all hosts in Evergreen

Parameters

Name	Type	Description
start_at	string	Optional. The identifier of the host to start at in the pagination
limit	int	Optional. The number of hosts to be returned per page of pagination. Defaults to 100
status	string	Optional. A status of host to limit the results to

Fetch Hosts Spawned By User

GET /users/<user_id>/hosts

Returns a list of hosts spawned by the given user.

Parameters

Name	Type	Description
start_at	string	Optional. The identifier of the host to start at in the pagination
limit	int	Optional. The number of hosts to be returned per page of pagination. Defaults to 100
status	string	Optional. A status of host to limit the results to

Fetch Host By ID

GET /hosts/<host_id>

Fetches a single host using its ID

Spawn a Host

POST /hosts

Spawns a host. The host must be of a distro which is spawnable by users (see `Distro`_).

Parameters

Name	Type	Description
distro	string	`Distro`_ name to spawn
keyname	string	`Key`_ name to use

Terminate Host with Given Host ID

POST /hosts/<host_id>/terminate

Immediately terminate a single host with given ID. Users may only terminate hosts which were created by them, unless the user is a super-user.

Hosts which have not been initialised yet will be marked as Terminated.

Trying to terminate a host which has already been terminated will result in an error.

All other host statuses will result in an attempt to terminate using the provider's API

A response code of 200 OK indicates that the host was successfully terminated

All other response codes indicate errors; the response body can be parsed as a rest.APIError

Change RDP Password of Host with Given Host ID

POST /hosts/<host_id>/change_password

Immediately changes the RDP password of a Windows host with a given ID. Users may only change passwords for hosts which were created by them, unless the user is a super-user.

A response code of 200 OK indicates that the host's password was successfully terminated

Attempting to set the RDP password of a host that is not a Windows host or host that is not running will result in an error.

All other response codes indicate errors; the response body can be parsed as a rest.APIError

Change Password

Name	Type	Description
rdp_pwd	string	New RDP password; must meet RDP password criteria as provided by Microsoft at: https://technet.microsoft.com/en-us/library/cc786468(v=ws.10).aspx and be between 6 and 255 characters long

Extend the Expiration of Host with Given Host ID

POST /hosts/<host_id>/extend_expiration

Extend the expiration time of a host with a given ID. Users may only extend expirations for hosts which were created by them, unless the user is a super-user

The expiration date of a host may not be more than 1 week in the future.

A response code of 200 OK indicates that the host's expiration was successfully extended.

Attempt to extend the expiration time of a terminated host will result in an error

All other response codes indicate errors; the response body can be parsed as a rest.APIError

Extend Expiration

Name	Type	Description
add_hours	int	Number of hours to extend expiration; not to exceed 168