API guide
Install and use the Buddy SDKs
Install from the package registry
Node.js 18+: run npm install @usebuddy/sdk@beta. Python 3.9+: create a virtual environment and run python3 -m pip install --pre usebuddy. The Python distribution is named usebuddy; import it with from buddy import Buddy. The Node package supports both ES modules and CommonJS.
The quickstart contains complete runnable examples for both packages. Store the key in BUDDY_API_KEY. Both clients default to the production API URL; a test key selects simulated data without changing the host.
Read response data
The SDKs return the API response envelope. In Node, read result.data; in Python, read result['data']. A connection check is buddy.me.get() in Node and buddy.me() in Python. Check data.livemode before sending. List responses also include has_more and next_cursor.
Resource helpers cover common operations. For other endpoints, use buddy.call with the operation ID displayed in the reference URL. Node accepts path, query, body and idempotencyKey in its options object. Python accepts path, query, body and idempotency_key as keyword arguments.
Recover from errors
Node exposes BuddyError with status, code, requestId, details and retryAfter. Python exposes BuddyError with status, code, request_id, details and retry_after. Retain the request ID when reporting an issue, but never include API keys or recipient secrets.
Both clients make at most two retries by default for eligible network errors, rate limits and server failures. They retain the body and idempotency key within a call. Persist your own idempotency key for recovery across process restarts. A new SDK call can generate a new key; it is not automatically the same business operation. PATCH requests and embedded-session creation are not automatically retried.