Skip to main content
Choose the tier that matches your needs. Each tier builds on the previous one. Redirect learners to Edpire’s hosted assessment UI. No code on your server beyond generating the URL. How it works:
  1. Publish an assessment in the Edpire dashboard and note its share code (e.g., ABC123)
  2. Redirect the learner to the assessment URL
  3. After completion, Edpire redirects back to your return_url with results
Redirect URL: 
https://{your-slug}.edpire.com/take/{shareCode}?learner_ref={userId}&return_url={yourUrl}
ParameterRequiredDescription
shareCodeYesAssessment share code from the dashboard
learner_refRecommendedYour stable internal user ID
return_urlRecommendedWhere to send the learner after completion (must be in Allowed Origins)
Return URL parameters appended by Edpire: 
https://yourplatform.com/results?submission_id=sub_xxx&score=14&max_score=20
When to use: Quick integration, comfortable with a browser redirect, no custom UI needed.

​
Tier 2: Embed Widget

Render the assessment inline on your page using the @edpire/sdk JavaScript SDK. No redirect — the learner stays on your site. Step 1 — Mint an embed token (server-side only) 
// On your server — never expose your API key to the browser
const res = await fetch("https://app.edpire.com/api/v1/embed/token", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.EDPIRE_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    assessment_id: "asmt_xxx",
    learner_ref: "your-user-id",
  }),
})
const { data } = await res.json()
// data.token — pass this to the browser
Step 2 — Mount the SDK in the browser
The CDN bundle (cdn.edpire.com) is coming soon. Until then, use the npm package (npm install @edpire/sdk).
<div id="assessment-root"></div>
<script src="https://cdn.edpire.com/sdk/v0/edpire-sdk.umd.js"></script>
<script>
  const embed = EdpireSDK.EdpireAssessment.mount({
    token: "{{ token_from_server }}",
    container: "#assessment-root",
    onComplete: function (result) {
      console.log(result.submission_id, result.percentage + "%")
    },
    onError: function (err) {
      console.error(err.code, err.message)
    },
  })
</script>
When to use: Assessment must appear inside your site. You want Edpire’s player UI without a redirect.

​
Tier 3: SDK Components (per-question feedback)

Build a fully custom learner experience (Duolingo-style flows, flashcard drills, practice modes) using Edpire’s SDK components for rendering and the /check endpoint for real-time per-question grading. Step 1 — Fetch the assessment 
const { data: assessment } = await fetch(
  `https://app.edpire.com/api/v1/assessments/${id}`,
  { headers: { Authorization: `Bearer ${apiKey}` } }
).then((r) => r.json())
Step 2 — Flatten into a question sequence 
import { flattenAssessment } from "@edpire/sdk"

const steps = flattenAssessment(assessment)
// steps[0] = { exerciseId, questionId, content, points, sequenceNumber, index }
Step 3 — Render questions with EdpireQuestion 
import { EdpireQuestion } from "@edpire/sdk/react"

<EdpireQuestion
  content={step.content}
  onAnswersChange={setAnswers}
  feedback={feedback}
  dir="ltr"
/>
Step 4 — Grade each question via your backend proxy 
// Your backend proxies this to Edpire (keeps API key server-side)
const result = await fetch("/api/edpire/check", {
  method: "POST",
  body: JSON.stringify({
    assessment_id: assessmentId,
    exercise_id: step.exerciseId,
    question_id: step.questionId,
    answers: currentAnswers,
    learner_ref: userId,
    session_id: sessionId, // UUID, generated once per attempt
  }),
}).then((r) => r.json())
// result.data = { correct, score, max_score, feedback }
Step 5 — Submit the full attempt when done The /check endpoint is stateless and does not create submission records. After all questions, submit the full answer set via POST /assessments/{id}/submit.
Rate limiting: Each (session_id, question_id) pair is limited to 3 checks per hour (configurable per org). Generate a fresh session_id per attempt.
When to use: Custom UX (Duolingo-style, flashcards, hearts/lives), immediate per-question feedback.

​
Tier 4: Fully Headless (server-side grading)

Your server collects answers in whatever UI you build, then submits the full answer set to Edpire for grading. No Edpire UI or SDK involved at all. Step 1 — Fetch assessment content 
import { EdpireClient } from "@edpire/sdk/client"

const client = new EdpireClient({ apiKey: process.env.EDPIRE_API_KEY! })
const assessment = await client.getAssessment("assessment-uuid")
// assessment.exercises[].questions[].content_ast — render in your own UI
Step 2 — Collect answers in your UI Build your own question rendering. The answers must match this structure: 
{
  exerciseAnswers: [
    {
      exerciseId: "ex-1",
      questionAnswers: [
        {
          questionId: "q-1",
          answers: [
            { nodeId: "choice_abc", type: "choiceSet", value: ["opt_a"] }
          ]
        }
      ]
    }
  ]
}
Step 3 — Submit for grading 
const result = await client.submit("assessment-uuid", {
  learner_ref: "user-123",
  answers: { exerciseAnswers: [...] },
})

console.log(result.score, result.max_score, result.passed)
// result.exercise_results[].question_results[].feedback — per-question correctness
Error codes:
StatusMeaning
404Assessment not found or not in your org
400Assessment is archived, or is a draft without allow_draft: true
409Maximum attempts exceeded
422Grading failed (check answer format)
When to use: Full control over UX, mobile apps, server-to-server integrations.