API-Dokumentation

API-Referenz

Die Schnittstelle /v1 ist die versionierte, lesende API für Kundensysteme: 35 Endpunkte, 34 GETs und ein bewusster POST mit reiner Lesesemantik. Jeder Endpunkt authentifiziert sich wie unter Authentifizierung beschrieben, antwortet mit reinem JSON und ändert nichts in Ihrem Arbeitsbereich. Dieselben Daten stehen KI-Assistenten über MCP zur Verfügung.

Diese Seite ist der Leitfaden. Die Referenz auf Feldebene ist das aktive OpenAPI-Dokument unter https://api.stonewake.ai/openapi.json: das maschinenlesbare Schema für jede Antwort, jeden Anfrageparameter und jede Fehlerform. Die /v1-Routen tragen dort das Tag v1, und die unten genannte abgelöste Parallelroute trägt dort deprecated: true.

Unten kommen zwei getrennte Kennungssysteme vor, die sich auf keiner Route vermischen: node_id ist die Kennung eines Graphknotens, die Kennung, die Treffer aus /v1/search tragen und die jede Route unter /v1/nodes/... erwartet; entity_id ist das eigene Kennungssystem des geschlossenen Gegenparteienverzeichnisses (/v1/entities).

Portfolio

  • GET /v1/portfolio: der überwachte Bestand, ein Eintrag je Engagement mit aktuellem Status, Score, wichtigsten Signalen und letzter Statusänderung. Sortiert nach Schwere, Rot zuerst. include_inactive=true nimmt deaktivierte Engagements auf.
  • GET /v1/portfolio/summary: Statuszählungen für den aktiven Bestand sowie die Zahl der Statusänderungen der letzten 30 Tage.
  • GET /v1/portfolio/transitions: der Feed der Statusänderungen, neueste zuerst. since (ein ISO-8601-Zeitstempel) begrenzt den Feed.

Risiko je Unternehmen

  • GET /v1/nodes/{node_id}/risk: die aktuelle Risikoeinschätzung Ihres Teams zu einem Unternehmen, mit den bewerteten Signalzeilen und ihren Quellenangaben. Die Antwort führt den name des Unternehmens (denselben Namen, den Zeilen aus /v1/portfolio als label liefern) und unterscheidet zwischen „nicht gehalten“, „gehalten, aber noch nicht bewertet“ und „bewertet“.

Signalzeilen tragen ein band von red, amber, green oder null. Ein band von null bedeutet, dass sich das Signal aus den zu diesem Unternehmen verfügbaren Daten nicht bewerten ließ; die Zeile wird trotzdem ausgeliefert, und ihr note sagt warum, damit Unbeobachtbares benannt und nicht verschwiegen wird. Genau die unbewerteten Zeilen halten die completeness einer Einschätzung unter 1, und evidence_completeness zählt ausschließlich Bänder, die durch tatsächliche Nachweise gedeckt sind (nie Bänder, die ein konservatives Bewertungsschema bei fehlenden Daten angenommen hat). Damit ist es der strengere der beiden Werte und derjenige, den die Untergrenze für den Status insufficient liest.

  • GET /v1/entities/{node_id}/risk: abgelöste Parallelroute der Route darüber, für bestehende Aufrufer erhalten und im OpenAPI-Schema mit deprecated: true gekennzeichnet. Neue Anbindungen verwenden /v1/nodes/{node_id}/risk.
  • GET /v1/risk-assessments/{assessment_id}: eine Einschätzung nach Kennung. Einschätzungen bilden eine ausschließlich fortgeschriebene Historie, die Kennung ist also ein dauerhafter Permalink.

Bewertungsschema

  • GET /v1/risk-profiles: die Fassungen des Bewertungsschemas Ihres Teams, neueste zuerst.
  • GET /v1/risk-profiles/{version}: eine Fassung mit ihrer vollständigen Konfiguration.
  • GET /v1/risk-config: das Bewertungsschema, nach dem die Engagements Ihres Teams derzeit bewertet werden. version ist null, solange die eingebaute Voreinstellung aktiv ist.

Gegenparteienverzeichnis

  • GET /v1/entities: das Gegenparteienverzeichnis (Exportkreditagenturen, Banken, Sponsoren), in Namensreihenfolge.
  • GET /v1/entities/{entity_id}: der Stammdatensatz einer Gegenpartei.

