Dokumentacja punktów końcowych

Niniejsza dokumentacja zawiera publiczne punkty końcowe bramy dla ścieżki tworzenia Twojego agenta. Dostęp do bramy jest w fazie beta i jest aktywowany przez operatora. Specyficzne dla możliwości parametry params, obiekty result, zakresy uprawnień, ryzyka i koszty zawsze odczytujesz przez describe.

Bazowy URL:

https://connect.webrichtung.de

W przypadku mutacji wymagany jest klucz idempotencji. Format i zachowanie przy ponownych próbach znajdują się na stronie Wymaganie idempotencji.

Wykrywanie

Punkt końcowy	Autoryzacja	Odpowiedź
`GET /health`	nie	JSON ze `status`, `service`, `domain`, `timestamp`
`GET /llms.txt`	nie	`text/plain` z maszynowo czytelnym punktem wejścia
`GET /mcp/manifest`	nie	Manifest JSON z meta-narzędziami, zasobami i względnymi punktami końcowymi transportu
`GET /capabilities`	nie	Katalog JSON z meta-narzędziami i publicznymi możliwościami
`GET /openapi.json`	nie	Dokument OpenAPI, o ile jest publicznie udostępniony

POST /register

Tworzy aplikację agenta i zwraca klucz rozruchowy.

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"
  }
}

Odpowiedź 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"]
  }
}

Pole	Reguła
`owner_email`	Wymagane. Prawidłowy adres e-mail osoby odpowiedzialnej. Ten sam adres musi zostać powtórzony w `/organizations`.
`agent_email`	Opcjonalne. Jeśli zostanie ustawione, ta skrzynka pocztowa musi zostać później potwierdzona przez OTP agenta.
`app.slug`	Wymagane. Techniczny identyfikator składający się z małych liter, cyfr i `-`, od 3 do 63 znaków.
`app.name`	Wymagane. Czytelna nazwa aplikacji agenta, od 2 do 120 znaków.
`app.description`	Opcjonalne. Krótki opis aplikacji agenta.
`app.contact_email`	Opcjonalne. Adres kontaktowy operatora agenta.
`app.homepage_url`	Opcjonalne. Publiczna strona internetowa aplikacji agenta lub operatora.
`bootstrap_key.token`	Krótkotrwały klucz dla `/organizations` i materiałów katalogowych. Nie używać jako klucza roboczego.

POST /organizations

Tworzy organizację właściciela, instalację agenta i pierwszy klucz instalacyjny.

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"
  }
}

Odpowiedź 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"
    }
  }
}

Pole	Reguła
`Authorization`	Wymagane. Użyj klucza rozruchowego z `/register`.
`owner_email`	Wymagane. Musi dokładnie odpowiadać adresowi e-mail właściciela z `/register`.
`agent_email`	Opcjonalne. Musi odpowiadać zarejestrowanemu `agent_email`, jeśli został tam ustawiony.
`organization.name`	Wymagane. Wyświetlana nazwa nowej organizacji, od 3 do 160 znaków.
`installation.id`	Stabilny identyfikator instalacji do diagnostyki i przekazania. Nie jest to klucz API.
`installation.agent_email_verification_status`	`not_required`, jeśli nie ustawiono `agent_email`; w przeciwnym razie `pending`, dopóki `/agent-otp/verify` nie zakończy się sukcesem.
`installation.operator_approval_status`	`pending`, `approved` lub `blocked`. Praca operacyjna rozpoczyna się dopiero przy `approved`.
`installation_key.token`	Klucz w formacie tekstowym do dalszej ścieżki początkowej. Jest wyświetlany tylko w tej odpowiedzi.
`owner_otp_delivery.status`	`queued`, `sent` lub `suppressed`. Przy `suppressed` zatrzymać i wyjaśnić.
`agent_otp_delivery.correlation_id`	Publiczna referencja wyszukiwania dla e-maila agenta, w temacie jako `Ref: <ID>`.
`agent_otp_delivery.extraction.code_regex`	Wyrażenie regularne dla samodzielnej linii treści z kodem.

POST /owner-otp/claim

Przekazuje kod właściciela i dokumentuje przejęcie odpowiedzialności.

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>"
}

Odpowiedź 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"]
  }
}

Pole	Reguła
`Authorization`	Wymagane. Użyj klucza instalacyjnego z `/organizations`.
`otp`	Wymagane. Skopiuj wygenerowany przez e-mail kod właściciela dokładnie i bez wypisywania do logu.
`installation.owner_verified_at`	Oznacza: legitymacja właściciela jest udokumentowana. Praca operacyjna może jednak nadal być zablokowana.

POST /owner-otp/resend

Żąda świeżego kodu właściciela.

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

{}

Odpowiedź 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"
  }
}

