Getting Started

Get from zero to a working API call against the cPod platform. Use the local emulator during development — no credentials, no cloud account required.

Just want to run code? Start the emulator with node src/index.js (from the emulator/ folder) and any Bearer token works. Full details in the Emulator guide.

Start the local emulator

Clone the repo and start the emulator:

git clone https://github.com/cpod-ai/cpod-sdk.git
cd cpod-sdk/emulator
npm install
node src/index.js

Verify it’s running:

curl http://localhost:4000/v1/health
# {"status":"ok","version":"1.0.0","uptime":3,"edm":{"people":8,...}}

The emulator has 100+ seed records and accepts any Bearer token — no OAuth setup required for local dev.

Install the SDK

npm install @cpod/sdk

Node.js 18+. Full TypeScript types included.

pip install cpod-sdk

Python 3.9+. Async-first with asyncio.

go get github.com/cpod-ai/cpod-sdk-go

Go 1.21+

dotnet add package Cpod.SDK

.NET 8+

Set environment variables

For the local emulator — no registration needed:

export CPOD_API_URL=http://localhost:4000
export CPOD_API_KEY=dev-token

For production, swap in your real credentials:

export CPOD_API_URL=https://api.cyberpod.app
export CPOD_API_KEY=cpk_live_xxxxxxxxxxxxxxxxxxxx

Make your first call

import { CpodClient } from '@cpod/sdk'
 
// Reads CPOD_API_URL and CPOD_API_KEY from env
const sdk = CpodClient.fromEnv()
 
// List people from the EDM
const people = await sdk.people.list({ limit: 5 })
console.log(people.items)
// → [{ id: 'per-001', displayName: 'Alice Chen', email: '...', ... }, ...]

import asyncio
from cpod import CpodClient
 
async def main():
    # Reads CPOD_API_URL and CPOD_API_KEY from env
    sdk = CpodClient.from_env()
 
    people = await sdk.people.list(limit=5)
    for person in people.items:
        print(person.display_name)
 
asyncio.run(main())

package main
 
import (
    "context"
    "fmt"
    cpod "github.com/cpod-ai/cpod-sdk-go"
)
 
func main() {
    // Reads CPOD_API_URL and CPOD_API_KEY from env
    sdk, err := cpod.NewFromEnv()
    if err != nil { panic(err) }
 
    people, err := sdk.People.List(context.Background(), nil)
    if err != nil { panic(err) }
    for _, p := range people.Items {
        fmt.Println(p.DisplayName)
    }
}

using Cpod.SDK;
 
// Reads CPOD_API_URL and CPOD_API_KEY from env
var sdk = CpodClient.FromEnv();
 
var people = await sdk.People.ListAsync(limit: 5);
foreach (var person in people.Items)
    Console.WriteLine(person.DisplayName);

Environment Variables

All four SDKs read the same two variables:

Variable	Required	Description
`CPOD_API_URL`	Yes	API base URL — `http://localhost:4000` (emulator) or `https://api.cyberpod.app` (prod)
`CPOD_API_KEY`	Yes	Your API key — any string for local emulator, real key for production

⚠️

Never commit credentials to source control. Use environment injection (Docker secrets, Vault, AWS Secrets Manager, GitHub Secrets). The key should only exist in your secrets manager and the running process environment.

What happens on each SDK call

sdk.people.list()
    │
    ▼
GET http://localhost:4000/v1/people
Authorization: Bearer <CPOD_API_KEY>
    │
    ▼
cpod-backend (or emulator)
    extracts tenantId + appId from token
    scopes the query automatically
    │
    ▼
{ items: [...], total: 8 }

Your app never passes tenantId or appId — the backend extracts them from the token server-side. Every call is automatically isolated to your tenant.

What’s next

Emulator — full emulator reference, seed data, CI usage
SDK Reference — all methods for TypeScript, Python, Go, .NET
Enterprise Data Model — what entities exist and how they relate
Authentication — OAuth flows, scopes, production setup
Architecture — how the platform works under the hood

Design Decisions Authentication