Skip to main content

​
API Keys

All REST API calls require a Bearer token: 
Authorization: Bearer edp_live_<your-key>
Generate API keys in your Edpire dashboard under Settings → API Keys.

​
Environments

Edpire provides two isolated environments. The key prefix determines which environment a request targets — no other configuration needed.
Key prefixEnvironmentDatabase
edp_live_...ProductionYour org’s live data
edp_test_...SandboxIsolated, resettable sample data
Swap your key prefix to move between environments. All endpoints behave identically in both. 
# Production
Authorization: Bearer edp_live_abc123...

# Sandbox
Authorization: Bearer edp_test_abc123...
Use sandbox keys for all development and testing. They route to a separate database that can be reset at any time — your production data is never touched.

​
Scopes

Each API key can be granted one or more scopes:
ScopeGrants access to
read:assessmentsList/fetch assessments, collections, webhooks. Grade single questions via /check.
write:assessmentsCreate/update assessments, manage collections, register webhooks, mint embed tokens.
read:resultsFetch submissions, learner results, assessment results, collection results.
write:submissionsSubmit answers for server-side grading via POST /assessments/{id}/submit.
Grant the minimum scopes your integration needs.

​
Rate Limits

EnvironmentLimit
Production (edp_live_...)100 requests per minute per key
Sandbox (edp_test_...)300 requests per minute per key
When exceeded, the API returns 429 Too Many Requests with a Retry-After header indicating when to retry. The /check endpoint has a separate per-question rate limit (default 3 checks per question per session, configurable per org).

​
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