TypeScript SDK

Install

npm install @polpo-ai/sdk

Configure

import { PolpoClient } from "@polpo-ai/sdk";

const client = new PolpoClient({
  baseUrl: "https://{project}.polpo.cloud",
  apiKey: process.env.POLPO_API_KEY,
  user: "usr_123",
});

Option	Type	Description
`baseUrl`	`string`	Project or self-hosted base URL
`apiKey`	`string`	Project API key
`apiPrefix`	`string`	Override `/v1` on Cloud or `/api/v1` when self-hosted
`fetch`	`typeof fetch`	Custom fetch implementation
`user`	`string`	Default external user identifier for chat, tasks, and missions

projectId remains in the configuration type for compatibility but is deprecated and ignored.

Chat

const stream = client.chatCompletionsStream({
  agent: "backend-dev",
  loop: "implementation-flow",
  model: "anthropic/claude-sonnet-4-5",
  sandbox: {
    isolation: "fresh",
    lifecycle: {
      onRelease: "pool",
      stopAfterIdleMinutes: 30,
      deleteAfterStopMinutes: 60,
    },
  },
  messages: [{ role: "user", content: "Review the auth module" }],
  metadata: { tenant_id: "tenant_123" },
});

for await (const chunk of stream) {
  process.stdout.write(chunk.choices[0]?.delta?.content ?? "");
}

console.log(stream.sessionId, stream.aborted);

messages is required. agent is optional and omission selects the orchestrator. Other fields are loop, sessionId, user, metadata, sandbox, and stream. model can override the selected agent model for this request. Sandbox isolation and release behavior can be configured independently. See Sandboxes for the complete policy and precedence. ChatCompletionStream exposes sessionId, aborted, askUser, missionPreview, vaultPreview, openFile, navigateTo, and openTab, plus abort().

const response = await client.chatCompletions({
  messages: [{ role: "user", content: "Summarize the project" }],
});
console.log(response.choices[0].message.content);

Sessions

const { sessions } = await client.getSessions();
const { session, messages } = await client.getSessionMessages(sessions[0].id);
await client.renameSession(session.id, "Architecture review");
await client.deleteSession(session.id);

Pass sessionId to chat calls to continue a session. The caller should still include the message history needed by the model.

Agents and loops

await client.addAgent({
  name: "qa-engineer",
  role: "Writes and runs tests",
  model: "anthropic/claude-sonnet-4-5",
  allowedTools: ["read", "write", "edit", "bash"],
  sandbox: {
    isolation: "fresh",
    lifecycle: { onRelease: "destroy" },
  },
  assignedLoops: ["qa-flow"],
});

await client.updateAgent("qa-engineer", { reasoning: "high" });
const agent = await client.getAgent("qa-engineer");
const agents = await client.getAgents();
await client.removeAgent("qa-engineer");

Use getLoops, getLoop, createLoop, updateLoop, and deleteLoop for project loops. Agents only store assignedLoops; a chat or task selects a loop explicitly.

Memory and legacy vault

const shared = await client.getMemory();
await client.saveMemory("Updated project context");
const agentMemory = await client.getAgentMemory("backend-dev");
await client.saveAgentMemory("backend-dev", "Prefers functional patterns");

await client.saveVaultEntry({
  agent: "emailer",
  service: "smtp",
  type: "smtp",
  credentials: { host: "smtp.example.com", user: "bot", pass: "secret" },
});
const entries = await client.listVaultEntries("emailer");
await client.patchVaultEntry("emailer", "smtp", { credentials: { pass: "rotated" } });
await client.removeVaultEntry("emailer", "smtp");

Vault list operations return metadata and credential key names, never values. Use project Connections for new shared API keys, OAuth accounts, and external integrations. Vault APIs remain for compatibility with agent-scoped secrets.

Files

const { roots } = await client.getFileRoots();
const { path, entries } = await client.listFiles("/src");
const preview = await client.previewFile("/src/index.ts");
const response = await client.readFile("/src/index.ts");
await client.uploadFile("/workspace", file, file.name);
await client.createDirectory("/src/utils");
await client.renameFile("/src/old.ts", "new.ts");
await client.deleteFile("/src/obsolete.ts");
const results = await client.searchFiles("config", "/src", 20);

