Semestra

Sem (assistant)

Upload a file or image for the assistant.

POST
/agent/attachments

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
session_id*Session Id
file*File

Response Body

Successful Response

application/json
  1. response
id*Id
session_id*Session Id
kind*Kind
Value in"image""file"
name*Name
mime*Mime
size*Size
created_at*Created At
Formatdate-time
file_item_id?string|null
Example Request
curl -X POST 'https://example.com/agent/attachments' \  -F 'session_id=string' \  -F 'file=string'
Example Response
{  "id": "string",  "session_id": "string",  "kind": "image",  "name": "string",  "mime": "string",  "size": 0,  "created_at": "2019-08-24T14:15:22Z",  "file_item_id": "string"}

Remove an uploaded attachment that has not been sent.

DELETE
/agent/attachments/{id}

Attachments already part of a message stay until the conversation is deleted.

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

Attachment id.

Response Body

Successful Response

application/json
  1. response
deleted*Deleted
Example Request
curl -X DELETE 'https://example.com/agent/attachments/string'
Example Response
{  "deleted": true}

Save a file attached to the conversation to a course's files.

POST
/agent/attachments/{id}:save

Use when the user wants to keep an attached document (a syllabus, notes) with the course. The file is then processed like any course file (searchable, citable). Saving it to the same course again returns the saved file.

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

Attachment id

Request Body

application/json
  1. body
course_id*Course Id

Course to save the file to

Response Body

Successful Response

application/json
  1. response
id*Id
course_id*Course Id
folder_id*string|null
kind*Kind
Value in"file""link"
display_name*Display Name
original_name*string|null
mime_type*string|null
size_bytes*Size Bytes
sha256*string|null
url*string|null
pinned*Pinned
source_kind*|null
source_ref*string|null
doc_status*Doc Status
Value in"none""pending""processing""ready""failed""unsupported"
doc_error_code*string|null
page_count*integer|null
ocr_skipped_pages*Ocr Skipped Pages
job_id*string|null
created_at*Created At
Formatdate-time
updated_at*Updated At
Formatdate-time
Example Request
curl -X POST 'https://example.com/agent/attachments/string:save' \  -H 'Content-Type: application/json' \  -d '{  "course_id": "string"}'
Example Response
{  "id": "string",  "course_id": "string",  "folder_id": "string",  "kind": "file",  "display_name": "string",  "original_name": "string",  "mime_type": "string",  "size_bytes": 0,  "sha256": "string",  "url": "string",  "pinned": true,  "source_kind": "upload",  "source_ref": "string",  "doc_status": "none",  "doc_error_code": "string",  "page_count": 0,  "ocr_skipped_pages": 0,  "job_id": "string",  "created_at": "2019-08-24T14:15:22Z",  "updated_at": "2019-08-24T14:15:22Z"}

Delete every memory.

POST
/agent/memories:clear

Conversations are kept.

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
deleted*Deleted
Example Request
curl -X POST 'https://example.com/agent/memories:clear'
Example Response
{  "deleted": 0}

Edit a memory.

PATCH
/agent/memories/{id}

Only the fields sent are changed. Also the undo of a memory updated in a conversation (send back its previous fields).

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

Memory id.

Request Body

application/json
  1. body
name?|

The memory's kebab-case name (lowercase ASCII letters, digits and hyphens), such as preferred-name or no-tables-in-answers.

type?|

New type.

description?|

New one-line text.

body?|

New body; an empty string removes it.

Response Body

Successful Response

application/json
  1. response
id*Id
name*Name
type*Type
Value in"user""feedback""project""reference"
description*Description
body*Body
source_session_id*string|null
created_at*Created At
Formatdate-time
updated_at*Updated At
Formatdate-time
Example Request
curl -X PATCH 'https://example.com/agent/memories/string' \  -H 'Content-Type: application/json' \  -d '{}'
Example Response
{  "id": "string",  "name": "string",  "type": "user",  "description": "string",  "body": "string",  "source_session_id": "string",  "created_at": "2019-08-24T14:15:22Z",  "updated_at": "2019-08-24T14:15:22Z"}

Delete a memory.

DELETE
/agent/memories/{id}

Also the undo of a memory saved in a conversation.

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

Memory id.

Response Body

Successful Response

application/json
  1. response
id*Id
name*Name
type*Type
Value in"user""feedback""project""reference"
description*Description
body*Body
source_session_id*string|null
created_at*Created At
Formatdate-time
updated_at*Updated At
Formatdate-time
Example Request
curl -X DELETE 'https://example.com/agent/memories/string'
Example Response
{  "id": "string",  "name": "string",  "type": "user",  "description": "string",  "body": "string",  "source_session_id": "string",  "created_at": "2019-08-24T14:15:22Z",  "updated_at": "2019-08-24T14:15:22Z"}

