Semestra

Export, import and account deletion

Upload a backup file and get its preview.

POST
/me/imports

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
  1. body
file*File

Response Body

Successful Response

application/json
  1. response
id*Id
status*Status
Value in"uploaded""importing""imported""failed"
size_bytes*integer|null
preview*
report*|null
error_code*string|null
job_id*string|null
created_at*Created At
Formatdate-time
expires_at*Expires At
Formatdate-time
Example Request
curl -X POST 'https://example.com/me/imports' \  -F 'file=string'
Example Response
{  "id": "string",  "status": "uploaded",  "size_bytes": 0,  "preview": {    "exported_at": "2019-08-24T14:15:22Z",    "app_version": "string",    "include_files": true,    "files_bytes": 0,    "counts": {      "property1": {        "property1": 0,        "property2": 0      },      "property2": {        "property1": 0,        "property2": 0      }    },    "programs": [      {        "id": "string",        "name": "string",        "term_count": 0,        "course_count": 0      }    ],    "quota_exceeded": true,    "unknown_modules": [      "string"    ]  },  "report": {    "imported": {      "property1": {        "property1": 0,        "property2": 0      },      "property2": {        "property1": 0,        "property2": 0      }    },    "skipped": {      "property1": {        "property1": 0,        "property2": 0      },      "property2": {        "property1": 0,        "property2": 0      }    }  },  "error_code": "string",  "job_id": "string",  "created_at": "2019-08-24T14:15:22Z",  "expires_at": "2019-08-24T14:15:22Z"}

Export Download

GET
/me/exports/{export_id}/download

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

export_id*Export Id

Response Body

Successful Response

application/zip
Example Request
curl -X GET 'https://example.com/me/exports/string/download'
Example Response
Empty

Delete the user's account and all of their data.

POST
/me:delete

Irreversible. Signs out everywhere at once; the data is deleted by a background job. 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
confirmation*Confirmation

The typed confirmation sentence.

Lengthlength <= 100
acknowledged*Acknowledged

The user ticked that this cannot be undone.

password?|

Re-authentication when the last sign-in is older than 10 minutes.

Response Body

Successful Response

application/json
  1. response
id*Id
kind*Kind
status*Status
Value in"pending""running""succeeded""failed""cancelled"
progress*Progress
step*string|null
step_current*integer|null
step_total*integer|null
result*|null
error_code*string|null
error_params*|null
attempts*Attempts
max_attempts*Max Attempts
cancel_requested*Cancel Requested
created_at*Created At
Formatdate-time
started_at*|null
finished_at*|null
waiting?|null
Example Request
curl -X POST 'https://example.com/me:delete' \  -H 'Content-Type: application/json' \  -d '{  "confirmation": "string",  "acknowledged": true}'
Example Response
{  "id": "string",  "kind": "string",  "status": "pending",  "progress": 0,  "step": "string",  "step_current": 0,  "step_total": 0,  "result": {},  "error_code": "string",  "error_params": {},  "attempts": 0,  "max_attempts": 0,  "cancel_requested": true,  "created_at": "2019-08-24T14:15:22Z",  "started_at": "2019-08-24T14:15:22Z",  "finished_at": "2019-08-24T14:15:22Z",  "waiting": {    "reason": "string",    "until": "2019-08-24T14:15:22Z"  }}

Count the user's data: rows per table, for the data settings overview.

GET
/me/data-counts

Every table the portability adapters cover (the user data purged with the account, whether or not a backup exports it), and the caps some modules put on a table. 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.

Response Body

Successful Response

application/json
  1. response
tables*

Rows the user has in each table the portability adapters cover (the user data purged with the account, exported or not), by table name

limits*

Most rows a user may have, for the tables a module caps, by table name

Example Request
curl -X GET 'https://example.com/me/data-counts'
Example Response
{  "tables": {    "property1": 0,    "property2": 0  },  "limits": {    "property1": 0,    "property2": 0  }}

List the user's recent exports and whether they can be downloaded.

GET
/me/exports

Newest first; expired exports are left 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.

Response Body

Successful Response

application/json
  1. response
items*array<>
Example Request
curl -X GET 'https://example.com/me/exports'
Example Response
{  "items": [    {      "id": "string",      "status": "pending",      "include_files": true,      "size_bytes": 0,      "job_id": "string",      "created_at": "2019-08-24T14:15:22Z",      "expires_at": "2019-08-24T14:15:22Z"    }  ]}

Start exporting the user's data to a backup file.

POST
/me/exports

Runs as a background job; the file can be downloaded for 24 hours.

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
include_files?Include Files

