StarPlan API

The StarPlan API is the public, read-only HTTP API for HFU timetable data — programs, semesters, courses, rooms, instructors, schedules, and change events. It is mounted under https://api.hfu.digital/v1/starplan/*.

What it gives you

• Catalog — list and inspect every program, semester, course, room, and instructor at HFU.
• Schedules — fetch week-by-week occurrences, room schedules, and per-instructor course lists.
• iCal feeds — drop-in .ics URLs per semester that any calendar app can subscribe to.
• Change events — query the change log to see what was added, updated, or removed.
• Webhooks — receive HMAC-signed HTTP push notifications when StarPlan data changes.

Sections

Base URL

https://api.hfu.digital

All endpoints documented here are prefixed with /v1/starplan. The legacy splan.dev.hfu.digital/api/v1/* host is retired — see Migration from splan-api.

Quickstart

# Anonymous — no key needed
curl https://api.hfu.digital/v1/starplan/programs

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

# Current ISO week occurrences
curl https://api.hfu.digital/v1/starplan/week/current

To create webhooks or read your usage stats, you'll need an API key:

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

The response includes a one-time apiKey — store it securely. Then send it as X-API-Key on subsequent dev/webhook calls. See Authentication.

Response envelope

Most endpoints return JSON wrapped in a data envelope:

{ "data": [ /* … */ ] }

Mutating endpoints (developer registration, webhook creation, etc.) may also include a message field with a human-readable status note. Errors use a different envelope — see Errors.

What's not here

The StarPlan API exposes only public, read-only HFU timetable data plus the developer-key and webhook surfaces that go with it. Personal calendar feeds (per-user iCal at /ical/:feedToken), authoring tools, sync jobs, and Discord/web integrations are part of the internal api/ service and are not part of the public StarPlan contract.