Skip to main content
Worker genies are autonomous background AI agents powered by Anthropic Claude. They can execute tasks on schedule, by event trigger, or on-demand. Each worker genie has access to tools including web_fetch, memory_read, memory_write, query_data, and notify_owner.
Worker genies run server-side and have access to stored credentials for calling external APIs securely.

​
List worker genies

Retrieves all worker genies for the authenticated user.
​
resource
string
required
Must be "worker-genies".
​
action
string
required
Must be "all" or "list".
​
success
boolean
​
data
object
curl -s https://api.helpgenie.ai/v1/worker-genies \
  -H "Authorization: Bearer hg_live_YOUR_KEY"

​
Get worker genie

Retrieves a single worker genie by ID, including recent run history.
​
resource
string
required
Must be "worker-genies".
​
action
string
required
Must be "get".
​
id
string
required
The UUID of the worker genie.
curl -s https://api.helpgenie.ai/v1/worker-genies/GENIE_UUID \
  -H "Authorization: Bearer hg_live_YOUR_KEY"

​
Create worker genie

Creates a new worker genie with the specified configuration.
​
resource
string
required
Must be "worker-genies".
​
action
string
required
Must be "create".
​
data
object
required
curl -s -X POST https://api.helpgenie.ai/v1/worker-genies \
  -H "Authorization: Bearer hg_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "HubSpot Contact Digest",
    "soul_prompt": "You are a sales intelligence worker. Use web_fetch with the hubspot_api credential to call the HubSpot API...",
    "trigger_type": "manual",
    "credential_refs": ["hubspot_api"]
  }'

​
Update worker genie

Updates an existing worker genie. Supports partial updates.
​
resource
string
required
Must be "worker-genies".
​
action
string
required
Must be "update".
​
id
string
required
The UUID of the worker genie to update.

​
Delete worker genie

Permanently deletes a worker genie and all of its run history.
​
resource
string
required
Must be "worker-genies".
​
action
string
required
Must be "delete".
​
id
string
required
The UUID of the worker genie to delete.
This action is irreversible. The worker genie and all associated run history will be permanently deleted.

​
Run worker genie

Triggers a manual run of a worker genie. The run executes asynchronously and results can be retrieved via run history.
​
resource
string
required
Must be "worker-genies".
​
action
string
required
Must be "run".
​
id
string
required
The UUID of the worker genie to run.
​
data
object
curl -s -X POST https://api.helpgenie.ai/v1/worker-genies \
  -H "Authorization: Bearer hg_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "action": "run", "id": "GENIE_UUID" }'

​
Get run history

Retrieves the execution history for a worker genie or all worker genies.
​
resource
string
required
Must be "worker-genies".
​
action
string
required
Must be "runs".
​
id
string
Optional worker genie UUID. If omitted, returns runs for all genies.
​
data.items
array
curl -s -X POST https://api.helpgenie.ai/v1/worker-genies \
  -H "Authorization: Bearer hg_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "action": "runs", "id": "GENIE_UUID" }'

​
Test credential

Tests a credential before or after storing. Can test an already-stored credential by name, or test a new credential value before committing it. Optionally makes a test HTTP request to verify the credential works.
​
resource
string
required
Must be "worker-genies".
​
action
string
required
Must be "test-credential".
​
data
object
required
​
data
object
curl -s -X POST https://api.helpgenie.ai/v1/worker-genies \
  -H "Authorization: Bearer hg_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "test-credential",
    "data": {
      "name": "hubspot_api",
      "url": "https://api.hubapi.com/crm/v3/objects/contacts?limit=1"
    }
  }'

​
Store credential

Stores an encrypted API credential that worker genies can use during runs. Credentials are encrypted at rest using AES-GCM.
​
resource
string
required
Must be "worker-genies".
​
action
string
required
Must be "store-credential".
​
data
object
required
curl -s -X POST https://api.helpgenie.ai/v1/worker-genies \
  -H "Authorization: Bearer hg_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "store-credential",
    "name": "hubspot_api",
    "credential_type": "bearer_token",
    "value": "pat-na1-xxxxx"
  }'

​
List credentials

Lists all stored credentials for the authenticated user. Secret values are never returned.
​
resource
string
required
Must be "worker-genies".
​
action
string
required
Must be "list-credentials".
​
data.items
array
curl -s -X POST https://api.helpgenie.ai/v1/worker-genies \
  -H "Authorization: Bearer hg_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "action": "list-credentials" }'

​
Delete credential

Deletes a stored credential by ID.
​
resource
string
required
Must be "worker-genies".
​
action
string
required
Must be "delete-credential".
​
id
string
required
The UUID of the credential to delete.

​
Available tools

Worker genies have access to the following tools during execution:
ToolDescription
web_fetchHTTP request to any URL. Supports GET, POST, PUT, PATCH, DELETE. Auto-injects stored credentials.
memory_readRead from durable memory store (account or genie-scoped).
memory_writeWrite to durable memory store. Persists across runs.
query_dataQuery internal tables: conversations, leads, call_logs, agents, lead_activities, documents, email_logs.
notify_ownerSend email or dashboard notification to the account owner.