Warning

Scheduled for deletion

This legacy repository has been consolidated into cerul-ai/cerul at packages/js. Do not start new features or releases here. It remains temporarily available for historical and release recovery and will be deleted after final consolidation verification.

Cerul TypeScript SDK

Where video becomes citable.

The video search API for agents — meaning-based, grounded, timestamped.

Docs · Website · Main Repo ·

Install

npm install cerul

Quick Start

import { cerul } from "cerul";

const client = cerul(); // reads CERUL_API_KEY

const result = await client.search({ query: "Sam Altman on AGI timeline" });

for (const r of result.results) {
  console.log(r.title, r.url);
}

Get a free API key at cerul.ai/dashboard.

Examples

// Search with filters
const result = await client.search({
  query: "Jensen Huang on AI infrastructure",
  max_results: 5,
  ranking_mode: "rerank",
  include_answer: true,
  filters: { speaker: "Jensen Huang", published_after: "2024-01-01" },
});

// AI-generated answer
console.log(result.answer);

// Check credits
const usage = await client.usage();
console.log(`${usage.credits_remaining} credits remaining`);

Configuration

const client = cerul({
  apiKey: "cerul_sk_...",   // or CERUL_API_KEY env var
  timeout: 30_000,          // default 30s
  retry: true,              // retry 429/5xx/network errors
});

Error Handling

import { CerulError } from "cerul";

try {
  await client.search({ query: "test" });
} catch (error) {
  if (error instanceof CerulError) {
    console.error(error.status, error.code, error.message);
  }
}

Features

• Zero dependencies — native fetch (Node 18+, Bun, Deno, Cloudflare Workers)
• Full TypeScript types — complete type definitions included
• Retry with backoff — 429 reads Retry-After, 5xx exponential backoff
• Network error retry — timeouts and connection errors also retried when retry: true

Links

• CLI — curl -fsSL https://cli.cerul.ai/install.sh | bash
• Python SDK — pip install cerul
• Main repo — docs, skills, remote MCP

License

MIT