## 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](https://docs.institflow.com/en/guides/conventions#pagination)) cheap.

On top of the REST surface, three integration surfaces exist for building on Institflow without a human in the loop: [webhooks](https://docs.institflow.com/en/webhooks) (get told when something happens), the [registration widget](https://docs.institflow.com/en/widget) (embed a lead-capture form on any site), and an [MCP server](https://docs.institflow.com/en/mcp) (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:

```bash
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](https://docs.institflow.com/en/guides/self-hosting)) 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](https://docs.institflow.com/en/guides/self-hosting)). 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](https://docs.institflow.com/en/guides/conventions#multi-tenancy) for how isolation works within your own tenant).

> **No public sandbox**
>
> There is no shared public sandbox. To try the API, run the self-hosted bundle locally — it gives you a real, isolated tenant to build against, and nothing you do there is visible to anyone else.