streaming.md 2.35 KB
Newer Older
1 2
---
title: Streaming API
3
description: How to use Mastodon's streaming API for live, real-time updates
4 5 6 7 8 9 10 11 12 13
menu:
  docs:
    parent: api
    weight: 4
---

Your application can use a [server-sent events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events) endpoint to receive updates in real-time. Server-sent events is an incredibly simple transport method that relies entirely on chunked-encoding transfer, i.e. the HTTP connection is kept open and receives new data periodically.

Alternatively, a WebSocket connection can also be established.

Eugen Rochko's avatar
Eugen Rochko committed
14
## Server-sent events (HTTP)
15 16
### Endpoints

17
    GET /api/v1/streaming/user
18 19 20

Returns events that are relevant to the authorized user, i.e. home timeline and notifications

21
    GET /api/v1/streaming/public
22 23 24

Returns all public statuses

25
    GET /api/v1/streaming/public/local
26 27 28

Returns all local statuses

29
    GET /api/v1/streaming/hashtag?tag={id}
30

31
Returns all public statuses for a particular hashtag
32

33
    GET /api/v1/streaming/hashtag/local?tag={id}
34

35
Returns all local statuses for a particular hashtag
36

37
    GET /api/v1/streaming/list?list={id}
38

39
Returns statuses for a list
40

41
    GET /api/v1/streaming/direct
42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71

Returns all direct messages

### Stream contents

The stream will contain events as well as heartbeat comments. Lines that begin with a colon (`:`) can be ignored by parsers, they are simply there to keep the connection open. Events have this structure:

```
event: name
data: payload
```

## WebSocket

For WebSockets, there is only one URL path (`/api/v1/streaming`). The access token as well as the endpoint you are interested in must be provided with query params, respectively `access_token` and `stream`. Query params `list` and `tag` are likewise supported for relevant endpoints.

Possible `stream` values:

- `user`
- `public`
- `public:local`
- `hashtag`
- `hashtag:local`
- `list`
- `direct`

## Event types

|Event|Description|What's in the payload|
|-----|-----------|---------------------|
72 73
|`update`|A new status has appeared|[Status]({{< relref "entities.md#status" >}})|
|`notification`|A new notification has appeared|[Notification]({{< relref "entities.md#notification" >}})|
74 75 76 77 78 79
|`delete`|A status has been deleted|ID of the deleted status|
|`filters_changed`|Keyword filters have been changed||

The payload is JSON-encoded.

> **Note:** In case of `filters_changed` event, `payload` is not defined.