Precept API for developers

Get a key

The program director signs in to Precept and opens Program › Settings › API access. Give the key a name, like the system that will use it, and choose read only or read and add students. The key is shown once, so copy it then. Precept keeps only a scrambled copy and can't show it again.

You can turn a key off at any time from the same place. Anything using it stops working right away.

Keys never see sign-ins, uploaded documents, shift narratives, patient details or billing.

Make a request

Send the key in the Authorization header. Every answer is JSON.

curl https://precept.squidskull.com/api/v1/students \
  -H "Authorization: Bearer prc_your_key_here"

Request	What it returns
`GET /api/v1/program`	The program name, its classes, every requirement with its minimum and simulation allowance, and when the records were last saved.
`GET /api/v1/students`	Each student: class, email, signed shifts, hours, shifts waiting to be signed, requirements met, and percent complete.
`GET /api/v1/counts`	Each student's count for every requirement: logged, simulation, what counts toward the minimum, the minimum, and whether it is met.
`GET /api/v1/shifts`	Signed shifts: student, date, site, hours, preceptor, number of patients and the signed record code. Add `?since=2026-08-01` to get only newer ones.
`GET /api/v1/exams`	Exam and quiz scores with the cut score and whether the student passed.
`POST /api/v1/students`	Adds students to the roster. Needs a read-and-write key.

Adding students

curl -X POST https://precept.squidskull.com/api/v1/students \
  -H "Authorization: Bearer prc_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"students": [{"name": "Jordan Lee", "class": "Fall 2026", "email": "jordan.lee@college.edu"}]}'

Send up to 100 students at a time. class is the class name or id from /api/v1/program; leave it out to use the program's first class that is still running. A name already on the roster is refused. New students go on the roster the next time someone in the program opens Precept, then the director sends each one their sign-in link.

Counts follow the program's rules

The counted number in /counts is what counts toward the minimum. It follows the same rule as the app: simulation only counts up to the share of the minimum the program allows.

Errors

401: no key, or the key is wrong or turned off.
403: a read-only key tried to add students.
404: no such endpoint.
503: Precept could not reach its database. Try again in a minute.

Every error answer has an error field that says what went wrong in plain words.

Questions