Pole	Reguła
`owner_otp_delivery.status`	`queued`, `sent` lub `suppressed`; przy `suppressed` zatrzymać i wyjaśnić.
`owner_otp_delivery.expires_at`	Moment wygaśnięcia świeżego kodu właściciela. Poprzedni kod nie ma już znaczenia po tym czasie.

POST /agent-otp/verify

Potwierdza opcjonalną skrzynkę pocztową agenta.

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>"
}

Odpowiedź 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"]
  }
}

Pole	Reguła
`otp`	Wymagane. Skopiuj kod e-mail agenta dokładnie i bez wypisywania do logu.
`installation.agent_email_verified_at`	Oznacza: opcjonalna tożsamość e-mail agenta jest zweryfikowana.
`installation.operator_approval_status`	`pending` zatrzymuje pracę operacyjną. Dopiero `approved` pozwala na kolejny krok.

POST /agent-otp/resend

Żąda świeżego kodu e-mail agenta.

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

{}

Odpowiedź 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"
    }
  }
}

Pole	Reguła
`agent_otp_delivery.correlation_id`	Nowa referencja wyszukiwania dla nowo dostarczonego e-maila agenta.
`agent_otp_delivery.extraction.code_regex`	Wyrażenie regularne dla linii treści z kodem.

GET /org/current

Odczytuje po wszystkich wymaganych OTP status organizacji i aktywacji. Przed potwierdzeniem właściciela lub, jeśli ustawiono agent_email, przed weryfikacją e-maila agenta, HTTP 412 precondition_failed jest oczekiwanym zachowaniem; szczegóły znajdują się w Taksonomii błędów.

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

Odpowiedź 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"]
  }
}

Pole	Znaczenie
`organization.id`	Stabilny identyfikator organizacji właściciela do przekazania i diagnostyki.
`organization.short_id`	Krótki kod organizacji do ludzkiego odniesienia.
`organization.is_active`	`false` oznacza: nie kontynuować pracy, przekazać operatorowi.
`installation.agent_email_verification_status`	Musi zostać osiągnięty stan `not_required` lub `verified`, zanim rozpocznie się praca operacyjna.
`installation.operator_approval_status`	`pending` = czekać lub przekazać, `approved` = praca dozwolona, `blocked` = zatrzymać.
`principal.sb_user_id`	Techniczny identyfikator principal agenta. Nie interpretować jako identyfikatora właściciela.
`principal.scopes`	Zakresy uprawnień aktualnie używanego klucza instalacyjnego.

Meta-narzędzia MCP

Wszystkie meta-narzędzia znajdują się pod /mcp/* i używają klucza instalacyjnego, gdy tylko ścieżka początkowa jest zainicjowana.

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
}

Odpowiedź:

{
  "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
}

Pole	Reguła
`query`, `domain`, `risk_level_max`, `limit`, `cursor`	Opcjonalne. `limit` maksymalnie 50.
`results[].access`	`allowed`, `scope_missing` lub `approval_always`. Przy `scope_missing` nie zgadywać, tylko odczytać `describe`.

POST /mcp/describe

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

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

Odpowiedź: Kompletny kontrakt wykonawczy możliwości. Dla params i result obowiązują input_schema i output_schema.

POST /mcp/dry_run

Operacyjne wywołania dry_run wymagają legitymowanej i aktywowanej instalacji. Przed wymaganymi OTP lub przed zatwierdzeniem operatora handler odpowiada 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": {}
}

Forma odpowiedzi i semantyka kosztów znajdują się na dry_run & Kosten-Preflight.

POST /mcp/invoke

/mcp/invoke używa tego samego łańcucha zabezpieczeń co dry_run: klucz instalacyjny, wymagane OTP, zatwierdzenie operatora, zakresy uprawnień, schemat, polityka, audyt, rozliczenia i wyjście. Przed wymaganymi OTP lub przed zatwierdzeniem operatora HTTP 412 precondition_failed jest oczekiwanym zachowaniem.

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

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

W przypadku możliwości modyfikujących treść zawiera dodatkowo idempotency_key. Dokładny obiekt result pochodzi z kontraktu describe możliwości.

Udane wywołania używają tej otoczki:

{
  "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"
  }
}

Pola obowiązkowe to interface_version, status, capability_id, resolved_version i audit_id. result, approval, poll, cost, replayed i warnings zależą od możliwości i stanu wykonania.

estimated_cost należy do odpowiedzi dry_run. Udane invoke używa zamiast tego opcjonalnie cost, jeśli brama zaksięgowała lub handler zgłosił koszty.

W przypadku wallet.agent_budget.guard.check decyzja znajduje się zatem w result.allowed, a nie na najwyższym poziomie:

{
  "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

Rotuj klucz instalacyjny dopiero po ścieżce początkowej. Przed wymaganymi OTP punkt końcowy odpowiada HTTP 412 precondition_failed. Nowy klucz w formacie tekstowym pojawia się tylko raz.

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

{}

Odpowiedź 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"
  }
}

Dalej

Fehlerbehebung & Recovery