Actions

Workspace actions: user-authored code executed in a sandbox, with vault credentials injected as env vars.

An action belongs to a workspace and carries the code (must export an execute(input) function), its dependencies as a verbatim package.json, an egress allowlist, and bound vault credentials - each credential payload key becomes one env var in the sandbox (process.env[name]; later credentials win name collisions). Runs are recorded durably and queryable via v3.action.runs. v3.action.trigger waits up to 25 s: longer runs return the still-running record and finish in the background.

Endpoints

Endpoint	Arguments	Returns
`v3.action.cancelRun`	`runId: string`	object
`v3.action.create`	`action: { name, workspaceId, code, packageJson?, allowNet?, credentialIds?, limits?, maxRunsPerHour?, runners?, triggers?, schedule?, description?, key?, public?, enabled? }`	object
`v3.action.get`	`actionId: string`	object
`v3.action.getRun`	`runId: string`	object
`v3.action.list`	`options: { workspaceId }`	object[]
`v3.action.remove`	`actionId: string`	boolean
`v3.action.run`	`options: { workspaceId, config: { name?, code, packageJson?, allowNet?, credentialIds?, limits? }, actionId?, input?, activityId?, member?: { userId, event: 'joined' \| 'left' } }`	object
`v3.action.runs`	`options: { workspaceId, actionId?, status?, createdFrom?, createdTo?, limit?, skip? }`	object[]
`v3.action.trigger`	`options: { actionId?, workspaceId?, key?, publicKey? }, input?: any`	object
`v3.action.triggers`	-	object[]
`v3.action.update`	`actionId: string, changes: { name?, description?, key?, public?, rotatePublicKey?, enabled?, code?, packageJson?, allowNet?, credentialIds?, limits?, maxRunsPerHour?, runners?, triggers?, schedule? }`	boolean

`v3.action.cancelRun`

Description

Cancel a run the executor still holds queued (status queued with an execRunId - phase-triggered runs waiting for a sandbox slot). Returns the cancelled record. Fails with the executor's message when the run has already left queued there or the executor no longer has its record; the record here is left untouched - the executor's callbacks own its state. Workspace admins and owners only.

Parameters

Argument 1 (ObjectId, required):

Example

javascript

const { Client } = require('@hailer/cli');

const client = await Client.create({
  host: 'https://api.hailer.com',
  username: 'you@example.com',
  password: '••••••',
});

const result = await client.request('v3.action.cancelRun', [
  '507f1f77bcf86cd799439011', // ObjectId (required)
]);
console.log(result);

Returns

Field	Type	Required	Description
`_id`	ObjectId	yes
`actionId`	ObjectId	no
`workspaceId`	WorkspaceId	yes	workspaceId (former networkId)
`event`	`manual` \| `phase.activity-created` \| `phase.activity-updated` \| `phase.activity-moved` \| `workspace.member-joined` \| `workspace.member-left` \| `schedule.run`	yes
`test`	boolean	no
`triggeredBy`	ObjectId	no
`config`	object	no	See below.
`arguments`	string	no
`status`	`queued` \| `running` \| `completed` \| `runtime_error` \| `timeout` \| `output_limit` \| `infra_error` \| `cancelled` \| `config_error` \| `denied`	yes
`execRunId`	string	no
`exitCode`	number	no
`stdout`	string	no
`stderr`	string	no
`output`	any	no
`message`	string	no
`wallTimeMs`	number	no
`created`	number	yes
`finishedAt`	number	no

config (object):

Field	Type	Required	Description
`name`	string	no
`code`	string	yes
`packageJson`	string	no
`allowNet`	string[]	no
`credentialIds`	credentialId[]	no
`limits`	object	no	See below.

config.limits (object):

Field	Type	Required	Description
`wallTimeMs`	integer	no

Auth: requires an authenticated session.

Errors: on failure returns the standard Hailer error object { code, msg, details?, retryAfter?, debug? }. retryAfter is a delay in milliseconds.

`v3.action.create`

Description

