Semestra

Tasks

Delete the completed tasks of a Program, optionally of one list, term or course.

POST
/programs/{program_id}/tasks:clear-completed

Irreversible; returns how many were deleted. Use only when the user asks to clear or clean up completed tasks.

Authorization

cookiesemestra_session<token>

Set by the sign-in endpoints for the web app. Requests other than GET, HEAD and OPTIONS also need the X-Semestra-CSRF header set to the semestra_csrf cookie.

Path Parameters

program_id*Program Id

Program id

Request Body

application/json
  1. body
list_id?|

Only completed tasks of this list

term_id?|

Only completed tasks of this term

course_id?|

Only completed tasks of this course

Response Body

Successful Response

application/json
  1. response
deleted*Deleted
Example Request
curl -X POST 'https://example.com/programs/string/tasks:clear-completed' \  -H 'Content-Type: application/json' \  -d '{}'
Example Response
{  "deleted": 0}

Mark a task done, or reopen it with completed=false.

POST
/tasks/{task_id}:complete

Completing a task never changes grades, even if it came from an assessment.

Authorization

cookiesemestra_session<token>

Set by the sign-in endpoints for the web app. Requests other than GET, HEAD and OPTIONS also need the X-Semestra-CSRF header set to the semestra_csrf cookie.

Path Parameters

task_id*Task Id

Task id

Request Body

application/json
  1. body
completed?Completed

False reopens the task

Defaulttrue

Response Body

Successful Response

application/json
  1. response
id*Id
program_id*Program Id
term_id*string|null
course_id*string|null
list_id*|

Null for the Program's inbox

title*Title
notes*Notes
due_date*|null
due_time*|

Wall-clock time in the Program's time zone

priority*Priority
Value in"none""low""medium""high""urgent"
flagged*Flagged
completed_at*|null
overdue*Overdue

Unfinished and past its due moment (Program time zone)

position*Position
source_kind*|null
source_ref*string|null
assessment_id*|

The gradebook assessment this task stands for: its title, due date and course follow the assessment, and it is deleted with it

created_at*Created At
Formatdate-time
updated_at*Updated At
Formatdate-time
Example Request
curl -X POST 'https://example.com/tasks/string:complete' \  -H 'Content-Type: application/json' \  -d '{}'
Example Response
{  "id": "string",  "program_id": "string",  "term_id": "string",  "course_id": "string",  "list_id": "string",  "title": "string",  "notes": "string",  "due_date": "2019-08-24",  "due_time": "14:15:22Z",  "priority": "none",  "flagged": true,  "completed_at": "2019-08-24T14:15:22Z",  "overdue": true,  "position": 0,  "source_kind": "lms",  "source_ref": "string",  "assessment_id": "string",  "created_at": "2019-08-24T14:15:22Z",  "updated_at": "2019-08-24T14:15:22Z"}

Counts of unfinished tasks per smart list, list and course (sidebar badges).

GET
/programs/{program_id}/task-counts

Cheap overview: today, overdue, scheduled, all, inbox, flagged and completed.

Authorization

cookiesemestra_session<token>

Set by the sign-in endpoints for the web app. Requests other than GET, HEAD and OPTIONS also need the X-Semestra-CSRF header set to the semestra_csrf cookie.

Path Parameters

program_id*Program Id

Program id

Query Parameters

term_id?|

Only this term's tasks and those that belong to no term

course_id?|

Only this course's tasks

Response Body

Successful Response

application/json
  1. response
today*Today

Unfinished tasks due today or overdue

overdue*Overdue
scheduled*Scheduled
all*All
inbox*Inbox
flagged*Flagged
completed*Completed
lists*

Unfinished tasks per list id

courses*

Unfinished tasks per course id

