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.

Ingestion preview (not system of record)

The ingestion API validates events and API keys today, but does not yet persist model calls, prompts, incidents, or evidence into audit logs or the evidence vault. Use the console for text evidence records and governance workflows until full ingestion ships.

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,
});