NSSurge Python API Client

Python implementation of the Surge HTTP API spec client using aiohttp.

You can use it to get/set Surge rules / policies / proxy groups, get recent requests / events and much more.

This projects fully implements the Surge HTTP API spec.

If you're looking for a command line tool to interact with your running Surge app, check out NSSurge CLI.

NSSurge Python API Client
- Installation
  - pip
- Usage
- Develop
- See also

Installation

pip

$ pip install nssurge-api

Usage

# source: https://github.com/tddschn/nssurge-cli/blob/master/nssurge_cli/cap_commands.py
from nssurge_cli.types import OnOffToggleEnum
from nssurge_api import SurgeAPIClient
from nssurge_api.types import Capability
import asyncio

async def get_set_cap(
    capability: Capability, on_off: OnOffToggleEnum | None = None
) -> bool | tuple[bool, bool]:
    """
    Get or set a capability
    """
    async with SurgeAPIClient(*get_config()) as client:
        state_orig = await get_cap_state(client, capability)
        match on_off:
            case OnOffToggleEnum.on | OnOffToggleEnum.off:
                await client.set_cap(capability, s2b(on_off))
            case OnOffToggleEnum.toggle:
                await client.set_cap(capability, not state_orig)
            case _:
                return state_orig
        state_new = await get_cap_state(client, capability)
        return state_orig, state_new

Develop

$ git clone https://github.com/tddschn/nssurge-api.git
$ cd nssurge-api
$ poetry install

Metadata

Release files for nssurge-api 1.0.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for nssurge-api 1.0.1
File	Size	Uploaded
nssurge_api-1.0.1.tar.gz	82.2 kB	Feb 19, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for nssurge-api 1.0.1
File	Interpreter	ABI	Platform	Reset
nssurge_api-1.0.1-py3-none-any.whl 6.8 kB Feb 19, 2026	Python 3	none	any	Details

Total release size: 89.0 kB

Release files / nssurge_api-1.0.1.tar.gz

Download URL	nssurge_api-1.0.1.tar.gz
Size	82.2 kB
Tags	Source
SHA-256 checksum How to use checksums	`498a3efcd7eb0cbdbe029f89cf3695a31842fd1413e15b3d017ee4f9bda89be0`
BLAKE2b-256 checksum How to use checksums	`e4f81093e92b36b5c697f03f26323c80ca073caa4aa69edffc31fa649aa52408`
Upload date	Feb 19, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`uv/0.9.26 {"installer":{"name":"uv","version":"0.9.26","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}`

Release files / nssurge_api-1.0.1-py3-none-any.whl

Download URL	nssurge_api-1.0.1-py3-none-any.whl
Size	6.8 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`f7081f71b74e961a47f03c4517684817a558d6b29c2ee37cff76261ae50a1397`
BLAKE2b-256 checksum How to use checksums	`13f3d32e3f93587b0b027d872263126f19be1d64d8cd3ed5db9ef2326184ba53`
Upload date	Feb 19, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`uv/0.9.26 {"installer":{"name":"uv","version":"0.9.26","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}`