{"schema_version":"1.0","publisher":"Primitive SDKs","canonical_url":"https://test.abhinandan.one/primitive-api-client","markdown_url":"https://test.abhinandan.one/primitive-api-client.md","article":{"id":"f1a0e860-3a2c-4efa-82d4-52aeccc8b5b4","article_slug":"primitive-api-client","parent_article_slug":null,"parent_article_title":null,"kind":"reference","published_at":"2026-08-11T18:55:05.581151+00:00","keywords":["PrimitiveApiClient","PrimitiveApiError","@primitivedotdev/api-core","createPrimitiveApiClient","DEFAULT_API_BASE_URL","PrimitiveApiClientOptions"],"meta_description":"PrimitiveApiClient is the host-aware, authenticated fetch client in @primitivedotdev/api-core, re-exported by the Node SDK and CLI with a typed PrimitiveApiError.","og_image_url":null,"source_file_paths":["packages/api-core/src/index.ts"],"recording_id":null,"replayable":false,"task_name":"PrimitiveApiClient","category":"API Core / OpenAPI Generation","summary":null,"description":"Reference for PrimitiveApiClient, the host-aware, authenticated HTTP client shared by the Node SDK and CLI, plus the shape of the PrimitiveApiError it throws.","content_kind":"repo_page","content_markdown":"## What PrimitiveApiClient is\n\n`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](api-core-overview) 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.\n\n<Note>\n\nThis is the **generated API client** layer: the OpenAPI-codegenerated surface that exposes every operation directly. For everyday send/receive/reply/forward code, use the high-level `primitive.client()` / `client.send()` surface described in the [inbound/outbound email model](email-model) instead. Reach for `PrimitiveApiClient` for operations the high-level client doesn't cover, such as [Primitive Memories](node-sdk-api-client) or account/domain management.\n\n</Note>\n\n## Where it comes from\n\n`PrimitiveApiClient` is defined and exported from `@primitivedotdev/api-core`, alongside its options type, its error class, and a factory function:\n\n```typescript\nexport {\n  createPrimitiveApiClient,\n  DEFAULT_API_BASE_URL,\n  PrimitiveApiClient,\n  type PrimitiveApiClientOptions,\n  PrimitiveApiError,\n  type PrimitiveApiErrorDetails,\n  type RequestOptions as PrimitiveRequestOptions,\n} from \"./client.js\";\n```\n\nConsumers never import `@primitivedotdev/api-core` directly. The Node SDK re-exports the same names from `@primitivedotdev/sdk/api`:\n\n```typescript\nimport { PrimitiveApiClient, getAccount } from \"@primitivedotdev/sdk/api\";\n\nconst api = new PrimitiveApiClient({ apiKey: process.env.PRIMITIVE_API_KEY });\nconst result = await getAccount({ client: api.client });\n```\n\nThe CLI's internal `api-command` plumbing constructs `PrimitiveApiClient` the same way to drive the [generic API access commands](cli-generic-api-access) and every task-oriented CLI command.\n\n## Constructing a client\n\n```typescript\nnew PrimitiveApiClient(options?: PrimitiveApiClientOptions)\n```\n\n| Field | Type | Required | Description |\n|---|---|---|---|\n| `apiKey` | `string` | Yes (for authenticated calls) | Bearer token sent as `Authorization: Bearer <apiKey>` on every request. |\n\n`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.\n\nA `createPrimitiveApiClient(...)` factory function is exported as an alternative construction path alongside the `new PrimitiveApiClient(...)` constructor; both produce the same client shape.\n\n## Calling a generated operation\n\nEvery 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:\n\n```typescript\nimport { PrimitiveApiClient, getAccount } from \"@primitivedotdev/sdk/api\";\n\nconst api = new PrimitiveApiClient({ apiKey: process.env.PRIMITIVE_API_KEY });\n\nconst result = await getAccount({ client: api.client });\n```\n\nThe full list of generated operations is documented in the [operation manifest](operation-manifest). Passing `responseStyle: \"fields\"` returns a `{ data, error, response }`-shaped result; check `error` to detect failure.\n\n## PrimitiveApiError\n\nFailed requests surface as a typed `PrimitiveApiError`, carrying structured detail rather than a bare message:\n\n| Field | Type | Description |\n|---|---|---|\n| `message` | `string` | Human-readable error message. |\n| `status` | `number \\| undefined` | The HTTP status code, when the request reached the server. |\n| `code` | `string \\| undefined` | Machine-readable error code from the API's error envelope. |\n| `gates` | `GateDenial[] \\| undefined` | Structured gate-denial detail when a send/reply/forward was blocked by a policy gate. |\n| `requestId` | `string \\| undefined` | The server's request id, useful when filing a support ticket. |\n| `retryAfter` | `number \\| undefined` | Parsed from the `Retry-After` response header, when present (for example on `429`). |\n| `details` | `PrimitiveApiErrorDetails \\| undefined` | Additional structured error detail, when the API supplied it. |\n\n`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](node-sdk-request-options).\n\nThe Node SDK's higher-level wrappers (`client.send`, `client.reply`, `client.agent.*`, `client.memories.*`) throw `PrimitiveApiError` directly, so you can catch it with `instanceof`:\n\n```typescript\nimport primitive from \"@primitivedotdev/sdk\";\nimport { PrimitiveApiError } from \"@primitivedotdev/sdk/api\";\n\nconst client = primitive.client({ apiKey: process.env.PRIMITIVE_API_KEY! });\n\ntry {\n  await client.send({\n    from: \"Support <support@example.com>\",\n    to: \"alice@example.com\",\n    subject: \"Hello\",\n    bodyText: \"Hi there\",\n  });\n} catch (error) {\n  if (error instanceof PrimitiveApiError) {\n    console.error(error.status, error.code, error.requestId, error.retryAfter);\n  }\n}\n```\n\n## Relationship to the high-level client\n\n`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](node-sdk-sending-email) and [Receiving Inbound Email](node-sdk-receiving-email); this page covers only the underlying generated-client layer.\n\n## Next steps\n\n<CardGroup cols={2}>\n\n<Card title=\"Operation Manifest Reference\" href=\"operation-manifest\">\n\nLook up every generated operation's command name, method, path, and inlined JSON Schemas.\n\n</Card>\n\n<Card title=\"Generated API Client and Primitive Memories\" href=\"node-sdk-api-client\">\n\nSee PrimitiveApiClient used for Memories and other advanced operations from the Node SDK.\n\n</Card>\n\n<Card title=\"What is API Core?\" href=\"api-core-overview\">\n\nUnderstand the workspace-internal package PrimitiveApiClient is defined in.\n\n</Card>\n\n<Card title=\"Node.js SDK Errors\" href=\"node-sdk-errors\">\n\nLook up every error code the Node SDK's clients (including PrimitiveApiError) can raise.\n\n</Card>\n\n</CardGroup>","canonical_base_url":"https://test.abhinandan.one","seo_indexing_enabled":true,"last_modified":"2026-08-21T18:22:43.359885+00:00","video_url":null,"voiceover_url":null,"tools_used":[],"demonstrated_by":[],"steps":[],"related_links":[],"intro":null,"prerequisites":[],"verification":[],"troubleshooting":[],"suggest_edit_url":"https://github.com/abhi-browzer/primitive-sdks/edit/main/packages/api-core/src/index.ts","raise_issue_url":"https://github.com/abhi-browzer/primitive-sdks/issues/new?title=Docs+feedback%3A+PrimitiveApiClient&body=Page%3A+https%3A%2F%2Ftest.abhinandan.one%2Fprimitive-api-client","page_feedback_enabled":true,"verified_ref":null,"verified_at":"2026-08-11T18:38:45.205849+00:00"}}