Developer quickstart

Gapwise has two developer surfaces with different privacy boundaries. Start by choosing the one your integration actually needs.

Choose your integration

Public API & SDKs

Use the public platform when you need canonical UTM campus data or deterministic campus calculations without private student context.

No API key or Gapwise account is required.
Covers buildings, places, routing, and route-aware planning for an explicit free interval you provide.
Does not expose student timetables, accounts, friends, private sync state, credentials, or precise live location.

Start the public API quickstart ↓ · API overview · SDKs

Gapwise AI & MCP

Use Gapwise AI when a compatible remote MCP client needs explicitly delegated private Gapwise context or bounded personal actions.

Remote MCP resource: https://ai.gapwise.ca/api/mcp
OAuth protected-resource metadata: https://ai.gapwise.ca/.well-known/oauth-protected-resource
Private access is permissioned, minimized, revision-aware, and revocable.
Academic timetable meetings are read-only through the AI boundary.
The live service currently exposes 13 permissioned tools.

Open the AI & MCP guide → · Connect an AI client → · Review privacy & security

Public API quickstart

Gapwise’s canonical public API requires no API key. The production base URL is https://api.gapwise.ca/v1.

Inspect API capabilities

curl https://api.gapwise.ca/v1

The root response reports the API version, campus data versions, supported capabilities, authentication mode, and privacy boundary.

List UTM buildings

curl 'https://api.gapwise.ca/v1/buildings?q=instructional&category=academic'

Collections return a deterministic page in data and pagination metadata in meta.pagination. Use limit and offset to page through results.

Find campus places

curl 'https://api.gapwise.ca/v1/places?building=HM&openNow=unknown'

Availability is explicitly open, closed, or unknown. Never treat unknown as closed.

Calculate a route

curl -X POST https://api.gapwise.ca/v1/routes \
  -H 'content-type: application/json' \
  -d '{"from":"MN","to":"IB"}'

Route results are building-level campus routes. Inspect the returned status, accuracy, verification state, and warnings instead of assuming every requested route is fully verified.

Plan a gap

curl -X POST https://api.gapwise.ca/v1/gaps/plan \
  -H 'content-type: application/json' \
  -d '{"from":"MN","to":"IB","term":"Fall","weekday":"Wednesday","startTime":660,"endTime":780}'

Gap planning evaluates only the explicit free interval you send. The public API does not retrieve or accept a private student timetable.

Response envelope

Successful responses use:

{
  "data": {},
  "meta": {
    "apiVersion": "v1",
    "requestId": "..."
  }
}

Errors use:

{
  "error": {
    "code": "building_not_found",
    "message": "Campus building not found."
  },
  "meta": {
    "apiVersion": "v1",
    "requestId": "..."
  }
}

See Errors for the canonical failure model and Rate limits for retry guidance.

SDKs

@gapwise/sdk@0.1.0 is published on npm with provenance and can be installed now:

npm install @gapwise/sdk@0.1.0

The Python gapwise client is implemented at version 0.1.0 but is still awaiting its first verified PyPI release. Until that release and clean-install verification complete, use the public HTTPS API or the Python client directly from the Gapwise repository rather than assuming pip install gapwise is available.

For common integration patterns, continue to Recipes.

The authoritative machine-readable contract is https://api.gapwise.ca/openapi.json.