Workflow API-Referenz

POST /api/v1/workflow/start

Initialisiert einen neuen Workflow und sendet einen OTP-Code an die angegebene Email.

Auth: Keine (MVP). x402-Pricing in Phase C. Rate-Limit: 5/Stunde pro IP

Request

{
  "user_email": "matthias@example.com",
  "agent_id": "claude-sonnet-4-5",
  "briefing_hash": "abc123...",
  "briefing_metadata": {
    "title": "Marketing-Kampagne Q3",
    "expected_output_count": 50
  },
  "tier": "standard"
}

Response 201

{
  "workflow_id": "uuid",
  "workflow_token": "opaque-bearer-token",
  "otp_sent_to": "matthias@example.com",
  "expires_at": "2026-05-20T14:30:00Z",
  "status": "pending"
}

Workflow-Token sicher aufbewahren

Das workflow_token ist der einzige Zugang zu /stamp und /complete. Es wird nur einmal zurückgegeben.

GET /api/v1/workflow/{id}/verify-user?challenge=...

OTP-Verifizierung. User klickt den Link aus der Email.

Auth: Keine (Token im Query-Parameter)

Erfolg: Workflow-Status wechselt zu active, HTML-Bestätigung
Fehler: 410 Gone (abgelaufen, bereits verwendet, zu viele Versuche)

POST /api/v1/workflow/{id}/stamp

Stempelt einen einzelnen Output innerhalb des Workflows.

Auth: Authorization: Workflow <token> Rate-Limit: 100/Minute pro Workflow

Request

{
  "output_hash": "abc123...",
  "output_type": "image",
  "output_metadata": {
    "filename": "campaign-hero.png",
    "dimensions": "1920x1080",
    "model": "FLUX.1 Pro"
  }
}

Response 201

{
  "output_id": "uuid",
  "sequence_number": 1,
  "stamp_token_id": "uuid",
  "verify_url": "https://siegel.kavra.cloud/workflow/{id}#output-1",
  "workflow_anchor_url": "https://siegel.kavra.cloud/workflow/{id}"
}

POST /api/v1/workflow/{id}/complete

Finalisiert den Workflow. Berechnet Merkle-Wurzel aller Output-Hashes.

Auth: Authorization: Workflow <token>

Response 200

{
  "workflow_id": "uuid",
  "status": "completed",
  "output_count": 47,
  "verify_url": "https://siegel.kavra.cloud/workflow/{id}",
  "completed_at": "2026-05-19T16:00:00Z"
}

GET /workflow/{id}

Öffentliche Verify-Page. Zeigt Workflow-Details, Output-Liste und Trust-Anker.

Auth: Keine Format: HTML

POST /api/v1/workflow/{id}/redact-pii

DSGVO Art. 17: Email-Bindung anonymisieren.

Auth: Authorization: Workflow <token>

Setzt user_email auf [REDACTED]. Hash-Anker und Output-Kette bleiben erhalten.