Create a workspace action: sandboxed code run by the executor. Workspace admins only. Bound credentials are injected as env vars (each payload key becomes one env var; later credentials win name collisions). maxRunsPerHour bounds runs per sliding hour - test runs are exempt; default 1000. triggers are event keys from v3.action.triggers: phase.* keys carry the workflowId and phaseId of this workspace (phase.activity-created:<workflowId>:<phaseId>), workspace.* keys are the bare event. schedule arms a cron run: a 5-field cron expression and an optional IANA tz (UTC when absent); the stored schedule carries the api-computed nextRunAt.

Parameters

Argument 1 (object, required):

Field	Type	Required	Description
`name`	string	yes
`workspaceId`	WorkspaceId	yes	workspaceId (former networkId)
`code`	string	yes
`packageJson`	string	no
`allowNet`	string[]	no
`credentialIds`	credentialId[]	no
`limits`	object	no	See below.
`maxRunsPerHour`	integer	no
`runners`	string[]	no
`triggers`	string[]	no
`schedule`	object	no	See below.
`description`	string	no
`key`	string	no
`public`	boolean	no
`enabled`	boolean	no

limits (object):

Field	Type	Required	Description
`wallTimeMs`	integer	no

schedule (object):

Field	Type	Required	Description
`cron`	string	yes
`tz`	string	no	One of 597 values, e.g. `Africa/Abidjan`, `Africa/Accra`, `Africa/Addis_Ababa`, `Africa/Algiers`, `Africa/Asmara`.

Example

javascript

const { Client } = require('@hailer/cli');

const client = await Client.create({
  host: 'https://api.hailer.com',
  username: 'you@example.com',
  password: '••••••',
});

const result = await client.request('v3.action.create', [
  {
    name: 'string',
    workspaceId: '507f1f77bcf86cd799439011', // workspaceId (former networkId)
    code: 'string',
  },
]);
console.log(result);

Returns

Field	Type	Required	Description
`_id`	ObjectId	yes

Auth: requires an authenticated session.

Errors: on failure returns the standard Hailer error object { code, msg, details?, retryAfter?, debug? }. retryAfter is a delay in milliseconds.

`v3.action.get`

Description

Get one action - same shape as a v3.action.list item. Use it to fetch the latest state of a single action (e.g. before editing). Workspace admins and owners only.

Parameters

Argument 1 (ObjectId, required):

Example

javascript

const { Client } = require('@hailer/cli');

const client = await Client.create({
  host: 'https://api.hailer.com',
  username: 'you@example.com',
  password: '••••••',
});

const result = await client.request('v3.action.get', [
  '507f1f77bcf86cd799439011', // ObjectId (required)
]);
console.log(result);

Returns

Field	Type	Required	Description
`_id`	ObjectId	yes
`name`	string	yes
`workspaceId`	WorkspaceId	yes	workspaceId (former networkId)
`description`	string	no
`key`	string	no
`public`	boolean	no
`publicKey`	string	no
`enabled`	boolean	yes
`code`	string	yes
`packageJson`	string	no
`allowNet`	string[]	no
`credentialIds`	credentialId[]	yes
`limits`	object	no	See below.
`maxRunsPerHour`	integer	no
`runners`	string[]	no
`triggers`	string[]	yes
`schedule`	object	no	See below.
`createdBy`	ObjectId	yes
`created`	number	yes
`updated`	number	yes

limits (object):

Field	Type	Required	Description
`wallTimeMs`	integer	no

schedule (object):

Field	Type	Required	Description
`cron`	string	yes
`tz`	string	no	One of 597 values, e.g. `Africa/Abidjan`, `Africa/Accra`, `Africa/Addis_Ababa`, `Africa/Algiers`, `Africa/Asmara`.
`nextRunAt`	timestamp	no	Time (milliseconds since 1970-01-01 UTC)

Auth: requires an authenticated session.

Errors: on failure returns the standard Hailer error object { code, msg, details?, retryAfter?, debug? }. retryAfter is a delay in milliseconds.

`v3.action.getRun`

Description

Get one run record - same shape as a v3.action.runs item. The action.run.updated signal carries only ids and status; fetch the changed row with this instead of relisting. Workspace admins and owners see the full record; the user who triggered the run sees the outcome only (status, output, message).

Parameters

Argument 1 (ObjectId, required):

Example

javascript

const { Client } = require('@hailer/cli');

