Client SDK

Client Setup

Create and configure the Monospace SDK client.

Create a Client

Import createClient from the generated output and pass your connection details. The factory uses your generated Schema to type each collection's methods.

client.ts

import { createClient } from './generated/monospace';

const client = createClient({
  url: 'https://example.monospace.io',
  workspace: 'blog',
  apiKey: 'YOUR_API_KEY',
});

const articles = await client.Articles.readMany({
  fields: ['*'],
});

Without code generation, import createClient from @monospace/sdk; the options are the same, but the types differ. See Use the SDK from JavaScript.

Connection

Option	Type	Default	Description
`url`	`string`	—	Monospace instance base URL (required)
`workspace`	`string`	—	Workspace identifier (required)
`apiKey`	`string`	`undefined`	API key for authentication

Advanced

Option	Type	Default	Description
`unwrapEnvelope`	`boolean`	`true`	Strip the `{ data }` envelope from responses. See Response Envelope
`strictNull`	`boolean`	`true`	Add `\| null` to all field types to account for conditional permissions. See Null Strictness

Configure from Environment Variables

Read connection details from environment variables to avoid hardcoding secrets.

client.ts

import process from 'node:process';
import { createClient } from './generated/monospace';

import 'dotenv/config';

export const client = createClient({
  url: 'http://localhost:3000',
  workspace: 'dev',
  apiKey: process.env.MONOSPACE_API_KEY!,
});

Set the API key in .env:

.env

MONOSPACE_API_KEY=your-api-key-here

Warning

Never commit API keys to source control. Use .env files, CI secrets, or a secrets manager.

Customize Response Behavior

Set these response options on the client or override them per request:

unwrapEnvelope — Removes the { data } wrapper from API responses by default (true). Set to false to keep the envelope, including any future metadata fields.
strictNull — Adds | null to all field types by default (true) to account for conditional field-level permissions. Set to false when your credentials grant full field access.

Both options support per-request overrides via a second argument to any CRUD method:

SDK

const response = await client.Articles.readMany(
  { fields: ['id', 'title'] },
  { unwrapEnvelope: false, strictNull: false },
);

See Advanced for examples of response envelopes and null handling.

Next Steps

Installation — set up the SDK and generate types
Type System — understand generated types and inference
API Overview — the REST API the SDK wraps
Authentication — API key management and auth flows

Installation

Install the SDK, configure your project, and generate types.

Type System

Leverage TypeScript for type-safe data access with generated types and inference.