Hooks API Documentation


BaseUrl
https://hooks.taskcluster.net/v1

Hooks are a mechanism for creating tasks in response to events.

Hooks are identified with a hookGroupId and a hookId.

When an event occurs, the resulting task is automatically created. The task is created using the scope assume:hook-id:<hookGroupId>/<hookId>, which must have scopes to make the createTask call, including satisfying all scopes in task.scopes. The new task has a taskGroupId equal to its taskId, as is the convention for decision tasks.

Hooks can have a "schedule" indicating specific times that new tasks should be created. Each schedule is in a simple cron format, per https://www.npmjs.com/package/cron-parser. For example:

  • ['0 0 1 * * *'] -- daily at 1:00 UTC
  • ['0 0 9,21 * * 1-5', '0 0 12 * * 0,6'] -- weekdays at 9:00 and 21:00 UTC, weekends at noon

Hooks can be parametrized using JSON-e. The task definition in the hook is used as a JSON-e template, and the paramters are supplied as a JSON-e context. The result of rendeting the template and context is used as the task definition. Currently context can only be provided with the triggerHook method. You can find a complete description about how json-e works, here: https://github.com/taskcluster/json-e

Functions

For more information on invoking the API methods described here, see Using the APIs in the manual.
SignatureSummary
listHookGroups() : resultList hook groups
listHooks(hookGroupId) : resultList hooks in a given group
hook(hookGroupId, hookId) : resultGet hook definition
getHookStatus(hookGroupId, hookId) : resultGet hook status
getHookSchedule(hookGroupId, hookId) : resultGet hook schedule
createHook(hookGroupId, hookId, payload) : resultCreate a hook
updateHook(hookGroupId, hookId, payload) : resultUpdate a hook
removeHook(hookGroupId, hookId) : voidDelete a hook
triggerHook(hookGroupId, hookId, payload) : resultTrigger a hook
getTriggerToken(hookGroupId, hookId) : resultGet a trigger token
resetTriggerToken(hookGroupId, hookId) : resultReset a trigger token
triggerHookWithToken(hookGroupId, hookId, token, payload) : resultTrigger a hook with a token
ping() : voidPing Server

List hook groups

(experimental)

Method
get
Route
/hooks
Signature
listHookGroups() : result
Stability
experimental

This endpoint will return a list of all hook groups with at least one hook.

Response

Hook groups (source)

List of hookGroupIds.

groupsArray of

Groups

string


List hooks in a given group

(experimental)

Method
get
Route
/hooks/<hookGroupId>
Signature
listHooks(hookGroupId) : result
Stability
experimental

This endpoint will return a list of all the hook definitions within a given hook group.

Response

Hook list (source)

List of hooks

hooksArray of

Hooks

hookGroupIdstring[1:22]^([a-zA-Z0-9-_]*)$
hookIdstring[0:255]
metadataObject of

Definition of a hook that will create tasks when defined events occur.

namestring[0:255]

Human readable name of the hook

descriptionstring[0:32768]

Long-form of the hook's purpose and behavior

ownerstring[0:255]

Email of the person or group responsible for this hook.

emailOnErrorboolean
default: true

Whether to email the owner on an error creating the task.

schedule

Definition of the times at which a hook will result in creation of a task. If several patterns are specified, tasks will be created at any time specified by one or more patterns. Note that tasks may not be created at exactly the time specified. {$ref: "http://schemas.taskcluster.net/hooks/v1/schedule.json"}

expiresstring
default: 3 months

Task expiration, time at which task definition and status is deleted. Notice that all artifacts for the must have an expiration that is no later than this. Must be specified as A years B months C days D hours E minutes F seconds, though you may leave out zeros. For more details see: taskcluster.fromNow in taskcluster-client

deadlinestring
default: 1 day

Deadline of the task, pending and running runs are resolved as failed if not resolved by other means before the deadline. Note, deadline cannot be more than 5 days into the future. Must be specified as A years B months C days D hours E minutes F seconds, though you may leave out zeros. For more details see: taskcluster.fromNow in taskcluster-client

taskObject of

Definition of a hook that will create tasks when defined events occur.

provisionerIdstring[1:22]^([a-zA-Z0-9-_]*)$

Unique identifier for a provisioner, that can supply specified workerType

workerTypestring[1:22]^([a-zA-Z0-9-_]*)$

Unique identifier for a worker-type within a specific provisioner

schedulerIdstring[1:22]
default: -
^([a-zA-Z0-9-_]*)$

Identifier for the scheduler that defined this task, this can be an identifier for a user or a service like the "task-graph-scheduler". Task submitter required scopes queue:assume:scheduler-id:<schedulerId>/<taskGroupId>. This scope is also necessary to schedule a defined task, or rerun a task.

taskGroupIdstring^[A-Za-z0-9_-]{8}[Q-T][A-Za-z0-9_-][CGKOSWaeimquy26-][A-Za-z0-9_-]{10}[AQgw]$

Identifier for a group of tasks scheduled together with this task, by scheduler identified by schedulerId. For tasks scheduled by the task-graph scheduler, this is the taskGraphId. Defaults to taskId if property isn't specified.

routesArray of[0:10]
default:

List of task specific routes, AMQP messages will be CC'ed to these routes. Task submitter required scopes queue:route:<route> for each route given.

Task Specific Routestring[1:249]

