İçeriğe geç
webRichtungDokümanlar

Uç Nokta Referansı

Bu referans, Agent ilk yolunuz için genel Gateway uç noktalarını bir araya getirir. Gateway erişimi Beta aşamasındadır ve operatör tarafından etkinleştirilir. Capability’ye özgü params, result nesneleri, Scope’lar, riskler ve maliyetler her zaman describe üzerinden okunur.

Temel URL:

https://connect.webrichtung.de

Mutasyonlarda Idempotency-Key zorunludur. Format ve yeniden deneme davranışı Idempotency Zorunluluğu sayfasındadır.

Discovery

Bölüm başlığı “Discovery”
Endpoint Auth Yanıt
GET /health hayır status, service, domain, timestamp içeren JSON
GET /llms.txt hayır makine tarafından okunabilir giriş noktası içeren text/plain
GET /mcp/manifest hayır Meta Araçlar, Kaynaklar ve göreceli Transport uç noktaları içeren JSON Manifest
GET /capabilities hayır Meta Araçlar ve genel Capability’ler içeren JSON Katalog
GET /openapi.json hayır Genel olarak sağlandığı ölçüde OpenAPI Belgesi

POST /register

Bölüm başlığı “POST /register”

Bir Agent App oluşturur ve bir Bootstrap-Key döndürür.

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

Yanıt 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"]
  }
}
Alan Kural
owner_email Zorunlu. Sorumlu kişinin geçerli e-posta adresi. Aynı adres /organizations içinde tekrarlanmalıdır.
agent_email İsteğe bağlı. Ayarlanırsa, bu posta kutusu daha sonra Agent-Mail-OTP ile onaylanmalıdır.
app.slug Zorunlu. Küçük harfler, sayılar ve - ile teknik kısa ad, 3 ila 63 karakter.
app.name Zorunlu. Agent App’in insan tarafından okunabilir adı, 2 ila 120 karakter.
app.description İsteğe bağlı. Agent App’in kısa açıklaması.
app.contact_email İsteğe bağlı. Agent operatörünün iletişim adresi.
app.homepage_url İsteğe bağlı. Agent App veya operatörünün genel web sitesi.
bootstrap_key.token /organizations ve katalog materyali için kısa ömürlü Key. Çalışma Key’i olarak kullanmayın.

POST /organizations

Bölüm başlığı “POST /organizations”

Owner Organizasyonu, Agent Kurulumu ve ilk Installation-Key’i oluşturur.

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

Yanıt 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"
    }
  }
}
Alan Kural
Authorization Zorunlu. /register çıktısındaki Bootstrap-Key’i kullanın.
owner_email Zorunlu. /register çıktısındaki Owner e-postası ile tam olarak eşleşmelidir.
agent_email İsteğe bağlı. Orada ayarlanmışsa, kayıtlı agent_email ile eşleşmelidir.
organization.name Zorunlu. Yeni organizasyonun görüntülenme adı, 3 ila 160 karakter.
installation.id Teşhis ve Handover için kararlı Kurulum ID’si. API-Key değildir.
installation.agent_email_verification_status not_required ayarlanmamışsa agent_email; aksi takdirde pending başarılı olana kadar /agent-otp/verify.
installation.operator_approval_status pending, approved veya blocked. Operatif çalışma ancak approved durumunda başlar.
installation_key.token İleri adımlar için düz metin Key. Yalnızca bu yanıtta gösterilir.
owner_otp_delivery.status queued, sent veya suppressed. suppressed ise durdurun ve netleştirin.
agent_otp_delivery.correlation_id Agent-Mail için genel arama referansı, konuda Ref: <ID> olarak.
agent_otp_delivery.extraction.code_regex Kod içeren bağımsız Body satırı için regex.

POST /owner-otp/claim

Bölüm başlığı “POST /owner-otp/claim”

Owner kodunu gönderir ve sorumluluk üstlenmeyi belgeler.

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

Yanıt 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"]
  }
}
Alan Kural
Authorization Zorunlu. /organizations çıktısındaki Installation-Key’i kullanın.
otp Zorunlu. E-posta ile oluşturulan Owner kodunu tam olarak kopyalayın ve log çıktısı olmadan.
installation.owner_verified_at Şu anlama gelir: Owner meşruiyeti belgelenmiştir. Operatif çalışma yine de engellenebilir.

POST /owner-otp/resend

Bölüm başlığı “POST /owner-otp/resend”

Yeni bir Owner kodu talep eder.

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

Yanıt 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"
  }
}
Alan Kural
owner_otp_delivery.status queued, sent veya suppressed; suppressed ise durdurun ve netleştirin.
owner_otp_delivery.expires_at Yeni Owner kodunun son kullanma zamanı. Önceki kod bundan sonra geçerli değildir.

POST /agent-otp/verify

Bölüm başlığı “POST /agent-otp/verify”

İsteğe bağlı Agent posta kutusunu onaylar.

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

