mirror of
https://github.com/mastodon/documentation
synced 2025-04-11 22:56:17 +02:00
79 lines
2.2 KiB
Markdown
79 lines
2.2 KiB
Markdown
---
|
|
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.
|
|
|
|
## Server-sent events (HTTP)
|
|
### Endpoints
|
|
|
|
**GET /api/v1/streaming/user**
|
|
|
|
Returns events that are relevant to the authorized user, i.e. home timeline and notifications
|
|
|
|
**GET /api/v1/streaming/public**
|
|
|
|
Returns all public statuses
|
|
|
|
**GET /api/v1/streaming/public/local**
|
|
|
|
Returns all local statuses
|
|
|
|
**GET /api/v1/streaming/hashtag**
|
|
|
|
Returns all public statuses for a particular hashtag (query param `tag`)
|
|
|
|
**GET /api/v1/streaming/hashtag/local**
|
|
|
|
Returns all local statuses for a particular hashtag (query param `tag`)
|
|
|
|
**GET /api/v1/streaming/list**
|
|
|
|
Returns statuses for a list (query param `list`)
|
|
|
|
**GET /api/v1/streaming/direct**
|
|
|
|
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|
|
|
|-----|-----------|---------------------|
|
|
|`update`|A new status has appeared!|Status|
|
|
|`notification`|A new notification|Notification|
|
|
|`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.
|