API.stream Event API

asyncapi: 3.0.0
info:
  title: API.stream Event API
  version: '2.0'
  description: >-
    Event-driven view of the API.stream Event API. The Event API provides a bidirectional
    publish/subscribe channel between a partner's backend services, the compositor and connected
    clients, and also carries the events emitted by the Live API and Layout API. Subscriptions are
    scoped by target: an event published against a layoutId can be received by subscribers
    targeting that layoutId, its projectId, or its collectionId.


    Provenance: this document is GENERATED by the API Evangelist enrichment pipeline from the
    provider's own published Event API specification
    (openapi/lightstream-event-openapi-original.yml, harvested from
    https://www.api.stream/docs/api/event/rest/) plus the Event API documentation. Lightstream
    does not publish an AsyncAPI document of its own. Message payloads below are the provider's
    real Protobuf-derived schemas. Nothing here is invented; API.stream ships no HTTP webhooks —
    this is a long-lived stream, not a callback surface.
  externalDocs:
    url: https://www.api.stream/docs/api/event/
  contact:
    name: API.stream
    url: https://www.api.stream/
servers:
  production:
    host: live.api.stream
    pathname: /event/v2
    protocol: https
    description: REST/gRPC-Web gateway for the Event API. Native gRPC is also offered.
    security:
    - $ref: '#/components/securitySchemes/accessToken'
channels:
  stream:
    address: /stream
    title: Event stream
    description: >-
      Long-lived server stream (GET /event/v2/stream). The client sends subscribe, unsubscribe,
      publish and ping messages and receives events, acknowledgements, errors and reconnect
      directives. Every message may carry a correlationId which is echoed on the corresponding
      response or error.
    messages:
      eventsStreamResponse:
        $ref: '#/components/messages/eventsStreamResponse'
      subscribe:
        $ref: '#/components/messages/subscribe'
      unsubscribe:
        $ref: '#/components/messages/unsubscribe'
  publish:
    address: /publish
    title: Publish event
    description: >-
      Unary publish of a single custom event (POST /event/v2/publish), scoped to a collection,
      project or layout target.
    messages:
      publishEventRequest:
        $ref: '#/components/messages/publishEventRequest'
      publishEventResponse:
        $ref: '#/components/messages/publishEventResponse'
operations:
  publishEvent:
    action: send
    channel:
      $ref: '#/channels/publish'
    summary: Publish Event
    description: Publish a named, free-form event against a target scope.
    messages:
    - $ref: '#/channels/publish/messages/publishEventRequest'
  subscribeToEvents:
    action: receive
    channel:
      $ref: '#/channels/stream'
    summary: Stream Events
    description: >-
      Subscribe to an event name (exact, wildcard `my_service:*`, or alternation
      `my_event|my_other_event`) within a target scope and receive matching events.
    messages:
    - $ref: '#/channels/stream/messages/eventsStreamResponse'
components:
  securitySchemes:
    accessToken:
      type: httpApiKey
      name: Authorization
      in: header
      description: 'JWT access token asserted as ''Authorization: Bearer <access token>''.'
  messages:
    subscribe:
      name: SubscribePayload
      title: Subscribe
      payload:
        $ref: '#/components/schemas/subscribePayload'
    unsubscribe:
      name: SubscribePayload
      title: Unsubscribe
      payload:
        $ref: '#/components/schemas/subscribePayload'
    publishEventRequest:
      name: PublishEventRequest
      payload:
        $ref: '#/components/schemas/publishEventRequest'
    publishEventResponse:
      name: PublishEventResponse
      payload:
        $ref: '#/components/schemas/publishEventResponse'
    eventsStreamResponse:
      name: EventsStreamResponse
      title: Event stream response
      payload:
        $ref: '#/components/schemas/eventsStreamResponse'
  schemas:
    eventTarget:
      type: object
      description: >-
        Targeting for an event. Subscribers receive events for the chosen scope and any higher
        scope that is not itself targeted.
      properties:
        collectionId:
          type: string
          description: Subscribe to events in a given collection.
        projectId:
          type: string
          description: Subscribe to events in a given project.
        layoutId:
          type: string
          format: uuid
          description: >-
            Stream events to a specific layout. When specified, collection_id and project_id are
            implicitly defined; if supplied they must match the layout.
    subscribePayload:
      type: object
      required:
      - name
      properties:
        name:
          type: string
          description: >-
            Event name to subscribe to. May be a wildcard `my_service:*` or an alternation
            `my_event|my_other_event`.
        target:
          $ref: '#/components/schemas/eventTarget'
    publishEventRequest:
      type: object
      required:
      - name
      - payload
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 128
          description: Name of the event.
        payload:
          type: object
          description: Free-form value of the event; API.stream does not inspect it.
        requestMetadata:
          type: object
          description: Metadata about why the event happened.
        target:
          $ref: '#/components/schemas/eventTarget'
      examples:
      - name: my_app:user_chat
        payload:
          custom_event: true
        requestMetadata:
          example_data: true
        target:
          collectionId: 624c6f475887b2894ed87c89
          projectId: 624c6f465887b2894ed87c87
          layoutId: 713f6e91-3831-4421-a720-1c8084d10525
    publishEventResponse:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        payload:
          type: object
        requestMetadata:
          type: object
        target:
          $ref: '#/components/schemas/eventTarget'
    eventsStreamError:
      type: object
      description: >-
        Indicates an error with a message sent to the Event API. Tie correlationId on the request
        to correlationId on the parent response to identify the failing request.
      properties:
        code:
          type: integer
          format: int32
          description: The gRPC error code for the event.
        message:
          type: string
    eventsStreamReconnectRequest:
      type: object
      description: Instructs the client to re-open its connection.
      properties:
        reauthenticate:
          type: boolean
          description: Whether the access token must be refreshed before reconnecting.
        beforeTimestamp:
          type: string
          description: >-
            Timestamp by which the connection should be reconnected. Clients holding multiple
            connections should reconnect at a random interval within this range.
    eventsStreamResponse:
      type: object
      properties:
        correlationId:
          type: string
        sessionId:
          type: string
        event:
          $ref: '#/components/schemas/publishEventResponse'
        pong:
          type: string
        error:
          $ref: '#/components/schemas/eventsStreamError'
        subscribed:
          type: object
        unsubscribed:
          type: object
        published:
          type: object
        reconnectBefore:
          $ref: '#/components/schemas/eventsStreamReconnectRequest'