Explorer API Reference

All server-side API endpoints available in the jinflow Explorer.

These are internal Explorer APIs, not a public REST API. They serve the Explorer web UI. Documented here for transparency and for teams building integrations.

Health & Status

`GET /health`

Health check with DB connectivity status.

Parameter	In	Required	Type	Description
(none)

Response: { status, mode?, db?, sizeMb?, tenants?, downloading?, errors?, initialized? } — shape varies by mode. Returns status: "ok" with DB info in local mode, or KLS store stats in R2 mode. HTTP 503 with status: "error" on failure.

`GET /api/identity`

Git identity (name/email) for the current user, optionally scoped to a tenant.

Parameter	In	Required	Type	Description
`tenant`	query	no	string	Tenant slug to scope identity lookup

Response: { name, email } from git config.

`GET /api/store-status`

KLS store download progress. Only meaningful in R2 mode.

Parameter	In	Required	Type	Description
(none)

Response: { active: false } when not in KLS store mode. Otherwise { active, initialized, ready, downloading, error, tenants[] } where each tenant entry has compositeId, tenantId, displayName, pack, sizeMb, status, hasSis.

`GET /api/db-status/[tenant]`

Lightweight mtime/generation poll for the DbWatcher component. No DuckDB query — just a stat() call.

Parameter	In	Required	Type	Description
`tenant`	path	yes	string	Composite tenant ID (e.g. `millesime.domaine_zufferey`)

Response: { generation, mtime, sizeMb? } — mtime is ISO timestamp of KLS file, generation is an in-memory counter incremented on DB swap.

Search

`GET /api/jumpbar`

Global search across all content types. Supports three modes: tenants (list all tenants), summary (finding severity counts), and search (full-text search across signals, theses, taxonomies, entities, SMEbits, BitBundles, people, dimensions, and glossary).

Parameter	In	Required	Type	Description
`mode`	query	no	string	`search` (default), `tenants`, or `summary`
`tenant`	query	yes*	string	Tenant slug (required for `search` and `summary`)
`q`	query	yes*	string	Search query, min 1 char (required for `search`)

Response (search): { probes[], hypotheses[], taxonomies[], entities[], smebits[], bitbundles[], people[], dimensions[], glossary[] } — each array contains matching items with tri-lingual names and metadata.

Response (tenants): { tenants[{ id, name, source }] }

Response (summary): { summary: { total, high, medium, low, money } }

Content Delivery

`GET /api/logo/[tenant]`

Tenant logo image. Tries DB-stored logo first, falls back to filesystem. Cached 24 hours.

Parameter	In	Required	Type	Description
`tenant`	path	yes	string	Tenant slug or composite ID

Response: Binary image (PNG, SVG, JPEG, or WebP) with appropriate Content-Type. HTTP 404 if no logo found.

`GET /api/pipeline/[tenant]/[artifact_key]`

Pipeline DAG artifact from the KLS.

Parameter	In	Required	Type	Description
`tenant`	path	yes	string	Tenant slug
`artifact_key`	path	yes	string	`graph_json` or `graph_html`

Response: JSON (for graph_json) or HTML (for graph_html) pipeline graph. Cached 1 hour. HTTP 404 if not found.

`GET /api/reports/[tenant]/[report_key]`

PDF report blob from the KLS report_pdfs table.

Parameter	In	Required	Type	Description
`tenant`	path	yes	string	Tenant slug
`report_key`	path	yes	string	Report identifier (lowercase alphanumeric + underscores)

Response: application/pdf binary with inline Content-Disposition. Cached 1 hour. HTTP 404 if not found.

Lineage & Explanation

`GET /api/explain`

Level 2 lineage: source Gold records that contributed to a finding. Queries Gold tables based on entity type and returns matching rows grouped by source table.

Parameter	In	Required	Type	Description
`tenant`	query	yes	string	Tenant slug
`entity_type`	query	no	string	Entity type (`Material`, `Case`, `BillingEvent`, `CostCentre`)
`entity_id`	query	yes	string	Entity identifier
`time_bucket`	query	no	string	Month filter (e.g. `2024-03`)

