Developers

JavaScript / TypeScript SDK

Official npm client for PromptCache

API base URL

https://api.promptcache.app

The @optiqlabs/promptcache-sdk package is the easiest way to call PromptCache from Node.js or any JavaScript environment with fetch (Node 20+).

Install from npm, pass your API key and the API base URL shown at the top of developer pages, and use typed methods instead of raw HTTP.

All authenticated calls send Authorization: Bearer … with either a pk_… API key or a user access token from sign-in (see Authentication).

Install

The package is @optiqlabs/promptcache-sdk, published on the public npm registry (npmjs.com). With the default npm registry, use:

npm install @optiqlabs/promptcache-sdk

If npm install fails, confirm you are using the public npm registry (https://registry.npmjs.org/) and that the package name is exactly @optiqlabs/promptcache-sdk.

Create a client

Pass your API origin only (no /api path). With a pk_… key you do not configure an organizationId on the client: the server derives the org from the key.

Every client needs a fetch implementation. On Node.js 20+ or in the browser, import createPlatformFetch() from @optiqlabs/promptcache-sdk/platform and pass it as fetch. In tests, inject a mock instead.

Use a pk_… key for automation; use a user access token from POST /api/v1/auth/login when you need publish / fork.

Successful API bodies are wrapped as { data: … }; the SDK unwraps them automatically. List methods return arrays; use *Paginated() variants when you need pagination metadata. prompts.listPaginated() also returns summary (workspace counts) and accepts optional visibility (all / public / private). prompts.queueCsvImport sends multipart/form-data (user JWT only).

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

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

For JWT scripts that call prompts.list, prompts.create, forkVersion, or queueCsvImport, access tokens carry no default organization in the REST API, you can set defaultOrganizationId on the client so those methods send organizationId / targetOrganizationId when you omit per-call values.

All authenticated requests send Authorization: Bearer plus your API key or user access token. The client prefixes paths with /api (e.g. GET /api/v1/prompts).

Organizations

API keys are scoped to one organization. organizations.list() returns IOrganization[] (one entry for a key). Use organizations.listPaginated() if you need the { organizations } wrapper shape matching the raw API payload after unwrap.

const organizations = await client.organizations.list();

const org = organizations[0];

Prompts: CRUD, invoke, inject

Method	Purpose
`prompts.list(query?)`	`IPrompt[]`, paginate/search/tags/`visibility` (use `listPaginated` for metadata)
`prompts.listPaginated(query?)`	`{ prompts, pagination, summary }`
`prompts.create(body)`	Create a draft prompt → `IPrompt`
`prompts.queueCsvImport(options)`	`POST …/import` → `{ batchId, message }`, JWT only (multipart)
`prompts.get(id)`	Fetch one prompt → `IPrompt`
`prompts.update(id, body)`	Update draft fields → `IPrompt` & optional `staleVariables`
`prompts.remove(id)`	Delete
`prompts.invoke(id, variables)`	Render template; server enforces required variables
`prompts.inject(id, variables)`	Preview render; returns `unresolvedVariables` without failing on required
`prompts.getVariables(id)`	`IPromptVariable[]`
`prompts.updateVariable(id, name, partial)`	Update one variable’s metadata → `IPrompt`
`prompts.listVersions(id, { published?: true })`	`IPromptVersion[]` (use `listVersionsPaginated` for wrapper)
`prompts.listVersionsPaginated(id, options?)`	`{ versions }`
`prompts.getVersion(id, versionId)`	One version snapshot → `IPromptVersion`
`prompts.publish(id)`	`POST …/publish`, user JWT only (`403` with API key)
`prompts.unpublish(id)`	`DELETE …/publish`, org-scoped JWT or API key per server checks
`prompts.forkVersion(id, versionId, body)`	`POST …/fork`, user JWT only

const { renderedContent, variables } = await client.prompts.invoke(
  promptId,
  {
    topic: 'release notes',
  },
);

Client-side validation

Before calling invoke, you can check required keys locally with validateInvokeVariables. A variable is satisfied if its name is a key in your map (an empty string still counts as present, the same rule the API uses for in checks).

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

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

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

Public catalog (no API key)

Use client.publicPrompts for unauthenticated list, get, and invoke against /api/v1/public/prompts. list() returns IPublicPrompt[]; use listPaginated() for { prompts, pagination }.

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

Subpath imports

@optiqlabs/promptcache-sdk/platform, createPlatformFetch() for Node.js 20+ and modern browsers.
@optiqlabs/promptcache-sdk/types, enums and interfaces (IPrompt, IPromptVariable, …).
@optiqlabs/promptcache-sdk/utils, extractVariableNames, slugifyPromptName, and validateInvokeVariables.

Errors

Non-success HTTP responses throw PromptCacheApiError with status and body. Handle rate limits and validation errors the same way you would for raw HTTP calls.

Code

import { PromptCacheApiError } from '@optiqlabs/promptcache-sdk';
 
try {
  await client.prompts.get('unknown-id');
} catch (err) {
  if (err instanceof PromptCacheApiError) {
    console.error(err.status, err.message);
  }
}

What is not in the SDK

Managing API keys or billing, use the PromptCache dashboard.
POST /api/v1/public/prompts/:id/fork, fork from the public catalog requires a signed-in user; use the dashboard or the Prompts API with a user access token.

For JWT auth from scripts, exchange credentials with POST /api/v1/auth/login and pass the access token as Authorization: Bearer … instead of pk_… wherever the server expects a logged-in user.

Authentication, API keys and scopes
Prompts API, full HTTP reference
npm package README, install snippets and method tables