Aller au contenu
webRichtungDocumentation

Référence des endpoints

Cette référence rassemble les endpoints publics de la passerelle pour le parcours initial de votre agent. L’accès est en bêta et doit être activé par l’opérateur. Consultez toujours describe pour les params, les objets result, les scopes, les risques et les coûts propres à chaque capacité.

URL de base :

https://connect.webrichtung.de

Les mutations exigent une clé d’idempotence. Son format et le comportement des nouvelles tentatives sont décrits dans Idempotence obligatoire.

Découverte

Section intitulée « Découverte »
Endpoint Authentification Réponse
GET /health non JSON avec status, service, domain, timestamp
GET /llms.txt non text/plain avec un guide de démarrage lisible par les machines
GET /mcp/manifest non Manifeste JSON avec méta-outils, ressources et endpoints de transport relatifs
GET /capabilities non Catalogue JSON avec méta-outils et capacités publiques
GET /openapi.json non Document OpenAPI, dans la mesure où il est rendu public

POST /register

Section intitulée « POST /register »

Crée une Agent App et renvoie une clé 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"
  }
}

Réponse 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"]
  }
}
Champ Règle
owner_email Obligatoire. Adresse e-mail valide de la personne responsable. La même adresse doit être utilisée dans /organizations.
agent_email Facultatif. Si renseigné, cette boîte devra ensuite être confirmée avec un code Agent-Mail-OTP.
app.slug Obligatoire. Nom technique court de 3 à 63 caractères, composé de lettres minuscules, de chiffres et de -.
app.name Obligatoire. Nom lisible de l’Agent App, de 2 à 120 caractères.
app.description Facultatif. Courte description de l’Agent App.
app.contact_email Facultatif. Adresse de contact de l’opérateur de l’agent.
app.homepage_url Facultatif. Site public de l’Agent App ou de son opérateur.
bootstrap_key.token Clé de courte durée pour /organizations et le catalogue. Ne pas l’utiliser comme clé de travail.

POST /organizations

Section intitulée « POST /organizations »

Crée l’organisation du propriétaire, l’Agent Installation et la première clé d’installation.

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

Réponse 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"
    }
  }
}
Champ Règle
Authorization Obligatoire. Utilisez la clé de bootstrap reçue de /register.
owner_email Obligatoire. Doit correspondre exactement à l’e-mail Owner de /register.
agent_email Facultatif. Doit correspondre à l’adresse agent_email enregistrée si elle a été renseignée.
organization.name Obligatoire. Nom affiché de la nouvelle organisation, de 3 à 160 caractères.
installation.id Identifiant stable de l’installation pour le diagnostic et le passage de relais. Ce n’est pas la clé API.
installation.agent_email_verification_status not_required si agent_email n’est pas renseigné ; sinon pending jusqu’à la réussite de /agent-otp/verify.
installation.operator_approval_status pending, approved ou blocked. Le travail opérationnel commence uniquement avec approved.
installation_key.token Clé en clair pour la suite du parcours initial. Elle est affichée uniquement dans cette réponse.
owner_otp_delivery.status queued, sent ou suppressed. Avec suppressed, s’arrêter et clarifier.
agent_otp_delivery.correlation_id Référence publique de recherche de l’e-mail de l’agent, présente dans l’objet sous la forme Ref: <ID>.
agent_otp_delivery.extraction.code_regex Expression régulière pour la ligne distincte du corps contenant le code.

POST /owner-otp/claim

Section intitulée « POST /owner-otp/claim »

Soumet le code Owner et consigne la prise de responsabilité.

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

Réponse 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"]
  }
}
Champ Règle
Authorization Obligatoire. Utilisez la clé d’installation reçue de /organizations.
otp Obligatoire. Copiez exactement le code Owner envoyé par e-mail, sans l’écrire dans les journaux.
installation.owner_verified_at L’autorisation du propriétaire est consignée. Le travail opérationnel peut encore être bloqué.

POST /owner-otp/resend

Section intitulée « POST /owner-otp/resend »

Demande un nouveau code Owner.

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

Réponse 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"
  }
}
Champ Règle
owner_otp_delivery.status queued, sent ou suppressed ; avec suppressed, s’arrêter et clarifier.
owner_otp_delivery.expires_at Date d’expiration du nouveau code Owner. Le code précédent n’est alors plus celui à utiliser.

POST /agent-otp/verify

Section intitulée « POST /agent-otp/verify »

Confirme la boîte e-mail facultative de l’agent.

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

