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. In the cloud, every institute calls the same origin — there is no per-tenant subdomain. 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:

https://api.institflow.com/api/v1/students
https://ims.your-institute.org/api/v1/students

The second line is either a verified custom domain (the institute points its own domain at Institflow; nothing else about the request changes) or a self-hosted deployment (see Self-hosting & licensing) serving the same API at whatever host you run it on — the request/response shapes are identical in all three cases.

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.

Environments#

There are two deployment modes, sharing one codebase and one API contract:

• Cloud — multi-tenant, hosted for you. Each institute gets its own tenant (data isolation is enforced at the database and application layer — see Multi-tenancy), reachable at the shared https://api.institflow.com origin or a verified custom domain — never a per-tenant subdomain.
• Self-hosted — a single-tenant Docker bundle you run on your own server, gated by a signed license. Functionally identical to cloud; only the infrastructure and billing surface differ.