> ## 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. # Haz pull de los eventos a los que tienes derecho > Obtiene una página de los eventos a los que una suscripción pull tiene derecho, en orden de llegada `seq`. La lectura funciona también como el acknowledgment (cursor-as-ack): tras una obtención exitosa, el `seq` más alto devuelto se persiste como el cursor de la suscripción, de forma monotónica. Un cursor `after` explícito sobrescribe el cursor persistido para la lectura; un salto hacia adelante avanza el cursor durable más allá del hueco no leído (el rango omitido no se vuelve a entregar — caller-owns-the-gap), mientras que un salto hacia atrás nunca lo rebobina. La lectura tiene rate limit por tenant. Los eventos son at-least-once; deduplica en `ceId`. ## OpenAPI ````yaml es/openapi/v3-current/streaming-hub.yaml get /v1/events 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: >- La API de control-plane de Streaming Hub. Streaming Hub es el borde gestionado de entrega de eventos de Lerian: consume CloudEvents del backbone de streaming interno de la plataforma y los distribuye a los destinos externos propios de cada tenant — webhooks, Amazon SQS, RabbitMQ, Amazon EventBridge o una bandeja de entrada de tipo pull. Esta API permite a un tenant explorar el catálogo de eventos alimentado por el manifest, crear y gestionar suscripciones de entrega, verificar y rotar sus credenciales, leer la salud de entrega y hacer pull de los eventos a los que tiene derecho. Los errores ahora se sirven como documentos RFC 9457 `application/problem+json`. Cada error propio del hub incluye `type`, `title`, `status`, `detail` y un `code` estable y de baja cardinalidad legible por máquina sobre el que ramifican los clientes; para respuestas `5xx` el campo `detail` se sanitiza centralmente al valor estático `"internal error"`, de modo que ninguna causa interna se filtre al llamador. Las operaciones de mutación requieren un header `X-Idempotency` para semántica at-most-once; una petición reproducida (replay) devuelve la respuesta original byte a byte con `X-Idempotency-Replayed: true`. El catálogo y la superficie de eventos pull están acotados por tenant a través del JWT bearer; los endpoints operacionales de sonda (`/healthz`, `/readyz`, `/version`, `/runtime`, `/metrics`) no requieren autenticación. Streaming Hub es de código cerrado bajo la Lerian Studio General License. servers: - url: https://streaming-hub.sandbox.lerian.net security: - BearerAuth: [] tags: - name: Catalog description: >- Explora el catálogo de tipos de evento disponibles para suscripción, alimentado por el manifest. - name: Subscriptions description: >- Crea, lee, actualiza y elimina suscripciones de entrega, y gestiona el ciclo de vida de verificación del destino (ping, verify, credential, delegated grant, rotación de secreto, health). - name: Event Delivery description: >- Haz pull de los eventos a los que tienes derecho para una suscripción de tipo pull (lectura cursor-as-acknowledgment). - name: Admin description: >- Análisis forense de operador entre tenants. Requiere un scope de autorización de operador. - name: Operational description: >- Sondas de liveness, readiness, build, runtime y métricas sin autenticación. paths: /v1/events: get: tags: - Event Delivery summary: Haz pull de los eventos a los que tienes derecho description: >- Obtiene una página de los eventos a los que una suscripción pull tiene derecho, en orden de llegada `seq`. La lectura funciona también como el acknowledgment (cursor-as-ack): tras una obtención exitosa, el `seq` más alto devuelto se persiste como el cursor de la suscripción, de forma monotónica. Un cursor `after` explícito sobrescribe el cursor persistido para la lectura; un salto hacia adelante avanza el cursor durable más allá del hueco no leído (el rango omitido no se vuelve a entregar — caller-owns-the-gap), mientras que un salto hacia atrás nunca lo rebobina. La lectura tiene rate limit por tenant. Los eventos son at-least-once; deduplica en `ceId`. operationId: pullEvents parameters: - name: subscription_id in: query required: true description: >- The pull subscription to read. Resolved through an existence gate then a kind gate: an absent, cross-tenant, or non-`pull` id all return a uniform `404 not_found` (no existence or kind oracle). schema: type: string format: uuid - name: after in: query required: false description: >- Explicit keyset cursor (replay). When present it overrides the persisted cursor for the read; absent it, the read resumes from the persisted acknowledged `seq` (0 = from the beginning). A malformed value is ignored and folds to the persisted cursor. schema: type: integer format: int64 - name: limit in: query required: false description: Page size, clamped to the range 1–500, defaulting to 100. schema: type: integer responses: '200': description: Una página de eventos en orden ascendente de `seq`. content: application/json: schema: $ref: '#/components/schemas/PullEventsResponse' '400': description: >- El parámetro de query obligatorio `subscription_id` está ausente — `error` es `bad_request`. content: application/json: schema: $ref: '#/components/schemas/Error' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '429': description: >- El limitador de lecturas de entrada por tenant denegó la petición — `error` es `rate_limited`. Haz backoff y reintenta. content: application/json: schema: $ref: '#/components/schemas/Error' '500': $ref: '#/components/responses/InternalError' security: - BearerAuth: [] components: schemas: PullEventsResponse: type: object additionalProperties: false properties: events: type: array description: A page of events in ascending `seq` order. items: $ref: '#/components/schemas/PullEvent' next_cursor: type: - integer - 'null' format: int64 description: >- The maximum `seq` in the page when it filled exactly to `limit` (a possible next page); `null` on a short or final page. This diverges deliberately from the subscriptions list cursor (which is a DESC-by-id string with an empty-string sentinel). examples: - 42 required: - events - next_cursor Error: type: object description: >- Documento RFC 9457 `application/problem+json` devuelto para cada error propio del hub en las superficies `/v1` y `/admin`. El `code` estable es el campo sobre el que un cliente ramifica; `detail` es una explicación segura para el llamador y, para cualquier `5xx`, se sanitiza centralmente al valor `"internal error"` para que ninguna causa interna pueda filtrarse. (Un `403` emitido por el punto de decisión de autorización situado por delante del hub es la única excepción — su cuerpo es texto plano.) properties: type: type: string format: uri description: >- URI estable y versionado que identifica el tipo de problema (`https://errors.lerian.studio/v1/`), o `about:blank` para problemas sin un código asignado por el hub. examples: - https://errors.lerian.studio/v1/not_found title: type: string description: Un resumen corto y legible por humanos — el texto del estado HTTP. examples: - Not Found status: type: integer description: El código de estado HTTP, replicado en el cuerpo. examples: - 404 detail: type: string description: >- Explicación humana y segura para el llamador de esta ocurrencia específica. Para respuestas `5xx` este campo es siempre la cadena estática `"internal error"`. examples: - subscription not found code: type: string description: >- El token estable, de baja cardinalidad y legible por máquina sobre el que ramifica un cliente (por ejemplo `not_found`, `unauthorized`, `idempotency_conflict`, `validation_error`). Vacío para fallos de validación nativos de huma. examples: - not_found required: - type - title - status PullEvent: type: object additionalProperties: false properties: seq: type: integer format: int64 description: The tenant arrival-order sequence number (the keyset key). examples: - 42 ceId: type: string description: >- The CloudEvents id (UUIDv7) — the stable dedup key. Deduplicate on this across at-least-once redeliveries. examples: - 0192f1a0-0000-7000-8000-0000000000ce eventType: type: string description: The event type (the `.` tail). examples: - orders.created schemaVersion: type: string description: The event's schema version. examples: - 1.0.0 receivedAt: type: string format: date-time description: When the hub received the event (UTC, RFC 3339). examples: - '2026-06-06T12:00:00Z' payload: type: object additionalProperties: true description: >- The producer's event payload, surfaced opaquely (arbitrary JSON). Carries no secret material. examples: - order_id: abc amount: 42 required: - seq - ceId - eventType - schemaVersion - receivedAt - payload responses: Unauthorized: description: >- La autenticación falló, o no hay contexto de tenant confiable. `code` es `unauthorized` (cuerpo uniforme — no se revela ninguna razón). content: application/problem+json: schema: $ref: '#/components/schemas/Error' Forbidden: description: >- El punto de decisión de autorización (lib-auth, situado por delante del hub) denegó la petición. Este 403 sigue siendo texto plano — actualmente no usa `application/problem+json`. content: text/plain: schema: type: string NotFound: description: >- El recurso está ausente, soft-deleted o pertenece a otro tenant — un `code` uniforme de `not_found` (sin oráculo de existencia). content: application/problem+json: schema: $ref: '#/components/schemas/Error' InternalError: description: >- Un fallo de infraestructura. `code` es `internal_error` y el campo `detail` se sanitiza centralmente al valor estático `"internal error"` (la causa real se registra, nunca se devuelve al llamador). content: application/problem+json: schema: $ref: '#/components/schemas/Error' securitySchemes: BearerAuth: type: http scheme: bearer bearerFormat: JWT description: >- Un JWT bearer emitido por plugin-auth (lib-auth). La identidad del tenant se resuelve a partir de los claims validados del token; la superficie `/v1` nunca lee un tenant del cuerpo, del path ni de la query. Los llamadores de máquina obtienen un token vía el flujo client-credentials de plugin-auth. La superficie `/admin` autoriza contra un scope de operador y no lleva contexto de tenant. ````