Platform API client

@alienplatform/platform-api is a typed TypeScript client for the Alien REST API. Your backend uses it to create setup links, read deployment status, and manage releases and deployments for each customer.

import { Alien } from "@alienplatform/platform-api"

const alien = new Alien({ apiKey: process.env.ALIEN_API_KEY ?? "" })

const link = await alien.setupLinks.create({
  project: "acme",
  externalId: "customer-1",
  name: "customer-1",
})
console.log(link.deploymentLink)

The client is generated from the same OpenAPI document as the REST API reference, so every endpoint there has a method here. For code inside a deployment, use the runtime SDK, @alienplatform/sdk.

InstallCopy Anchor Link

npm install @alienplatform/platform-api

The package is ESM only and runs on Node.js 18 or newer, Bun, and Deno.

AuthenticateCopy Anchor Link

Create an API key under Settings → API Keys in the dashboard, or with alien api-keys create. Keys start with ax_. Store the key in your secret manager and pass it to the client:

import { Alien } from "@alienplatform/platform-api"

const alien = new Alien({
  apiKey: process.env.ALIEN_API_KEY ?? "",
})

• The client sends the key as Authorization: Bearer ax_....
• An API key belongs to one workspace, so you don't pass workspace.
• Give the key the smallest role that works, such as project.developer for a backend that creates setup links. See Authentication.
• Never use an API key in browser code.

Create a setup linkCopy Anchor Link

A setup link opens the deployment portal, where a customer's admin runs the initial setup in their own cloud. Create one when the customer clicks Deploy, not when the page renders (Add a Deploy button):

export async function connectCloud(tenantId: string) {
  const link = await alien.setupLinks.create({
    project: "acme",
    externalId: tenantId,
    name: tenantId,
  })
  return link.deploymentLink
}

The response has deploymentLink, token, deploymentGroup, and expiresAt.

List deploymentsCopy Anchor Link

List endpoints return { items, nextCursor }. Pass nextCursor back as cursor to read the next page:

let cursor: string | undefined
do {
  const page = await alien.deployments.list({ project: "acme", limit: 100, cursor })
  for (const deployment of page.items) {
    console.log(deployment.name, deployment.status)
  }
  cursor = page.nextCursor ?? undefined
} while (cursor)

Filter by deploymentGroup, status, name, or search. limit is 1 to 100 and defaults to 20.

Method namesCopy Anchor Link

Methods are grouped by resource: alien.projects, alien.deploymentGroups, alien.setupLinks, alien.deployments, alien.releases, alien.releaseChannels, alien.packages, alien.commands, alien.operations, alien.apiKeys, alien.machines, alien.domains, and others. Some common calls:

Methods that take an ID and a body accept the ID first. Check each request type in your editor or in the REST API reference.

ErrorsCopy Anchor Link

Failed requests throw APIError, which includes the HTTP status and the API error body:

import * as errors from "@alienplatform/platform-api/models/errors"

try {
  await alien.deployments.get({ id: "dep_missing" })
} catch (error) {
  if (error instanceof errors.APIError) {
    console.log(error.statusCode, error.data$.code, error.data$.retryable)
  }
}

Retry only when retryable is true. Validation, authorization, and conflict errors need a change to the request or to the resource's state first.

The error body also carries an optional remediation hint and the requestId to quote when you contact support.

Network failures throw ConnectionError, RequestTimeoutError, or RequestAbortedError. Configure retries and timeouts with the retryConfig and timeoutMs client options.

React Query hooksCopy Anchor Link

The package also exports React Query hooks from @alienplatform/platform-api/react-query and standalone tree-shakable functions from @alienplatform/platform-api/funcs/*. Use them only in a server-side or trusted context that can hold an API key.

NextCopy Anchor Link

• REST API: every endpoint, with request and response schemas
• Setup links
• Show deployment status in your product