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.

LanguagePackageRegistryQuickstart
TypeScript / Node@spreadspace/sdknpmTypeScript
PythonspreadspacePyPIPython
C# / .NETSpreadSpaceNuGetC#

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) 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 quickstarts

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