streaming.md 2.28 KB
Newer Older
1 2 3 4 5 6 7 8 9 10 11 12
---
title: Streaming API
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
13
## Server-sent events (HTTP)
14 15
### Endpoints

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

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

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

Returns all public statuses

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

Returns all local statuses

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

30
Returns all public statuses for a particular hashtag
31

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

34
Returns all local statuses for a particular hashtag
35

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

38
Returns statuses for a list
39

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.