> This page is for API.

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

# API Reference

The SpreadSpace API is organized by resource. Pick a group from the sidebar to see
its endpoints, request and response schemas, and copy-paste examples in cURL and
every official SDK.

## Base URL

Every request goes to one base URL. The API key **prefix** (not the URL) selects
the environment:

```
https://api.spreadspace.app
```

* **`ss_live_…`** operates on live workspace data.
* **`ss_test_…`** routes to the isolated developer sandbox (test mode), where uploads
  return premade sample extractions at no charge.

## Authentication

Every request carries a bearer token in the `Authorization` header:

```bash
curl https://api.spreadspace.app/api/borrowers \
  -H "Authorization: Bearer ss_live_..."
```

Key management, prefixes, and secret handling: [Authentication](/api/authentication).

## Find an extraction

When browsing a mixed document packet, list the borrower's extractions first.
The optional `loan_id` query parameter limits the list to one loan; omit it to
browse across the borrower's loans.

```bash
curl "https://api.spreadspace.app/api/borrowers/111111111111111111111111/extractions?loan_id=222222222222222222222222" \
  -H "Authorization: Bearer ss_test_..."
```

Each row describes one extraction. These selected fields from a fictional row
identify the statement, its reporting period and its source pages:

```json
{
  "extracted_document_id": "333333333333333333333333",
  "document_category": "balance_sheet",
  "display_name": "Balance sheet (2025-12-31)",
  "period_label": "2025-12-31",
  "period_start": null,
  "period_end": "2025-12-31",
  "fiscal_year": 2025,
  "created_at": "2026-01-15T14:30:00Z",
  "original_filename": "annual-statements (2 of 3).pdf",
  "source_pages": [4, 5],
  "links": {
    "data": "/api/borrowers/111111111111111111111111/extractions/333333333333333333333333/balance-sheet-statement"
  }
}
```

`display_name` is a concise document label. `period_label`, `period_start`,
`period_end` and `fiscal_year` describe the reporting period when known;
`created_at` records when the extraction was stored, not the report date.
`original_filename` is the stored source or document label and may include a
section suffix. `source_pages` contains positive, 1-based page numbers in the
original uploaded PDF: cited pages when available, otherwise the source
section's full page coverage. It is null when that coverage is unknown.

Follow `links.data` with a GET request and the same bearer token. The link is
relative to the API base URL, and the request uses the same access checks as
any other extraction read:

```bash
curl "https://api.spreadspace.app/api/borrowers/111111111111111111111111/extractions/333333333333333333333333/balance-sheet-statement" \
  -H "Authorization: Bearer ss_test_..."
```

The link selects the typed read when one exists, otherwise the generic
`report-data` read. `links.data` is null when the document is unextractable or
has no extracted data. If you already know the document kind, use its typed
list, such as `GET /api/borrowers/{borrower_id}/extractions/balance-sheets`.
The generic `GET /api/borrowers/{borrower_id}/extractions/{doc_id}/report-data`
route remains available for advanced integrations that handle several kinds
through one read.

## Versioning

The API surface is versioned with date stamps. Pin one per request with the
optional `SpreadSpace-Version` header; omit it to get the latest. Resolution
order, supported versions, and drift detection: [Versioning](/api/versioning).
What changed on the public surface: [Changelog](/api/changelog).

## Idempotency

Mutating calls accept an optional `Idempotency-Key` header so retries never
double-apply an operation: [Idempotency](/api/idempotency).

## Request IDs

Every response carries an `X-Request-ID` header: yours echoed back if you sent
one shaped `req_` plus 1 to 64 letters or digits, otherwise minted server-side
as `req_<24 hex chars>`. Quote it in support tickets so we can find the
request's logs.

## SDKs

Prefer a typed client? The [SDKs](/sdks/overview) wrap the core integration
surface (borrowers, loans and attributes, jobs, documents, exports, webhooks,
embed sessions) with retries, cursor pagination, idempotency, and webhook
verification.

## Resources

* **OpenAPI spec**: `https://api.spreadspace.app/v1/openapi.json` is the public
  contract used by these reference pages. Download it:

  ```bash
  curl -sS https://api.spreadspace.app/v1/openapi.json -o spreadspace-openapi.json
  ```

* **Postman**: a [collection](https://spreadspace.app/postman/spreadspace-api.postman_collection.json)
  with one request per public operation, grouped by resource, and a
  [test mode environment](https://spreadspace.app/postman/spreadspace-test-mode.postman_environment.json).
  Import both, select the environment, and paste an `ss_test_` key into its
  `apiKey` variable.

* **Status**: [spreadspace.app/status](https://spreadspace.app/status) shows
  the result of a live probe of `GET https://api.spreadspace.app/health` (which
  answers `200` with the plain-text body `Healthy` when the API is up), the
  version stamp the API resolved for it, and, when available, the trailing
  successful request rate.

* **SDK packages**: [`@spreadspace/sdk`](https://www.npmjs.com/package/@spreadspace/sdk) 1.1.0
  (npm), [`spreadspace`](https://pypi.org/project/spreadspace/) 1.1.0 (PyPI),
  [`SpreadSpace`](https://www.nuget.org/packages/SpreadSpace) 1.1.0 (NuGet),
  [`@spreadspace/react`](https://www.npmjs.com/package/@spreadspace/react) 0.2.0
  (npm), [`@spreadspace/embed`](https://www.npmjs.com/package/@spreadspace/embed)
  1.0.0 (npm).

* **Agents**: `https://docs.spreadspace.app/llms.txt` indexes every page, and
  any page is served as Markdown when you append `.md` to its URL, for example
  `https://docs.spreadspace.app/api/versioning.md`. A coding agent can follow
  [Agent-assisted integration](/get-started/agent-assisted-integration).

* **Changelog**: what changed on the public surface:
  [Changelog](/api/changelog).

* **Support**: contact `support@spreadspace.app` and include the request's
  `X-Request-ID`.