Réponse 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"]
  }
}
Champ Règle
otp Obligatoire. Copiez exactement le code e-mail de l’agent, sans l’écrire dans les journaux.
installation.agent_email_verified_at L’identité e-mail facultative de l’agent est vérifiée.
installation.operator_approval_status pending bloque le travail opérationnel. Seul approved permet l’étape suivante.

POST /agent-otp/resend

Section intitulée « POST /agent-otp/resend »

Demande un nouveau code e-mail pour l’agent.

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

Réponse 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"
    }
  }
}
Champ Règle
agent_otp_delivery.correlation_id Nouvelle référence de recherche pour l’e-mail renvoyé à l’agent.
agent_otp_delivery.extraction.code_regex Expression régulière pour la ligne du corps contenant le code.

GET /org/current

Section intitulée « GET /org/current »

Lit le statut de l’organisation et de l’activation après tous les OTP requis. Avant la validation Owner ou, si agent_email est renseigné, avant la vérification e-mail de l’agent, la réponse HTTP 412 precondition_failed est attendue. Voir Catégories d’erreurs pour les détails.

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

Réponse 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"]
  }
}
Champ Signification
organization.id Identifiant stable de l’organisation du propriétaire pour le passage de relais et le diagnostic.
organization.short_id Code court de l’organisation à utiliser comme référence entre personnes.
organization.is_active Avec false, ne pas poursuivre le travail et transmettre à l’opérateur.
installation.agent_email_verification_status Doit avoir atteint not_required ou verified avant le début du travail opérationnel.
installation.operator_approval_status pending : attendre ou passer le relais ; approved : travail autorisé ; blocked : s’arrêter.
principal.sb_user_id Identifiant technique du principal de l’agent. Ne pas l’interpréter comme l’identifiant du propriétaire.
principal.scopes Scopes de la clé d’installation actuellement utilisée.

Méta-outils MCP

Section intitulée « Méta-outils MCP »

Tous les méta-outils se trouvent sous /mcp/* et utilisent la clé d’installation dès que le bootstrap du parcours initial est terminé.

POST /mcp/search_capabilities

Section intitulée « 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
}

Réponse :

{
  "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
}
Champ Règle
query, domain, risk_level_max, limit, cursor Facultatifs. limit ne peut pas dépasser 50.
results[].access allowed, scope_missing ou approval_always. Avec scope_missing, consulter describe plutôt que supposer les droits.

POST /mcp/describe

Section intitulée « POST /mcp/describe »
POST https://connect.webrichtung.de/mcp/describe
Content-Type: application/json
Authorization: Bearer <installation-api-key>
{
  "id": "core.org.current.get"
}

Réponse : le contrat d’exécution complet de la capacité. input_schema et output_schema font foi pour params et result.

POST /mcp/dry_run

Section intitulée « POST /mcp/dry_run »

Les appels opérationnels dry_run exigent une installation autorisée et activée. Avant les OTP requis ou l’approbation de l’opérateur, le gestionnaire répond 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": {}
}

Le format de réponse et l’interprétation des coûts sont décrits dans dry_run et estimation des coûts.

POST /mcp/invoke

Section intitulée « POST /mcp/invoke »

/mcp/invoke applique la même chaîne de contrôles que dry_run : clé d’installation, OTP requis, approbation de l’opérateur, scopes, schéma, politique, audit, facturation et sorties réseau. Avant les OTP requis ou l’approbation de l’opérateur, HTTP 412 precondition_failed est attendu.

POST https://connect.webrichtung.de/mcp/invoke
Content-Type: application/json
Authorization: Bearer <installation-api-key>
{
  "id": "core.org.current.get",
  "params": {}
}

Pour les capacités qui modifient des données, le corps contient aussi idempotency_key. L’objet result exact est défini par le contrat describe de la capacité.

Les appels Invoke réussis utilisent cette enveloppe :

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

Les champs obligatoires sont interface_version, status, capability_id, resolved_version et audit_id. Les champs result, approval, poll, cost, replayed et warnings dépendent de la capacité et de l’état d’exécution.

estimated_cost appartient à la réponse de dry_run. Un invoke réussi utilise éventuellement cost lorsque la passerelle a comptabilisé une consommation ou que le gestionnaire signale des coûts.

Pour wallet.agent_budget.guard.check, la décision se trouve donc dans result.allowed, pas au premier niveau :

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

Section intitulée « POST /keys/rotate »

Effectuez la rotation de la clé d’installation après le parcours initial. Avant les OTP requis, l’endpoint répond HTTP 412 precondition_failed. La nouvelle clé en clair n’est affichée qu’une fois.

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

Réponse 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"
  }
}

Pour continuer

Section intitulée « Pour continuer »

Dépannage et reprise