A task specific route, AMQP messages will be CC'ed with a routing key matching route.<task-specific route>. It's possible to dot (.) in the task specific route to make sub-keys, etc. See the RabbitMQ tutorial for examples on how to use routing-keys.

prioritystring
default: normal
  • high
  • normal

Priority of task, this defaults to normal. Additional levels may be added later. Task submitter required scopes queue:task-priority:high for high priority tasks.

retriesinteger[0:49]
default: 5

Number of times to retry the task in case of infrastructure issues. An infrastructure issue is a worker node that crashes or is shutdown, these events are to be expected.

scopesArray of
default:

List of scopes (or scope-patterns) that the task is authorized to use.

Scopestring^[\x20-\x7e]*$

A scope (or scope-patterns) which the task is authorized to use. This can be a string or a string ending with * which will authorize all scopes for which the string is a prefix. Scopes must be composed of printable ASCII characters and spaces. Task submitter required scopes The same scope-pattern(s) given (otherwise a task could be submitted to perform an action that the task submitter is not authorized to perform).

payloadObject of

Definition of a task embedded in a hook

Anything ¯\_(ツ)_/¯
metadataObject of

Definition of a task embedded in a hook

namestring[0:255]

Human readable name of task, used to very briefly given an idea about what the task does.

descriptionstring[0:32768]

Human readable description of the task, please explain what the task does. A few lines of documentation is not going to hurt you.

ownerstring[0:255]

E-mail of person who caused this task, e.g. the person who did hg push. The person we should contact to ask why this task is here.

sourcestring[0:4096]uri

Link to source of this task, should specify a file, revision and repository. This should be place someone can go an do a git/hg blame to who came up with recipe for this task.

tagsObject of

Definition of a task embedded in a hook

<string>string[0:4096]
extraObject of

Definition of a task embedded in a hook

Anything ¯\_(ツ)_/¯
triggerSchemaObject of

Definition of a hook that will create tasks when defined events occur.

Anything ¯\_(ツ)_/¯


Get hook definition

(experimental)

Method
get
Route
/hooks/<hookGroupId>/<hookId>
Signature
hook(hookGroupId, hookId) : result
Stability
experimental

This endpoint will return the hook definition for the given hookGroupId and hookId.

Response

Hook definition (source)

Definition of a hook that will create tasks when defined events occur.

hookGroupIdstring[1:22]^([a-zA-Z0-9-_]*)$
hookIdstring[0:255]
metadataObject of

Definition of a hook that will create tasks when defined events occur.

namestring[0:255]

Human readable name of the hook

descriptionstring[0:32768]

Long-form of the hook's purpose and behavior

ownerstring[0:255]

Email of the person or group responsible for this hook.

emailOnErrorboolean
default: true

Whether to email the owner on an error creating the task.

schedule

Definition of the times at which a hook will result in creation of a task. If several patterns are specified, tasks will be created at any time specified by one or more patterns. Note that tasks may not be created at exactly the time specified. {$ref: "http://schemas.taskcluster.net/hooks/v1/schedule.json"}

expiresstring
default: 3 months

Task expiration, time at which task definition and status is deleted. Notice that all artifacts for the must have an expiration that is no later than this. Must be specified as A years B months C days D hours E minutes F seconds, though you may leave out zeros. For more details see: taskcluster.fromNow in taskcluster-client

deadlinestring
default: 1 day

Deadline of the task, pending and running runs are resolved as failed if not resolved by other means before the deadline. Note, deadline cannot be more than 5 days into the future. Must be specified as A years B months C days D hours E minutes F seconds, though you may leave out zeros. For more details see: taskcluster.fromNow in taskcluster-client

taskObject of

Definition of a hook that will create tasks when defined events occur.

provisionerIdstring[1:22]^([a-zA-Z0-9-_]*)$

Unique identifier for a provisioner, that can supply specified workerType

workerTypestring[1:22]^([a-zA-Z0-9-_]*)$

Unique identifier for a worker-type within a specific provisioner

schedulerIdstring[1:22]
default: -
^([a-zA-Z0-9-_]*)$

Identifier for the scheduler that defined this task, this can be an identifier for a user or a service like the "task-graph-scheduler". Task submitter required scopes queue:assume:scheduler-id:<schedulerId>/<taskGroupId>. This scope is also necessary to schedule a defined task, or rerun a task.

taskGroupIdstring^[A-Za-z0-9_-]{8}[Q-T][A-Za-z0-9_-][CGKOSWaeimquy26-][A-Za-z0-9_-]{10}[AQgw]$

Identifier for a group of tasks scheduled together with this task, by scheduler identified by schedulerId. For tasks scheduled by the task-graph scheduler, this is the taskGraphId. Defaults to taskId if property isn't specified.

routesArray of[0:10]
default:

List of task specific routes, AMQP messages will be CC'ed to these routes. Task submitter required scopes queue:route:<route> for each route given.

Task Specific Routestring[1:249]

A task specific route, AMQP messages will be CC'ed with a routing key matching route.<task-specific route>. It's possible to dot (.) in the task specific route to make sub-keys, etc. See the RabbitMQ tutorial for examples on how to use routing-keys.

prioritystring
default: normal
  • high
  • normal

Priority of task, this defaults to normal. Additional levels may be added later. Task submitter required scopes queue:task-priority:high for high priority tasks.

retriesinteger[0:49]
default: 5

Number of times to retry the task in case of infrastructure issues. An infrastructure issue is a worker node that crashes or is shutdown, these events are to be expected.

scopesArray of
default:

