Entwickler

Die INTAYO-API verbindet dein Konto mit Automatisierungswerkzeugen wie n8n und Zapier, mit eigenen Bots und mit KI-Assistenten über MCP.

Zugang

Jeder Aufruf trägt einen Token im Kopf Authorization. Einen eigenen Token legst du in den Einstellungen an — dafür ist ein Club-Zugang nötig. Firmen erhalten Tokens für eine ganze Gruppe über den Support.

Authorization: Bearer ity_…

Ein Token gilt entweder für ein Konto oder für eine Gruppe. Ein Gruppen-Token nennt bei jedem Aufruf das handelnde Mitglied über user_email und lehnt Nichtmitglieder ab.

Berechtigungen

profile:readProfil und Bilanz lesen
challenges:readChallenges lesen
challenges:writeChallenges anlegen und beantworten
events:readEreignisverlauf lesen
group:readGruppe und Mitglieder lesen
group:manageMitglieder verwalten
webhooks:manageWebhooks einrichten
questions:readTagesfrage lesen
questions:voteBei der Tagesfrage tippen

Erste Challenge anlegen

curl -X POST https://intayo.app/api/v1/challenges \
  -H "Authorization: Bearer ity_…" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: mein-lauf-001" \
  -d '{
    "claim": "Ich laufe den Halbmarathon unter zwei Stunden",
    "opponent_email": "[email protected]",
    "stake": "coffee",
    "due_days": 30
  }'

Der Kopf Idempotency-Key sorgt dafür, dass eine Wiederholung nach einem Netzwerkfehler keine zweite Challenge anlegt.

Endpunkte

Methode	Pfad	Berechtigung
GET	/v1/me	profile:read
GET	/v1/challenges	challenges:read
POST	/v1/challenges	challenges:write
GET	/v1/challenges/{id}	challenges:read
POST	/v1/challenges/{id}/accept	challenges:write
POST	/v1/challenges/{id}/resolve	challenges:write
POST	/v1/challenges/{id}/cancel	challenges:write
GET	/v1/events	events:read
GET	/v1/groups	group:read
GET	/v1/groups/{id}/members	group:read
POST	/v1/groups/{id}/members	group:manage
GET	/v1/groups/{id}/challenges	group:read
GET	/v1/groups/{id}/stats	group:read
GET	/v1/webhooks	webhooks:manage
POST	/v1/webhooks	webhooks:manage
POST	/v1/webhooks/{id}/test	webhooks:manage
GET	/v1/questions/daily	questions:read
POST	/v1/questions/daily	questions:vote

Listen liefern next_cursor — diesen Wert beim nächsten Aufruf als cursor übergeben. limit geht bis 100.

Webhooks

Statt im Takt abzufragen, lässt du dich benachrichtigen. Jede Zustellung trägt eine Signatur im Kopf X-ITY-Signature. Prüfe sie, bevor du den Inhalt verwendest — sonst kann jeder deinem Endpunkt etwas unterschieben.

import { createHmac, timingSafeEqual } from 'crypto';

export function verify(secret, header, rawBody) {
  const parts = Object.fromEntries(
    header.split(',').map((p) => p.trim().split('='))
  );
  const alter = Math.abs(Date.now() / 1000 - Number(parts.t));
  if (!(alter < 300)) return false;

  const erwartet = createHmac('sha256', secret)
    .update(`${parts.t}.${rawBody}`)
    .digest('hex');

  return parts.v1.length === erwartet.length &&
    timingSafeEqual(Buffer.from(parts.v1), Buffer.from(erwartet));
}

Fehlgeschlagene Zustellungen werden fünfmal mit wachsendem Abstand wiederholt, danach wird das Abo abgeschaltet.

Grenzen und Fehler

120 lesende und 30 schreibende Aufrufe je Minute und Token. Die Kopfzeilen X-RateLimit-Remaining und X-Quota-Remaining sagen dir jederzeit, wie viel bleibt.

invalid_token	401
insufficient_scope	403
plan_required	402
quota_exceeded	429
rate_limited	429
not_found	404
invalid_request	400
invalid_state	409
conflict	409
forbidden	403
internal_error	500

Jede Antwort trägt eine request_id, auch im Kopf X-Request-Id. Bei Rückfragen an den Support bitte angeben.

Rücksicht auf die Gegenseite

Eine Challenge hat immer zwei Beteiligte. Deshalb gibt die API von der jeweils anderen Person nur den Vornamen heraus — nie Nachname, nie E-Mail-Adresse. Wenn du Daten in andere Dienste überträgst, überträgst du auch Daten einer Person, die davon nichts weiß. Geh sparsam damit um.

Token in den Einstellungen anlegen INTAYO per Siri