const client = await Client.create({
  host: 'https://api.hailer.com',
  username: 'you@example.com',
  password: '••••••',
});

const result = await client.request('v3.action.getRun', [
  '507f1f77bcf86cd799439011', // ObjectId (required)
]);
console.log(result);

Returns

Field	Type	Required	Description
`_id`	ObjectId	yes
`actionId`	ObjectId	no
`workspaceId`	WorkspaceId	yes	workspaceId (former networkId)
`event`	`manual` \| `phase.activity-created` \| `phase.activity-updated` \| `phase.activity-moved` \| `workspace.member-joined` \| `workspace.member-left` \| `schedule.run`	yes
`test`	boolean	no
`triggeredBy`	ObjectId	no
`config`	object	no	See below.
`arguments`	string	no
`status`	`queued` \| `running` \| `completed` \| `runtime_error` \| `timeout` \| `output_limit` \| `infra_error` \| `cancelled` \| `config_error` \| `denied`	yes
`execRunId`	string	no
`exitCode`	number	no
`stdout`	string	no
`stderr`	string	no
`output`	any	no
`message`	string	no
`wallTimeMs`	number	no
`created`	number	yes
`finishedAt`	number	no

config (object):

Field	Type	Required	Description
`name`	string	no
`code`	string	yes
`packageJson`	string	no
`allowNet`	string[]	no
`credentialIds`	credentialId[]	no
`limits`	object	no	See below.

config.limits (object):

Field	Type	Required	Description
`wallTimeMs`	integer	no

Auth: requires an authenticated session.

Errors: on failure returns the standard Hailer error object { code, msg, details?, retryAfter?, debug? }. retryAfter is a delay in milliseconds.

`v3.action.list`

Description

List a workspace's actions as full documents, code included - one fetch gets everything. Workspace admins and owners only.

Parameters

Argument 1 (object, required):

Field	Type	Required	Description
`workspaceId`	WorkspaceId	yes	workspaceId (former networkId)

Example

javascript

const { Client } = require('@hailer/cli');

const client = await Client.create({
  host: 'https://api.hailer.com',
  username: 'you@example.com',
  password: '••••••',
});

const result = await client.request('v3.action.list', [
  {
    workspaceId: '507f1f77bcf86cd799439011', // workspaceId (former networkId)
  },
]);
console.log(result);

Returns

Array of objects:

Field	Type	Required	Description
`_id`	ObjectId	yes
`name`	string	yes
`workspaceId`	WorkspaceId	yes	workspaceId (former networkId)
`description`	string	no
`key`	string	no
`public`	boolean	no
`publicKey`	string	no
`enabled`	boolean	yes
`code`	string	yes
`packageJson`	string	no
`allowNet`	string[]	no
`credentialIds`	credentialId[]	yes
`limits`	object	no	See below.
`maxRunsPerHour`	integer	no
`runners`	string[]	no
`triggers`	string[]	yes
`schedule`	object	no	See below.
`createdBy`	ObjectId	yes
`created`	number	yes
`updated`	number	yes

limits (object):

Field	Type	Required	Description
`wallTimeMs`	integer	no

schedule (object):

Field	Type	Required	Description
`cron`	string	yes
`tz`	string	no	One of 597 values, e.g. `Africa/Abidjan`, `Africa/Accra`, `Africa/Addis_Ababa`, `Africa/Algiers`, `Africa/Asmara`.
`nextRunAt`	timestamp	no	Time (milliseconds since 1970-01-01 UTC)

Auth: requires an authenticated session.

Errors: on failure returns the standard Hailer error object { code, msg, details?, retryAfter?, debug? }. retryAfter is a delay in milliseconds.

`v3.action.remove`

Description

Remove an action. Its run records are kept as the workspace's run history. Workspace admins and owners only.

Parameters

Argument 1 (ObjectId, required):

Example

javascript

const { Client } = require('@hailer/cli');

const client = await Client.create({
  host: 'https://api.hailer.com',
  username: 'you@example.com',
  password: '••••••',
});

const result = await client.request('v3.action.remove', [
  '507f1f77bcf86cd799439011', // ObjectId (required)
]);
console.log(result);

Returns

boolean

Auth: requires an authenticated session.

