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

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

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

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

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

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

İ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

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

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

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

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

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

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

/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

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ı

Sorun Giderme & Kurtarma