Pages and cards

Get the cards on a Program, term or course overview, or on the Today page.

GET

/layouts/boards/{scope_type}/{scope_id}

Use to find card instances (their instance_id and settings), e.g. which sticky notes or habit trackers a course has, before calling a card-specific tool.

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

scope_type*Scope Type

program, term or course overview; 'today' is the Program's Today page

Value in"program""term""course""today"

scope_id*Scope Id

Program, term or course id; for 'today' the Program id

Response Body

Successful Response

application/json

response

scope_type*Scope Type

Value in"program""term""course""today"

scope_id*Scope Id

cards*array<>

customized*Customized

False while the board still follows the template

updated_at*|null

Example Request

curl -X GET 'https://example.com/layouts/boards/program/string'

Example Request

curl -X GET 'https://example.com/layouts/boards/program/string'

Example ResponseSchema

{
  "scope_type": "program",
  "scope_id": "string",
  "cards": [
    {
      "instance_id": "string",
      "card_id": "string",
      "size": "s",
      "x": 0,
      "y": 0,
      "positions": [
        {
          "cols": 6,
          "x": 0,
          "y": 0
        }
      ],
      "settings": {}
    }
  ],
  "customized": true,
  "updated_at": "2019-08-24T14:15:22Z"
}

{  "scope_type": "program",  "scope_id": "string",  "cards": [    {      "instance_id": "string",      "card_id": "string",      "size": "s",      "x": 0,      "y": 0,      "positions": [        {          "cols": 6,          "x": 0,          "y": 0        }      ],      "settings": {}    }  ],  "customized": true,  "updated_at": "2019-08-24T14:15:22Z"}

Replace the card layout of a board (positions, sizes, added and removed cards).

PUT

/layouts/boards/{scope_type}/{scope_id}

Cards left out of the list are deleted together with their data.

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

scope_type*Scope Type

Board scope type

Value in"program""term""course""today"

scope_id*Scope Id

Board scope id

Request Body

application/json

body

cards*array<>

The whole layout; cards left out are deleted

Itemsitems <= 60

Response Body

Successful Response

application/json

response

scope_type*Scope Type

Value in"program""term""course""today"

scope_id*Scope Id

cards*array<>

customized*Customized

False while the board still follows the template

updated_at*|null

Example Request

curl -X PUT 'https://example.com/layouts/boards/program/string' \
  -H 'Content-Type: application/json' \
  -d '{
  "cards": [
    {
      "card_id": "string",
      "size": "s",
      "x": 0,
      "y": 0
    }
  ]
}'

Example Request

curl -X PUT 'https://example.com/layouts/boards/program/string' \  -H 'Content-Type: application/json' \  -d '{  "cards": [    {      "card_id": "string",      "size": "s",      "x": 0,      "y": 0    }  ]}'

Example ResponseSchema

{
  "scope_type": "program",
  "scope_id": "string",
  "cards": [
    {
      "instance_id": "string",
      "card_id": "string",
      "size": "s",
      "x": 0,
      "y": 0,
      "positions": [
        {
          "cols": 6,
          "x": 0,
          "y": 0
        }
      ],
      "settings": {}
    }
  ],
  "customized": true,
  "updated_at": "2019-08-24T14:15:22Z"
}

{  "scope_type": "program",  "scope_id": "string",  "cards": [    {      "instance_id": "string",      "card_id": "string",      "size": "s",      "x": 0,      "y": 0,      "positions": [        {          "cols": 6,          "x": 0,          "y": 0        }      ],      "settings": {}    }  ],  "customized": true,  "updated_at": "2019-08-24T14:15:22Z"}

Add a card to a board, e.g. a sticky note to a course overview.

POST

/layouts/boards/{scope_type}/{scope_id}/cards

Use when the user asks to put a card (sticky note, pomodoro timer, habit tracker, ...) on an overview or the Today page. The card goes to the first free spot. Check with plugins.catalog.list that its plugin is installed.

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

scope_type*Scope Type

program, term or course overview; 'today' is the Program's Today page

Value in"program""term""course""today"

