Skip to content
Browse documentation

OpenAPI operations

Validate a task definition

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

Authorizations

Section titled “Authorizations”

Responses

Section titled “Responses”

200

Section titled “200”

Success

Media typeapplication/json

Validated task document

object
valid
required
boolean
task
required

Normalized task document

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
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
id
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
id
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
id
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
key
additional properties

Example 

{
  "valid": true
}

400

Section titled “400”

Validation error

Media typeapplication/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

Section titled “401”

Missing or invalid credentials

Media typeapplication/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

Section titled “403”

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

Media typeapplication/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

Section titled “429”

Rate limited

Media typeapplication/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

Section titled “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