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.
Instructions for the genie.
manual, schedule, or event.
Cron expression (if scheduled).
Names of stored credentials.
Whether the genie is active.
ISO 8601 timestamp of last run.
ISO 8601 creation timestamp.
ISO 8601 last-updated timestamp.
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.
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.
Display name for the worker genie.
Detailed instructions for what the genie should do during each run.
model
string
default: "claude-sonnet-4-6"
AI model identifier.
manual, schedule, or event.
Cron expression. Required when trigger_type is schedule.
Names of stored credentials this genie can access during runs.
Whether the genie is active.
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.
The UUID of the worker genie to update.
Delete worker genie Permanently deletes a worker genie and all of its run history.
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.
The UUID of the worker genie to run.
Additional context passed to the genie for this run.
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.
Optional worker genie UUID. If omitted, returns runs for all genies.
What triggered the run (manual, schedule, event).
ISO 8601 start timestamp.
AI-generated summary of the run.
Number of tool calls made.
Error message if the run failed.
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.
Must be "test-credential".
Name of an already-stored credential to test. If provided without value, tests the stored credential.
A credential value to test before storing. Used with credential_type.
Type of the credential being tested. Default: "bearer_token".
URL to make a test request against. If omitted, only checks that the credential exists.
Custom header name for api_key_header type. Default: "X-Api-Key".
Whether the credential test passed.
HTTP status code from the test request (if a URL was provided).
Human-readable result message.
Error message if the test failed.
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.
Must be "store-credential".
Unique name used as a reference in credential_refs.
bearer_token, api_key_header, basic_auth, or oauth2.
The secret value to store.
Extra configuration, for example { "header_name": "X-Api-Key" }.
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.
Must be "list-credentials".
ISO 8601 creation timestamp.
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.
Must be "delete-credential".
The UUID of the credential to delete.
Worker genies have access to the following tools during execution:
Tool Description 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.