Response: { entity_type, entity_id, time_bucket, groups[] } where each group has { table, label, count, rows[] }. Rows are raw Gold records (up to 20 per group).

`GET /[tenant]/api/explain/[finding_id]`

Level 1+2 lineage: finding metadata plus source Gold records. Looks up the finding by ID, then calls the explainer to resolve source records.

Parameter	In	Required	Type	Description
`tenant`	path	yes	string	Tenant slug
`finding_id`	path	yes	string	Finding identifier

Response: { explanation } containing finding metadata and source record groups. HTTP 404 if finding not found.

`POST /api/explain-narrative`

Level 4 lineage: AI-generated natural-language explanation via Claude API. Enriches the finding with entity attributes and signal metadata before generating.

Parameter	In	Required	Type	Description
`tenant`	body	yes	string	Tenant slug
`finding`	body	yes	object	Finding object (probe_id, entity_type, entity_id, time_bucket, severity, money_at_risk, evidence)
`locale`	body	no	string	`en` (default), `de`, or `fr`

Response: { narrative, model } — narrative is a 3-4 sentence explanation, model is the Claude model used. HTTP 503 if ANTHROPIC_API_KEY is not set. HTTP 502 on API errors.

Drift Detection

`GET /api/drift`

Compare KLS build commit against GitHub remote HEAD. Reads _jinflow_snapshot and _jinflow_afs_remote from the KLS, then calls the GitHub Compare API. Cached 5 minutes per tenant.

Parameter	In	Required	Type	Description
`tenant`	query	yes	string	Tenant slug

Response: { status, ahead_by?, build_commit?, remote_head?, commits[]?, files[]? } where status is in_sync, behind, no_build_info, no_remote, repo_not_found, api_error, or fetch_error. Commits include sha, author, date, message. Files include filename and status.

KLS Store

`POST /api/refresh`

Invalidate cached R2 files and trigger re-download. Only active in KLS store mode. Also accepts GET for convenience.

Parameter	In	Required	Type	Description
`scope`	body/query	no	string	`all` (default), `pack`, or `tenant`
`pack`	body/query	no	string	Pack name (when scope=`pack`)
`tenant`	body/query	no	string	Tenant ID (when scope=`tenant`)

Response: { status, scope, pack?, tenant?, invalidated, tenants, ready } — counts of invalidated and re-downloaded entries. Returns { status: "skipped", reason } when not in KLS store mode.

Saved Views

`GET /api/views`

List saved views, optionally filtered by entity.

Parameter	In	Required	Type	Description
`tenant`	query	yes	string	Tenant slug
`entity`	query	no	string	Entity/dimension key to filter by

Response: { views[] } — array of saved view objects.

`POST /api/views`

Create a new saved view.

Parameter	In	Required	Type	Description
`tenant`	body	yes	string	Tenant slug
`entity`	body	yes	string	Entity/dimension key
`name`	body	yes	string	View display name
`params`	body	yes	object	View parameters (filters, sort, etc.)
`author`	body	no	string	Author name

Response: { view } — the created view object.

`PUT /api/views`

Update an existing saved view.

Parameter	In	Required	Type	Description
`tenant`	body	yes	string	Tenant slug
`view_id`	body	yes	string	View identifier
`name`	body	no	string	Updated name
`params`	body	no	object	Updated parameters

Response: { ok } — boolean success flag.

`DELETE /api/views`

Delete a saved view.

Parameter	In	Required	Type	Description
`tenant`	query	yes	string	Tenant slug
`view_id`	query	yes	string	View identifier

Response: { ok } — boolean success flag.

Signal Builder

`GET /api/probe-builder/list`

List all signal, perspective, thesis, and verdict definitions available in the AFS.

Parameter	In	Required	Type	Description
`tenant`	query	yes	string	Tenant slug

Response: { probes[{ probe_id, type, description, contract }] }

`GET /api/probe-builder/load`

Load YAML source for a single signal/perspective/thesis/verdict.

Parameter	In	Required	Type	Description
`tenant`	query	yes	string	Tenant slug
`probe_id`	query	yes	string	Signal identifier (must match `^(probe_\|assessment_\|hyp_\|diag_)[a-z][a-z0-9_]*$`)

