Introduction

Overview#

The Institflow API is a resource-oriented REST API for every part of running a school or training institute: people (students, guardians, staff), academics (courses, teaching groups, enrollments, sessions), attendance, assessment (exams, grades, progress reports), billing (invoices, payments), notifications, and administration (members, roles, settings, branches). It speaks JSON only, uses plural resource nouns (/students, /invoices), and every id is a UUID v7 — sortable by creation time, which also makes cursor pagination (see Conventions) cheap.

On top of the REST surface, three integration surfaces exist for building on Institflow without a human in the loop: webhooks (get told when something happens), the registration widget (embed a lead-capture form on any site), and an MCP server (let an AI agent operate the system with real, scoped permissions).

Base URL#

Every endpoint in this reference lives under /api/v1. Institflow is sold self-hosted only, so there is no shared vendor origin to call: the base URL is your own institute's Institflow address — the host you (or your users) already sign in on. If you don't know it, ask your administrator; never assume a domain, including the one below, which is only a placeholder:

https://your-institute.example/api/v1/students

There is no per-tenant subdomain and no shared multi-tenant hostname: each self-hosted install (see Self-hosting & licensing) answers only for its own institute, at whatever host it was deployed on — a bare domain, a verified custom domain, or an internal address, depending on how the institute set it up. The tenant is resolved from the credential you authenticate with (an API key or a JWT is always bound to exactly one tenant), never from the hostname.

Versioning#

The API is versioned in the URL path (/api/v1), not by header or query parameter. Within a version line, changes are additive and backwards-compatible: new optional request fields, new response fields, new endpoints, new enum values you should already be tolerant of. A breaking change would ship as /api/v2 — there is only one version today.

Deployment#

Institflow ships as a single-tenant Docker bundle you run on your own server, gated by a signed license (see Self-hosting & licensing). There is no vendor-hosted, multi-tenant alternative — your institute's data and API stay on infrastructure you control, and data isolation from any other institute's install is physical, not just enforced in software (see Multi-tenancy for how isolation works within your own tenant).