Quickstart for Agents

This quickstart connects your external Agent to the agent-enabled operating system webRichtung: You register it, bootstrap the organization, authenticate the Owner, wait for operator approval, and execute a first Capability. Gateway access is in beta.

For field rules, complete bodies, and recovery paths, use the Endpoint Reference and Troubleshooting afterwards.

Read Discovery.

The Gateway base address is:
```
https://connect.webrichtung.de
```
First check that the Gateway responds, then read the public Discovery resources:
```
GET https://connect.webrichtung.de/health
GET https://connect.webrichtung.de/llms.txt
GET https://connect.webrichtung.de/mcp/manifest
GET https://connect.webrichtung.de/capabilities
```
For real work you will later use the meta tools search_capabilities, describe, dry_run, and invoke.

POST /register creates the Agent App and returns a Bootstrap Key. The Owner email is the human accountability anchor and must remain identical in the next step.

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

Use an Idempotency-Key for every mutation following the Idempotency rule.

Bootstrap the organization.

POST /organizations uses the Bootstrap Key and returns the Installation Key for the further initial path. At the same time the Owner code is triggered; if agent_email is set, an Agent email code is also sent.
```
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"
  }
}
```
Rule of thumb: The Bootstrap Key is only valid up to /organizations. After that, the Installation Key from this response is your working key.
Redeem the required OTPs.

The human Owner reviews the process and only consciously passes on the Owner code for this onboarding. The Agent submits it with the Installation Key:
```
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>"
}
```
If agent_email is set, additionally verify the Agent mailbox. Search this mailbox for the subject component Ref: <correlation_id> from the Bootstrap response and read the code from the standalone line Code: <OTP>.
```
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>"
}
```
Owner code and Agent email code may be redeemed in any order. The simplest sequence is: complete all required OTPs, then poll for approval.
Wait for approval.

After Owner claim and optional Agent email verification, webRichtung reviews the process. Operational work starts only when installation.operator_approval_status has the value approved.
```
GET https://connect.webrichtung.de/org/current
Authorization: Bearer <installation-api-key>
```
Polling rule: first poll after 30 seconds, then at most once per 60 seconds, maximum 15 minutes. If the status remains pending, stop the Agent flow and hand off to a human.

HTTP 412 precondition_failed from /org/current before successful Owner claim or before required Agent email verification is expected behavior. The exact response is in the Error Taxonomy.

Execute the first paid Capability.

After approved follows the first paid action. This example uses documents.document.upload: first read the Contract, then generate a cost estimate, check the Budget Guard, and only then execute with Idempotency-Key.

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

{
  "id": "documents.document.upload"
}

Prepare the parameters exclusively from describe.input_schema. For the example a small text file is sufficient:

{
  "file_name": "note.txt",
  "mime_type": "text/plain",
  "content_base64": "SGVsbG8gd2VicmljaHR1bmc="
}

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

{
  "id": "documents.document.upload",
  "params": {
    "file_name": "note.txt",
    "mime_type": "text/plain",
    "content_base64": "SGVsbG8gd2VicmljaHR1bmc="
  }
}

documents.document.upload currently has describe.dry_run: "supported", not "required". In this flow you execute dry_run anyway because the Budget Guard needs estimated_cost.amount_max as a number in Credits.

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

{
  "id": "wallet.agent_budget.guard.check",
  "params": {
    "capability_id": "documents.document.upload",
    "estimated_cost_credits": 0.09,
    "window": "task"
  }
}

Only proceed if the normal Invoke envelope contains status: "succeeded" and result.allowed: true.

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

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

{
  "id": "documents.document.upload",
  "params": {
    "file_name": "note.txt",
    "mime_type": "text/plain",
    "content_base64": "SGVsbG8gd2VicmljaHR1bmc="
  },
  "idempotency_key": "idem-doc-upload-20260704-0001"
}

A successful upload has status: "succeeded" in the Invoke envelope. The Capability result is under result; the exact output form remains the describe.output_schema Contract.

Next Steps

Open Endpoint Reference