Response: { probe_id, yaml } — raw YAML source string. HTTP 404 if not found.

`POST /api/probe-builder/save`

Write signal YAML to the AFS signals directory.

Parameter	In	Required	Type	Description
`probe_id`	body	yes	string	Signal identifier (must start with `probe_`)
`yaml`	body	yes	string	YAML content
`force`	query	no	boolean	`true` to overwrite existing file (default: false)

Response: { saved, path? } on success. HTTP 409 if file exists and force is not set. HTTP 400 on invalid probe_id.

`POST /api/probe-builder/validate`

Validate signal YAML against contracts. Writes YAML to a temp file and runs signalcheck.py.

Parameter	In	Required	Type	Description
`yaml`	body	yes	string	YAML content to validate

Response: { valid, errors[] } — valid is boolean, errors is an array of error messages (empty when valid).

`POST /api/probe-builder/compile`

Compile signal YAML to SQL. Pipes YAML into probecompile_single.py via stdin.

Parameter	In	Required	Type	Description
`yaml`	body	yes	string	YAML content to compile

Response: { ok, sql? } on success, { ok: false, errors[] } on failure.

Notebooks

`GET /[tenant]/api/notebook`

Get the tenant notebook. Auto-creates an empty notebook if none exists.

Parameter	In	Required	Type	Description
`tenant`	path	yes	string	Tenant slug

Response: { notebook: { tenant_id, cells, created_at, updated_at } } — cells is a JSON string of cell array.

`POST /[tenant]/api/notebook/cells`

Add a cell to the tenant notebook.

Parameter	In	Required	Type	Description
`tenant`	path	yes	string	Tenant slug
`cell`	body	yes	object	Cell object with `type` (one of: `narrative`, `view`, `reference`, `discussion`, `action`) and type-specific fields
`author`	body	no	string	Author name

Response: { notebook } — updated notebook. HTTP 201 on success.

`PUT /[tenant]/api/notebook/cells/[cell_id]`

Update an existing cell in the tenant notebook.

Parameter	In	Required	Type	Description
`tenant`	path	yes	string	Tenant slug
`cell_id`	path	yes	string	Cell identifier
`updates`	body	yes	object	Fields to update
`author`	body	no	string	Author name

Response: { notebook } — updated notebook. HTTP 404 if cell not found.

`DELETE /[tenant]/api/notebook/cells/[cell_id]`

Delete a cell from the tenant notebook.

Parameter	In	Required	Type	Description
`tenant`	path	yes	string	Tenant slug
`cell_id`	path	yes	string	Cell identifier

Response: { notebook } — updated notebook. HTTP 404 if cell not found.

`POST /[tenant]/api/notebook/cells/[cell_id]/discussion`

Add a reply to a discussion cell.

Parameter	In	Required	Type	Description
`tenant`	path	yes	string	Tenant slug
`cell_id`	path	yes	string	Discussion cell identifier
`author`	body	yes	string	Reply author name
`text`	body	yes	object	Reply text with `en`/`de`/`fr` keys
`date`	body	no	string	ISO date (defaults to today)

Response: { notebook } — updated notebook. HTTP 201 on success. HTTP 404 if discussion cell not found.

`GET /[tenant]/api/notes`

List all notes for a tenant.

Parameter	In	Required	Type	Description
`tenant`	path	yes	string	Tenant slug

Response: { notes[] } — array of note summary objects.

`POST /[tenant]/api/notes`

Create a new note.

Parameter	In	Required	Type	Description
`tenant`	path	yes	string	Tenant slug
`title`	body	yes	string	Note title
`tags`	body	no	string[]	Optional tags

Response: { note } — the created note object. Author is auto-resolved from git identity.

`GET /[tenant]/api/notes/[note_id]`

Get a single note by ID.

Parameter	In	Required	Type	Description
`tenant`	path	yes	string	Tenant slug
`note_id`	path	yes	string	Note identifier

Response: { note } — full note object with cells. HTTP 404 if not found.

`POST /[tenant]/api/notes/[note_id]`

