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 campus data or deterministic campus calculations across supported universities without private student context.

No API key or Gapwise account is required.
Covers universities, campuses, 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.
Official SDKs are published for JavaScript/TypeScript and Python.

Start the public API quickstart ↓ · API overview · SDKs

Gapwise AI & MCP

Use Gapwise AI when a compatible remote MCP client needs deterministic public campus intelligence across 13 supported universities, 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
Twelve stateless public campus tools do not require private Gapwise account context.
Thirteen private tools require explicit delegation and the relevant permissions (twelve reads and one write).
Private access is permissioned, minimized, revision-aware, and revocable.
Academic timetable meetings are read-only through the AI boundary.
The live service currently exposes 30 tools total: 17 public + 13 private.

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.

Discover supported universities & campuses

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

Gapwise supports 13 Canadian universities and 15 campus models. Query parameters university (default uoft) and campus (default utm) scope building and routing calls.

List campus buildings

List buildings for Carleton University:

curl 'https://api.gapwise.ca/v1/buildings?university=carleton&limit=10'

Or query UTM (default):

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

Calculate a route at Carleton University (from Tory Building to Mackenzie Building):

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

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

Both first-party SDK implementations are published and target the same canonical v1 contract. The JavaScript/TypeScript implementation is distributed through npm and JSR; Python is distributed through PyPI.

JavaScript / TypeScript (npm):

npm install @gapwise/sdk@0.1.2

JavaScript / TypeScript (JSR / Deno):

deno add jsr:@gapwise/sdk@0.1.2

Python:

python -m pip install gapwise==0.1.1

The Python release was independently clean-installed and exercised against the production API. Registry publishing uses trusted OIDC workflows rather than long-lived release tokens where supported.

For common integration patterns, continue to Recipes.

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