Errors: on failure returns the standard Hailer error object { code, msg, details?, retryAfter?, debug? }. retryAfter is a delay in milliseconds.

`v3.action.run`

Description

Run an action config inline, without saving an action - the editor's test button, usable on unsaved drafts and unsaved edits alike. Same sandbox, credential rules and billing as a saved action. The run is recorded with test: true and a snapshot of the executed config; pass actionId when testing an edit of an existing action to link the record to it. Input, one of: free-form input, delivered as the payload of a manual event; activityId to receive that activity exactly as a phase trigger delivers it on creation (event 'phase.activity-created'); member to receive a workspace member exactly as a membership trigger delivers them (event 'workspace.member-joined' or 'workspace.member-left', the caller standing in as inviter / remover). Waits up to 25 s like v3.action.trigger. Workspace admins and owners only.

Parameters

Argument 1 (object, required):

Field	Type	Required	Description
`workspaceId`	WorkspaceId	yes	workspaceId (former networkId)
`config`	object	yes	See below.
`actionId`	ObjectId	no
`input`	any	no
`activityId`	ObjectId	no
`member`	object	no	See below.

config (object):

Field	Type	Required	Description
`name`	string	no
`code`	string	yes
`packageJson`	string	no
`allowNet`	string[]	no
`credentialIds`	credentialId[]	no
`limits`	object	no	See below.

config.limits (object):

Field	Type	Required	Description
`wallTimeMs`	integer	no

member (object):

Field	Type	Required	Description
`userId`	ObjectId	yes
`event`	`joined` \| `left`	yes

Example

javascript

const { Client } = require('@hailer/cli');

const client = await Client.create({
  host: 'https://api.hailer.com',
  username: 'you@example.com',
  password: '••••••',
});

const result = await client.request('v3.action.run', [
  {
    workspaceId: '507f1f77bcf86cd799439011', // workspaceId (former networkId)
    config: {
      code: 'string',
    },
  },
]);
console.log(result);

Returns

Field	Type	Required	Description
`_id`	ObjectId	yes
`actionId`	ObjectId	no
`workspaceId`	WorkspaceId	yes	workspaceId (former networkId)
`event`	`manual` \| `phase.activity-created` \| `phase.activity-updated` \| `phase.activity-moved` \| `workspace.member-joined` \| `workspace.member-left` \| `schedule.run`	yes
`test`	boolean	no
`triggeredBy`	ObjectId	no
`config`	object	no	See below.
`arguments`	string	no
`status`	`queued` \| `running` \| `completed` \| `runtime_error` \| `timeout` \| `output_limit` \| `infra_error` \| `cancelled` \| `config_error` \| `denied`	yes
`execRunId`	string	no
`exitCode`	number	no
`stdout`	string	no
`stderr`	string	no
`output`	any	no
`message`	string	no
`wallTimeMs`	number	no
`created`	number	yes
`finishedAt`	number	no

config (object):

Field	Type	Required	Description
`name`	string	no
`code`	string	yes
`packageJson`	string	no
`allowNet`	string[]	no
`credentialIds`	credentialId[]	no
`limits`	object	no	See below.

config.limits (object):

Field	Type	Required	Description
`wallTimeMs`	integer	no

Auth: requires an authenticated session.

Errors: on failure returns the standard Hailer error object { code, msg, details?, retryAfter?, debug? }. retryAfter is a delay in milliseconds.

`v3.action.runs`

Description

List a workspace's action run records, newest first - optionally filtered to one action, a set of statuses, and/or a created-time range (createdFrom/createdTo, epoch ms, inclusive). Also the polling endpoint for runs that outlived v3.action.trigger's 25 s window. Rows omit arguments; v3.action.getRun returns it. Workspace admins and owners only.

Parameters

Argument 1 (object, required):

Field	Type	Required	Description
`workspaceId`	WorkspaceId	yes	workspaceId (former networkId)
`actionId`	ObjectId	no
`status`	(`queued` \| `running` \| `completed` \| `runtime_error` \| `timeout` \| `output_limit` \| `infra_error` \| `cancelled` \| `config_error` \| `denied`)[]	no
`createdFrom`	integer	no
`createdTo`	integer	no
`limit`	integer	no
`skip`	integer	no

