API

Diese Seite ist für Entwicklerinnen und Entwickler. Mit der API übersetzen Sie Texte ohne Widget, zum Beispiel auf Ihrem Server für Sprachversionen, die Suchmaschinen finden. Im Bereich API einer Website probieren Sie /translate direkt aus und verwalten die Schlüssel.

Anmeldung

Den Schlüssel geben Sie in einem dieser beiden Header mit:

X-API-Key: <schlüssel>
Authorization: Bearer <schlüssel>

Ältere Integrationen, die vom Server aus einen Widget-Token schicken, funktionieren nur, solange der Betreiber das erlaubt, und höchstens mit 1.200 Anfragen pro Minute je Token und Absender. Nutzen Sie dafür einen Server-API-Schlüssel.

Basisadresse

https://a11y.pocket-rocket.io/api/v1

POST /translate

Einen Text übersetzen.

Anfrage:

{
  "text": "Hallo Welt",
  "sourceLang": "de",
  "targetLang": "en"
}

Antwort:

{
  "translatedText": "Hello world",
  "cached": false,
  "needsReview": false
}

Mehrere Texte

Mit texts übersetzen Sie mehrere Texte in einer Anfrage. Jeder Text bekommt eine eigene id.

Anfrage:

{
  "texts": [
    { "id": "title", "text": "Willkommen" },
    { "id": "button", "text": "Mehr erfahren" }
  ],
  "targetLang": "en"
}

Antwort:

{
  "translations": {
    "title": { "translatedText": "Welcome", "cached": true, "needsReview": false },
    "button": { "translatedText": "Learn more", "cached": false, "needsReview": false }
  },
  "stats": { "total": 2, "cached": 1, "translated": 1, "failed": 0 }
}

Parameter

Kann ein Text nicht übersetzt werden, steht in translatedText das Original. needsReview markiert Übersetzungen, die jemand prüfen sollte.

POST /simplify

Einen Text in Leichte Sprache umwandeln. Leichte Sprache muss in den Features der Website aktiv sein und die KI eingerichtet.

Anfrage:

{
  "text": "Die Antragstellung erfolgt ausschließlich in elektronischer Form.",
  "lang": "de"
}

Antwort:

{
  "simplifiedText": "Sie stellen den Antrag im Internet.",
  "cached": false
}

Verbindungsschlüssel

Mit einem Verbindungsschlüssel ändern Plugins wie das WordPress-Plugin die Einstellungen einer Website und starten Audits. Sie erstellen ihn im Bereich API der Website mit einem Namen und mindestens einem Recht:

Pro Website gibt es bis zu 20 Verbindungsschlüssel. Die Liste zeigt Name, Anfang, Rechte und die letzte Nutzung.

GET /connection

Prüft den Schlüssel und nennt Website, Rechte und das Paket des Kontos.

{
  "website": { "name": "Landkreis", "domain": "https://www.beispiel.de", "allowedDomains": ["https://www.beispiel.de"] },
  "rights": ["settings", "audit"],
  "plan": {
    "name": "Nur Übersetzung",
    "mode": "translation",
    "products": { "accessibility": false, "translation": true },
    "modules": ["integrations"],
    "limits": { "pageViews": 10000, "aiRequests": null, "auditPages": null, "websites": 1, "languages": 5 },
    "trial": false,
    "endsAt": null,
    "ended": false
  }
}

Ohne zugewiesenes Paket sind alle Produkte und Module dabei und name ist null. Das WordPress-Plugin zeigt danach nur die Seiten, die das Paket enthält.

GET /settings

Liefert Funktionen, Design und Sprachen der Website. Mit ?lang=de kommen Namen und Beschreibungen auf Deutsch, sonst auf Englisch. Braucht das Recht Einstellungen.

