Endpunkt-Referenz

Diese Referenz bündelt die öffentlichen Gateway-Endpunkte aus dem Agent-Erstpfad. Sie ist absichtlich knapp: Capability-spezifische params, result-Objekte, Scopes, Risiken und Kosten liest du immer über describe.

Basis-URL:

https://connect.webrichtung.de

Bei Mutationen ist eine Idempotency-Key Pflicht. Format und Retry-Verhalten stehen auf der Seite Idempotency-Pflicht.

Discovery

Endpoint	Auth	Antwort
`GET /health`	nein	JSON mit `status`, `service`, `domain`, `timestamp`
`GET /llms.txt`	nein	`text/plain` mit maschinenlesbarem Einstieg
`GET /mcp/manifest`	nein	JSON-Manifest mit Meta-Tools, Ressourcen und relativen Transport-Endpunkten
`GET /capabilities`	nein	JSON-Katalog mit Meta-Tools und öffentlichen Capabilities
`GET /openapi.json`	nein	OpenAPI-Dokument, soweit öffentlich bereitgestellt

POST /register

Legt eine Agent App an und gibt einen Bootstrap-Key zurück.

POST https://connect.webrichtung.de/register
Content-Type: application/json
Idempotency-Key: idem-register-20260704-0001

{
  "owner_email": "owner@example.com",
  "agent_email": "agent@example.com",
  "app": {
    "slug": "acme-ops-agent",
    "name": "Acme Ops Agent",
    "description": "Operativer Agent für die Musterorganisation.",
    "contact_email": "ops@example.com",
    "homepage_url": "https://example.com/agent"
  }
}

Antwort 201:

{
  "app": {
    "id": "app_123",
    "slug": "acme-ops-agent",
    "name": "Acme Ops Agent",
    "verification_status": "unverified"
  },
  "agent_email": "agent@example.com",
  "bootstrap_key": {
    "token": "<bootstrap-api-key>",
    "expires_at": "2026-07-05T12:00:00.000Z",
    "scopes": ["platform:bootstrap"]
  }
}

Feld	Regel
`owner_email`	Pflicht. Gültige E-Mail-Adresse des verantwortlichen Menschen. Dieselbe Adresse muss in `/organizations` wiederholt werden.
`agent_email`	Optional. Wenn gesetzt, muss diese Mailbox später per Agent-Mail-OTP bestätigt werden.
`app.slug`	Pflicht. Technischer Kurzname mit Kleinbuchstaben, Zahlen und `-`, 3 bis 63 Zeichen.
`app.name`	Pflicht. Menschlich lesbarer Name der Agent App, 2 bis 120 Zeichen.
`app.description`	Optional. Kurze Beschreibung der Agent App.
`app.contact_email`	Optional. Kontaktadresse des Agent-Betreibers.
`app.homepage_url`	Optional. Öffentliche Website der Agent App oder des Betreibers.
`bootstrap_key.token`	Kurzlebiger Key für `/organizations` und Katalogmaterial. Nicht als Arbeits-Key verwenden.

POST /organizations

Erstellt die Owner-Organisation, die Agent Installation und den ersten Installation-Key.

POST https://connect.webrichtung.de/organizations
Content-Type: application/json
Authorization: Bearer <bootstrap-api-key>
Idempotency-Key: idem-bootstrap-20260704-0001

{
  "owner_email": "owner@example.com",
  "agent_email": "agent@example.com",
  "organization": {
    "name": "Musterfirma GmbH"
  }
}

Antwort 201:

{
  "organization": {
    "id": "org_123",
    "name": "Musterfirma GmbH"
  },
  "installation": {
    "id": "inst_123",
    "agent_email": "agent@example.com",
    "agent_email_verified_at": null,
    "agent_email_verification_status": "pending",
    "owner_email": "owner@example.com",
    "owner_user_id": "user_123",
    "owner_verified_at": null,
    "operator_approval_status": "pending",
    "scopes": ["org:manage", "platform.catalog:read"]
  },
  "installation_key": {
    "token": "<installation-api-key>",
    "expires_at": "2026-10-02T12:00:00.000Z",
    "scopes": ["org:manage", "platform.catalog:read"]
  },
  "owner_otp_delivery": {
    "status": "queued",
    "expires_at": "2026-07-07T12:00:00.000Z"
  },
  "agent_otp_delivery": {
    "status": "queued",
    "expires_at": "2026-07-07T12:00:00.000Z",
    "correlation_id": "otpref_123",
    "extraction": {
      "mailbox": "agent_email",
      "imap_search": {
        "header": "Subject",
        "contains": "Ref: otpref_123"
      },
      "subject_contains": "Ref: otpref_123",
      "code_line_prefix": "Code: ",
      "code_regex": "^Code:\\s*(?<otp>\\S+)\\s*$",
      "verify_endpoint": "/agent-otp/verify"
    }
  }
}

