CONNECT

API reference

Peridot’s API lets your systems do what a registry or HR team would otherwise do by hand: enrol learners and collect their results. Every call is authenticated with an API key and only ever sees your organisation’s data. PERIDOT in the examples stands for the address you use for Peridot.

Authentication

Send Authorization: Bearer pk_… with every request. Request bodies are JSON with Content-Type: application/json. Courses can be named by id or by code, and spaces don’t matter: CSC111 and CSC 111 are the same course.

Enrol a learner

POST /v1/courses/ followed by the course and /enrolments enrols one learner by their matric or staff number and returns a launch_url that takes them straight into the course.

Enrol Daniel Cole in CSC 111

POST /v1/courses/CSC111/enrolments
Authorization: Bearer pk_7Hq2…
Content-Type: application/json

{ "student": { "id": "LCU/2026/0777", "name": "Daniel Cole" } }

201 Created
{ "id": "enr_…", "launch_url": "https://…/l/e_…", … }

Enrolling from your student records system. The learner follows the launch link; results come back by webhook or by fetching them.

Fetch results

GET /v1/results returns lab results, newest changes last. Filter by course, offering_id or student; page with limit and since. Pass the next_since from one answer as since in the next to get only what changed.

Results for CSC 111 changed since the last fetch

GET /v1/results?course=CSC111&since=2026-11-09T08:00:00Z&limit=100
Authorization: Bearer pk_7Hq2…

200 OK
{ "data": [
    { "student": "LCU/2026/0412", "name": "Daniel Cole", "course": "CSC 111",
      "offering_id": "off_…", "version": 3, "lab": "csc111-3.2",
      "status": "passed", "passed": true, "score": 1, "attempt": 1,
      "tasks": { "done": 4, "total": 4 },
      "started_at": "…", "completed_at": "…", "updated_at": "…" } ],
  "next_since": "…" }

Webhooks

Method	Path	Does
`GET`	`/v1/webhooks`	Lists your webhooks.
`POST`	`/v1/webhooks`	Adds one: `url` (HTTPS) and `events`. Returns the secret once.
`GET`	`/v1/webhooks/{id}/deliveries`	Every delivery and its tries.
`DELETE`	`/v1/webhooks/{id}`	Stops deliveries; the log is kept.

Events, payloads and signatures are on Webhooks.

Errors

Errors come back with a 4xx or 5xx status and a JSON body with an error message. 401 means the key is missing, wrong or revoked; 404 means the course, offering or webhook isn’t in your organisation; 400 means the body is missing something, such as a webhook URL that isn’t HTTPS.