API Reference | SpreadSpace

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:

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

Key management, prefixes, and secret handling: 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.

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:

{
  "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:

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. What changed on the public surface: Changelog.

Idempotency

Mutating calls accept an optional Idempotency-Key header so retries never double-apply an operation: 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 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:
```
curl -sS https://api.spreadspace.app/v1/openapi.json -o spreadspace-openapi.json
```
Postman: a collection with one request per public operation, grouped by resource, and a test mode environment. Import both, select the environment, and paste an ss_test_ key into its apiKey variable.
Status: 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 1.1.0 (npm), spreadspace 1.1.0 (PyPI), SpreadSpace 1.1.0 (NuGet), @spreadspace/react 0.2.0 (npm), @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.
Changelog: what changed on the public surface: Changelog.
Support: contact support@spreadspace.app and include the request’s X-Request-ID.