Example Request
curl -X GET 'https://example.com/programs/string/task-counts'
Example Response
{  "today": 0,  "overdue": 0,  "scheduled": 0,  "all": 0,  "inbox": 0,  "flagged": 0,  "completed": 0,  "lists": {    "property1": 0,    "property2": 0  },  "courses": {    "property1": 0,    "property2": 0  }}

List a Program's tasks by view: today, scheduled, all, completed, inbox, flagged.

GET
/programs/{program_id}/tasks

Use for 'what do I have to do'. today includes overdue tasks. For questions about what is due this week prefer calendar.occurrence.list, which merges tasks with assessment deadlines and classes. Filter with list_id, term_id, course_id, search and due_from/due_to; completed tasks are hidden unless the view is completed or completed is include or only.

Authorization

cookiesemestra_session<token>

Set by the sign-in endpoints for the web app. Requests other than GET, HEAD and OPTIONS also need the X-Semestra-CSRF header set to the semestra_csrf cookie.

Path Parameters

program_id*Program Id

Program id

Query Parameters

view?View

today = due today or overdue; scheduled = has a due date; all; completed; inbox = no list; flagged

Default"all"
Value in"today""scheduled""all""completed""inbox""flagged"
list_id?|

Only this list

term_id?|

Only this term's tasks and those that belong to no term

course_id?|

Only this course

search?|

Fuzzy match on title and notes

due_from?|

Due on or after this date

due_to?|

Due on or before this date

completed?Completed

Completed tasks the view would show: leave out, add, or return only them (ignored by the completed view)

Default"exclude"
Value in"exclude""include""only"
sort?Sort

Order of the result

Default"manual"
Value in"manual""due""priority""created""title"
fields?array<>|

Agent/MCP only: return just these fields of each task (and its id)

cursor?|

next_cursor of the previous page

limit?Limit

Page size

Default200

Response Body

Successful Response

application/json
  1. response
items*array<>
next_cursor*string|null
total*Total

How many tasks match, over all pages

Example Request
curl -X GET 'https://example.com/programs/string/tasks'
Example Response
{  "items": [    {      "id": "string",      "program_id": "string",      "term_id": "string",      "course_id": "string",      "list_id": "string",      "title": "string",      "notes": "string",      "due_date": "2019-08-24",      "due_time": "14:15:22Z",      "priority": "none",      "flagged": true,      "completed_at": "2019-08-24T14:15:22Z",      "overdue": true,      "position": 0,      "source_kind": "lms",      "source_ref": "string",      "assessment_id": "string",      "created_at": "2019-08-24T14:15:22Z",      "updated_at": "2019-08-24T14:15:22Z"    }  ],  "next_cursor": "string",  "total": 0}

Create a task (a to-do or reminder), optionally with a due date, course and list.

POST
/programs/{program_id}/tasks

Always pass the course and due date when the user's words or the current scope give them. Dates are in the Program's time zone; a time needs a date. The term is inferred from the course and due date. Omit list_id to put the task in the inbox. Use tasks.item.create_many for several tasks.

Authorization

cookiesemestra_session<token>

Set by the sign-in endpoints for the web app. Requests other than GET, HEAD and OPTIONS also need the X-Semestra-CSRF header set to the semestra_csrf cookie.

Path Parameters

program_id*Program Id

Program id

Request Body

application/json
  1. body
title*Title

What to do

Length1 <= length <= 300
notes?Notes

Notes

Lengthlength <= 20000
Default""
due_date?|

Due date (Program time zone)

due_time?|

Due time of day; needs a due date. Seconds are dropped.

priority?|

Priority; omit for the Program's default

flagged?Flagged

Flag the task

Defaultfalse
term_id?|

Term; inferred from the course and due date when omitted

course_id?|

Course the task is for

list_id?|

List; omit for the inbox

source_kind?Source Kind

Where the task came from. The assistant may only use agent (its default), syllabus or manual; lms tasks are made by the app itself

Default"manual"
Value in"lms""syllabus""agent""manual"
source_ref?|

Id of the source item; makes batch imports idempotent

