TypeScript SDK

The official TypeScript/JavaScript SDK for the KLIQ AI API. Full type safety, auto-pagination, and automatic token refresh.

npm install @kliq-ai/sdk

KliqClient

The root client. Create one per application.

Methods

import { KliqClient } from '@kliq-ai/sdk';

const kliq = new KliqClient({
  apiKey: process.env.KLIQ_API_KEY!,
});

const tenant = kliq.forTenant('t_abc123');

KliqTenantClient

Tenant-scoped client with access to all resource APIs.

Properties

Observations

observations.create(input)

Returns: Promise<Observation>

observations.get(id)

Get a single observation by ID. Returns: Promise<Observation>

observations.list(params?)

Returns: Promise<PaginatedResponse<Observation>>

observations.listAll(params?)

Auto-paginating async iterator. Returns: AsyncIterable<Observation>

for await (const obs of tenant.observations.listAll({ status: 'completed' })) {
  console.log(obs.id, obs.status);
}

observations.createBatch(inputs)

Create multiple observations at once. Returns: Promise<Observation[]>

observations.delete(id)

Delete an observation. Returns: Promise<void>

observations.getUploadUrl(params)

Get a signed URL for direct image upload. Returns: Promise<{ uploadUrl: string; imageUrl: string }>

Locations

locations.create(input)

Returns: Promise<Location>

locations.get(id) / locations.list(params?) / locations.update(id, input) / locations.delete(id)

Standard CRUD operations with the same pagination pattern.

CvJobs

cv.start(input)

Returns: Promise<CvJob>

cv.get(id)

Returns: Promise<CvJob>

cv.waitForCompletion(id, options?)

Polls until the job completes or fails. Returns: Promise<CvJob>

cv.list(params?)

Returns: Promise<PaginatedResponse<CvJob>>

Webhooks

webhooks.create(input)

Returns: Promise<Webhook>

webhooks.list() / webhooks.delete(id)

Standard list and delete operations.

TrackedObjects (Catalog)

catalog.create(input) / catalog.import(config) / catalog.list(params?)

Manage the SKU/product catalog for CV model matching.

Verticals

verticals.list()

Returns: Promise<PaginatedResponse<Vertical>>

verticals.get(slug)

Returns: Promise<Vertical>

verticals.create(tenantId, params)

const vertical = await kliq.verticals.create('t_abc123', {
  slug: 'acme-wine-scan',
  name: 'WineScan',
  description: 'Fine wine authentication and condition grading.',
  brandColor: '#722F37',
});

Returns: Promise<Vertical>

Grading Schemas

gradingSchemas.listForVertical(slug)

Returns: Promise<PaginatedResponse<GradingSchema>>

gradingSchemas.get(id)

Returns: Promise<GradingSchema> — includes the attributes array.

gradingSchemas.create(tenantId, params)

const schema = await kliq.gradingSchemas.create('t_abc123', {
  verticalSlug: 'acme-wine-scan',
  slug: 'parker-100-point',
  name: 'Parker 100-Point Scale',
  standard: 'Robert Parker / Wine Advocate',
  overallFormula: { method: 'weighted_average', weightField: 'weight' },
  attributes: [
    { key: 'aroma', name: 'Aroma', type: 'scale', config: { min: 0, max: 15, step: 1 }, weight: 0.15, required: true },
    { key: 'flavor', name: 'Flavor', type: 'scale', config: { min: 0, max: 20, step: 1 }, weight: 0.20, required: true },
  ],
});

Returns: Promise<GradingSchema>

Catalog

catalog.categories.list(verticalSlug)

Returns: Promise<PaginatedResponse<CatalogCategory>>

catalog.types.list(categorySlug) / catalog.types.gradingGuide(typeSlug)

Returns grading guide descriptions and AI prompt hints for each attribute grade value.

catalog.items.list(typeSlug) / catalog.items.get(id) / catalog.items.search(params)

// Search across all public items
const results = await kliq.catalog.items.search({ search: 'charizard' });

// Get a specific item
const card = await kliq.catalog.items.get('pkmn-base-charizard-holo-4');
console.log(card.type.gradingSchemaSlug); // "psa-10-point"

catalog.items.create(tenantId, params)

Creates a private catalog item scoped to the tenant.

Returns: Promise<CatalogItem>

Inspections

Inspections are accessed via the tenant client: kliq.forTenant(id).inspections.

inspections.create(params)

const inspection = await tenant.inspections.create({
  catalogItemSlug: 'pkmn-base-charizard-holo-4',
  gradingSchemaSlug: 'psa-10-point',
  notes: 'Submitted by collector.',
});

Returns: Promise<Inspection>

inspections.list(params?)

Returns: Promise<PaginatedResponse<Inspection>>

inspections.get(id)

Returns: Promise<Inspection> — includes aiGrades, finalGrades, and status.

inspections.grade(id)

Triggers the AI grading pipeline. Returns: Promise<{ jobId: string; status: string }>

inspections.submitHumanGrades(id, params)

const finalized = await tenant.inspections.submitHumanGrades(inspection.id, {
  grades: { centering: 8, corners: 9, edges: 9, surface: 9 },
  notes: 'Minor centering offset on left border.',
});

console.log(finalized.finalGrades.overall); // 8.75
console.log(finalized.status); // "completed"

Returns: Promise<Inspection>

Buildings (BuildingScan)

buildings.create(input) / buildings.get(id) / buildings.list(params?) / buildings.update(id, input)

Manage buildings for inspection workflows.

Assets (BuildingScan)

assets.create(input) / assets.get(id) / assets.list(params?) / assets.update(id, input)

Manage individual building assets/components.

Visits

visits.create(input) / visits.get(id) / visits.list(params?)

Track inspection visits and link them to observations.

Types

Observation

interface Observation {
  id: string;
  tenantId: string;
  locationId: string;
  imageUrl: string;
  latitude?: number;
  longitude?: number;
  status: 'pending' | 'processing' | 'completed' | 'failed';
  metadata: Record<string, any>;
  createdAt: string;
  updatedAt: string;
}

CvJob

interface CvJob {
  id: string;
  observationId: string;
  model: string;
  status: 'queued' | 'processing' | 'completed' | 'failed';
  result?: {
    detections: Detection[];
    summary: Record<string, any>;
  };
  error?: string;
  createdAt: string;
  completedAt?: string;
}

Detection

interface Detection {
  objectName: string;
  confidence: number;
  boundingBox: { x: number; y: number; width: number; height: number };
  attributes: Record<string, any>;
}

PaginatedResponse

interface PaginatedResponse<T> {
  data: T[];
  cursor: {
    next: string | null;
    hasMore: boolean;
  };
}