scope_id*Scope Id

Program, term or course id; for 'today' the Program id

Request Body

application/json

body

card_id*Card Id

Card to add, e.g. 'sticky.note' or 'pomodoro.timer'

Length1 <= length <= 100

size?|

Size; default is the card's own

settings?|

Initial settings

Response Body

Successful Response

application/json

response

instance_id*Instance Id

Card instance id; pass it to card capabilities

card_id*Card Id

Which card, e.g. 'sticky.note'

size*Size

s=1x1, m=2x1, l=2x2, xl=4x2 on a 4-column grid

Value in"s""m""l""xl"

x*X

Column, 0-3

y*Y

Row, from 0

positions?array<>

Positions on the wider 6- and 8-column grids, where the user placed them

settings*

The card's settings as stored

Example Request

curl -X POST 'https://example.com/layouts/boards/program/string/cards' \
  -H 'Content-Type: application/json' \
  -d '{
  "card_id": "string"
}'

Example Request

curl -X POST 'https://example.com/layouts/boards/program/string/cards' \  -H 'Content-Type: application/json' \  -d '{  "card_id": "string"}'

Example ResponseSchema

{
  "instance_id": "string",
  "card_id": "string",
  "size": "s",
  "x": 0,
  "y": 0,
  "positions": [
    {
      "cols": 6,
      "x": 0,
      "y": 0
    }
  ],
  "settings": {}
}

{  "instance_id": "string",  "card_id": "string",  "size": "s",  "x": 0,  "y": 0,  "positions": [    {      "cols": 6,      "x": 0,      "y": 0    }  ],  "settings": {}}

Get the settings of a card instance.

GET

/layouts/cards/{instance_id}/settings

layouts.board.get already includes every card's settings.

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

instance_id*Instance Id

Card instance id

Response Body

Successful Response

application/json

response

instance_id*Instance Id

card_id*Card Id

settings*

Example Request

curl -X GET 'https://example.com/layouts/cards/string/settings'

Example Request

curl -X GET 'https://example.com/layouts/cards/string/settings'

Example ResponseSchema

{
  "instance_id": "string",
  "card_id": "string",
  "settings": {}
}

{  "instance_id": "string",  "card_id": "string",  "settings": {}}

Replace the settings of a card instance.

PUT

/layouts/cards/{instance_id}/settings

The settings are validated against the card's schema.

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

instance_id*Instance Id

Card instance id

Request Body

application/json

body

settings*

The card's whole settings object

Response Body

Successful Response

application/json

response

instance_id*Instance Id

card_id*Card Id

settings*

Example Request

curl -X PUT 'https://example.com/layouts/cards/string/settings' \
  -H 'Content-Type: application/json' \
  -d '{
  "settings": {
    "property1": null,
    "property2": null
  }
}'

Example Request

curl -X PUT 'https://example.com/layouts/cards/string/settings' \  -H 'Content-Type: application/json' \  -d '{  "settings": {    "property1": null,    "property2": null  }}'

Example ResponseSchema

{
  "instance_id": "string",
  "card_id": "string",
  "settings": {}
}

{  "instance_id": "string",  "card_id": "string",  "settings": {}}

Remove a card from its board, deleting its data.

DELETE

/layouts/cards/{instance_id}

Use when the user asks to remove a card. Find its instance_id with layouts.board.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

instance_id*Instance Id

Card instance id

Response Body

Successful Response

application/json

response

instance_id*Instance Id

Example Request

curl -X DELETE 'https://example.com/layouts/cards/string'

Example Request

curl -X DELETE 'https://example.com/layouts/cards/string'

Example ResponseSchema

{
  "instance_id": "string"
}

{  "instance_id": "string"}

Get the order and hidden pages of the tab bar of a scope type.

GET

/layouts/nav/{scope_type}

Applies to every Program, every term or every course alike.

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

scope_type*Scope Type

Scope type whose tab bar to read

Value in"program""term""course"

Response Body

Successful Response

application/json

response

scope_type*Scope Type

Value in"program""term""course"

order*array<string>

Page ids in tab order; pages not listed come last