Attach an uploaded path with a chat content part such as { type: "file", file_id: "/workspace/report.pdf" }. Agents use their configured file or image tools to inspect it.

Sandbox volumes

Catalog resources and agent grants are distinct from the sandbox.volumes selection sent with a run:

const catalog = await client.listSandboxVolumes();

const volume = await client.createSandboxVolume({
  name: "reference",
  strategy: "hydrated",
  access: "read-only",
});

await client.setSandboxVolumeGrant("researcher", volume.id, {
  access: "read-only",
});

await client.updateSandboxVolume("reference", {
  label: "Reference files",
});

const { grants } = await client.listSandboxVolumeGrants("researcher");
await client.revokeSandboxVolumeGrant("researcher", volume.id);
await client.deleteSandboxVolume("reference");

The SDK never accepts storage credentials or provider prefixes. Grant methods use immutable volume ids; runtime selection uses stable volume names.

Skills

await client.createSkill({
  name: "code-review",
  description: "Reviews changes for correctness",
  content: "Review behavior, tests, and error handling.",
  allowedTools: ["read", "grep"],
});

await client.installSkills("github:acme/polpo-skills", {
  skillNames: ["testing"],
  force: false,
});
await client.assignSkill("code-review", "backend-dev");
await client.unassignSkill("code-review", "backend-dev");
await client.deleteSkill("code-review");

Schedules and playbooks

await client.createSchedule({
  missionId: "mission_abc123",
  expression: "0 2 * * *",
  recurring: true,
});
await client.updateSchedule("mission_abc123", { enabled: false });
await client.deleteSchedule("mission_abc123");

await client.createPlaybook({
  name: "onboard-repo",
  description: "Analyze a repository",
  mission: {
    tasks: [{ title: "Scan", description: "Map the repository", assignTo: "analyst" }],
  },
});
await client.deletePlaybook("onboard-repo");

Live events

getEventsUrl() and EventSourceManager use an apiKey query parameter for browser EventSource compatibility. The current Cloud authentication middleware does not accept query-string API keys, so these helpers cannot authenticate a direct Cloud SSE connection. Use a server-side SSE client with an Authorization header or an application-owned authenticated proxy. See Events.

Errors

import { PolpoApiError } from "@polpo-ai/sdk";

try {
  await client.getAgent("missing");
} catch (error) {
  if (error instanceof PolpoApiError) {
    console.error(error.code, error.statusCode, error.message);
  }
}

Application databases

The Databases API uses polpo.listData(), polpo.createData({name,schema}) and polpo.data(nameOrId).

const db = polpo.data("crm");
const page = await db.table("contacts").list({ limit: 25 });
const result = await db.query({
  sql: "SELECT count(*) AS total FROM contacts WHERE email = $1",
  params: ["mario@example.test"],
});

db.transaction(operations, {idempotencyKey}) runs atomic typed record operations. db.query supports scoped SQL and explicit write mode; it is a bounded PostgreSQL subset. Administrators use db.migrate for additive JSON schemas, db.migrateSql for supported SQL DDL/backfills and db.migrations() for history. Keep application keys server-side and enforce your application’s user permissions before calling Polpo. The SDK never needs a Neon key or database URL.

CLI

SDKs

Reference

Integrations

Templates

Resources

TypeScript SDK

Install

Configure

Chat

Sessions

Agents and loops

Memory and legacy vault

Files

Sandbox volumes

Skills

Schedules and playbooks

Live events

Errors

Application databases

​Install

​Configure

​Chat

​Sessions

​Agents and loops

​Memory and legacy vault

​Files

​Sandbox volumes

​Skills

​Schedules and playbooks

​Live events

​Errors

​Application databases

Install

Configure

Chat

Sessions

Agents and loops

Memory and legacy vault

Files

Sandbox volumes

Skills

Schedules and playbooks

Live events

Errors

Application databases