> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.spreadspace.app/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.spreadspace.app/_mcp/server.

# SDKs

> Official SpreadSpace SDKs for TypeScript, Python, and C#: typed errors, automatic retries, idempotency, and cursor pagination over the same API.

SpreadSpace ships official, server-side SDKs in three languages. Each one wraps
the same HTTP API documented in the [API Reference](/api): 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.

| Language          | Package            | Registry | Quick start                    |
| ----------------- | ------------------ | -------- | ------------------------------ |
| TypeScript / Node | `@spreadspace/sdk` | npm      | [TypeScript](/sdks/typescript) |
| Python            | `spreadspace`      | PyPI     | [Python](/sdks/python)         |
| C# / .NET         | `SpreadSpace`      | NuGet    | [C#](/sdks/csharp)             |

Current versions: `@spreadspace/sdk` 1.0.0
([npm](https://www.npmjs.com/package/@spreadspace/sdk)), `spreadspace` 1.0.0
([PyPI](https://pypi.org/project/spreadspace/)), `SpreadSpace` 1.0.0
([NuGet](https://www.nuget.org/packages/SpreadSpace)), `@spreadspace/react`
0.2.0 ([npm](https://www.npmjs.com/package/@spreadspace/react)) and
`@spreadspace/embed` 1.0.0 ([npm](https://www.npmjs.com/package/@spreadspace/embed)).
See the public [changelog](/api/changelog) for release notes.
`@spreadspace/react` and `@spreadspace/embed`, the browser packages for the
[embed](/embed/overview), release independently of the three SDKs.

## Install

**`TypeScript`**

```bash title="TypeScript"
npm i @spreadspace/sdk
```

**`Python`**

```bash title="Python"
pip install spreadspace
```

**`C#`**

```bash title="C#"
dotnet add package SpreadSpace
```

## 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.

**`TypeScript`**

```ts title="TypeScript"
import { SpreadSpace } from '@spreadspace/sdk';

const client = new SpreadSpace({ apiKey: 'ss_test_...' });
// or: new SpreadSpace()  -> reads SPREADSPACE_API_KEY
```

**`Python`**

```python title="Python"
from spreadspace import SpreadSpace

client = SpreadSpace(api_key="ss_test_...")
# or: SpreadSpace()  -> reads SPREADSPACE_API_KEY
```

**`C#`**

```csharp title="C#"
using SpreadSpace;

using var client = new SpreadSpaceClient(apiKey: "ss_test_...");
// or: new SpreadSpaceClient()  -> 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.

**`TypeScript`**

```ts title="TypeScript"
import { SpreadSpace } from '@spreadspace/sdk';

const client = new SpreadSpace({ apiKey: 'ss_test_...', apiVersion: '2026-07-19' });
```

**`Python`**

```python title="Python"
from spreadspace import SpreadSpace

client = SpreadSpace(api_key="ss_test_...", api_version="2026-07-19")
```

**`C#`**

```csharp title="C#"
using SpreadSpace;

using var client = new SpreadSpaceClient(new SpreadSpaceClientOptions
{
    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](/api/changelog) under the release
that made it. A patch release does not change the surface.

The twelve-month promise on the [Versioning](/api/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.

* [TypeScript quick start](/sdks/typescript)
* [Python quick start](/sdks/python)
* [C# quick start](/sdks/csharp)