List of scopes (or scope-patterns) that the task is authorized to use.

Scopestring^[\x20-\x7e]*$

A scope (or scope-patterns) which the task is authorized to use. This can be a string or a string ending with * which will authorize all scopes for which the string is a prefix. Scopes must be composed of printable ASCII characters and spaces. Task submitter required scopes The same scope-pattern(s) given (otherwise a task could be submitted to perform an action that the task submitter is not authorized to perform).

payloadObject of

Definition of a task embedded in a hook

Anything ¯\_(ツ)_/¯
metadataObject of

Definition of a task embedded in a hook

namestring[0:255]

Human readable name of task, used to very briefly given an idea about what the task does.

descriptionstring[0:32768]

Human readable description of the task, please explain what the task does. A few lines of documentation is not going to hurt you.

ownerstring[0:255]

E-mail of person who caused this task, e.g. the person who did hg push. The person we should contact to ask why this task is here.

sourcestring[0:4096]uri

Link to source of this task, should specify a file, revision and repository. This should be place someone can go an do a git/hg blame to who came up with recipe for this task.

tagsObject of

Definition of a task embedded in a hook

<string>string[0:4096]
extraObject of

Definition of a task embedded in a hook

Anything ¯\_(ツ)_/¯
triggerSchemaObject of

Definition of a hook that will create tasks when defined events occur.

Anything ¯\_(ツ)_/¯


Get hook status

(experimental)

Method
get
Route
/hooks/<hookGroupId>/<hookId>/status
Signature
getHookStatus(hookGroupId, hookId) : result
Stability
experimental

This endpoint will return the current status of the hook. This represents a snapshot in time and may vary from one call to the next.

Response

Hook status response (source)

A snapshot of the current status of a hook.

lastFireObject of

A snapshot of the current status of a hook.

One of

Information about the last time this hook fired. This property is only present if the hook has fired at least once.

Object of

Information about a successful firing of the hook

resultstring
  • success
taskIdstring^[A-Za-z0-9_-]{8}[Q-T][A-Za-z0-9_-][CGKOSWaeimquy26-][A-Za-z0-9_-]{10}[AQgw]$

The task created

timestringdate-time

The time the task was created. This will not necessarily match task.created.

Object of

Information about an unsuccessful firing of the hook

resultstring
  • error
errorObject of

Information about an unsuccessful firing of the hook

Anything ¯\_(ツ)_/¯
timestringdate-time

The time the task was created. This will not necessarily match task.created.

Object of

Information about no firing of the hook (e.g., a new hook)

resultstring
  • no-fire
nextScheduledDatestringdate-time

The next time this hook's task is scheduled to be created. This property is only present if there is a scheduled next time. Some hooks don't have any schedules.



Get hook schedule

(deprecated)

Method
get
Route
/hooks/<hookGroupId>/<hookId>/schedule
Signature
getHookSchedule(hookGroupId, hookId) : result
Stability
deprecated

This endpoint will return the schedule and next scheduled creation time for the given hook.

Response

Hook schedule response (source)

A description of when a hook's task will be created, and the next scheduled time

scheduleArray of
default:

A list of cron-style definitions to represent a set of moments in (UTC) time. If several patterns are specified, a given moment in time represented by more than one pattern is considered only to be counted once, in other words it is allowed for the cron patterns to overlap; duplicates are redundant.

Cron Patternstring

Cron-like specification for when tasks should be created. The pattern is parsed in a UTC context. See cron-parser on npm.

nextScheduledDatestringdate-time

The next time this hook's task is scheduled to be created. This property is only present if there is a scheduled next time. Some hooks don't have any schedules.



Create a hook

(experimental)

Method
put
Route
/hooks/<hookGroupId>/<hookId>
Scopes
hooks:modify-hook:<hookGroupId>/<hookId>

assume:hook-id:<hookGroupId>/<hookId>
Signature
createHook(hookGroupId, hookId, payload) : result
Stability
experimental

This endpoint will create a new hook.

The caller's credentials must include the role that will be used to create the task. That role must satisfy task.scopes as well as the necessary scopes to add the task to the queue.

Request Payload

Hook creation request (source)

Definition of a hook that can create tasks at defined times.

metadataObject of

Definition of a hook that can create tasks at defined times.

namestring[0:255]

Human readable name of the hook

descriptionstring[0:32768]

Long-form of the hook's purpose and behavior

ownerstring[0:255]

Email of the person or group responsible for this hook.

emailOnErrorboolean
default: true

Whether to email the owner on an error creating the task.

scheduleArray of
default:

Definition of the times at which a hook will result in creation of a task. If several patterns are specified, tasks will be created at any time specified by one or more patterns.

Cron Patternstring

Cron-like specification for when tasks should be created. The pattern is parsed in a UTC context. See cron-parser on npm. Note that tasks may not be created at exactly the time specified.

expiresstring
default: 3 months

Task expiration, time at which task definition and status is deleted. Notice that all artifacts for the must have an expiration that is no later than this. Must be specified as A years B months C days D hours E minutes F seconds, though you may leave out zeros. For more details see: taskcluster.fromNow in taskcluster-client

deadlinestring
default: 1 day

Deadline of the task, pending and running runs are resolved as failed if not resolved by other means before the deadline. Note, deadline cannot be more than 5 days into the future. Must be specified as A years B months C days D hours E minutes F seconds, though you may leave out zeros. For more details see: taskcluster.fromNow in taskcluster-client

