openapi: 3.2.0
info:
  title: Event Service API
  version: '2.0'
  description: 'The event API provides a mechanism for you to subscribe and publish events between

    your backend services and the composition, as well as receive events from the live and layout api.'
servers:
- url: https://live.api.stream/event/v2
tags:
- name: Event Service
  description: 'The event API provides a mechanism for you to subscribe and publish events between

    your backend services and the composition, as well as receive events from the live and layout api.'
paths:
  /publish:
    post:
      summary: Publish Event
      operationId: EventService_Publish
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/v2PublishEventResponse'
        '404':
          description: Layout not found
          content:
            application/json:
              schema: {}
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/rpcStatus'
      tags:
      - Event Service
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/v2PublishEventRequest'
        required: true
  /stream:
    get:
      summary: Stream Events
      operationId: EventService_Stream
      responses:
        '200':
          description: A successful response.(streaming responses)
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    $ref: '#/components/schemas/v2EventsStreamResponse'
                  error:
                    $ref: '#/components/schemas/rpcStatus'
                title: Stream result of v2EventsStreamResponse
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/rpcStatus'
      parameters:
      - name: correlationId
        description: 'Optional value to tag any return values with. This can be any string-based value

          that your are able to track.'
        in: query
        required: false
        schema:
          type: string
      - name: subscribe.name
        description: 'Event name to subscribe to for custom events.

          This can be a wildcard `my_service:*` or multiple events `my_event|my_other_event`.'
        in: query
        required: true
        schema:
          type: string
      - name: subscribe.target.collectionId
        description: Subscribe to events in a given collection.
        in: query
        required: false
        schema:
          type: string
      - name: subscribe.target.projectId
        description: Subscribe to events in a given project.
        in: query
        required: false
        schema:
          type: string
      - name: subscribe.target.layoutId
        description: 'Stream events to a specific layout.

          Note: when specified, collection_id and project_id are implictly defined. If you choose

          to define them, you they _must_ match the layout.'
        in: query
        required: false
        schema:
          type: string
          format: uuid
      - name: unsubscribe.name
        description: 'Event name to subscribe to for custom events.

          This can be a wildcard `my_service:*` or multiple events `my_event|my_other_event`.'
        in: query
        required: true
        schema:
          type: string
      - name: unsubscribe.target.collectionId
        description: Subscribe to events in a given collection.
        in: query
        required: false
        schema:
          type: string
      - name: unsubscribe.target.projectId
        description: Subscribe to events in a given project.
        in: query
        required: false
        schema:
          type: string
      - name: unsubscribe.target.layoutId
        description: 'Stream events to a specific layout.

          Note: when specified, collection_id and project_id are implictly defined. If you choose

          to define them, you they _must_ match the layout.'
        in: query
        required: false
        schema:
          type: string
          format: uuid
      - name: publish.name
        description: Name of the event.
        in: query
        required: true
        schema:
          type: string
      - name: publish.target.collectionId
        description: Subscribe to events in a given collection.
        in: query
        required: false
        schema:
          type: string
      - name: publish.target.projectId
        description: Subscribe to events in a given project.
        in: query
        required: false
        schema:
          type: string
      - name: publish.target.layoutId
        description: 'Stream events to a specific layout.

          Note: when specified, collection_id and project_id are implictly defined. If you choose

          to define them, you they _must_ match the layout.'
        in: query
        required: false
        schema:
          type: string
          format: uuid
      - name: ping
        description: Initiate a ping-pong message.
        in: query
        required: false
        schema:
          type: string
      tags:
      - Event Service