Suche

  • GET /v1/search?q=...: ein Unternehmen über Namen oder Kennung finden (lei:5493..., eine reine Registernummer oder einen Namen). Treffer tragen die node_id, die die Knotenrouten sprechen, dazu Jurisdiktion und Registerdaten. connected_sources benennt die Quellen, gegen die die Abfrage lief, sodass ein leeres Ergebnis zuordenbar ist. limit ist auf 25 gedeckelt.

Die Suche antwortet mit einem eigenen Umschlag, nicht mit dem Standardumschlag für Listen: { "query": ..., "hits": [...], "connected_sources": [...] }, ohne die Schlüssel limit, offset und total.

Unternehmensknoten

  • GET /v1/nodes/{node_id}: die Identität eines Unternehmensknotens: Namen, Jurisdiktion und Registerkennungen.
  • GET /v1/nodes/{node_id}/financials: die eingereichten Finanzkennzahlen des Knotens, jede Zeile mit Angabe ihres Quelleintrags.
  • GET /v1/nodes/{node_id}/events: der Feed der Registerereignisse zum Knoten, gruppiert und nach Stufe sortiert, jede Zeile mit Angabe des belegenden Eintrags, soweit einer existiert. group klappt eine Sammelzeile in ihre Einzelzeilen auf.

Finanzierung

  • GET /v1/nodes/{node_id}/financing: die Verschuldungsseite des Knotens: eingetragene Sicherheiten, notierte Schuldtitel, eingereichte Schuldpositionen und der Abdeckungsstand je Quelle, damit benannt ist, wonach nicht gesucht wurde.

Beteiligungsverhältnisse

  • GET /v1/nodes/{node_id}/ownership-chain: die Eigentümerketten des Knotens nach oben, Schritt für Schritt, jeder Schritt belegt. Personen werden nie namentlich genannt: Eine Kette, die eine Person erreicht, endet dort mit einem ausdrücklich gesperrten Endknoten.

Beobachtungen

  • GET /v1/watches: die von Ihrem Arbeitsbereich beobachteten Unternehmensknoten, neueste zuerst.

Screenings

  • GET /v1/screenings: die Adverse-Media-Screening-Läufe Ihres Arbeitsbereichs über Organisationen und Länder, neueste zuerst. Filter: entity_id, node_id, iso3, subject (der Name des geprüften Unternehmens oder Landes, abgeglichen über seine normalisierte Form) und subject_type (entity oder country).
  • GET /v1/screenings/{screening_id}: ein Screening mit seinen Einschätzungen je Kategorie, seinen Feststellungen und den belegten Pressezitaten.
  • GET /v1/deals/{deal_id}/screening-rollup: das Screening-Bild über die Beteiligten einer Transaktion hinweg.

Transaktionen

  • GET /v1/deals: das sortierte Deal Book. Filter: stage, window, country_code, region, sector, status, eca, eca_named, min_value_usd und q; sort ist eines von score, last_activity, value, first_seen, und jede Sortierung ordnet zuerst nach dem Fenster und dann nach dem gewählten Schlüssel innerhalb des Fensters. Die Zeilen, die ein Desk standardmäßig zurückhält (score_hidden gleich true: abgeschlossen, abgebrochen, eigene Bank, inländisch), erscheinen nur mit include_hidden=true.
  • GET /v1/deals/{deal_id}: eine Transaktion mit ihren Beteiligten, dem Memo und der belegten Zeitleiste. timeline_limit deckelt die Zeilen der Zeitleiste, bis 200.
  • merged_into nennt bei einer Transaktion diejenige, in die sie eingegliedert wurde, nachdem sich beide als dieselbe Transaktion erwiesen haben. Bei jeder eigenständigen Transaktion ist das Feld null; ist es gesetzt, lesen Sie die genannte Transaktion und behandeln Sie diese Zeile als Historie. Eingegliederte Zeilen behalten Zeitleiste und Ereignisse und gelten als verworfen, erscheinen also nur, wenn status verworfene Transaktionen anfordert.