taskObject of

Definition of a hook that can create tasks at defined times.

provisionerIdstring[1:22]^([a-zA-Z0-9-_]*)$

Unique identifier for a provisioner, that can supply specified workerType

workerTypestring[1:22]^([a-zA-Z0-9-_]*)$

Unique identifier for a worker-type within a specific provisioner

schedulerIdstring[1:22]
default: -
^([a-zA-Z0-9-_]*)$

Identifier for the scheduler that defined this task, this can be an identifier for a user or a service like the "task-graph-scheduler". Task submitter required scopes queue:assume:scheduler-id:<schedulerId>/<taskGroupId>. This scope is also necessary to schedule a defined task, or rerun a task.

taskGroupIdstring^[A-Za-z0-9_-]{8}[Q-T][A-Za-z0-9_-][CGKOSWaeimquy26-][A-Za-z0-9_-]{10}[AQgw]$

Identifier for a group of tasks scheduled together with this task, by scheduler identified by schedulerId. For tasks scheduled by the task-graph scheduler, this is the taskGraphId. Defaults to taskId if property isn't specified.

routesArray of[0:10]
default:

List of task specific routes, AMQP messages will be CC'ed to these routes. Task submitter required scopes queue:route:<route> for each route given.

Task Specific Routestring[1:249]

A task specific route, AMQP messages will be CC'ed with a routing key matching route.<task-specific route>. It's possible to dot (.) in the task specific route to make sub-keys, etc. See the RabbitMQ tutorial for examples on how to use routing-keys.

prioritystring
default: normal
  • high
  • normal

Priority of task, this defaults to normal. Additional levels may be added later. Task submitter required scopes queue:task-priority:high for high priority tasks.

retriesinteger[0:49]
default: 5

Number of times to retry the task in case of infrastructure issues. An infrastructure issue is a worker node that crashes or is shutdown, these events are to be expected.

scopesArray of
default:

List of scopes (or scope-patterns) that the task is authorized to use.

Scopestring^[\x20-\x7e]*$

A scope (or scope-patterns) which the task is authorized to use. This can be a string or a string ending with * which will authorize all scopes for which the string is a prefix. Scopes must be composed of printable ASCII characters and spaces. Task submitter required scopes The same scope-pattern(s) given (otherwise a task could be submitted to perform an action that the task submitter is not authorized to perform).

payloadObject of

Definition of a task embedded in a hook

Anything ¯\_(ツ)_/¯
metadataObject of

Definition of a task embedded in a hook

namestring[0:255]

Human readable name of task, used to very briefly given an idea about what the task does.

descriptionstring[0:32768]

Human readable description of the task, please explain what the task does. A few lines of documentation is not going to hurt you.

ownerstring[0:255]

E-mail of person who caused this task, e.g. the person who did hg push. The person we should contact to ask why this task is here.

sourcestring[0:4096]uri

Link to source of this task, should specify a file, revision and repository. This should be place someone can go an do a git/hg blame to who came up with recipe for this task.

tagsObject of

Definition of a task embedded in a hook

<string>string[0:4096]
extraObject of

Definition of a task embedded in a hook

Anything ¯\_(ツ)_/¯
triggerSchemaObject of

Definition of a hook that can create tasks at defined times.

Anything ¯\_(ツ)_/¯

Response

Hook definition (source)

Definition of a hook that will create tasks when defined events occur.

hookGroupIdstring[1:22]^([a-zA-Z0-9-_]*)$
hookIdstring[0:255]
metadataObject of

Definition of a hook that will create tasks when defined events occur.

namestring[0:255]

Human readable name of the hook

descriptionstring[0:32768]

Long-form of the hook's purpose and behavior

ownerstring[0:255]

Email of the person or group responsible for this hook.

emailOnErrorboolean
default: true

Whether to email the owner on an error creating the task.

schedule

Definition of the times at which a hook will result in creation of a task. If several patterns are specified, tasks will be created at any time specified by one or more patterns. Note that tasks may not be created at exactly the time specified. {$ref: "http://schemas.taskcluster.net/hooks/v1/schedule.json"}

expiresstring
default: 3 months

Task expiration, time at which task definition and status is deleted. Notice that all artifacts for the must have an expiration that is no later than this. Must be specified as A years B months C days D hours E minutes F seconds, though you may leave out zeros. For more details see: taskcluster.fromNow in taskcluster-client

deadlinestring
default: 1 day

Deadline of the task, pending and running runs are resolved as failed if not resolved by other means before the deadline. Note, deadline cannot be more than 5 days into the future. Must be specified as A years B months C days D hours E minutes F seconds, though you may leave out zeros. For more details see: taskcluster.fromNow in taskcluster-client

taskObject of

Definition of a hook that will create tasks when defined events occur.

provisionerIdstring[1:22]^([a-zA-Z0-9-_]*)$

Unique identifier for a provisioner, that can supply specified workerType

workerTypestring[1:22]^([a-zA-Z0-9-_]*)$

Unique identifier for a worker-type within a specific provisioner

schedulerIdstring[1:22]
default: -
^([a-zA-Z0-9-_]*)$

Identifier for the scheduler that defined this task, this can be an identifier for a user or a service like the "task-graph-scheduler". Task submitter required scopes queue:assume:scheduler-id:<schedulerId>/<taskGroupId>. This scope is also necessary to schedule a defined task, or rerun a task.

