Skogviken TIOS API Docs

Overview & Authentication

The Skogviken TIOS API is a Node.js/Express service backed by MongoDB. It tracks live train positions, timetables, station arrivals/departures, disruptions, announcements, GSM-R radio numbers, and station staffing status for the Skogviken TIOS network.

Base URL

https://api.tios.sk.polartracks.no

Protected endpoints accept either the master API key or a scoped API token. Public endpoints do not require authentication. The /status health check is public, as are read endpoints such as arrivals and departures.

For master-key access, pass the API key in the key request header:

key: <YOUR_API_KEY>

Scoped tokens use the standard bearer authorization header:

Authorization: Bearer <YOUR_TOKEN>

Bearer tokens can only access resources/actions granted in their permissions. Missing, expired, revoked, or invalid credentials receive 401 Unauthorized; a valid token without the required permission receives 403 Forbidden. Token management endpoints require the master key and do not accept bearer tokens.

Permission examples

• trains:read grants read access to train endpoints.
• fido:write grants write access to FIDO endpoints.
• *:read grants read access across resources; * grants all access.

Response Conventions

• All responses are JSON (Content-Type: application/json), except 204 No Content responses, which have no body.
• GET endpoints return 200 OK with the requested object, or an array for list endpoints. Lists with no matches return [], not an error. Single-item lookups return 404 when the item doesn't exist.
• POST create endpoints return 201 Created with the new object; PATCH/PUT return the updated object; DELETE returns 204 No Content.
• Documents stored in MongoDB include _id and __v. Some endpoints also add an id string copy of _id.
• Dates are UTC ISO 8601 strings (e.g. 2026-10-08T06:00:00.000Z) unless an endpoint says it returns Norway local time. Scheduled times in defaultRoute are { "hours", "minutes" } objects in Norway local time.
• Errors are { "error": "message" }; see Error Responses.
• Request bodies must be sent as JSON with Content-Type: application/json.

Rate Limits

All endpoints, including public ones, are rate limited per one-minute window. The limit depends on how the request is authenticated:

When the limit is exceeded, the API responds with 429 Too Many Requests and the body:

{ "error": "Too many requests" }

Every response includes the standard RateLimit-Limit, RateLimit-Remaining, and RateLimit-Reset headers so clients can track their remaining quota. Counters are held in memory and reset when the API restarts.

Sections