Response Body

Successful Response

application/json
  1. response
id*Id
program_id*Program Id
term_id*string|null
course_id*string|null
list_id*|

Null for the Program's inbox

title*Title
notes*Notes
due_date*|null
due_time*|

Wall-clock time in the Program's time zone

priority*Priority
Value in"none""low""medium""high""urgent"
flagged*Flagged
completed_at*|null
overdue*Overdue

Unfinished and past its due moment (Program time zone)

position*Position
source_kind*|null
source_ref*string|null
assessment_id*|

The gradebook assessment this task stands for: its title, due date and course follow the assessment, and it is deleted with it

created_at*Created At
Formatdate-time
updated_at*Updated At
Formatdate-time
Example Request
curl -X POST 'https://example.com/programs/string/tasks' \  -H 'Content-Type: application/json' \  -d '{  "title": "string"}'
Example Response
{  "id": "string",  "program_id": "string",  "term_id": "string",  "course_id": "string",  "list_id": "string",  "title": "string",  "notes": "string",  "due_date": "2019-08-24",  "due_time": "14:15:22Z",  "priority": "none",  "flagged": true,  "completed_at": "2019-08-24T14:15:22Z",  "overdue": true,  "position": 0,  "source_kind": "lms",  "source_ref": "string",  "assessment_id": "string",  "created_at": "2019-08-24T14:15:22Z",  "updated_at": "2019-08-24T14:15:22Z"}

Create several tasks at once; items with an already known source are skipped.

POST
/programs/{program_id}/tasks:batch

Use for a list of tasks the user dictates or pastes; tasks in a document go through imports.session.create. Items whose source_kind and source_ref match an existing task are skipped and returned with that task's id, so repeating an import does not duplicate them.

Authorization

cookiesemestra_session<token>

Set by the sign-in endpoints for the web app. Requests other than GET, HEAD and OPTIONS also need the X-Semestra-CSRF header set to the semestra_csrf cookie.

Path Parameters

program_id*Program Id

Program id

Request Body

application/json
  1. body
items*array<>

Tasks to create

Items1 <= items <= 200

Response Body

Successful Response

application/json
  1. response
created*array<>
skipped*array<>
Example Request
curl -X POST 'https://example.com/programs/string/tasks:batch' \  -H 'Content-Type: application/json' \  -d '{  "items": [    {      "title": "string"    }  ]}'
Example Response
{  "created": [    {      "id": "string",      "program_id": "string",      "term_id": "string",      "course_id": "string",      "list_id": "string",      "title": "string",      "notes": "string",      "due_date": "2019-08-24",      "due_time": "14:15:22Z",      "priority": "none",      "flagged": true,      "completed_at": "2019-08-24T14:15:22Z",      "overdue": true,      "position": 0,      "source_kind": "lms",      "source_ref": "string",      "assessment_id": "string",      "created_at": "2019-08-24T14:15:22Z",      "updated_at": "2019-08-24T14:15:22Z"    }  ],  "skipped": [    {      "index": 0,      "task_id": "string"    }  ]}

Get one task with its notes, due date, priority and source.

GET
/tasks/{task_id}

Use when you need the full details of a task you already know the id of.

Authorization

cookiesemestra_session<token>

Set by the sign-in endpoints for the web app. Requests other than GET, HEAD and OPTIONS also need the X-Semestra-CSRF header set to the semestra_csrf cookie.

Path Parameters

task_id*Task Id

Task id

Response Body

Successful Response

application/json
  1. response
id*Id
program_id*Program Id
term_id*string|null
course_id*string|null
list_id*|

Null for the Program's inbox

title*Title
notes*Notes
due_date*|null
due_time*|

Wall-clock time in the Program's time zone

priority*Priority
Value in"none""low""medium""high""urgent"
flagged*Flagged
completed_at*|null
overdue*Overdue

Unfinished and past its due moment (Program time zone)