{
  "website": { "name": "Landkreis", "domain": "https://www.beispiel.de" },
  "plan": { "name": "Komplett", "mode": "full", "products": { "accessibility": true, "translation": true }, "modules": ["ai", "audit", "integrations"], "limits": { "languages": null } },
  "aiConfigured": false,
  "features": {
    "enabled": ["fontSize", "contrast", "readPage"],
    "showSearch": true,
    "showFeatureIcons": true,
    "persistSettings": true,
    "customLayout": false,
    "categories": [
      { "id": "reading", "name": "Readability", "features": [
        { "id": "fontSize", "name": "Font size", "description": "Make text larger or smaller", "requiresAi": false }
      ] }
    ]
  },
  "design": {
    "theme": { "primaryColor": "#667eea", "secondaryColor": "#764ba2", "backgroundColor": "#ffffff", "textColor": "#0f172a", "textMuted": "#64748b", "borderColor": "#e2e8f0", "successColor": "#10b981", "errorColor": "#ef4444" },
    "sizes": { "panelWidth": 420, "toggleSize": 64, "fontSize": 14, "iconSize": 20, "spacing": 1, "borderRadius": 16 },
    "sizeLimits": { "panelWidth": { "min": 240, "max": 800, "step": 1 } },
    "position": { "x": 100, "y": 100, "margin": 2 },
    "buttonGradient": { "from": "#667eea", "to": "#764ba2" },
    "triggerMode": "built-in"
  },
  "languages": {
    "enabled": ["de", "en"],
    "available": [{ "code": "de", "name": "German", "defaultFlag": "de" }, { "code": "en", "name": "English", "defaultFlag": "gb" }],
    "flags": { "de": "de", "en": "us", "ar": "arab" },
    "flagChoices": [{ "code": "af", "name": "Afghanistan" }, { "code": "eg", "name": "Egypt" }]
  }
}

plan hat dasselbe Format wie bei GET /connection. features.enabled nennt die Funktionen, die Besucher sehen. customLayout ist true, wenn die Website im Dashboard eigene Abschnitte hat. sizeLimits nennt die Grenzen jeder Größe. languages.flags nennt für jede Sprache die Flagge, die das Widget zeigt (leer: keine Flagge), flagChoices alle wählbaren Flaggen mit Namen, nach Namen sortiert. Die Flaggen selbst liefert /api/widget/flags/<code>.svg.

PATCH /settings

Ändert die mitgeschickten Teile, alles andere bleibt. Die Antwort hat das Format von GET. Braucht das Recht Einstellungen.

{
  "features": { "enabled": ["fontSize", "contrast", "readPage"], "showSearch": false },
  "design": { "triggerMode": "custom", "theme": { "primaryColor": "#1d4ed8" }, "position": { "x": 0, "y": 100 } },
  "languages": { "enabled": ["de", "en", "tr"], "flags": { "en": "us", "ar": "", "fa": null } }
}

Ohne das Produkt Barrierefreiheit lehnt die API features mit 403 ab, ohne das Produkt Übersetzung languages; design geht mit jedem Paket. Verstößt ein Feld gegen eine Regel, antwortet die API mit 400 und einer Meldung wie design.sizes.panelWidth must be between 240 and 800 und ändert nichts. Gespeicherte Änderungen sehen Besucher auf der nächsten Seite, die sie öffnen.

GET /audit

Liefert die letzten 20 Audits der Website, den neuesten zuerst. Braucht das Recht Audit, wie alle Aufrufe unter /audit.

{
  "website": { "name": "Landkreis", "domain": "https://www.beispiel.de" },
  "browserConfigured": true,
  "pageLimit": 50,
  "maxPageLimit": 500,
  "runs": [
    { "id": "cmvj7sqnc0000pa7df9byt2lm", "status": "COMPLETED", "trigger": "MANUAL", "startUrl": null, "pageLimit": 10, "pagesDiscovered": 5, "pagesCompleted": 4, "pagesFailed": 1, "score": 89, "elements": 9, "errorMessage": null, "createdAt": "2026-10-22T07:23:38.088Z", "startedAt": "2026-10-22T07:23:38.094Z", "completedAt": "2026-10-22T07:23:43.100Z" }
  ]
}

status ist PENDING, RUNNING, COMPLETED, FAILED oder CANCELLED. pageLimit ist das Seitenlimit aus dem Zeitplan der Website, maxPageLimit die Obergrenze des Servers. browserConfigured ist false, wenn der Server keinen Browser-Dienst hat und keine Audits ausführen kann.

POST /audit

Startet einen Audit. Beide Felder sind optional; ohne pageLimit gilt das Seitenlimit der Website, ohne startUrl beginnt der Audit bei Sitemap und Startseite. Die Antwort (201) hat das Format eines Eintrags aus runs.

{ "pageLimit": 20, "startUrl": "https://www.beispiel.de/service/" }

