TypeScript SDK quickstart

The American Cloud TypeScript SDK is a typed client for the public API, generated from the same OpenAPI specification that drives the platform (via Fern). It works in both TypeScript and JavaScript projects. For the language-agnostic picture — supply-chain posture, the SDK-vs-MCP decision — see the SDKs overview.

Install

npm install @americancloud/sdk
# or
pnpm add @americancloud/sdk

The published package is @americancloud/sdk. Pin the exact version you install and upgrade deliberately — see Versioning below.

Authenticate

Every request is signed with an API key pair — two values sent as headers. You pass both to the client at construction:

Create and manage keys at console.americancloud.com/api-keys. The client secret is shown once at creation — store it in an environment variable or secrets manager, never in your repository. If it's lost, revoke the key and create a new one.

Keys are scoped when you create them:

• read-only keys can call GET endpoints only — listing and reading resources.
• read-write keys have full access, including creating and destroying resources.

Start with a read-only key while you're exploring, and switch to read-write when you're ready to provision. Load both values from the environment rather than hard-coding them:

import { AmericancloudApiClient } from "@americancloud/sdk";
 
const client = new AmericancloudApiClient({
  apiKey: process.env.AMERICANCLOUD_API_CLIENT_ID!,
  apiClientSecret: process.env.AMERICANCLOUD_API_CLIENT_SECRET!,
});

The client targets the production API at https://api.americancloud.com by default. The client is namespaced by resource — client.vms, client.regions, client.sshKeys, client.dnsZones, and so on — and each namespace exposes the operations available on that resource.

Your first call

A read-only key is enough for this. List the regions you can deploy into, then list any VMs on the account:

const regions = await client.regions.listRegions();
for (const region of regions.data) {
  console.log(`${region.label} — ${region.displayName}`);
}
 
const vms = await client.vms.listVms();
console.log(`You have ${vms.total} VM(s).`);

Both list calls return a paginated envelope: total (the count across all pages) plus a data array of items. The label on each region is the value you pass as region when creating a VM.

Estimate cost, then create

Before creating a VM you can preview its price with getCostEstimateVms. It accepts the same request body as createVms, so you can estimate and create from one object — no surprises on the bill. The estimate is safe to call with a read-only key; the create step needs a read-write key.

const spec = {
  name: "web-01",
  region: "us-west-0",
  vmPackage: "standard-custom",
  vmSpecs: {
    vcpu: 2,
    memoryMb: 2048,
    rootDiskGb: 50,
  },
  image: "ubuntu-22.04",
  subscriptionPeriod: "monthly" as const,
  keypairs: ["my-laptop"],
};
 
// Preview pricing — creates nothing.
const estimate = await client.vms.getCostEstimateVms(spec);
console.log("Monthly total:", estimate.estimates.monthly.total);
console.log("Hourly total:", estimate.estimates.hourly.total);
 
// Happy with the number? Create it with the same object.
const vm = await client.vms.createVms(spec);
console.log("Created VM:", vm);

The estimate response splits cost into estimates.hourly and estimates.monthly, each with base, discount, and total fields. The keypairs array references SSH key pairs by name — list yours with client.sshKeys.listSshKeys() or create one through the same namespace. subscriptionPeriod accepts "hourly" or "monthly".

Handle errors

Failed calls throw. The base error type is AmericancloudApiError, exported from the package root; it carries the HTTP statusCode, the parsed response body, and a human-readable message. Catch it to branch on the status:

import { AmericancloudApiError } from "@americancloud/sdk";
 
try {
  const vm = await client.vms.getVms({ id: "does-not-exist" });
  console.log(vm);
} catch (err) {
  if (err instanceof AmericancloudApiError) {
    console.error(`API error ${err.statusCode}:`, err.body);
    if (err.statusCode === 404) {
      // Resource doesn't exist (or isn't yours).
    }
  } else {
    throw err; // network/abort error — re-throw or handle separately
  }
}

err.statusCode is the standard HTTP status — 400 for a bad request, 401 for a missing or invalid key, 403 when your key's scope doesn't permit the operation (e.g. a read-only key calling a create endpoint), 404 for a resource that doesn't exist, and 409 for a conflicting state.

Pagination

List endpoints accept optional page (1-indexed, defaults to 1) and pageSize (defaults to 100, server cap 500) parameters, and return total alongside the data array. Compare how many items you've collected against total to walk every page:

async function listAllVms() {
  const all = [];
  let page = 1;
  const pageSize = 100;
 
  while (true) {
    const res = await client.vms.listVms({ page, pageSize });
    all.push(...res.data);
    if (all.length >= res.total) break;
    page += 1;
  }
 
  return all;
}

Versioning

The SDK version is generated in lockstep with the API: SDK 1.3.0 is generated from API version 1.3.0, so the version you install tells you exactly which API surface you're coding against. Patch and minor releases are backward-compatible and safe to upgrade; a major release tracks a new API URL version and may require code changes. Pin an exact version and upgrade on your own schedule. The SDKs overview covers the full versioning policy.

Because additive API changes (new endpoints, optional fields, new enum values) can ship within a major version, write code that tolerates unknown response fields and unrecognized enum values gracefully.

Next steps

• SDKs overview — versioning policy, supply-chain posture, and the SDK-vs-MCP decision
• Go quickstart and Python quickstart — the same API in two more languages
• API reference — every endpoint, request shape, and response shape, each mapping directly to an SDK method
• Source on GitHub — report issues or browse the generated client
• MCP server — if you want an AI assistant to manage infrastructure conversationally instead of writing code, this is the path (it's built on this SDK)