TuWasGutes API — Dokumentation

Base URL: https://tuwasgutes.app

Alle Endpunkte geben JSON zurück. Sprache wählbar via lang=de oder lang=en (Default: de).

Was ist das?

Die TuWasGutes API gibt deiner App oder Plattform täglich eine kuratierte zivile Aktion — spenden, Petition unterschreiben, Brief schreiben. Ein API-Call, vollständig automatisiert, kein Redaktionsteam nötig. Inhalte stammen aus verifizierten deutschen NGOs, werden KI-angereichert mit Dringlichkeitskontext und Wirkungsaussagen, und täglich um 02:00 Uhr CET aktualisiert.

Authentifizierung

Sende deinen API-Key als HTTP-Header in jedem Request:

X-Api-Key: your-key-here

Fehlende oder ungültige Keys liefern HTTP 401. Keys werden manuell ausgestellt — siehe „API-Key anfragen" unten.

Rate Limits

Zur technischen Missbrauchsprävention gilt ein Limit von 1 Request pro Sekunde pro API-Key. Dieses Limit wird bei normalem Nutzungsverhalten niemals ausgelöst.

Bei Überschreitung: HTTP 429, Body {"error":"Rate limit exceeded. Retry after 1 second."} — nach 1 Sekunde erneut versuchen.

Endpunkte

GET /api/v1/daily-action

Gibt die algorithmisch ausgewählte Aktion des Tages zurück (cause-Objekt + action-Objekt). Für alle API-Key-Inhaber an einem Tag identisch. Aktualisierung täglich um 02:00 Uhr CET.

Response 200:

{
  "cause": {
    "id": "abc123",
    "slug": "seenotrettung-im-mittelmeer-stoppen",
    "title": "Seenotrettung im Mittelmeer stoppen",
    "summary": "Tausende Menschen riskieren ihr Leben auf der Flucht...",
    "category": "Petition",
    "organisationName": "WeAct",
    "organisationUrl": "https://weact.campact.de",
    "imageUrl": "https://assets.tuwasgutes.app/causes/abc123.jpg",
    "fundingProgressPct": 94,
    "deadline": "2026-05-31",
    "urgency_score": {
      "total": 80,
      "breakdown": {
        "deadline_proximity": 60,
        "funding_gap": 20,
        "recency": 0,
        "engagement": 0
      },
      "signals": {
        "days_until_deadline": 5,
        "progress_percentage": 94,
        "days_since_import": 18,
        "has_above_average_ctr": false
      }
    },
    "source_name": "betterplace",
    "source_url": "https://www.betterplace.org/...",
    "original_platform": "betterplace",
    "refreshed_at": "2026-05-17T02:00:00Z"
  },
  "action": {
    "type": "Petition",
    "headline": "Jetzt unterzeichnen und den Druck erhöhen",
    "whyNow": "Der Bundestag stimmt nächste Woche über neue Grenzschutzgesetze ab...",
    "whyYou": "Deine Unterschrift zählt — 132 Abgeordnete sind noch unentschlossen.",
    "impactStatement": "Mit deiner Unterschrift erhöhst du den öffentlichen Druck...",
    "isAiGenerated": true,
    "language": "de"
  }
}

GET /api/v1/causes

Paginierte Liste aller aktiven Aktionen (cause-Objekte), sortiert nach Urgency Score absteigend.

{
  "total": 142,
  "page": 1,
  "pageSize": 20,
  "items": [
    {
      /* cause object: gleiche Felder wie cause in /daily-action */
      /* inkl. urgency_score breakdown, source_name, source_url, original_platform */
      /* ohne: description, fundingGoal, fundingCurrent, leverageScore, actionsToTippingPoint */
      /* kein action-Objekt in der Liste */
    }
  ]
}

GET /api/v1/causes/{slug}

Einzelne Aktion nach Slug, inklusive vollständigem Urgency Score.

• 200 — Gleiche Struktur wie Aktionen (cause-Objekte) in /api/v1/causes
• 301 — Slug wurde umbenannt — Location-Header folgen
• 404 — Cause nicht gefunden

Urgency Score — vollständige Spezifikation

Der Urgency Score ist der Kernalgorithmus von TuWasGutes. Er bestimmt, welche Aktion als Tagesaktion ausgewählt wird, und wie Aktionen in der Gesamtliste gereiht werden. Der Score ist transparent und in jeder API-Antwort vollständig enthalten.

Score-Struktur

{
  "urgency_score": {
    "total": 80,
    "breakdown": {
      "deadline_proximity": 60,
      "funding_gap": 20,
      "recency": 0,
      "engagement": 0
    },
    "signals": {
      "days_until_deadline": 5,
      "progress_percentage": 94,
      "days_since_import": 18,
      "has_above_average_ctr": false
    }
  }
}

Scoring-Regeln

Maximal möglicher Score: 100 Punkte.

Suppressionsregeln

Beispiel-Scores

Preise

Pauschalpreis. Keine Call-Limits, kein Usage-Metering, keine Überraschungen.

Alle Preise zzgl. MwSt. Monatlich kündbar. Größere Integration geplant? Schreib uns einfach.

Attribution

Alle Integrationen müssen überall, wo eine Cause angezeigt wird, folgende Attribution sichtbar darstellen:

Quelle: TuWasGutes (tuwasgutes.app)

Das Feld source_url in jeder Antwort muss als anklickbarer Attributionslink gerendert werden.

Code-Beispiele

JavaScript

const response = await fetch(
  'https://tuwasgutes.app/api/v1/daily-action?lang=de',
  { headers: { 'X-Api-Key': 'your-key-here' } }
);
const cause = await response.json();

console.log(cause.title);
console.log(`Urgency score: ${cause.urgency_score.total}`);
console.log(`Days until deadline: ${cause.urgency_score.signals.days_until_deadline}`);

C#

using var client = new HttpClient();
client.DefaultRequestHeaders.Add("X-Api-Key", "your-key-here");

var cause = await client.GetFromJsonAsync<CauseDto>(
  "https://tuwasgutes.app/api/v1/daily-action?lang=de"
);

Console.WriteLine(cause.Title);
Console.WriteLine($"Urgency score: {cause.UrgencyScore.Total}");

Fehler-Responses