taskGroupIdstring^[A-Za-z0-9_-]{8}[Q-T][A-Za-z0-9_-][CGKOSWaeimquy26-][A-Za-z0-9_-]{10}[AQgw]$

Identifier for a group of tasks scheduled together with this task, by scheduler identified by schedulerId. For tasks scheduled by the task-graph scheduler, this is the taskGraphId. Defaults to taskId if property isn't specified.

routesArray of[0:10]
default:

List of task specific routes, AMQP messages will be CC'ed to these routes. Task submitter required scopes queue:route:<route> for each route given.

Task Specific Routestring[1:249]

A task specific route, AMQP messages will be CC'ed with a routing key matching route.<task-specific route>. It's possible to dot (.) in the task specific route to make sub-keys, etc. See the RabbitMQ tutorial for examples on how to use routing-keys.

prioritystring
default: normal
  • high
  • normal

Priority of task, this defaults to normal. Additional levels may be added later. Task submitter required scopes queue:task-priority:high for high priority tasks.

retriesinteger[0:49]
default: 5

Number of times to retry the task in case of infrastructure issues. An infrastructure issue is a worker node that crashes or is shutdown, these events are to be expected.

scopesArray of
default:

List of scopes (or scope-patterns) that the task is authorized to use.

Scopestring^[\x20-\x7e]*$

A scope (or scope-patterns) which the task is authorized to use. This can be a string or a string ending with * which will authorize all scopes for which the string is a prefix. Scopes must be composed of printable ASCII characters and spaces. Task submitter required scopes The same scope-pattern(s) given (otherwise a task could be submitted to perform an action that the task submitter is not authorized to perform).

payloadObject of

Definition of a task embedded in a hook

Anything ¯\_(ツ)_/¯
metadataObject of

Definition of a task embedded in a hook

namestring[0:255]

Human readable name of task, used to very briefly given an idea about what the task does.

descriptionstring[0:32768]

Human readable description of the task, please explain what the task does. A few lines of documentation is not going to hurt you.

ownerstring[0:255]

E-mail of person who caused this task, e.g. the person who did hg push. The person we should contact to ask why this task is here.

sourcestring[0:4096]uri

Link to source of this task, should specify a file, revision and repository. This should be place someone can go an do a git/hg blame to who came up with recipe for this task.

tagsObject of

Definition of a task embedded in a hook

<string>string[0:4096]
extraObject of

Definition of a task embedded in a hook

Anything ¯\_(ツ)_/¯
triggerSchemaObject of

Definition of a hook that will create tasks when defined events occur.

Anything ¯\_(ツ)_/¯


Update a hook

(experimental)

Method
post
Route
/hooks/<hookGroupId>/<hookId>
Scopes
hooks:modify-hook:<hookGroupId>/<hookId>

assume:hook-id:<hookGroupId>/<hookId>
Signature
updateHook(hookGroupId, hookId, payload) : result
Stability
experimental

This endpoint will update an existing hook. All fields except hookGroupId and hookId can be modified.

Request Payload

Hook creation request (source)

Definition of a hook that can create tasks at defined times.

metadataObject of

Definition of a hook that can create tasks at defined times.

namestring[0:255]

Human readable name of the hook

descriptionstring[0:32768]

Long-form of the hook's purpose and behavior

ownerstring[0:255]

Email of the person or group responsible for this hook.

emailOnErrorboolean
default: true

Whether to email the owner on an error creating the task.

scheduleArray of
default:

Definition of the times at which a hook will result in creation of a task. If several patterns are specified, tasks will be created at any time specified by one or more patterns.

Cron Patternstring

Cron-like specification for when tasks should be created. The pattern is parsed in a UTC context. See cron-parser on npm. Note that tasks may not be created at exactly the time specified.

expiresstring
default: 3 months

Task expiration, time at which task definition and status is deleted. Notice that all artifacts for the must have an expiration that is no later than this. Must be specified as A years B months C days D hours E minutes F seconds, though you may leave out zeros. For more details see: taskcluster.fromNow in taskcluster-client

deadlinestring
default: 1 day

Deadline of the task, pending and running runs are resolved as failed if not resolved by other means before the deadline. Note, deadline cannot be more than 5 days into the future. Must be specified as A years B months C days D hours E minutes F seconds, though you may leave out zeros. For more details see: taskcluster.fromNow in taskcluster-client

taskObject of

Definition of a hook that can create tasks at defined times.

provisionerIdstring[1:22]^([a-zA-Z0-9-_]*)$

Unique identifier for a provisioner, that can supply specified workerType

workerTypestring[1:22]^([a-zA-Z0-9-_]*)$

Unique identifier for a worker-type within a specific provisioner

schedulerIdstring[1:22]
default: -
^([a-zA-Z0-9-_]*)$

Identifier for the scheduler that defined this task, this can be an identifier for a user or a service like the "task-graph-scheduler". Task submitter required scopes queue:assume:scheduler-id:<schedulerId>/<taskGroupId>. This scope is also necessary to schedule a defined task, or rerun a task.

taskGroupIdstring^[A-Za-z0-9_-]{8}[Q-T][A-Za-z0-9_-][CGKOSWaeimquy26-][A-Za-z0-9_-]{10}[AQgw]$

Identifier for a group of tasks scheduled together with this task, by scheduler identified by schedulerId. For tasks scheduled by the task-graph scheduler, this is the taskGraphId. Defaults to taskId if property isn't specified.

routesArray of[0:10]
default:

