Přehled REST API

Tato stránka je koncepční přehled: jak se autentizovat, jak API verzujeme, jak vypadají chyby a které zdroje existují. Autoritativním zdrojem pravdy je OpenAPI specifikace — interaktivní referenci najdete ve Swagger UI, alternativně v ReDoc.

Autentizace

Všechna datová volání vyžadují API klíč v hlavičce Authorization: Bearer. Klíče se na serveru ukládají výhradně hashované a nesou oprávnění (scopes) — například čtení a zápis šetření. Tenant se odvozuje z klíče na serveru; z těla požadavku jej nelze podvrhnout.

Klíče spravujete přes /v1/admin/api-keys: vytvoření (plný klíč se vrací pouze jednou, při vytvoření), výpis a revokaci.

curl -H "Authorization: Bearer $PROGRESUS_API_KEY" \
  https://<vase-instance>/v1/sources

# 401 bez platného klíče

{
  "type": "about:blank",
  "title": "Unauthorized",
  "status": 401,
  "detail": "missing or invalid API key"
}

Konvence

Verzování

Datové endpointy žijí pod prefixem /v1. Zpětně nekompatibilní změny znamenají novou verzi prefixu, ne tichou změnu chování. Meta endpointy (/health, /version) jsou bez prefixu.

Chyby

Každá ne-2xx odpověď je application/problem+json obálka s poli type, title, status a detail — včetně validačních chyb (422).

Idempotence

Založení šetření přijímá idempotency_key; opakované odeslání téhož požadavku nevytvoří druhý běh. Dlouhé operace běží asynchronně — API vrací stav, na výsledek se dotazujete.

Zdroje API

Přehled aktuálně vystavených endpointů. Přesná schémata požadavků a odpovědí jsou ve Swagger UI.

Metoda a cesta	Popis
GET /health · GET /version	Zdraví služby a verze nasazení; bez autentizace.
GET /health/dependencies	Souběžná, časově omezená kontrola dostupnosti PostgreSQL, Redisu a Meilisearch.
GET /metrics	Provozní metriky (čítače, histogramy) v Prometheus textovém formátu.
GET /v1/sources	Katalog dostupných zdrojů dat z registru poskytovatelů (kód, kategorie, právní základ, podporované druhy subjektů).
GET /v1/investigations	Stránkovaný seznam šetření tenantu.
POST /v1/investigations	Založí šetření (idempotentně) a zařadí jeho běh do fronty; vrací `201` se stavem `queued`.
GET /v1/investigations/{id}	Stav šetření včetně časů zahájení a dokončení.
GET /v1/investigations/{id}/events	Průběžný stav běžícího šetření jako SSE stream.
POST /v1/investigations/{id}/cancel	Ruční zrušení běžícího šetření; worker jej zohlední na nejbližším kontrolním bodě.
GET /v1/investigations/{id}/findings	Zjištění šetření (kategorie, závažnost, důvěryhodnost, odkazy na důkazy).
GET /v1/investigations/{id}/evidence	Důkazy šetření ve veřejné obálce (zdroj, čas pořízení, hash, právní základ).
GET /v1/findings/{id}	Detail jednoho zjištění.
GET /v1/search · POST /v1/search/multi	Fulltextové vyhledávání nad subjekty, důkazy a zjištěními; vícedotazová varianta v jednom volání.
GET /v1/investigations/{id}/graph/neighbors/{entity_id}	Sousedé entity v grafu šetření.
POST /v1/investigations/{id}/graph/query	Ohraničený grafový dotaz (hloubka, typy vztahů, minimální důvěryhodnost) — žádný surový Cypher.
GET /v1/investigations/{id}/graph/cycles · …/centrality · …/path	Detekce vlastnických cyklů, centralita entit a hledání cest mezi entitami.
GET /v1/reports · POST /v1/reports · GET /v1/reports/{id} · GET /v1/reports/{id}/download	Stránkovaný seznam zpráv, vygenerování zprávy ze šetření, její metadata a stažení ve formátu JSON, HTML nebo Markdown.
POST · GET /v1/admin/api-keys · POST …/revoke	Správa API klíčů: vytvoření, výpis, revokace.
/v1/osint-problems	Strukturovaná evidence OSINT problémů/zadání a jejich stavu (vytvoření, výpis, detail, aktualizace).

Plánované rozšíření API — webhooky pro notifikace o dokončení šetření — je popsané na roadmapě a v aktuální verzi neexistuje.

Kompletní průchod: od zadání ke zprávě

# 1) založení šetření

POST /v1/investigations
{
  "project_id": "6f1c9c0e-8a2b-4c3d-9e4f-5a6b7c8d9e0f",
  "subject": {
    "kind": "company",
    "identifiers": { "ico": "04543645" }
  },
  "scope": {
    "sources": ["cz-ares", "cz-isir",
                "cz-justice-or", "sanctions-eu"],
    "max_depth": 1
  },
  "idempotency_key": "dd-2026-07-27-001"
}

# 2) dotaz na stav (worker běží asynchronně)

GET /v1/investigations/b3f8d2a1-…
{
  "id": "b3f8d2a1-…",
  "project_id": "6f1c9c0e-…",
  "status": "completed",
  "created_at": "2026-07-27T09:14:03Z",
  "started_at": "2026-07-27T09:14:05Z",
  "completed_at": "2026-07-27T09:14:41Z"
}

# 3) zjištění s odkazy na důkazy

GET /v1/investigations/b3f8d2a1-…/findings
[
  {
    "id": "7b0e4f0a-…",
    "category": "insolvency",
    "severity": "high",
    "confidence": 0.85,
    "title": "Aktivní insolvenční řízení",
    "summary": "Subjekt je veden v ISIR…",
    "evidence_ids": ["0d9f2c66-…", "5a1b8e02-…"],
    "status": "confirmed"
  }
]

# 4) zpráva ke stažení

POST /v1/reports
{ "investigation_id": "b3f8d2a1-…", "format": "html" }

GET /v1/reports/{report_id}/download?format=html
→ zpráva s ledgerem důkazů a hashovým manifestem

Příklady jsou ilustrativní (identifikátory zkrácené); přesná schémata polí definuje OpenAPI reference.