Feld	Regel
`Authorization`	Pflicht. Verwende den Bootstrap-Key aus `/register`.
`owner_email`	Pflicht. Muss exakt zur Owner-E-Mail aus `/register` passen.
`agent_email`	Optional. Muss zur registrierten `agent_email` passen, wenn dort gesetzt.
`organization.name`	Pflicht. Anzeigename der neuen Organisation, 3 bis 160 Zeichen.
`installation.id`	Stabile Installations-ID für Diagnose und Handover. Nicht der API-Key.
`installation.agent_email_verification_status`	`not_required`, wenn keine `agent_email` gesetzt ist; sonst `pending`, bis `/agent-otp/verify` erfolgreich war.
`installation.operator_approval_status`	`pending`, `approved` oder `blocked`. Operative Arbeit startet erst bei `approved`.
`installation_key.token`	Klartext-Key für den weiteren Erstpfad. Er wird nur in dieser Antwort angezeigt.
`owner_otp_delivery.status`	`queued`, `sent` oder `suppressed`. Bei `suppressed` stoppen und klären.
`agent_otp_delivery.correlation_id`	Öffentliche Suchreferenz für die Agent-Mail, im Betreff als `Ref: <ID>`.
`agent_otp_delivery.extraction.code_regex`	Regex für die eigenständige Body-Zeile mit dem Code.

POST /owner-otp/claim

Reicht den Owner-Code ein und dokumentiert die Verantwortungsübernahme.

POST https://connect.webrichtung.de/owner-otp/claim
Content-Type: application/json
Authorization: Bearer <installation-api-key>
Idempotency-Key: idem-owner-claim-20260704-0001

{
  "otp": "<owner-otp>"
}

Antwort 200:

{
  "installation": {
    "id": "inst_123",
    "agent_email": "agent@example.com",
    "agent_email_verified_at": null,
    "agent_email_verification_status": "pending",
    "owner_email": "owner@example.com",
    "owner_user_id": "user_123",
    "owner_verified_at": "2026-07-04T12:10:00.000Z",
    "operator_approval_status": "pending",
    "scopes": ["billing.wallet:read", "core:read", "core:write", "documents:read", "documents:write", "org:manage", "platform.catalog:read"]
  }
}

Feld	Regel
`Authorization`	Pflicht. Verwende den Installation-Key aus `/organizations`.
`otp`	Pflicht. Kopiere den per E-Mail erzeugten Owner-Code exakt und ohne Log-Ausgabe.
`installation.owner_verified_at`	Bedeutet: Owner-Legitimation ist dokumentiert. Operative Arbeit kann trotzdem noch gesperrt sein.

POST /owner-otp/resend

Fordert einen frischen Owner-Code an.

POST https://connect.webrichtung.de/owner-otp/resend
Content-Type: application/json
Authorization: Bearer <installation-api-key>
Idempotency-Key: idem-owner-resend-20260704-0001

{}

Antwort 200:

{
  "installation": {
    "id": "inst_123",
    "agent_email": "agent@example.com",
    "agent_email_verified_at": null,
    "agent_email_verification_status": "pending",
    "owner_email": "owner@example.com",
    "owner_verified_at": null,
    "operator_approval_status": "pending",
    "scopes": ["org:manage", "platform.catalog:read"]
  },
  "owner_otp_delivery": {
    "status": "queued",
    "expires_at": "2026-07-07T12:30:00.000Z"
  }
}

Feld	Regel
`owner_otp_delivery.status`	`queued`, `sent` oder `suppressed`; bei `suppressed` stoppen und klären.
`owner_otp_delivery.expires_at`	Ablaufzeitpunkt des frischen Owner-Code. Der vorherige Code ist danach nicht mehr maßgeblich.

POST /agent-otp/verify

Bestätigt die optionale Agent-Mailbox.

POST https://connect.webrichtung.de/agent-otp/verify
Content-Type: application/json
Authorization: Bearer <installation-api-key>
Idempotency-Key: idem-agent-verify-20260704-0001

{
  "otp": "<agent-mail-otp>"
}

Antwort 200:

{
  "installation": {
    "id": "inst_123",
    "agent_email": "agent@example.com",
    "agent_email_verified_at": "2026-07-04T12:12:00.000Z",
    "agent_email_verification_status": "verified",
    "owner_email": "owner@example.com",
    "owner_verified_at": "2026-07-04T12:10:00.000Z",
    "operator_approval_status": "pending",
    "scopes": ["billing.wallet:read", "core:read", "core:write", "documents:read", "documents:write", "org:manage", "platform.catalog:read"]
  }
}