List what Sem remembers about the user.

GET
/agent/memories

Newest first.

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<>
limit*Limit
Example Request
curl -X GET 'https://example.com/agent/memories'
Example Response
{  "items": [    {      "id": "string",      "name": "string",      "type": "user",      "description": "string",      "body": "string",      "source_session_id": "string",      "created_at": "2019-08-24T14:15:22Z",      "updated_at": "2019-08-24T14:15:22Z"    }  ],  "limit": 0}

Get the assistant preferences.

GET
/agent/preferences

Which write actions run without a confirmation card; MCP delete permission.

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
auto_approve*array<string>

Write capabilities that run without asking.

mcp_allow_destructive*Mcp Allow Destructive

MCP clients may run delete actions.

Example Request
curl -X GET 'https://example.com/agent/preferences'
Example Response
{  "auto_approve": [    "string"  ],  "mcp_allow_destructive": true}

Change the assistant preferences.

PATCH
/agent/preferences

Only write actions can be auto-approved; delete actions always ask.

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
auto_approve?array<string>|

Write capabilities that run without asking.

mcp_allow_destructive?|

Let MCP clients run delete actions.

Response Body

Successful Response

application/json
  1. response
auto_approve*array<string>

Write capabilities that run without asking.

mcp_allow_destructive*Mcp Allow Destructive

MCP clients may run delete actions.

Example Request
curl -X PATCH 'https://example.com/agent/preferences' \  -H 'Content-Type: application/json' \  -d '{}'
Example Response
{  "auto_approve": [    "string"  ],  "mcp_allow_destructive": true}

List the user's assistant conversations.

GET
/agent/sessions

Newest first; pinned ones are sorted by the client.

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.

Query Parameters

query?|

Matches the title.

archived?Archived

List archived sessions instead.

Defaultfalse
limit?Limit

At most this many, newest first.

Default100

Response Body

Successful Response

application/json
  1. response
items*array<>
Example Request
curl -X GET 'https://example.com/agent/sessions'
Example Response
{  "items": [    {      "id": "string",      "title": "string",      "program_id": "string",      "scope": {        "program_id": "string",        "term_id": "string",        "course_id": "string"      },      "pinned": true,      "temporary": true,      "created_at": "2019-08-24T14:15:22Z",      "updated_at": "2019-08-24T14:15:22Z",      "archived_at": "2019-08-24T14:15:22Z"    }  ]}

Start a new conversation.

POST
/agent/sessions

Where the assistant works: a Program or one of its terms. Idempotent per client_key.

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
scope?|

Page scope to start from.

client_key?|

Random key of the new conversation in the client; creating again with the same key returns the same conversation (double sends, upload and send racing).

temporary?Temporary

A temporary chat neither reads nor writes memories.

Defaultfalse

Response Body

Successful Response

application/json
  1. response
id*Id
title*string|null
program_id*string|null
scope*|null
pinned*Pinned
temporary*Temporary
created_at*Created At
Formatdate-time
updated_at*Updated At
Formatdate-time
archived_at*|null
Example Request
curl -X POST 'https://example.com/agent/sessions' \  -H 'Content-Type: application/json' \  -d '{}'
Example Response
{  "id": "string",  "title": "string",  "program_id": "string",  "scope": {    "program_id": "string",    "term_id": "string",    "course_id": "string"  },  "pinned": true,  "temporary": true,  "created_at": "2019-08-24T14:15:22Z",  "updated_at": "2019-08-24T14:15:22Z",  "archived_at": "2019-08-24T14:15:22Z"}

Get a conversation with its messages and proposals.

GET
/agent/sessions/{id}

Pending proposals older than 24 hours are reported as expired.

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

Session id.

Response Body

Successful Response

application/json
  1. response
session*
messages*array<>
proposals*array<>
attachments*array<>
generating*Generating

An answer is being generated right now.

regenerable?|