Jede Zeile im Deal Book trägt, wie sie eingeordnet wurde. score_window ist das Fenster, in das sie einsortiert wurde, score_window_label das Wort, das eine Leserin sieht: Finanzierung offen, frühe Phase, nicht bestätigt, Finanzierung abgeschlossen, abgebrochen. Der Score ist eine Priorität INNERHALB dieses Fensters, nie über das ganze Buch hinweg. Beide werden zusammen gelesen: eine abgeschlossene Transaktion mit 90 und eine offene mit 60 sind keine vergleichbaren Zahlen, und die Liste stellt die abgeschlossene nie über die offene. score_band ist das Bandwort, das vor der Zahl steht, score_reason_count die Anzahl der Begründungen dahinter, und score_hidden markiert die Portfoliozeilen, die ein Desk standardmäßig zurückhält (abgeschlossen, abgebrochen, eigene Bank, inländisch). score_own_bank markiert die Zeilen, in denen die eigene Bank als Kreditgeber genannt ist, gelesen aus dem gespeicherten Abwertungssatz; das Deal Book zeigt sie als Your bank is in. Die Einzelantwort ergänzt score_reasons: das Bandwort, das Fenster, pro Bewertungskomponente einen Satz in Klartext, welcher Fakt gegriffen hat, und die angewandten Abwertungen mit Namen.

Jede Zeile trägt außerdem, was die Oberflächen aus ihren gespeicherten Fakten ableiten, damit ein Client dieselben Wörter liest, die das Dashboard, das PDF und die Arbeitsmappe zeigen. state und state_label sind der über die verknüpften Feststellungen bestätigte Stand der Transaktion und sein Wort (frühe Nachricht, geplant, Ausschreibung offen, Auftrag vergeben, Arrangeur mandatiert, Finanzierung wird arrangiert, Deckung dem Grunde nach, Deckung zugesagt, unterzeichnet oder abgeschlossen, abgebrochen, nicht bestätigt); null bedeutet, dass das Zitat keiner Quelle einen Stand bestätigt hat. event_date ist das neueste Ereignisdatum, das eine Quelle in eigenen Worten genannt hat; null bedeutet, dass keines genannt wurde und last_event_at, das Veröffentlichungsdatum, die Rückfalloption ist. lenders führt die Namen der Kreditgeber der Transaktion in Namensreihenfolge, die dritte Beteiligtengruppe, die die Spalte Who is in neben den Agenturen und den Exporteuren zeigt. angle sagt, warum die Zeile auf der Liste des Desks steht (eine Exportkreditagentur genannt, ein Exporteur genannt, ein Käufer genannt oder noch niemand), und ask, was noch zu finanzieren ist, abgeleitet aus Stand, Fenster, den genannten Agenturen und den genannten Kreditgebern (ein genannter Kreditgeber ohne Agentur und ohne bestätigten Schritt liest sich als Lenders named, cover open). Einträge der Zeitleiste tragen state, state_label, state_quote (die Passage, die den Stand bestätigt hat, gedeckelt wie jedes Zitat) und event_date, jeweils null, wo nichts bestätigt wurde.

Monitoring

  • GET /v1/monitoring/targets: die überwachten Organisationen, jede mit dem Ergebnis ihres letzten Laufs und dem nächsten Fälligkeitszeitpunkt.
  • GET /v1/monitoring/catalog: der geprüfte Monitoring-Katalog Ihres Teams.
  • GET /v1/monitoring/sources: die beobachteten Quellen, die das Monitoring speisen.

Länder und Referenzdaten

  • GET /v1/countries: der Länderindex.
  • GET /v1/countries/{iso3}: die belegten Einzelheiten zu einem Land: Indikatoren, Risikoaufschlüsselung und zugehörige Transaktionen. Jede Indikatorzeile führt die Namensnennung ihres Datensatzes mit.
  • GET /v1/reference/datasets: die Referenzdatensätze hinter den Länderdaten, mit Angaben zu Lizenz und Namensnennung. Ein Datensatz, dessen Bedingungen eine erneute Veröffentlichung nicht erlauben, wird über die gesamte Schnittstelle zurückgehalten, statt ohne Namensnennung ausgeliefert zu werden.

Geografie

  • GET /v1/geography/summary: das aktive Deal Book nach Region und Land verdichtet: Anzahl, Volumen und Risikowerte.
  • GET /v1/geography/events: der geografische Ereignis-Feed aus Referenzlisten, neueste zuerst.

