Getting started

The catalog endpoints are anonymous, so you can start without registering.

1. Pick a program

curl 'https://api.hfu.digital/v1/starplan/programs?search=informatik'

{
  "data": [
    {
      "id": "8b7c…",
      "name": "Allgemeine Informatik",
      "shortName": "AIB",
      "degreeType": "B.Sc.",
      "facultyId": "f1…",
      "isActive": true,
      "createdAt": "2024-09-01T00:00:00.000Z",
      "updatedAt": "2026-04-12T08:13:42.117Z"
    }
  ]
}

2. List its semesters

curl https://api.hfu.digital/v1/starplan/programs/<programId>/semesters

3. Get the timetable for the current ISO week

curl https://api.hfu.digital/v1/starplan/week/current

The response shape is:

{
  "week": "2026-W17",
  "dateRange": {
    "start": "2026-04-20T00:00:00.000Z",
    "end":   "2026-04-26T23:59:59.999Z"
  },
  "occurrences": [ /* CourseKit Occurrence shape */ ]
}

You can filter by instructorIds, roomIds, courseIds, groupIds (comma-separated UUID lists). See Week endpoints.

https://api.hfu.digital/v1/starplan/ical/<semesterId>

That URL serves text/calendar; charset=utf-8 with a 10-minute public cache and a 365-day horizon. Drop it directly into Apple Calendar, Google Calendar, Thunderbird, etc. See iCal endpoints.

5. (Optional) Register an API key for webhooks and usage stats

The catalog, week, iCal, and change endpoints work without a key. To create webhooks or call /developers/* routes, register once:

curl -X POST https://api.hfu.digital/v1/starplan/developers/register \
  -H 'Content-Type: application/json' \
  -d '{"email":"you@example.com","name":"My Integration"}'

{
  "data": {
    "id": "c0a8…",
    "email": "you@example.com",
    "name": "My Integration",
    "apiKey": "spk_AbCd1234…",
    "apiKeyHint": "AbCd",
    "createdAt": "2026-04-26T12:00:00.000Z"
  },
  "message": "Save your API key securely — it will not be shown again."
}

The raw apiKey is shown once, on this single response. The server only stores a bcrypt hash plus the last 4 characters as a hint. If you lose it, call POST /v1/starplan/developers/regenerate-key (which itself requires the current key, so don't lose track until you've stored a copy).

Subsequent calls send the key in the X-API-Key header:

curl https://api.hfu.digital/v1/starplan/developers/me \
  -H 'X-API-Key: spk_AbCd1234…'

Next steps

Authentication — when you need a key and when you don't.
Catalog endpoints — full reference for programs/courses/rooms/instructors.
Webhooks — push notifications for change events.
Migration from splan-api — if you used the legacy host.