Shadow Lighthouse HTTP API¶

The HTTP service exposes source-local and multi-source read surfaces over local Lighthouse indexes.

Start the multi-source server:

uv run shadow-lighthouse --config config.example.toml serve \
  --host 127.0.0.1 \
  --port 8766

Start a single-source server:

uv run shadow-lighthouse --config config.example.toml serve \
  --source cninfo_announcements \
  --host 127.0.0.1 \
  --port 8766

Multi-Source Endpoints¶

Endpoint	Purpose
`GET /health`	Service health and initialized source names
`GET /sources`	Source summaries, index presence, and document counts
`GET /documents`	Merged reverse-time document stream
`GET /documents/{id}`	Find a document across sources
`GET /objects/{sha256}`	Find documents referencing one object
`GET /search?q=...`	Fan-out FTS search across source-local indexes
`GET /news/search?q=...`	Search the global news index
`GET /tables/search?q=...`	Fan-out structured table search

GET /documents accepts:

Parameter	Meaning
`source`	Optional repeated source filter
`start`	Inclusive lower bound for `published_at`
`end`	Inclusive upper bound for `published_at`
`limit`	Result limit, default `50`, max `500`

Example:

curl "http://127.0.0.1:8766/documents?source=cninfo_announcements&limit=24"

Source-Scoped Endpoints¶

All source-local surfaces are also available under /sources/{source}:

Endpoint	Purpose
`GET /sources/{source}/status`	Source status
`GET /sources/{source}/documents`	Source-local reverse-time documents
`GET /sources/{source}/documents/{id}`	Source-local document lookup
`GET /sources/{source}/objects/{sha256}`	Source-local object lookup
`GET /sources/{source}/objects/{sha256}/file`	Serve original object bytes
`GET /sources/{source}/issuers/{query}/documents`	Documents for issuer name/code/id
`GET /sources/{source}/issuer-counts`	Per-issuer document/object counts
`GET /sources/{source}/search?q=...`	Source-local FTS search
`GET /sources/{source}/tables/search?q=...`	Source-local table row search

Single-Source Endpoints¶

When serve --source <name> is used, the source prefix is omitted:

Endpoint	Purpose
`GET /status`	Source status
`GET /documents`	Source-local documents
`GET /documents/{id}`	Document lookup
`GET /objects/{sha256}`	Object lookup
`GET /objects/{sha256}/file`	Serve original object bytes
`GET /issuers/{query}/documents`	Documents for issuer name/code/id
`GET /issuer-counts`	Per-issuer counts
`GET /search?q=...`	FTS search
`GET /tables/search?q=...`	Table row search

Document IDs¶

Lighthouse accepts raw source ids such as:

announcement:1225267495

It also accepts AI-facing ids for CNInfo documents:

cninfo:announcement:1225267495

Multi-source document lookup returns a list because the caller may not know which source owns the id. Source-local lookup returns one document object.

Artifact Content¶

Derived artifacts can be listed and fetched through document routes:

curl "http://127.0.0.1:8766/sources/manual_media/documents/manual:call:1/artifacts"
curl "http://127.0.0.1:8766/sources/manual_media/documents/manual:call:1/artifacts/transcript/content"

Use these routes for OCR text, transcripts, extracted table JSON, and other derived content written by Lighthouse extractors.