API reference

Automate EduShell from your own tools. The API is a REST interface over HTTPS, authenticated with organisation API keys.

Base URL

All API requests go to the versioned base URL over HTTPS:

bash

https://edushell.app/api/v1

Requests and responses are JSON. Send on requests that carry a body.

Authentication

Authenticate with an API key. Create one in Administration > API keys; the full key is shown once, at creation, and looks like . Store it as a secret. A key carries a role ( or ) and acts within the organisation that issued it.

Send it as a Bearer token on every request:

bash

curl https://edushell.app/api/v1/me \
  -H "Authorization: Bearer esk_your_key_here"

A missing, malformed or revoked key returns . Revoke a key at any time from the same screen; it stops working immediately.

Treat an API key like a password: it acts with the role you gave it, across your whole organisation. Never put it in client-side code, a public repository or a URL. If one leaks, revoke it and issue a new one.

Conventions

HTTPS only. Plain HTTP is not served.
JSON everywhere. Bodies are JSON; timestamps are ISO 8601 in UTC (for example ); identifiers are UUIDs.
Methods. reads, creates, updates, removes.
Scope. A key is bound to its organisation; you never pass credentials for another org, and cannot read across orgs.

Errors

Errors use standard HTTP status codes and a consistent JSON envelope:

json

{
  "error": {
    "code": "unauthorized",
    "message": "invalid or revoked API key"
  }
}

Status	Meaning
400	The request was malformed
401	Missing, invalid or revoked key
403	The key's role may not do this
404	No such resource in your org
409	Conflict, for example a name already taken
429	Rate limited, slow down

Rate limits

Requests are rate limited per caller. When you exceed the budget the API returns with the standard error envelope; back off and retry. Budgets are generous for normal automation; if you are batch-importing, add a short pause between calls rather than retrying a 429 immediately.

Endpoints

The API mirrors what the console does. The most useful endpoints:

Method and path	What it does
	The authenticated principal and its org
	List members
	Change a member's role
	Remove a member
	The organisation activity log
and	List or create sessions
and	Read or delete a session
	Rotate the join code
and	List or create labs
	List a lab's versions
	Manage API keys
	Manage webhook endpoints

Every path is relative to the base URL. IDs are UUIDs returned by the list endpoints.

Want to react to changes instead of polling? Subscribe to webhooks and EduShell will POST signed events to your endpoint.