Developer Platform (April 2026)

Intelligent Agents (Agents, Categories, Runs)

«  Surveys   ·  [   home  ·   reference  ·   community   |   search  ·   index   ·  routing table   ·  scopes table   ]   ·  My CPD Records  »

Intelligent agents provide the ability to monitor user activity within an org unit and take automated actions based on configurable conditions and schedules. This API allows you to manage intelligent agents, their categories, and their run history.

Attributes

SCHEDULETYPE_T

Intelligent agents can have different schedule types, identified by these integer values:

Value

Description

0

Daily

1

Weekly

2

Monthly

3

Yearly

4

Hourly

5

One-time run
ENROLLMENTTYPE_T

Enrollment actions on intelligent agents can have one of the following types, identified by these integer values:

Value

Description

0

Enroll

1

Unenroll
RUNNOWTYPE_T

When triggering an agent run manually, you can specify the type of run using these integer values:

Value

Description

0

Practice run (no actions are taken)

1

Full run (default; actions are executed)
AGENTRUNTYPE_T

Agent runs can be one of several types, identified by these integer values:

Value

Description

0

Practice run

1

Manual run

2

Scheduled run
AGENTSORTFIELD_T

You can sort the list of agents by providing one of these string values as the sortField query parameter:

Value

Description

Name

Sort by agent name (default)

LastRunDate

Sort by the date the agent was last run

NextRunDateTime

Sort by the next scheduled run date/time
LOGINCONDITIONTYPE_T

The Type field on a IntelligentAgents.DateCondition block used within LoginActivity takes one of these integer values:

Value

Description

0

Has not logged in within the specified number of days

1

Has logged in within the specified number of days
ACCESSCONDITIONTYPE_T

The Type field on a IntelligentAgents.DateCondition block used within CourseActivity takes one of these integer values:

Value

Description

0

Has not accessed the course within the specified number of days

1

Has accessed the course within the specified number of days

Agent data

IntelligentAgents.AgentData

When you use actions that retrieve or create/update intelligent agent information, the service provides or expects a block like this:

{
    "AgentId": <number:D2LID>|null,
    "Name": <string>,
    "Description": <string>,
    "IsEnabled": <boolean>,
    "Schedule": { <composite:IntelligentAgents.ScheduleData> }|null,
    "Action": { <composite:IntelligentAgents.ActionData> }|null,
    "Condition": { <composite:IntelligentAgents.ConditionData> }|null,
    "LastRunDate": <string:UTCDateTime>|null,
    "NextRunDate": <string:UTCDateTime>|null,
    "CategoryId": <number:D2LID>|null
}
AgentId

The system-assigned identifier for the agent. On input for creation this value is ignored; on output it is always present.

Schedule

An optional IntelligentAgents.ScheduleData block describing the agent’s schedule. Can be null if no schedule is configured.

Action

An optional IntelligentAgents.ActionData block describing the actions the agent takes when it runs. Can be null if no actions are configured.

Condition

An optional IntelligentAgents.ConditionData block describing the conditions that must be met for the agent to act on a user. Can be null if no conditions are configured.

LastRunDate

Read-only. The UTC date/time the agent was last run, or null if it has never been run. This field is ignored if included on input.

NextRunDate

Read-only. The UTC date/time the agent is next scheduled to run, or null if no future run is scheduled. This is a calculated field and is ignored if included on input.

CategoryId

The identifier of the category the agent belongs to, or null if uncategorized.

IntelligentAgents.DeletedAgentData

When you retrieve deleted agents, the service provides a block like this:

{
    "AgentId": <number:D2LID>,
    "Name": <string>,
    "Description": <string>,
    "DateDeleted": <string:UTCDateTime>,
    "DeletedBy": { <composite:User> }
}
DeletedBy

A user object identifying the user who deleted the agent.

Schedule data

IntelligentAgents.ScheduleData
{
    "IsEnabled": <boolean>,
    "Type": <number:SCHEDULETYPE_T>|null,
    "StartDate": <string:UTCDateTime>|null,
    "EndDate": <string:UTCDateTime>|null,
    "RepeatsEvery": <number>|null,
    "RepeatsOnDay": <number>|null,
    "RepeatsOnDays": [ <string>, ... ]|null,
    "RepeatsOnMonth": <number>|null
}
Type

The schedule type. See SCHEDULETYPE_T.

StartDate

The UTC date/time when the schedule becomes active, or null.

EndDate

The UTC date/time when the schedule expires (inclusive), or null if the schedule does not expire.

