Skip to content
Flux Developer Portal

API guide

Everything you need to know before your first request: getting credentials, how calls are authorized, what errors look like and how the API changes over time. The exact fields of every operation are in the API reference.

Version 1Credentials required

Who the API is for

The API is for applications built by other developers, such as a school's own engineer or a company building a tool for schools, that work with a school's directory data: the roster, calendar, menus, notices, documents, polls, permission slips, organizations and staff. It serves exactly what a signed-in person could see or do in Flux Student Directory itself. School administration (roster management, access and roles, school settings) is not part of it.

Getting access

There is no anonymous access and no self-service sign-up. Credentials for your application are issued by Flux. Write to flux-support@fluxstudentdirectory.com and tell us:

  • who you are and what you are building;
  • which school or schools it is for, and whether the school has agreed;
  • which parts of the reference you expect to use, read-only or also writes.

We reply with what you need to obtain and renew access tokens for the people who use your application. Please do this before you start building.

How calls are authorized

Every request carries the access token of one real user of Flux Student Directory:

Authorization: Bearer <token>

The response contains only what that user may see, and a write succeeds only if that user may make it. A parent's token cannot read another family's private notes or lists, and a user who belongs to two schools sees each school separately. Your application is never more powerful than the person it acts for.

  • Treat tokens as secrets. Keep them on your server where you can, never log them or put them in a URL, and discard them when the user signs out.
  • Tokens expire. A 401 means get a fresh one and retry once.
  • A user who has set up two-step verification and has not completed it for this session gets 401 with the code mfa_required. Ask for the verification code, complete it, and retry.

Your first request

All paths are relative to https://studentdirectory.app/api/v1. Start with GET /me: it lists the user's schools and roles, and the school identifiers every other call needs.

curl https://studentdirectory.app/api/v1/me \
  -H "Authorization: Bearer $FLUX_TOKEN" \
  -H "Accept: application/json"

Then call, for example, GET /schools/{schoolId}/students for the roster or GET /schools/{schoolId}/menus/week for lunch.

Errors

Every error has the same shape:

{ "error": { "code": "not_authorized", "message": "You don't have access to this school." } }

Switch on code, which is stable (for example not_authenticated, not_authorized, not_found, validation_failed, mfa_required). message is for people and may be shown to the user, but do not parse it. The HTTP status follows the usual meaning: 400 bad request, 401 missing, expired or invalid token, 403 this user may not do this, 404 not found.

404 can also mean “exists, but not visible to you”. The API does not confirm that something exists to someone who may not see it. If a 404 surprises you, check the user's access before assuming the item was deleted. A feature a school has turned off also answers 404.

Working with the data

  • No pagination. List operations return the complete result for the school. A roster of a thousand students is still one response. Optional paging may be added later without a new API version, so do not depend on getting everything in one call forever.
  • Photos are not in the JSON. Photo operations give you a signed address that works for about five minutes. Download the image right away and do not store or share the address; ask again when you need it.
  • Rich text. Notices, documents and descriptions may contain formatted text and embedded images. Embedded images are references that you resolve through the API like photos.
  • Dates and times. A date without a time is a calendar date at the school. A timestamp is in UTC; show it in the school's time zone (see the school's features) rather than the viewer's.
  • Be gentle. There is no published rate limit, but cache what rarely changes (the roster, staff, menus) and do not poll every few seconds.

People's information

The data describes children and their families. Use it only for the purpose you agreed with Flux and the school, show a person only what that person is entitled to see, and delete what you no longer need. Our Privacy Policy describes how the product itself handles this data.

Versioning

  • The path starts with /v1. New operations, new optional request fields and new response fields are added without a new version, so ignore response fields you do not recognize.
  • A breaking change (removing or renaming a field, changing a type or meaning, removing an operation) gets a new /v2, and /v1 keeps running until clients have moved.
  • The openapi.yaml file always matches the reference. Generate a client from it if you like.

AI assistants

To let an AI assistant read this data, use the MCP server. Coding agents can start from llms.txt.