List of task specific routes, AMQP messages will be CC'ed to these routes. Task submitter required scopes queue:route:<route> for each route given.

Task Specific Routestring[1:249]

A task specific route, AMQP messages will be CC'ed with a routing key matching route.<task-specific route>. It's possible to dot (.) in the task specific route to make sub-keys, etc. See the RabbitMQ tutorial for examples on how to use routing-keys.

prioritystring
default: normal
  • high
  • normal

Priority of task, this defaults to normal. Additional levels may be added later. Task submitter required scopes queue:task-priority:high for high priority tasks.

retriesinteger[0:49]
default: 5

Number of times to retry the task in case of infrastructure issues. An infrastructure issue is a worker node that crashes or is shutdown, these events are to be expected.

scopesArray of
default:

List of scopes (or scope-patterns) that the task is authorized to use.

Scopestring^[\x20-\x7e]*$

A scope (or scope-patterns) which the task is authorized to use. This can be a string or a string ending with * which will authorize all scopes for which the string is a prefix. Scopes must be composed of printable ASCII characters and spaces. Task submitter required scopes The same scope-pattern(s) given (otherwise a task could be submitted to perform an action that the task submitter is not authorized to perform).

payloadObject of

Definition of a task embedded in a hook

Anything ¯\_(ツ)_/¯
metadataObject of

Definition of a task embedded in a hook

namestring[0:255]

Human readable name of task, used to very briefly given an idea about what the task does.

descriptionstring[0:32768]

Human readable description of the task, please explain what the task does. A few lines of documentation is not going to hurt you.

ownerstring[0:255]

E-mail of person who caused this task, e.g. the person who did hg push. The person we should contact to ask why this task is here.

sourcestring[0:4096]uri

Link to source of this task, should specify a file, revision and repository. This should be place someone can go an do a git/hg blame to who came up with recipe for this task.

tagsObject of

Definition of a task embedded in a hook

<string>string[0:4096]
extraObject of

Definition of a task embedded in a hook

Anything ¯\_(ツ)_/¯
triggerSchemaObject of

Definition of a hook that can create tasks at defined times.

Anything ¯\_(ツ)_/¯

Response

Hook definition (source)

Definition of a hook that will create tasks when defined events occur.

hookGroupIdstring[1:22]^([a-zA-Z0-9-_]*)$
hookIdstring[0:255]
metadataObject of

Definition of a hook that will create tasks when defined events occur.

namestring[0:255]

Human readable name of the hook

descriptionstring[0:32768]

Long-form of the hook's purpose and behavior

ownerstring[0:255]

Email of the person or group responsible for this hook.

emailOnErrorboolean
default: true

Whether to email the owner on an error creating the task.

schedule

Definition of the times at which a hook will result in creation of a task. If several patterns are specified, tasks will be created at any time specified by one or more patterns. Note that tasks may not be created at exactly the time specified. {$ref: "http://schemas.taskcluster.net/hooks/v1/schedule.json"}

expiresstring
default: 3 months

Task expiration, time at which task definition and status is deleted. Notice that all artifacts for the must have an expiration that is no later than this. Must be specified as A years B months C days D hours E minutes F seconds, though you may leave out zeros. For more details see: taskcluster.fromNow in taskcluster-client

deadlinestring
default: 1 day

Deadline of the task, pending and running runs are resolved as failed if not resolved by other means before the deadline. Note, deadline cannot be more than 5 days into the future. Must be specified as A years B months C days D hours E minutes F seconds, though you may leave out zeros. For more details see: taskcluster.fromNow in taskcluster-client

taskObject of

Definition of a hook that will create tasks when defined events occur.

provisionerIdstring[1:22]^([a-zA-Z0-9-_]*)$

Unique identifier for a provisioner, that can supply specified workerType

workerTypestring[1:22]^([a-zA-Z0-9-_]*)$

Unique identifier for a worker-type within a specific provisioner

schedulerIdstring[1:22]
default: -
^([a-zA-Z0-9-_]*)$

Identifier for the scheduler that defined this task, this can be an identifier for a user or a service like the "task-graph-scheduler". Task submitter required scopes queue:assume:scheduler-id:<schedulerId>/<taskGroupId>. This scope is also necessary to schedule a defined task, or rerun a task.

taskGroupIdstring^[A-Za-z0-9_-]{8}[Q-T][A-Za-z0-9_-][CGKOSWaeimquy26-][A-Za-z0-9_-]{10}[AQgw]$

Identifier for a group of tasks scheduled together with this task, by scheduler identified by schedulerId. For tasks scheduled by the task-graph scheduler, this is the taskGraphId. Defaults to taskId if property isn't specified.

routesArray of[0:10]
default:

List of task specific routes, AMQP messages will be CC'ed to these routes. Task submitter required scopes queue:route:<route> for each route given.

Task Specific Routestring[1:249]

A task specific route, AMQP messages will be CC'ed with a routing key matching route.<task-specific route>. It's possible to dot (.) in the task specific route to make sub-keys, etc. See the RabbitMQ tutorial for examples on how to use routing-keys.

prioritystring
default: normal
  • high
  • normal

Priority of task, this defaults to normal. Additional levels may be added later. Task submitter required scopes queue:task-priority:high for high priority tasks.

retriesinteger[0:49]
default: 5

Number of times to retry the task in case of infrastructure issues. An infrastructure issue is a worker node that crashes or is shutdown, these events are to be expected.

scopesArray of
default:

List of scopes (or scope-patterns) that the task is authorized to use.

