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 0.4.0 (npm), spreadspace 0.4.0 (PyPI), SpreadSpace 0.4.0 (NuGet), @spreadspace/react 0.1.2 (npm), @spreadspace/embed 0.1.3 (npm). Release notes for @spreadspace/sdk, spreadspace and SpreadSpace are kept in the SDK changelog (sdk/CHANGELOG.md) beside the SDK sources; the embed packages release under their own tags.

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.

1import { SpreadSpace } from '@spreadspace/sdk';
2
3const client = new SpreadSpace({ apiKey: 'ss_test_...' });
4// 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 (currently 2026-05-03, which resolves to the same behaviour as the latest 2026-07-19) 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.

1import { SpreadSpace } from '@spreadspace/sdk';
2
3const client = new SpreadSpace({ apiKey: 'ss_test_...', apiVersion: '2026-05-03' });

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, and typed error handling.