Custom Flow - Edpire

Custom Flow gives you full control over pacing, navigation, and scoring UX. The SDK renders questions and collects answers; you own everything else — progress bars, hearts/lives, animations, “next” buttons. The shape of a Custom Flow:

Fetch the assessment (server)

Your server calls client.getAssessment() — the API key never reaches the browser.

Flatten into steps

flattenAssessment() turns the nested assessment into a flat array of questions.

Render each question

<EdpireQuestion> (React) or renderQuestion() (vanilla) renders one step at a time.

Check answers per question

Your server proxies POST /check for immediate per-question feedback. Stateless — no record created.

Submit the full attempt

When done, your server calls client.submit() once to record + grade the whole attempt.

1. Fetch (server)

Keep the API key server-side — never call Edpire directly from the browser. Expose a thin proxy your browser can call:

// GET /api/edpire/assessment/[id]/route.ts
import { EdpireClient } from "@edpire/sdk/client"

const client = new EdpireClient({ apiKey: process.env.EDPIRE_API_KEY! }) // module level

export async function GET(_req: Request, { params }: { params: Promise<{ id: string }> }) {
  const { id } = await params
  const assessment = await client.getAssessment(id)
  return Response.json({ data: assessment })
}

2. Flatten — `flattenAssessment()`

import { flattenAssessment } from "@edpire/sdk"

const steps = flattenAssessment(assessment)

Returns an ordered FlatStep[] — one entry per question, in the order a learner would see them (exercise order, then question order).

interface FlatStep {
  /** The exercise this question belongs to — required for POST /check. */
  exerciseId: string
  /** The question ID — required for POST /check. */
  questionId: string
  /** ContentAST — pass directly to EdpireQuestion's `content` prop. */
  content: unknown
  /** Point value of this question. */
  points: number
  /** Original sequence number within its exercise. */
  sequenceNumber: number
  /** 0-based index in the flattened sequence — use for a progress bar. */
  index: number
}

exerciseId and questionId are required for the /check call — that’s why flattenAssessment preserves them on every step. Use index for progress (index + 1 of steps.length).

3. Render — `<EdpireQuestion>` or `renderQuestion()`

Generate your session_id now, before rendering the first question. You’ll need it for every /check call and it must be the same across all questions in one attempt. Create it once at attempt start:

const sessionId = crypto.randomUUID()  // once per attempt, before step 3

If you wait until step 4 and generate one per question, rate limiting accumulates across retakes and causes surprise 429s.

React
Vanilla JS

import { EdpireQuestion } from "@edpire/sdk/react"
import type { RuntimeAnswer } from "@edpire/sdk"

const [i, setI] = useState(0)
const [answers, setAnswers] = useState<RuntimeAnswer[]>([])
const [feedback, setFeedback] = useState<Record<string, unknown> | null>(null)
const step = steps[i]

<EdpireQuestion
  content={step.content}
  onAnswersChange={setAnswers}
  feedback={feedback}   // null until the learner checks; pass /check result to reveal
  dir="ltr"
/>

import { flattenAssessment, renderQuestion } from "@edpire/sdk"

const steps = flattenAssessment(assessment)
let i = 0

const q = renderQuestion({
  container: "#question-root",      // selector or HTMLElement
  content: steps[i].content,
  onAnswersChange: (answers) => { current = answers },
})

// After POST /check:
q.setFeedback(checkResult.feedback)

// Move to the next question (also clears feedback):
q.setContent(steps[++i].content)

// Cleanup:
q.unmount()

renderQuestion() returns a QuestionInstance for non-React environments.

`EdpireQuestionProps`

EdpireQuestion is deliberately unstyled beyond what makes the interaction work. It inherits your fonts and colors, and your CSS reaches into it on purpose. Style it to match your product.

Prop	Type	Required	Description
`content`	`unknown`	Yes	The question’s `content_ast`, i.e. a `FlatStep.content`.
`onAnswersChange`	`(answers: RuntimeAnswer[]) => void`	No	Fires on every answer change. Collect these for `/check` and submit.
`feedback`	`Record<string, unknown> \| null`	No	Pass the `feedback` field from `POST /check` directly; the component converts it internally. `null` clears feedback.
`initialAnswers`	`RuntimeAnswer[]`	No	Pre-fill answers, e.g. restoring state when navigating back.
`readOnly`	`boolean`	No	Lock the question: answers show but cannot change. For reviewing a past attempt. Since 0.8.0.
`className`	`string`	No	Class added to the question root `<div>`.
`dir`	`"ltr" \| "rtl"`	No	Text direction. Default `"ltr"`.

feedback takes the raw JSON from /check, with no manual mapping. Internally the component converts it to the Map the runtime expects.

`renderQuestion()` reference

The imperative equivalent, for Vue, Svelte, Angular or plain JS. Also available as EdpireSDK.renderQuestion on the script-tag build.

function renderQuestion(options: RenderQuestionOptions): QuestionInstance

RenderQuestionOptions takes the same fields as EdpireQuestionProps plus container. QuestionInstance:

Method	Description
`setContent(content)`	Replace the question. Also clears feedback — ready for the next step.
`setFeedback(feedback \| null)`	Update feedback (e.g. after `/check`). `null` clears it.
`setInitialAnswers(answers)`	Pre-fill answers (e.g. navigating back).
`unmount()`	Tear down the React root.

4. Check per question — `POST /check`

Grade a single question for immediate feedback. Stateless — no submission is recorded. Proxy it through your server so the API key and include_correct_answers flag stay trusted:

// POST /api/edpire/check/[id]/route.ts
import { EdpireClient } from "@edpire/sdk/client"

const client = new EdpireClient({ apiKey: process.env.EDPIRE_API_KEY! })

export async function POST(req: Request, { params }: { params: Promise<{ id: string }> }) {
  const { id } = await params              // assessmentId in the URL path
  const body = await req.json()
  // Always set include_correct_answers server-side — never trust the client.
  const result = await client.checkQuestion(id, { ...body, include_correct_answers: true })
  return Response.json(result)             // { correct, score, max_score, feedback }
}

The browser then passes result.feedback straight into EdpireQuestion’s feedback prop (or q.setFeedback()).

Rate limiting: 3 checks per question, per session, per rolling hour (configurable per org), keyed on (api key, assessment, question, session_id) and falling back to learner_ref if session_id is omitted. Use the session_id you generated in step 3 — one per attempt, not per question.

How feedback maps onto the question

The /check response’s feedback is keyed by node ID → feedback state (correct/partial/incorrect, score, message, and — when include_correct_answers is true — the correct answer fields). EdpireQuestion consumes that object directly and renders the right per-node visual state. Set feedback back to null (or call setContent) before showing the next question to reset it. When include_correct_answers is true, feedback also includes: correctChoiceIds (choice/drag-drop), correctPairings (matching), and displayAnswer (typed blanks).

5. Submit the full attempt: `client.submit()`

/check records nothing. After the last question, submit the whole attempt once to create the graded submission record (and fire the submission.graded webhook). Collect answers as a flat StoredAnswer[] during the session:

import { EdpireClient } from "@edpire/sdk/client"
import type { StoredAnswer } from "@edpire/sdk"

const stored: StoredAnswer[] = []
// after each step:
stored.push({ exerciseId: step.exerciseId, questionId: step.questionId, answers })

// at the end (client is module-level — see step 1):
const result = await client.submit(assessmentId, {
  learner_ref: userId,
  answers: stored,   // client.submit() accepts the flat array directly
})
console.log(`Final: ${result.score}/${result.max_score}`)

client.submit() accepts either a flat StoredAnswer[] or the nested { exerciseAnswers: [...] } format. If you need the nested form explicitly (e.g. constructing it elsewhere), convert with buildSubmitPayload(stored).

Required API key scopes: read:assessments (fetch + check) and write:submissions (the final submit).

If the learner abandons mid-flow: /check is stateless, so nothing is recorded. If they close the tab before step 5, their attempt is lost. Consider saving answers to sessionStorage after each question so you can restore them on reload, and warn users before they navigate away during an active attempt.

6. Review a past attempt, one question at a time

Once an attempt is submitted, the learner can page back through it the way they took it: one question per screen, their answer locked, marked, with the expected answer on anything missed. Since 0.8.0. Your server fetches the attempt with GET /submissions/{id}/review (client.getSubmissionReview(id, { learnerRef })) after checking it belongs to the learner. The browser turns it into steps and draws each one read-only:

const review = await fetch(`/api/attempts/${submissionId}/review`).then((r) => r.json())
const steps = flattenReview(review)            // one ReviewStep per question

let q = renderQuestion({
  container: el,
  content: steps[i].content,
  initialAnswers: steps[i].answers,            // what the learner answered
  feedback: steps[i].feedback,                 // already in /check's shape
  readOnly: true,
})
// steps[i].status: "correct" | "partial" | "incorrect" | "awaiting_review" | "unscored"
// steps[i].score / steps[i].maxScore for your own verdict line

// Next question: unmount and render a fresh one (initialAnswers are read on mount)
q.unmount()
q = renderQuestion({ ...same fields for steps[i + 1] })

ReviewStep

Field	Description
`exerciseId`, `questionId`	Which question
`content`	Pass to `content`
`sharedContext`	The exercise’s reading passage or figure, or `null`. Unlike `flattenAssessment()`, it is on every step. Render it with `renderQuestion` too
`answers`	Pass to `initialAnswers`
`feedback`	Pass to `feedback`, untouched
`score`, `maxScore`	The question’s marks
`status`	`awaiting_review` while a teacher has yet to mark it. `unscored` when it is worth nothing: do not show it as wrong
`index`	Position in the assessment’s order

Steps come back in the assessment’s order. Edpire does not record the order an attempt was shown in, so if you shuffle, keep the question IDs in the order you used and sort the steps by them. The Angular example does this.

flattenReview is pure, so it is also exported from @edpire/sdk/core and from the script-tag build as EdpireSDK.flattenReview. To show the whole attempt at once instead, use EdpireAssessment.review(). The design around both, including what to store, is in Attempt History.

Full example

The steps above map directly to a complete implementation — see the Custom Flow example for a reference build that wires all five steps together end-to-end.

​1. Fetch (server)

​2. Flatten — flattenAssessment()

​3. Render — <EdpireQuestion> or renderQuestion()

​EdpireQuestionProps

​renderQuestion() reference

​4. Check per question — POST /check

​How feedback maps onto the question

​5. Submit the full attempt: client.submit()

​6. Review a past attempt, one question at a time

​Full example

1. Fetch (server)

2. Flatten — `flattenAssessment()`

3. Render — `<EdpireQuestion>` or `renderQuestion()`

`EdpireQuestionProps`

`renderQuestion()` reference

4. Check per question — `POST /check`

How feedback maps onto the question

5. Submit the full attempt: `client.submit()`

6. Review a past attempt, one question at a time

Full example