Python SDK quickstart

Esta guía todavía no está traducida a tu idioma: se muestra en inglés.

Python client for the LegalCloud API: read your legal documents, sites, resources and statistics, and embed documents in any Python web application (Django, Flask, FastAPI...).

Version 1.1.0 · Python 3.8+ · depends on requests
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-python-1.1.0.zip
pip install ./legalcloud

(or copy the inner legalcloud/ package next to your code and pip install requests).

Quick start

from legalcloud import LegalCloudClient

client = LegalCloudClient(token='lc_...', source='django', site_url='https://example.com')

page = client.list_documents(page=1, per_page=20)      # {documents, total, page, per_page}
for doc in client.iter_documents():                   # every page, lazily
    print(doc['id'], doc['title'])

html = client.get_document('abc123def456', lang='es')  # HTML of /d/{hash}
snippet = client.iframe_html('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.

Client options

Option	Default	Meaning
`token`	required	API token (`Authorization: Bearer`)
`source`	`custom`	Platform that embeds LegalCloud (analytics)
`site_url`	`''`	Public URL of your site (analytics)
`plugin_id`	generated	Stable id of this installation (analytics)
`base_url`	`https://api.legalcloud.info`	API origin
`embed_base_url`	`base_url` if given, else `https://dash.legalcloud.info`	Origin of `/d/{hash}` pages
`timeout`	`15`	Seconds per request
`max_retries`	`2`	Retries for 429, 5xx and network errors
`backoff`	`0.5`	Base seconds of the exponential backoff (a `Retry-After` header wins; capped at 30 s)

Methods

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

Method	Endpoint	Scope
`get_document(hash, lang)`	`GET /d/{hash}`	public / document token
`get_document_restrictions(hash, country)`	`GET /d/{hash}/restrictions`	public
`public_url(hash, lang, include_token)` · `iframe_html(...)`	(builds URLs / HTML)	-
`list_documents(page, per_page, site_id)` · `iter_documents()`	`GET /api/documents`	`documents:read`
`get_document_info(hash)`	`GET /api/documents/{hash}`	`documents:read`
`get_document_languages()` · `get_document_limits()`	`GET /api/documents/languages`, `/limits`	`documents:read`
`list_document_versions(hash)` · `get_document_version(hash, n)` · `diff_document_versions(hash, a, b)`	`GET /api/documents/{hash}/versions...`	`documents:read`
`list_sites()` · `get_site(id)` · `get_site_limits()`	`GET /api/sites...`	`sites:read`
`list_resources(...)` · `iter_resources()` · `get_resource_usage()` · `get_resource_statistics()`	`GET /api/resources...`	`resources:read`
`get_stats(days)` · `get_kpis()` · `get_views(...)` · `get_document_stats(hash, days)` · `get_document_visits(hash, ...)` · `get_source_breakdown(hash, days)` · `get_top_sites(hash, days)`	`GET /api/statistics/...`	`documents:read`
`list_tokens()` · `get_api_usage()` · `list_api_calls(...)`	`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.last_quota (X-Quota-Limit/Remaining/Reset, monthly plan quota) and client.last_rate_limit (X-RateLimit-*, per minute) hold the latest values.

from legalcloud import RateLimitError, NotFoundError, LegalCloudError

try:
    client.get_document_info('missing')
except NotFoundError:
    ...
except RateLimitError as e:
    print(e.retry_after, e.quota, e.rate_limit)
except LegalCloudError as e:     # base class: network errors, API errors...
    print(e)

Exception	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.retry_after`)
`ServerError`	5xx
`NetworkError`	no HTTP response

All inherit from ApiError (except NetworkError) and LegalCloudError; ApiError exposes status, code, body, quota, rate_limit.

Security

iframe_html() 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 include_token=False for documents that are public.

Next steps

Última actualización: 2026-10-27