Workers

A worker is the definition of an autonomous agent — its runtime, source code, secrets, configuration, and execution constraints. Workers are reusable blueprints; each execution is a Job.

List workers

bash

GET /v1/ava/workers

Name	Type	Required	Description
filter[status]	string	No	active \| paused \| deprecated
filter[runtime]	string	No	nodejs \| python \| deno \| shell \| wasm
q	string	No	Search workers by name.
page / per_page	integer	No	Pagination. Default page=1, per_page=20.

Create a worker

bash

POST /v1/ava/workers

Name	Type	Required	Description
name	string	Yes	Human-readable worker name.
runtime	string	Yes	nodejs \| python \| deno \| shell \| wasm
description	string	No	What this worker does.
entrypoint	string	No	File path within source bundle (e.g. "index.js"). Defaults to runtime convention.
source_code	string	No	Inline source code (for simple workers). For complex workers use source bundles via the deploy endpoint.
config	object	No	Non-secret config key/value pairs injected as environment variables.
secrets	array	No	Secret key names to inject at runtime. Values are set separately via the secrets vault.
timeout_seconds	integer	No	Max execution time. Default 300, max 3600.
max_retries	integer	No	Auto-retry on failure. Default 0, max 5.

bash

curl -X POST https://api.hldgroup.org/v1/ava/workers \
  -H "x-internal-secret: <key>" \
  -H "x-tenant-id: ten_01hxyz" \
  -H "x-user-id: usr_01hxyz" \
  -H "x-platform-role: tenant-system-admin" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Incident enrichment pipeline",
    "runtime": "python",
    "description": "Pulls threat intel for new critical incidents and posts enriched summary to Slack",
    "timeout_seconds": 120,
    "max_retries": 1,
    "config": {
      "SLACK_CHANNEL": "#security-ops",
      "MIN_SEVERITY": "high"
    },
    "secrets": ["SLACK_BOT_TOKEN", "VIRUSTOTAL_API_KEY"],
    "source_code": "async def handler(input, env):\n  # ... enrichment logic"
  }'

Get a worker

bash

GET /v1/ava/workers/:id

Update a worker

bash

PATCH /v1/ava/workers/:id

Name	Type	Required	Description
name	string	No	New display name.
description	string	No	Updated description.
status	string	No	active \| paused — change without modifying code.
source_code	string	No	Updated source. New jobs will use the new version immediately.
config	object	No	Merged into existing config.
timeout_seconds	integer	No	Updated timeout.
max_retries	integer	No	Updated retry count.

Note:Pausing a worker (status: "paused") prevents new jobs from being queued. Jobs already running will complete. Scheduled runs are skipped while paused.

Delete (deprecate) a worker

bash

DELETE /v1/ava/workers/:id

Workers are soft-deleted — status is set to deprecated. Historical jobs and logs are preserved. Deprecated workers cannot accept new jobs.

Worker source format

Node.js

javascript

// Export a handler function. AVA injects input and env.
module.exports = async function handler({ input, env }) {
  const { channel } = input
  const token = env.SLACK_BOT_TOKEN
  // ... your logic
  return { success: true, message_ts: '...' }
}

Python

python

# Define an async handler function.
async def handler(input: dict, env: dict) -> dict:
    channel = input.get("channel")
    token = env.get("SLACK_BOT_TOKEN")
    # ... your logic
    return {"success": True}

Jobs Schedules