Account and API tokens

Upload a profile picture (PNG, JPEG or WebP, up to 5 MB).

POST

/account/avatar

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

multipart/form-data

body

file*File

Response Body

Successful Response

application/json

response

id*Id

email*Email

display_name*Display Name

avatar_url*string|null

locale*string|null

has_password*Has Password

identities*array<>

created_at*Created At

Formatdate-time

Example Request

curl -X POST 'https://example.com/account/avatar' \
  -F 'file=string'

Example Request

curl -X POST 'https://example.com/account/avatar' \  -F 'file=string'

Example ResponseSchema

{
  "id": "string",
  "email": "string",
  "display_name": "string",
  "avatar_url": "string",
  "locale": "string",
  "has_password": true,
  "identities": [
    {
      "provider": "google",
      "email": "string",
      "created_at": "2019-08-24T14:15:22Z"
    }
  ],
  "created_at": "2019-08-24T14:15:22Z"
}

{  "id": "string",  "email": "string",  "display_name": "string",  "avatar_url": "string",  "locale": "string",  "has_password": true,  "identities": [    {      "provider": "google",      "email": "string",      "created_at": "2019-08-24T14:15:22Z"    }  ],  "created_at": "2019-08-24T14:15:22Z"}

Avatar Get

GET

/account/avatars/{user_id}/{version}

Public: the URL embeds a random version, so it is unguessable and cacheable forever.

Path Parameters

user_id*User Id

Match^[A-Za-z0-9_-]+$

version*Version

Match^[A-Za-z0-9_-]+$

Response Body

Successful Response

image/webp

Example Request

curl -X GET 'https://example.com/account/avatars/string/string'

Example Request

curl -X GET 'https://example.com/account/avatars/string/string'

Example Response

Empty

Confirm the new account email with its code.

POST

/account/email/change-confirm

Finishes an email change started with account.email.change_start.

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

body

code*Code

The 6-digit code sent to the new address

Match^\d{6}$

Response Body

Successful Response

application/json

response

id*Id

email*Email

display_name*Display Name

avatar_url*string|null

locale*string|null

has_password*Has Password

identities*array<>

created_at*Created At

Formatdate-time

Example Request

curl -X POST 'https://example.com/account/email/change-confirm' \
  -H 'Content-Type: application/json' \
  -d '{
  "code": "string"
}'

Example Request

curl -X POST 'https://example.com/account/email/change-confirm' \  -H 'Content-Type: application/json' \  -d '{  "code": "string"}'

Example ResponseSchema

{
  "id": "string",
  "email": "string",
  "display_name": "string",
  "avatar_url": "string",
  "locale": "string",
  "has_password": true,
  "identities": [
    {
      "provider": "google",
      "email": "string",
      "created_at": "2019-08-24T14:15:22Z"
    }
  ],
  "created_at": "2019-08-24T14:15:22Z"
}

{  "id": "string",  "email": "string",  "display_name": "string",  "avatar_url": "string",  "locale": "string",  "has_password": true,  "identities": [    {      "provider": "google",      "email": "string",      "created_at": "2019-08-24T14:15:22Z"    }  ],  "created_at": "2019-08-24T14:15:22Z"}

Start changing the account email.

POST

/account/email/change-start

Sends a verification code to the new address. 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

body

new_email*New Email

The new email address; a code is sent to it

password?|

Current password; needed unless the session signed in during the last 10 minutes

Response Body

Successful Response

application/json

response

resend_in_seconds*Resend In Seconds

expires_in_seconds*Expires In Seconds

Example Request

curl -X POST 'https://example.com/account/email/change-start' \
  -H 'Content-Type: application/json' \
  -d '{
  "new_email": "string"
}'

Example Request

curl -X POST 'https://example.com/account/email/change-start' \  -H 'Content-Type: application/json' \  -d '{  "new_email": "string"}'

Example ResponseSchema

{
  "resend_in_seconds": 0,
  "expires_in_seconds": 0
}

{  "resend_in_seconds": 0,  "expires_in_seconds": 0}

Link a Google account to the signed-in user.

POST

/account/google/link

Links the Google account behind the given ID token. 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

body

id_token*Id Token

Google Identity Services ID token

Lengthlength <= 4096

Response Body

Successful Response

application/json

response

id*Id

email*Email

display_name*Display Name

avatar_url*string|null

locale*string|null

has_password*Has Password

identities*array<>

created_at*Created At

Formatdate-time

