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.

resource · string · required

Must be "goals".

action · string · required

Must be "list".

data · object

Show properties

limit · number

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

offset · number

Pagination offset. Default: 0.

agentId · string

Filter goals to a specific agent.

status · string

Filter by goal status.

searchTerm · string

Search goals by name.

adminMode · boolean

Admin only. View other users’ goals.

userId · string

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

Response

success · boolean

data · object

Show properties

items · object[]

Array of goal objects. See goal object.

count · number

limit · number

offset · number

Example request

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

---

Get a goal

Retrieves a specific goal by ID.

resource · string · required

Must be "goals".

action · string · required

Must be "get".

id · string · required

The goal UUID.

data · object

Show properties

adminMode · boolean

Admin only. Allows fetching other users’ goals.

Response

success · boolean

data · object

Show properties

goal · object

See goal object.

---

Create a goal

Creates a new goal associated with an agent.

resource · string · required

Must be "goals".

action · string · required

Must be "create".

data · object · required

Show properties

name · string · required

Goal name.

agent_id · string · required

Associated agent ID.

description · string

Goal description.

status · string

Goal status. Default: "active".

priority · number

Priority level.

userId · string

Admin only. Create goal on behalf of another user.

Response (status 201)

success · boolean

data · object

Show properties

goal · object

The created goal object.

---

Update a goal

Updates an existing goal. Supports partial updates.

resource · string · required

Must be "goals".

action · string · required

Must be "update".

id · string · required

The goal UUID.

data · object · required

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

---

Delete a goal

Permanently deletes a goal.

resource · string · required

Must be "goals".

action · string · required

Must be "delete".

id · string · required

The goal UUID.

Response

success · boolean

data · object

Show properties

success · boolean

message · string

goalId · string

---

Attach goal to agent

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

resource · string · required

Must be "goals".

action · string · required

Must be "attach".

data · object · required

Show properties

goalId · string · required

The goal to attach.

agentId · string · required

The agent to attach the goal to.

Response

success · boolean

data · object

Show properties

success · boolean

message · string

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

Example request

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

---

Detach goal from agent

Removes a goal attachment from an agent.

resource · string · required

Must be "goals".

action · string · required

Must be "detach".

data · object · required

Show properties

goalId · string · required

The goal to detach.

agentId · string · required

The agent to detach the goal from.

Response

success · boolean

data · object

Show properties

success · boolean

message · string

---

Generate goal

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

resource · string · required

Must be "goals".

action · string · required

Must be "generate".

data · object · required

Show properties

description · string · required

Natural-language description of the goal to generate.

Response

success · boolean

data · object

Show properties

name · string

Suggested goal name.

description · string

Suggested goal description.

fields · object[]

Up to 50 suggested lead-info fields.

Show field properties

type · string

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

confidence · number

Confidence score from 0 to 1.

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

Example request

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

---

Goal object

id · string

agent_id · string

name · string

description · string | null

status · string

priority · number | null

created_at · string

updated_at · string

owner · object

Present only in admin mode.

Show properties

id · string

full_name · string

email · 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