Skip to navigation
SDKs

SDKs

SpreadSpace ships official, server-side SDKs in three languages. Each one wraps the same HTTP API documented in the API Reference: same endpoints, same auth, same wire contract. Each adds a typed error hierarchy, automatic retries with exponential backoff + jitter, idempotency on non-GET calls, and cursor pagination exposed as a native async iterator. The long-running flows (document upload, extraction export) come with first-class create + wait helpers so you don’t hand-roll polling loops.

LanguagePackageRegistryQuick start
TypeScript / Node@spreadspace/sdknpmTypeScript
PythonspreadspacePyPIPython
C# / .NETSpreadSpaceNuGetC#

Current versions: @spreadspace/sdk 1.0.0 (npm), spreadspace 1.0.0 (PyPI), SpreadSpace 1.0.0 (NuGet), @spreadspace/react 0.2.0 (npm) and @spreadspace/embed 1.0.0 (npm). See the public changelog for release notes. @spreadspace/react and @spreadspace/embed, the browser packages for the embed, release independently of the three SDKs.

Install

npm i @spreadspace/sdk

Authentication

Every SDK authenticates with an API key and talks to the same base URL, https://api.spreadspace.app. The key prefix selects the environment:

  • ss_test_… routes to your sandbox tenant: seed data, safe to experiment against.
  • ss_live_… routes to your live tenant: real workspace data.

You can pass the key explicitly at construction, or omit it and let the SDK read SPREADSPACE_API_KEY from the environment.

import { SpreadSpace } from '@spreadspace/sdk';
const client = new SpreadSpace({ apiKey: 'ss_test_...' });
// or: new SpreadSpace()  -> reads SPREADSPACE_API_KEY

Never hard-code a live key, and never commit any key.

Pinning the API version

The SpreadSpace API is dated: every request sends a SpreadSpace-Version header, and each SDK release pins a known-good default so a server-side change can’t silently shift behavior under you.

Pin it explicitly to insulate your integration, and override per call when you need a newer surface. The version is decoupled from the SDK’s own semver; you upgrade the package and the API version independently.

import { SpreadSpace } from '@spreadspace/sdk';
const client = new SpreadSpace({ apiKey: 'ss_test_...', apiVersion: '2026-07-19' });

Stability

SDK releases follow semver. A minor release adds methods, types, or options without changing existing ones; a change to an SDK’s own surface ships as a new major and is listed on the changelog under the release that made it. A patch release does not change the surface.

The twelve-month promise on the Versioning page covers the API version an SDK sends. Pin the SDK version in your lockfile and upgrade on your own schedule. A pinned SDK keeps working for as long as the API version it sends stays supported, and that is at least twelve months after any stamp that supersedes it.

Per-language quick starts

Each quick start covers client construction and the core flows: cursor pagination, document upload + wait, typed extraction reads, extraction export + wait, webhook signature verification, embed minting, and typed error handling.