Semestra

Settings

Get the user's personal preferences.

GET
/me/preferences

Use when you need the user's language, clock format (12h/24h) or first day of the week, for example to format a time or date in the way the user expects. Do not use to read per-module settings such as the calendar default view; use settings.value.get.

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.

Response Body

Successful Response

application/json
  1. response
locale*|

Interface language; null follows the browser

theme*Theme

Light, dark, or follow the system

Value in"system""light""dark"
accent*Accent

Accent color of buttons and highlights

Value in"neutral""blue""violet""green""orange""rose""teal""amber"
time_format*Time Format

12-hour or 24-hour clock; auto follows locale

Value in"auto""12h""24h"
week_start*Week Start

First day of the week; 0 follows the language

Value in017
reduce_motion*Reduce Motion

Reduce animations; system follows the OS

Value in"system""on""off"
start_page*Start Page

The page the app opens on

Value in"last""today""overview""calendar""tasks""grades""files""assistant""summary"
keep_course_tab*Keep Course Tab

Switching courses from a course page opens the same tab of the other course

active_program_id*|

The Program currently being viewed

updated_at*|

Null until the first change

Example Request
curl -X GET 'https://example.com/me/preferences'
Example Response
{  "locale": "en",  "theme": "system",  "accent": "neutral",  "time_format": "auto",  "week_start": 0,  "reduce_motion": "system",  "start_page": "last",  "keep_course_tab": true,  "active_program_id": "string",  "updated_at": "2019-08-24T14:15:22Z"}

Change personal preferences (language, theme, accent, clock, week start).

PATCH
/me/preferences

Partial update: only the fields that are sent change. Not for agents.

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.

Request Body

application/json
  1. body
locale?|

Interface language, or null

theme?|

Light, dark, or follow the system

accent?|

Accent color

time_format?|

12-hour or 24-hour clock

week_start?|

First day of the week

reduce_motion?|

Reduce animations

start_page?|

The page the app opens on

keep_course_tab?|

Switching courses keeps the open tab

active_program_id?|

The Program currently being viewed, or null

Response Body

Successful Response

application/json
  1. response
locale*|

Interface language; null follows the browser

theme*Theme

Light, dark, or follow the system

Value in"system""light""dark"
accent*Accent

Accent color of buttons and highlights

Value in"neutral""blue""violet""green""orange""rose""teal""amber"
time_format*Time Format

12-hour or 24-hour clock; auto follows locale

Value in"auto""12h""24h"
week_start*Week Start

First day of the week; 0 follows the language

Value in017
reduce_motion*Reduce Motion

Reduce animations; system follows the OS

Value in"system""on""off"
start_page*Start Page

The page the app opens on

Value in"last""today""overview""calendar""tasks""grades""files""assistant""summary"
keep_course_tab*Keep Course Tab

Switching courses from a course page opens the same tab of the other course

active_program_id*|

The Program currently being viewed

updated_at*|

Null until the first change

Example Request
curl -X PATCH 'https://example.com/me/preferences' \  -H 'Content-Type: application/json' \  -d '{}'
Example Response
{  "locale": "en",  "theme": "system",  "accent": "neutral",  "time_format": "auto",  "week_start": 0,  "reduce_motion": "system",  "start_page": "last",  "keep_course_tab": true,  "active_program_id": "string",  "updated_at": "2019-08-24T14:15:22Z"}

List every settings namespace with its fields.

GET
/me/settings-schemas

Use before changing a module setting to find the namespace, the field names, their allowed values and the levels (account, program, term, course) where they can be set. Do not use to read current values; use settings.value.get.

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.

Response Body

Successful Response

application/json
  1. response
items*array<>
Example Request
curl -X GET 'https://example.com/me/settings-schemas'
Example Response
{  "items": [    {      "namespace": "string",      "levels": [        "account"      ],      "plugin_id": "string",      "agent_writable": true,      "json_schema": {}    }  ]}

Read several UI state entries at once.

POST
/me/ui-state:get

Reads interface state (sort orders, collapsed panels) by key or key prefix. Not available to agents.

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.

Request Body

application/json
  1. body
keys?array<>

Exact keys to read

Itemsitems <= 200
prefixes?array<>

Read every key that starts with one of these, e.g. 'layout.'

Itemsitems <= 20

Response Body

Successful Response

application/json
  1. response
items*

Existing keys and their values

Example Request
curl -X POST 'https://example.com/me/ui-state:get' \  -H 'Content-Type: application/json' \  -d '{}'
Example Response
{  "items": {    "property1": null,    "property2": null  }}