position*Position
source_kind*|null
source_ref*string|null
assessment_id*|

The gradebook assessment this task stands for: its title, due date and course follow the assessment, and it is deleted with it

created_at*Created At
Formatdate-time
updated_at*Updated At
Formatdate-time
Example Request
curl -X GET 'https://example.com/tasks/string'
Example Response
{  "id": "string",  "program_id": "string",  "term_id": "string",  "course_id": "string",  "list_id": "string",  "title": "string",  "notes": "string",  "due_date": "2019-08-24",  "due_time": "14:15:22Z",  "priority": "none",  "flagged": true,  "completed_at": "2019-08-24T14:15:22Z",  "overdue": true,  "position": 0,  "source_kind": "lms",  "source_ref": "string",  "assessment_id": "string",  "created_at": "2019-08-24T14:15:22Z",  "updated_at": "2019-08-24T14:15:22Z"}

Change a task's title, notes, due date and time, priority, flag, list or course.

PATCH
/tasks/{task_id}

Partial update: only the fields that are sent change; null clears the nullable ones (due_date, due_time, course_id, list_id, term_id). Use tasks.item.complete to finish a task and tasks.item.move to reorder it. A task with source_kind assessment takes its title, due date and course from the assessment: changing those is refused (tasks.managed_by_assessment); change the assessment instead.

Authorization

cookiesemestra_session<token>

Set by the sign-in endpoints for the web app. Requests other than GET, HEAD and OPTIONS also need the X-Semestra-CSRF header set to the semestra_csrf cookie.

Path Parameters

task_id*Task Id

Task id

Request Body

application/json
  1. body
title?|

Title

notes?|

Notes

due_date?|

Due date; null clears date and time

due_time?|

Due time; null clears it

priority?|

Priority

flagged?|

Flag

term_id?|

Term; null clears it

course_id?|

Course; null clears it

list_id?|

List; null moves to the inbox

Response Body

Successful Response

application/json
  1. response
id*Id
program_id*Program Id
term_id*string|null
course_id*string|null
list_id*|

Null for the Program's inbox

title*Title
notes*Notes
due_date*|null
due_time*|

Wall-clock time in the Program's time zone

priority*Priority
Value in"none""low""medium""high""urgent"
flagged*Flagged
completed_at*|null
overdue*Overdue

Unfinished and past its due moment (Program time zone)

position*Position
source_kind*|null
source_ref*string|null
assessment_id*|

The gradebook assessment this task stands for: its title, due date and course follow the assessment, and it is deleted with it

created_at*Created At
Formatdate-time
updated_at*Updated At
Formatdate-time
Example Request
curl -X PATCH 'https://example.com/tasks/string' \  -H 'Content-Type: application/json' \  -d '{}'
Example Response
{  "id": "string",  "program_id": "string",  "term_id": "string",  "course_id": "string",  "list_id": "string",  "title": "string",  "notes": "string",  "due_date": "2019-08-24",  "due_time": "14:15:22Z",  "priority": "none",  "flagged": true,  "completed_at": "2019-08-24T14:15:22Z",  "overdue": true,  "position": 0,  "source_kind": "lms",  "source_ref": "string",  "assessment_id": "string",  "created_at": "2019-08-24T14:15:22Z",  "updated_at": "2019-08-24T14:15:22Z"}

Delete a task for good.

DELETE
/tasks/{task_id}

Irreversible. To finish a task use tasks.item.complete instead; delete only when the user asks to remove it. A task made from an assessment comes back when the assessment changes.

Authorization

cookiesemestra_session<token>

Set by the sign-in endpoints for the web app. Requests other than GET, HEAD and OPTIONS also need the X-Semestra-CSRF header set to the semestra_csrf cookie.

Path Parameters

task_id*Task Id

Task id

Response Body

Successful Response

application/json
  1. response