Add a cell or discussion reply to a note.

Parameter	In	Required	Type	Description
`tenant`	path	yes	string	Tenant slug
`note_id`	path	yes	string	Note identifier
`cell`	body	no	object	Cell to add (if adding a cell)
`reply`	body	no	object	Reply object with `text` (if adding a discussion reply)
`cell_id`	body	no	string	Target cell for reply (required with `reply`)

Response: { cell_id } when adding a cell, { ok } when adding a reply. Provide either cell or reply+cell_id.

`PUT /[tenant]/api/notes/[note_id]`

Update a note’s metadata or a cell within a note.

Parameter	In	Required	Type	Description
`tenant`	path	yes	string	Tenant slug
`note_id`	path	yes	string	Note identifier
`cell_id`	body	no	string	Cell to update (if updating a cell)
`updates`	body	no	object	Cell field updates (required with `cell_id`)
(other)	body	no	object	Note metadata fields (if no `cell_id`)

Response: { ok } — boolean success flag.

`DELETE /[tenant]/api/notes/[note_id]`

Delete a note or a cell within a note.

Parameter	In	Required	Type	Description
`tenant`	path	yes	string	Tenant slug
`note_id`	path	yes	string	Note identifier
`cell_id`	query	no	string	If provided, deletes this cell instead of the entire note

Response: { ok } — boolean success flag.

Taxonomy & Dimensions

`GET /[tenant]/taxonomies/[taxonomy_id]/members`

List or search taxonomy members.

Parameter	In	Required	Type	Description
`tenant`	path	yes	string	Tenant slug
`taxonomy_id`	path	yes	string	Taxonomy identifier
`node_id`	query	no	string	Filter members by taxonomy node
`q`	query	no	string	Full-text search across members (overrides `node_id`)

Response: Array of member objects.

`GET /[tenant]/taxonomies/cardinality/member`

Cross-taxonomy mappings for a single member.

Parameter	In	Required	Type	Description
`tenant`	path	yes	string	Tenant slug
`id`	query	yes	string	Member identifier

Response: Array of mapping objects showing which taxonomy nodes the member belongs to.

`GET /[tenant]/taxonomies/cardinality/members`

Members shared between two taxonomy nodes.

Parameter	In	Required	Type	Description
`tenant`	path	yes	string	Tenant slug
`a`	query	yes	string	First taxonomy ID
`b`	query	yes	string	Second taxonomy ID
`nodeA`	query	no	string	Node filter in first taxonomy
`nodeB`	query	no	string	Node filter in second taxonomy
`dim`	query	no	string	Dimension type filter

Response: Array of shared member objects.

`GET /[tenant]/taxonomies/cardinality/fanout`

Fanout distribution between two taxonomies (how many nodes in B each node in A maps to).

Parameter	In	Required	Type	Description
`tenant`	path	yes	string	Tenant slug
`a`	query	yes	string	First taxonomy ID
`b`	query	yes	string	Second taxonomy ID
`dim`	query	no	string	Dimension type filter

Response: Distribution object with fanout statistics.

`GET /[tenant]/taxonomies/cardinality/detail`

Cardinality metrics between two taxonomies.

Parameter	In	Required	Type	Description
`tenant`	path	yes	string	Tenant slug
`a`	query	yes	string	First taxonomy ID
`b`	query	yes	string	Second taxonomy ID
`dim`	query	no	string	Dimension type filter

Response: Detail object with cardinality metrics (counts, ratios).

`GET /[tenant]/dimensions/[entity]/export`

CSV export of a dimension table (up to 1M rows).

Parameter	In	Required	Type	Description
`tenant`	path	yes	string	Tenant slug
`entity`	path	yes	string	Dimension/entity key
`q`	query	no	string	Search filter
`sort`	query	no	string	Column to sort by
`order`	query	no	string	`asc` (default) or `desc`
`f.*`	query	no	string	Column filters (e.g. `f.is_active=true`)

Response: text/csv file download with Content-Disposition: attachment.

jinflow is a jazzisnow product

v0.45.1 · built 2026-04-17 08:14 UTC 