Quickstart

Getting started with Clairist

This guide walks you through creating an API key, installing the Clairist SDK, and sending your first events. Public Trust Pages and Trust Badges are available when your workspace meets publication eligibility and you enable them in settings.

1. Create an API key

  1. Sign in to Clairist and select the team you want to instrument.
  2. Navigate to Settings > API keys and create a new ingestion API key.
  3. Store this key securely (for example as CLAIRIST_API_KEY in your application environment).

2. Install the SDK

The official Node SDK is published as @clairist/sdk.

npm

npm install @clairist/sdk

yarn

yarn add @clairist/sdk

3. Initialize the client

Create a single shared instance of the Clairist client using your API key and optional defaults for team and system identifiers.

import { createClairistClient } from "@clairist/sdk";

const clairist = createClairistClient({
  // Alternatively set CLAIRIST_API_KEY in your environment
  apiKey: process.env.CLAIRIST_API_KEY,
  // Optional: override the default ingestion URL
  // baseUrl: "https://api.clairist.com",
  defaultTeamId: "<your-team-id>",
  defaultSystemId: "<your-ai-system-id>",
});

4. Send your first events

Clairist supports four primary event types: model_call, prompt, incident and evidence. The SDK exposes convenience methods for each.

Log a model call (latency, token usage, prompt/response)

await clairist.logModelCall({
  systemId: "<your-ai-system-id>",
  modelId: "gpt-4.1-mini",
  requestCount: 1,
  tokenUsage: 1024,
  prompt: userPrompt,
  response: modelResponse,
  latencyMs: elapsedMs,
  metadata: { route: "/api/chat", tenantId },
});

Log a prompt interaction

await clairist.logPrompt({
  teamId: "<your-team-id>",
  actorId: user.id,
  scope: "ai_assistant",
  action: "prompt_logged",
  channel: "web",
  subjectId: conversationId,
  prompt: userPrompt,
  response: modelResponse,
});