Worker genies

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.

string

required

Must be "worker-genies".

string

required

Must be "all" or "list".

boolean

object

Show properties

array

Show item properties

string

Worker genie UUID.

string

Display name.

string

Instructions for the genie.

string

AI model identifier.

string

manual, schedule, or event.

string

Cron expression (if scheduled).

string[]

Names of stored credentials.

boolean

Whether the genie is active.

string

ISO 8601 timestamp of last run.

string

ISO 8601 creation timestamp.

string

ISO 8601 last-updated timestamp.

curl -s https://api.helpgenie.ai/v1/worker-genies \
  -H "Authorization: Bearer hg_live_YOUR_KEY"

{
  "resource": "worker-genies",
  "action": "all"
}

{
  "success": true,
  "data": {
    "items": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "name": "HubSpot Contact Digest",
        "soul_prompt": "You are a sales intelligence worker...",
        "model": "claude-sonnet-4-6",
        "trigger_type": "manual",
        "schedule": null,
        "credential_refs": ["hubspot_api"],
        "enabled": true,
        "last_run_at": "2024-03-01T10:00:00.000Z",
        "created_at": "2024-01-15T10:30:00.000Z",
        "updated_at": "2024-01-15T10:30:00.000Z"
      }
    ]
  }
}

Get worker genie

Retrieves a single worker genie by ID, including recent run history.

string

required

Must be "worker-genies".

string

required

Must be "get".

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"

{
  "resource": "worker-genies",
  "action": "get",
  "id": "550e8400-e29b-41d4-a716-446655440000"
}

Create worker genie

Creates a new worker genie with the specified configuration.

string

required

Must be "worker-genies".

string

required

Must be "create".

object

required

Show properties

string

required

Display name for the worker genie.

string

required

Detailed instructions for what the genie should do during each run.

string

default:"claude-sonnet-4-6"

AI model identifier.

string

default:"manual"

manual, schedule, or event.

string

Cron expression. Required when trigger_type is schedule.

string[]

Names of stored credentials this genie can access during runs.

boolean

default:"true"

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"]
  }'

{
  "resource": "worker-genies",
  "action": "create",
  "data": {
    "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"]
  }
}

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "HubSpot Contact Digest",
    "soul_prompt": "You are a sales intelligence worker...",
    "model": "claude-sonnet-4-6",
    "trigger_type": "manual",
    "enabled": true,
    "created_at": "2024-01-15T10:30:00.000Z"
  }
}

Update worker genie

Updates an existing worker genie. Supports partial updates.

string

required

Must be "worker-genies".

string

required

Must be "update".

string

required

The UUID of the worker genie to update.

Delete worker genie

Permanently deletes a worker genie and all of its run history.

string

required

Must be "worker-genies".

string

required

Must be "delete".

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.

string

required

Must be "worker-genies".

string

required

Must be "run".

string

required

The UUID of the worker genie to run.

object

Show properties

string

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" }'

{
  "resource": "worker-genies",
  "action": "run",
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "data": {
    "context": "Focus on new contacts from the last 24 hours"
  }
}

Get run history

Retrieves the execution history for a worker genie or all worker genies.

string

required

Must be "worker-genies".

string

required

Must be "runs".

string

Optional worker genie UUID. If omitted, returns runs for all genies.

array

Show item properties

string

Run UUID.

string

Worker genie UUID.

string

What triggered the run (manual, schedule, event).

string

Run status.

string

ISO 8601 start timestamp.

string

ISO 8601 end timestamp.

string

AI-generated summary of the run.

number

Number of tool calls made.

string

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" }'

{
  "resource": "worker-genies",
  "action": "runs",
  "id": "550e8400-e29b-41d4-a716-446655440000"
}

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.

string

required

Must be "worker-genies".

string

required

Must be "test-credential".

object

required

Show properties

string

Name of an already-stored credential to test. If provided without value, tests the stored credential.

string

A credential value to test before storing. Used with credential_type.

string

Type of the credential being tested. Default: "bearer_token".

string

URL to make a test request against. If omitted, only checks that the credential exists.

string

Custom header name for api_key_header type. Default: "X-Api-Key".

object

Show properties

boolean

Whether the credential test passed.

number

HTTP status code from the test request (if a URL was provided).

string

Human-readable result message.

string

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.

string

required

Must be "worker-genies".

string

required

Must be "store-credential".

object

required

Show properties

string

required

Unique name used as a reference in credential_refs.

string

required

bearer_token, api_key_header, basic_auth, or oauth2.

string

required

The secret value to store.

object

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.

string

required

Must be "worker-genies".

string

required

Must be "list-credentials".

array

Show item properties

string

Credential UUID.

string

Credential name.

string

Type of credential.

object

Extra configuration.

string

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.

string

required

Must be "worker-genies".

string

required

Must be "delete-credential".

string

required

The UUID of the credential to delete.

Available tools

Worker genies have access to the following tools during execution:

Tool	Description
`web_fetch`	HTTP request to any URL. Supports GET, POST, PUT, PATCH, DELETE. Auto-injects stored credentials.
`memory_read`	Read from durable memory store (account or genie-scoped).
`memory_write`	Write to durable memory store. Persists across runs.
`query_data`	Query internal tables: conversations, leads, call_logs, agents, lead_activities, documents, email_logs.
`notify_owner`	Send email or dashboard notification to the account owner.

Overview

Public (unauthenticated)

Agents

Knowledge

CRM

Marketplace

Platform

Telephony

Quality & Compliance

Access Control

Intelligence

Education

Voice

Integrations

Expanded Platform

Worker genies

List worker genies

Get worker genie

Create worker genie

Update worker genie

Delete worker genie

Run worker genie

Get run history

Test credential

Store credential

List credentials

Delete credential

Available tools

​List worker genies

​Get worker genie

​Create worker genie

​Update worker genie

​Delete worker genie

​Run worker genie

​Get run history

​Test credential

​Store credential

​List credentials

​Delete credential

​Available tools

List worker genies

Get worker genie

Create worker genie

Update worker genie

Delete worker genie

Run worker genie

Get run history

Test credential

Store credential

List credentials

Delete credential

Available tools