Referencia de endpoints

Esta referencia agrupa los endpoints públicos del gateway para la ruta de creación de tu agente. El acceso al gateway está en beta y lo habilita el operador. Los objetos params y result específicos de cada capability, así como los scopes, riesgos y costos, siempre los consultas mediante describe.

URL base:

https://connect.webrichtung.de

Para las mutaciones, la clave de idempotencia es obligatoria. El formato y el comportamiento de reintento se encuentran en la página Obligación de idempotencia.

Discovery

Endpoint	Auth	Respuesta
`GET /health`	no	JSON con `status`, `service`, `domain`, `timestamp`
`GET /llms.txt`	no	`text/plain` con entrada legible por máquina
`GET /mcp/manifest`	no	Manifiesto JSON con meta-herramientas, recursos y endpoints de transporte relativos
`GET /capabilities`	no	Catálogo JSON con meta-herramientas y capabilities públicas
`GET /openapi.json`	no	Documento OpenAPI, en la medida en que se proporcione públicamente

POST /register

Crea una Agent App y devuelve una clave de bootstrap.

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

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

Campo	Regla
`owner_email`	Obligatorio. Dirección de correo electrónico válida de la persona responsable. La misma dirección debe repetirse en `/organizations`.
`agent_email`	Opcional. Si se establece, este buzón deberá confirmarse posteriormente mediante OTP de correo del agente.
`app.slug`	Obligatorio. Nombre técnico corto con letras minúsculas, números y `-`, de 3 a 63 caracteres.
`app.name`	Obligatorio. Nombre legible de la Agent App, de 2 a 120 caracteres.
`app.description`	Opcional. Descripción breve de la Agent App.
`app.contact_email`	Opcional. Dirección de contacto del operador del agente.
`app.homepage_url`	Opcional. Sitio web público de la Agent App o del operador.
`bootstrap_key.token`	Clave de corta duración para `/organizations` y material del catálogo. No utilizar como clave de trabajo.

POST /organizations

Crea la organización propietaria, la instalación del agente y la primera clave de instalación.

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

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

Campo	Regla
`Authorization`	Obligatorio. Utiliza la clave de bootstrap de `/register`.
`owner_email`	Obligatorio. Debe coincidir exactamente con el correo del propietario de `/register`.
`agent_email`	Opcional. Debe coincidir con la `agent_email` registrada, si se estableció allí.
`organization.name`	Obligatorio. Nombre visible de la nueva organización, de 3 a 160 caracteres.
`installation.id`	ID de instalación estable para diagnóstico y handover. No es la clave de API.
`installation.agent_email_verification_status`	`not_required`, si no se estableció `agent_email`; de lo contrario `pending`, hasta que `/agent-otp/verify` tenga éxito.
`installation.operator_approval_status`	`pending`, `approved` o `blocked`. El trabajo operativo solo comienza con `approved`.
`installation_key.token`	Clave en texto claro para la ruta de creación posterior. Solo se muestra en esta respuesta.
`owner_otp_delivery.status`	`queued`, `sent` o `suppressed`. Con `suppressed` detener y aclarar.
`agent_otp_delivery.correlation_id`	Referencia de búsqueda pública para el correo del agente, en el asunto como `Ref: <ID>`.
`agent_otp_delivery.extraction.code_regex`	Regex para la línea del cuerpo independiente con el código.

POST /owner-otp/claim

Envía el código del propietario y documenta la asunción de responsabilidad.

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

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

Campo	Regla
`Authorization`	Obligatorio. Utiliza la clave de instalación de `/organizations`.
`otp`	Obligatorio. Copia el código del propietario generado por correo electrónico exactamente y sin salida de log.
`installation.owner_verified_at`	Significa: la legitimación del propietario está documentada. El trabajo operativo puede estar aún bloqueado.

POST /owner-otp/resend

Solicita un código de propietario nuevo.

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

{}

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

Campo	Regla
`owner_otp_delivery.status`	`queued`, `sent` o `suppressed`; con `suppressed` detener y aclarar.
`owner_otp_delivery.expires_at`	Momento de expiración del código de propietario nuevo. El código anterior deja de ser aplicable después de esto.

POST /agent-otp/verify

