Home / Docs / The SDK

The SDK

A typed TypeScript client generated from the contract, and the version rule that keeps it honest.

Use this page to call the router's own endpoints from TypeScript with types. @massrelay/sdk is a small typed client generated from the same contract as the reference pages, so an endpoint that changes in the contract changes in the SDK, and a build that forgot to regenerate is caught by a check.

For chat, use the OpenAI or Anthropic SDK (see Quickstart). This one is for the endpoints those SDKs do not have: credits, usage, the key, the policy and the route explanation.

Install

npm install @massrelay/sdk

Make a call

import { createClient } from "@massrelay/sdk";

const mr = createClient({
  baseUrl: "https://api.massrelay.ai",
  apiKey: process.env.MASSRELAY_KEY,
});
const credits = await mr.get("/v1/credits"); // typed from the contract

A path with a parameter takes it in path: mr.get("/v1/generation/{id}", { path: { id } }). A POST takes the typed body as its second argument. The key is sent only in the Authorization header, never in a URL or a body.

Handle errors

A non-2xx answer throws:

• **PaymentRequiredError** — a 402, the same walls as in Errors.
• **RateLimitedError** — a 429. It carries retryAfterSeconds when the server sent Retry-After.
• **UpgradeRequiredError** — a 426.
• **ApiError** — any other status, with status and body.

Keep the client current

Every request carries X-MassRelay-Client: @massrelay/sdk/<version>; protocol=<n>. The server publishes the protocol it speaks and the oldest it accepts at GET /public/version. A client older than the minimum is refused with 426 upgrade_required before anything else happens, and the SDK raises UpgradeRequiredError: upgrade the package.