streaming.md 2.37 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
### Endpoints
Eugen Rochko's avatar
Eugen Rochko committed
16
#### GET /api/v1/streaming/user
17 18 19

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

Eugen Rochko's avatar
Eugen Rochko committed
20
#### GET /api/v1/streaming/public
21 22 23

Returns all public statuses

Eugen Rochko's avatar
Eugen Rochko committed
24
#### GET /api/v1/streaming/public/local
25 26 27

Returns all local statuses

Eugen Rochko's avatar
Eugen Rochko committed
28
#### GET /api/v1/streaming/hashtag?tag=:hashtag
29

30
Returns all public statuses for a particular hashtag
31

Eugen Rochko's avatar
Eugen Rochko committed
32
#### GET /api/v1/streaming/hashtag/local?tag=:hashtag
33

34
Returns all local statuses for a particular hashtag
35

Eugen Rochko's avatar
Eugen Rochko committed
36
#### GET /api/v1/streaming/list?list=:list_id
37

38
Returns statuses for a list
39

Eugen Rochko's avatar
Eugen Rochko committed
40
#### GET /api/v1/streaming/direct
41 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

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|
|-----|-----------|---------------------|
71 72
|`update`|A new status has appeared|[Status]({{< relref "entities.md#status" >}})|
|`notification`|A new notification has appeared|[Notification]({{< relref "entities.md#notification" >}})|
73 74 75 76 77 78
|`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.