hidden*array<string>

Hidden page ids

Example Request

curl -X GET 'https://example.com/layouts/nav/program'

Example Request

curl -X GET 'https://example.com/layouts/nav/program'

Example ResponseSchema

{
  "scope_type": "program",
  "order": [
    "string"
  ],
  "hidden": [
    "string"
  ]
}

{  "scope_type": "program",  "order": [    "string"  ],  "hidden": [    "string"  ]}

Set the order and hidden pages of the tab bar of a scope type.

PUT

/layouts/nav/{scope_type}

Applies to every Program, every term or every course alike.

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

scope_type*Scope Type

Scope type whose tab bar to change

Value in"program""term""course"

Request Body

application/json

body

order*array<>

Page ids in tab order

Itemsitems <= 100

hidden*array<>

Page ids to hide

Itemsitems <= 100

Response Body

Successful Response

application/json

response

scope_type*Scope Type

Value in"program""term""course"

order*array<string>

Page ids in tab order; pages not listed come last

hidden*array<string>

Hidden page ids

Example Request

curl -X PUT 'https://example.com/layouts/nav/program' \
  -H 'Content-Type: application/json' \
  -d '{
  "order": [
    "string"
  ],
  "hidden": [
    "string"
  ]
}'

Example Request

curl -X PUT 'https://example.com/layouts/nav/program' \  -H 'Content-Type: application/json' \  -d '{  "order": [    "string"  ],  "hidden": [    "string"  ]}'

Example ResponseSchema

{
  "scope_type": "program",
  "order": [
    "string"
  ],
  "hidden": [
    "string"
  ]
}

{  "scope_type": "program",  "order": [    "string"  ],  "hidden": [    "string"  ]}

Get the default card layout new boards of a scope type start from.

GET

/layouts/templates/{scope_type}

Either the user's own default or the built-in 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.

Path Parameters

scope_type*Scope Type

Scope type of the default layout

Value in"program""term""course""today"

Response Body

Successful Response

application/json

response

scope_type*Scope Type

Value in"program""term""course""today"

cards*array<>

customized*Customized

True when the user saved their own default layout

Example Request

curl -X GET 'https://example.com/layouts/templates/program'

Example Request

curl -X GET 'https://example.com/layouts/templates/program'

Example ResponseSchema

{
  "scope_type": "program",
  "cards": [
    {
      "card_id": "string",
      "size": "s",
      "x": 0,
      "y": 0
    }
  ],
  "customized": true
}

{  "scope_type": "program",  "cards": [    {      "card_id": "string",      "size": "s",      "x": 0,      "y": 0    }  ],  "customized": true}

Go back to the built-in default layout of a scope type.

DELETE

/layouts/templates/{scope_type}

Boards that were never changed follow it at once.

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

scope_type*Scope Type

Scope type of the default layout

Value in"program""term""course""today"

Response Body

Successful Response

application/json

response

scope_type*Scope Type

Value in"program""term""course""today"

cards*array<>

customized*Customized

True when the user saved their own default layout

Example Request

curl -X DELETE 'https://example.com/layouts/templates/program'

Example Request

curl -X DELETE 'https://example.com/layouts/templates/program'

Example ResponseSchema

{
  "scope_type": "program",
  "cards": [
    {
      "card_id": "string",
      "size": "s",
      "x": 0,
      "y": 0
    }
  ],
  "customized": true
}

{  "scope_type": "program",  "cards": [    {      "card_id": "string",      "size": "s",      "x": 0,      "y": 0    }  ],  "customized": true}

Make a board's layout the default for its scope type.

POST

/layouts/templates/{scope_type}:from-board

Boards that were never changed follow it at once; changed boards keep theirs.

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

scope_type*Scope Type

Scope type of the board and template

Value in"program""term""course""today"

Request Body

application/json

body

scope_id*Scope Id

The board whose layout becomes the default

Length1 <= length <= 200

Response Body

Successful Response

application/json

response

scope_type*Scope Type

Value in"program""term""course""today"

cards*array<>

customized*Customized

True when the user saved their own default layout

