Curvestone

SDKs & Libraries

Official client libraries for Python and TypeScript.

Py

Python

Installation
terminal
bash
pip install curvestone
Basic usage
check.py
python
from curvestone import Agent


agent = Agent()  # reads CURVESTONE_API_KEY from env


result = agent.check(
    case_type="residential_mortgage",
    depth="full_check",
    documents=[
        open("fact_find.pdf", "rb"),
        open("suitability_letter.pdf", "rb"),
    ],
    reference="CASE-2026-00451",
)


print(f"Triage: {result.triage}")
print(f"Job ID: {result.id}")
Python 3.8+Async support via asyncioFull type hints
TS

TypeScript

Installation
terminal
bash
npm install @curvestone/sdk
Basic usage
check.ts
typescript
import { Agent } from '@curvestone/sdk';
import { readFileSync } from 'fs';


const agent = new Agent();  // reads CURVESTONE_API_KEY from env


const result = await agent.check({
  caseType: 'residential_mortgage',
  depth: 'full_check',
  documents: [
    readFileSync('fact_find.pdf'),
    readFileSync('suitability_letter.pdf'),
  ],
  reference: 'CASE-2026-00451',
});


console.log(`Triage: ${result.triage}`);
console.log(`Job ID: ${result.id}`);
Node.js 18+TypeScript 5+ESM and CJS

Configuration

Environment variable

Both SDKs read the CURVESTONE_API_KEY environment variable automatically. This is the recommended approach for production.

terminal
bash
export CURVESTONE_API_KEY='cs_live_xxxxxxxxxxxx'

Direct initialization

You can also pass the key directly. Useful for testing or when managing multiple keys.

init.py
python
from curvestone import Agent


agent = Agent(api_key="cs_live_xxxxxxxxxxxx")

Version pinning

The API uses header-based versioning via Curvestone-Version. The SDK sends the version it was built against by default. You can override it to pin a specific date.

version.py
python
from curvestone import Agent


agent = Agent(
    api_key="cs_live_xxxxxxxxxxxx",
    version="2026-02-21",
)

Common Patterns

Async operations

The TypeScript SDK is async-first. The Python SDK supports both sync and async via AsyncAgent.

async_check.py
python
from curvestone import AsyncAgent
import asyncio


async def main():
    agent = AsyncAgent()


    result = await agent.check(
        case_type="residential_mortgage",
        depth="full_check",
        documents=[
            open("fact_find.pdf", "rb"),
        ],
    )


    print(f"Triage: {result.triage}")


asyncio.run(main())

Error handling

Both SDKs raise typed exceptions. Catch specific error types or handle the base CurvestoneError.

errors.py
python
from curvestone import Agent, CurvestoneError, ValidationError, RateLimitError


agent = Agent()


try:
    result = agent.check(
        case_type="residential_mortgage",
        depth="full_check",
        documents=[open("fact_find.pdf", "rb")],
    )
except ValidationError as e:
    print(f"Validation failed: {e.message}")
    print(f"Field: {e.param}")
except RateLimitError as e:
    print(f"Rate limited. Retry after {e.retry_after}s")
except CurvestoneError as e:
    print(f"API error: {e.code} — {e.message}")

Polling for results

Long-running checks return immediately with a job ID. Poll GET /jobs/:id until the status changes, or use webhooks for push-based notification.

poll.py
python
import time
from curvestone import Agent


agent = Agent()


job = agent.check(
    case_type="residential_mortgage",
    depth="full_check",
    documents=[open("fact_find.pdf", "rb")],
)


while job.status != "completed":
    time.sleep(5)
    job = agent.jobs.get(job.id)


print(f"Done: {job.triage}")

Platform integration with X-Actor

Platform partners submit jobs on behalf of users using the X-Actor header. This associates the job with the correct broker for billing and audit.

x_actor.py
python
from curvestone import Agent


agent = Agent(
    default_headers={"X-Actor": "broker_12345"},
)


result = agent.check(
    case_type="residential_mortgage",
    depth="full_check",
    documents=[open("fact_find.pdf", "rb")],
    reference="CRM-REF-98765",
)

Further reading

Quickstart

End-to-end walkthrough in 5 minutes.

API Reference

All endpoints, parameters, and response shapes.