Examplary API SDK for TypeScript

A type-safe TypeScript client for the Examplary API. One method per API operation, fully typed inputs and responses, axios-backed.

Installation

yarn add @examplary/sdk

Quick start

import { Examplary } from "@examplary/sdk";

const client = new Examplary({
  apiKey: process.env.EXAMPLARY_API_KEY,
});

// Create a minimal exam with a single open-ended question.
const exam = await client.exams.create({
  name: "End-of-term assessment",
  language: "en",
  questions: [
    {
      type: "single-line-text",
      title: "What is the capital of France?",
      scoring: {
        rubricType: "exact-values",
        criteria: [{ id: "answer", title: "Paris", points: 1 }],
      },
    },
  ],
});

console.log(exam.id);

Calling conventions

Every method takes a single object whose fields combine path, query, and body parameters:

// Path + body merged into one object.
await client.exams.update({
  id: exam.id,
  name: "Updated name",
});

// Just a string when the operation has a single path parameter.
const questionType = await client.questionTypes.get("single-line-text");

Each method accepts an optional second argument that extends axios's request config — anything except method, url, data, params, baseURL:

await client.exams.list({}, {
  timeout: 10_000,
  signal: controller.signal,
  headers: { "X-Trace-Id": traceId },
});

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.id,
  sessionId,
  questionId,
});

Errors

Failed requests reject with an ExamplaryError (an AxiosError subclass). The error message is taken from the API response body when available:

import { Examplary, ExamplaryError } from "@examplary/sdk";

try {
  await client.exams.get("ex_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:

| Option | Type | Description | | --------- | -------- | ---------------------------------------------------------------------- | | apiKey | string | Required. API key or OAuth access token. Sent as Authorization header. | | baseUrl | string | Override the API host. Defaults to https://api.examplary.ai. |

Types

Per-operation argument and response types are exported under predictable names:

import type {
  ExamsCreateArgs,
  ExamsCreateResponse,
  QuestionTypesGetArgs,
} from "@examplary/sdk";

The full OpenAPI surface is also available as paths, operations, and components exports for advanced use.