@optiqlabs/promptcache-sdk

Official JavaScript / TypeScript client for the PromptCache HTTP API.

Use it from Node.js scripts, backend services, serverless functions, or any environment with fetch (Node.js 20+). Manage prompts, render templates with invoke, preview with inject, and browse the public catalog — all with typed methods instead of raw HTTP.

Links: npm · Documentation · API reference · Create an API key

Requirements

• Node.js 20+ (or any runtime with global fetch)
• A PromptCache API key (pk_…) for authenticated routes, or no key for the public catalog only

Install

npm install @optiqlabs/promptcache-sdk

pnpm add @optiqlabs/promptcache-sdk

yarn add @optiqlabs/promptcache-sdk

Quick start

1. Create an API key in the PromptCache dashboard (starts with pk_).
2. Install the package (above).
3. Create a client and invoke a prompt:

import { PromptCacheClient } from '@optiqlabs/promptcache-sdk';
import { createPlatformFetch } from '@optiqlabs/promptcache-sdk/platform';

const client = new PromptCacheClient({
  apiKey: process.env.PROMPTCACHE_API_KEY!, // pk_…
  baseUrl: 'https://api.promptcache.app', // API origin only — no /api path
  fetch: createPlatformFetch(),
});

const prompts = await client.prompts.list({ limit: 10 });
const { renderedContent } = await client.prompts.invoke(prompts[0]._id!, {
  topic: 'release notes',
});

console.log(renderedContent);

Self-hosted or staging? Set baseUrl to your API origin (the same value shown in the PromptCache developer docs for your deployment).

Authentication

| Credential | Use for | | ---------------------------------------- | -------------------------------------------------------------------------------- | | API key (pk_…) | Integrations, CI, backend services — pass as apiKey on the client | | User access token (JWT from sign-in) | Dashboard-style flows that need publish, fork version, or CSV import |

All authenticated calls send Authorization: Bearer …. With an API key you do not pass organizationId on the client — the server infers the org from the key.

For JWT-based scripts, set defaultOrganizationId on the client so prompts.list, prompts.create, forkVersion, and queueCsvImport include org context when you omit it per call.

See Authentication in the docs for scopes and key setup.

Common tasks

List prompts and read variables

const prompts = await client.prompts.list({ search: 'email', limit: 20 });

// Pagination + workspace summary
const page = await client.prompts.listPaginated({
  page: 1,
  visibility: 'public',
});
console.log(page.pagination, page.summary);

const variables = await client.prompts.getVariables(prompts[0]._id!);

Validate variables before invoke

import { validateInvokeVariables } from '@optiqlabs/promptcache-sdk';

const variables = await client.prompts.getVariables(promptId);
const check = validateInvokeVariables(variables, { topic: 'docs' });

if (!check.ok) {
  throw new Error(
    `Missing required variables: ${check.missingRequired.join(', ')}`
  );
}

const result = await client.prompts.invoke(promptId, { topic: 'docs' });

Preview without failing on missing required vars

const preview = await client.prompts.inject(promptId, { name: 'Ada' });
console.log(preview.renderedContent, preview.unresolvedVariables);

Public catalog (no auth header)

client.publicPrompts calls /api/v1/public/prompts and does not send Authorization (even when your client was created with an API key):

const prompts = await client.publicPrompts.list({ search: 'email' });
const detail = await client.publicPrompts.get(prompts[0]._id!);
const out = await client.publicPrompts.invoke(prompts[0]._id!, { name: 'Ada' });

Handle errors

import {
  PromptCacheClient,
  PromptCacheApiError,
} from '@optiqlabs/promptcache-sdk';

try {
  await client.prompts.get('unknown-id');
} catch (err) {
  if (err instanceof PromptCacheApiError) {
    console.error(err.status, err.message, err.body);
  }
  throw err;
}

Debug logging

const client = new PromptCacheClient({
  apiKey: process.env.PROMPTCACHE_API_KEY!,
  baseUrl: 'https://api.promptcache.app',
  fetch: createPlatformFetch(),
  debug: true, // logs method, path, timing, status — never logs the API key
});

Pass a custom logger implementing PromptCacheSdkLogger (debug / info / warn / error) to send logs to your own sink.

How responses work

The HTTP API wraps successful JSON as { data: … }. The SDK unwraps that automatically.

| Pattern | Returns | | ------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------ | | prompts.list(), publicPrompts.list(), organizations.list(), prompts.listVersions() | Array of items | | prompts.listPaginated(), publicPrompts.listPaginated(), organizations.listPaginated(), prompts.listVersionsPaginated() | Full payload with pagination (and summary for prompts) | | prompts.get(), prompts.create(), prompts.update(), etc. | Single entity (IPrompt, IOrganization, …) |

