Chaya's REST V2 Usage

Task Annotations

Task Annotations give users more context about task failures.

Objects

Host

Name	Type	Description
id	string	Unique identifier of this task annotation
task_id	string	Identifier of the task that this annotation is for
task_execution	int	The number of the execution of the task that the annotation is for
metadata	map[string]interface{}	Structured data about the task. Since this is user-given json data, the structure can differ between annotations
note	note_object	Comment about the failure
issues	[IssueLink]	Links to tickets definitely related
suspected_issues	[IssueLink]	Links to tickets possibly related

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