Ai Tasks

An AI Task defines a Files.com AI prompt that can run on a schedule or in response to file actions.

List Ai Tasks

SDK Method

Files::AiTask.list

Return Object

List<AiTask>

Authorization Requirement

Requires either a Site-Wide API key or User API key or session from a User with Site Admin permissions.

Additional Arguments

Example Request

begin
  ai_tasks = Files::AiTask.list
  ai_tasks.auto_paging_each do |ai_task|
    # Operate on ai_task
  end
rescue Files::NotAuthenticatedError => e
  puts "Authentication Error Occurred (#{e.class.to_s}): " + e.message
rescue Files::Error => e
  puts "Unknown Error Occurred (#{e.class.to_s}): " + e.message
end

Show Ai Task

SDK Method

Files::AiTask.find

Return Object

AiTask

Authorization Requirement

Requires either a Site-Wide API key or User API key or session from a User with Site Admin permissions.

Method Arguments

ArgumentDescription
id
int64
Required		Ai Task ID.

Example Request

begin
  ai_task = Files::AiTask.find(id)
  # Operate on ai_task
rescue Files::NotAuthenticatedError => e
  puts "Authentication Error Occurred (#{e.class.to_s}): " + e.message
rescue Files::Error => e
  puts "Unknown Error Occurred (#{e.class.to_s}): " + e.message
end

Create Ai Task

SDK Method

Files::AiTask.create

Return Object

AiTask

Authorization Requirement

Requires either a Site-Wide API key or User API key or session from a User with Site Admin permissions.

Method Arguments

ArgumentDefaultDescription
description
string		AI Task description.
disabled
boolean		falseIf true, this AI Task will not run.
holiday_region
string		Optional holiday region used by the AI Task schedule.
interval
string		If trigger is daily, this specifies how often to run the AI Task.
name
string
Required		AI Task name.
path
string		""Path scope used for action-triggered AI Tasks.
permission_set
string		"full"Permissions used by the internal API key for this AI Task. Valid values are full and files_only.
Possible values: full, files_only
prompt
string
Required		Prompt sent when this AI Task is invoked.
recurring_day
int64		If trigger is daily, this selects the day number inside the chosen interval.
recurring_days
array(int64)		If trigger is daily, this selects one or more day numbers inside a week, month, quarter, or year interval.
schedule_id
int64		If trigger is custom_schedule, the reusable Schedule used instead of the AI Task's schedule fields.
schedule_days_of_week
array(int64)		If trigger is custom_schedule, the 0-based weekdays used by the schedule.
schedule_time_zone
string		Time zone used by the AI Task schedule.
schedule_times_of_day
array(string)		Times of day in HH:MM format for the AI Task schedule.
source
string		"*"Source glob used with path for action-triggered AI Tasks.
trigger
string		"manual"How this AI Task is triggered.
Possible values: manual, daily, custom_schedule, action
trigger_actions
array(string)		If trigger is action, the file action types that invoke this AI Task. Valid actions are create, copy, move, archived_delete, update, read, destroy.
workspace_id
int64		0Workspace ID. 0 means the default workspace.

Example Request

begin
  ai_task = Files::AiTask.create(
    name: "Summarize daily reports",
    prompt: "Summarize the uploaded file and identify follow-up actions."
  )
  # Operate on ai_task
rescue Files::NotAuthenticatedError => e
  puts "Authentication Error Occurred (#{e.class.to_s}): " + e.message
rescue Files::Error => e
  puts "Unknown Error Occurred (#{e.class.to_s}): " + e.message
end

Manually Run AI Task

SDK Method

ai_task.manual_run

Return Object

nil

Authorization Requirement

Requires either a Site-Wide API key or User API key or session from a User with Site Admin permissions.

Example Request

begin
  # Find the ai_task object by its id.
  ai_task = Files::AiTask.find(id)
  ai_task.manual_run
rescue Files::NotAuthenticatedError => e
  puts "Authentication Error Occurred (#{e.class.to_s}): " + e.message
rescue Files::Error => e
  puts "Unknown Error Occurred (#{e.class.to_s}): " + e.message
end

Update Ai Task

SDK Method

ai_task.update

Return Object

AiTask

Authorization Requirement

Requires either a Site-Wide API key or User API key or session from a User with Site Admin permissions.

Method Arguments

