Endpoint Reference

This reference consolidates the public gateway endpoints for your agent initial path. Gateway access is in beta and is enabled by the operator. Capability-specific params, result objects, scopes, risks, and costs are always read via describe.

Base URL:

https://connect.webrichtung.de

An idempotency key is required for mutations. Format and retry behavior are on the Idempotency Requirement page.

Discovery

Endpoint	Auth	Response
`GET /health`	no	JSON with `status`, `service`, `domain`, `timestamp`
`GET /llms.txt`	no	`text/plain` with machine-readable entry point
`GET /mcp/manifest`	no	JSON manifest with meta-tools, resources, and relative transport endpoints
`GET /capabilities`	no	JSON catalog with meta-tools and public capabilities
`GET /openapi.json`	no	OpenAPI document, if publicly provided

POST /register

Creates an agent app and returns a bootstrap key.

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

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

Field	Rule
`owner_email`	Required. Valid email address of the responsible person. The same address must be repeated in `/organizations`.
`agent_email`	Optional. If set, this mailbox must be confirmed later via agent mail OTP.
`app.slug`	Required. Technical short name with lowercase letters, numbers, and `-`, 3 to 63 characters.
`app.name`	Required. Human-readable name of the agent app, 2 to 120 characters.
`app.description`	Optional. Brief description of the agent app.
`app.contact_email`	Optional. Contact address of the agent operator.
`app.homepage_url`	Optional. Public website of the agent app or operator.
`bootstrap_key.token`	Short-lived key for `/organizations` and catalog material. Do not use as a working key.

POST /organizations

Creates the owner organization, the agent installation, and the first 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"
  }
}

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

Field	Rule
`Authorization`	Required. Use the bootstrap key from `/register`.
`owner_email`	Required. Must match exactly with the owner email from `/register`.
`agent_email`	Optional. Must match the registered `agent_email`, if set there.
`organization.name`	Required. Display name of the new organization, 3 to 160 characters.
`installation.id`	Stable installation ID for diagnosis and handover. Not the API key.
`installation.agent_email_verification_status`	`not_required` if no `agent_email` is set; otherwise `pending` until `/agent-otp/verify` succeeds.
`installation.operator_approval_status`	`pending`, `approved`, or `blocked`. Operational work starts only with `approved`.
`installation_key.token`	Plaintext key for the further initial path. It is shown only in this response.
`owner_otp_delivery.status`	`queued`, `sent`, or `suppressed`. Stop and clarify if `suppressed`.
`agent_otp_delivery.correlation_id`	Public search reference for the agent mail, in the subject as `Ref: <ID>`.
`agent_otp_delivery.extraction.code_regex`	Regex for the standalone body line with the code.

POST /owner-otp/claim

Submits the owner code and documents the assumption of responsibility.

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

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

Field	Rule
`Authorization`	Required. Use the installation key from `/organizations`.
`otp`	Required. Copy the owner code generated by email exactly and without log output.
`installation.owner_verified_at`	Means: Owner legitimation is documented. Operational work may still be blocked.

POST /owner-otp/resend

Requests a fresh owner code.

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

{}

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

Field	Rule
`owner_otp_delivery.status`	`queued`, `sent`, or `suppressed`; stop and clarify if `suppressed`.
`owner_otp_delivery.expires_at`	Expiration time of the fresh owner code. The previous code is no longer authoritative after this.

POST /agent-otp/verify

Confirms the optional 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>"
}

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

Field	Rule
`otp`	Required. Copy the agent mail code exactly and without log output.
`installation.agent_email_verified_at`	Means: The optional agent mail identity is verified.
`installation.operator_approval_status`	`pending` stops operational work. Only `approved` allows the next step.

POST /agent-otp/resend

Requests a fresh agent mail code.

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

{}

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

Field	Rule
`agent_otp_delivery.correlation_id`	New search reference for the newly delivered agent mail.
`agent_otp_delivery.extraction.code_regex`	Regex for the body line with the code.

GET /org/current

Reads the organization and approval status after all required OTPs. Before owner claim, or before agent mail verification if agent_email is set, HTTP 412 precondition_failed is expected behavior; details are in the Error Taxonomy.

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

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

Field	Meaning
`organization.id`	Stable ID of the owner organization for handover and diagnosis.
`organization.short_id`	Short organization code for human reference.
`organization.is_active`	`false` means: do not continue, hand over to the operator.
`installation.agent_email_verification_status`	`not_required` or `verified` must be reached before operational work begins.
`installation.operator_approval_status`	`pending` = wait or handover, `approved` = work allowed, `blocked` = stop.
`principal.sb_user_id`	Technical principal ID of the agent. Do not interpret as owner ID.
`principal.scopes`	Scopes of the currently used installation key.

MCP Meta-Tools

All meta-tools are under /mcp/* and use the installation key as soon as the initial path is bootstrapped.

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
}

Response:

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

Field	Rule
`query`, `domain`, `risk_level_max`, `limit`, `cursor`	Optional. `limit` maximum 50.
`results[].access`	`allowed`, `scope_missing`, or `approval_always`. For `scope_missing`, do not guess, read `describe` instead.

POST /mcp/describe

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

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

Response: The complete runtime contract of the capability. For params and result, input_schema and output_schema are authoritative.

POST /mcp/dry_run

Operational dry_run calls require a legitimized and approved installation. Before required OTPs or before operator approval, the handler responds with 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": {}
}

Response form and cost semantics are on dry_run & Cost Preflight.

POST /mcp/invoke

/mcp/invoke uses the same guard chain as dry_run: installation key, required OTPs, operator approval, scopes, schema, policy, audit, billing, and egress. Before required OTPs or before operator approval, HTTP 412 precondition_failed is expected behavior.

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

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

For mutating capabilities, the body additionally contains idempotency_key. The exact result object comes from the capability’s describe contract.

Successful invokes use this wrapper:

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

Required fields are interface_version, status, capability_id, resolved_version, and audit_id. result, approval, poll, cost, replayed, and warnings depend on capability and execution state.

estimated_cost belongs to the dry_run response. A successful invoke uses cost optionally instead, when the gateway has billed or the handler reports costs.

For wallet.agent_budget.guard.check, the decision is therefore under result.allowed, not 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

Rotate the installation key only after the initial path. Before required OTPs, the endpoint responds with HTTP 412 precondition_failed. The new plaintext key appears only once.

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

{}

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

Troubleshooting & Recovery

Endpoint Reference

Discovery

POST /register

POST /organizations

POST /owner-otp/claim

POST /owner-otp/resend

POST /agent-otp/verify

POST /agent-otp/resend

GET /org/current

MCP Meta-Tools

POST /mcp/search_capabilities

POST /mcp/describe

POST /mcp/dry_run

POST /mcp/invoke

POST /keys/rotate

Next