11.5 API & Webhooks Docs

This feature is available only for Enterprise Plan

The Docs tab, under Settings → API & Webhooks → Docs, is the technical manual for the EdisonOS API and webhooks. The other two tabs are where you click buttons to set things up; this is where the technical details live.

What the Docs tab is

The Docs tab is read-only and built into the product, so it always matches the current version of the system there's no separate docs site to keep in sync.

It's written for whoever is building the integration: an in-house developer, a contractor, an agency, or whoever maintains your Zapier/Make/n8n flows. As the Owner or Admin, you don't need to read it cover-to-cover. Your job is to know what's in there so you can point your developer to the right section.

How it's organised

The page has a sidebar on the left and a scrollable main panel. The sidebar has two sections:

API Reference - sending data to EdisonOS.
Webhooks Reference - receiving data from EdisonOS.

Click any subtopic in the sidebar to jump to that part of the docs.

API Reference

Subtopic	What it covers
Base URL	The single web address all API requests go to: `https://gateway.edisonos.com`. All traffic is HTTPS.
Authentication	How to pass the access token using the `X-API-Key` header, and what each token status (Active / Paused / Revoked) means.
Errors	The standard JSON error format (`message`, `error_code`, `details`) and the full list of error codes — `VALIDATION_ERROR`, `UNAUTHORIZED`, `FORBIDDEN`, `ACADEMY_NOT_FOUND`, `RATE_LIMIT_EXCEEDED`, `INTERNAL_ERROR`.
Endpoints	The actual actions available. Currently one: `POST /students/enroll`.

The Endpoints subtopic for POST /students/enroll includes:

Request body - a students array of 1–50 objects, each with full_name, email, and programs.
Program labels - sat, act, psat_nmsqt, psat_10, psat_8_9, shsat, isee, ssat, ap_us_history, ap_physics_1.
Example request and response as copy-paste JSON.
Behavior notes - existing students (matched by email) get enrolled into any new programs, duplicates are skipped, and the whole batch fails if any single student is invalid.

Webhooks Reference

Subtopic	What it covers
Overview	How webhook delivery works at a high level.
Events	The events you can subscribe to. Currently `assessment.summary`.
Delivery	The headers EdisonOS sends with each webhook, the retry policy (6 attempts, 2s→5min backoff), the 10-second timeout, and what status codes your server should return.
Verifying Signatures	The exact format of `X-Edison-Signature` and step-by-step verification, with Python and Node.js code samples ready to copy.
Payload Format	The full JSON structure of `assessment.summary`, field by field with student info, assessment metadata, summary scores, section breakdowns, per-question results with timing and tags.
Best Practices	Four practical tips: respond quickly with `2xx`, deduplicate using `X-Event-Id`, always verify signatures, and avoid logging student personal data.

Handing off to a developer

A clean handoff usually looks like this:

In the API tab, create an access token named for the project (e.g. enrollment-sync-prod). Copy the value once and save it in your password manager.
In the Webhooks tab, add the webhooks you need. Copy each signing secret once.
Share the token and signing secrets with your developer through a secure channel includes password manager, encrypted vault, or short-lived secure note. Don't use email or chat.
Send them the link to the Docs tab. Everything else they need is in there.

For staging vs production, create separate tokens and webhooks per environment (-staging, -prod). Never share tokens across environments.

If your developer hits something the Docs tab doesn't cover, contact EdisonOS support with the request method, path, request body (with the token redacted), and the response. That's usually enough for us to help quickly.