components:
  schemas:
    v2PublishEventRequest:
      type: object
      properties:
        name:
          type: string
          example: my_app:user_chat
          description: Name of the event.
          maxLength: 128
          minLength: 1
          required:
          - name
        payload:
          type: object
          example:
            custom_event: true
          description: Value of the event. This can be a free-form value which we do not inspect.
          required:
          - payload
        requestMetadata:
          type: object
          example:
            example_data: true
          description: 'Metadata associated with the publishing of the event.

            Typically this is information about _why_ the event happened. Use `payload` for

            _what_ the event is.'
        target:
          $ref: '#/components/schemas/v2EventTarget'
          title: Scope the event to a specific target
      title: Publish a custom event
      required:
      - name
      - payload
    rpcStatus:
      type: object
      properties:
        code:
          type: integer
          format: int32
        message:
          type: string
        details:
          type: array
          items:
            $ref: '#/components/schemas/protobufAny'
    v2EventsStreamError:
      type: object
      properties:
        code:
          type: integer
          format: int32
          example: 13
          description: The GRPC error code for the event.
        message:
          type: string
          example: 'INTERNAL: Something went wrong'
          description: A mesasage indicating what the error is.
      description: 'Indicates an error with a message sent to the Event API.

        Tie `correlation_id` on the message sent to the Event API and the `correlation_id`

        on the parent message to understand which request this error is for.'
    v2SubscribePayload:
      type: object
      properties:
        name:
          type: string
          example: my_app:user_chat|other_events:*
          description: 'Event name to subscribe to for custom events.

            This can be a wildcard `my_service:*` or multiple events `my_event|my_other_event`.'
          maxLength: 128
          minLength: 1
          required:
          - name
        target:
          $ref: '#/components/schemas/v2EventTarget'
          description: The target to subscribe to.
      title: Payload to subscribe or unsubscribe from an event
      required:
      - name
    v2PublishEventResponse:
      type: object
      properties:
        name:
          type: string
          example: my_app:user_chat
          description: Name of the event.
          maxLength: 128
          minLength: 1
          required:
          - name
        payload:
          type: object
          example:
            custom_event: true
          description: Value of the event.
          required:
          - payload
        target:
          $ref: '#/components/schemas/v2EventTarget'
          description: Custom scoping parameters.
        requestMetadata:
          type: object
          example:
            example_data: true
          title: Metadata associated with the publishing of the event
        id:
          type: string
          format: uuid
          example: 7f23f76c-1990-4a50-b3b9-d615703c777f
          description: Internal ID of the event.
      description: 'Response of an event being forwarded to a subscription.

        note: if this socket is also the publisher, this payload will be

        sent twice. Once for `published` and once for `event`. You can use `correlation_id`

        to identify the published event.'
      required:
      - name
      - payload
    v2EventsStreamReconnectRequest:
      type: object
      properties:
        reauthenticate:
          type: boolean
          example: false
          description: Whether the access token needs to be refreshed before reconnecting.
          required:
          - reauthenticate
        beforeTimestamp:
          type: string
          example: '1649179486223'
          description: 'A timestamp indicating when the connection should be reconnected by.

            If you''re maintaining multiple connections, you should reconnect at a random interval within this time range.'
          required:
          - before_timestamp
      title: Indicate to the client that they should re-open their connection
      required:
      - reauthenticate
      - beforeTimestamp
    v2EventTarget:
      type: object
      properties:
        collectionId:
          type: string
          example: 624c6f475887b2894ed87c89
          description: Subscribe to events in a given collection.
        projectId:
          type: string
          example: 624c6f465887b2894ed87c87
          description: Subscribe to events in a given project.
        layoutId:
          type: string
          format: uuid
          example: 713f6e91-3831-4421-a720-1c8084d10525
          description: 'Stream events to a specific layout.

            Note: when specified, collection_id and project_id are implictly defined. If you choose

            to define them, you they _must_ match the layout.'
      description: 'Targetting for an event

        Event targetting allows you to listen or publish an event against a specific target. You can assume that:

        When subscribing, you will receive events for the chosen scope and any higher scope that isn''t targetted. This means

        - An event published against a layoutId can be listened to by targetting the given layoutId, projectId or collectionId

        - An event published against a collectionId can be subscribed by scoping to any given projectId or layoutId under the collection.'
    v2EventsStreamResponse:
      type: object
      properties:
        correlationId:
          type: string
          example: 7a59c49f-c0bb-4f94-9cbe-73af126dd1ea
          title: 'Optional value to tag any return values with.

            Correlation ID should be used to correlate requests sent down the socket,

            enabling you to tie a `PUBLISH` to a `PUBLISHED``'
        sessionId:
          type: string
          example: 0c596f1b-3428-47bb-a673-563211ca0c75
          description: 'Optional session id

            This is set by sending the `SessionId` header for any HTTP requests

            and the `sessionId` query parameter for websockets.'
        event:
          $ref: '#/components/schemas/v2PublishEventResponse'
          title: Custom event emitted
        pong:
          type: string
          title: Ping payload
        error:
          $ref: '#/components/schemas/v2EventsStreamError'
          title: Non-blocking streaming error
        subscribed:
          $ref: '#/components/schemas/v2SubscribePayload'
          description: Subscribe to a new event.
        unsubscribed:
          $ref: '#/components/schemas/v2SubscribePayload'
          description: Unsubscribe from an event.
        published:
          $ref: '#/components/schemas/v2PublishEventResponse'
          description: Publish a new event.
        reconnectBefore:
          $ref: '#/components/schemas/v2EventsStreamReconnectRequest'
          description: Inform the client should reoconnect before a timestamp.
      description: Payload returned from the event API.
    protobufAny:
      type: object
      properties:
        '@type':
          type: string
      additionalProperties: {}