ok?Ok
Defaulttrue
Example Request
curl -X DELETE 'https://example.com/tasks/string'
Example Response
{  "ok": true}

Move a task to another list (or the inbox) and/or to a place within the list.

POST
/tasks/{task_id}:move

Send list_id (null = inbox) to change list; leave it out to reorder inside the current one. before_task_id places the task right before that task, otherwise it goes last.

Authorization

cookiesemestra_session<token>

Set by the sign-in endpoints for the web app. Requests other than GET, HEAD and OPTIONS also need the X-Semestra-CSRF header set to the semestra_csrf cookie.

Path Parameters

task_id*Task Id

Task id

Request Body

application/json
  1. body
list_id?|

Target list (null = inbox); if not sent the list is unchanged

before_task_id?|

Place the task before this one (same target list; from tasks.item.query); else last

Response Body

Successful Response

application/json
  1. response
id*Id
program_id*Program Id
term_id*string|null
course_id*string|null
list_id*|

Null for the Program's inbox

title*Title
notes*Notes
due_date*|null
due_time*|

Wall-clock time in the Program's time zone

priority*Priority
Value in"none""low""medium""high""urgent"
flagged*Flagged
completed_at*|null
overdue*Overdue

Unfinished and past its due moment (Program time zone)

position*Position
source_kind*|null
source_ref*string|null
assessment_id*|

The gradebook assessment this task stands for: its title, due date and course follow the assessment, and it is deleted with it

created_at*Created At
Formatdate-time
updated_at*Updated At
Formatdate-time
Example Request
curl -X POST 'https://example.com/tasks/string:move' \  -H 'Content-Type: application/json' \  -d '{}'
Example Response
{  "id": "string",  "program_id": "string",  "term_id": "string",  "course_id": "string",  "list_id": "string",  "title": "string",  "notes": "string",  "due_date": "2019-08-24",  "due_time": "14:15:22Z",  "priority": "none",  "flagged": true,  "completed_at": "2019-08-24T14:15:22Z",  "overdue": true,  "position": 0,  "source_kind": "lms",  "source_ref": "string",  "assessment_id": "string",  "created_at": "2019-08-24T14:15:22Z",  "updated_at": "2019-08-24T14:15:22Z"}

List the task lists of a Program (term lists and Program-wide lists).

GET
/programs/{program_id}/task-lists

Use to find a list id before creating or moving tasks. Tasks without a list are in the inbox, which is not a list row.

Authorization

cookiesemestra_session<token>

Set by the sign-in endpoints for the web app. Requests other than GET, HEAD and OPTIONS also need the X-Semestra-CSRF header set to the semestra_csrf cookie.

Path Parameters

program_id*Program Id

Program id

Response Body

Successful Response

application/json
  1. response
items*array<>
Example Request
curl -X GET 'https://example.com/programs/string/task-lists'
Example Response
{  "items": [    {      "id": "string",      "program_id": "string",      "term_id": "string",      "name": "string",      "color": "string",      "icon": "string",      "position": 0,      "created_at": "2019-08-24T14:15:22Z",      "updated_at": "2019-08-24T14:15:22Z"    }  ]}

Create a task list, for one term or for the whole Program.

POST
/programs/{program_id}/task-lists

Use when the user wants a named list such as 'Errands'. Names are unique within a term (or within the Program-wide lists). Do not create a list just to file one task: leave tasks in the inbox unless the user names a list.

Authorization

cookiesemestra_session<token>

Set by the sign-in endpoints for the web app. Requests other than GET, HEAD and OPTIONS also need the X-Semestra-CSRF header set to the semestra_csrf cookie.

Path Parameters

program_id*Program Id

Program id

Request Body

application/json
  1. body
name*Name

List name, unique within its term (or Program-wide)

Length1 <= length <= 100
term_id?|

Term the list belongs to; omit for a Program-wide list

color?|

Color

icon?|

Icon

Response Body

Successful Response

