arct and python -m arct for terminal automation; see the CLI installation guide, including the macOS/Linux shell installer.
Install the Preview
Install an exact preview from PyPI or npm:
Install from Source
With Git installed, clone the source into your project directory:Authenticate and Read Resources
Create a token in Settings > API Tokens. Choose Read only for queries and Read & write for mutations. Supply it through your environment or secret manager:token= in Python or { token } in TypeScript overrides ARCT_TOKEN. Both SDKs use https://api.arct.cloud/v1 by default. Keep tokens server-side; never embed them in browser code.
- Python
- Async Python
- TypeScript / JavaScript
list() lazily retrieves every page, using 100 items per page by default and preserving filters. Python list_page() and TypeScript listPage() return one page with its pagination metadata. Page-number results can change while resources are being added or removed. See Pagination.
Create and Wait for a Server
ReplacePLAN_ID with a plan slug from plans.list() and TARGET_PLAN with the target resize plan. Choose a compatible image for the same location and a saved public key matching your local private key. These examples use the saved key name my-laptop; add your public key in SSH Keys first.
- Python
- TypeScript / JavaScript
201 with an order and a server that may still be provisioning or null. Waiters resolve acknowledged delayed creations and return the final server. Pre-orders can outlive the default 600-second deadline.
Python async resource calls use the same arguments with await; list() remains an async iterator. Use async with AsyncArct() to close the client.
Keep the original result: waiting does not overwrite its order or one-time password. Passwords are masked in normal representations and JSON. Deliberately unwrap a non-null password with Python result.password.get_secret_value() or TypeScript result.password.getSecretValue() only when needed. Omitted ssh_key_ids uses saved keys; an explicit empty array requests password access where supported. See Creating Servers.
Lifecycle and Completion
Start, stop, restart and reinstall return accepted HTTP
202 responses. Pass the original action result to a waiter: a bare server ID checks current status, while the original restart/reinstall result retains transition tracking. An initial stale running observation cannot prove those operations completed; a missed transition can time out as unverified.
Waiters poll every 5 seconds by default. Python uses timeout in seconds; TypeScript uses timeoutMs in milliseconds. Timeouts expose last_state in Python or lastState in TypeScript. Cancellation stops waiting and does not cancel an accepted remote operation. Cancel an async Python task or pass an AbortSignal in the final TypeScript request/wait options.
Resize Safely
Stop the server and wait forstopped before resizing. resize() obtains an eligible quote and sends its exact amount_due_today as expected_amount. To retain an already reviewed quote, supply that amount explicitly. A price_changed conflict requires a new decision; it is never silently re-quoted.
Python servers.wait_resize(id, resize_result) and TypeScript servers.waitUntil(id, 'stopped', { plan: 'TARGET_PLAN' }) check resize completion. HTTP 200 applied and 202 pending_payment are distinct. A pending payment may need dashboard action. Start the server only after the requested plan is confirmed applied; resizing and waiting never start it automatically.
Python monetary responses use Decimal. TypeScript monetary responses are JavaScript numbers, while automatic resize quoting preserves the original numeric text. Use a decimal string for an explicit TypeScript amount. Explicit Python expected_amount=None or TypeScript expected_amount: null opts out of price protection and accepts the current API price.
Errors and Retry Safety
Both SDKs exportAPIError and typed errors including AuthenticationError, PaymentRequiredError, PermissionDeniedError, NotFoundError, ConflictError, ValidationError, RateLimitError, ChargeUnknownError, UncertainOperationError, WaitTimeoutError and OperationFailedError.
API errors expose status, code and redacted details; validation errors also expose fields. Unknown error codes fall back to their HTTP status class. See the error reference for codes.
- Reads and eligible creation failures have at most three total attempts; creation retries retain the identical body and hostname. Other uncertain mutations are not blindly repeated.
429honorsRetry-Afterwithin the operation deadline. Local scheduling complements the server’s rate limits.details.order_intent_idor409 payment_pendingraisesChargeUnknownErrorwithout retrying. Keep support identifiers and verify billing before another purchase.- A lost response or a matching hostname cannot prove a successful order or recover its one-time password.
UncertainOperationErrorrequires reconciliation before repeating the action.
Available Resources and Limits
Resources areaccount, servers, locations, plans, images, invoices, and Python ssh_keys / TypeScript sshKeys. They cover the endpoints listed in this API reference; new response fields and enum strings are accepted.
You can enable automatic backups during server creation with Python enable_backups=True or TypeScript enable_backups: true, where the selected plan supports them. There are no backup/snapshot management endpoints or SDK management methods. Use the dashboard for backup and snapshot management. Token issuance/revocation, cards, invoice payment, password resets and VNC also remain dashboard operations.