Tasks
Tasks let you schedule messages to be sent later. Each task belongs to a thread and defines a schedule in the JSCalendar format.
You can create recurring tasks to automate prompts and proactively reach out to your users. Example use cases include:
"Can you give me a briefing on AI news each afternoon?"
"Practice French with me daily"
"Remind me about my mom’s birthday"
Endpoints
Manage your tasks with these REST endpoints.
List tasksRetrieve a list of tasks
Create taskCreate a new task
Get taskRetrieve a specific task
Update taskUpdate an existing task
Delete taskDelete an existing task
Task type
Schedule format
schedule follows the JSCalendar event schema. Provide at minimum a start timestamp in ISO 8601 format. If you specify a timeZone, omit the trailing Z from the start value so it is interpreted in that zone. When no timeZone is given, start must include a UTC offset (for example Z for UTC). Use recurrenceRules to repeat events.Example daily schedule:
{
"start": "2025-07-01T09:00:00Z",
"recurrenceRules": [
{ "frequency": "daily" }
]
}
Example weekly schedule in a specific time zone:
{
"start": "2025-07-01T09:00:00",
"timeZone": "America/New_York",
"recurrenceRules": [
{ "frequency": "weekly", "byDay": ["tu"] }
]
}
Example task
const task = {
id: '70cfe680-fee5-49b9-b386-6a7097eb8497',
title: 'Send reminder',
message: 'Check in with the user',
schedule: {
start: '2025-07-01T09:00:00',
timeZone: 'America/New_York',
recurrenceRules: [
{ frequency: 'daily' }
]
},
threadId: '60cfe680-fee5-49b9-b386-6a7097eb8497',
key: '',
createdAt: '2025-07-01T09:00:00Z',
updatedAt: '2025-07-01T09:00:00Z',
}
Key templates
key scopes tasks to a pool. All assistants in the workspace can access tasks with the same key. Leave it blank to share tasks globally.When using the tasks tool you may define a key template. Key templates support
{{variable}} placeholders from thread metadata and each unique template creates its own task pool. The key field stores the resolved value when the task is created.