CiteFoundry Docs
Open dashboard

TypeScript SDK

Install @citefoundry/api-client, configure auth, and call the API with full TypeScript types.

@citefoundry/api-client is the official TypeScript SDK. It’s generated from the OpenAPI spec, so the types you get are always in sync with the live API — no hand-written wrappers to drift.

Install

Terminal window
pnpm add @citefoundry/api-client
# or: npm install @citefoundry/api-client / yarn add @citefoundry/api-client

Configure

The SDK reads two globals at call time: OpenAPI.BASE (the API root) and OpenAPI.TOKEN (your Bearer JWT or a function that returns one). Set them once at app boot:

import { OpenAPI } from "@citefoundry/api-client";


OpenAPI.BASE = process.env.CITEFOUNDRY_API_URL ?? "https://api.citefoundry.com";
OpenAPI.TOKEN = async () => process.env.CITEFOUNDRY_TOKEN!;

Returning a function instead of a string lets you refresh the token — useful in the dashboard, where the session JWT is short-lived.

Your first call

Every operation lives on the generated DefaultService class. List your projects:

import { DefaultService } from "@citefoundry/api-client";


const projects = await DefaultService.listProjects({ limit: 20 });
for (const project of projects.items) {
  console.log(project.id, project.name);
}


if (projects.nextCursor) {
  // ...paginate with { cursor: projects.nextCursor }
}

Error handling

The SDK throws an ApiError on non-2xx responses. The body is the RFC 7807 problem so you can switch on the stable type field rather than parsing free-form text:

import { ApiError } from "@citefoundry/api-client";


try {
  await DefaultService.createMonitor({ projectId, requestBody });
} catch (err) {
  if (err instanceof ApiError && err.body?.type === "https://citefoundry.com/problems/plan-quota-exceeded") {
    // Show an upgrade prompt
  } else {
    throw err;
  }
}

See Error handling for the full pattern, including the 401-refresh-retry helper used inside the dashboard.

What’s next

  • Examples — full snippets: list projects, create monitors, fetch runs with citations, kick off prompt ingestion.
  • Configuration — every option on the OpenAPI singleton, plus runtime config patterns.
  • API reference — the source of truth the SDK is generated from.