Clous SDK for TypeScript / Node

Public data intelligence for AI agents — the official TypeScript / Node client.

Entity-resolved SEC/EDGAR filings, ownership, financials, fund holdings, governance, enforcement, and a live business-change events & monitors feed — fully typed, for humans and AI agents.

clous.ai · docs.clous.ai · examples

30-second quickstart

npm install @clousai/sdk

Get a free key at clous.ai (100 credits, no card), then:

import { Clous } from "@clousai/sdk";

// apiKey defaults to process.env.CLOUS_API_KEY
const clous = new Clous({ apiKey: "clous_live_..." });

// Search the EDGAR filing index.
const { data } = await clous.filings.search({ q: "NVIDIA", form_type: "8-K", limit: 5 });
for (const filing of data) console.log(filing);

// All XBRL facts for one company (Apple), filtered to revenue.
const revenue = await clous.financials.get("0000320193", { concept: "Revenues" });

// Grounded, cited answer over the filings.
const answer = await clous.answer({ q: "What did NVIDIA most recently disclose?", ticker: "NVDA" });
console.log(answer.data[0]);

Requires Node 18+ (for global fetch). SEC/EDGAR is live today; Clous is expanding across public data.

Key features

• Fully typed — params and the response envelope for every endpoint.
• Auto-pagination via async iterators — for await (const x of clous.filings.iterate(...)).
• Token-efficient — fields / output_schema projection trims payloads before they reach your LLM.
• Typed errors with request ids; automatic 429/5xx retries with backoff + jitter; timeouts.
• Zero runtime dependencies — uses the global fetch; ESM + CommonJS builds.
• OpenAI-compatible — clous.chat.completions.create({ model: "clous" }), or point the openai client at https://api.clous.ai/v1.

Authentication

Pass apiKey to the constructor, or set the CLOUS_API_KEY environment variable. The key is sent as Authorization: Bearer <key>.

const clous = new Clous();                       // reads CLOUS_API_KEY
const clous = new Clous({ apiKey: "clous_live_..." });
const clous = new Clous({
  apiKey: "clous_live_...",
  baseURL: "https://api.clous.ai", // default
  timeoutMs: 60_000,               // default
  maxRetries: 2,                   // default; retries 429/5xx with backoff
});

The response envelope

Every endpoint returns the same envelope. List endpoints carry a page block; single-resource lookups return a one-element data array.

interface Envelope<T> {
  data: T[];
  page: { limit: number; next_cursor: string | null; has_more: boolean };
  as_of?: string;
  source?: string;
  query_echo?: Record<string, unknown>;
  warnings?: string[];
}

Token efficiency

Trim the payload with a field projection or a server-side output schema — useful when feeding results to an LLM:

await clous.filings.search({
  form_type: "4",
  fields: ["accession", "company_name", "filed_at"], // or "a,b.c"
});

await clous.entities.search({ ticker: "NVDA", output_schema: { name: true, cik: true } });

Pagination

Pass cursor manually, or let the SDK stream every page for you:

// Manual:
let page = await clous.advisers.search({ state: "NY", limit: 100 });
while (page.page.has_more) {
  page = await clous.advisers.search({ state: "NY", limit: 100, cursor: page.page.next_cursor! });
}

// Auto — follows page.next_cursor to the end:
for await (const adviser of clous.advisers.iterate({ state: "NY", limit: 100 })) {
  console.log(adviser);
}

iterate() is available on every list resource (filings, entities, insider, holdings, managers, advisers, events, …).

Errors

Non-2xx responses throw a typed error carrying the HTTP status, the stable Clous error code, the request id, and the parsed body:

import { Clous, ClousNotFoundError, ClousRateLimitError, ClousAPIError } from "@clousai/sdk";

try {
  await clous.events.get("does-not-exist");
} catch (err) {
  if (err instanceof ClousNotFoundError) console.log(err.code);      // "not_found"
  if (err instanceof ClousRateLimitError) console.log(err.retryAfterSeconds);
  if (err instanceof ClousAPIError) console.log(err.status, err.requestId, err.body);
}

Error classes: ClousBadRequestError (400/422), ClousAuthenticationError (401), ClousPermissionError (403), ClousNotFoundError (404), ClousRateLimitError (429), ClousServerError (5xx), plus ClousConnectionError / ClousTimeoutError for transport failures. All extend ClousAPIError / ClousError.