RepeatsEvery

The repeat interval, interpreted based on the schedule Type:

Schedule type

Unit value

0 (Daily)

Number of days between runs

1 (Weekly

Number of weeks between runs

2 (Monthly)

Number of months between runs

3 (Yearly)

Number of years between runs

4 (Hourly)

Number of hours between runs

Note

Note this property’s value is not applicable and is ignored for the 5 (OneTimeRun) schedule type.

RepeatsOnDay

For monthly and yearly schedules, the day of the month (1–31) on which the agent runs. Not applicable and ignored for other schedule types.

RepeatsOnDays

For weekly schedules, an array of day-of-week strings on which the agent runs. Valid values are: “Sunday”, “Monday”, “Tuesday”, “Wednesday”, “Thursday”, “Friday”, “Saturday”. Not applicable and ignored for other schedule types.

RepeatsOnMonth

For yearly schedules, the month (1–12) on which the agent runs. Not applicable and ignored for other schedule types.

Action data

IntelligentAgents.ActionData
{
    "RepeatType": <number>,
    "EmailAction": { <composite:IntelligentAgents.EmailAction> }|null,
    "EnrollmentAction": { <composite:IntelligentAgents.EnrollmentAction> }|null
}
RepeatType

Determines whether the action repeats for the same user across runs.

  • 0 = take action only once per user

  • 1 = take action every time the user satisfies the condition.

IntelligentAgents.EmailAction
{
    "IsEnabled": <boolean>,
    "To": <string>|null,
    "Cc": <string>|null,
    "Bcc": <string>|null,
    "Subject": <string>|null,
    "Message": <string>|null,
    "IsHtml": <boolean>
}
To, Cc, Bcc

Comma-separated email address strings. {InitiatingUser}, {InitiatingUserAuditors} and {InitiatingUserParents} can be used as replace strings.

IsHtml

If true, the Message body is treated as HTML.

IntelligentAgents.EnrollmentAction
{
    "IsEnabled": <boolean>,
    "EnrollmentType": <number:ENROLLMENTTYPE_T>|null,
    "OrgUnitId": <number:D2LID>|null,
    "RoleId": <number:D2LID>|null
}
EnrollmentType

See ENROLLMENTTYPE_T. When Enroll (0), OrgUnitId and RoleId must be provided. When Unenroll (1), those fields are ignored.

Condition data

IntelligentAgents.ConditionData
{
    "LoginActivity": { <composite:IntelligentAgents.DateCondition> }|null,
    "CourseActivity": { <composite:IntelligentAgents.DateCondition> }|null,
    "ReleaseCondition": { <composite:IntelligentAgents.ReleaseCondition> }|null,
    "RoleIds": [ <number:D2LID>, ... ]|null
}
LoginActivity

Condition based on user login activity. When present, the Type field uses LOGINCONDITIONTYPE_T values. Null if not configured.

CourseActivity

Condition based on user course access activity. When present, the Type field uses ACCESSCONDITIONTYPE_T values. Null if not configured.

ReleaseCondition

A reference to a release condition set. Null if not configured.

RoleIds

An optional array of role identifiers to filter which users the agent evaluates. Null or empty means all roles.

IntelligentAgents.DateCondition
{
    "Type": <number>,
    "Days": <number>
}
Type

The type of date-based condition check. The meaning of this field depends on which parent property contains the DateCondition:

  • When used in LoginActivity: see LOGINCONDITIONTYPE_T (0 = has not logged in, 1 = has logged in).

  • When used in CourseActivity: see ACCESSCONDITIONTYPE_T (0 = has not accessed the course, 1 = has accessed the course).

Days

The number of days used in the condition evaluation (e.g. “has not logged in within the last N days”).

IntelligentAgents.ReleaseCondition
{
    "ConditionSetId": <number:D2LID>|null
}

Category data

IntelligentAgents.CategoryData

When you use actions that retrieve or create/update agent category information, the service provides or expects a block like this:

{
    "CategoryId": <number:D2LID>|null,
    "Name": <string>,
    "SortOrder": <number>|null
}
CategoryId

The system-assigned identifier for the category. On input for creation this value is ignored; on output it is always present.

SortOrder

An optional integer that describes the display order of the category. Lower numbers appear earlier in the list.

Run data

IntelligentAgents.RunData

When you use actions that retrieve or create agent run information, the service provides a block like this:

{
    "RunId": <number:D2LID>,
    "RunType": <number:AGENTRUNTYPE_T>,
    "RunNowUserId": <number:D2LID>|null,
    "StartDate": <string:UTCDateTime>|null,
    "EndDate": <string:UTCDateTime>|null,
    "NumUsers": <number>,
    "NumUsersWithInfo": <number>,
    "NumUsersWithWarnings": <number>,
    "NumUsersWithError": <number>
}
RunType

See AGENTRUNTYPE_T.

RunNowUserId

The user who initiated the run, if it was a manual or practice run. Null for scheduled runs.

NumUsers

The total number of users evaluated during the run.

NumUsersWithInfo

The number of users for whom the agent took action successfully.

NumUsersWithWarnings

The number of users for whom the agent encountered warnings.

NumUsersWithError

The number of users for whom the agent encountered errors.

IntelligentAgents.RunNowData

When you are triggering a new run, the service provides a block like this:

{
    "RunNowType": <number:RUNNOWTYPE_T>|null
}
RunType

If set to null the value defaults to 1 (full run).

Actions

Agents

DELETE /d2l/api/le/(version)/(orgUnitId)/agents/(agentId)

Delete an intelligent agent (soft delete).

Parameters:

  • version (D2LVERSION) – API version.

  • orgUnitId (D2LID) – Org unit ID.

  • agentId (D2LID) – Agent ID.

Oauth2 Scopes:

intelligentagents:agent:delete

Status Codes:
API Versions:

  • 1.93+ – Route first appears in LMS v20.26.4.

GET /d2l/api/le/(version)/(orgUnitId)/agents

Retrieve all intelligent agents for an org unit.

Parameters:
Query Parameters:

  • sortField – Optional. Sort field for the results. See AGENTSORTFIELD_T. Defaults to Name.

Oauth2 Scopes:

intelligentagents:agent:read

Status Codes:
API Versions:

  • 1.93+ – Route first appears in LMS v20.26.4.

Return. This action returns an ObjectListPage JSON block containing a list of IntelligentAgents.AgentData blocks for the org unit.

GET /d2l/api/le/(version)/(orgUnitId)/agents/deleted

Retrieve all deleted intelligent agents for an org unit.

Parameters:
Oauth2 Scopes:

intelligentagents:agent:read

Status Codes:
API Versions:

  • 1.93+ – Route first appears in LMS v20.26.4.

Return. This action returns a JSON array of IntelligentAgents.DeletedAgentData blocks.

GET /d2l/api/le/(version)/(orgUnitId)/agents/(agentId)

Retrieve a specific intelligent agent.

Parameters:

  • version (D2LVERSION) – API version.

  • orgUnitId (D2LID) – Org unit ID.

  • agentId (D2LID) – Agent ID.

Oauth2 Scopes:

intelligentagents:agent:read

Status Codes:
API Versions:

  • 1.93+ – Route first appears in LMS v20.26.4.

Return. This action returns an IntelligentAgents.AgentData JSON block.

POST /d2l/api/le/(version)/(orgUnitId)/agents

Create a new intelligent agent in the specified org unit.

Parameters:
JSON Parameters:
Oauth2 Scopes:

intelligentagents:agent:create

Status Codes:
API Versions:

  • 1.93+ – Route first appears in LMS v20.26.4.

Return. This action returns an IntelligentAgents.AgentData JSON block for the newly created agent.

POST /d2l/api/le/(version)/(orgUnitId)/agents/(agentId)

Restore a previously deleted intelligent agent.

Parameters:

  • version (D2LVERSION) – API version.

  • orgUnitId (D2LID) – Org unit ID.

  • agentId (D2LID) – Agent ID.

Oauth2 Scopes:

intelligentagents:agent:update

Status Codes:
API Versions:

  • 1.93+ – Route first appears in LMS v20.26.4.

Return. This action returns an IntelligentAgents.AgentData JSON block for the restored agent.

Note

This route shares the same URL pattern as Create Agent, but targets a specific agent ID. A POST to /d2l/api/le/{version}/{orgUnitId}/agents/{agentId} restores a deleted agent, while a POST to /d2l/api/le/{version}/{orgUnitId}/agents creates a new one.

PUT /d2l/api/le/(version)/(orgUnitId)/agents/(agentId)

Update an existing intelligent agent.

Parameters:

  • version (D2LVERSION) – API version.

  • orgUnitId (D2LID) – Org unit ID.

  • agentId (D2LID) – Agent ID.

JSON Parameters:
Oauth2 Scopes:

intelligentagents:agent:update

Status Codes:
API Versions:

  • 1.93+ – Route first appears in LMS v20.26.4.

Return. This action returns an IntelligentAgents.AgentData JSON block for the updated agent.

Agent runs

GET /d2l/api/le/(version)/(orgUnitId)/agents/(agentId)/runs

Retrieve the run history for an intelligent agent.

Parameters:

  • version (D2LVERSION) – API version.

  • orgUnitId (D2LID) – Org unit ID.

  • agentId (D2LID) – Agent ID.

Query Parameters:

  • startDate (UTCDateTime) – Optional. UTC date/time filter — only return runs that started on or after this date.

  • endDate (UTCDateTime) – Optional. UTC date/time filter — only return runs that started on or before this date.

Oauth2 Scopes:

intelligentagents:runs:read

Status Codes:
API Versions:

  • 1.93+ – Route first appears in LMS v20.26.4.

Return. This action returns an ObjectListPage JSON block containing a list of IntelligentAgents.RunData blocks.

GET /d2l/api/le/(version)/(orgUnitId)/agents/(agentId)/runs/(runId)

Retrieve a specific run for an intelligent agent.

Parameters:

  • version (D2LVERSION) – API version.

  • orgUnitId (D2LID) – Org unit ID.

  • agentId (D2LID) – Agent ID.

  • runId (D2LID) – Run ID.

Oauth2 Scopes:

intelligentagents:runs:read

Status Codes:
API Versions:

  • 1.93+ – Route first appears in LMS v20.26.4.

Return. This action returns an IntelligentAgents.RunData JSON block.

POST /d2l/api/le/(version)/(orgUnitId)/agents/(agentId)/runs

Trigger a run for an intelligent agent.

Parameters:

  • version (D2LVERSION) – API version.

  • orgUnitId (D2LID) – Org unit ID.

  • agentId (D2LID) – Agent ID.

JSON Parameters:
Oauth2 Scopes:

intelligentagents:runs:create

Status Codes:
API Versions:

  • 1.93+ – Route first appears in LMS v20.26.4.

Return. This action returns an IntelligentAgents.RunData JSON block for the newly created run.

Categories

DELETE /d2l/api/le/(version)/(orgUnitId)/agents/categories/(categoryId)

Delete an agent category.

Parameters:

  • version (D2LVERSION) – API version.

  • orgUnitId (D2LID) – Org unit ID.

  • categoryId (D2LID) – Category ID.

Oauth2 Scopes:

intelligentagents:category:delete

Status Codes:
API Versions:

  • 1.93+ – Route first appears in LMS v20.26.4.

GET /d2l/api/le/(version)/(orgUnitId)/agents/categories/

Retrieve all agent categories for an org unit.

Parameters:
Oauth2 Scopes:

intelligentagents:category:read

Status Codes:
API Versions:

  • 1.93+ – Route first appears in LMS v20.26.4.

Return. This action returns an ObjectListPage JSON block containing a list of IntelligentAgents.CategoryData blocks.

GET /d2l/api/le/(version)/(orgUnitId)/agents/categories/(categoryId)

Retrieve a specific agent category.

Parameters:

  • version (D2LVERSION) – API version.

  • orgUnitId (D2LID) – Org unit ID.

  • categoryId (D2LID) – Category ID.

Oauth2 Scopes:

intelligentagents:category:read

Status Codes:
API Versions:

  • 1.93+ – Route first appears in LMS v20.26.4.

Return. This action returns an IntelligentAgents.CategoryData JSON block.

POST /d2l/api/le/(version)/(orgUnitId)/agents/categories/

Create a new agent category in the specified org unit.

Parameters:
JSON Parameters:
Oauth2 Scopes:

intelligentagents:category:create

Status Codes:
API Versions:

  • 1.93+ – Route first appears in LMS v20.26.4.

Return. This action returns an IntelligentAgents.CategoryData JSON block for the newly created category.

PUT /d2l/api/le/(version)/(orgUnitId)/agents/categories/(categoryId)

Update an existing agent category.

Parameters:

  • version (D2LVERSION) – API version.

  • orgUnitId (D2LID) – Org unit ID.

  • categoryId (D2LID) – Category ID.

JSON Parameters:
Oauth2 Scopes:

intelligentagents:category:update

Status Codes:
API Versions:

  • 1.93+ – Route first appears in LMS v20.26.4.

Return. This action returns an IntelligentAgents.CategoryData JSON block for the updated category.

«  Surveys   ·  [   home  ·   reference  ·   community   |   search  ·   index   ·  routing table   ·  scopes table   ]   ·  My CPD Records  »