Yanıt 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"]
  }
}
Alan Kural
otp Zorunlu. Agent-Mail kodunu tam olarak kopyalayın ve log çıktısı olmadan.
installation.agent_email_verified_at Şu anlama gelir: İsteğe bağlı Agent-Mail kimliği doğrulanmıştır.
installation.operator_approval_status pending operatif çalışmayı durdurur. Ancak approved sonraki adıma izin verir.

POST /agent-otp/resend

Bölüm başlığı “POST /agent-otp/resend”

Yeni bir Agent-Mail kodu talep eder.

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

Yanıt 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"
    }
  }
}
Alan Kural
agent_otp_delivery.correlation_id Yeni teslim edilen Agent-Mail için yeni arama referansı.
agent_otp_delivery.extraction.code_regex Kod içeren Body satırı için regex.

GET /org/current

Bölüm başlığı “GET /org/current”

Tüm gerekli OTP’lerden sonra Organizasyon ve etkinleştirme durumunu okur. Owner-Claim’den önce, veya agent_email ayarlanmışsa Agent-Mail doğrulamasından önce, HTTP 412 precondition_failed beklenen davranıştır; ayrıntılar Hata Taksonomi içindedir.

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

Yanıt 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"]
  }
}
Alan Anlam
organization.id Handover ve teşhis için Owner Organizasyonu’nun kararlı ID’si.
organization.short_id İnsan referansı için kısa Organizasyon kodu.
organization.is_active false şu anlama gelir: çalışmaya devam etmeyin, operatöre devrolunan.
installation.agent_email_verification_status Operatif çalışma başlamadan önce not_required veya verified sağlanmalıdır.
installation.operator_approval_status pending = bekleyin veya Handover, approved = çalışmaya izin verildi, blocked = durdurun.
principal.sb_user_id Agent’ın teknik Principal ID’si. Owner ID olarak yorumlamayın.
principal.scopes Şu anda kullanılan Installation-Key’in Scope’ları.

MCP-Meta-Araçlar

Bölüm başlığı “MCP-Meta-Araçlar”

Tüm Meta-Araçlar /mcp/* altındadır ve ilk yol bootstrap edildikten sonra Installation-Key kullanır.

POST /mcp/search_capabilities

Bölüm başlığı “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
}

Yanıt:

{
  "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
}
Alan Kural
query, domain, risk_level_max, limit, cursor İsteğe bağlı. limit maksimum 50.
results[].access allowed, scope_missing veya approval_always. scope_missing durumunda tahmin etmeyin, describe okuyun.

POST /mcp/describe

Bölüm başlığı “POST /mcp/describe”
POST https://connect.webrichtung.de/mcp/describe
Content-Type: application/json
Authorization: Bearer <installation-api-key>
{
  "id": "core.org.current.get"
}

Yanıt: Capability’nin tam Runtime-Contract’ı. params ve result için input_schema ve output_schema bağlayıcıdır.

POST /mcp/dry_run

Bölüm başlığı “POST /mcp/dry_run”

Operatif dry_run çağrıları meşrulaştırılmış ve etkinleştirilmiş bir Kurulum gerektirir. Gerekli OTP’lerden önce veya Operator-Approval’dan önce Handler HTTP 412 precondition_failed ile yanıt verir.

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

Yanıt formu ve maliyet semantiği dry_run & Maliyet-Preflight üzerindedir.

POST /mcp/invoke

Bölüm başlığı “POST /mcp/invoke”

/mcp/invoke, dry_run ile aynı Guard zincirini kullanır: Installation-Key, gerekli OTP’ler, Operator-Approval, Scope’lar, Schema, Policy, Audit, Billing ve Egress. Gerekli OTP’lerden önce veya Operator-Approval’dan önce HTTP 412 precondition_failed beklenen davranıştır.

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

Mutasyon yapan Capability’lerde Body ayrıca idempotency_key içerir. Tam result nesnesi Capability’nin describe-Contract’ından gelir.

Başarılı Invoke’lar bu zarfı kullanır:

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

Zorunlu alanlar interface_version, status, capability_id, resolved_version ve audit_id şeklindedir. result, approval, poll, cost, replayed ve warnings, Capability ve yürütme durumuna bağlıdır.

estimated_cost, dry_run yanıtına aittir. Başarılı bir invoke, Gateway rezerve ettiyse veya Handler maliyetleri raporladıysa bunun yerine isteğe bağlı olarak cost kullanır.

wallet.agent_budget.guard.check durumunda karar dolayısıyla result.allowed altındadır, üst seviyede değil:

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

Bölüm başlığı “POST /keys/rotate”

Installation-Key’i ancak ilk yoldan sonra döndürün. Gerekli OTP’lerden önce Endpoint HTTP 412 precondition_failed ile yanıt verir. Yeni düz metin Key yalnızca bir kez görünür.

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

Yanıt 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"
  }
}

Devamı

Bölüm başlığı “Devamı”

Sorun Giderme & Kurtarma