Using the SDKs

Surge has official SDKs for Python, TypeScript, Ruby, and Elixir. Each SDK wraps the REST API with language-native types, pagination helpers, retry logic, error handling, and webhook signature verification.

Choose your language

• Python — pip install surge-sdk; supports sync and async clients
• TypeScript — npm install @surgeapi/node; full TypeScript types
• Ruby — gem "surge_api"; Sorbet types included
• Elixir — {:surge_api, "~> 0.1"}; includes a Phoenix WebhookPlug

Authentication

All SDKs read the API key from the SURGE_API_KEY environment variable by default. You can also pass it directly to the client constructor.

# Python: reads SURGE_API_KEY from environment
surge = Surge()

# Or explicitly:
surge = Surge(api_key="sk_live_...")

// TypeScript: reads SURGE_API_KEY from environment
const surge = new Surge();

// Or explicitly:
const surge = new Surge({ apiKey: "sk_live_..." });

Account scoping

All account-scoped SDK methods take the account_id as a parameter (or first positional argument). This maps to the account ID in the request path.

# Python
messages = surge.messages.list(account_id="acct_01j...")

// TypeScript
const messages = await surge.messages.list({ accountId: "acct_01j..." });

Making requests not covered by an explicit function

Every SDK exposes a raw HTTP method for endpoints that don't have a dedicated SDK function. For example, new endpoints in beta or private APIs.

# Python
response = surge.request("GET", "/accounts/acct_01j.../status", params={
    "capabilities": "local_messaging"
})

// TypeScript
const response = await surge.get("/accounts/acct_01j.../status", {
  query: { capabilities: "local_messaging" },
});

Use this escape hatch when you need to call an endpoint before the SDK has a typed method for it. You get full request/response types from the SDK client but no IDE autocompletion on the response body.