Entwickler

API-Referenz

Alle API-Endpunkte erfordern eine gültige Sitzung. Senden Sie Ihr Sitzungs-Cookie mit jeder Anfrage oder verwenden Sie den API-Schlüssel Ihrer Organisation, sofern eine tokenbasierte Authentifizierung eingerichtet ist. Jede Antwort liefert { data } bei Erfolg und { error: string } bei einem Fehler.

Basis-URL: https://www.kodex-compliance.com

Öffentliche API v1

Öffentliche API v1

Die öffentliche API ist für andere Systeme gedacht: eine GRC-Plattform, ein Data Warehouse, ein Ticket-Tool. Sie authentifiziert sich mit einem API-Schlüssel statt mit einer Browser-Sitzung. Ein Organisationsinhaber erstellt Schlüssel unter Einstellungen, API-Schlüssel; der vollständige Schlüssel wird einmal angezeigt, gespeichert wird im Klartext nur sein Präfix.

Senden Sie den Schlüssel bei jeder Anfrage als Authorization: Bearer kx_…. Jeder Schlüssel trägt Berechtigungen (scans:read, scans:write, documents:read); eine Anfrage außerhalb dieser Berechtigungen erhält 403 mit der benötigten Berechtigung. Antworten sind { data, nextCursor } oder { error }. Listen sind seitenweise: geben Sie nextCursor als cursor zurück, bis er null ist. Das Limit liegt bei 600 Anfragen pro Minute und Schlüssel.

Das Starten eines Scans erfordert einen Schlüssel mit scans:write. Der Scan läuft genau wie ein aus der App gestarteter, zählt zum Plan-Kontingent der Organisation und wird im Prüfprotokoll mit dem Schlüssel als Quelle festgehalten.

POST/api/v1/scans

Startet einen Scan eines Projekts gegen ein oder mehrere Frameworks.

Query

  • projectIdDas zu scannende Projekt.
  • frameworkIds1 bis 10 Framework-IDs der Organisation.
  • deepScan(optional) true, um verbundene Repositories auf Code-Ebene zu prüfen.

Antwort

201 { data: { scanId, scanIds, batchId, scans: [{ id, frameworkType, status }], message } }

Berechtigung: scans:write. 404 für ein Projekt oder Framework außerhalb der Organisation des Schlüssels; 403, wenn das Scan-Kontingent des Plans ausgeschöpft ist; 5 Starts pro Stunde und Organisation.

GET/api/v1/scans

Scans der Organisation des Schlüssels, neueste zuerst.

Query

  • projectId(optional) Nach Projekt filtern.
  • status(optional) QUEUED, RUNNING, AWAITING_CLARIFICATION, COMPLETED, FAILED oder CANCELLED.
  • limit(optional) 1 bis 100, Standard 25.
  • cursor(optional) Der nextCursor der vorherigen Seite.

Antwort

{ data: [{ id, projectId, frameworkType, status, score, riskLevel, createdAt, startedAt, completedAt }], nextCursor }

Berechtigung: scans:read.

GET/api/v1/scans/[scanId]

Ein Scan mit seinen Kontrollergebnissen: Code, Titel, Status, Konfidenz, Lücken, Maßnahmen, Hinweis.

Antwort

{ data: { …scan, controls: [...] } }

Berechtigung: scans:read. Liefert die Zusammenfassung; Nachweisquellen, Prüfwerte und der vollständige Bericht sind für Schlüssel nicht zugänglich. 404 für einen Scan außerhalb der Organisation des Schlüssels.

GET/api/v1/documents

Dokument-Metadaten der Organisation des Schlüssels. Inhalte werden nie zurückgegeben.

Query

  • projectId(optional) Nach Projekt filtern.
  • limit(optional) 1 bis 100, Standard 25.
  • cursor(optional) Der nextCursor der vorherigen Seite.

Antwort

{ data: [{ id, projectId, title, category, fileName, mimeType, fileSize, createdAt }], nextCursor }

Berechtigung: documents:read.

Scan-API

Scan-API

POST/api/scan

Einen Compliance-Scan starten.

Body

  • frameworkId | frameworkIds[]Ein Framework oder bis zu 10 für einen Sammel-Scan.
  • projectId(optional) Den Scan auf ein bestimmtes Projekt begrenzen.
  • questionnaire(optional) Schlüssel-Wert-Antworten zum Vorbefüllen des Fragebogens.
  • githubRepo(optional) GitHub-Repository im Format owner/repo.

Antwort

{ scanId, scanIds, message }

Ratenbegrenzung pro Organisation. Planabhängige Scan-Limits werden durchgesetzt.

GET/api/scan

Abgeschlossene Scans der authentifizierten Organisation auflisten.

Query

  • projectId(optional) Nach Projekt filtern.

Antwort

Array von Scan-Zusammenfassungen, bei Multi-Framework-Scans nach batchId gruppiert. Liefert die letzten 10 Einträge.
GET/api/scan/[scanId]

Vollständige Scan-Details: Status, Bericht, Kontrollergebnisse, Shadow Pass, Nachweisquellen.

GET/api/scan/status/[scanId]

Schlanke Statusabfrage für Polling.

Antwort

{ status, progressPct, pendingClarification }
GET/api/scan/[scanId]/events

Seitenweiser Ereignis-Feed aus dem Scan-Ereignisprotokoll.

Query

  • limitAnzahl der zurückzugebenden Ereignisse.
  • offsetVersatz für die Seitenaufteilung.
GET/api/scan/[scanId]/pdf

PDF-Bericht für ein einzelnes Framework herunterladen.

GET/api/scan/batch-pdf

Zusammengefassten PDF-Bericht für einen Multi-Framework-Sammel-Scan herunterladen.

Query

  • scanIdsKommagetrennte Liste von Scan-IDs (2–20).

Ratenbegrenzung pro Benutzer.

POST/api/scan/[scanId]/cancel

Einen laufenden oder eingereihten Scan abbrechen. Bricht auch zugehörige Scans desselben Sammel-Scans ab.

POST/api/scan/[scanId]/clarify

Eine Rückfrage beantworten, während der Scan darauf wartet.

Body

  • answerAntwort als Klartext, 1–10.000 Zeichen.

Schreibt in die Datenbank und nach Redis und reiht den Worker anschließend erneut ein.

Integrations-API

Integrations-API

GET/api/integrations/status

Alle Integrationen der authentifizierten Organisation mit Verbindungsstatus und Überwachungskonfiguration auflisten.

DELETE/api/integrations/status

Eine Integration trennen. Widerruft das Anbieter-Token, entfernt Überwachungszeitpläne und löscht die verschlüsselte Konfiguration.

GET/api/integrations/monitoring

Überwachungsstatus für alle Integrationen.

PATCH/api/integrations/monitoring

Kontinuierliche Überwachung für eine Integration ein- oder ausschalten. Nur im BUSINESS-Plan.

Body

  • typeKennung des Integrationstyps.
  • enabledtrue zum Aktivieren, false zum Deaktivieren.
  • schedule(optional) DAILY | WEEKLY | MONTHLY | ON_PUSH | CUSTOM.
  • customCron(optional) Cron-Ausdruck, wenn schedule CUSTOM ist.
  • githubRepo(optional) Repository für den ON_PUSH-Zeitplan.