Läufe und Entwicklungen

  • GET /v1/runs: die Historie der Rechercheläufe Ihres Arbeitsbereichs, neueste zuerst.
  • GET /v1/runs/{run_id}: ein Lauf mit seinen belegten Feststellungen, Quellen und Pressezitaten.
  • GET /v1/developments: der Feed der belegten Entwicklungen. sort ist recent oder score.

Quellenangaben

  • POST /v1/citations/resolve: der einzige Nicht-GET dieser Schnittstelle, mit reiner Lesesemantik: Es wird nichts angelegt, nichts geändert und nichts eingereiht. Der Body führt Kennungslisten (record_ids, event_ids, assessment_ids; je bis zu 100 Kennungen), und jede angefragte Kennung erhält entweder ihre aufgelöste Nachweiszeile oder ein ausdrückliches null. Unbekannte Kennungen und Kennungen, die diese Schnittstelle nicht ausliefern darf, sind nicht voneinander zu unterscheiden.

Paginierung

Listenendpunkte nehmen limit und offset entgegen und antworten mit einer Antwortstruktur:

json
{ "items": [], "limit": 50, "offset": 0, "total": 0 }

total ist die genaue Anzahl nach Filterung. Das Maximum für limit ist 100, außer bei /v1/search, das bei 25 Treffern deckelt und mit einem eigenen Umschlag antwortet (siehe Suche).

Fehler

Jede 4xx eines /v1-Endpunkts trägt den strukturierten Umschlag, der unter Fehler und Anfragebegrenzungen beschrieben ist, mit Ausnahme einer 422 aus der Validierung, deren Body stattdessen den beanstandeten Parameter oder das beanstandete Feld benennt. Eine 404 ist einheitlich: Sie bestätigt nie, ob eine Ressource außerhalb Ihres Arbeitsbereichs existiert.

Grundsätze

  • Lesend: Jeder Endpunkt ist ein GET, außer POST /v1/citations/resolve, dessen Semantik ein reiner Lesezugriff ist.
  • Nur Unternehmen und Länder: Personenbezogene Daten erscheinen auf dieser Schnittstelle nie, unabhängig von den Einstellungen Ihres Arbeitsbereichs. Eine Abfrage zu einer Person beantwortet dieselbe einheitliche 404 wie eine unbekannte Kennung.
  • Belegt: Antworten mit Feststellungen führen die Quellenangaben mit. Pressezitate sind auf 240 Zeichen gedeckelt, eine Passage je Quelle, stets mit Quellen-URL und Namensnennung; ein Zitat, das sich nicht zuordnen lässt, wird nicht ausgeliefert.
  • Nach Herausgeber eingestuft: Jede zitierte Quelle führt source_tier und tier_label mit. Stufe 1 ist eine Primärquelle, also die Partei der Transaktion oder die Stelle, die sie amtlich festhält; Stufe 2 ist Fachpresse; Stufe 3 ist ein Aggregator, wo auch jeder von uns nicht eingestufte Herausgeber landet. Eine Quelle, deren Text aus einem Suchindex statt von der Seite stammt, trägt text_provenance gleich snippet und zählt als ein Bericht, dessen Seite nicht geprüft ist.

Versionierung und Abkündigung

Die Version ist das Pfadpräfix: /v1 ist die aktuelle Version, und die folgenden Zusagen gelten für sie.

  • Innerhalb von v1 verläuft die Entwicklung additiv. Weitere Endpunktfamilien kommen hinzu, und Antwortfelder sowie Fehlercodes können hinzukommen; bestehende Routen, Felder und Fehlercodes werden innerhalb von v1 nie umbenannt, entfernt oder in ihrem Typ geändert. Schreiben Sie Clients so, dass sie unbekannte Felder ignorieren.
  • Eine Route, die ersetzt wird, trägt im OpenAPI-Dokument deprecated: true und bleibt vor jeder Entfernung funktionsfähig; die abgelöste Parallelroute unter Risiko je Unternehmen ist das aktive Beispiel.
  • Inkompatible Änderungen erscheinen ausschließlich unter einem neuen Versionspräfix, nie innerhalb von v1, und mit Vorlauf gegenüber betroffenen Kunden.
  • Geplante Wartungen kündigen wir vorab an, soweit möglich, und wesentliche betriebliche Änderungen teilen wir betroffenen Kunden mit.