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. The four SDK pages are organized the same way: install and authenticate, send your first request, paginate, handle errors, and verify webhooks. Pick the SDK that matches your stack:

Python

pip install surge-sdk. Sync and async clients.

TypeScript

npm install @surgeapi/node. Full TypeScript types.

Ruby

gem "surge_api". Sorbet types included.

Elixir

{:surge_api, "~> 0.2"}. Phoenix WebhookPlug and WebhookHandler.

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.

# Reads SURGE_API_KEY from environment
surge = Surge()

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

// 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.

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

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.

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

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.