AI providers and models
Not for agents.
semestra_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.
Successful Response
application/json- response
items*array<>curl -X GET 'https://example.com/ai/assignments'{ "items": [ { "purpose": "chat", "provider_id": "string", "model": "string", "params": { "temperature": 0, "max_tokens": 1, "reasoning_effort": "minimal" }, "recommended": { "provider_id": "string", "model": "string" } } ]}provider_id null removes the choice so the default applies. Not for agents.
semestra_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.
application/json- body
purpose*PurposeWhich purpose to configure.
"chat""extraction""vision""ocr""embedding""title"provider_id*|Provider to use; null removes the choice (the recommended default applies), or, for ocr and embedding with a local model name in model, picks that model this server runs itself.
model?|Model name at that provider.
params?|Model parameters for the purpose; left out, the current ones stay.
Successful Response
application/json- response
items*array<>curl -X PUT 'https://example.com/ai/assignments' \ -H 'Content-Type: application/json' \ -d '{ "purpose": "chat", "provider_id": "string"}'{ "items": [ { "purpose": "chat", "provider_id": "string", "model": "string", "params": { "temperature": 0, "max_tokens": 1, "reasoning_effort": "minimal" }, "recommended": { "provider_id": "string", "model": "string" } } ]}They apply whichever model serves the purpose, Auto included. Not for agents.
semestra_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.
application/json- body
purpose*PurposeWhich purpose to configure.
"chat""extraction""vision""ocr""embedding""title"params*Its model parameters, whichever model serves it (on Auto too).
Successful Response
application/json- response
items*array<>curl -X PUT 'https://example.com/ai/assignments/params' \ -H 'Content-Type: application/json' \ -d '{ "purpose": "chat", "params": {}}'{ "items": [ { "purpose": "chat", "provider_id": "string", "model": "string", "params": { "temperature": 0, "max_tokens": 1, "reasoning_effort": "minimal" }, "recommended": { "provider_id": "string", "model": "string" } } ]}Frees its disk space for every user of the server; whoever uses it gets it downloaded again when it is next needed. Refused while it downloads. Not for agents.
semestra_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.
application/json- body
purpose*PurposeWhat the model is for.
"ocr""embedding"model*ModelThe local model to remove from this server.
length <= 200Successful Response
application/json- response
purpose*Purpose"ocr""embedding"model*Modelcurl -X POST 'https://example.com/ai/local-models/delete' \ -H 'Content-Type: application/json' \ -d '{ "purpose": "ocr", "model": "string"}'{ "purpose": "ocr", "model": "string"}Defaults to the user's model for that purpose. Returns the download job's id, or null when the model is already here. Not for agents.
semestra_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.
application/json- body
purpose*PurposeWhat the model is for.
"ocr""embedding"model?|A local model; defaults to the one this user's purpose uses.
Successful Response
application/json- response
job_id*string|nullcurl -X POST 'https://example.com/ai/local-models/download' \ -H 'Content-Type: application/json' \ -d '{ "purpose": "ocr"}'{ "job_id": "string"}Providers the user connected with their own API keys. Not for agents.
semestra_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.
Successful Response
application/json- response
items*array<>curl -X GET 'https://example.com/ai/providers'{ "items": [ { "id": "string", "kind": "anthropic", "display_name": "string", "base_url": "string", "key_hint": "string", "capabilities": [ "chat" ], "capabilities_editable": true, "enabled": true, "max_concurrency": 0, "last_checked_at": "2019-08-24T14:15:22Z", "last_error_code": "string", "created_at": "2019-08-24T14:15:22Z", "updated_at": "2019-08-24T14:15:22Z" } ]}Checks the key and URL by listing the provider's models before saving; a failed check returns ai.provider_check_failed with the reason. Not for agents.
semestra_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.
application/json- body
kind*KindProvider type.
"anthropic""anthropic_compatible""openai""openai_compatible""openai_responses""gemini""ollama"display_name?|Name shown in the list; defaults to the type.
base_url?|API base URL; required for the compatible kinds and ollama.
api_key?|API key (stored encrypted).
capabilities?array<>|What the endpoint supports; only for the compatible kinds and ollama.
Successful Response
application/json- response
id*Idkind*Kind"anthropic""anthropic_compatible""openai""openai_compatible""openai_responses""gemini""ollama"display_name*Display Namebase_url*string|nullkey_hint*string|nullcapabilities*array<>capabilities_editable*Capabilities Editableenabled*Enabledmax_concurrency*integer|nulllast_checked_at*|nulllast_error_code*string|nullcreated_at*Created Atdate-timeupdated_at*Updated Atdate-timecurl -X POST 'https://example.com/ai/providers' \ -H 'Content-Type: application/json' \ -d '{ "kind": "anthropic"}'{ "id": "string", "kind": "anthropic", "display_name": "string", "base_url": "string", "key_hint": "string", "capabilities": [ "chat" ], "capabilities_editable": true, "enabled": true, "max_concurrency": 0, "last_checked_at": "2019-08-24T14:15:22Z", "last_error_code": "string", "created_at": "2019-08-24T14:15:22Z", "updated_at": "2019-08-24T14:15:22Z"}A new key or base URL is checked again before saving. Not for agents.
semestra_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.
id*IdProvider id.
application/json- body
display_name?|New name.
base_url?|New base URL.
api_key?|New API key; the provider is checked again before saving.
capabilities?array<>|New capabilities (compatible kinds and ollama only).
enabled?|Turn the provider on or off.
max_concurrency?|Most requests sent to the provider at once; null for the default (4).
Successful Response
application/json- response
id*Idkind*Kind"anthropic""anthropic_compatible""openai""openai_compatible""openai_responses""gemini""ollama"display_name*Display Namebase_url*string|nullkey_hint*string|nullcapabilities*array<>capabilities_editable*Capabilities Editableenabled*Enabledmax_concurrency*integer|nulllast_checked_at*|nulllast_error_code*string|nullcreated_at*Created Atdate-timeupdated_at*Updated Atdate-timecurl -X PATCH 'https://example.com/ai/providers/string' \ -H 'Content-Type: application/json' \ -d '{}'{ "id": "string", "kind": "anthropic", "display_name": "string", "base_url": "string", "key_hint": "string", "capabilities": [ "chat" ], "capabilities_editable": true, "enabled": true, "max_concurrency": 0, "last_checked_at": "2019-08-24T14:15:22Z", "last_error_code": "string", "created_at": "2019-08-24T14:15:22Z", "updated_at": "2019-08-24T14:15:22Z"}Not for agents.
semestra_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.
id*IdProvider id.
Successful Response
application/json- response
id*Idcleared_purposes*array<>curl -X DELETE 'https://example.com/ai/providers/string'{ "id": "string", "cleared_purposes": [ "chat" ]}Cached for an hour. Not for agents.
semestra_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.
id*IdProvider id.
Successful Response
application/json- response
items*array<>manual_entry*Manual Entrycurl -X GET 'https://example.com/ai/providers/string/models'{ "items": [ { "id": "string", "display_name": "string" } ], "manual_entry": true}Records the result on the provider. Not for agents.
semestra_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.
id*IdProvider id.
Successful Response
application/json- response
ok*Okerror_code*string|nullchecked_at*Checked Atdate-timecurl -X POST 'https://example.com/ai/providers/string:test'{ "ok": true, "error_code": "string", "checked_at": "2019-08-24T14:15:22Z"}The frontend enables or greys out AI features with it. Not for agents.
semestra_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.
Successful Response
application/json- response
items*array<>local?array<>curl -X GET 'https://example.com/ai/status'{ "items": [ { "purpose": "chat", "available": true, "source": "assignment", "provider_id": "string", "provider_kind": "anthropic", "provider_name": "string", "model": "string" } ], "local": [ { "purpose": "ocr", "models": [ "string" ], "default": "string", "downloaded": [ "string" ], "sizes": { "property1": 0, "property2": 0 }, "downloading": [ "string" ], "download_job": "string", "custom": false } ]}Defaults to all time; days or start/end narrow it. Not for agents.
semestra_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.
days?|How many days back to summarise, today included; omit for all time.
start?|First local day to summarise; overrides days.
end?|Last local day to summarise (inclusive); defaults to today.
tz?TzIANA time zone for day buckets.
"UTC"Successful Response
application/json- response
since*Sincedate-timeuntil*Untildatetotals*cost_complete*Cost Completeby_day*array<>by_purpose*array<>by_module*array<>by_model*array<>curl -X GET 'https://example.com/ai/usage'{ "since": "2019-08-24T14:15:22Z", "until": "2019-08-24", "totals": { "calls": 0, "errors": 0, "input_tokens": 0, "cached_tokens": 0, "output_tokens": 0, "cost_usd": 0 }, "cost_complete": true, "by_day": [ { "date": "2019-08-24", "purpose": "chat", "calls": 0, "input_tokens": 0, "output_tokens": 0, "cost_usd": 0, "cost_complete": true } ], "by_purpose": [ { "calls": 0, "errors": 0, "input_tokens": 0, "cached_tokens": 0, "output_tokens": 0, "cost_usd": 0, "key": "string", "cost_complete": true } ], "by_module": [ { "calls": 0, "errors": 0, "input_tokens": 0, "cached_tokens": 0, "output_tokens": 0, "cost_usd": 0, "key": "string", "cost_complete": true } ], "by_model": [ { "calls": 0, "errors": 0, "input_tokens": 0, "cached_tokens": 0, "output_tokens": 0, "cost_usd": 0, "key": "string", "cost_complete": true } ]}