ArgumentDescription
description
string		AI Task description.
disabled
boolean		If true, this AI Task will not run.
holiday_region
string		Optional holiday region used by the AI Task schedule.
interval
string		If trigger is daily, this specifies how often to run the AI Task.
name
string		AI Task name.
path
string		Path scope used for action-triggered AI Tasks.
permission_set
string		Permissions used by the internal API key for this AI Task. Valid values are full and files_only.
Possible values: full, files_only
prompt
string		Prompt sent when this AI Task is invoked.
recurring_day
int64		If trigger is daily, this selects the day number inside the chosen interval.
recurring_days
array(int64)		If trigger is daily, this selects one or more day numbers inside a week, month, quarter, or year interval.
schedule_id
int64		If trigger is custom_schedule, the reusable Schedule used instead of the AI Task's schedule fields.
schedule_days_of_week
array(int64)		If trigger is custom_schedule, the 0-based weekdays used by the schedule.
schedule_time_zone
string		Time zone used by the AI Task schedule.
schedule_times_of_day
array(string)		Times of day in HH:MM format for the AI Task schedule.
source
string		Source glob used with path for action-triggered AI Tasks.
trigger
string		How this AI Task is triggered.
Possible values: manual, daily, custom_schedule, action
trigger_actions
array(string)		If trigger is action, the file action types that invoke this AI Task. Valid actions are create, copy, move, archived_delete, update, read, destroy.
workspace_id
int64		Workspace ID. 0 means the default workspace.

Example Request

begin
  # Find the ai_task object by its id.
  ai_task = Files::AiTask.find(id)
  ai_task.update(
    description: "Summarizes files uploaded by the accounting team."
  )
rescue Files::NotAuthenticatedError => e
  puts "Authentication Error Occurred (#{e.class.to_s}): " + e.message
rescue Files::Error => e
  puts "Unknown Error Occurred (#{e.class.to_s}): " + e.message
end

Delete Ai Task

SDK Method

ai_task.delete

Return Object

nil

Authorization Requirement

Requires either a Site-Wide API key or User API key or session from a User with Site Admin permissions.

Example Request

begin
  # Find the ai_task object by its id.
  ai_task = Files::AiTask.find(id)
  ai_task.delete
rescue Files::NotAuthenticatedError => e
  puts "Authentication Error Occurred (#{e.class.to_s}): " + e.message
rescue Files::Error => e
  puts "Unknown Error Occurred (#{e.class.to_s}): " + e.message
end

The AiTask Object

Some of the methods above return a AiTask object. The attributes of this object are listed below.

AttributeDescription
id
int64		AI Task ID.
workspace_id
int64		Workspace ID. 0 means the default workspace.
name
string		AI Task name.
description
string		AI Task description.
prompt
string		Prompt sent when this AI Task is invoked.
permission_set
string		Permissions used by the internal API key for this AI Task. Valid values are full and files_only.
Possible values: full, files_only
path
string		Path scope used for action-triggered AI Tasks. This must be slash-delimited, but it must neither start nor end with a slash. Maximum of 5000 characters.
source
string		Source glob used with path for action-triggered AI Tasks.
disabled
boolean		If true, this AI Task will not run.
trigger
string		How this AI Task is triggered.
Possible values: manual, daily, custom_schedule, action
trigger_actions
array(string)		If trigger is action, the file action types that invoke this AI Task. Valid actions are create, copy, move, archived_delete, update, read, destroy.
interval
string		If trigger is daily, this specifies how often to run the AI Task.
recurring_day
int64		If trigger is daily, this selects the day number inside the chosen interval.
recurring_days
array(int64)		If trigger is daily, this selects one or more day numbers inside a week, month, quarter, or year interval.
schedule_id
int64		If trigger is custom_schedule, the reusable Schedule used instead of the AI Task's schedule fields.
schedule_days_of_week
array(int64)		If trigger is custom_schedule, the 0-based weekdays used by the schedule.
schedule_times_of_day
array(string)		Times of day in HH:MM format for the AI Task schedule.
schedule_time_zone
string		Time zone used by the AI Task schedule.
holiday_region
string		Optional holiday region used by the AI Task schedule.
human_readable_schedule
string		Human-readable schedule description.
last_run_at
date-time		Most recent successful invocation time.
master_admin_user_id
int64		Master User ID used for AI Task invocations.
created_at
date-time		Creation time.
updated_at
date-time		Last update time.