Example Request

curl -X POST 'https://example.com/account/google/link' \
  -H 'Content-Type: application/json' \
  -d '{
  "id_token": "string"
}'

Example Request

curl -X POST 'https://example.com/account/google/link' \  -H 'Content-Type: application/json' \  -d '{  "id_token": "string"}'

Example ResponseSchema

{
  "id": "string",
  "email": "string",
  "display_name": "string",
  "avatar_url": "string",
  "locale": "string",
  "has_password": true,
  "identities": [
    {
      "provider": "google",
      "email": "string",
      "created_at": "2019-08-24T14:15:22Z"
    }
  ],
  "created_at": "2019-08-24T14:15:22Z"
}

{  "id": "string",  "email": "string",  "display_name": "string",  "avatar_url": "string",  "locale": "string",  "has_password": true,  "identities": [    {      "provider": "google",      "email": "string",      "created_at": "2019-08-24T14:15:22Z"    }  ],  "created_at": "2019-08-24T14:15:22Z"}

Unlink Google from the signed-in user.

POST

/account/google/unlink

Removes the Google sign-in. Email code sign-in always remains available.

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

response

id*Id

email*Email

display_name*Display Name

avatar_url*string|null

locale*string|null

has_password*Has Password

identities*array<>

created_at*Created At

Formatdate-time

Example Request

curl -X POST 'https://example.com/account/google/unlink'

Example Request

curl -X POST 'https://example.com/account/google/unlink'

Example ResponseSchema

{
  "id": "string",
  "email": "string",
  "display_name": "string",
  "avatar_url": "string",
  "locale": "string",
  "has_password": true,
  "identities": [
    {
      "provider": "google",
      "email": "string",
      "created_at": "2019-08-24T14:15:22Z"
    }
  ],
  "created_at": "2019-08-24T14:15:22Z"
}

{  "id": "string",  "email": "string",  "display_name": "string",  "avatar_url": "string",  "locale": "string",  "has_password": true,  "identities": [    {      "provider": "google",      "email": "string",      "created_at": "2019-08-24T14:15:22Z"    }  ],  "created_at": "2019-08-24T14:15:22Z"}

Change or set the account password.

POST

/account/password/change

Change the password (or set the first one). Signs out all other sessions.

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

body

current_password?|

Current password; omit when the account has none yet

new_password*New Password

The new password

Length1 <= length <= 256

Response Body

Successful Response

application/json

response

id*Id

email*Email

display_name*Display Name

avatar_url*string|null

locale*string|null

has_password*Has Password

identities*array<>

created_at*Created At

Formatdate-time

Example Request

curl -X POST 'https://example.com/account/password/change' \
  -H 'Content-Type: application/json' \
  -d '{
  "new_password": "string"
}'

Example Request

curl -X POST 'https://example.com/account/password/change' \  -H 'Content-Type: application/json' \  -d '{  "new_password": "string"}'

Example ResponseSchema

{
  "id": "string",
  "email": "string",
  "display_name": "string",
  "avatar_url": "string",
  "locale": "string",
  "has_password": true,
  "identities": [
    {
      "provider": "google",
      "email": "string",
      "created_at": "2019-08-24T14:15:22Z"
    }
  ],
  "created_at": "2019-08-24T14:15:22Z"
}

{  "id": "string",  "email": "string",  "display_name": "string",  "avatar_url": "string",  "locale": "string",  "has_password": true,  "identities": [    {      "provider": "google",      "email": "string",      "created_at": "2019-08-24T14:15:22Z"    }  ],  "created_at": "2019-08-24T14:15:22Z"}

Get the signed-in user's account profile.

GET

/account/me

Use when you need the user's name, email address or preferred language. Do not use to read academic data; use the academics, grading or schedule capabilities.

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

response

id*Id

email*Email

display_name*Display Name

avatar_url*string|null

locale*string|null

has_password*Has Password

identities*array<>

created_at*Created At

Formatdate-time

Example Request

curl -X GET 'https://example.com/account/me'

Example Request

curl -X GET 'https://example.com/account/me'

Example ResponseSchema

{
  "id": "string",
  "email": "string",
  "display_name": "string",
  "avatar_url": "string",
  "locale": "string",
  "has_password": true,
  "identities": [
    {
      "provider": "google",
      "email": "string",
      "created_at": "2019-08-24T14:15:22Z"
    }
  ],
  "created_at": "2019-08-24T14:15:22Z"
}

