> ## 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. # List subscriptions > Lists the authenticated tenant's live subscriptions, newest-first, keyset-paginated. No read projection ever carries the signing secret. Each row carries `endpoint_display`, a short rendering of the destination; read the full destination with `GET /v1/subscriptions/{id}/endpoint`. ## OpenAPI ````yaml /pt/openapi/v3-current/streaming-hub.yaml get /v1/subscriptions openapi: 3.1.0 info: title: Lerian Streaming Hub API version: 1.2.0 contact: email: contact@lerian.studio name: Lerian Studio url: https://lerian.studio license: name: Lerian Studio General License description: >- The Streaming Hub control-plane API. Streaming Hub is Lerian's managed event-delivery edge: it consumes CloudEvents from the platform's internal streaming backbone and fans them out to a tenant's own external destinations — webhooks, Amazon SQS, RabbitMQ, Amazon EventBridge, or a pull inbox. This API lets a tenant browse the manifest-fed event catalog, create and manage delivery subscriptions, verify and rotate their credentials, read delivery health, and pull entitled events. An RFC 9457 `application/problem+json` error body carries `title` and `status`. An error the hub raises adds `type`, `detail`, and a stable low-cardinality `code` you can branch on; a request the framework rejects before the operation runs, such as a malformed or schema-invalid one, carries no `code`. Mutating operations require an `X-Idempotency` header for at-most-once semantics; a replayed request returns the original response byte-for-byte with `X-Idempotency-Replayed: true`. The catalog and the pull events surface are tenant-scoped through the bearer JWT; the operational probe endpoints (`/healthz`, `/readyz`, `/version`, `/runtime`, `/metrics`) are unauthenticated. servers: - url: https://streaming-hub.sandbox.lerian.net security: - BearerAuth: [] tags: - name: Catalog description: Browse the manifest-fed catalog of event types available for subscription. - name: Subscriptions description: >- Create, read, update, and delete delivery subscriptions, and drive the destination verification lifecycle (ping, verify, credential, delegated grant, secret rotation, health). - name: Event Delivery description: >- Pull entitled events for a pull-sink subscription (cursor-as-acknowledgment read). - name: Dashboard description: >- The read-only operational dashboard: a consistent snapshot of ingestion, push delivery, and pull eligibility, plus the paged list of subscriptions that need attention. It never consumes events and never returns a secret. - name: Admin description: Cross-tenant operator forensics. Requires an operator authorization scope. - name: Operational description: Unauthenticated liveness, readiness, build, runtime, and metrics probes. paths: /v1/subscriptions: get: tags: - Subscriptions summary: List subscriptions description: >- Lists the authenticated tenant's live subscriptions, newest-first, keyset-paginated. No read projection ever carries the signing secret. Each row carries `endpoint_display`, a short rendering of the destination; read the full destination with `GET /v1/subscriptions/{id}/endpoint`. operationId: listSubscriptions parameters: - name: sink_kind in: query required: false description: >- Optional filter restricting results to one sink kind. Any other value returns `422 validation_error`. schema: $ref: '#/components/schemas/SinkKind' - name: limit in: query required: false description: >- Page size, clamped to a server maximum. A non-positive value uses the server default. schema: type: integer - name: after in: query required: false description: >- Keyset cursor — the `id` of the last row from the previous page (subscriptions are ordered DESC by id). A value that is not a UUID returns `422 validation_error`. schema: type: string - name: name in: query required: false description: >- Optional exact-name filter, trimmed before matching. It matches in your scope, the same scope the create checks for a name conflict, so a hit is a page of one. A value that is only whitespace returns `422 validation_error`. schema: type: string - name: enabled in: query required: false description: >- Optional filter on the `enabled` flag, `true` or `false`. Any other value returns `422 validation_error`. schema: type: boolean - name: verification_state in: query required: false description: Optional filter on the verification state. schema: $ref: '#/components/schemas/VerificationState' responses: '200': description: A page of subscriptions. headers: X-RateLimit-Limit: $ref: '#/components/headers/RateLimitLimit' X-RateLimit-Remaining: $ref: '#/components/headers/RateLimitRemaining' X-RateLimit-Reset: $ref: '#/components/headers/RateLimitReset' content: application/json: schema: $ref: '#/components/schemas/ListSubscriptionsResponse' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '422': $ref: '#/components/responses/ValidationError' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/InternalError' '503': $ref: '#/components/responses/MeteredServiceUnavailable' '504': $ref: '#/components/responses/GatewayTimeout' security: - BearerAuth: [] components: schemas: SinkKind: type: string description: >- The delivery destination kind. `webhook` posts signed HTTPS requests; `pull` exposes an inbox read over `GET /v1/events`; `sqs`, `rabbitmq`, and `eventbridge` fan out to the named queue or bus. enum: - webhook - pull - sqs - rabbitmq - eventbridge VerificationState: type: string description: >- The subscription's position in the destination verification state machine. Only an `active` subscription is deliverable. A `pull` subscription is born `active` — it has no destination to probe. Every other kind is born `pending_verification` and reaches `active` on a successful probe: `POST /v1/subscriptions/{id}/ping` for a `webhook`, and `PUT /v1/subscriptions/{id}/credential` for any queue sink (`sqs`, `rabbitmq`, `eventbridge`). An `sqs` or `eventbridge` sink has a second path: register a delegated grant — which persists the coordinates and leaves this field unchanged — then call `POST /v1/subscriptions/{id}/verify`. An `active` subscription whose probe later fails becomes `degraded`. The same successful probe returns this field to `active`. This field is one half of deliverability: `enabled` is the other half, and both must hold. No probe changes `enabled` except `POST /v1/subscriptions/{id}/verify`, which on a probe success clears an auto-disable in the same transaction as the state move. enum: - pending_verification - active - degraded ListSubscriptionsResponse: type: object additionalProperties: false properties: subscriptions: type: array items: $ref: '#/components/schemas/SubscriptionRead' next_cursor: type: string description: >- Keyset cursor for the next page (the id of the last row). Non-empty only on a full page; an empty string marks the final page. examples: - 0192f1a0-0000-7000-8000-00000000c002 required: - subscriptions - next_cursor SubscriptionRead: type: object additionalProperties: false description: >- The non-secret projection of a subscription on the list and detail routes. It carries `endpoint_display` instead of the full destination, and never carries the signing secret or any credential material. properties: id: type: string format: uuid description: The unique identifier of the subscription (UUIDv7). examples: - 0192f1a0-0000-7000-8000-00000000c001 name: type: string description: The human label supplied at create. examples: - orders-webhook sink_kind: $ref: '#/components/schemas/SinkKind' endpoint_display: type: string description: >- A short rendering of the destination: scheme and host for a `webhook`; the queue, exchange, or bus name for a queue sink; the `pull://` value unchanged. Empty when the stored destination cannot be parsed. Read the full destination with `GET /v1/subscriptions/{id}/endpoint`. examples: - https://hooks.example.com event_types: type: array description: >- The event types the subscription delivers. Omitted when none are pinned. items: type: string examples: - - account.created - account.updated origin: type: string description: >- The `ce-source` of a producing application. Omitted when none is set. examples: - ledger timeout_ms: type: integer description: >- The per-attempt delivery timeout in milliseconds. Omitted when every attempt uses the `10000` default. examples: - 20000 schema_major: type: integer description: The pinned schema major, when set. examples: - 1 event_majors: type: object additionalProperties: type: integer description: >- The schema major per event type that overrides `schema_major`. Omitted when none is set. signature_version: type: integer description: The webhook signature scheme version. examples: - 1 plan_tier: type: string description: The subscription's plan tier. examples: - standard enabled: type: boolean description: >- Whether delivery is enabled: `false` once auto-disable trips; `POST /v1/subscriptions/{id}/verify` re-enables it. Independent of `verification_state`; both must hold for delivery. examples: - true verification_state: $ref: '#/components/schemas/VerificationState' credential_kind: type: string enum: - signing_secret - static_credential - delegated_grant - none description: >- The credential the subscription delivers with: `signing_secret` (a webhook signing secret), `static_credential` (a stored queue credential), `delegated_grant` (a cross-account AWS role; nothing is stored or rotated), or `none`. examples: - signing_secret secret_configured: type: boolean description: >- Whether stored secret material is present: a signing secret, or a queue sink's stored delivery credential. The material itself is never returned. Read `credential_kind` for what the subscription delivers with. examples: - true secret_rotated_at: type: - string - 'null' format: date-time description: >- When the stored secret material was last replaced (UTC, RFC 3339). `null` when no secret is stored or the hub has no record of the time. examples: - '2026-01-15T12:00:00Z' secret_overlap_until: type: - string - 'null' format: date-time description: >- Until when the previous signing secret stays valid after a rotation (UTC, RFC 3339). `null` when no overlap window is open. A second rotation inside an open window replaces the previous secret and restarts the window. examples: - '2026-01-16T12:00:00Z' delegated_scope: type: string description: >- The Base64 delegated scope of the subscription. Omitted on a tenant-wide subscription. examples: - Rk9ORE8tQQ== created_at: type: string format: date-time description: Creation timestamp (UTC, RFC 3339). examples: - '2026-01-15T12:00:00Z' updated_at: type: string format: date-time description: Last-update timestamp (UTC, RFC 3339). examples: - '2026-01-15T12:00:00Z' required: - id - name - sink_kind - endpoint_display - signature_version - plan_tier - enabled - verification_state - credential_kind - secret_configured - secret_rotated_at - secret_overlap_until - created_at - updated_at Error: type: object description: >- RFC 9457 `application/problem+json` document. An error the hub raises carries `detail` and the stable `code` a client branches on; a request the framework rejects before the operation runs carries no `code`. properties: type: type: string format: uri description: >- A stable, versioned URI identifying the problem type (`https://errors.lerian.studio/v1/`). examples: - https://errors.lerian.studio/v1/not_found title: type: string description: A short human-readable summary — the HTTP status text. examples: - Not Found status: type: integer description: The HTTP status code, mirrored in the body. examples: - 404 detail: type: string description: A human explanation of this specific occurrence. examples: - subscription not found code: type: string description: >- The stable, low-cardinality, machine-readable token a client branches on (for example `not_found`, `unauthorized`, `idempotency_conflict`, `validation_error`). Absent when the framework rejects the request before the operation runs. examples: - not_found instance: type: string description: The trace id of the request, when the hub has one. examples: - 4bf92f3577b34da6a3ce929d0e0e4736 errors: type: array description: >- When present, the entries name what was refused. On `unknown_event_type`, each entry names one refused event type and its schema major. items: type: object properties: location: type: string description: The refused field, with its position in a list. examples: - event_types/2 message: type: string description: Why the hub refused the value. examples: - '"transaction.creatd" has no catalog entry at schema major 1' required: - title - status headers: RateLimitLimit: description: >- The requests this tenant may make in one window of this route's allowance. schema: type: integer examples: - 60 RateLimitRemaining: description: The requests left in the current window. `0` on a refusal. schema: type: integer examples: - 59 RateLimitReset: description: The Unix time, in seconds, at which the current window ends. schema: type: integer examples: - 1789499562 RetryAfter: description: The whole seconds to wait before a retry. Always at least `1`. schema: type: string examples: - '1' responses: Unauthorized: description: >- Authentication failed. `code` names the cause, for example `AUT-0006` (no token), `AUT-0007` (an expired, invalid, or malformed token), or `unauthorized` (no trusted tenant context). content: application/problem+json: schema: $ref: '#/components/schemas/Error' Forbidden: description: >- The caller is authenticated but is not allowed to make this request. `code` names the cause, for example `AUT-1020` (the credential does not have the permission; `detail` names the refused `resource:action`) or `forbidden`. content: application/problem+json: schema: $ref: '#/components/schemas/Error' ValidationError: description: A caller-correctable shape fault — `code` is `validation_error`. content: application/problem+json: schema: $ref: '#/components/schemas/Error' RateLimited: description: >- The tenant's allowance for this route is spent. `code` is `rate_limited`. Wait `Retry-After` seconds, then retry. Each tenant has three allowances: one for the catalog and the subscription list, detail, endpoint, health, and setup-artifacts reads; one for `GET /v1/events`; and one for the two dashboard routes. headers: Retry-After: $ref: '#/components/headers/RetryAfter' X-RateLimit-Limit: $ref: '#/components/headers/RateLimitLimit' X-RateLimit-Remaining: $ref: '#/components/headers/RateLimitRemaining' X-RateLimit-Reset: $ref: '#/components/headers/RateLimitReset' content: application/problem+json: schema: $ref: '#/components/schemas/Error' InternalError: description: >- An infrastructure fault. `code` is `internal_error` and `detail` is scrubbed to the static `"internal error"` (the cause is logged, never returned). On a mutation that requires `X-Idempotency`, `code` can instead be `idempotency_outcome_unrecorded`: the mutation may have committed, and its outcome was not recorded. Read the resource before you send anything again. content: application/problem+json: schema: $ref: '#/components/schemas/Error' MeteredServiceUnavailable: description: >- The hub cannot serve the request now. Branch on `code`. `AUT-0033`: Access Manager did not decide the request. `rate_limiter_unavailable`: the hub cannot check the tenant's allowance. `delegated_party_unconfirmed`, on `GET /v1/events` only: the hub cannot yet confirm the delegated party of the subscription. `read_timeout`, on the dashboard reads and the delivery-health read only: the read ran out of its time budget. Each is a transient condition, not a denial or a quota. Wait the `Retry-After` seconds, then retry; `read_timeout` carries no `Retry-After`. headers: Retry-After: $ref: '#/components/headers/RetryAfter' content: application/problem+json: schema: $ref: '#/components/schemas/Error' GatewayTimeout: description: >- Access Manager did not answer in time. `code` names the cause, for example `AUT-1021`. Retry the request. content: application/problem+json: schema: $ref: '#/components/schemas/Error' securitySchemes: BearerAuth: type: http scheme: bearer bearerFormat: JWT description: >- A bearer JWT issued by Access Manager. The `/v1` surface never reads a tenant from the body, path, or query. Machine callers obtain a token with the Access Manager client-credentials flow. The `/admin` surface authorizes against an operator scope and carries no tenant context. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.