Legacy v1 API client (@scramjet/api-client)

July 16, 2026 · View on GitHub

Note: This page documents the v1 API surface used by @scramjet/api-client and the /api/v1 route tree. The v1 API remains available and supported for backwards compatibility. New projects should use the v2 API surface (see API client usage).

Overview

The @scramjet/api-client package provides a TypeScript/JavaScript library that wraps the v1 Hub and Manager HTTP APIs in a typed, promise-based interface.

Installation

npm install @scramjet/api-client

HostClient (Hub API)

The HostClient provides direct access to a single Hub's v1 API:

import { HostClient } from "@scramjet/api-client";

const host = new HostClient("http://localhost:8000/api/v1");

// List Instances on this Hub
const instances = await host.listInstances();

// Inspect a specific Instance
const info = await host.getInstanceInfo(instanceId);

// List Sequences
const sequences = await host.listSequences();

// Upload a Sequence package
const sequence = await host.sendSequence(fs.createReadStream("./my-sequence.tar.gz"));

ManagerClient (Manager API)

The ManagerClient provides access to the Manager's unified control plane:

import { createHostClient, ManagerClient } from "@scramjet/api-client";

const manager = new ManagerClient("http://localhost:8200/api/v1", undefined, createHostClient);

// List all Instances across all Hubs
const instances = await manager.getInstances();

// List all Sequences across all Hubs
const sequences = await manager.getAllSequences();

// List registered Hubs
const hubs = await manager.getHosts();

// Get a HostClient for a specific Hub
const hostClient = await manager.getHostClient(hubId);

Key client concepts (v1)

The HostClient provides operations scoped to a single Hub:

  • listInstances() — list Instances on this Hub
  • getInstanceInfo(id) — inspect an Instance
  • listSequences() — list Sequences on this Hub
  • sendSequence(stream) — upload a Sequence package
  • sendTopic(topic, stream) — publish data to a Topic
  • getTopic(topic) — read data from a Topic
  • createTopic(id, contentType) — create a Topic

The ManagerClient provides a fleet-wide view:

  • getInstances() — list all Instances across all Hubs
  • getAllSequences() — list all Sequences across all Hubs
  • getHosts() — list registered Hubs
  • getHostClient(id) — obtain a HostClient for a specific Hub when the ManagerClient was constructed with a host-client factory
  • sendNamedData(topic, stream) — publish data to a named topic
  • getNamedData(topic) — read data from a named topic

Note: The exact method signatures and available operations are evolving. For the complete up-to-date API, refer to the TypeScript type definitions in the @scramjet/api-client package or the generated API reference.

Creating sub-clients

Both HostClient and ManagerClient provide factory methods for scoped sub-clients:

// From HostClient
const instanceClient = host.getInstanceClient(instanceId);
const sequenceClient = host.getSequenceClient(sequenceId);

// From ManagerClient constructed with a host-client factory
const hostClient = await manager.getHostClient(hubId);

Direct HTTP access (v1)

You can call the v1 Hub or Manager API directly with any HTTP client:

List Instances:

curl http://localhost:8000/api/v1/instances

Upload a Sequence:

curl -X POST http://localhost:8000/api/v1/sequence \
  -F "package=@./my-sequence.tar.gz"

Get Instance info:

curl http://localhost:8000/api/v1/instance/<id>

Migration to v2

The v1 API remains supported for existing deployments. New projects should use the v2 API via @scramjet/rest-api2. See the API client usage page for v2 documentation.

See also