Deployments.ai Docs

SDK overview

Install the TypeScript SDK, create a client, and make your first call.

@deployments-ai/sdk is a TypeScript client for the public API. It is generated from the platform's OpenAPI document and exports one async function per API operation, named after the operation ID, such as listAgentDefinitions or submitAgentRun. Each function has typed path parameters, query parameters, headers, request body, and response. Use the SDK in Node.js services, scripts, and tools. For terminal work, use the CLI.

Availability

The SDK is published to the public npm registry as @deployments-ai/sdk. The current release is a prerelease on the next dist-tag.

Requirements

  • Node.js 26 or later. The package declares "node": ">=26" in engines.
  • ES modules. The package is ESM only, so load it with import, not require.
  • TypeScript is optional. The package ships its own type declarations.

Install the SDK

Install from the next dist-tag:

npm install @deployments-ai/sdk@next

Create a client and make a call

Create one client with the API origin and a credential, then pass it to every call:

import { createClient, createConfig, getHealth, listAgentDefinitions } from "@deployments-ai/sdk";

const client = createClient(
  createConfig({
    baseUrl: "https://api.example.com",
    headers: { authorization: `Bearer ${process.env.DEPLOYMENTS_API_KEY}` },
  }),
);

const health = await getHealth({ client });
console.log(health.data?.status); // "ok"

const { data, error, response } = await listAgentDefinitions({
  client,
  headers: { "x-deployments-environment": "<environment-id>" },
  query: { limit: 20 },
});

if (error) {
  console.error(response?.status, error);
} else {
  for (const definition of data.items) console.log(definition.id, definition.name);
}

Every function returns an object with data on success or error on failure, plus the request and response. It does not throw on HTTP errors unless you ask it to. Making requests covers the options, and Error handling covers failures.

The function reference lists every function with its endpoint and CLI command. Each function links to an API reference page with the request and response schemas and a complete example.

The client protects your credential

The client refuses requests that could send your bearer token somewhere you did not intend:

  • baseUrl must be an origin, such as https://api.example.com, with no path, query, or fragment.
  • The origin must use HTTPS. Plain HTTP works only for loopback hosts such as localhost and 127.0.0.1.
  • The URL must not contain a user name or password.
  • Every request must go to the client's configured origin. A request that carries an authorization, cookie, or proxy-authorization header fails if the client has no configured origin.
  • The client does not follow redirects. A redirect response fails the request.

createClient checks baseUrl when you create the client and throws a TypeError if it breaks a rule. To check a configured URL earlier, for example when your service starts, call validatePlatformBaseUrl(url). It returns the parsed URL or throws the same TypeError.

Because a client is tied to one origin and one credential, create one client per credential and origin. The package also exports a default client, which has no base URL. Pass your own client in the client option instead of changing the shared default.

The stream gateway that serves live run output has its own origin. Reading it needs a second client or a plain fetch, as Streaming run output shows.

What the package exports

ExportWhat it is
Operation functionsOne function per public API operation. See the function reference.
createClientCreates a client and checks its base URL.
createConfigBuilds a client configuration, such as baseUrl, headers, auth, and fetch.
clientThe shared default client. It has no base URL.
validatePlatformBaseUrlChecks that a URL is a valid API origin.
ClientThe TypeScript type of a client.
contractMetadataThe API version, operation count, and SHA-256 hashes of the OpenAPI document the package was generated from.

The same contract metadata is available as JSON at @deployments-ai/sdk/contract. Use it to confirm which API contract a build was generated from.

Next steps

On this page