JavaScript SDK quickstart

Dieser Leitfaden ist noch nicht in Ihre Sprache übersetzt.

Client for the LegalCloud API: read your legal documents, sites, resources and statistics, and embed documents in any JS/TS application (Node, serverless, bundlers).

Version 1.1.0 · Node 18+ (global fetch) · ES module + CommonJS · TypeScript types included · no dependencies
Default API origin https://api.legalcloud.info; public pages on https://dash.legalcloud.info

Install

The SDK is distributed as a ZIP from your dashboard (Downloads). Unzip it and install the folder:

unzip legalcloud_sdk-js-1.1.0.zip
npm install ./legalcloud

Quick start

import { LegalCloudClient } from '@legalcloud/sdk';      // or: const { LegalCloudClient } = require('@legalcloud/sdk');

const client = new LegalCloudClient({ token: 'lc_...', source: 'express', siteUrl: 'https://example.com' });

const { documents, total } = await client.listDocuments({ page: 1, perPage: 20 });
for await (const doc of client.iterDocuments()) console.log(doc.id, doc.title);

const html = await client.getDocument('abc123def456', 'es');                 // HTML of /d/{hash}
const iframe = client.iframeHtml('abc123def456', { lang: 'es', height: 600 });

Create the token in the dashboard (Organization > API). A document token only opens its own document; to call the rest of the API use a token with the scopes shown below.

Options

Option	Default	Meaning
`token`	required	API token (`Authorization: Bearer`)
`source`	`custom`	Platform that embeds LegalCloud (analytics)
`siteUrl`	`window.location.origin` or `''`	Public URL of your site (analytics)
`pluginId`	generated	Stable id of this installation (analytics)
`baseUrl`	`https://api.legalcloud.info`	API origin
`embedBaseUrl`	`baseUrl` if given, else `https://dash.legalcloud.info`	Origin of `/d/{hash}` pages
`timeout`	`15000`	Milliseconds per request
`maxRetries`	`2`	Retries for 429, 5xx and network errors
`backoff`	`500`	Base milliseconds of the exponential backoff (a `Retry-After` header wins; capped at 30 s)
`fetch`	global `fetch`	Custom fetch implementation

Methods

Every method returns the data of the API envelope ({"success": true, "data": ...}).

Method	Endpoint	Scope
`getDocument(hash, lang)`	`GET /d/{hash}`	public / document token
`getDocumentRestrictions(hash, country)`	`GET /d/{hash}/restrictions`	public
`publicUrl(hash, {lang, includeToken})` · `iframeHtml(hash, {lang, height, includeToken})`	(builds URLs / HTML)	-
`listDocuments({page, perPage, siteId})` · `iterDocuments()`	`GET /api/documents`	`documents:read`
`getDocumentInfo(hash)`	`GET /api/documents/{hash}`	`documents:read`
`getDocumentLanguages()` · `getDocumentLimits()`	`GET /api/documents/languages`, `/limits`	`documents:read`
`listDocumentVersions(hash)` · `getDocumentVersion(hash, n)` · `diffDocumentVersions(hash, from, to)`	`GET /api/documents/{hash}/versions...`	`documents:read`
`listSites()` · `getSite(id)` · `getSiteLimits()`	`GET /api/sites...`	`sites:read`
`listResources({type, siteId, page, perPage})` · `iterResources()` · `getResourceUsage()` · `getResourceStatistics()`	`GET /api/resources...`	`resources:read`
`getStats({days})` · `getKpis()` · `getViews({documentHash, days})` · `getDocumentStats(hash, {days})` · `getDocumentVisits(hash, {page, limit, days})` · `getSourceBreakdown(hash, {days})` · `getTopSites(hash, {days})`	`GET /api/statistics/...`	`documents:read`
`listTokens()` · `getApiUsage()` · `listApiCalls({...})`	`GET /api/account/...`	`organization:read`

The SDK covers the read endpoints. Creating, editing and deleting content is done in the dashboard.

Quota and errors

After every call client.lastQuota (X-Quota-Limit/Remaining/Reset, monthly plan quota) and client.lastRateLimit (X-RateLimit-*, per minute) hold the latest values.

import { RateLimitError, NotFoundError, LegalCloudError } from '@legalcloud/sdk';

try {
  await client.getDocumentInfo('missing');
} catch (e) {
  if (e instanceof NotFoundError) { /* ... */ }
  else if (e instanceof RateLimitError) console.log(e.retryAfter, e.quota, e.rateLimit);
  else if (e instanceof LegalCloudError) console.log(e.message);   // base class
}

Error	When
`ValidationError`	400 / 422
`AuthenticationError`	401: missing, invalid, revoked or expired token
`PermissionDeniedError`	403: scope missing or feature not in the plan (`e.code`: `SCOPE_FORBIDDEN`, `PLAN_UPGRADE_REQUIRED`...)
`NotFoundError`	404
`RateLimitError`	429: monthly quota or per-minute limit (`e.retryAfter` seconds)
`ServerError`	5xx
`NetworkError`	no HTTP response

ApiError (all but NetworkError) exposes status, code, body, quota, rateLimit, retryAfter.

Security

iframeHtml() puts the token in the URL by default (the only way an iframe can authenticate). That URL ends up in logs and browser history: use a document token for embeds, or pass includeToken: false for public documents. Never ship a full-scope token in browser code.

Next steps

Zuletzt aktualisiert: 2026-10-27