Atla bietet eine REST-API und Webhooks für die programmatische Anbindung an deine eigenen Systeme, z. B. CI/CD-Pipelines, Lokalisierungs-Tools, internes Reporting oder Custom-Integrationen.

API-Token erstellen

1. Öffne Settings → API & Webhooks → Tokens.
2. Klick auf + New Token.
3. Vergib einen Namen (z. B. “CI/CD Bot”).
4. Wähle Scopes:
   • docs:read, Docs lesen
   • docs:write, Docs erstellen / ändern
   • translations:read, Translations lesen
   • translations:write, Jobs erstellen
   • ava:invoke, Ava-Anfragen
   • webhooks:manage, Webhooks verwalten
5. Optional: Expiry (z. B. 90 Tage).
6. Token kopieren, wird nur einmal gezeigt.

Authentifizierung

Sende den Token im Authorization-Header:

curl https://api.atla.so/v1/docs \
  -H "Authorization: Bearer YOUR_TOKEN"

Endpoints (Übersicht)

Docs

Translations

Ava

Workspace

Beispiel: Doc anlegen

curl -X POST https://api.atla.so/v1/docs \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "API Test Doc",
    "content": "# Hallo\n\nDas ist ein API-erzeugtes Doc.",
    "folder_id": "fld_abc123",
    "tags": ["api", "test"]
  }'

Response:

{
  "id": "doc_xyz789",
  "title": "API Test Doc",
  "url": "https://dev.atla.so/d/doc_xyz789",
  "created_at": "2026-05-13T10:23:00Z"
}

Beispiel: Übersetzungs-Job starten

curl -X POST https://api.atla.so/v1/translations \
  -H "Authorization: Bearer $TOKEN" \
  -F "file=@meine-datei.xliff" \
  -F "target_locales=en,es,fr" \
  -F "tone=neutral"

Beispiel: Ava-Anfrage

curl -X POST https://api.atla.so/v1/ava/chat \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.1",
    "mode": "core",
    "messages": [
      {"role": "user", "content": "Fasse das Doc doc_xyz789 zusammen."}
    ]
  }'

Webhooks

Atla kann Events an deine URL pushen, sobald etwas im Workspace passiert.

Webhook anlegen

1. Settings → API & Webhooks → Webhooks.
2. + New Webhook.
3. Target-URL angeben (HTTPS).
4. Events wählen, siehe unten.
5. Secret kopieren (für Signaturen).

Events

Payload

Beispiel doc.created:

{
  "event": "doc.created",
  "timestamp": "2026-05-13T10:23:00Z",
  "workspace": "ws_abc",
  "data": {
    "doc_id": "doc_xyz789",
    "title": "API Test Doc",
    "author": "user_123",
    "folder_id": "fld_abc123"
  }
}

Signaturen verifizieren

Atla signiert jeden Webhook mit deinem Secret:

X-Atla-Signature: sha256=<hex>

Verifiziere in deinem Endpoint:

import hmac, hashlib
 
expected = hmac.new(
    secret.encode(),
    body,
    hashlib.sha256
).hexdigest()
 
if not hmac.compare_digest(expected, sig.split('=')[1]):
    abort(401)

Retry

• 3 Retries bei HTTP ≥ 500 oder Timeout
• Exponentielles Backoff (10s, 60s, 5min)
• Nach 3 Fehlversuchen wird der Event als verworfen markiert

Rate Limits

Bei Überschreitung: HTTP 429 mit Retry-After-Header (in Sekunden).

SDK / Libraries

Atla bietet (sofern verfügbar) offizielle SDKs:

Installation z. B. via:

npm install @atla/sdk

Versionierung

Atla nutzt URL-basierte Versionierung: /v1/, /v2/. Breaking Changes erscheinen in einer neuen Version mit mindestens 6 Monaten paralleler Verfügbarkeit der alten.

Häufige Fragen

Mein Token funktioniert nicht

• Korrekt im Header? Authorization: Bearer XYZ
• Scope ausreichend für die Operation?
• Token abgelaufen?

Webhook kommt nicht an

• Target-URL erreichbar?
• HTTPS mit gültigem Zertifikat?
• Firewall blockiert Atla-IPs?
• Im Webhook-Log (Settings → Webhooks → Logs) siehst du Versuche und Antworten.

API-Doku vollständig?

Siehe https://docs.atla.so/api (sofern verfügbar) für OpenAPI-Spec.

Verwandte Seiten