PrimitiveApiClient

What PrimitiveApiClient is#

PrimitiveApiClient is the host-aware, authenticated request client that every generated Primitive API operation is called through. It lives in the workspace-internal api-core package and is bundled inline into both @primitivedotdev/sdk and the primitive CLI, so neither package declares a dependency on the other or on @primitivedotdev/api-core directly.

Where it comes from#

PrimitiveApiClient is defined and exported from @primitivedotdev/api-core, alongside its options type, its error class, and a factory function:

export {
  createPrimitiveApiClient,
  DEFAULT_API_BASE_URL,
  PrimitiveApiClient,
  type PrimitiveApiClientOptions,
  PrimitiveApiError,
  type PrimitiveApiErrorDetails,
  type RequestOptions as PrimitiveRequestOptions,
} from "./client.js";

Consumers never import @primitivedotdev/api-core directly. The Node SDK re-exports the same names from @primitivedotdev/sdk/api:

import { PrimitiveApiClient, getAccount } from "@primitivedotdev/sdk/api";

const api = new PrimitiveApiClient({ apiKey: process.env.PRIMITIVE_API_KEY });
const result = await getAccount({ client: api.client });

The CLI's internal api-command plumbing constructs PrimitiveApiClient the same way to drive the generic API access commands and every task-oriented CLI command.

Constructing a client#

new PrimitiveApiClient(options?: PrimitiveApiClientOptions)

DEFAULT_API_BASE_URL, exported alongside the class, is the production host constant the client uses when no base URL is supplied. Production code should rely on that default.

A createPrimitiveApiClient(...) factory function is exported as an alternative construction path alongside the new PrimitiveApiClient(...) constructor; both produce the same client shape.

Calling a generated operation#

Every generated operation function (getAccount, setMemory, getMemory, sendEmail, and so on) takes a client option pointing at apiClient.client, the underlying generated fetch client PrimitiveApiClient wraps:

import { PrimitiveApiClient, getAccount } from "@primitivedotdev/sdk/api";

const api = new PrimitiveApiClient({ apiKey: process.env.PRIMITIVE_API_KEY });

const result = await getAccount({ client: api.client });

The full list of generated operations is documented in the operation manifest. Passing responseStyle: "fields" returns a { data, error, response }-shaped result; check error to detect failure.

PrimitiveApiError#

Failed requests surface as a typed PrimitiveApiError, carrying structured detail rather than a bare message:

PrimitiveApiErrorDetails is exported as a type alongside the error class for callers who want to narrow details further. PrimitiveRequestOptions (the re-exported RequestOptions type) is the per-call options shape accepted by the generated client's request layer; the high-level client.send() / client.reply() surface has its own RequestOptions, documented on Request Options and Idempotency.

The Node SDK's higher-level wrappers (client.send, client.reply, client.agent.*, client.memories.*) throw PrimitiveApiError directly, so you can catch it with instanceof:

import primitive from "@primitivedotdev/sdk";
import { PrimitiveApiError } from "@primitivedotdev/sdk/api";

const client = primitive.client({ apiKey: process.env.PRIMITIVE_API_KEY! });

try {
  await client.send({
    from: "Support <support@example.com>",
    to: "alice@example.com",
    subject: "Hello",
    bodyText: "Hi there",
  });
} catch (error) {
  if (error instanceof PrimitiveApiError) {
    console.error(error.status, error.code, error.requestId, error.retryAfter);
  }
}

Relationship to the high-level client#

PrimitiveClient (the send / reply / forward client returned by primitive.client(...)) is built on top of the same generated operations and the same PrimitiveApiClient host-aware plumbing, but exposes a smaller, task-shaped surface with its own SendResult, ReplyInput, and RequestOptions types. That high-level surface is documented on Sending, Replying, and Forwarding Email and Receiving Inbound Email; this page covers only the underlying generated-client layer.

Next steps#