Authentication

API Keys

All REST API calls require a Bearer token:

Authorization: Bearer edp_live_<your-key>

Generate API keys in your Edpire dashboard under Integrations → API Keys.

Scopes

Each API key can be granted one or more scopes:

Scope	Grants access to
`read:assessments`	List/fetch assessments, collections, webhooks. Grade single questions via `/check`.
`write:assessments`	Create/update assessments, manage collections, register webhooks, mint embed tokens.
`read:results`	Fetch submissions, learner results, assessment results, collection results.
`write:submissions`	Submit answers for server-side grading via `POST /assessments/{id}/submit`.

Grant the minimum scopes your integration needs.

Rate Limits

Limits are applied per API key, on a rolling 60-second window:

Endpoint	Limit
All REST endpoints (default)	300 requests / minute
`POST /assessments/{id}/submit`	100 requests / minute
`POST /assessments/{id}/check`	600 requests / minute

When exceeded, the API returns 429 Too Many Requests with a Retry-After header indicating how many seconds to wait. /check also carries a separate anti-brute-force limit: 3 checks per question, per session, per rolling hour (configurable per org). It is keyed on (api key, assessment, question, session_id), falling back to learner_ref when you omit session_id. Exceeding it also returns 429, with a Retry-After that can be up to an hour — so back off on the header value, never on a fixed schedule. See Technical Limits for quotas and overage.

Response Envelope

All API responses use a consistent envelope:

// Success
{ "data": <payload>, "error": null, "meta": <pagination-or-null> }

// Error
{ "data": null, "error": { "message": "..." }, "meta": null }

List endpoints include pagination metadata:

{
  "data": [...],
  "error": null,
  "meta": { "total": 42, "page": 1, "limit": 20 }
}

The `learner_ref` field

Every submission and session accepts a learner_ref — your internal identifier for the learner:

Use a stable, immutable ID (database primary key or UUID)
Never use mutable values like email addresses
Edpire echoes it back exactly as provided and never validates it
Not unique-enforced — the same learner can have multiple submissions

Getting Started

For Platforms & Developers

For Schools

Authentication

API Keys

Scopes

Rate Limits

Response Envelope

The `learner_ref` field

​API Keys

​Scopes

​Rate Limits

​Response Envelope

​The learner_ref field

API Keys

Scopes

Rate Limits

Response Envelope

The `learner_ref` field