TypeScript SDK

@capydb/sdk - fully typed client for the control plane, generated from the OpenAPI document.

What it is

@capydb/sdk is the official TypeScript SDK for the CapyDB control plane - projects, preview databases, backups & PITR restores, imports, Studio SQL, webhooks, and deployment integrations.

It is generated from the control plane's OpenAPI document (GET https://capydb.dev/api/capydb/v1/openapi.json) with @hey-api/openapi-ts, so every operation and model is fully typed and always in lockstep with the API. The generated sources are committed to the package repo, so you can audit exactly what ships.

Install

pnpm add @capydb/sdk

Usage

import { createCapyDB } from "@capydb/sdk";

const capydb = createCapyDB({ apiKey: process.env.CAPYDB_API_KEY! });

// List projects
const projects = await capydb.listProjects();

// Create a preview database for a branch and wait on its job
const preview = await capydb.createPreviewDatabase({
  path: { projectID: "prj_..." },
  body: { name: "pr-42", mode: "clone", ttl_hours: 72 },
});

// Fetch connection strings
const connections = await capydb.getPreviewDatabaseConnections({
  path: { previewID: preview.data!.preview.id },
});

Operation names match the OpenAPI operationIds, so the per-tag API pages double as SDK documentation: every endpoint there is a method here.

Ephemeral databases (no account)

createCapyDB() works without an API key for the two calls that need none: creating an ephemeral database and reading it back with its claim token.

const anonymous = createCapyDB({});

const { data: created } = await anonymous.createEphemeralDatabase();
// created.claim_token is shown once and cannot be recovered - keep it.

const { data: details } = await anonymous.getEphemeralDatabase({
  path: { projectID: created!.ephemeral_database.project_id },
  headers: { "X-CapyDB-Claim-Token": created!.claim_token },
});
// details.connections.pooled_url once details.ephemeral_database.state === "ready"

// Keep it: claim it into your organization. This call does need an org-wide key.
await capydb.claimEphemeralDatabase({
  path: { projectID: created!.ephemeral_database.project_id },
  body: { claim_token: created!.claim_token },
});

Async jobs

Lifecycle calls return 202 with a job - same contract as the raw API. Poll getJob until completed/failed, or lean on webhooks for push-based completion.

Key scoping

Use a project-scoped API key (Dashboard → Settings → API keys, with a project_id) for CI and integrations: it can only touch the one project it was minted for. See Authentication.