Node SDK

@synthetiq/platform-sdk is the official Node/TypeScript client for the Platform API. It’s the same library the CLI is built on, so anything the CLI does, you can script. Every REST resource in this section has a typed accessor on the client.

Install

The SDK ships from the same private registry as the CLI — see CLI installation for the registry/auth setup, then:

npm install @synthetiq/platform-sdk

Instantiate

import { SynthetiqClient } from "@synthetiq/platform-sdk";

const sdk = new SynthetiqClient({
  baseUrl: "https://api.synthetiq.com/api",
  // Called before every request — you own credential storage and refresh.
  getAccessToken: () => process.env.SYNTHETIQ_TOKEN!,
});

Option	Required	Description
`baseUrl`	Yes	Platform API base, including `/api`
`getAccessToken`	Yes	Sync or async function returning a bearer token before each request
`extraHeaders`	No	Headers sent on every request
`fetch`	No	Override `fetch` (tests, instrumentation)

getAccessToken is a callback so the SDK never owns credentials: the CLI reads its credentials file, the desktop app its session, and CI does an OIDC token exchange.

Resource accessors

Each accessor maps to a resource in this section:

Accessor	Resource
`sdk.me`	Current user
`sdk.organizations`	Organizations
`sdk.members`, `sdk.roles`, `sdk.scopes`	Members & roles
`sdk.serviceAccounts`, `sdk.oidcTrusts`	Service accounts & OIDC trusts
`sdk.awsConfig`	Deployment infrastructure (BYOI)
`sdk.storageConfig`	Organizations (storage config)
`sdk.entities`	Entities & Versions
`sdk.prdComments`	PRD comments
`sdk.shares`, `sdk.publishers`, `sdk.stores`	Sharing
`sdk.productionApps`	Production apps
`sdk.deploys`	Deployments

Example

// Check your own permissions before attempting a scoped operation.
const me = await sdk.me.get();
if (!me.organization?.scopes.some((s) => s.key === "entities:deploy")) {
  throw new Error(`${me.organization?.role.name ?? "no"} role cannot deploy`);
}

// List an org's deployment targets, then trigger a deploy.
const { configs } = await sdk.awsConfig.list(orgId);

const deployment = await sdk.deploys.create({
  productionAppId: app.id,
  versionId: version.id,
});
console.log(deployment.status);

Setting an avatar is a three-step flow — request a signed URL, upload the bytes, point the profile at it — wrapped in one call:

import fs from "fs";

const profile = await sdk.me.uploadAvatar(fs.readFileSync("me.png"), "png");
console.log(profile.avatar_url);

// Revert to whatever picture your identity provider supplies.
await sdk.me.clearAvatar();

uploadAvatar sends back the exact publicUrl the API issued. The API only accepts avatar URLs it issued for that user, so a reconstructed URL is rejected.

Error handling

Failed requests throw SynthetiqApiError with the HTTP status and the API’s error message. When the API returns a coded error, the machine-readable code and the parsed response body are on the error as well:

import { SynthetiqApiError } from "@synthetiq/platform-sdk";

try {
  await sdk.organizations.get(orgId);
} catch (err) {
  if (err instanceof SynthetiqApiError && err.status === 403) {
    // missing scope — see Authentication
  }
}

Authorization is enforced per-resource; see Authentication for the scope model.

Platform Docs

Synthetiq Desktop

Synthetiq CLI

App Framework

Services Framework

Workflows Framework

Platform API

Deployments

Install

Instantiate

Resource accessors

Example

Error handling

​Install

​Instantiate

​Resource accessors

​Example

​Error handling

Install

Instantiate

Resource accessors

Example

Error handling