OpenAPI operations

Cancel an engine-owned task run

POST

/v1/tasks/{engineId}/runs/{runId}/cancel

const url = 'https://api.hooks.events/v1/tasks/example/runs/example/cancel';
const options = {method: 'POST', 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 POST \
  --url https://api.hooks.events/v1/tasks/example/runs/example/cancel \
  --header 'Authorization: Bearer <token>'

Authorizations

apiKey
sessionCookie

Parameters

Path Parameters

engineId

required

string

runId

required

string

Responses

200

Success

application/json

object

run

required

Automation task run

object

required

Resource id

string

engineId

required

string

taskName

required

string

projectId

required

string

environmentId

required

string | null

environmentName

required

string | null

eventId

required

string | null

rerunOf

required

string | null

status

required

Lifecycle status of a task run

string

Allowed values: queued starting running waiting cancelling done failed cancelled

callbackUrl

required

string

concurrencyKey

required

string

targetRunId

required

string | null

failedStep

required

Any of:

object
null

object

required

string

uses

required

string

currentStepIndex

required

integer

>= -9007199254740991 <= 9007199254740991

steps

required

Array<object>

object

required

string

uses

required

string

status

required

string

Allowed values: pending running waiting succeeded failed cancelled skipped

attempts

required

integer

>= -9007199254740991 <= 9007199254740991

input

required

Step input after secret redaction

object

key

additional properties

output

required

Any of:

object
null

object

key

additional properties

error

required

string | null

startedAt

required

Any of:

string
null

ISO-8601 timestamp

string

finishedAt

required

Any of:

string
null

ISO-8601 timestamp

string

key

additional properties

outputs

required

object

key

additional properties

object

key

additional properties

afterDeliverSteps

required

Array<object>

object

required

string

uses

required

string

status

required

string

Allowed values: pending running waiting succeeded failed cancelled skipped

attempts

required

integer

>= -9007199254740991 <= 9007199254740991

input

required

Step input after secret redaction

object

key

additional properties

output

required

Any of:

object
null

object

key

additional properties

error

required

string | null

startedAt

required

Any of:

string
null

ISO-8601 timestamp

string

finishedAt

required

Any of:

string
null

ISO-8601 timestamp

string

key

additional properties

failureSteps

required

Array<object>

object

required

string

uses

required

string

status

required

string

Allowed values: pending running waiting succeeded failed cancelled skipped

attempts

required

integer

>= -9007199254740991 <= 9007199254740991

input

required

Step input after secret redaction

object

key

additional properties

output

required

Any of:

object
null

object

key

additional properties

error

required

string | null

startedAt

required

Any of:

string
null

ISO-8601 timestamp

string

finishedAt

required

Any of:

string
null

ISO-8601 timestamp

string

key

additional properties

phase

required

string

Allowed values: main after_deliver on_failure

error

required

string | null

waitDeadline

required

Epoch milliseconds

number | null

deadlineAt

required

Hard deadline in epoch milliseconds

number | null

retryAt

required

Earliest retry time in epoch milliseconds

number | null

slotHeld

required

boolean

events

required

Array<object>

object

required

ISO-8601 timestamp

string

type

required

string

Allowed values: status deduplicated timeout warning agent

message

required

string

key

additional properties

cancelRequested

required

boolean

cleanupStarted

required

boolean

completedBy

required

string | null

completedAt

required

Any of:

string
null

ISO-8601 timestamp

string

callbackReceivedAt

required

Any of:

string
null

ISO-8601 timestamp

string

agentSession

required

Any of:

object
null

object

kind

required

string

Allowed values: slack linear

required

string

channelId

required

string | null

threadTs

required

string | null

sessionId

required

string | null

destinationId

required

string | null

tokenSecret

required

Project secret name, never the secret value

string

status

required

string

Allowed values: processing waiting_approval done stopped

steps

required

Array<object>

object

callId

required

string

title

required

string

status

required

string

Allowed values: running succeeded failed

detail

required

string | null

updatedAt

required

ISO-8601 timestamp

string

key

additional properties

approvals

required

Array<object>

object

callId

required

string

title

required

string

detail

required

string | null

requestedAt

required

ISO-8601 timestamp

string

decision

required

Any of:

string
null

string

Allowed values: approve deny

decidedBy

required

string | null

decidedAt

required

Any of:

string
null

ISO-8601 timestamp

string

messageTs

required

string | null

key

additional properties

decisions

required

Array<object>

object

seq

required

integer

>= -9007199254740991 <= 9007199254740991

callId

required

string

decision

required

string

Allowed values: approve deny

decidedBy

required

string

required

ISO-8601 timestamp

string

key

additional properties

followUps

required

Array<object>

object

seq

required

integer

>= -9007199254740991 <= 9007199254740991

text

required

string

userId

required

string | null

required

ISO-8601 timestamp

string

key

additional properties

stopRequested

required

boolean

streamedText

required

string

receivedEventIds

required

Array<string>

updatedAt

required

ISO-8601 timestamp

string

key

additional properties

createdAt

required

ISO-8601 timestamp

string

updatedAt

required

ISO-8601 timestamp

string

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

event

required

Triggering event after secret redaction

object

key

additional properties

deliveryStatus

required

Delivery vocabulary view of status

string

key

additional properties

key

additional properties

any

Example

{
  "run": {
    "status": "queued",
    "steps": [
      {
        "status": "pending"
      }
    ],
    "afterDeliverSteps": [
      {
        "status": "pending"
      }
    ],
    "failureSteps": [
      {
        "status": "pending"
      }
    ],
    "phase": "main",
    "events": [
      {
        "type": "status"
      }
    ],
    "agentSession": {
      "kind": "slack",
      "status": "processing",
      "steps": [
        {
          "status": "running"
        }
      ],
      "approvals": [
        {
          "decision": "approve"
        }
      ],
      "decisions": [
        {
          "decision": "approve"
        }
      ]
    }
  }
}

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

Cancel an engine-owned task run

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