prompts.update returns IPrompt & { staleVariables?: string[] } when the server reports outdated variable definitions.

Client options

| Option | Description | | ----------------------- | ------------------------------------------------------------------------------------------------------------------------ | | apiKey | API key (pk_…) or user JWT | | baseUrl | API origin only, e.g. https://api.promptcache.app (paths are prefixed with /api/v1/…) | | fetch | Required. Use createPlatformFetch() from @optiqlabs/promptcache-sdk/platform, or inject your own (e.g. in tests) | | defaultOrganizationId | Optional. For JWT usage — merged into list/create/fork/import when omitted per call | | debug | Log each HTTP call to the console | | logger | Custom log sink (overrides debug) |

Package exports

| Import | Contents | | ------------------------------------- | ----------------------------------------------------------------------------------- | | @optiqlabs/promptcache-sdk | PromptCacheClient, errors, DTO types, validateInvokeVariables, template helpers | | @optiqlabs/promptcache-sdk/platform | createPlatformFetch() for Node.js 20+ / browsers | | @optiqlabs/promptcache-sdk/types | Domain types (IPrompt, IPromptVariable, …) | | @optiqlabs/promptcache-sdk/utils | validateInvokeVariables, extractVariableNames, slugifyPromptName |

API methods

Organizations

| Method | HTTP | | ------------------------------- | ----------------------------------------------- | | organizations.list() | GET /api/v1/organizations → IOrganization[] | | organizations.listPaginated() | Same → { organizations } | | organizations.get(id) | GET /api/v1/organizations/:id |

Prompts (authenticated)

| Method | HTTP | Notes | | ------------------------------------------ | --------------------------------------------- | ---------------------------------- | | prompts.list(query?) | GET /api/v1/prompts | Returns IPrompt[] | | prompts.listPaginated(query?) | Same | { prompts, pagination, summary } | | prompts.create(body) | POST /api/v1/prompts | | | prompts.get(id) | GET /api/v1/prompts/:id | | | prompts.update(id, body) | PUT /api/v1/prompts/:id | | | prompts.remove(id) | DELETE /api/v1/prompts/:id | | | prompts.invoke(id, vars, options?) | POST /api/v1/prompts/:id/invoke | Render template | | prompts.inject(id, vars) | POST /api/v1/prompts/:id/inject | Preview render | | prompts.getVariables(id) | GET /api/v1/prompts/:id/variables | | | prompts.updateVariable(id, name, body) | PUT /api/v1/prompts/:id/variables/:name | | | prompts.listVersions(id, options?) | GET /api/v1/prompts/:id/versions | | | prompts.getVersion(id, versionId) | GET /api/v1/prompts/:id/versions/:versionId | | | prompts.publish(id) | POST /api/v1/prompts/:id/publish | JWT only | | prompts.unpublish(id) | DELETE /api/v1/prompts/:id/publish | | | prompts.forkVersion(id, versionId, body) | POST …/versions/:versionId/fork | JWT only | | prompts.queueCsvImport(options) | POST /api/v1/prompts/import | JWT only, multipart |

Which methods succeed depends on your API key scopes or JWT permissions. See the Prompts API docs.

Public catalog

| Method | HTTP | | -------------------------------- | ---------------------------------------- | | publicPrompts.list(query?) | GET /api/v1/public/prompts | | publicPrompts.get(id) | GET /api/v1/public/prompts/:id | | publicPrompts.invoke(id, vars) | POST /api/v1/public/prompts/:id/invoke |

TypeScript

Types are included. Import domain interfaces from the main package or from @optiqlabs/promptcache-sdk/types:

import type {
  IPrompt,
  IPromptVariable,
} from '@optiqlabs/promptcache-sdk/types';

Security

This client sends HTTPS requests only to the baseUrl you configure. It does not contact third-party analytics or load remote code. Your API key is sent only as a Bearer token to that origin.

Store keys in environment variables or a secrets manager — never commit them to source control.

Upgrading

0.2.8-beta and later: fetch is required on PromptCacheClient. Pass createPlatformFetch() from @optiqlabs/promptcache-sdk/platform.

0.2.3-beta and later: List methods return arrays directly (await client.prompts.list() → IPrompt[]). Use *Paginated() when you need pagination metadata. The SDK unwraps { data: … } responses automatically.

Learn more

• SDK guide — full walkthrough with examples
• Getting started
• Prompts API
• Support

License

MIT © Optiq Labs