Get access

SDKs and tools · 21 / 42

Python over HTTP

Northsun does not currently publish an official Python SDK from this repository. Python applications should use the frozen REST API directly with httpx or another maintained HTTP client; this avoids fictional package names and keeps the contract explicit.

Install an HTTP client

python -m pip install httpx

Create a shared client

import os
import httpx

client = httpx.Client(
    base_url="https://mcp.northsun.ai",
    headers={"Authorization": f"Bearer {os.environ['NORTHSUN_API_KEY']}"},
    timeout=5.0,
)

Keep NORTHSUN_API_KEY in a server-side secret store. Do not place it in a notebook you plan to share.

Recall and enrich

response = client.post(
    "/v1/recall_and_enrich",
    json={
        "phone_number": "+15551234567",
        "trigger": "answered",
        "session_id": "call_01",
    },
)
response.raise_for_status()
packet = response.json()

print(packet["caller"]["name"])
print(packet["memory"]["summary"])

Write back after the call

response = client.post(
    "/v1/calls/end",
    json={
        "phone_number": "+15551234567",
        "session_id": "call_01",
        "transcript": [
            {"role": "user", "text": "Please call me Tuesday.", "ts_ms": 0},
            {"role": "agent", "text": "I will note that request.", "ts_ms": 2400},
        ],
        "duration_s": 18,
        "outcome": "callback_requested",
    },
)
response.raise_for_status()
assert response.status_code == 204

Read a caller

from urllib.parse import quote

phone = quote("+15551234567", safe="")
response = client.get(f"/v1/caller/{phone}")

For production code, URL-encode the phone number so the leading + becomes %2B. Treat 404 as an unknown caller, not as an authentication failure.

Retry deliberately

Retry timeouts, 429, and temporary 5xx responses with capped exponential backoff and jitter. Do not retry invalid JSON, validation errors, or authentication failures unchanged. See Errors and retries.

Python SDK status

Any older document showing a Python package or methods such as client.recall_and_enrich() is draft evidence until an official package, version, and contract are source-proved. This HTTP guide is the supported documentation path today.

Next steps