API / public contracts

Hugin API

Public JSON contracts for monitors, dashboards, mirrors, and evidence clients. Probe freshness with HEAD, reuse ETags with If-None-Match, then fetch the body only when the record changes.

18documented HEAD probes6hash receipt headers7civic and archive validators

Start hereHEAD /api/v1/civic/bundle

Check freshness before fetching bodies.

Hugin keeps public reads cheap and cache-friendly. A monitor can send a HEAD request, compare the ETag, and skip the heavier JSON response when the bundle is unchanged.

curl -I https://hugin.studio/api/v1/civic/bundle
curl https://hugin.studio/api/v1/civic/bundle \
  -H 'If-None-Match: <etag-from-last-response>'

Machine index JSON OpenAPI Integration manifest Limits JSON Status JSON

Guardrails

Open reads with explicit budgets and public status.

Public status Cost transparency

60 requestsper IP, per minute300s index cachestale-while-revalidate enabledFail closeddaily public spend guardrailNo accountrequired for public reads

HEAD /api/v1X-Hugin-API-Index-ETagAPI index validators.

HEAD /api/v1/statusX-Hugin-Status-ETagPublic status validators.

HEAD /api/v1/limitsX-Hugin-Limits-ETagPublic budget and limiter validators.

HEAD /api/v1/integrationsX-Hugin-Integration-Manifest-ETagIntegration manifest validators.

HEAD /api/v1/openapiX-Hugin-OpenAPI-ETagOpenAPI contract validators.

HEAD /api/v1/civic/bundleX-Hugin-Civic-Bundle-ETagCivic bundle manifest validators.

Discovery

Machine-readable entrypoints

Start with the index, then let generated clients use the OpenAPI contract or the integration manifest.

GET /api/v1Index JSONRoutes, budgets, limits, validators, and license context.

GET /api/v1/openapiOpenAPI 3.1Generated-client contract with the same HEAD probes documented.

GET /api/v1/integrationsIntegration manifestEmbed paths, event shapes, direct scan handoffs, and summaries.

Open index JSON

Evidence

Reports, search, and archive reads

Pull recent evidence packets, search public reports, or resolve a single stable report URL.

GET /api/v1/recentRecent archiveLatest reports as JSON or CSV, capped for public clients.

GET /api/v1/searchSearchFind reports by title, community, author, or public URL context.

GET /api/v1/r/{slug}Report detailVerdict, evidence trail, metrics, flags, and exportable context.

Recent reports

Civic

Hash-verifiable civic bundles

Mirror neutral civic packets, source receipts, claim ledgers, and case-file manifests with stable hashes.

GET /api/v1/civic/bundleBundle manifestArtifact URLs, hashes, dependency links, and mirror storage paths.

GET /api/v1/civic/source-receiptsSource receiptsAccepted observations, source errors, payload hashes, and review gates.

GET /api/v1/civic/casesCase indexPublic-record case files with neutral source and entity guardrails.

Civic bundle