Dedalus

This library provides convenient access to the Dedalus REST API from TypeScript or JavaScript.

The full API of this library can be found in api.md.

Contents

• Installation
• Usage
• API Reference
• Authentication
• Errors
• Client Options
• Request Options
• Retries and Timeouts
• Pagination
• Helpers
• Logging
• Requirements

Installation

npm install dedalus

Usage

import Dedalus from 'dedalus';

const client = new Dedalus({
  apiKey: process.env['DEDALUS_API_KEY'], // defaults to the DEDALUS_API_KEY env var
});

const machine = await client.machines.create({
  autosleep: '300s',
  memory_mib: 4096,
  storage_gib: 10,
  vcpu: 1,
});

console.log(machine.machine_id);

The examples in the following sections assume a client configured as shown above.

See the API reference for every available operation.

Authentication

Pass credentials to the generated client constructor. Environment variables are read automatically when supported by the target runtime.

Option	Type	Default	Description
apiKey	string | provider	-	API key authentication using Bearer token Defaults to DEDALUS_API_KEY.
xAPIKey	string | provider	-	API key authentication using X-API-Key header Defaults to DEDALUS_X_API_KEY.

Declared schemes:

• ApiKeyAuth API key in header x-api-key
• BearerAuth bearer token

Errors

Non-success responses throw generated API errors. Error objects expose status, headers, response body, and request metadata where the target runtime supports it.

import { APIError } from 'dedalus';

try {
  const machine = await client.machines.create({
    autosleep: '300s',
    memory_mib: 4096,
    storage_gib: 10,
    vcpu: 1,
  });
} catch (err) {
  if (err instanceof APIError) {
    console.log(err.status, err.name, err.headers);
  }
  throw err;
}

Documented error statuses: 400, 401, 403, 409, 429, 500, 502, 503, default.

Client Options

Configure the generated client by setting any of these options when you create it.

import Dedalus from 'dedalus';

const client = new Dedalus({
  timeout: 60000,
  maxRetries: 2,
  logLevel: 'debug',
});

Option	Type	Default	Description
apiKey	string | AuthTokenProvider	process.env["DEDALUS_API_KEY"]	API key authentication using Bearer token
xAPIKey	string | AuthTokenProvider	process.env["DEDALUS_X_API_KEY"]	API key authentication using X-API-Key header
baseURL	string | null	process.env["DEDALUS_BASE_URL"]	Override the default API base URL. Pass null when selecting a configured environment.
timeout	number	60000	Maximum time in milliseconds to wait for a response before aborting a request.
maxRetries	number	2	Number of retries for temporary failures.
defaultHeaders	HeadersInit	-	Headers sent with every request.
defaultQuery	Record<string, string | undefined>	-	Query parameters sent with every request.
fetchOptions	RequestInit	-	Additional fetch options sent with every request.
fetch	Fetch	-	Custom fetch implementation.
logLevel	"off" | "error" | "warn" | "info" | "debug" | null	process.env["DEDALUS_LOG"]	Controls request and retry debug logging.
logger	Logger | null	console	Custom logger implementation.

Request Options

Option	Type	Default	Description
headers	HeadersInit	-	Per-request headers.
query	Record<string, unknown>	-	Per-request query parameters.
body	unknown	-	Override the generated request body.
timeout	number	-	Per-request timeout in milliseconds.
maxRetries	number	-	Per-request retry count.
signal	AbortSignal	-	Abort an in-flight request.
fetchOptions	RequestInit	-	Per-request fetch options.
idempotencyKey	string	-	Idempotency key for retry-safe operations. Applies to this request and its retries.

Retries and Timeouts

Generated clients support request timeouts and retry temporary failures such as network errors, 408, 409, 429, and 5xx responses. Retry delays honor Retry-After headers when present. Tune the retry and timeout client options shown above, or override them per request.

Pagination

List endpoints return paginated results you can iterate directly; the SDK fetches subsequent pages for you.

const page = await client.machines.list();

Helpers

• Use .withResponse() on any request to inspect both parsed data and the raw Response object.
• Every operation returns an APIPromise, so you can await it directly or chain .withResponse().

Logging

• Set logLevel: "debug" to log request URLs, options, response status, response headers, and retry attempts.
• Pass a custom logger to route logs into your own observability pipeline.
• Set logLevel: null to disable environment-driven logging.

Requirements

• Node.js 20+, a modern browser, or any runtime with fetch support

Powered by Scalar.

Verify a local package

Run pnpm install --frozen-lockfile --ignore-scripts, pnpm build, and pnpm test:package to install a tarball in an isolated directory and check both ESM and CommonJS imports. The probe uses a public fixture URL and does not send an API request. It catches runtime dependencies that a source-tree build can hide.

CI runs the same package check. Edit ci/sdk-ci.ts and run pnpm ci:generate to change its generated workflow.

Automatic retry identity

Client-generated idempotency keys use the API's 32-character UUIDv7 format. Automatic retries reuse the original key. Independent submissions receive new keys, and callers can still supply an explicit key when retrying a saved request.