Clause Export API

Endpoints

Authentication

Same auth as the rest of Hugo. From a browser session the cookie is enough. From a shell, use the CF Access service token already configured for *.nordiclawfirm.com:

source ~/.env.cloudflare
curl -sS \
  -H "CF-Access-Client-Id: $CF_ACCESS_CLIENT_ID" \
  -H "CF-Access-Client-Secret: $CF_ACCESS_CLIENT_SECRET" \
  "https://hugo.nordiclawfirm.com/funds/$FUND/export/clauses?view=library&format=ndjson"

Views

Each view returns a different shape and carries a distinct schema discriminator in the schema field of the JSON envelope and in the X-Hugo-Schema header on NDJSON / CSV responses.

Filters

Multi-value filters accept either repeated params (?source=manual&source=ai) or comma-separated lists (?source=manual,ai). Both work.

Common (all views)

Library-only

Cross-fund-only (/export/clauses)

MSL-only

ISL-only

Response shapes

JSON envelope (default)

{
  "schema": "clauses_library_v1",
  "schema_version": "1.0.0",
  "generated_at": "2026-04-12T21:28:46.037Z",
  "fund": { "id": "fund_northstar8", "name": "Northstar Equity Partners VIII" },
  "filters_applied": { "view": "library", "format": "json", "limit": 3, "lifecycle_status": ["live"] },
  "fields": ["id", "fund_id", "clause_name", "..."],
  "count": 3,
  "truncated": true,
  "clauses": [ /* ... */ ]
}

fund is null for cross-fund responses.

NDJSON

One JSON object per line, no envelope. Metadata moves to response headers so single-line tools like jq -c and DuckDB's read_json_auto('/dev/stdin') can consume it directly.

CSV

Content-Type: text/csv; charset=utf-8. Header row from the active projection (fields= or the view's default). Multi-value cells (e.g. elected_by) are joined with |. RFC 4180 quoting (" escaped as ""). Same X-Hugo-* metadata headers as NDJSON.

Errors

400 responses use the apiBadRequest helper:

{
  "error": "Unknown filter parameter \"bogus\"",
  "code": "invalid_filter",
  "parameter": "bogus",
  "allowed": ["bpmsl", "clause_group_id", "clause_name_id", "..."]
}

Code values: invalid_filter, invalid_value, missing_required, limit_exceeded, not_found (e.g. wrong-fund target_lp_id or commitment_id).

Schema stability

Version is exposed both in the JSON envelope (schema_version) and as the X-Hugo-Schema-Version response header.

Examples

1. Library view, NDJSON, piped through jq

curl -sS "${AUTH[@]}" \
  "$H/funds/$F/export/clauses?view=library&format=ndjson&lifecycle_status=live" \
  | jq -c '{id, clause_name, lp_count: (.assignments|length)}'

2. MSL view as JSON, projected to a few fields

curl -sS "${AUTH[@]}" \
  "$H/funds/$F/export/clauses?view=msl&fields=clause_id,clause_name,elected_by,eligible_lps" \
  | jq '.clauses[] | select((.elected_by | length) > 0)'

3. Per-LP ISL view as CSV

curl -sS "${AUTH[@]}" \
  "$H/funds/$F/export/clauses?view=isl&commitment_id=$COMMITMENT_ID&format=csv&fields=clause_id,clause_name,origin,source_lp_name,text" \
  > clauses.csv

4. Cross-fund library across two funds

curl -sS "${AUTH[@]}" \
  "$H/export/clauses?fund_id=$F1&fund_id=$F2&format=ndjson&lifecycle_status=live"

5. DuckDB ingest

curl -sS "${AUTH[@]}" \
  "$H/funds/$F/export/clauses?view=library&format=ndjson" \
  | duckdb -c "SELECT clause_name, count(*) FROM read_json_auto('/dev/stdin') GROUP BY 1 ORDER BY 2 DESC"

Operational notes

• loadMslData() is cached for 60 s per fund (SCOPE_MFN_BUNDLE). MSL exports off a warm cache are cheap; cold exports do ~11 D1 round trips.
• The cross-fund variant loops loadMslData per fund, so the MSL_CROSS_FUND_FUND_LIMIT = 5 cap exists to bound latency.
• Hugo has only one Worker environment (hugo.nordiclawfirm.com); there is no preview env. Smoke testing is done by deploying then curling.

Roadmap

Deferred from v1, considered for v1.1+:

• resolve_definitions=true — inline-substitute [Defined Term] placeholders using the existing applyDefinitions helper. Reviewer flagged this as Hugo's potential killer differentiator.
• True row-by-row NDJSON streaming — needs loadMslData / loadMfnData restructuring to yield incrementally.
• Cursor pagination — for now, large result sets get truncated: true at the limit cap.
• Saved exports — name a filter set, get a stable URL that re-runs on each fetch. Power users would use this as a webhook target.
• OpenAPI doc generated from the same allowlist the handler validates against, served at /funds/:fundId/export/openapi.json.
• ETag + If-None-Match so polling pipelines are cheap.