The SDK automatically retries 429 and 5xx responses (honoring Retry-After) up to maxRetries with exponential backoff + jitter.

Monitoring & events

// Create a webhook endpoint and a monitor that fires on material NVDA events.
const ep = await clous.webhooks.endpoints.create({ url: "https://example.com/hook" });
const monitor = await clous.monitors.create({
  name: "NVIDIA material changes",
  target_type: "ticker",
  target_value: "NVDA",
  signals: ["sec.filing.new", "sec.8k.executive_change"],
  materiality: "medium",
  cadence: "1h",
  trigger_on_create: true,
  webhook_endpoint_id: (ep.data[0] as any).id,
});

await clous.monitors.pause((monitor.data[0] as any).id);
await clous.monitors.resume((monitor.data[0] as any).id);

// Read the events feed directly (what monitors match against).
for await (const event of clous.events.iterate({ ticker: "NVDA", importance: "high" })) {
  console.log(event);
}

OpenAI-compatible

Clous exposes an OpenAI-compatible chat endpoint. Use the Clous SDK:

const completion = await clous.chat.completions.create({
  model: "clous",
  messages: [{ role: "user", content: "Summarize Tesla's most recent 8-K." }],
});

…or point the official openai client straight at Clous:

import OpenAI from "openai";
const openai = new OpenAI({ apiKey: process.env.CLOUS_API_KEY, baseURL: "https://api.clous.ai/v1" });
const res = await openai.chat.completions.create({
  model: "clous",
  messages: [{ role: "user", content: "Summarize Tesla's most recent 8-K." }],
});

The answer is grounded strictly in SEC filing text; citations + a confidence basis ride along under a clous field on the completion.

Client surface

| Namespace | Endpoint(s) | | --- | --- | | clous.filings | /v1/filings, /v1/full-text, and /v1/filings/{accession}/{documents,extract,events,insiders,subsidiaries,crowdfunding,proxy-votes,briefing} | | clous.entities | /v1/entities | | clous.insider | /v1/insider (+ .form144()) | | clous.ownership | /v1/ownership | | clous.holdings / clous.managers | /v1/holdings, /v1/managers | | clous.advisers | /v1/advisers (+ .get(crd)) | | clous.iapdIndividuals / clous.brokerDealers / clous.formCrs | /v1/iapd-individuals, /v1/broker-dealers, /v1/form-crs | | clous.financials | /v1/financials (+ .get(cik)) | | clous.financialStatements | /v1/financial-statements | | clous.funds | /v1/funds/holdings, /v1/funds/providers | | clous.privateFunds / clous.privateFundStats | /v1/private-funds, /v1/private-fund-stats | | clous.raises / clous.proxyOfficers / clous.board / clous.compensation / clous.patentGrants | /v1/raises, /v1/proxy/officers, /v1/board, /v1/compensation, /v1/uspto-patent-grants | | clous.enforcement / clous.litigation / clous.ntLate / clous.tradingSuspensions / clous.whistleblower / clous.cyberIncidents | /v1/enforcement, /v1/litigation, /v1/nt-late, /v1/trading-suspensions, /v1/whistleblower, /v1/cyber-incidents | | clous.events | /v1/events (+ .get(id)) | | clous.monitors | /v1/monitors CRUD (+ .pause / .resume) | | clous.webhooks | /v1/webhooks/endpoints, /v1/webhooks/deliveries | | clous.meta | /v1/sources, /v1/account | | clous.answer(...) | /v1/answer | | clous.briefing(accession) | /v1/filings/{accession}/briefing | | clous.chat.completions.create(...) | /v1/chat/completions |

See examples/ for runnable scripts: quickstart.ts, paginate.ts, monitors.ts, openai-compatible.ts.

Part of the Clous platform

Clous is public data intelligence for AI agents — entity-resolved signals from public records and the web, monitored in real time, delivered with citations. SEC/EDGAR is live today; expanding across public data.

| | | | --- | --- | | Website | clous.ai | | Docs | docs.clous.ai · llms.txt | | TS / Node SDK | clous-js ← you are here | | Python SDK | clous-python | | MCP server | Mcp · hosted at mcp.clous.ai | | Claude Code plugin | claude-code-plugin | | Agent Skill | skill | | Recipes | cookbook | | Framework tools | integrations (LangChain · LlamaIndex · OpenAI · Vercel AI · CrewAI) |

License

MIT