Chaya's REST V2 Usage

Task Annotations

Task Annotations give users more context about task failures.

Objects

Annotation

Name	Type	Description
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 task failure
issues	[]issue_link	Links to tickets definitely related
suspected_issues	[]issue_link	Links to tickets possibly related

Note

Name	Type	Description
message	string	Comment about the task failure
source	source_object	The source of the note

Source

Name	Type	Description
author	string	The author of the edit
time	time	The time of the edit
requester	string	The source of the request (api or ui)

Issue Link

Name	Type	Description
url	string	The url of the ticket
issue_key	string	Text to be displayed
source	source_object	The source of the edit

Endpoints

Fetch Task Annotations

GET /tasks/<task_id>/annotations

Returns the latest annotation for the given task, or null if there are no annotations.

Parameters

Name	Type	Description
fetch_all_executions	boolean	Optional. Fetches annotations for all executions of the task if they are available
execution	int	Optional. The 0-based number corresponding to the execution of the task the annotation is associated with. Defaults to the latest execution.

Create or Update a New Task Annotation

PUT tasks/{task_id}/annotation

Creates a task annotation, or updates an existing task annotation, overwriting any existing fields that are included in the update. The annotation is created based on the annotation specified in the request body. If no task_execution is specified in the request body, it will default to the latest execution. Note that usage of this endpoint requires that the requesting user have security to modify task annotations. The user does not need to specify the source, it will be added automatically. Example request body:

{
  "task_id": "my_task_id",
  "note": {
     "message": "this is a note about my_task_id's failure",
  },
  "issues":[
      {
         "url": "https://link.com",
         "issue_key": "link-1234"
      },
  ]
}

List Task Annotations By Build

GET /builds/<build_id>/annotations

Fetches the annotations for all the tasks in a build.

Parameters

Name	Type	Description
fetch_all_executions	boolean	Optional. Fetches annotations for all executions of the task if they are available

List Task Annotations By Version

GET /versions/<version_id>/annotations

Fetches the annotations for all the tasks in a version.

Parameters

Name	Type	Description
fetch_all_executions	boolean	Optional. Fetches annotations for all executions of the task if they are available