Login

Python SDK quickstart

Last updated: June 5, 2026

The official American Cloud Python SDK is a typed client for the public API, generated from the same OpenAPI document that drives the platform. It covers virtual machines, regions, SSH keys, DNS, networking, and more. For the language-agnostic picture — authentication model, versioning policy, and supply-chain posture — see the SDKs overview.

Install

The SDK is published to PyPI as americancloud:

sh
pip install americancloud

It requires Python 3.9+ and brings its own HTTP and validation dependencies (httpx, pydantic). Pin an exact version and upgrade deliberately — see Versioning below.

Authenticate

Every request needs both parts of an API key pair. 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 a secrets manager, never in your repo. If it's lost, revoke the key and create a new one.

Keys are scoped at creation:

  • read-only — can call GET endpoints only (list and read operations).
  • read-write — full access, including creating and deleting resources.

Start an integration with a read-only key and upgrade when you're ready to provision. Pass the pair to the client as api_key (the client ID) and api_client_secret:

python
import os
from americancloud import AmericancloudApi
 
client = AmericancloudApi(
    api_key=os.environ["AMERICANCLOUD_API_CLIENT_ID"],
    api_client_secret=os.environ["AMERICANCLOUD_API_CLIENT_SECRET"],
)

The client targets https://api.americancloud.com by default; pass base_url=... to override it.

Your first call

A read-only key is enough for everything in this section. List the regions available to your account:

python
regions = client.regions.list_regions()
 
for region in regions.data:
    print(region.label)

The client is namespaced by resource — client.regions, client.vms, client.ssh_keys, client.dns_zones, client.dns_records, and more. List methods return a page object whose items live on .data (see Pagination).

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

Estimate cost, then create

Before provisioning, preview pricing with get_cost_estimate_vms. It accepts the same body as the create call but doesn't create anything — so it's safe to call with a read-only key while you tune specs:

python
from americancloud import VmSpecsDto
 
spec = dict(
    name="web-01",
    region="us-west-0",
    vm_package="standard-custom",
    vm_specs=VmSpecsDto(vcpu=2.0, memory_mb=2048, root_disk_gb=50),
    image="ubuntu-22.04",
    subscription_period="hourly",
)
 
estimate = client.vms.get_cost_estimate_vms(**spec)
print(estimate.estimates.hourly.total)
print(estimate.estimates.monthly.total)

The estimate exposes estimates.hourly and estimates.monthly, each with base, discount, and total. Once the numbers look right, the same body creates the VM (this needs a read-write key):

python
vm = client.vms.create_vms(
    name="web-01",
    region="us-west-0",
    vm_package="standard-custom",
    vm_specs=VmSpecsDto(vcpu=2.0, memory_mb=2048, root_disk_gb=50),
    image="ubuntu-22.04",
    subscription_period="hourly",
    keypairs=["my-ssh-key"],
)
print(vm)

keypairs takes the names of SSH key pairs already on your account. To create one first — generating a new key pair and returning the private key once — call create_ssh_keys with just a name, or pass public_key=... to register a key you already hold:

python
key = client.ssh_keys.create_ssh_keys(name="my-ssh-key")

Async usage

For an asyncio application, use AsyncAmericancloudApi. It exposes the same namespaces and method names; each call is awaited:

python
import asyncio
import os
from americancloud import AsyncAmericancloudApi
 
async def main():
    client = AsyncAmericancloudApi(
        api_key=os.environ["AMERICANCLOUD_API_CLIENT_ID"],
        api_client_secret=os.environ["AMERICANCLOUD_API_CLIENT_SECRET"],
    )
    regions = await client.regions.list_regions()
    for region in regions.data:
        print(region.label)
 
asyncio.run(main())

Error handling

Failed calls raise a typed exception. Each subclass carries status_code, body, and headers:

python
from americancloud import NotFoundError, UnauthorizedError
 
try:
    region = client.regions.get_regions(id="123e4567-e89b-12d3-a456-426614174000")
except NotFoundError as err:
    print("Region not found:", err.status_code)
except UnauthorizedError as err:
    print("Check your API key pair:", err.body)

The available subclasses are BadRequestError (400), UnauthorizedError (401), ForbiddenError (403), NotFoundError (404), ConflictError (409), InternalServerError (500), and GatewayTimeoutError (504). To catch any API failure in one handler, catch the common base class:

python
from americancloud.core.api_error import ApiError
 
try:
    client.vms.list_vms()
except ApiError as err:
    print(err.status_code, err.body)

Pagination

List methods accept page (1-indexed, defaults to 1) and page_size (defaults to 100; server cap 500). The response carries the items on .data and the full match count on .total, so you can compute how many pages exist:

python
import math
 
page_size = 100
first = client.vms.list_vms(page=1, page_size=page_size)
pages = math.ceil(first.total / page_size)
 
all_vms = list(first.data)
for page in range(2, pages + 1):
    more = client.vms.list_vms(page=page, page_size=page_size)
    all_vms.extend(more.data)

Versioning

The SDK version is the same as the API platform version it was generated from — SDK 1.3.0 is generated from API 1.3.0, so the version you pin tells you exactly which API contract 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. The full policy is in the SDKs overview.

Write code that tolerates unknown response fields and unrecognized enum values gracefully — additive API changes can ship within a version.

Next steps