AVA Workers API

AVA (Autonomous Virtual Assistant) Workers are persistent, tenant-scoped serverless agents that execute automated tasks across your HLD environment — from data pipelines to security automation to custom business logic.

What AVA Workers do

Workers — define a reusable autonomous agent: runtime, source code, config, secrets, and execution limits.
Jobs — trigger a worker with a specific input payload. Returns immediately with a job ID; execution is async.
Schedules — run workers automatically on a cron expression in any IANA timezone.
Queues — inspect live queue depth and running jobs per worker.
Logs — stream structured execution logs from any job.
Analytics — success rates, average durations, failure breakdowns per worker.

Runtimes

Name	Type	Required	Description
nodejs	runtime	No	Node.js 20 LTS. Best for API integrations, data transforms, and web scraping.
python	runtime	No	Python 3.12. Best for data science, ML pipelines, and system automation.
deno	runtime	No	Deno 1.x. TypeScript-native, security-first. Best for lightweight transformers.
shell	runtime	No	Bash/sh. Best for system tasks, file operations, and wrapping CLI tools.
wasm	runtime	No	WebAssembly. Best for performance-critical, language-agnostic workloads.

Base URL

bash

https://api.hldgroup.org/v1/ava

Authentication

bash

curl https://api.hldgroup.org/v1/ava/workers \
  -H "x-internal-secret: <your-api-key>" \
  -H "x-user-id: usr_01hxyz" \
  -H "x-tenant-id: ten_01hxyz" \
  -H "x-platform-role: tenant-system-admin"

Note:Write operations (create/update/delete workers, trigger jobs, create schedules) require tenant-system-admin or above. Read operations (list workers, poll job status, view logs) are available to all authenticated roles.

Job lifecycle

bash

queued → running → completed
                   ↘ failed
                   ↘ cancelled

Jobs transition automatically. Subscribe to ava.job.completed and ava.job.failed webhook events to react in real time, or poll GET /v1/ava/jobs/:id.

Quick start

bash

# 1. Create a worker
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": "Daily security digest",
    "runtime": "nodejs",
    "description": "Fetches open Sentinel incidents and sends a Slack digest",
    "timeout_seconds": 60,
    "max_retries": 2,
    "source_code": "module.exports = async ({ input, env }) => { /* ... */ }"
  }'

# 2. Trigger it
curl -X POST https://api.hldgroup.org/v1/ava/jobs \
  -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 '{
    "worker_id": "wkr_01hxyz",
    "input": { "channel": "#security-ops" }
  }'

Workers Jobs