Goals

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.

string

required

Must be "goals".

string

required

Must be "list".

object

Show properties

number

Results per page. Range: 1-1000. Default: 50.

number

Pagination offset. Default: 0.

string

Filter goals to a specific agent.

string

Filter by goal status.

string

Search goals by name.

boolean

Admin only. View other users’ goals.

string

Admin only. Scope to a specific user’s goals.

Response

boolean

object

Show properties

object[]

Array of goal objects. See goal object.

number

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

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

Get a goal

Retrieves a specific goal by ID.

string

required

Must be "goals".

string

required

Must be "get".

string

required

The goal UUID.

object

Show properties

boolean

Admin only. Allows fetching other users’ goals.

Response

boolean

object

Show properties

object

See goal object.

Create a goal

Creates a new goal associated with an agent.

string

required

Must be "goals".

string

required

Must be "create".

object

required

Show properties

string

required

Goal name.

string

required

Associated agent ID.

string

Goal description.

string

Goal status. Default: "active".

number

Priority level.

string

Admin only. Create goal on behalf of another user.

Response (status 201)

boolean

object

Show properties

object

The created goal object.

Update a goal

Updates an existing goal. Supports partial updates.

string

required

Must be "goals".

string

required

Must be "update".

string

required

The goal UUID.

object

required

Any combination of name, description, status, priority, agent_id.

Delete a goal

Permanently deletes a goal.

string

required

Must be "goals".

string

required

Must be "delete".

string

required

The goal UUID.

Response

boolean

object

Show properties

boolean

string

Attach goal to agent

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

string

required

Must be "goals".

string

required

Must be "attach".

object

required

Show properties

string

required

The goal to attach.

string

required

The agent to attach the goal to.

Response

boolean

object

Show properties

boolean

string

Verifies ownership of both the goal and the agent before attaching.

await ApiService.invoke({
  resource: "goals",
  action: "attach",
  data: {
    goalId: "goal-uuid",
    agentId: "agent-uuid",
  },
});

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

Detach goal from agent

Removes a goal attachment from an agent.

string

required

Must be "goals".

string

required

Must be "detach".

object

required

Show properties

string

required

The goal to detach.

string

required

The agent to detach the goal from.

Response

boolean

object

Show properties

boolean

string

Generate goal

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

string

required

Must be "goals".

string

required

Must be "generate".

object

required

Show properties

string

required

Natural-language description of the goal to generate.

Response

boolean

object

Show properties

string

Suggested goal name.

string

Suggested goal description.

object[]

Up to 50 suggested lead-info fields.

Show field properties

string

Field type: text, email, phone, textarea, or select.

number

Confidence score from 0 to 1.

Generation uses AI (temperature 0.5). Results are suggestions — review before saving.

const result = await ApiService.invoke({
  resource: "goals",
  action: "generate",
  data: {
    description: "Collect customer name, email, and preferred contact time for callback scheduling",
  },
});

Goal object

string

string | null

string

number | null

string

object

Present only in admin mode.

Show properties

string

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

Overview

Public (unauthenticated)

Agents

Knowledge

CRM

Marketplace

Platform

Telephony

Worker genies

Quality & Compliance

Access Control

Intelligence

Education

Voice

Integrations

Expanded Platform

List goals

Response

Get a goal

Response

Create a goal

Response (status 201)

Update a goal

Delete a goal

Response

Attach goal to agent

Response

Detach goal from agent

Response

Generate goal

Response

Goal object

Error responses

​List goals

​Response

​Get a goal

​Response

​Create a goal

​Response (status 201)

​Update a goal

​Delete a goal

​Response

​Attach goal to agent

​Response

​Detach goal from agent

​Response

​Generate goal

​Response

​Goal object

​Error responses

List goals

Response

Get a goal

Response

Create a goal

Response (status 201)

Update a goal

Delete a goal

Response

Attach goal to agent

Response

Detach goal from agent

Response

Generate goal

Response

Goal object

Error responses