Example Request

curl -X POST 'https://example.com/layouts/templates/program:from-board' \
  -H 'Content-Type: application/json' \
  -d '{
  "scope_id": "string"
}'

Example Request

curl -X POST 'https://example.com/layouts/templates/program:from-board' \  -H 'Content-Type: application/json' \  -d '{  "scope_id": "string"}'

Example ResponseSchema

{
  "scope_type": "program",
  "cards": [
    {
      "card_id": "string",
      "size": "s",
      "x": 0,
      "y": 0
    }
  ],
  "customized": true
}

{  "scope_type": "program",  "cards": [    {      "card_id": "string",      "size": "s",      "x": 0,      "y": 0    }  ],  "customized": true}

Get the cards on a Program, term or course overview, or on the Today page.Copy Anchor Link

AuthorizationCopy Anchor Link

Path ParametersCopy Anchor Link

Response BodyCopy Anchor Link

Replace the card layout of a board (positions, sizes, added and removed cards).Copy Anchor Link

AuthorizationCopy Anchor Link

Path ParametersCopy Anchor Link

Request BodyCopy Anchor Link

Response BodyCopy Anchor Link

Add a card to a board, e.g. a sticky note to a course overview.Copy Anchor Link

AuthorizationCopy Anchor Link

Path ParametersCopy Anchor Link

Request BodyCopy Anchor Link

Response BodyCopy Anchor Link

Get the settings of a card instance.Copy Anchor Link

AuthorizationCopy Anchor Link

Path ParametersCopy Anchor Link

Response BodyCopy Anchor Link

Replace the settings of a card instance.Copy Anchor Link

AuthorizationCopy Anchor Link

Path ParametersCopy Anchor Link

Request BodyCopy Anchor Link

Response BodyCopy Anchor Link

Remove a card from its board, deleting its data.Copy Anchor Link

AuthorizationCopy Anchor Link

Path ParametersCopy Anchor Link

Response BodyCopy Anchor Link

Get the order and hidden pages of the tab bar of a scope type.Copy Anchor Link

AuthorizationCopy Anchor Link

Path ParametersCopy Anchor Link

Response BodyCopy Anchor Link

Set the order and hidden pages of the tab bar of a scope type.Copy Anchor Link

AuthorizationCopy Anchor Link

Path ParametersCopy Anchor Link

Request BodyCopy Anchor Link

Response BodyCopy Anchor Link

Get the default card layout new boards of a scope type start from.Copy Anchor Link

AuthorizationCopy Anchor Link

Path ParametersCopy Anchor Link

Response BodyCopy Anchor Link

Go back to the built-in default layout of a scope type.Copy Anchor Link

AuthorizationCopy Anchor Link

Path ParametersCopy Anchor Link

Response BodyCopy Anchor Link

Make a board's layout the default for its scope type.Copy Anchor Link

AuthorizationCopy Anchor Link

Path ParametersCopy Anchor Link

Request BodyCopy Anchor Link

Response BodyCopy Anchor Link

Get the cards on a Program, term or course overview, or on the Today page.

Authorization

Path Parameters

Response Body

Replace the card layout of a board (positions, sizes, added and removed cards).

Authorization

Path Parameters

Request Body

Response Body

Add a card to a board, e.g. a sticky note to a course overview.

Authorization

Path Parameters

Request Body

Response Body

Get the settings of a card instance.

Authorization

Path Parameters

Response Body

Replace the settings of a card instance.

Authorization

Path Parameters

Request Body

Response Body

Remove a card from its board, deleting its data.

Authorization

Path Parameters

Response Body

Get the order and hidden pages of the tab bar of a scope type.

Authorization

Path Parameters

Response Body

Set the order and hidden pages of the tab bar of a scope type.

Authorization

Path Parameters

Request Body

Response Body

Get the default card layout new boards of a scope type start from.

Authorization

Path Parameters

Response Body

Go back to the built-in default layout of a scope type.

Authorization

Path Parameters

Response Body

Make a board's layout the default for its scope type.

Authorization

Path Parameters

Request Body

Response Body