Login

TypeScript SDK quickstart

Last updated:

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

sh
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 carries an API token in the Authorization: Bearer header. Pass the token to the client as token, or set AMERICANCLOUD_API_TOKEN and omit it.

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

A token has the permissions you choose when you create it:

  • Read-only — list, read, and price resources.
  • Full access — also create, change, and delete resources.
  • Custom — pick read or manage for each service.

Start with a Read-only token while you're exploring, and create a Full access token when you're ready to provision. client.whoami.getWhoami() returns the permissions the token has now. Load the token from the environment rather than hard-coding it:

ts
import { AmericancloudApiClient } from "@americancloud/sdk";
 
const client = new AmericancloudApiClient({
  token: process.env.AMERICANCLOUD_API_TOKEN!,
});

SDK 1.8.0 and later take only a token. If you still use a legacy API key (client ID and secret), stay on 1.7.x or replace the key with a token.

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 token is enough for this. List the regions you can deploy into, then list any VMs on the account:

ts
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.

[ typescript sdk · first call ]
Running the snippet above — real regions and your VM count, fully typed.

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 token; the create step needs a Full access token.

ts
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:

ts
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 token, 403 when your token's permissions don't allow the operation (e.g. a Read-only token 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:

ts
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.8.0 is generated from API version 1.8.0, so the version you install tells you exactly which API surface you're coding against. A major release tracks a new API URL version and may require code changes. Read the changelog before any upgrade. From 1.8.0, the client takes an API token (token). 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)
Contact us