{"openapi":"3.1.0","info":{"title":"c:node Contract-API","description":"Scope/licence-aware sandbox & contract API over the belegbar graph.","version":"0.1.0"},"paths":{"/v1/health":{"get":{"summary":"Health","operationId":"health_v1_health_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/v1/usage":{"get":{"summary":"Usage","description":"The calling key's own usage — the belegbar basis for a metered contract.\n\n``ledger`` is the persisted count of billable events for this key over [since, until):\ndelivered answers, billable (grounded) answers, ingests, mean factscore. ``detail=true``\nreturns the individual rows those counters sum — every number is drillable to its events.\nThe rolling in-process ``used`` counter (this process, all /v1 calls) is kept for continuity.","operationId":"usage_v1_usage_get","parameters":[{"name":"since","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"window start: epoch, ISO, or 'Nd'/'Nh' ago","title":"Since"},"description":"window start: epoch, ISO, or 'Nd'/'Nh' ago"},{"name":"until","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"window end (exclusive): epoch or ISO","title":"Until"},"description":"window end (exclusive): epoch or ISO"},{"name":"detail","in":"query","required":false,"schema":{"type":"boolean","description":"include the raw ledger rows behind the counters","default":false,"title":"Detail"},"description":"include the raw ledger rows behind the counters"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":1000,"minimum":1,"default":100,"title":"Limit"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/profiles":{"get":{"summary":"Profiles","description":"Self-documenting catalogue — the licence posture of each servable profile.","operationId":"profiles_v1_profiles_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/v1/graph":{"get":{"summary":"Graph","operationId":"graph_v1_graph_get","parameters":[{"name":"profile","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"scope profile name","title":"Profile"},"description":"scope profile name"},{"name":"key","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"API key (or X-API-Key header)","title":"Key"},"description":"API key (or X-API-Key header)"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/attributions":{"get":{"summary":"Attributions","operationId":"attributions_v1_attributions_get","parameters":[{"name":"profile","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Profile"}},{"name":"key","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/provenance":{"get":{"summary":"Provenance","description":"The proof behind one fact: authority, verification state, licence, uncertainty, hash.","operationId":"provenance_v1_provenance_get","parameters":[{"name":"ref","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"standard_ref, e.g. CELEX:32016R0679","title":"Ref"},"description":"standard_ref, e.g. CELEX:32016R0679"},{"name":"label","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"concept label","title":"Label"},"description":"concept label"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/audit":{"get":{"summary":"Audit","description":"A regulatory-impact audit record for 'which companies does law X affect?'.","operationId":"audit_v1_audit_get","parameters":[{"name":"act","in":"query","required":true,"schema":{"type":"string","description":"named EU act, e.g. ArtificialIntelligenceAct","title":"Act"},"description":"named EU act, e.g. ArtificialIntelligenceAct"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/betroffenheit":{"get":{"summary":"Betroffenheit","description":"Regionale Betroffenheit: Gesetz → NACE-Sektor → betroffene Firmen → Bundesland → regionale\nKennzahlen (BIP, Arbeitslosenquote, Einkommen). Erweitert /v1/audit um die regionale Dimension\n(Handelsregister-Sitz × Regionalatlas). Jede abgeleitete Zahl trägt ihre Beleg-Kette.","operationId":"betroffenheit_v1_betroffenheit_get","parameters":[{"name":"act","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"named act, e.g. BSIGesetz; omit for all","title":"Act"},"description":"named act, e.g. BSIGesetz; omit for all"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"default":20,"title":"Limit"}},{"name":"profile","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Profile"}},{"name":"key","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/legal":{"get":{"summary":"Legal","description":"Retrieve grounded legal concepts (ELI/CELEX): a § by ref, a law's §§, or a search.\nPaginated via limit/offset; indexed lookups (no linear scan).","operationId":"legal_v1_legal_get","parameters":[{"name":"ref","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"exact standard_ref, e.g. ELI:BSIGesetz§1","title":"Ref"},"description":"exact standard_ref, e.g. ELI:BSIGesetz§1"},{"name":"law","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"act name, e.g. BSIGesetz — returns its §§","title":"Law"},"description":"act name, e.g. BSIGesetz — returns its §§"},{"name":"q","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"free-text search (whole-token AND)","title":"Q"},"description":"free-text search (whole-token AND)"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":500,"minimum":1,"default":50,"title":"Limit"}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0,"title":"Offset"}},{"name":"profile","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Profile"}},{"name":"key","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/leistung":{"get":{"summary":"Leistung","description":"Retrieve Verwaltungsleistungen (XZuFi/LeiKa) with their belegbar legal basis (§).\nRechtsgrundlagen are only the ``hatRechtsgrundlage`` edges to laws NENA holds — never guessed.\nPaginated via limit/offset; indexed lookups (no linear scan).","operationId":"leistung_v1_leistung_get","parameters":[{"name":"ref","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"exact ref, e.g. XZUFI:S1000030000000041","title":"Ref"},"description":"exact ref, e.g. XZUFI:S1000030000000041"},{"name":"q","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"free-text search (whole-token AND)","title":"Q"},"description":"free-text search (whole-token AND)"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":500,"minimum":1,"default":50,"title":"Limit"}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0,"title":"Offset"}},{"name":"profile","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Profile"}},{"name":"key","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/dossier":{"post":{"summary":"Dossier","description":"Assemble a hash-chained Antrags-Dossier (EU AI Act Art. 12): each field with its source,\nthe eIDAS trust-anchor verdict for its seal, and a tamper-evident hash chain. If the antrag\nnames a `leistung` ref and omits `rechtsgrundlagen`, they are auto-filled from the graph.","operationId":"dossier_v1_dossier_post","parameters":[{"name":"profile","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Profile"}},{"name":"key","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Key"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"{leistung?, antragsteller?, rechtsgrundlagen?[], felder:[{name, wert, quelle?, siegel?{aussteller,typ}}]}","title":"Antrag"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/ask":{"get":{"summary":"Ask","description":"Belegbar GraphRAG Q&A: the answer is grounded ONLY in graph concepts the profile admits,\neach claim cited by its standard ref; if the graph is silent it says so — never guessed.","operationId":"ask_v1_ask_get","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string","minLength":3,"description":"the question, natural language","title":"Q"},"description":"the question, natural language"},{"name":"k","in":"query","required":false,"schema":{"type":"integer","maximum":20,"minimum":1,"description":"how many concepts to ground on","default":6,"title":"K"},"description":"how many concepts to ground on"},{"name":"profile","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Profile"}},{"name":"key","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/ask/stream":{"get":{"summary":"Ask Stream","description":"Streaming belegbar Q&A (Server-Sent Events): the answer arrives token-by-token, then a\nfinal ``done`` event carries citations + verdict + factscore. Same grounding + gate as /v1/ask;\nperceived latency ~instant. Meters like /v1/ask once the answer completes.","operationId":"ask_stream_v1_ask_stream_get","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string","minLength":3,"description":"the question, natural language","title":"Q"},"description":"the question, natural language"},{"name":"k","in":"query","required":false,"schema":{"type":"integer","maximum":20,"minimum":1,"default":6,"title":"K"}},{"name":"profile","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Profile"}},{"name":"key","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/ingest":{"post":{"summary":"Ingest","description":"Grow a tenant's private micro graph: embed a document/note (bge-m3) and write it as a\nconcept into the tenant's WRITABLE micro store, so it is immediately answerable via /v1/ask\nand visible in /v1/graph. Requires a tenant contract key (the macro graph stays read-only).","operationId":"ingest_v1_ingest_post","parameters":[{"name":"profile","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Profile"}},{"name":"key","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Key"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"{title|label, text|content, source?, ref?}","title":"Body"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/demo/brain/stream":{"get":{"summary":"Demo Brain Stream","description":"Public hero demo (keyless): streams the brain working on ONE domain — pages read,\nImpressum, register, profile, macro anchors, findings. Guard-railed: per-IP hourly cap +\nglobal daily budget; a domain's result is cached 24 h and replayed (no second crawl/LLM).\nNothing is persisted to any tenant.","operationId":"demo_brain_stream_v1_demo_brain_stream_get","parameters":[{"name":"domain","in":"query","required":true,"schema":{"type":"string","minLength":3,"maxLength":120,"description":"Firmen-Domain, z. B. firma.de","title":"Domain"},"description":"Firmen-Domain, z. B. firma.de"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/brain/stream":{"get":{"summary":"Brain Stream","description":"Tenant brain bootstrap, streamed; on completion the profile, pages and findings are\nwritten into the tenant's micro store (anchored to macro) and GET /v1/findings serves them.","operationId":"brain_stream_v1_brain_stream_get","parameters":[{"name":"domain","in":"query","required":true,"schema":{"type":"string","minLength":3,"maxLength":120,"title":"Domain"}},{"name":"profile","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Profile"}},{"name":"key","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/brain/bootstrap":{"post":{"summary":"Brain Bootstrap","description":"Tenant brain bootstrap (non-streaming): returns the full result incl. findings and\npersists it into the tenant's micro store.","operationId":"brain_bootstrap_v1_brain_bootstrap_post","parameters":[{"name":"profile","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Profile"}},{"name":"key","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Key"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"{domain}","title":"Body"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/findings":{"get":{"summary":"Findings","description":"The tenant's current proactive findings (from the last brain run), each with sources.","operationId":"findings_v1_findings_get","parameters":[{"name":"profile","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Profile"}},{"name":"key","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/admin/keys":{"get":{"summary":"Admin List Keys","description":"List issued (dynamic) keys — non-PII: hashed key id + profile. Admin-only.","operationId":"admin_list_keys_v1_admin_keys_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}},"post":{"summary":"Admin Issue Key","description":"Issue a contract key bound to a scope profile (e.g. after a Stripe subscription). The key\nworks on the next request (merged into the key map). Admin-only (X-Admin-Key == NENA_ADMIN_KEY).","operationId":"admin_issue_key_v1_admin_keys_post","requestBody":{"content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Body","description":"{profile}"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/admin/keys/{key_id}":{"delete":{"summary":"Admin Revoke Key","description":"Revoke an issued key by its hashed id (key:...). Admin-only.","operationId":"admin_revoke_key_v1_admin_keys__key_id__delete","parameters":[{"name":"key_id","in":"path","required":true,"schema":{"type":"string","title":"Key Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}}}