{  "id": "string",  "email": "string",  "display_name": "string",  "avatar_url": "string",  "locale": "string",  "has_password": true,  "identities": [    {      "provider": "google",      "email": "string",      "created_at": "2019-08-24T14:15:22Z"    }  ],  "created_at": "2019-08-24T14:15:22Z"}

Update the display name or avatar.

PATCH

/account/profile

Change the signed-in user's profile. 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

body

display_name?|

New display name

avatar_url?|

HTTPS URL of the avatar image; send null to fall back to initials

Response Body

Successful Response

application/json

response

id*Id

email*Email

display_name*Display Name

avatar_url*string|null

locale*string|null

has_password*Has Password

identities*array<>

created_at*Created At

Formatdate-time

Example Request

curl -X PATCH 'https://example.com/account/profile' \
  -H 'Content-Type: application/json' \
  -d '{}'

Example Request

curl -X PATCH 'https://example.com/account/profile' \  -H 'Content-Type: application/json' \  -d '{}'

Example ResponseSchema

{
  "id": "string",
  "email": "string",
  "display_name": "string",
  "avatar_url": "string",
  "locale": "string",
  "has_password": true,
  "identities": [
    {
      "provider": "google",
      "email": "string",
      "created_at": "2019-08-24T14:15:22Z"
    }
  ],
  "created_at": "2019-08-24T14:15:22Z"
}

{  "id": "string",  "email": "string",  "display_name": "string",  "avatar_url": "string",  "locale": "string",  "has_password": true,  "identities": [    {      "provider": "google",      "email": "string",      "created_at": "2019-08-24T14:15:22Z"    }  ],  "created_at": "2019-08-24T14:15:22Z"}

List the signed-in devices.

GET

/account/sessions

Lists active sessions of the signed-in user. 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.

Response Body

Successful Response

application/json

response

items*array<>

Example Request

curl -X GET 'https://example.com/account/sessions'

Example Request

curl -X GET 'https://example.com/account/sessions'

Example ResponseSchema

{
  "items": [
    {
      "id": "string",
      "kind": "web",
      "user_agent": "string",
      "ip": "string",
      "created_at": "2019-08-24T14:15:22Z",
      "last_used_at": "2019-08-24T14:15:22Z",
      "expires_at": "2019-08-24T14:15:22Z",
      "current": true
    }
  ]
}

{  "items": [    {      "id": "string",      "kind": "web",      "user_agent": "string",      "ip": "string",      "created_at": "2019-08-24T14:15:22Z",      "last_used_at": "2019-08-24T14:15:22Z",      "expires_at": "2019-08-24T14:15:22Z",      "current": true    }  ]}

Sign out one device.

DELETE

/account/sessions/{session_id}

Revokes a session. Revoking the current session signs this browser out.

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

session_id*Session Id

Id of the session to sign out

Response Body

Successful Response

application/json

response

ok?Ok

Defaulttrue

Example Request

curl -X DELETE 'https://example.com/account/sessions/string'

Example Request

curl -X DELETE 'https://example.com/account/sessions/string'

Example ResponseSchema

{
  "ok": true
}

{  "ok": true}

Sign out all other devices.

POST

/account/sessions/revoke-others

Revokes every session except the current one.

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

response

ok?Ok

Defaulttrue

Example Request

curl -X POST 'https://example.com/account/sessions/revoke-others'

Example Request

curl -X POST 'https://example.com/account/sessions/revoke-others'

Example ResponseSchema

{
  "ok": true
}

{  "ok": true}

List personal access tokens.

GET

/account/tokens

Lists the user's non-revoked personal access tokens (never the secrets).

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

response

items*array<>

Example Request

curl -X GET 'https://example.com/account/tokens'

Example Request

curl -X GET 'https://example.com/account/tokens'

Example ResponseSchema

{
  "items": [
    {
      "id": "string",
      "name": "string",
      "prefix": "string",
      "scopes": [
        "read"
      ],
      "created_at": "2019-08-24T14:15:22Z",
      "last_used_at": "2019-08-24T14:15:22Z",
      "expires_at": "2019-08-24T14:15:22Z"
    }
  ]
}

{  "items": [    {      "id": "string",      "name": "string",      "prefix": "string",      "scopes": [        "read"      ],      "created_at": "2019-08-24T14:15:22Z",      "last_used_at": "2019-08-24T14:15:22Z",      "expires_at": "2019-08-24T14:15:22Z"    }  ]}

