> ## Documentation Index
> Fetch the complete documentation index at: https://docs.helpgenie.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Worker genies

> Create and manage autonomous background AI agents that execute tasks on schedule, by event, or manually

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`.

<Note>
  Worker genies run server-side and have access to stored credentials for calling external APIs securely.
</Note>

***

## List worker genies

Retrieves all worker genies for the authenticated user.

<ParamField body="resource" type="string" required>
  Must be `"worker-genies"`.
</ParamField>

<ParamField body="action" type="string" required>
  Must be `"all"` or `"list"`.
</ParamField>

<ResponseField name="success" type="boolean" />

<ResponseField name="data" type="object">
  <Expandable title="properties">
    <ResponseField name="items" type="array">
      <Expandable title="item properties">
        <ResponseField name="id" type="string">Worker genie UUID.</ResponseField>
        <ResponseField name="name" type="string">Display name.</ResponseField>
        <ResponseField name="soul_prompt" type="string">Instructions for the genie.</ResponseField>
        <ResponseField name="model" type="string">AI model identifier.</ResponseField>
        <ResponseField name="trigger_type" type="string">`manual`, `schedule`, or `event`.</ResponseField>
        <ResponseField name="schedule" type="string">Cron expression (if scheduled).</ResponseField>
        <ResponseField name="credential_refs" type="string[]">Names of stored credentials.</ResponseField>
        <ResponseField name="enabled" type="boolean">Whether the genie is active.</ResponseField>
        <ResponseField name="last_run_at" type="string">ISO 8601 timestamp of last run.</ResponseField>
        <ResponseField name="created_at" type="string">ISO 8601 creation timestamp.</ResponseField>
        <ResponseField name="updated_at" type="string">ISO 8601 last-updated timestamp.</ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<CodeGroup>
  ```bash cURL theme={null}
  curl -s https://api.helpgenie.ai/v1/worker-genies \
    -H "Authorization: Bearer hg_live_YOUR_KEY"
  ```

  ```json Request body theme={null}
  {
    "resource": "worker-genies",
    "action": "all"
  }
  ```

  ```json Response theme={null}
  {
    "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"
        }
      ]
    }
  }
  ```
</CodeGroup>

***

## Get worker genie

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

<ParamField body="resource" type="string" required>
  Must be `"worker-genies"`.
</ParamField>

<ParamField body="action" type="string" required>
  Must be `"get"`.
</ParamField>

<ParamField body="id" type="string" required>
  The UUID of the worker genie.
</ParamField>

<CodeGroup>
  ```bash cURL theme={null}
  curl -s https://api.helpgenie.ai/v1/worker-genies/GENIE_UUID \
    -H "Authorization: Bearer hg_live_YOUR_KEY"
  ```

  ```json Request body theme={null}
  {
    "resource": "worker-genies",
    "action": "get",
    "id": "550e8400-e29b-41d4-a716-446655440000"
  }
  ```
</CodeGroup>

***

## Create worker genie

Creates a new worker genie with the specified configuration.

<ParamField body="resource" type="string" required>
  Must be `"worker-genies"`.
</ParamField>

<ParamField body="action" type="string" required>
  Must be `"create"`.
</ParamField>

<ParamField body="data" type="object" required>
  <Expandable title="properties">
    <ParamField body="name" type="string" required>
      Display name for the worker genie.
    </ParamField>

    <ParamField body="soul_prompt" type="string" required>
      Detailed instructions for what the genie should do during each run.
    </ParamField>

    <ParamField body="model" type="string" default="claude-sonnet-4-6">
      AI model identifier.
    </ParamField>

    <ParamField body="trigger_type" type="string" default="manual">
      `manual`, `schedule`, or `event`.
    </ParamField>

    <ParamField body="schedule" type="string">
      Cron expression. Required when `trigger_type` is `schedule`.
    </ParamField>

    <ParamField body="credential_refs" type="string[]">
      Names of stored credentials this genie can access during runs.
    </ParamField>

    <ParamField body="enabled" type="boolean" default="true">
      Whether the genie is active.
    </ParamField>
  </Expandable>
</ParamField>

<CodeGroup>
  ```bash cURL theme={null}
  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"]
    }'
  ```

  ```json Request body theme={null}
  {
    "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"]
    }
  }
  ```

  ```json Response theme={null}
  {
    "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"
    }
  }
  ```
</CodeGroup>

***

## Update worker genie

Updates an existing worker genie. Supports partial updates.

<ParamField body="resource" type="string" required>
  Must be `"worker-genies"`.
</ParamField>

<ParamField body="action" type="string" required>
  Must be `"update"`.
</ParamField>

<ParamField body="id" type="string" required>
  The UUID of the worker genie to update.
</ParamField>

***

## Delete worker genie

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

<ParamField body="resource" type="string" required>
  Must be `"worker-genies"`.
</ParamField>

<ParamField body="action" type="string" required>
  Must be `"delete"`.
</ParamField>

<ParamField body="id" type="string" required>
  The UUID of the worker genie to delete.
</ParamField>

<Warning>
  This action is irreversible. The worker genie and all associated run history will be permanently deleted.
</Warning>

***

## Run worker genie

Triggers a manual run of a worker genie. The run executes asynchronously and results can be retrieved via run history.

<ParamField body="resource" type="string" required>
  Must be `"worker-genies"`.
</ParamField>

<ParamField body="action" type="string" required>
  Must be `"run"`.
</ParamField>

<ParamField body="id" type="string" required>
  The UUID of the worker genie to run.
</ParamField>

<ParamField body="data" type="object">
  <Expandable title="properties">
    <ParamField body="context" type="string">
      Additional context passed to the genie for this run.
    </ParamField>
  </Expandable>
</ParamField>

<CodeGroup>
  ```bash cURL theme={null}
  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" }'
  ```

  ```json Request body theme={null}
  {
    "resource": "worker-genies",
    "action": "run",
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "data": {
      "context": "Focus on new contacts from the last 24 hours"
    }
  }
  ```
</CodeGroup>

***

## Get run history

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

<ParamField body="resource" type="string" required>
  Must be `"worker-genies"`.
</ParamField>

<ParamField body="action" type="string" required>
  Must be `"runs"`.
</ParamField>

<ParamField body="id" type="string">
  Optional worker genie UUID. If omitted, returns runs for all genies.
</ParamField>

<ResponseField name="data.items" type="array">
  <Expandable title="item properties">
    <ResponseField name="id" type="string">Run UUID.</ResponseField>
    <ResponseField name="genie_id" type="string">Worker genie UUID.</ResponseField>
    <ResponseField name="trigger" type="string">What triggered the run (`manual`, `schedule`, `event`).</ResponseField>
    <ResponseField name="status" type="string">Run status.</ResponseField>
    <ResponseField name="started_at" type="string">ISO 8601 start timestamp.</ResponseField>
    <ResponseField name="finished_at" type="string">ISO 8601 end timestamp.</ResponseField>
    <ResponseField name="summary" type="string">AI-generated summary of the run.</ResponseField>
    <ResponseField name="tool_calls_count" type="number">Number of tool calls made.</ResponseField>
    <ResponseField name="error" type="string">Error message if the run failed.</ResponseField>
  </Expandable>
</ResponseField>

<CodeGroup>
  ```bash cURL theme={null}
  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" }'
  ```

  ```json Request body theme={null}
  {
    "resource": "worker-genies",
    "action": "runs",
    "id": "550e8400-e29b-41d4-a716-446655440000"
  }
  ```
</CodeGroup>

***

## 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.

<ParamField body="resource" type="string" required>
  Must be `"worker-genies"`.
</ParamField>

<ParamField body="action" type="string" required>
  Must be `"test-credential"`.
</ParamField>

<ParamField body="data" type="object" required>
  <Expandable title="properties">
    <ParamField body="name" type="string">
      Name of an already-stored credential to test. If provided without `value`, tests the stored credential.
    </ParamField>

    <ParamField body="value" type="string">
      A credential value to test before storing. Used with `credential_type`.
    </ParamField>

    <ParamField body="credential_type" type="string">
      Type of the credential being tested. Default: `"bearer_token"`.
    </ParamField>

    <ParamField body="url" type="string">
      URL to make a test request against. If omitted, only checks that the credential exists.
    </ParamField>

    <ParamField body="header_name" type="string">
      Custom header name for `api_key_header` type. Default: `"X-Api-Key"`.
    </ParamField>
  </Expandable>
</ParamField>

<ResponseField name="data" type="object">
  <Expandable title="properties">
    <ResponseField name="valid" type="boolean">
      Whether the credential test passed.
    </ResponseField>

    <ResponseField name="status" type="number">
      HTTP status code from the test request (if a URL was provided).
    </ResponseField>

    <ResponseField name="message" type="string">
      Human-readable result message.
    </ResponseField>

    <ResponseField name="error" type="string">
      Error message if the test failed.
    </ResponseField>
  </Expandable>
</ResponseField>

<CodeGroup>
  ```bash cURL theme={null}
  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"
      }
    }'
  ```
</CodeGroup>

***

## Store credential

Stores an encrypted API credential that worker genies can use during runs. Credentials are encrypted at rest using AES-GCM.

<ParamField body="resource" type="string" required>
  Must be `"worker-genies"`.
</ParamField>

<ParamField body="action" type="string" required>
  Must be `"store-credential"`.
</ParamField>

<ParamField body="data" type="object" required>
  <Expandable title="properties">
    <ParamField body="name" type="string" required>
      Unique name used as a reference in `credential_refs`.
    </ParamField>

    <ParamField body="credential_type" type="string" required>
      `bearer_token`, `api_key_header`, `basic_auth`, or `oauth2`.
    </ParamField>

    <ParamField body="value" type="string" required>
      The secret value to store.
    </ParamField>

    <ParamField body="metadata" type="object">
      Extra configuration, for example `{ "header_name": "X-Api-Key" }`.
    </ParamField>
  </Expandable>
</ParamField>

<CodeGroup>
  ```bash cURL theme={null}
  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"
    }'
  ```
</CodeGroup>

***

## List credentials

Lists all stored credentials for the authenticated user. Secret values are never returned.

<ParamField body="resource" type="string" required>
  Must be `"worker-genies"`.
</ParamField>

<ParamField body="action" type="string" required>
  Must be `"list-credentials"`.
</ParamField>

<ResponseField name="data.items" type="array">
  <Expandable title="item properties">
    <ResponseField name="id" type="string">Credential UUID.</ResponseField>
    <ResponseField name="name" type="string">Credential name.</ResponseField>
    <ResponseField name="credential_type" type="string">Type of credential.</ResponseField>
    <ResponseField name="metadata" type="object">Extra configuration.</ResponseField>
    <ResponseField name="created_at" type="string">ISO 8601 creation timestamp.</ResponseField>
  </Expandable>
</ResponseField>

<CodeGroup>
  ```bash cURL theme={null}
  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" }'
  ```
</CodeGroup>

***

## Delete credential

Deletes a stored credential by ID.

<ParamField body="resource" type="string" required>
  Must be `"worker-genies"`.
</ParamField>

<ParamField body="action" type="string" required>
  Must be `"delete-credential"`.
</ParamField>

<ParamField body="id" type="string" required>
  The UUID of the credential to delete.
</ParamField>

***

## 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.                                                 |