Ksiopea · Integration

Timetable API

Read the timetable Ksiopea generates, so a school's management system and other tools can consume it without personal credentials. Read-only, per school, versioned. The contract is OpenAPI 3.1: import it into Postman, Insomnia or a client generator, and the backend is built against that same document.

Download the OpenAPI contract Let's talk integration

Specification · integration draft

AuthenticationPer-school API key

Each school generates its key from the admin panel. It is shown once and stored hashed; read-only scope, revocable at any time. It is sent in the header:

Authorization: Bearer ksio_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxx

For integration testing, sandbox keys (ksio_test_...) are issued against a sample school.

Base and versioningStable routes

Production: https://api.ksiopea.com/v1
Testing: https://sandbox.api.ksiopea.com/v1

A breaking change bumps the route version (/v2); /v1 is never broken silently.

ResourcesEndpoints

Method	Path	Returns
GET	`/center`	School metadata (name, stages, active year).
GET	`/schedules`	Published timetables.
GET	`/schedules/{sid}`	Header + period frames (daily bells).
GET	`/schedules/{sid}/groups`	Groups with their code.
GET	`/schedules/{sid}/teachers`	Teachers with their code (idnumber/nick).
GET	`/schedules/{sid}/rooms`	Rooms with their code.
GET	`/schedules/{sid}/subjects`	Subjects with their code.
GET	`/schedules/{sid}/timetable`	With no filter, the full timetable; with `group`, `teacher` or `room`, that entity. `format=cifra` returns Cifra codes.
GET	`/schedules/{sid}/ics`	Subscribable ICS feed (Google/Microsoft).

Use current as the sid for the timetable in force, without listing.

ExampleA group's timetable

curl "https://api.ksiopea.com/v1/schedules/sched_2526_def/timetable?group=3esoA" \
  -H "Authorization: Bearer ksio_live_xxxx"

{
  "schedule_id": "sched_2526_def",
  "entity": { "id": "3esoA", "code": "3ESOA", "name": "Year 9 A" },
  "sessions": [
    {
      "day": 2, "slot": 2, "start": "09:55", "end": "10:50",
      "subject": { "id": "MAT", "name": "Mathematics" },
      "teacher": { "id": "a1b2", "code": "P034", "name": "Teacher 34" },
      "room":    { "id": "r12",  "code": "12",   "name": "Room 12" },
      "kind": "class"
    }
  ]
}

Periods follow the group's frame (bells offset between stages are already resolved). No student data is exposed.

FormatsAny SIS · Cifra and ICS

The native format is the general one and serves any management system. format=cifra is just a convenience to reconcile with that SIS, not an exclusive integration.

format=cifra: identifiers come out as the Cifra export codes (teacher/group/subject/frame), to reconcile without translating.
ICS feed: subscribable URL per group/teacher/room; each class is a weekly recurring event through the year, with an ETag and regeneration when a new timetable is published.

ErrorsResponses

Errors come as { "error": { "code", "message" } } with the matching HTTP status:

HTTP	code	When
401	`unauthorized`	Key missing or invalid.
403	`forbidden`	Key revoked or out of scope.
404	`not_found`	Resource does not exist.
400	`bad_request`	Invalid parameters.
429	`rate_limited`	Per-key limit; retry per `Retry-After`.

IntegrateFirst steps

Download the OpenAPI contract and import it into your tool (Postman, Insomnia, Swagger UI, or a client generator).
Request sandbox access: we give you a ksio_test_... key and a sample school to validate the integration.
Once the contract fits your side, we move to production with the real school's key.