> ## Documentation Index
> Fetch the complete documentation index at: https://docs.surge.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Using the SDKs

> Choose a Surge SDK, authenticate with an env var or constructor, and make requests for endpoints without typed methods.

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:

<CardGroup cols={2}>
  <Card title="Python" icon="python" href="./python">
    `pip install surge-sdk`. Sync and async clients.
  </Card>

  <Card title="TypeScript" icon="js" href="./typescript">
    `npm install @surgeapi/node`. Full TypeScript types.
  </Card>

  <Card title="Ruby" icon="gem" href="./ruby">
    `gem "surge_api"`. Sorbet types included.
  </Card>

  <Card title="Elixir" icon="droplet" href="./elixir">
    `{:surge_api, "~> 0.2"}`. Phoenix `WebhookPlug` and `WebhookHandler`.
  </Card>
</CardGroup>

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

<CodeGroup>
  ```python Python theme={null}
  # Reads SURGE_API_KEY from environment
  surge = Surge()

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

  ```typescript TypeScript theme={null}
  // Reads SURGE_API_KEY from environment
  const surge = new Surge();

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

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

<CodeGroup>
  ```python Python theme={null}
  messages = surge.messages.list(account_id="acct_01j...")
  ```

  ```typescript TypeScript theme={null}
  const messages = await surge.messages.list({ accountId: "acct_01j..." });
  ```
</CodeGroup>

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

<CodeGroup>
  ```python Python theme={null}
  response = surge.request("GET", "/accounts/acct_01j.../status", params={
      "capabilities": "local_messaging"
  })
  ```

  ```typescript TypeScript theme={null}
  const response = await surge.get("/accounts/acct_01j.../status", {
    query: { capabilities: "local_messaging" },
  });
  ```
</CodeGroup>

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.