GET /audit/{id}

Liefert das Ergebnis eines Audits: den Eintrag wie in runs, die Zahl der Regeln je Schweregrad, den Vergleich mit dem vorherigen abgeschlossenen Audit, die Probleme je Regel mit den betroffenen Seiten und die Seiten mit ihrer Punktzahl. Die Texte der Regeln sind Deutsch.

{
  "run": { "id": "cmvj7sqnc0000pa7df9byt2lm", "status": "COMPLETED", "score": 89 },
  "rulesByImpact": { "critical": 2, "serious": 3, "moderate": 0, "minor": 0 },
  "comparison": null,
  "rules": [
    { "ruleId": "image-alt", "impact": "critical", "help": "Abbildungen müssen einen Alternativtext besitzen.", "description": "Stellt sicher, dass <img>-Elemente einen Alternativtext oder eine ARIA-Rolle mit dem Wert none oder presentation besitzen.", "helpUrl": "https://dequeuniversity.com/rules/axe/4.11/image-alt?application=axeAPI", "criteria": [{ "id": "1.1.1", "level": "A", "title": "Nicht-Text-Inhalt" }], "pages": 2, "elements": 4, "occurrences": [{ "url": "https://www.beispiel.de/", "elements": 1 }, { "url": "https://www.beispiel.de/galerie", "elements": 3 }] }
  ],
  "pages": [
    { "url": "https://www.beispiel.de/kontakt", "status": "COMPLETED", "httpStatus": 200, "score": 100, "issues": 0, "elements": 0, "errorMessage": null }
  ]
}

comparison ist beim ersten Audit null, sonst { "score", "completedAt", "newIssues", "fixedIssues" } des vorherigen Audits. Gehört der Audit nicht zur Website des Schlüssels, antwortet die API mit 404.

POST /audit/{id}/cancel

Bricht einen wartenden oder laufenden Audit ab und liefert ihn mit dem Status CANCELLED. Ist er schon beendet, antwortet die API mit 409.

POST /audit/{id}/report-link

Erstellt einen Link zum druckfertigen Bericht eines abgeschlossenen Audits, der ohne Anmeldung eine Stunde lang funktioniert.

{ "path": "/shared-report#r1.eyJ3Ijoid19hdWRpdCIs…", "expiresAt": "2026-10-22T08:23:43.306Z" }

path gehört hinter die Adresse des Servers. Der Teil hinter # ist der Schlüssel: Browser schicken ihn nicht an den Server, er erscheint also in keinem Server-Log. Die Seite liest ihn und lädt damit den Bericht. Der Bericht nutzt die Berichtsangaben des Inhabers des Kontos, zu dem die Website gehört (bei mehreren Inhabern des ersten). Ist der Audit nicht abgeschlossen, antwortet die API mit 409.

Limits

Die Grenzen kann der Betreiber anpassen; die Namen der Einstellungen stehen in der README.

Über einem Limit antwortet die API mit 429 und nennt im Header Retry-After, nach wie vielen Sekunden es wieder geht.

Hinweise

• Ergebnisse landen im Übersetzungsspeicher der Website und lassen sich unter Übersetzungen bearbeiten. Bekannte Texte kommen direkt aus dem Speicher (cached: true).
• Fehler kommen als JSON mit error und dem passenden HTTP-Status, zum Beispiel 401 ohne gültigen Schlüssel, 413 bei zu großen Anfragen und 429 bei zu vielen Anfragen.
• Ist das Konto von Pocket Rocket gesperrt, antworten alle Endpunkte mit 403 und "code": "suspended".
• Fehlt im Paket des Kontos ein Modul oder Produkt, antwortet die API mit 403 und "code": "plan": Server-API-Schlüssel und Verbindungsschlüssel brauchen Integrationen, /simplify und Leichte Sprache brauchen KI, Audits brauchen Audit, /translate in eine andere Sprache braucht das Produkt Übersetzung. Erlaubt das Paket weniger Sprachen, als eingeschaltet sind, übersetzt /translate nur in die Sprachen, die auch das Widget zeigt, und antwortet sonst mit 403 und "code": "plan"; Deutsch zählt dabei nicht mit und bleibt immer möglich. PATCH /settings lehnt zusätzliche Sprachen über der Grenze ab.