The answer that can be regenerated (its first message's id), if any.

compactable?Compactable

There are turns before the last message to compact now.

Defaultfalse
context?|

How full the context is.

compaction?|

The summary that stands in for the earlier conversation.

Example Request
curl -X GET 'https://example.com/agent/sessions/string'
Example Response
{  "session": {    "id": "string",    "title": "string",    "program_id": "string",    "scope": {      "program_id": "string",      "term_id": "string",      "course_id": "string"    },    "pinned": true,    "temporary": true,    "created_at": "2019-08-24T14:15:22Z",    "updated_at": "2019-08-24T14:15:22Z",    "archived_at": "2019-08-24T14:15:22Z"  },  "messages": [    {      "id": "string",      "role": "user",      "content": [        {}      ],      "model": "string",      "input_tokens": 0,      "output_tokens": 0,      "created_at": "2019-08-24T14:15:22Z"    }  ],  "proposals": [    {      "id": "string",      "session_id": "string",      "message_id": "string",      "call_id": "string",      "capability": "string",      "effect": "read",      "args": {},      "input_schema": {},      "preview": {},      "status": "pending",      "result": null,      "display": {},      "error_code": "string",      "created_at": "2019-08-24T14:15:22Z",      "decided_at": "2019-08-24T14:15:22Z",      "executed_at": "2019-08-24T14:15:22Z"    }  ],  "attachments": [    {      "id": "string",      "session_id": "string",      "kind": "image",      "name": "string",      "mime": "string",      "size": 0,      "created_at": "2019-08-24T14:15:22Z",      "file_item_id": "string"    }  ],  "generating": true,  "regenerable": "string",  "compactable": false,  "context": {    "used": 0,    "window": 0,    "parts": {      "instructions": 0,      "tools": 0,      "summary": 0,      "conversation": 0,      "reads": 0,      "attachments": 0    }  },  "compaction": {    "until": "string",    "summary": "string"  }}

Rename, pin, archive a conversation or change where it works.

PATCH
/agent/sessions/{id}

Only the fields sent are changed.

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

Session id.

Request Body

application/json
  1. body
title?|

New title.

pinned?|

Pin to the top of the list.

archived?|

Archive or restore.

scope?|

Change where the assistant works (a term or the whole Program).

Response Body

Successful Response

application/json
  1. response
id*Id
title*string|null
program_id*string|null
scope*|null
pinned*Pinned
temporary*Temporary
created_at*Created At
Formatdate-time
updated_at*Updated At
Formatdate-time
archived_at*|null
Example Request
curl -X PATCH 'https://example.com/agent/sessions/string' \  -H 'Content-Type: application/json' \  -d '{}'
Example Response
{  "id": "string",  "title": "string",  "program_id": "string",  "scope": {    "program_id": "string",    "term_id": "string",    "course_id": "string"  },  "pinned": true,  "temporary": true,  "created_at": "2019-08-24T14:15:22Z",  "updated_at": "2019-08-24T14:15:22Z",  "archived_at": "2019-08-24T14:15:22Z"}

Delete a conversation with its messages and attachments.

DELETE
/agent/sessions/{id}

Cannot be undone.

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

Session id.

Response Body

Successful Response

application/json
  1. response
deleted*Deleted
Example Request
curl -X DELETE 'https://example.com/agent/sessions/string'
Example Response
{  "deleted": true}

Stop the answer being generated.

POST
/agent/sessions/{id}:stop

What was written so far is kept.

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

Session id.

Response Body

Successful Response

application/json
  1. response
stopped*Stopped
Example Request
curl -X POST 'https://example.com/agent/sessions/string:stop'
Example Response
{  "stopped": true}

List the skills the user can run as slash commands.

GET
/agent/skills

Titles are in both interface languages.

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/agent/skills'
Example Response
{  "items": [    {      "name": "string",      "title": {        "property1": "string",        "property2": "string"      },      "command": "string",      "description": "string",      "module": "string"    }  ]}

Suggested questions for a new conversation.

GET
/agent/suggestions

Up to three, from what is due, today's classes and the gradebook of the scope; in the small model's words when the account allows it (rewritten at most twice a day).

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.

Query Parameters

program_id*Program Id

Program the assistant works in.

term_id?|

Term it works in, if any.

course_id?|

Course of older conversations; new ones work in a Program or a term.

Response Body

Successful Response

application/json
  1. response
items*array<>
Example Request
curl -X GET 'https://example.com/agent/suggestions?program_id=string'
Example Response
{  "items": [    {      "key": "string",      "code": "overdue",      "params": {        "property1": "string",        "property2": "string"      },      "course_id": "string",      "text": "string"    }  ]}

List every tool the assistant can use for this user.

GET
/agent/tools

Plugin tools appear once the 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.

Response Body

Successful Response

application/json
  1. response
items*array<>
Example Request
curl -X GET 'https://example.com/agent/tools'
Example Response
{  "items": [    {      "name": "string",      "module": "string",      "summary": "string",      "effect": "read",      "plugin_id": "string",      "core": true,      "mcp": true,      "confirm": true    }  ]}