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

# Goals

> Manage goal records, outcomes, and lead-info presets for agents

Use `goals` to create, manage, and attach goal records to agents. Goals represent targets or outcomes that an agent should achieve, and can include lead-info field definitions.

Supported actions: `list`, `get`, `create`, `update`, `delete`, `attach`, `detach`, `generate`.

***

## List goals

Retrieves all goals for the authenticated user with optional filtering.

<ParamField body="resource" type="string" required>
  Must be `"goals"`.
</ParamField>

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

<ParamField body="data" type="object">
  <Expandable title="properties">
    <ParamField body="limit" type="number">
      Results per page. Range: 1-1000. Default: `50`.
    </ParamField>

    <ParamField body="offset" type="number">
      Pagination offset. Default: `0`.
    </ParamField>

    <ParamField body="agentId" type="string">
      Filter goals to a specific agent.
    </ParamField>

    <ParamField body="status" type="string">
      Filter by goal status.
    </ParamField>

    <ParamField body="searchTerm" type="string">
      Search goals by name.
    </ParamField>

    <ParamField body="adminMode" type="boolean">
      Admin only. View other users' goals.
    </ParamField>

    <ParamField body="userId" type="string">
      Admin only. Scope to a specific user's goals.
    </ParamField>
  </Expandable>
</ParamField>

### Response

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

