Skip to main content
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

​
Response

​
success
boolean
​
data
object
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

​
Response

​
success
boolean
​
data
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

​
Response (status 201)

​
success
boolean
​
data
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

​
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

​
Response

​
success
boolean
​
data
object
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",
  },
});

​
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

​
Response

​
success
boolean
​
data
object

​
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

​
Response

​
success
boolean
​
data
object
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

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

​
Error responses

StatusCodeDescription
400VALIDATION_ERRORInvalid parameters
401UNAUTHORIZEDMissing or invalid authentication
403FORBIDDENAccess denied
404NOT_FOUNDGoal not found
500INTERNAL_ERRORServer error