Feld	Regel
`otp`	Pflicht. Kopiere den Agent-Mail-Code exakt und ohne Log-Ausgabe.
`installation.agent_email_verified_at`	Bedeutet: Die optionale Agent-Mail-Identität ist verifiziert.
`installation.operator_approval_status`	`pending` stoppt operative Arbeit. Erst `approved` erlaubt den nächsten Schritt.

POST /agent-otp/resend

Fordert einen frischen Agent-Mail-Code an.

POST https://connect.webrichtung.de/agent-otp/resend
Content-Type: application/json
Authorization: Bearer <installation-api-key>
Idempotency-Key: idem-agent-resend-20260704-0001

{}

Antwort 200:

{
  "installation": {
    "id": "inst_123",
    "agent_email": "agent@example.com",
    "agent_email_verified_at": null,
    "agent_email_verification_status": "pending",
    "owner_email": "owner@example.com",
    "owner_verified_at": "2026-07-04T12:10:00.000Z",
    "operator_approval_status": "pending",
    "scopes": ["billing.wallet:read", "core:read", "core:write", "documents:read", "documents:write", "org:manage", "platform.catalog:read"]
  },
  "agent_otp_delivery": {
    "status": "queued",
    "expires_at": "2026-07-07T12:30:00.000Z",
    "correlation_id": "otpref_456",
    "extraction": {
      "mailbox": "agent_email",
      "imap_search": {
        "header": "Subject",
        "contains": "Ref: otpref_456"
      },
      "subject_contains": "Ref: otpref_456",
      "code_line_prefix": "Code: ",
      "code_regex": "^Code:\\s*(?<otp>\\S+)\\s*$",
      "verify_endpoint": "/agent-otp/verify"
    }
  }
}

Feld	Regel
`agent_otp_delivery.correlation_id`	Neue Suchreferenz für die neu zugestellte Agent-Mail.
`agent_otp_delivery.extraction.code_regex`	Regex für die Body-Zeile mit dem Code.

GET /org/current

Liest nach allen erforderlichen OTPs den Organisations- und Freischaltungsstatus. Vor Owner-Claim, oder bei gesetzter agent_email vor Agent-Mail-Verifikation, ist HTTP 412 precondition_failed erwartetes Verhalten; Details stehen in der Fehlertaxonomie.

GET https://connect.webrichtung.de/org/current
Authorization: Bearer <installation-api-key>

Antwort 200:

{
  "organization": {
    "id": "org_123",
    "name": "Musterfirma GmbH",
    "short_id": "abc123",
    "is_active": true,
    "created_at": "2026-07-04T12:00:00.000Z",
    "updated_at": "2026-07-04T12:10:00.000Z"
  },
  "installation": {
    "id": "inst_123",
    "agent_email": "agent@example.com",
    "agent_email_verified_at": "2026-07-04T12:12:00.000Z",
    "agent_email_verification_status": "verified",
    "owner_verified_at": "2026-07-04T12:10:00.000Z",
    "operator_approval_status": "approved",
    "operator_approved_at": "2026-07-04T12:15:00.000Z",
    "scopes": ["billing.wallet:read", "core:read", "core:write", "documents:read", "documents:write", "org:manage", "platform.catalog:read"]
  },
  "principal": {
    "sb_user_id": "principal_123",
    "installation_id": "inst_123",
    "scopes": ["billing.wallet:read", "core:read", "core:write", "documents:read", "documents:write", "org:manage", "platform.catalog:read"]
  }
}

Feld	Bedeutung
`organization.id`	Stabile ID der Owner-Organisation für Handover und Diagnose.
`organization.short_id`	Kurzer Organisationscode für menschliche Bezugnahme.
`organization.is_active`	`false` bedeutet: nicht weiterarbeiten, an den Betreiber übergeben.
`installation.agent_email_verification_status`	`not_required` oder `verified` muss erreicht sein, bevor operative Arbeit beginnt.
`installation.operator_approval_status`	`pending` = warten oder Handover, `approved` = Arbeit erlaubt, `blocked` = stoppen.
`principal.sb_user_id`	Technische Principal-ID des Agents. Nicht als Owner-ID interpretieren.
`principal.scopes`	Scopes des aktuell verwendeten Installation-Key.

MCP-Meta-Tools