Create a personal access token for an MCP client.

POST

/account/tokens

Creates a token. The plaintext is returned once and cannot be retrieved again.

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

body

name*Name

A label, e.g. the client name

Length1 <= length <= 60

scopes?array<>

read allows read capabilities only; write also allows changes

Items1 <= items

expires_in_days?|

Lifetime in days; omit for no expiry

password?|

Current password; needed unless the session signed in during the last 10 minutes

Response Body

Successful Response

application/json

response

id*Id

name*Name

prefix*Prefix

scopes*array<>

created_at*Created At

Formatdate-time

last_used_at*|null

expires_at*|null

token*Token

The plaintext token. Shown once, never stored.

Example Request

curl -X POST 'https://example.com/account/tokens' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "string"
}'

Example Request

curl -X POST 'https://example.com/account/tokens' \  -H 'Content-Type: application/json' \  -d '{  "name": "string"}'

Example ResponseSchema

{
  "id": "string",
  "name": "string",
  "prefix": "string",
  "scopes": [
    "read"
  ],
  "created_at": "2019-08-24T14:15:22Z",
  "last_used_at": "2019-08-24T14:15:22Z",
  "expires_at": "2019-08-24T14:15:22Z",
  "token": "string"
}

{  "id": "string",  "name": "string",  "prefix": "string",  "scopes": [    "read"  ],  "created_at": "2019-08-24T14:15:22Z",  "last_used_at": "2019-08-24T14:15:22Z",  "expires_at": "2019-08-24T14:15:22Z",  "token": "string"}

Revoke a personal access token.

DELETE

/account/tokens/{id}

Revokes the token immediately.

response

ok?Ok

Defaulttrue

Example Request

curl -X DELETE 'https://example.com/account/tokens/string'

Example Request

curl -X DELETE 'https://example.com/account/tokens/string'

Example ResponseSchema

{
  "ok": true
}

{  "ok": true}

Upload a profile picture (PNG, JPEG or WebP, up to 5 MB).复制链接

Authorization复制链接

Request Body复制链接

Response Body复制链接

Avatar Get复制链接

Path Parameters复制链接

Response Body复制链接

Confirm the new account email with its code.复制链接

Authorization复制链接

Request Body复制链接

Response Body复制链接

Start changing the account email.复制链接

Authorization复制链接

Request Body复制链接

Response Body复制链接

Link a Google account to the signed-in user.复制链接

Authorization复制链接

Request Body复制链接

Response Body复制链接

Unlink Google from the signed-in user.复制链接

Authorization复制链接

Response Body复制链接

Change or set the account password.复制链接

Authorization复制链接

Request Body复制链接

Response Body复制链接

Get the signed-in user's account profile.复制链接

Authorization复制链接

Response Body复制链接

Update the display name or avatar.复制链接

Authorization复制链接

Request Body复制链接

Response Body复制链接

List the signed-in devices.复制链接

Authorization复制链接

Response Body复制链接

Sign out one device.复制链接

Authorization复制链接

Path Parameters复制链接

Response Body复制链接

Sign out all other devices.复制链接

Authorization复制链接

Response Body复制链接

List personal access tokens.复制链接

Authorization复制链接

Response Body复制链接

Create a personal access token for an MCP client.复制链接

Authorization复制链接

Request Body复制链接

Response Body复制链接

Revoke a personal access token.复制链接

Authorization复制链接

Path Parameters复制链接

Response Body复制链接

Upload a profile picture (PNG, JPEG or WebP, up to 5 MB).

Authorization

Request Body

Response Body

Avatar Get

Path Parameters

Response Body

Confirm the new account email with its code.

Authorization

Request Body

Response Body

Start changing the account email.

Authorization

Request Body

Response Body

Link a Google account to the signed-in user.

Authorization

Request Body

Response Body

Unlink Google from the signed-in user.

Authorization

Response Body

Change or set the account password.

Authorization

Request Body

Response Body

Get the signed-in user's account profile.

Authorization

Response Body

Update the display name or avatar.

Authorization

Request Body

Response Body

List the signed-in devices.

Authorization

Response Body

Sign out one device.

Authorization

Path Parameters

Response Body

Sign out all other devices.

Authorization

Response Body

List personal access tokens.

Authorization

Response Body

Create a personal access token for an MCP client.

Authorization

Request Body

Response Body

Revoke a personal access token.

Authorization

Path Parameters

Response Body