Startseite / API-Dokumentation

API-Dokumentation

Die Breadcrumbs-API ermöglicht es dir, Log-Einträge aus beliebigen Anwendungen direkt per HTTP-Request zu senden. Alle Endpunkte akzeptieren und antworten mit JSON.

Base URL | https://breadcrumbs.rutta.net/api/v1

Authentifizierung

Jede Anfrage erfordert einen Bearer-Token im Authorization-Header. Tokens werden pro System im Dashboard unter Systeme generiert.

Authorization: Bearer lv_a3f8b2c1d9e8f7a6b5c4d3e2f1a0b9c8...
Tokens sind 64 Hex-Zeichen lang. Du kannst sie im Dashboard jederzeit regenerieren — dabei wird der alte Token sofort ungültig.

Rate-Limiting

Das Limit gilt pro System-Token und beträgt 600 Anfragen pro Minute (≈ 10/s). Bei Überschreitung antwortet die API mit HTTP 429. Für höhere Volumina nutze den Batch-Endpunkt.

LimitFensterScope
600 Requests 1 Minute Pro System-Token
500 Einträge Pro Batch-Request Maximale Array-Größe

Fehler-Codes

StatusBedeutungResponse
201 Log erfolgreich gespeichert {"success":true,"id":84721}
401 Fehlender oder ungültiger Token {"error":"Missing or invalid token"}
422 Pflichtfeld fehlt oder ungültig {"error":"Message is required"}
429 Rate-Limit überschritten {"error":"Rate limit exceeded"}
500 Interner Serverfehler {"error":"Internal server error"}
POST /api/v1/logs

Sendet einen oder mehrere Log-Einträge. Akzeptiert ein einzelnes JSON-Objekt oder ein JSON-Array für Batch-Ingestion.

Request-Header
HeaderWert
Authorization Bearer <token> required
Content-Type application/json required
Body-Parameter
FeldTypBeschreibung
message string Log-Nachricht (max. 65.535 Zeichen) required
severity string Schweregrad — eines von:
debug info notice warning error critical alert emergency 		optional
default: info
source string Dienst / Komponente, z.B. auth-service optional
hostname string Hostname des sendenden Servers, z.B. web-01.prod optional
metadata object Beliebige JSON-Zusatzdaten (User-ID, Request-ID, Stack-Trace, …) optional
Antwort — 201 Created
{
  "success": true,
  "id": 84721
}

Bei Batch-Ingestion werden statt id die Felder stored (Anzahl), ids (Array aller IDs) und errors (fehlerhafte Einträge) zurückgegeben.

Schweregrade

Breadcrumbs unterstützt alle 8 Schweregrade des RFC 5424 Syslog-Standards. Wird kein Schweregrad angegeben, wird info verwendet.

debug Level 7
Detaillierte Debugging-Infos für die Entwicklung. Nicht für Produktion geeignet.
info Level 6
Normale Betriebsmeldungen. Logins, erfolgreiche Aktionen, Status-Updates. Standard.
notice Level 5
Normale, aber bemerkenswerte Ereignisse. Konfigurationsänderungen, seltene Abläufe.
warning Level 4
Aufmerksamkeit nötig, kein Fehler. Hohe Latenzen, deprecated Aufrufe, Ressourcen-Engpässe.
error Level 3
Fehlerbedingung – eine Funktion schlug fehl. Exceptions, fehlgeschlagene DB-Abfragen.
critical Level 2
Kritischer Zustand – Teilsystem ausgefallen. DB-Verbindung unterbrochen, Speicher voll.
alert Level 1
Sofortiger Handlungsbedarf. Primäre Datenbank ausgefallen, Datenverlust droht.
emergency Level 0
System nicht verwendbar. Kompletter Ausfall, katastrophaler Fehler – höchste Priorität.
Im Dashboard kannst du unter Alerts Regeln konfigurieren, die dich per E-Mail benachrichtigen, sobald bestimmte Schweregrade auftreten.

Beispiele

cURL
shell
curl -X POST https://breadcrumbs.rutta.net/api/v1/logs \ -H "Authorization: Bearer <YOUR_TOKEN>" \ -H "Content-Type: application/json" \ -d '{ "message": "User 42 logged in", "severity": "info", "source": "auth-service", "hostname": "web-01.prod", "metadata": {"user_id": 42, "ip": "1.2.3.4"} }'
PHP
php
$ch = curl_init('https://breadcrumbs.rutta.net/api/v1/logs'); curl_setopt_array($ch, [ CURLOPT_POST => true, CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => [ 'Authorization: Bearer ' . $token, 'Content-Type: application/json', ], CURLOPT_POSTFIELDS => json_encode([ 'message' => 'Payment processed', 'severity' => 'info', 'source' => 'checkout', 'hostname' => gethostname(), 'metadata' => ['order_id' => 9981, 'amount' => 49.99], ]), ]); $res = json_decode(curl_exec($ch), true); // $res['id'] => 84721
Python
python
import requests response = requests.post( "https://breadcrumbs.rutta.net/api/v1/logs", headers={ "Authorization": f"Bearer {token}", "Content-Type": "application/json", }, json={ "message": "Deployment finished", "severity": "info", "source": "deploy-pipeline", "hostname": "ci-runner-01", "metadata": {"version": "2.4.1", "env": "production"}, }, ) data = response.json() # {'success': True, 'id': 84721}
Node.js (fetch)
javascript
const res = await fetch('https://breadcrumbs.rutta.net/api/v1/logs', { method: 'POST', headers: { 'Authorization': `Bearer ${token}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ message: 'Cache miss – recomputing', severity: 'warning', source: 'cache-layer', hostname: 'api-02.prod', metadata: { key: 'product:42:details', ttl: 0 }, }), }); const data = await res.json(); // { success: true, id: 84721 }
Batch-Ingest (mehrere Logs)

Sende ein JSON-Array statt eines Objekts — bis zu 500 Einträge pro Request.

shell – Batch cURL
curl -X POST https://breadcrumbs.rutta.net/api/v1/logs \ -H "Authorization: Bearer <YOUR_TOKEN>" \ -H "Content-Type: application/json" \ -d '[ {"message": "Step 1 complete", "severity": "info", "source": "pipeline"}, {"message": "Step 2 failed", "severity": "error", "source": "pipeline", "metadata": {"exit_code": 1}}, {"message": "Retrying step 2", "severity": "warning", "source": "pipeline"} ]' # Response { "success": true, "stored": 3, "ids": [84721, 84722, 84723], "errors": [] }