2

event

Interitio edited this page 2025-06-18 23:44:51 +10:00

Table of Contents

• Event
• Fields
• PlainEvent
• SubEvent
• CheerEvent
• RaidEvent
• Routes
• Examples
• Get sub events from a given user
• Create a message event, then add a stamp
• Remove stamps from an event document

Event

An Event represents event data for one of the saved events. This will typically have a Document attached with image data saved from the event. Events may also be created without documents, in which case the document and document_id fields will be null.

There are four types of events ('PlainEvent', 'SubEvent', 'CheerEvent', 'RaidEvent'), identified by their event_type field. The API will only ever accept or return these four concrete types, and never the abstract Event type. However, the abstraction is useful since multi-value endpoints such as GET /events will return a combination of these concrete types, which we shall just refer to as Events.

Fields

field	type	required	description
event_id	integer	-	UID for this event
document_id	integer?	-	UID of the associated document, if it exists.
document	Document?	no	Associated Document, if it exists.
user_id	integer	yes	(Internal) UID of the user which triggered this event.
user	User	no	User which triggered this event.
user_name	string?	yes	Name of the user when they triggered this event.
occurred_at	timestamp	yes	When this event originally occurred. Will typically be earlier than created_at
created_at	timestamp	-	When this event was created. Automatically set on creation.
event_type	string in EventType	yes	Type of the event. Must be one of the event types.

Allowed and possible values for EventType are plain, subscriber, cheer, raid. The event_type must be specified when creating an event (you cannot create a base Event, only one of the following four event types).

PlainEvent

An Event of type plain has the following further fields.

field	type	required	description
message	string	yes	Message for this event.

SubEvent

An Event of type subscriber has the following further fields.

field	type	required	description
tier	integer	yes	Tier of the subscription.
subscribed_length	integer	yes	Subscription length (not sure what the unit is?)
message	string?	no	Subscription message.

• What is the unit of subscribed_length? Is it cumulative? Does it make any sense to have subscription_start for the start of the current subscription?
• message was not in the original spec, does it make sense to add?

CheerEvent

An Event of type cheer has the following further fields.

field	type	required	description
amount	integer	yes	Number of bits cheered
cheer_type	string?	no	Type of cheer
message	string?	no	Message associated with the bit cheer.

• type was not in the original spec, does it make sense? message as well.

RaidEvent

An Event of type raid has the following further fields.

field	type	required	description
viewer_count	integer	yes	Number of viewers who came with the raid.

Routes

• POST /events

  • Create a return a new Event.
  • The event_type must be specified, and the additional fields for that event type should be considered.
  • The document should be specified in the form of a Document (as in POST /documents), however, may be specified as a document_id instead to attach to an existing document.
  • The user may be specified in the form of a User (as in POST /user), in which case user_id is not required and will be filled from the created User.
    • Supplying both user_id and user is not supported.
    • If a user already exists with the given twitch_id, then that user will instead be updated with the given fields, and the user_id of the existing user will be used to create the Event. This behaviour is distinct to the POST /users endpoint which will error if the user already exists.

• GET /events

  • Returns events matching the provided filters.
  • Intended to be the typical way of retrieving events and documents.
  • Supported filter parameters:
    • event_id
    • document_id
    • document_seal - Filter by document seal
    • user_id
    • user_name
    • occurred_before
    • occurred_after
    • created_before
    • created_after
    • event_type

• GET /events/{event_id}

  • Returns an Event with the given event_id.

• PATCH /events/{event_id}

  • Updates and returns the given Event.
  • Supports updating all added fields in the relevant event type.
  • Does not support updating any of the base event fields.

• DELETE /events/{event_id}

  • Delete and return the given Event
  • Note this will also delete the associated Document.

• * /events/{event_id}/document

  • If the action is POST, will create and return a Document for this event.
  • Otherwise inherits the /documents/{document_id} route with the associated document_id.
    • If there is no document associated, will raise Not Found.

• * /events/{event_id}/user

  • Inherits the /users/{user_id} route with the associated user_id.

• It might make sense to add the subtype fields for filtering as well

Examples

Get sub events from a given user

Create a message event, then add a stamp

Remove stamps from an event document