OpenAPI operations

Create or replace an automation task

PUT

/v1/tasks/{name}

const url = 'https://api.hooks.events/v1/tasks/example';
const options = {method: 'PUT', headers: {Authorization: 'Bearer <token>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request PUT \
  --url https://api.hooks.events/v1/tasks/example \
  --header 'Authorization: Bearer <token>'

Authorizations

apiKey
sessionCookie

Parameters

Path Parameters

name

required

string

Responses

200

Success

application/json

object

task

required

Stored automation task

object

required

Resource id

string

name

required

string

enabled

required

boolean

environmentId

required

string | null

environment

required

string | null

trigger

required

Trigger entries in dispatch order; the first match starts the run

Array<object>

object

source

required

Source adapter id, e.g. github, or * to match any source

string

event

required

Event type, e.g. issues.labeled, or * to match any event type

string

filter

required

AND-ed condition strings evaluated against the source payload, e.g. {{event.label.name}} == 'agent'

Array<string>

throttle

Optional per-key rate limit applied after the entry matches

object

key

required

Template rendered per event, e.g. {{event.issue.number}}

string

max

required

Maximum admitted runs per key per window

integer

>= -9007199254740991 <= 9007199254740991

windowMinutes

required

Throttle window in minutes

integer

>= -9007199254740991 <= 9007199254740991

task

required

Automation task definition

object

name

required

string

trigger

Trigger entries, evaluated in order; the first entry whose source, event and filters match starts the run. Matching is workspace-wide on source plus event type, not per endpoint. Omitted on schedule-only tasks.

Array<object>

object

source

required

Source adapter id, e.g. github, or * to match any source

string

event

required

Event type, e.g. issues.labeled, or * to match any event type

string

filter

required

AND-ed condition strings evaluated against the source payload, e.g. {{event.label.name}} == 'agent'

Array<string>

throttle

Optional per-key rate limit applied after the entry matches

object

key

required

Template rendered per event, e.g. {{event.issue.number}}

string

max

required

Maximum admitted runs per key per window

integer

>= -9007199254740991 <= 9007199254740991

windowMinutes

required

Throttle window in minutes

integer

>= -9007199254740991 <= 9007199254740991

schedule

Cron schedule. A task needs an event trigger, a schedule, or both; each tick starts one run, and missed ticks collapse into a single late run.

object

cron

required

Five-field cron: minute hour day-of-month month day-of-week

string

timezone

required

IANA timezone, e.g. Asia/Tokyo

string

agent

required

Any of:

object
null

object

trigger

required

object

label

required

Issue label that starts the run

string

skipLabels

required

Array<string>

requireCollaborator

required

boolean

frequency

required

object

max

required

integer

>= -9007199254740991 <= 9007199254740991

windowMinutes

required

integer

>= -9007199254740991 <= 9007199254740991

budget

required

object

timeoutMinutes

required

integer

>= -9007199254740991 <= 9007199254740991

maxRounds

required

integer

>= -9007199254740991 <= 9007199254740991

maxRunsPerDay

required

integer

>= -9007199254740991 <= 9007199254740991

permissions

required

object

dangerouslySkipPermissions

required

boolean

allowedDomains

required

Array<string>

key

additional properties

concurrency

required

object

max

required

integer

>= -9007199254740991 <= 9007199254740991

maxMachines

required

integer

>= -9007199254740991 <= 9007199254740991

dedupe

required

boolean

key

required

string | null

maxRunMinutes

required

0 disables the watchdog

integer

>= -9007199254740991 <= 9007199254740991

steps

required

Array<object>

object

required

Step id, stable within the task and addressable in templates

string

uses

required

Registered step handler, e.g. http.request

string

with

required

Step input after secret redaction

object

key

additional properties

timeoutMs

required

integer

>= -9007199254740991 <= 9007199254740991

retry

required

object

max

required

Additional attempts after the first one

integer

>= -9007199254740991 <= 9007199254740991

delayMs

required

integer

>= -9007199254740991 <= 9007199254740991

key

additional properties

afterDeliver

required

Actions that run after every main step succeeds

Array<object>

object

required

Step id, stable within the task and addressable in templates

string

uses

required

Registered step handler, e.g. http.request

string

with

required

Step input after secret redaction

object

key

additional properties

timeoutMs

required

integer

>= -9007199254740991 <= 9007199254740991

retry

required

object

max

required

Additional attempts after the first one

integer

>= -9007199254740991 <= 9007199254740991

delayMs

required

integer

>= -9007199254740991 <= 9007199254740991

key

additional properties

onFailure

required

Cleanup actions for failed, timed-out or cancelled runs

Array<object>

object

required

Step id, stable within the task and addressable in templates

string

uses

required

Registered step handler, e.g. http.request

string

with

required

Step input after secret redaction

object

key

additional properties

timeoutMs

required

integer

>= -9007199254740991 <= 9007199254740991

retry

required

object

max

required

Additional attempts after the first one

integer

>= -9007199254740991 <= 9007199254740991

delayMs

required

integer

>= -9007199254740991 <= 9007199254740991

key

additional properties

key

additional properties

stats

required

Any of:

object
null

object

runs7d

required

integer

>= -9007199254740991 <= 9007199254740991

succeeded7d

required

integer

>= -9007199254740991 <= 9007199254740991

failed7d

required

integer

>= -9007199254740991 <= 9007199254740991

successRate

required

number | null

latestStatus

required

Any of:

string
null

Lifecycle status of a task run

string

Allowed values: queued starting running waiting cancelling done failed cancelled

latestRunAt

required

Any of:

string
null

ISO-8601 timestamp

string

key

additional properties

createdAt

required

ISO-8601 timestamp

string

updatedAt

required

ISO-8601 timestamp

string

key

additional properties

key

additional properties

any

Example

{
  "task": {
    "stats": {
      "latestStatus": "queued"
    }
  }
}

400

Validation error

application/json

object

error

required

object

code

required

Machine-readable error code

string

message

required

string

requestId

required

Request id, also echoed in x-request-id

string

issues

Per-field validation details for VALIDATION_ERROR

Array<object>

object

path

required

Body or query field that failed validation

string

message

required

string

key

additional properties

key

additional properties

Example ^generated

{
  "error": {
    "code": "example",
    "message": "example",
    "requestId": "example",
    "issues": [
      {
        "path": "example",
        "message": "example"
      }
    ]
  }
}

401

Missing or invalid credentials

application/json

object

error

required

object

code

required

Machine-readable error code

string

message

required

string

requestId

required

Request id, also echoed in x-request-id

string

issues

Per-field validation details for VALIDATION_ERROR

Array<object>

object

path

required

Body or query field that failed validation

string

message

required

string

key

additional properties

key

additional properties

Example ^generated

{
  "error": {
    "code": "example",
    "message": "example",
    "requestId": "example",
    "issues": [
      {
        "path": "example",
        "message": "example"
      }
    ]
  }
}

403

The credential lacks the required scope, or the workspace is not writable

application/json

object

error

required

object

code

required

Machine-readable error code

string

message

required

string

requestId

required

Request id, also echoed in x-request-id

string

issues

Per-field validation details for VALIDATION_ERROR

Array<object>

object

path

required

Body or query field that failed validation

string

message

required

string

key

additional properties

key

additional properties

Example ^generated

{
  "error": {
    "code": "example",
    "message": "example",
    "requestId": "example",
    "issues": [
      {
        "path": "example",
        "message": "example"
      }
    ]
  }
}

404

Resource not found

application/json

object

error

required

object

code

required

Machine-readable error code

string

message

required

string

requestId

required

Request id, also echoed in x-request-id

string

issues

Per-field validation details for VALIDATION_ERROR

Array<object>

object

path

required

Body or query field that failed validation

string

message

required

string

key

additional properties

key

additional properties

Example ^generated

{
  "error": {
    "code": "example",
    "message": "example",
    "requestId": "example",
    "issues": [
      {
        "path": "example",
        "message": "example"
      }
    ]
  }
}

429

Rate limited

application/json

object

error

required

object

code

required

Machine-readable error code

string

message

required

string

requestId

required

Request id, also echoed in x-request-id

string

issues

Per-field validation details for VALIDATION_ERROR

Array<object>

object

path

required

Body or query field that failed validation

string

message

required

string

key

additional properties

key

additional properties

Example ^generated

{
  "error": {
    "code": "example",
    "message": "example",
    "requestId": "example",
    "issues": [
      {
        "path": "example",
        "message": "example"
      }
    ]
  }
}

Headers

X-RateLimit-Limit

integer

Requests allowed per window

X-RateLimit-Remaining

integer

X-RateLimit-Reset

integer

Seconds until the window resets

Retry-After

integer

Seconds to wait before retrying. Absent when the rejection has no retry time (for example the Free lifetime quota).

X-Quota-Limit

integer

Request allowance for the workspace’s plan

X-Quota-Remaining

integer

Requests left in the allowance after this request

Create or replace an automation task

Authorizations

Parameters

Path Parameters

Responses

200

Example

400

Example generated

401

Example generated

403

Example generated

404

Example generated

429

Example generated

Headers

Example ^generated

Example ^generated

Example ^generated

Example ^generated

Example ^generated