Skip to main content
NearNode provides official SDKs for the two most common integration languages. Every SDK is a thin, typed wrapper around the REST API — no magic, no vendor lock-in.

​
Official SDKs

Node.js / TypeScript

Full TypeScript types. Works in Node.js 18+, Deno, and Bun.

Python

Sync and async clients. Python 3.9+.

​
Node.js

​
Installation

npm install @nearnode/sdk

​
Quick Start

import { NearNode } from '@nearnode/sdk';

const client = new NearNode({
  apiKey: process.env.NEARNODE_API_KEY,
});

// Create a node
const node = await client.nodes.create({
  label: 'Basel HQ Entrance',
  function_type: 'redirect',
  payload: { url: 'https://acme.com/checkin' },
});

console.log(node.url); // https://nearnode.io/v/r5v5z7t2

// List all nodes
const { data: nodes } = await client.nodes.list();

// Update a node
await client.nodes.update('r5v5z7t2', {
  payload: { url: 'https://acme.com/new-checkin' },
});

// Create a batch
const batch = await client.batches.create({
  label: 'Q1 2026 Cards',
  prefix: 'VID-2026',
  quantity: 100,
  function_type: 'vcard',
  base_payload: {
    organization: 'Acme Corp',
    website: 'https://acme.com',
  },
});

// Query analytics
const analytics = await client.analytics.query('r5v5z7t2', {
  period: '30d',
});

​
TypeScript Types

The SDK exports all request and response types: 
import type { Node, Batch, AnalyticsEvent, RoutingRule } from '@nearnode/sdk';

​
Python

​
Installation

pip install nearnode

​
Quick Start

from nearnode import NearNode

client = NearNode(api_key="sk_live_...")

# Create a node
node = client.nodes.create(
    label="Basel HQ Entrance",
    function_type="redirect",
    payload={"url": "https://acme.com/checkin"},
)

print(node.url)  # https://nearnode.io/v/r5v5z7t2

# List all nodes
nodes = client.nodes.list()

# Update a node
client.nodes.update("r5v5z7t2", payload={"url": "https://acme.com/new-checkin"})

# Create a batch
batch = client.batches.create(
    label="Q1 2026 Cards",
    prefix="VID-2026",
    quantity=100,
    function_type="vcard",
    base_payload={
        "organization": "Acme Corp",
        "website": "https://acme.com",
    },
)

# Async support
import asyncio
from nearnode import AsyncNearNode

async def main():
    client = AsyncNearNode(api_key="sk_live_...")
    nodes = await client.nodes.list()

asyncio.run(main())

​
Direct API Access

No SDK required. The REST API works with any HTTP client: 
curl -X POST https://nearnode.io/api/v1/nodes \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "label": "Basel HQ Entrance",
    "function_type": "redirect",
    "payload": { "url": "https://acme.com/checkin" }
  }'

​
Community Integrations

LanguagePackageMaintainer
Gogo-nearnodeCommunity
Rubynearnode-rubyCommunity
PHPnearnode-phpCommunity
Community SDKs are not officially supported. Use at your own discretion and verify compatibility with the current API version.

​
SDK Versioning

SDKs follow semantic versioning. Major versions correspond to API versions:
SDK VersionAPI VersionStatus
1.xv1Current
Pin your SDK version in production. Subscribe to the Changelog for breaking change announcements.