Example

javascript

const { Client } = require('@hailer/cli');

const client = await Client.create({
  host: 'https://api.hailer.com',
  username: 'you@example.com',
  password: '••••••',
});

const result = await client.request('v3.action.runs', [
  {
    workspaceId: '507f1f77bcf86cd799439011', // workspaceId (former networkId)
  },
]);
console.log(result);

Returns

Array of objects:

Field	Type	Required	Description
`_id`	ObjectId	yes
`actionId`	ObjectId	no
`workspaceId`	WorkspaceId	yes	workspaceId (former networkId)
`event`	`manual` \| `phase.activity-created` \| `phase.activity-updated` \| `phase.activity-moved` \| `workspace.member-joined` \| `workspace.member-left` \| `schedule.run`	yes
`test`	boolean	no
`triggeredBy`	ObjectId	no
`config`	object	no	See below.
`arguments`	string	no
`status`	`queued` \| `running` \| `completed` \| `runtime_error` \| `timeout` \| `output_limit` \| `infra_error` \| `cancelled` \| `config_error` \| `denied`	yes
`execRunId`	string	no
`exitCode`	number	no
`stdout`	string	no
`stderr`	string	no
`output`	any	no
`message`	string	no
`wallTimeMs`	number	no
`created`	number	yes
`finishedAt`	number	no

config (object):

Field	Type	Required	Description
`name`	string	no
`code`	string	yes
`packageJson`	string	no
`allowNet`	string[]	no
`credentialIds`	credentialId[]	no
`limits`	object	no	See below.

config.limits (object):

Field	Type	Required	Description
`wallTimeMs`	integer	no

Auth: requires an authenticated session.

Errors: on failure returns the standard Hailer error object { code, msg, details?, retryAfter?, debug? }. retryAfter is a delay in milliseconds.

`v3.action.trigger`

Description

Trigger a saved action now. Waits up to 25 s for the result; longer runs return the still-running record and finish in the background (poll v3.action.getRun). The action is addressed one way: actionId or { workspaceId, key } for a logged-in caller - workspace admins and owners, plus anyone matched by the action's runners - or publicKey for anyone, no login needed, when the action is public. Admins get the full run record; everyone else the outcome only (status, output, message), not config, stdout or stderr. input is delivered as the payload of a manual event: execute({ event: 'manual', payload: input, workspaceId, triggeredBy }); triggeredBy is absent on a public trigger and the run is billed to the action's author.

Parameters

Argument 1 (object, required):

Field	Type	Required	Description
`actionId`	ObjectId	no
`workspaceId`	WorkspaceId	no	workspaceId (former networkId)
`key`	string	no
`publicKey`	string	no

Argument 2 (any, optional):

Example

javascript

const { Client } = require('@hailer/cli');

const client = await Client.create({
  host: 'https://api.hailer.com',
  username: 'you@example.com',
  password: '••••••',
});

const result = await client.request('v3.action.trigger', [
  {
    actionId: '507f1f77bcf86cd799439011',
    workspaceId: '507f1f77bcf86cd799439011', // workspaceId (former networkId)
  },
  '...', // argument 2
]);
console.log(result);

Returns

Field	Type	Required	Description
`_id`	ObjectId	yes
`actionId`	ObjectId	no
`workspaceId`	WorkspaceId	yes	workspaceId (former networkId)
`event`	`manual` \| `phase.activity-created` \| `phase.activity-updated` \| `phase.activity-moved` \| `workspace.member-joined` \| `workspace.member-left` \| `schedule.run`	yes
`test`	boolean	no
`triggeredBy`	ObjectId	no
`config`	object	no	See below.
`arguments`	string	no
`status`	`queued` \| `running` \| `completed` \| `runtime_error` \| `timeout` \| `output_limit` \| `infra_error` \| `cancelled` \| `config_error` \| `denied`	yes
`execRunId`	string	no
`exitCode`	number	no
`stdout`	string	no
`stderr`	string	no
`output`	any	no
`message`	string	no
`wallTimeMs`	number	no
`created`	number	yes
`finishedAt`	number	no

config (object):

Field	Type	Required	Description
`name`	string	no
`code`	string	yes
`packageJson`	string	no
`allowNet`	string[]	no
`credentialIds`	credentialId[]	no
`limits`	object	no	See below.

