Streamsource is a publicly readable API to store and retrieve information about livestreams across many streaming platforms.
If you just want to use the API to read stream data found at streams.streamwall.io, see API Reference
Streamsource is in active development at a very early stage. Do not consider the API stable. We don't even have versioning yet! (we accept PRs!)
Many assumptions are built in, and this application is tightly coupled to a few different services. This will improve over time.
- Clone this repository
npm install- Install Postgres and create a database, a user, etc.
- Copy example.env to just .env and update your configuration settings
npx sequelize-cli db:migrate
- Make sure Postgres is running
- Start server:
node bin/www - Preview streams json: https://localhost:3000/streams
- Get new code:
git pull - Apply migrations:
npx sequelize-cli db:migrate - Restart server:
node bin/www
This project is in its infancy. We're open to pull requests and will work with you to get improvements merged.
Most routes are protected with a JWT that you must include in your Authorization header when making authenticated requests.
API tokens can be obtained by creating a user and POSTing to /users/login, which will generate and return a token.
Subsequent authenticated requests must include the following header:
Authorization: Bearer MYTOKEN
- Create your user
curl -d "[email protected]&password=abc123" -X POST https://localhost:3000/users/signup - Log in
curl -d "[email protected]&password=abc123" -X POST https://localhost:3000/users/login - Save the token in your app/script/bot's configuration file (keep it secret!)
Creates a new user
| Param | Description |
|---|---|
| This will be your login | |
| password | This will be your password |
curl -d "[email protected]&password=abc123" -X POST https://localhost:3000/users/signup
{
"message": "Signed up successfully",
"user": {
"role": "default",
"id": 7,
"email": "[email protected]",
"password": "REDACTED",
"updatedAt": "2020-09-25T06:38:05.045Z",
"createdAt": "2020-09-25T06:38:05.045Z"
}
}Authenticate in order to retrieve a long-lived JWT that can be used to make requests to other endpoints.
| Param | Description |
|---|---|
| The email address of a valid user | |
| password | The password of a valid user |
curl -d "[email protected]&password=abc123" -X POST https://localhost:3000/users/login
{
"token": "YOURTOKEN"
}Retrieves a list of streams with the ability to filter results
Note: All string searches are case-insensitive and queried based on ILIKE '%YOURSEARCHTERM%'
| Param | Type | Description |
|---|---|---|
| source | String | The name of a stream or streamer |
| notSource | String | The name of a stream or streamer to exclude |
| platform | String | The name of a streaming platform (e.g., "Facebook", "Twitch") |
| notPlatform | String | The name of a platform to exclude |
| link | String | The URL of a stream |
| status | String | One of: ['Live', 'Offline', 'Unknown'] |
| notStatus | String | Exclude this status. One of: ['Live', 'Offline', 'Unknown'] |
| isPinned | Boolean | Defaults to null. When true, prevents state changes, e.g. updates to isExpired or status |
| isExpired | Boolean | Streams are considered expired when they are no longer active. Default: false |
| title | String | Title of a stream |
| notTitle | String | Title of a stream |
| postedBy | String | Name of the person who submitted the link |
| notPostedBy | String | Name of a person to exclude |
| city | String | Name of a city |
| notCity | String | Name of a city to exclude |
| region | String | Name of a region (e.g., state, country, province) |
| notRegion | String | Name of a region (e.g., state, country, province) to exclude |
| orderFields | String, CSV | CSV of fields to order by. Must be accompanied by an orderDirection for each field |
| orderDirections | String, CSV | CSV of directions to order by. One per orderField, respectively |
| format | String | Currently only accepts "array" or null; returns a raw array of streams for Streamwall if set to array, otherwise it's formatted like { data: [ {...}, {...} ] } |
Get all active streams in Seattle
curl https://localhost:3000/streams?city=seattle
[
{
"id": 1,
"source": "future_crystals",
"platform": "Instagram",
"link": "https://www.instagram.com/future_crystals/live",
"status": "Live",
"title": "",
"isPinned": false,
"isExpired": false,
"checkedAt": "2020-09-25T04:58:52.840Z",
"liveAt": "2020-09-25T04:58:52.840Z",
"embedLink": "https://www.instagram.com/future_crystals/live",
"postedBy": "someuser",
"city": "Seattle",
"region": "WA",
"createdAt": "2020-09-25T04:58:52.840Z",
"updatedAt": "2020-09-25T04:58:52.840Z"
}
]Create a new stream.
- Requires authentication
- Requires privileged role: Editor or Admin
curl -d "link=https://someurl.com&city=Seattle®ion=WA" -X POST https://localhost:3000/streams --header 'Authorization: Bearer MYTOKEN'
{
"id": 1,
"source": "future_crystals",
"platform": "Instagram",
"link": "https://www.instagram.com/future_crystals/live",
"status": "Live",
"title": "",
"isPinned": false,
"isExpired": false,
"checkedAt": "2020-09-25T04:58:52.840Z",
"liveAt": "2020-09-25T04:58:52.840Z",
"embedLink": "https://www.instagram.com/future_crystals/live",
"postedBy": "someuser",
"city": "Seattle",
"region": "WA",
"createdAt": "2020-09-25T04:58:52.840Z",
"updatedAt": "2020-09-25T04:58:52.840Z"
}Get details for a single stream
curl https://localhost:3000/streams/1
{
"id": 1,
"source": "future_crystals",
"platform": "Instagram",
"link": "https://www.instagram.com/future_crystals/live",
"status": "Live",
"title": "",
"isPinned": false,
"isExpired": false,
"checkedAt": "2020-09-25T04:58:52.840Z",
"liveAt": "2020-09-25T04:58:52.840Z",
"embedLink": "https://www.instagram.com/future_crystals/live",
"postedBy": "someuser",
"city": "Seattle",
"region": "WA",
"createdAt": "2020-09-25T04:58:52.840Z",
"updatedAt": "2020-09-25T04:58:52.840Z"
}Update a new stream.
- Requires authentication
- Requires privileged role: Editor or Admin
curl -d "status=Offline" -X POST https://localhost:3000/streams/1 --header 'Authorization: Bearer MYTOKEN'
{
...
"status": "Offline",
...
}Expire a stream
- Requires authentication
- Requires privileged role: Editor or Admin
curl -X DELETE https://localhost:3000/streams/1 --header 'Authorization: Bearer MYTOKEN'
{
...
"isExpired": true,
...
}Pin a stream; prevents state changes while pinned
- Requires authentication
- Requires privileged role: Editor or Admin
curl -X PUT https://localhost:3000/streams/1/pin --header 'Authorization: Bearer MYTOKEN'
{
...
"isPinned": true,
...
}Unpin a stream
- Requires authentication
- Requires privileged role: Editor or Admin
curl -X PUT https://localhost:3000/streams/1/pin --header 'Authorization: Bearer MYTOKEN'
{
...
"isPinned": false,
...
}