SDK API

Client methods, configuration options, and the production server-side endpoint for product feature flags.

Server-side essentials

Security and runtime requirements for every integration.

Official SDKs are server-side only.

Never expose API keys in browser or client code.

Store API keys in environment variables.

The default fallback is false.

SDKs fail safely if SwitchPilot is unreachable.

Default cache TTL: 60 seconds.

Default stale-if-error window: 5 minutes.

Prefer an SDK

The Node and Python SDKs handle authentication, response validation, timeouts, caching and safe fallbacks. Call the HTTP endpoint directly only when testing or building a server-side integration.

Node.js methods

Node.js

await flags.isEnabled("new-dashboard");       // Promise<boolean>
await flags.isEnabled("new-dashboard", true); // Per-call fallback
await flags.getAll();                           // Cached flags
await flags.refresh();                          // Force a fetch
flags.getStatus();                              // Local status

Python methods

Python

flags.is_enabled("new-dashboard")        # bool
flags.is_enabled("new-dashboard", True)  # Per-call fallback
flags.get_all()                              # Cached flags
flags.refresh()                              # Force a fetch
flags.get_status()                           # Local status

Configuration

Purpose	Node.js	Python	Default
Project key	apiKey	api_key	Required
SDK URL	endpoint	endpoint	Production URL
Safe value	fallback	fallback	false
Request timeout	timeoutMs	timeout	2 seconds
Cache lifetime	cacheTtlMs	cache_ttl	60 seconds
Stale on error	staleIfErrorMs	stale_if_error	5 minutes

HTTP endpoint

terminal

curl -H "Authorization: Bearer sp_live_your_project_key" \
  https://switchpilot-one.vercel.app/api/sdk/flags

The endpoint returns all boolean flags belonging to the project whose API key is supplied. API keys are project-scoped credentials: send them only from trusted server-side code.

Conditional synchronization

Responses include an ETag. Send it in If-None-Match on the next synchronization; an unchanged configuration returns 304 with no body.

Successful response

200 OK

{
  "flags": {
    "new-dashboard": true,
    "billing-v2": false
  },
  "updatedAt": "2026-07-15T00:08:13.477Z"
}

Response status

200 — returns the project flags

304 — configuration unchanged; no body

401 — missing, malformed or invalid key

429 — rate limited; inspect Retry-After

500 — internal server error

SDK checks keep the Last Known Good configuration during temporary failures while its stale window remains valid. The configured fallback is the last resort; its default is false.