<ResponseField name="data" type="object">
  <Expandable title="properties">
    <ResponseField name="items" type="object[]">
      Array of goal objects. See [goal object](#goal-object).
    </ResponseField>

    <ResponseField name="count" type="number" />

    <ResponseField name="limit" type="number" />

    <ResponseField name="offset" type="number" />
  </Expandable>
</ResponseField>

<CodeGroup>
  ```typescript Example request theme={null}
  const response = await ApiService.invoke<{
    items: Goal[];
    count: number;
  }>({
    resource: "goals",
    action: "list",
    data: {
      agentId: "agent-uuid",
      status: "active",
      limit: 50,
    },
  });
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.helpgenie.ai/v1/goals \
    -H "Authorization: Bearer hg_live_YOUR_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "action": "list",
      "data": { "agentId": "agent-uuid", "status": "active" }
    }'
  ```
</CodeGroup>

***

## Get a goal

Retrieves a specific goal by ID.

<ParamField body="resource" type="string" required>
  Must be `"goals"`.
</ParamField>

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

<ParamField body="id" type="string" required>
  The goal UUID.
</ParamField>

<ParamField body="data" type="object">
  <Expandable title="properties">
    <ParamField body="adminMode" type="boolean">
      Admin only. Allows fetching other users' goals.
    </ParamField>
  </Expandable>
</ParamField>

### Response

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

<ResponseField name="data" type="object">
  <Expandable title="properties">
    <ResponseField name="goal" type="object">
      See [goal object](#goal-object).
    </ResponseField>
  </Expandable>
</ResponseField>

***

## Create a goal

Creates a new goal associated with an agent.

<ParamField body="resource" type="string" required>
  Must be `"goals"`.
</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>
      Goal name.
    </ParamField>

    <ParamField body="agent_id" type="string" required>
      Associated agent ID.
    </ParamField>

    <ParamField body="description" type="string">
      Goal description.
    </ParamField>

    <ParamField body="status" type="string">
      Goal status. Default: `"active"`.
    </ParamField>

    <ParamField body="priority" type="number">
      Priority level.
    </ParamField>

    <ParamField body="userId" type="string">
      Admin only. Create goal on behalf of another user.
    </ParamField>
  </Expandable>
</ParamField>

### Response (status 201)

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

<ResponseField name="data" type="object">
  <Expandable title="properties">
    <ResponseField name="goal" type="object">
      The created goal object.
    </ResponseField>
  </Expandable>
</ResponseField>

***

## Update a goal

Updates an existing goal. Supports partial updates.

<ParamField body="resource" type="string" required>
  Must be `"goals"`.
</ParamField>

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

<ParamField body="id" type="string" required>
  The goal UUID.
</ParamField>

<ParamField body="data" type="object" required>
  Any combination of `name`, `description`, `status`, `priority`, `agent_id`.
</ParamField>

***

## Delete a goal

Permanently deletes a goal.

<ParamField body="resource" type="string" required>
  Must be `"goals"`.
</ParamField>

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

<ParamField body="id" type="string" required>
  The goal UUID.
</ParamField>

### Response

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

<ResponseField name="data" type="object">
  <Expandable title="properties">
    <ResponseField name="success" type="boolean" />

    <ResponseField name="message" type="string" />

    <ResponseField name="goalId" type="string" />
  </Expandable>
</ResponseField>

***

## Attach goal to agent

Links a goal (lead-info preset) to an agent. Any existing attachment for that agent is replaced.

<ParamField body="resource" type="string" required>
  Must be `"goals"`.
</ParamField>

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

<ParamField body="data" type="object" required>
  <Expandable title="properties">
    <ParamField body="goalId" type="string" required>
      The goal to attach.
    </ParamField>

    <ParamField body="agentId" type="string" required>
      The agent to attach the goal to.
    </ParamField>
  </Expandable>
</ParamField>

### Response

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

<ResponseField name="data" type="object">
  <Expandable title="properties">
    <ResponseField name="success" type="boolean" />

    <ResponseField name="message" type="string" />
  </Expandable>
</ResponseField>

<Note>
  Verifies ownership of both the goal and the agent before attaching.
</Note>

<CodeGroup>
  ```typescript Example request theme={null}
  await ApiService.invoke({
    resource: "goals",
    action: "attach",
    data: {
      goalId: "goal-uuid",
      agentId: "agent-uuid",
    },
  });
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.helpgenie.ai/v1/goals \
    -H "Authorization: Bearer hg_live_YOUR_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "action": "attach",
      "data": {
        "goalId": "goal-uuid",
        "agentId": "agent-uuid"
      }
    }'
  ```
</CodeGroup>

***

## Detach goal from agent

Removes a goal attachment from an agent.

<ParamField body="resource" type="string" required>
  Must be `"goals"`.
</ParamField>

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

<ParamField body="data" type="object" required>
  <Expandable title="properties">
    <ParamField body="goalId" type="string" required>
      The goal to detach.
    </ParamField>

    <ParamField body="agentId" type="string" required>
      The agent to detach the goal from.
    </ParamField>
  </Expandable>
</ParamField>

### Response

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

<ResponseField name="data" type="object">
  <Expandable title="properties">
    <ResponseField name="success" type="boolean" />

    <ResponseField name="message" type="string" />
  </Expandable>
</ResponseField>

***

## Generate goal

Uses AI to generate a goal configuration from a natural-language description. Returns suggested fields that can be reviewed before saving.

<ParamField body="resource" type="string" required>
  Must be `"goals"`.
</ParamField>

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

<ParamField body="data" type="object" required>
  <Expandable title="properties">
    <ParamField body="description" type="string" required>
      Natural-language description of the goal to generate.
    </ParamField>
  </Expandable>
</ParamField>

### Response

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

<ResponseField name="data" type="object">
  <Expandable title="properties">
    <ResponseField name="name" type="string">
      Suggested goal name.
    </ResponseField>

    <ResponseField name="description" type="string">
      Suggested goal description.
    </ResponseField>

    <ResponseField name="fields" type="object[]">
      Up to 50 suggested lead-info fields.

      <Expandable title="field properties">
        <ResponseField name="type" type="string">
          Field type: `text`, `email`, `phone`, `textarea`, or `select`.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="confidence" type="number">
      Confidence score from 0 to 1.
    </ResponseField>
  </Expandable>
</ResponseField>

<Info>
  Generation uses AI (temperature 0.5). Results are suggestions — review before saving.
</Info>

<CodeGroup>
  ```typescript Example request theme={null}
  const result = await ApiService.invoke({
    resource: "goals",
    action: "generate",
    data: {
      description: "Collect customer name, email, and preferred contact time for callback scheduling",
    },
  });
  ```
</CodeGroup>

***

## Goal object

<ResponseField name="id" type="string" />

<ResponseField name="agent_id" type="string" />

<ResponseField name="name" type="string" />

<ResponseField name="description" type="string | null" />

<ResponseField name="status" type="string" />

<ResponseField name="priority" type="number | null" />

<ResponseField name="created_at" type="string" />

<ResponseField name="updated_at" type="string" />

<ResponseField name="owner" type="object">
  Present only in admin mode.

  <Expandable title="properties">
    <ResponseField name="id" type="string" />

    <ResponseField name="full_name" type="string" />

    <ResponseField name="email" type="string" />
  </Expandable>
</ResponseField>

***

## Error responses

| Status | Code               | Description                       |
| ------ | ------------------ | --------------------------------- |
| 400    | `VALIDATION_ERROR` | Invalid parameters                |
| 401    | `UNAUTHORIZED`     | Missing or invalid authentication |
| 403    | `FORBIDDEN`        | Access denied                     |
| 404    | `NOT_FOUND`        | Goal not found                    |
| 500    | `INTERNAL_ERROR`   | Server error                      |