Pack the stored files into the backup too.

Defaultfalse

Response Body

Successful Response

application/json
  1. response
id*Id
status*Status
Value in"pending""ready""failed"
include_files*Include Files
size_bytes*integer|null
job_id*string|null
created_at*Created At
Formatdate-time
expires_at*Expires At

The download link works until then.

Formatdate-time
Example Request
curl -X POST 'https://example.com/me/exports' \  -H 'Content-Type: application/json' \  -d '{}'
Example Response
{  "id": "string",  "status": "pending",  "include_files": true,  "size_bytes": 0,  "job_id": "string",  "created_at": "2019-08-24T14:15:22Z",  "expires_at": "2019-08-24T14:15:22Z"}

Get an uploaded backup: its preview, and the import's state and report.

GET
/me/imports/{id}

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.

Path Parameters

id*Id

Upload id, as returned by the upload.

Response Body

Successful Response

application/json
  1. response
id*Id
status*Status
Value in"uploaded""importing""imported""failed"
size_bytes*integer|null
preview*
report*|null
error_code*string|null
job_id*string|null
created_at*Created At
Formatdate-time
expires_at*Expires At
Formatdate-time
Example Request
curl -X GET 'https://example.com/me/imports/string'
Example Response
{  "id": "string",  "status": "uploaded",  "size_bytes": 0,  "preview": {    "exported_at": "2019-08-24T14:15:22Z",    "app_version": "string",    "include_files": true,    "files_bytes": 0,    "counts": {      "property1": {        "property1": 0,        "property2": 0      },      "property2": {        "property1": 0,        "property2": 0      }    },    "programs": [      {        "id": "string",        "name": "string",        "term_count": 0,        "course_count": 0      }    ],    "quota_exceeded": true,    "unknown_modules": [      "string"    ]  },  "report": {    "imported": {      "property1": {        "property1": 0,        "property2": 0      },      "property2": {        "property1": 0,        "property2": 0      }    },    "skipped": {      "property1": {        "property1": 0,        "property2": 0      },      "property2": {        "property1": 0,        "property2": 0      }    }  },  "error_code": "string",  "job_id": "string",  "created_at": "2019-08-24T14:15:22Z",  "expires_at": "2019-08-24T14:15:22Z"}

Discard an uploaded backup without importing it.

DELETE
/me/imports/{id}

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.

Path Parameters

id*Id

Upload id, as returned by the upload.

Response Body

Successful Response

application/json
  1. response
id*Id
Example Request
curl -X DELETE 'https://example.com/me/imports/string'
Example Response
{  "id": "string"}

Import an uploaded backup, merging it or replacing the current data.

POST
/me/imports/{id}:start

Runs as a background job in one transaction. 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.

Path Parameters

id*Id

Upload id, as returned by the upload.

Request Body

application/json
  1. body
mode*Mode

merge adds the backup as new data; replace deletes the current data first.

Value in"merge""replace"
program_ids?array<string>|

Ids (from the preview) of the Programs to import; all if null.

include_preferences?Include Preferences

Also import preferences, layouts and account-level settings.

Defaultfalse
confirmation?|

The typed confirmation sentence; required for replace.

Response Body

Successful Response

application/json
  1. response
id*Id
status*Status
Value in"uploaded""importing""imported""failed"
size_bytes*integer|null
preview*
report*|null
error_code*string|null
job_id*string|null
created_at*Created At
Formatdate-time
expires_at*Expires At
Formatdate-time
Example Request
curl -X POST 'https://example.com/me/imports/string:start' \  -H 'Content-Type: application/json' \  -d '{  "mode": "merge"}'
Example Response
{  "id": "string",  "status": "uploaded",  "size_bytes": 0,  "preview": {    "exported_at": "2019-08-24T14:15:22Z",    "app_version": "string",    "include_files": true,    "files_bytes": 0,    "counts": {      "property1": {        "property1": 0,        "property2": 0      },      "property2": {        "property1": 0,        "property2": 0      }    },    "programs": [      {        "id": "string",        "name": "string",        "term_count": 0,        "course_count": 0      }    ],    "quota_exceeded": true,    "unknown_modules": [      "string"    ]  },  "report": {    "imported": {      "property1": {        "property1": 0,        "property2": 0      },      "property2": {        "property1": 0,        "property2": 0      }    },    "skipped": {      "property1": {        "property1": 0,        "property2": 0      },      "property2": {        "property1": 0,        "property2": 0      }    }  },  "error_code": "string",  "job_id": "string",  "created_at": "2019-08-24T14:15:22Z",  "expires_at": "2019-08-24T14:15:22Z"}