> ## Documentation Index > Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt > Use this file to discover all available pages before exploring further. # Obter a saúde de entrega da assinatura > Retorna um consolidado (rollup) não secreto da saúde de entrega de uma assinatura — a visão "por que este tenant parou de receber eventos". A verificação de existência (existence gate) roda primeiro, então um id ausente, soft-deleted ou de outro tenant (cross-tenant) retorna um `404 not_found` uniforme. As contagens de outcome são uma visão de janela recente, não um total desde sempre. ## OpenAPI ````yaml pt/openapi/v3-current/streaming-hub.yaml get /v1/subscriptions/{id}/health openapi: 3.1.0 info: title: Lerian Streaming Hub API version: v1.0.0 contact: email: contact@lerian.studio name: Lerian Studio url: https://lerian.studio license: name: Lerian Studio General License description: >- A API do plano de controle do Streaming Hub. O Streaming Hub é a borda gerenciada de entrega de eventos da Lerian: ele consome CloudEvents do backbone de streaming interno da plataforma e faz o fan-out para os destinos externos do próprio tenant — webhooks, Amazon SQS, RabbitMQ, Amazon EventBridge ou uma caixa de entrada pull. Esta API permite que um tenant navegue pelo catálogo de eventos alimentado por manifesto, crie e gerencie assinaturas de entrega, verifique e rotacione suas credenciais, consulte a saúde da entrega e puxe (pull) os eventos aos quais tem direito. Os erros usam um envelope plano `{"error":""}` (um token de baixa cardinalidade, legível por máquina — nunca problem+json do RFC 9457). As operações de mutação exigem um cabeçalho `X-Idempotency` para semântica de no-máximo-uma-vez (at-most-once); uma requisição repetida (replay) retorna a resposta original byte a byte com `X-Idempotency-Replayed: true`. O catálogo e a superfície de eventos por pull têm escopo de tenant através do JWT bearer; os endpoints operacionais de sondagem (`/healthz`, `/readyz`, `/version`, `/runtime`, `/metrics`) não exigem autenticação. O Streaming Hub é closed source sob a Lerian Studio General License. servers: - url: https://streaming-hub.sandbox.lerian.net security: - BearerAuth: [] tags: - name: Catalog description: >- Navegue pelo catálogo de tipos de evento disponíveis para assinatura, alimentado por manifesto. - name: Subscriptions description: >- Crie, leia, atualize e exclua assinaturas de entrega e conduza o ciclo de vida de verificação do destino (ping, verify, credential, delegated grant, rotação de segredo, saúde). - name: Event Delivery description: >- Puxe (pull) os eventos aos quais uma assinatura de sink pull tem direito (leitura com cursor-como-confirmação). - name: Admin description: >- Análise forense de operador entre tenants (cross-tenant). Exige um escopo de autorização de operador. - name: Operational description: >- Sondagens não autenticadas de liveness, readiness, build, runtime e métricas. paths: /v1/subscriptions/{id}/health: get: tags: - Subscriptions summary: Obter a saúde de entrega da assinatura description: >- Retorna um consolidado (rollup) não secreto da saúde de entrega de uma assinatura — a visão "por que este tenant parou de receber eventos". A verificação de existência (existence gate) roda primeiro, então um id ausente, soft-deleted ou de outro tenant (cross-tenant) retorna um `404 not_found` uniforme. As contagens de outcome são uma visão de janela recente, não um total desde sempre. operationId: getSubscriptionHealth parameters: - $ref: '#/components/parameters/SubscriptionId' responses: '200': description: O rollup de saúde de entrega. content: application/json: schema: $ref: '#/components/schemas/SubscriptionHealth' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/InternalError' security: - BearerAuth: [] components: parameters: SubscriptionId: name: id in: path required: true description: The unique identifier of the subscription (UUIDv7). schema: type: string format: uuid schemas: SubscriptionHealth: type: object additionalProperties: false description: >- The consolidated, non-secret delivery-health rollup for one subscription. properties: subscription_id: type: string format: uuid description: The subscription the rollup describes. examples: - 0192f1a0-0000-7000-8000-00000000a001 enabled: type: boolean description: The operator on/off flag. examples: - true verification_state: $ref: '#/components/schemas/VerificationState' status: $ref: '#/components/schemas/HealthStatus' delivery_outcomes: type: object additionalProperties: type: integer description: >- Delivery-attempt outcome counts over the configured recent window (keyed by outcome, e.g. `delivered`, `failed`, `dead_lettered`). Always an object, never null. examples: - delivered: 7 failed: 2 dead_lettered: 1 recent_outcomes: type: object additionalProperties: type: integer description: >- The same outcome histogram restricted to the last 24 hours (a subset of `delivery_outcomes`). Always an object; an outcome with no recent activity is simply a missing key. examples: - delivered: 3 failed: 1 success_rate: type: - number - 'null' description: >- The derived per-attempt delivery rate over the window (`delivered / (delivered + failed + dead_lettered)`), in `[0.0, 1.0]`. `null` when there are zero terminal attempts (distinct from a genuine `0.0`). Per-attempt, not per-job, and informational only — it does not change `status`. examples: - 0.7 dead_lettered: type: integer description: The count of dead-lettered attempts in the window. examples: - 1 poison_events: type: integer description: >- A best-effort count of quarantined (poison) events keyed on the untrusted captured tenant id; drives `dropped_tenant`. examples: - 3 dropped_tenant: type: boolean description: True when quarantined tenant events were observed. examples: - true consumer_lag_ms: type: integer format: int64 description: >- Process consumer lag in milliseconds; `0` when no lag-as-time source is exposed. examples: - 12000 auto_disabled: type: - boolean - 'null' description: >- The auto-disable verdict: `null` when the subscription has no recorded attempts yet, `false` when a health row exists with no verdict, `true` when auto-disable has tripped (which drives `status: "Down"`). examples: - true disabled_reason: type: string description: >- A fixed, secret-free auto-disable verdict token (e.g. `consecutive_failures`). Omitted when empty. examples: - consecutive_failures last_success_at: type: string format: date-time description: >- The last successful delivery timestamp (RFC 3339). Omitted when none. examples: - '2026-06-01T12:00:00Z' last_failure_at: type: string format: date-time description: The last failed delivery timestamp (RFC 3339). Omitted when none. examples: - '2026-06-05T09:30:00Z' required: - subscription_id - enabled - verification_state - status - delivery_outcomes - recent_outcomes - success_rate - dead_lettered - poison_events - dropped_tenant - consumer_lag_ms - auto_disabled VerificationState: type: string description: >- The subscription's position in the destination verification state machine. Only an `active` subscription is deliverable. A `webhook` sub is born `active`; a queue sub is born `pending_verification` and reaches `active` on a successful credential probe. `degraded` and `disabled` signal an impaired or auto-disabled destination that a successful `verify` returns to `active`. enum: - pending_verification - active - degraded - disabled HealthStatus: type: string description: >- The rolled-up delivery-health verdict. `Down` means the subscription was auto-disabled by the system (the endpoint is judged broken); `Degraded` means a lesser impairment (a manual disable, dead-lettered attempts, or dropped tenant events); `Healthy` otherwise. enum: - Healthy - Degraded - Down Error: type: object additionalProperties: false description: >- The flat error envelope used across the `/v1` and `/admin` surfaces. It carries a single low-cardinality, machine-readable token and never leaks secret material or internal detail. (A `403` from the authorization decision point is the one exception — its body is plain text.) properties: error: type: string description: The machine-readable error token. examples: - not_found required: - error responses: Unauthorized: description: >- A autenticação falhou, ou não há contexto de tenant confiável. `error` é `unauthorized` (corpo uniforme — nenhuma razão é revelada). content: application/json: schema: $ref: '#/components/schemas/Error' Forbidden: description: >- O ponto de decisão de autorização (authorization decision point) negou a requisição. O corpo é texto puro (não o envelope de erro JSON). content: text/plain: schema: type: string NotFound: description: >- O recurso está ausente, soft-deleted ou pertence a outro tenant — um `error` uniforme de `not_found` (sem oráculo de existência). content: application/json: schema: $ref: '#/components/schemas/Error' InternalError: description: >- Uma falha de infraestrutura. `error` é `internal_error` (sanitizado; o detalhe é logado, nunca retornado). content: application/json: schema: $ref: '#/components/schemas/Error' securitySchemes: BearerAuth: type: http scheme: bearer bearerFormat: JWT description: >- Um JWT bearer emitido pelo plugin-auth (lib-auth). A identidade do tenant é resolvida a partir das claims validadas do token; a superfície `/v1` nunca lê um tenant do corpo, do path ou da query. Chamadores de máquina obtêm um token via o fluxo client-credentials do plugin-auth. A superfície `/admin` autoriza contra um escopo de operador e não carrega contexto de tenant. ````