TypeScript SDK

The Examplary API SDK for TypeScript provides a type-safe client for the Examplary API. It includes methods for all API endpoints, as well as type definitions for request and response data.

Installation

yarn add @examplary/sdk

Usage

To use the SDK, create an instance of the client and provide your personal API key:

import { Examplary } from "@examplary/sdk";
 
const client = new Examplary({
  apiKey: "my-api-key",
});
 
const questionTypes = await client.questionTypes.listPublic();

Calling conventions

Every method takes its path, query, and body parameters merged into a single object — or, for operations with just one path parameter, that parameter as a plain string:

// Path + body merged into one object.
await client.exams.update({
  id: "exam_1234",
  name: "Updated name",
});
 
// Just a string when the operation has a single path parameter.
const questionType = await client.questionTypes.get("single-line-text");

Nested resources (e.g. client.exams.sessions.acceptSuggestion) rename the parent id to examId (or practiceSpaceId, etc.) for readability:

await client.exams.sessions.acceptSuggestion({
  examId: "exam_1234",
  sessionId: "ses_5678",
  questionId: "my_question_1",
});

Each method accepts an optional second argument that extends axios's request config (timeouts, an abort signal, extra headers, etc.) — method, url, data, params, and baseURL are excluded from this per-call config, since those are managed by the client itself.

Errors

A failed request rejects the returned promise with an ExamplaryError (an AxiosError subclass). The error message is taken from the API response body when available:

import { Examplary, ExamplaryError } from "@examplary/sdk";
 
const client = new Examplary({ apiKey: "my-api-key" });
 
try {
  await client.exams.get("exam_does_not_exist");
} catch (err) {
  if (err instanceof ExamplaryError) {
    console.error(err.message, err.response?.status);
  }
}

Configuration

new Examplary(options) accepts every axios CreateAxiosDefaults field plus:

A 429 is retried for any method, waiting as long as the Retry-After header says. Network errors, timeouts, and 5xx responses are only retried for idempotent methods (GET, HEAD, OPTIONS, PUT, DELETE), with exponential backoff. maxRetries can also be set per call, alongside the other options described under Calling conventions.