Using the TypeScript SDK (@zinn-digital/sdk)

@zinn-digital/sdk is our official TypeScript client for the Zinn Digital® API, published on npm. Every path, parameter and response in it is generated from the same OpenAPI specification the API is built from, and a new version is published automatically whenever that specification changes. This guide installs it, authenticates it and makes your first calls.

Install

npm install @zinn-digital/sdk

It works in any JavaScript runtime that has fetch: Node.js, the browser and edge runtimes. It has one runtime dependency, openapi-fetch, and it is MIT-licensed.

Create an API key

Open the API keys page of your dashboard (app.zinndigital.com/api-keys) and press Create a key. Give the key a name and only the permissions your code needs — for example sites.view to list sites. The key is shown once; store it in an environment variable or your secret store, never in source code. You can revoke a key at any time on the same page.

Public catalogue endpoints, such as hosting regions and plans, need no key at all.

Your first calls

import { createApiClient } from "@zinn-digital/sdk";

const api = createApiClient({ baseUrl: "https://api.zinndigital.com" });

// Public catalogue endpoints need no key.
const { data: regions } = await api.GET("/v1/catalog/regions");
console.log(regions?.data.map((r) => r.slug));

// Everything else uses a per-organisation API key.
api.use({
  onRequest({ request }) {
    request.headers.set("Authorization", `Bearer ${process.env.ZINN_API_KEY}`);
  },
});

const { data, error } = await api.GET("/v1/sites", { params: { query: { limit: 5 } } });
if (error) throw new Error(error.error.message);
for (const site of data.data) console.log(site.name, site.status);

Run it with ZINN_API_KEY=zdk_live_… npx tsx first-calls.ts. The first line prints the hosting regions, then one line per site.

Types for your own code

The schema types are exported, so your own functions can use the API's shapes:

import type { components } from "@zinn-digital/sdk";

type Site = components["schemas"]["Site"];
type DnsRecord = components["schemas"]["DnsRecord"];

A misspelt path, parameter or field is a compile error rather than a request that silently does the wrong thing.

Errors

Every call returns { data, error, response }. On a non-2xx response data is undefined and error is the API's error envelope: error.error.code, a human-readable error.error.message and, for validation failures, error.error.details naming each field. A 403 means the key does not carry the permission the endpoint needs — create a key with that permission rather than reusing one with more.

Where to go next

• The guide on our website: zinndigital.com/developers/sdk-typescript
• Every endpoint, its parameters and its permission: zinndigital.com/developers/api
• The package on npm: npmjs.com/package/@zinn-digital/sdk