Scopestring^[\x20-\x7e]*$

A scope (or scope-patterns) which the task is authorized to use. This can be a string or a string ending with * which will authorize all scopes for which the string is a prefix. Scopes must be composed of printable ASCII characters and spaces. Task submitter required scopes The same scope-pattern(s) given (otherwise a task could be submitted to perform an action that the task submitter is not authorized to perform).

payloadObject of

Definition of a task embedded in a hook

Anything ¯\_(ツ)_/¯
metadataObject of

Definition of a task embedded in a hook

namestring[0:255]

Human readable name of task, used to very briefly given an idea about what the task does.

descriptionstring[0:32768]

Human readable description of the task, please explain what the task does. A few lines of documentation is not going to hurt you.

ownerstring[0:255]

E-mail of person who caused this task, e.g. the person who did hg push. The person we should contact to ask why this task is here.

sourcestring[0:4096]uri

Link to source of this task, should specify a file, revision and repository. This should be place someone can go an do a git/hg blame to who came up with recipe for this task.

tagsObject of

Definition of a task embedded in a hook

<string>string[0:4096]
extraObject of

Definition of a task embedded in a hook

Anything ¯\_(ツ)_/¯
triggerSchemaObject of

Definition of a hook that will create tasks when defined events occur.

Anything ¯\_(ツ)_/¯


Delete a hook

(experimental)

Method
delete
Route
/hooks/<hookGroupId>/<hookId>
Scopes
hooks:modify-hook:<hookGroupId>/<hookId>
Signature
removeHook(hookGroupId, hookId) : void
Stability
experimental

This endpoint will remove a hook definition.



Trigger a hook

(experimental)

Method
post
Route
/hooks/<hookGroupId>/<hookId>/trigger
Scopes
hooks:trigger-hook:<hookGroupId>/<hookId>
Signature
triggerHook(hookGroupId, hookId, payload) : result
Stability
experimental

This endpoint will trigger the creation of a task from a hook definition.

Request Payload

trigger context (source)

Trigger context

Anything ¯\_(ツ)_/¯

Response

Task Status Structure (source)

A representation of task status as known by the queue

statusObject of

A representation of task status as known by the queue

taskIdstring^[A-Za-z0-9_-]{8}[Q-T][A-Za-z0-9_-][CGKOSWaeimquy26-][A-Za-z0-9_-]{10}[AQgw]$

Unique task identifier, this is UUID encoded as URL-safe base64 and stripped of = padding.

provisionerIdstring[1:22]^([a-zA-Z0-9-_]*)$

Unique identifier for the provisioner that this task must be scheduled on

workerTypestring[1:22]^([a-zA-Z0-9-_]*)$

Identifier for worker type within the specified provisioner

schedulerIdstring[1:22]^([a-zA-Z0-9-_]*)$

Identifier for the scheduler that defined this task.

taskGroupIdstring^[A-Za-z0-9_-]{8}[Q-T][A-Za-z0-9_-][CGKOSWaeimquy26-][A-Za-z0-9_-]{10}[AQgw]$

Identifier for a group of tasks scheduled together with this task, by scheduler identified by schedulerId. For tasks scheduled by the task-graph scheduler, this is the taskGraphId.

deadlinestring
default: 1 day

Deadline of the task, pending and running runs are resolved as failed if not resolved by other means before the deadline. Note, deadline cannot be more than 5 days into the future. Must be specified as A years B months C days D hours E minutes F seconds, though you may leave out zeros. For more details see: taskcluster.fromNow in taskcluster-client

expiresstring
default: 3 months

Task expiration, time at which task definition and status is deleted. Notice that all artifacts for the must have an expiration that is no later than this. Must be specified as A years B months C days D hours E minutes F seconds, though you may leave out zeros. For more details see: taskcluster.fromNow in taskcluster-client

retriesLeftinteger[0:999]

Number of retries left for the task in case of infrastructure issues

statestring
  • unscheduled
  • pending
  • running
  • completed
  • failed
  • exception

State of this task. This is just an auxiliary property derived from state of latests run, or unscheduled if none.

runsArray of

List of runs, ordered so that index i has runId == i

runIdinteger[0:1000]

Id of this task run, run-ids always starts from 0

statestring
  • pending
  • running
  • completed
  • failed
  • exception

State of this run

reasonCreatedstring
  • scheduled
  • retry
  • task-retry
  • rerun
  • exception

Reason for the creation of this run, more reasons may be added in the future.

reasonResolvedstring
  • completed
  • failed
  • deadline-exceeded
  • canceled
  • superseded
  • claim-expired
  • worker-shutdown
  • malformed-payload
  • resource-unavailable
  • internal-error
  • intermittent-task

Reason that run was resolved, this is mainly useful for runs resolved as exception. Note, more reasons may be added in the future, also this property is only available after the run is resolved.

workerGroupstring[1:22]^([a-zA-Z0-9-_]*)$

Identifier for group that worker who executes this run is a part of, this identifier is mainly used for efficient routing. Note, this property is only present after the run is claimed.

workerIdstring[1:22]^([a-zA-Z0-9-_]*)$

Identifier for worker evaluating this run within given workerGroup. Note, this property is only available after the run has been claimed.

takenUntilstringdate-time

Time at which the run expires and is resolved as failed, if the run isn't reclaimed. Note, only present after the run has been claimed.

scheduledstringdate-time

Date-time at which this run was scheduled, ie. when the run was created in state pending.