Confirma el buzón opcional del agente.

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

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

Campo	Regla
`otp`	Obligatorio. Copia el código de correo del agente exactamente y sin salida de log.
`installation.agent_email_verified_at`	Significa: la identidad opcional del correo del agente está verificada.
`installation.operator_approval_status`	`pending` detiene el trabajo operativo. Solo `approved` permite el siguiente paso.

POST /agent-otp/resend

Solicita un código de correo del agente nuevo.

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

{}

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

Campo	Regla
`agent_otp_delivery.correlation_id`	Nueva referencia de búsqueda para el correo del agente recién entregado.
`agent_otp_delivery.extraction.code_regex`	Regex para la línea del cuerpo con el código.

GET /org/current

Lee el estado de la organización y de habilitación después de todos los OTP requeridos. Antes del claim del propietario, o si hay agent_email establecida antes de la verificación del correo del agente, HTTP 412 precondition_failed es el comportamiento esperado; los detalles se encuentran en la taxonomía de errores.

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

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

Campo	Significado
`organization.id`	ID estable de la organización propietaria para handover y diagnóstico.
`organization.short_id`	Código de organización corto para referencia humana.
`organization.is_active`	`false` significa: no continuar trabajando, transferir al operador.
`installation.agent_email_verification_status`	`not_required` o `verified` debe alcanzarse antes de que comience el trabajo operativo.
`installation.operator_approval_status`	`pending` = esperar o handover, `approved` = trabajo permitido, `blocked` = detener.
`principal.sb_user_id`	ID de principal técnico del agente. No interpretar como ID del propietario.
`principal.scopes`	Scopes de la clave de instalación actualmente en uso.

Meta-herramientas MCP

Todas las meta-herramientas se encuentran en /mcp/* y utilizan la clave de instalación, una vez que se ha completado el bootstrap de la ruta de creación.

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
}

Respuesta:

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

Campo	Regla
`query`, `domain`, `risk_level_max`, `limit`, `cursor`	Opcional. `limit` máximo 50.
`results[].access`	`allowed`, `scope_missing` o `approval_always`. Con `scope_missing` no adivinar, sino leer `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"
}

Respuesta: El contrato de tiempo de ejecución completo de la capability. Para params y result, input_schema y output_schema son vinculantes.

POST /mcp/dry_run

Las llamadas operativas de dry_run requieren una instalación legitimada y habilitada. Antes de los OTP requeridos o antes de la aprobación del operador, el handler responde con 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": {}
}

La forma de respuesta y la semántica de costos se encuentran en dry_run y preflight de costos.

POST /mcp/invoke

/mcp/invoke utiliza la misma cadena de protección que dry_run: clave de instalación, OTP requeridos, aprobación del operador, scopes, esquema, política, auditoría, facturación y salida. Antes de los OTP requeridos o antes de la aprobación del operador, HTTP 412 precondition_failed es el comportamiento esperado.

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

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

Para capabilities que mutan, el cuerpo contiene adicionalmente idempotency_key. El objeto result exacto proviene del contrato describe de la capability.

Las invocaciones exitosas utilizan este envoltorio:

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

Los campos obligatorios son interface_version, status, capability_id, resolved_version y audit_id. result, approval, poll, cost, replayed y warnings dependen de la capability y del estado de ejecución.

estimated_cost pertenece a la respuesta de dry_run. Un invoke exitoso utiliza opcionalmente cost en su lugar, si el gateway ha contabilizado o el handler reporta costos.

Para wallet.agent_budget.guard.check, la decisión se encuentra en result.allowed, no en el nivel superior:

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

Rota la clave de instalación solo después de la ruta de creación. Antes de los OTP requeridos, el endpoint responde con HTTP 412 precondition_failed. La nueva clave en texto claro aparece solo una vez.

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

{}

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

Solución de errores y recuperación

Referencia de endpoints

Discovery

POST /register

POST /organizations

POST /owner-otp/claim

POST /owner-otp/resend

POST /agent-otp/verify

POST /agent-otp/resend

GET /org/current

Meta-herramientas MCP

POST /mcp/search_capabilities

POST /mcp/describe

POST /mcp/dry_run

POST /mcp/invoke

POST /keys/rotate

Siguiente