Alle Meta-Tools liegen unter /mcp/* und verwenden den Installation-Key, sobald der Erstpfad bootstrapped ist.

POST /mcp/search_capabilities

POST https://connect.webrichtung.de/mcp/search_capabilities
Content-Type: application/json
Authorization: Bearer <installation-api-key>

{
  "query": "organization context",
  "domain": "core",
  "risk_level_max": "medium",
  "limit": 5
}

Antwort:

{
  "interface_version": "1.0",
  "results": [
    {
      "id": "core.org.current.get",
      "version": "1.0.0",
      "summary": "Aktuellen Organisationskontext lesen.",
      "domain": "core",
      "risk_level": "low",
      "access": "allowed"
    }
  ],
  "total": 1,
  "next_cursor": null
}

Feld	Regel
`query`, `domain`, `risk_level_max`, `limit`, `cursor`	Optional. `limit` maximal 50.
`results[].access`	`allowed`, `scope_missing` oder `approval_always`. Bei `scope_missing` nicht raten, sondern `describe` lesen.

POST /mcp/describe

POST https://connect.webrichtung.de/mcp/describe
Content-Type: application/json
Authorization: Bearer <installation-api-key>

{
  "id": "core.org.current.get"
}

Antwort: Der vollständige Runtime-Contract der Capability. Für params und result sind input_schema und output_schema verbindlich.

POST /mcp/dry_run

Operative dry_run-Aufrufe brauchen eine legitimierte und freigeschaltete Installation. Vor erforderlichen OTPs oder vor Operator-Approval antwortet der Handler mit HTTP 412 precondition_failed.

POST https://connect.webrichtung.de/mcp/dry_run
Content-Type: application/json
Authorization: Bearer <installation-api-key>

{
  "id": "core.org.current.get",
  "params": {}
}

Antwortform und Kostensemantik stehen auf dry_run & Kosten-Preflight.

POST /mcp/invoke

/mcp/invoke nutzt dieselbe Guard-Kette wie dry_run: Installation-Key, erforderliche OTPs, Operator-Approval, Scopes, Schema, Policy, Audit, Billing und Egress. Vor erforderlichen OTPs oder vor Operator-Approval ist HTTP 412 precondition_failed erwartetes Verhalten.

POST https://connect.webrichtung.de/mcp/invoke
Content-Type: application/json
Authorization: Bearer <installation-api-key>

{
  "id": "core.org.current.get",
  "params": {}
}

Bei mutierenden Capabilities enthält der Body zusätzlich idempotency_key. Das genaue result-Objekt kommt aus dem describe-Contract der Capability.

Erfolgreiche Invokes verwenden diese Hülle:

{
  "interface_version": "1.0",
  "status": "succeeded",
  "capability_id": "documents.document.upload",
  "resolved_version": "1.0.0",
  "audit_id": "audit_123",
  "result": {
    "...": "capability-specific output"
  },
  "cost": {
    "...": "nur vorhanden, wenn gebucht oder vom Handler gemeldet"
  }
}

Pflichtfelder sind interface_version, status, capability_id, resolved_version und audit_id. result, approval, poll, cost, replayed und warnings sind abhängig von Capability und Ausführungszustand.

estimated_cost gehört zur dry_run-Antwort. Ein erfolgreicher invoke verwendet stattdessen optional cost, wenn der Gateway gebucht hat oder der Handler Kosten meldet.

Bei wallet.agent_budget.guard.check liegt die Entscheidung daher unter result.allowed, nicht top-level:

{
  "interface_version": "1.0",
  "status": "succeeded",
  "capability_id": "wallet.agent_budget.guard.check",
  "resolved_version": "1.0.0",
  "audit_id": "audit_123",
  "result": {
    "allowed": true,
    "organization_id": "org_123",
    "wallet_balance_credits": "100.00",
    "estimated_cost_credits": 0.09,
    "policy": {
      "policy_profile_id": "policy_123",
      "task_cap_credits": 0,
      "daily_cap_credits": 10,
      "monthly_cap_credits": 100,
      "burn_rate_hourly_cap_credits": 0,
      "kill_switch_enabled": false
    },
    "ledger": {
      "hour_cost_credits": 0.2,
      "today_cost_credits": 0.5,
      "month_cost_credits": 2
    }
  }
}

POST /keys/rotate

Rotiere den Installation-Key erst nach dem Erstpfad. Vor erforderlichen OTPs antwortet der Endpoint mit HTTP 412 precondition_failed. Der neue Klartext-Key erscheint nur einmal.

POST https://connect.webrichtung.de/keys/rotate
Content-Type: application/json
Authorization: Bearer <installation-api-key>
Idempotency-Key: idem-key-rotate-20260704-0001

{}

Antwort 201:

{
  "key": {
    "token": "<rotated-installation-api-key>",
    "expires_at": "2026-10-02T12:15:00.000Z",
    "scopes": ["billing.wallet:read", "core:read", "core:write", "documents:read", "documents:write", "org:manage", "platform.catalog:read"],
    "rotated_from_key_id": "key_123"
  }
}

Weiter

Fehlerbehebung & Recovery