Save one UI state entry.

PUT
/me/ui-state/{key}

Stores interface state under a key. Not available to agents.

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

key*Key

'.[.]', at most 128 characters

Request Body

application/json
  1. body
value*JsonValue

Any JSON value up to 16 KB

Response Body

Successful Response

application/json
  1. response
key*Key
value*JsonValue
Example Request
curl -X PUT 'https://example.com/me/ui-state/string' \  -H 'Content-Type: application/json' \  -d '{  "value": null}'
Example Response
{  "key": "string",  "value": null}

Get the effective settings of a module or plugin at a scope.

GET
/me/settings/{namespace}

Use when the user asks how a module is configured, e.g. the default calendar view. Returns the effective value of every field and the level it is inherited from (default, account, program, term or course). Do not use for personal preferences such as language or theme; use settings.preference.get.

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

namespace*Namespace

Settings namespace, e.g. 'calendar' or 'plugin.pomodoro'

Query Parameters

scope_type?Scope Type

Scope level to resolve for

Default"account"
Value in"account""program""term""course"
scope_id?|

Id of the scope; omit for 'account'

Response Body

Successful Response

application/json
  1. response
namespace*Namespace
scope_type*Scope Type
Value in"account""program""term""course"
scope_id*string|null
values*

Effective value of every field

sources*

Where each effective value comes from

inherited*

What every field resolves to from the levels above, ignoring this level's own values: what 'follow' shows and what a reset brings back

Example Request
curl -X GET 'https://example.com/me/settings/string'
Example Response
{  "namespace": "string",  "scope_type": "account",  "scope_id": "string",  "values": {},  "sources": {    "property1": "default",    "property2": "default"  },  "inherited": {    "property1": {      "value": null,      "source": "default"    },    "property2": {      "value": null,      "source": "default"    }  }}

Change settings of a module or plugin at one scope level.

PATCH
/me/settings/{namespace}

Use when the user wants to change a module setting, e.g. make the calendar open in month view. Only the given fields are set at that level; deeper levels still override them. Look up namespace and field names with settings.schema.list first. Namespaces whose schema says agent_writable false can only be changed by the user in the settings page: tell the user where to find it instead. Do not use to change language, theme or other personal preferences.

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

namespace*Namespace

Settings namespace

Request Body

application/json
  1. body
scope_type?Scope Type

Level to write the values at

Default"account"
Value in"account""program""term""course"
scope_id?|

Id of the scope; omit for 'account'

values*

Fields to set at this level; other levels are not touched

Properties1 <= properties

Response Body

Successful Response

application/json
  1. response
namespace*Namespace
scope_type*Scope Type
Value in"account""program""term""course"
scope_id*string|null
values*

Effective value of every field

sources*

Where each effective value comes from

inherited*

What every field resolves to from the levels above, ignoring this level's own values: what 'follow' shows and what a reset brings back

Example Request
curl -X PATCH 'https://example.com/me/settings/string' \  -H 'Content-Type: application/json' \  -d '{  "values": {    "property1": null,    "property2": null  }}'
Example Response
{  "namespace": "string",  "scope_type": "account",  "scope_id": "string",  "values": {},  "sources": {    "property1": "default",    "property2": "default"  },  "inherited": {    "property1": {      "value": null,      "source": "default"    },    "property2": {      "value": null,      "source": "default"    }  }}

Remove one setting at a scope level so it is inherited again.

DELETE
/me/settings/{namespace}/keys/{key}

Restores a field to the value of the level above (or the default). Not available to agents.

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

namespace*Namespace

Settings namespace

key*Key

Field to restore to the value inherited from the level above

Query Parameters

scope_type?Scope Type

Level to remove the value from

Default"account"
Value in"account""program""term""course"
scope_id?|

Id of the scope; omit for 'account'

Response Body

Successful Response

application/json
  1. response
namespace*Namespace
scope_type*Scope Type
Value in"account""program""term""course"
scope_id*string|null
values*

Effective value of every field

sources*

Where each effective value comes from

inherited*

What every field resolves to from the levels above, ignoring this level's own values: what 'follow' shows and what a reset brings back

Example Request
curl -X DELETE 'https://example.com/me/settings/string/keys/string'
Example Response
{  "namespace": "string",  "scope_type": "account",  "scope_id": "string",  "values": {},  "sources": {    "property1": "default",    "property2": "default"  },  "inherited": {    "property1": {      "value": null,      "source": "default"    },    "property2": {      "value": null,      "source": "default"    }  }}