config.limits (object):

Field	Type	Required	Description
`wallTimeMs`	integer	no

Auth: callable without authentication.

Errors: on failure returns the standard Hailer error object { code, msg, details?, retryAfter?, debug? }. retryAfter is a delay in milliseconds.

`v3.action.triggers`

Description

List the trigger events an action can bind to. Each definition names the event and the key parameters in order: the key is the event followed by the parameter values, joined with ":" (phase.activity-created:<workflowId>:<phaseId>; workspace.member-joined has no parameters).

Parameters

Undocumented

This endpoint declares no argument schema in the source yet.

Example

javascript

const { Client } = require('@hailer/cli');

const client = await Client.create({
  host: 'https://api.hailer.com',
  username: 'you@example.com',
  password: '••••••',
});

const result = await client.request('v3.action.triggers', []);
console.log(result);

Returns

Array of objects:

Field	Type	Required	Description
`event`	string	yes
`params`	string[]	yes

Auth: requires an authenticated session.

Errors: on failure returns the standard Hailer error object { code, msg, details?, retryAfter?, debug? }. retryAfter is a delay in milliseconds.

`v3.action.update`

Description

Update an action. Workspace admins and owners only. Partial: only provided fields change; null clears description, key, packageJson, allowNet, limits, maxRunsPerHour, runners, triggers or schedule. triggers replaces the whole list; schedule replaces the schedule and restarts it from now. Changed credentials are re-validated against the workspace. enabled: false is the kill switch - a disabled action refuses to run on any trigger. rotatePublicKey: true replaces publicKey with a new random one, invalidating the old; public: true on an action without one generates it.

Parameters

Argument 1 (ObjectId, required):

Argument 2 (object, required):

Field	Type	Required	Description
`name`	string	no
`description`	string	no
`key`	string	no
`public`	boolean	no
`rotatePublicKey`	boolean	no
`enabled`	boolean	no
`code`	string	no
`packageJson`	string	no
`allowNet`	string[]	no
`credentialIds`	credentialId[]	no
`limits`	object	no	See below.
`maxRunsPerHour`	integer	no
`runners`	string[]	no
`triggers`	string[]	no
`schedule`	object	no	See below.

limits (object):

Field	Type	Required	Description
`wallTimeMs`	integer	no

schedule (object):

Field	Type	Required	Description
`cron`	string	yes
`tz`	string	no	One of 597 values, e.g. `Africa/Abidjan`, `Africa/Accra`, `Africa/Addis_Ababa`, `Africa/Algiers`, `Africa/Asmara`.

Example

javascript

const { Client } = require('@hailer/cli');

const client = await Client.create({
  host: 'https://api.hailer.com',
  username: 'you@example.com',
  password: '••••••',
});

const result = await client.request('v3.action.update', [
  '507f1f77bcf86cd799439011', // ObjectId (required)
  {
    name: 'string',
    description: 'string',
  },
]);
console.log(result);

Returns

boolean

Auth: requires an authenticated session.

Errors: on failure returns the standard Hailer error object { code, msg, details?, retryAfter?, debug? }. retryAfter is a delay in milliseconds.

Endpoints

Legacy

V2

V3

Actions

Endpoints

`v3.action.cancelRun`

`v3.action.create`

`v3.action.get`

`v3.action.getRun`

`v3.action.list`

`v3.action.remove`

`v3.action.run`

`v3.action.runs`

`v3.action.trigger`

`v3.action.triggers`

`v3.action.update`

Legacy

V2

V3

Actions ​

Endpoints ​

v3.action.cancelRun ​

v3.action.create ​

v3.action.get ​

v3.action.getRun ​

v3.action.list ​

v3.action.remove ​

v3.action.run ​

v3.action.runs ​

v3.action.trigger ​

v3.action.triggers ​

v3.action.update ​

Actions

Endpoints

`v3.action.cancelRun`

`v3.action.create`

`v3.action.get`

`v3.action.getRun`

`v3.action.list`

`v3.action.remove`

`v3.action.run`

`v3.action.runs`

`v3.action.trigger`

`v3.action.triggers`

`v3.action.update`