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 generated factory is pre-typed with your Schema, so every collection accessor is fully typed.

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 instead. Every option on this page applies unchanged. Only the types differ. See Use the SDK from JavaScript.

Connection

Option	Type	Default	Description
`url`	`string`	—	Base URL of your Monospace instance (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`	Apply `\| null` to all fields for conditional permission safety. See Null Strictness
`http`	`HttpClientFactory`	Built-in client	Custom HTTP client factory for custom fetch implementations

The http option accepts a factory function (config: HttpClientConfig) => HttpClient. The returned object must implement get, post, patch, and delete. Use this for request logging, custom retry logic, or token refresh.

const client = createClient({
  url: 'https://example.monospace.io',
  workspace: 'blog',
  apiKey: 'YOUR_API_KEY',
  http: (config) => ({
    get: (path, opts) => { /* your implementation */ },
    post: (path, opts) => { /* your implementation */ },
    patch: (path, opts) => { /* your implementation */ },
    delete: (path, opts) => { /* your implementation */ },
  }),
});

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!,
});

.env

MONOSPACE_API_KEY=your-api-key-here

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

Customize Response Behavior

The SDK provides two response modifiers that can be set at the client level or overridden per request:

unwrapEnvelope — Controls whether the SDK strips the { data } wrapper from API responses. Default: true (unwrapped). Set to false to preserve the envelope for forward compatibility with future metadata fields.
strictNull — Controls whether all fields include | null in their types to account for conditional field-level permissions. Default: true (strict). Set to false when your auth context has full field access.

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

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

For detailed examples and explanations, see Advanced.

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.