application/json
  1. response
id*Id
program_id*Program Id
term_id*|

Null for a list shared by every term of the Program

name*Name
color*string|null
icon*string|null
position*Position
created_at*Created At
Formatdate-time
updated_at*Updated At
Formatdate-time
Example Request
curl -X POST 'https://example.com/programs/string/task-lists' \  -H 'Content-Type: application/json' \  -d '{  "name": "string"}'
Example Response
{  "id": "string",  "program_id": "string",  "term_id": "string",  "name": "string",  "color": "string",  "icon": "string",  "position": 0,  "created_at": "2019-08-24T14:15:22Z",  "updated_at": "2019-08-24T14:15:22Z"}

Rename a task list or change its color or icon.

PATCH
/task-lists/{list_id}

Partial update: only the fields that are sent change. Get the id from tasks.list.list. Tasks are moved between lists with tasks.item.move.

Authorization

cookiesemestra_session<token>

Set by the sign-in endpoints for the web app. Requests other than GET, HEAD and OPTIONS also need the X-Semestra-CSRF header set to the semestra_csrf cookie.

Path Parameters

list_id*List Id

List id

Request Body

application/json
  1. body
name?|

New name

color?|

Color

icon?|

Icon

Response Body

Successful Response

application/json
  1. response
id*Id
program_id*Program Id
term_id*|

Null for a list shared by every term of the Program

name*Name
color*string|null
icon*string|null
position*Position
created_at*Created At
Formatdate-time
updated_at*Updated At
Formatdate-time
Example Request
curl -X PATCH 'https://example.com/task-lists/string' \  -H 'Content-Type: application/json' \  -d '{}'
Example Response
{  "id": "string",  "program_id": "string",  "term_id": "string",  "name": "string",  "color": "string",  "icon": "string",  "position": 0,  "created_at": "2019-08-24T14:15:22Z",  "updated_at": "2019-08-24T14:15:22Z"}

Delete a task list; its tasks move to the inbox unless told otherwise.

DELETE
/task-lists/{list_id}

With delete_tasks true the list's tasks are deleted for good, so only use it when the user asked for that. By default the tasks are kept in the inbox.

Authorization

cookiesemestra_session<token>

Set by the sign-in endpoints for the web app. Requests other than GET, HEAD and OPTIONS also need the X-Semestra-CSRF header set to the semestra_csrf cookie.

Path Parameters

list_id*List Id

List id

Query Parameters

delete_tasks?Delete Tasks

Delete the list's tasks too; by default they move to the inbox

Defaultfalse

Response Body

Successful Response

application/json
  1. response
deleted_task_count*Deleted Task Count
moved_task_count*Moved Task Count
Example Request
curl -X DELETE 'https://example.com/task-lists/string'
Example Response
{  "deleted_task_count": 0,  "moved_task_count": 0}

Set the display order of a Program's task lists.

PUT
/programs/{program_id}/task-list-order

Lists not named keep their relative order after the named ones.

Authorization

cookiesemestra_session<token>

Set by the sign-in endpoints for the web app. Requests other than GET, HEAD and OPTIONS also need the X-Semestra-CSRF header set to the semestra_csrf cookie.

Path Parameters

program_id*Program Id

Program id

Request Body

application/json
  1. body
list_ids*array<>

List ids in the new display order (lists not named go last)

Itemsitems <= 200

Response Body

Successful Response

application/json
  1. response
items*array<>
Example Request
curl -X PUT 'https://example.com/programs/string/task-list-order' \  -H 'Content-Type: application/json' \  -d '{  "list_ids": [    "string"  ]}'
Example Response
{  "items": [    {      "id": "string",      "program_id": "string",      "term_id": "string",      "name": "string",      "color": "string",      "icon": "string",      "position": 0,      "created_at": "2019-08-24T14:15:22Z",      "updated_at": "2019-08-24T14:15:22Z"    }  ]}