startedstringdate-time

Date-time at which this run was claimed, ie. when the run changed state from pending to running. This property is only present after the run has been claimed.

resolvedstringdate-time

Date-time at which this run was resolved, ie. when the run changed state from running to either completed, failed or exception. This property is only present after the run as been resolved.



Get a trigger token

(experimental)

Method
get
Route
/hooks/<hookGroupId>/<hookId>/token
Scopes
hooks:get-trigger-token:<hookGroupId>/<hookId>
Signature
getTriggerToken(hookGroupId, hookId) : result
Stability
experimental

Retrieve a unique secret token for triggering the specified hook. This token can be deactivated with resetTriggerToken.

Response

trigger token response (source)

Secret token for a trigger

tokenstring

Token



Reset a trigger token

(experimental)

Method
post
Route
/hooks/<hookGroupId>/<hookId>/token
Scopes
hooks:reset-trigger-token:<hookGroupId>/<hookId>
Signature
resetTriggerToken(hookGroupId, hookId) : result
Stability
experimental

Reset the token for triggering a given hook. This invalidates token that may have been issued via getTriggerToken with a new token.

Response

trigger token response (source)

Secret token for a trigger

tokenstring

Token



Trigger a hook with a token

(experimental)

Method
post
Route
/hooks/<hookGroupId>/<hookId>/trigger/<token>
Signature
triggerHookWithToken(hookGroupId, hookId, token, payload) : result
Stability
experimental

This endpoint triggers a defined hook with a valid token.

Request Payload

trigger context (source)

Trigger context

Anything ¯\_(ツ)_/¯

Response

Task Status Structure (source)

A representation of task status as known by the queue

statusObject of

A representation of task status as known by the queue

taskIdstring^[A-Za-z0-9_-]{8}[Q-T][A-Za-z0-9_-][CGKOSWaeimquy26-][A-Za-z0-9_-]{10}[AQgw]$

Unique task identifier, this is UUID encoded as URL-safe base64 and stripped of = padding.

provisionerIdstring[1:22]^([a-zA-Z0-9-_]*)$

Unique identifier for the provisioner that this task must be scheduled on

workerTypestring[1:22]^([a-zA-Z0-9-_]*)$

Identifier for worker type within the specified provisioner

schedulerIdstring[1:22]^([a-zA-Z0-9-_]*)$

Identifier for the scheduler that defined this task.

taskGroupIdstring^[A-Za-z0-9_-]{8}[Q-T][A-Za-z0-9_-][CGKOSWaeimquy26-][A-Za-z0-9_-]{10}[AQgw]$

Identifier for a group of tasks scheduled together with this task, by scheduler identified by schedulerId. For tasks scheduled by the task-graph scheduler, this is the taskGraphId.

deadlinestring
default: 1 day

Deadline of the task, pending and running runs are resolved as failed if not resolved by other means before the deadline. Note, deadline cannot be more than 5 days into the future. Must be specified as A years B months C days D hours E minutes F seconds, though you may leave out zeros. For more details see: taskcluster.fromNow in taskcluster-client

expiresstring
default: 3 months

Task expiration, time at which task definition and status is deleted. Notice that all artifacts for the must have an expiration that is no later than this. Must be specified as A years B months C days D hours E minutes F seconds, though you may leave out zeros. For more details see: taskcluster.fromNow in taskcluster-client

retriesLeftinteger[0:999]

Number of retries left for the task in case of infrastructure issues

statestring
  • unscheduled
  • pending
  • running
  • completed
  • failed
  • exception

State of this task. This is just an auxiliary property derived from state of latests run, or unscheduled if none.

runsArray of

List of runs, ordered so that index i has runId == i

runIdinteger[0:1000]

Id of this task run, run-ids always starts from 0

statestring
  • pending
  • running
  • completed
  • failed
  • exception

State of this run

reasonCreatedstring
  • scheduled
  • retry
  • task-retry
  • rerun
  • exception

Reason for the creation of this run, more reasons may be added in the future.

reasonResolvedstring
  • completed
  • failed
  • deadline-exceeded
  • canceled
  • superseded
  • claim-expired
  • worker-shutdown
  • malformed-payload
  • resource-unavailable
  • internal-error
  • intermittent-task

Reason that run was resolved, this is mainly useful for runs resolved as exception. Note, more reasons may be added in the future, also this property is only available after the run is resolved.

workerGroupstring[1:22]^([a-zA-Z0-9-_]*)$

Identifier for group that worker who executes this run is a part of, this identifier is mainly used for efficient routing. Note, this property is only present after the run is claimed.

workerIdstring[1:22]^([a-zA-Z0-9-_]*)$

Identifier for worker evaluating this run within given workerGroup. Note, this property is only available after the run has been claimed.

takenUntilstringdate-time

Time at which the run expires and is resolved as failed, if the run isn't reclaimed. Note, only present after the run has been claimed.

scheduledstringdate-time

Date-time at which this run was scheduled, ie. when the run was created in state pending.

startedstringdate-time

Date-time at which this run was claimed, ie. when the run changed state from pending to running. This property is only present after the run has been claimed.

resolvedstringdate-time

Date-time at which this run was resolved, ie. when the run changed state from running to either completed, failed or exception. This property is only present after the run as been resolved.



Ping Server

Method
get
Route
/ping
Signature
ping() : void
Stability
stable

Respond without doing anything. This endpoint is used to check that the service is up.