2020-07-30 02:55:33 -05:00
# Using Satyr's Rest API
2020-07-29 03:24:19 -05:00
2020-07-30 02:55:33 -05:00
## /api/instance/info
2020-07-29 03:24:19 -05:00
Generic enformation about the instance.
2020-07-30 02:55:33 -05:00
**Method**: GET
2020-07-29 03:24:19 -05:00
2020-07-30 02:55:33 -05:00
**Authentication**: no
2020-07-29 03:24:19 -05:00
2020-07-30 02:55:33 -05:00
**Parameters**: none
2020-07-29 03:24:19 -05:00
2020-07-30 02:55:33 -05:00
**Response**: Returns a JSON object containing the name, domain, version, email, and whether registration is open. Email will be null if not specified.
2020-07-29 03:24:19 -05:00
2020-07-30 02:55:33 -05:00
**Example**: `{name: "Example Instance", domain: "example.com", registration: false, version: 0.7, email: null}`
2020-07-29 03:24:19 -05:00
2020-07-30 02:55:33 -05:00
## /api/instance/config
2020-07-29 03:24:19 -05:00
Configuration of the instance relating to media
2020-07-30 02:55:33 -05:00
**Method**: GET
2020-07-29 03:24:19 -05:00
2020-07-30 02:55:33 -05:00
**Authentication**: no
2020-07-29 03:24:19 -05:00
2020-07-30 02:55:33 -05:00
**Parameters**: none
2020-07-29 03:24:19 -05:00
2020-10-18 02:16:54 -05:00
**Response**: JSON object containing the port and ping_timeout for RTMP, whether clustering is enabled, public and private play endpoints, and whether adaptive livestreaming and VOD recording are enabled.
2020-07-29 03:24:19 -05:00
2020-07-30 02:55:33 -05:00
**Example**:
2020-07-29 03:24:19 -05:00
```
{
rtmp: {
2020-10-17 22:08:56 -05:00
cluster: false,
2020-07-29 03:24:19 -05:00
port: 1935,
ping_timeout: 60
},
media: {
vods: false,
publicEndpoint: 'live',
privateEndpoint: 'stream',
adaptive: true
}
}
```
2020-07-30 02:55:33 -05:00
2020-07-29 03:24:19 -05:00
Public and private endpoints work like this, from the above example:
2020-07-30 02:55:33 -05:00
2020-07-29 03:24:19 -05:00
stream to: rtmp://example.com/stream
2020-07-30 02:55:33 -05:00
play from: rtmp://example.com/live/username or https://example.com/live/username/index.mpd
2020-07-29 03:24:19 -05:00
2020-07-30 02:55:33 -05:00
## /api/users/live/
2020-07-30 00:45:08 -05:00
2020-07-29 03:24:19 -05:00
Returns the usernames and stream titles of 10 users who are currently streaming
2020-07-30 02:55:33 -05:00
**Method**: POST
**Authentication**: no
**Parameters**: num (optional), sort (optional), page (optional)
2020-07-29 03:24:19 -05:00
2020-07-30 02:55:33 -05:00
number is the number of results (maximum is 50)
2020-07-29 03:24:19 -05:00
2020-07-30 02:55:33 -05:00
sort is the optional way to sort results. current options are "alphabet" and "alphabet-r" (reversed)
2020-07-29 03:24:19 -05:00
2020-07-30 02:55:33 -05:00
page is the page number (i.e. skip the first num * page results)
2020-07-29 03:24:19 -05:00
2020-10-18 02:16:54 -05:00
**Response**: Returns an array of JSON objects containing the username and title of each stream. Returns an empty array if no one is streaming. Returns `{"error":"error reason"}` in the event of an error. Will attempt to correct malformed requests to default values.
2020-07-29 03:24:19 -05:00
2020-08-03 05:01:20 -05:00
The array will be wrapped in a JSON object under the key 'users'.
**Example**: `{users: [{username:"foo", title:"bar"}] }`
2020-07-29 03:24:19 -05:00
2020-07-30 02:55:33 -05:00
## /api/users/all
2020-07-29 03:24:19 -05:00
2020-10-18 02:16:54 -05:00
Same as above, but returns all users regardless of whether they are streaming and if they're streaming or not. Also returns a value 'live' indicating whether a user is currently streaming.
2020-08-24 11:14:26 -05:00
**Example**: `{users: [{username:"foo", title:"bar", live:1}] }`
2020-07-29 03:24:19 -05:00
2020-07-30 02:55:33 -05:00
## /api/register
2020-07-29 03:24:19 -05:00
Register a new user.
2020-07-30 02:55:33 -05:00
**Method**: POST
2020-07-29 03:24:19 -05:00
2020-07-30 02:55:33 -05:00
**Authentication**: no
2020-07-29 03:24:19 -05:00
2020-10-13 16:16:37 -05:00
**Parameters**: Username, password, confirm, invite(optional)
Invite is an optional invite code to bypass disabled registration.
2020-07-29 03:24:19 -05:00
2020-07-30 02:55:33 -05:00
**Response**: If successful, returns a json object with the users stream key. Otherwise returns `{error: "error reason"}`
2020-07-29 03:24:19 -05:00
2020-07-30 02:55:33 -05:00
**Examples**:
2020-07-29 03:24:19 -05:00
`{stream_key: "asdfghjkltyuiop12345"}`
2020-07-30 02:55:33 -05:00
2020-07-29 03:24:19 -05:00
`{error: "registration disabled"}`
2020-07-30 02:55:33 -05:00
## /api/login
2020-07-29 03:24:19 -05:00
Obtain a signed json web token for authentication
2020-07-30 02:55:33 -05:00
**Method**: POST
2020-07-29 03:24:19 -05:00
2020-07-30 02:55:33 -05:00
**Authentication**: no
2020-07-29 03:24:19 -05:00
2020-07-30 02:55:33 -05:00
**Parameters**: Username and password OR a valid JWT cookie expiring in less than 24 hours
2020-07-29 03:24:19 -05:00
2020-07-30 02:55:33 -05:00
**Response**: If succesful, will return `{success: ""}` or `{success: "already verified"}` if the JWT provided is too early to be renewed. If unsuccesful, will return `{error: "invalid password"}` or `{error: "Username or Password Incorrect"}` depending on the authentication method. Note that if a JWT is available, the parameters will be ignored.
2020-07-29 03:24:19 -05:00
2020-10-16 22:25:24 -05:00
**Notes**: The returned JWT is set as the cookie httponly 'Authorization'. It will also return a non httponly cookie X-Auth-As with the username of the authenticated user.
2020-07-29 03:24:19 -05:00
2020-07-30 02:55:33 -05:00
## /api/user/update
2020-07-29 03:24:19 -05:00
Update the current user's information
2020-07-30 02:55:33 -05:00
**Method**: POST
**Authentication**: yes
2020-07-29 03:24:19 -05:00
2020-10-12 12:12:27 -05:00
**Parameters**: title, bio, rec, twitch, twitch_key
2020-07-29 03:24:19 -05:00
2020-10-12 12:12:27 -05:00
Rec is a boolean (whether to record VODs), twitch is a boolean (whether to mirror video streams to twitch) others are strings. Twitch_key is the stream key to use for twitch. Parameters that are not included in the request will not be updated.
2020-07-29 03:24:19 -05:00
2020-10-18 02:16:54 -05:00
**Response**: Returns `{error: "error reason"}` or `{success: ""}`
2020-07-29 03:24:19 -05:00
2020-07-30 02:55:33 -05:00
## /api/user/update/chat
2020-07-29 03:24:19 -05:00
Update the chatrooms on other platforms to integrate with the user's stream chat
2020-07-30 02:55:33 -05:00
**Method**: POST
2020-07-29 03:24:19 -05:00
2020-07-30 02:55:33 -05:00
**Authentication**: yes
2020-07-29 03:24:19 -05:00
2020-07-30 02:55:33 -05:00
**Parameters**: discord, xmpp, twitch irc
2020-07-29 03:24:19 -05:00
2020-10-18 02:16:54 -05:00
Strings corresponding to a channel name to mirror to. Parameters not included in the request will not be updated.
2020-07-29 03:24:19 -05:00
2020-10-18 02:16:54 -05:00
**Response**: Returns `{error: "error reason"}` or `{success: ""}`
2020-07-29 03:24:19 -05:00
2020-07-30 02:55:33 -05:00
## /api/user/vods/delete
2020-07-29 03:24:19 -05:00
Delete the specified vods of the current user
2020-07-30 02:55:33 -05:00
**Method:** POST
2020-07-29 03:24:19 -05:00
2020-07-30 02:55:33 -05:00
**Authentication**: yes
2020-07-29 03:24:19 -05:00
2020-10-18 02:16:54 -05:00
**Paramters**: A string array of the names of vods to be deleted. (Do not include the file extension)
2020-07-29 03:24:19 -05:00
2020-10-18 02:16:54 -05:00
**Response**: Returns `{error: "error reason"}` or `{success: ""}`
2020-07-29 03:24:19 -05:00
2020-07-30 02:55:33 -05:00
## /api/user/password
2020-07-29 03:24:19 -05:00
Change the current user's password
2020-07-30 02:55:33 -05:00
**Method**: POST
2020-07-29 03:24:19 -05:00
2020-07-30 02:55:33 -05:00
**Authentication**: yes
2020-07-29 03:24:19 -05:00
2020-07-30 02:55:33 -05:00
**Parameters**: The user's current password, the new password, AND a valid JWT cookie.
2020-07-29 03:24:19 -05:00
2020-10-18 02:16:54 -05:00
**Response**: Returns `{error: "error reason"}` or `{success: ""}`
2020-07-29 03:24:19 -05:00
2020-07-30 02:55:33 -05:00
## /api/user/streamkey
2020-07-29 03:24:19 -05:00
Change the current user's stream key. This will not affect the stream if the user is currently live.
2020-07-30 02:55:33 -05:00
**Method**: POST
**Authentication**: yes
**Parameters**: A valid JWT cookie. No other parameters.
2020-07-29 03:24:19 -05:00
2020-10-18 02:16:54 -05:00
**Response**: Returns `{error: "error reason"}` or `{success: "new_stream_key"}`
2020-07-29 03:24:19 -05:00
2020-07-30 02:55:33 -05:00
## /api/:user/vods
2020-07-29 03:24:19 -05:00
Get a list of the named users VODs
2020-07-30 02:55:33 -05:00
**Method**: GET
2020-07-29 03:24:19 -05:00
2020-07-30 02:55:33 -05:00
**Authentication**: no
2020-07-29 03:24:19 -05:00
2020-07-30 02:55:33 -05:00
**Parameters**: user
2020-07-29 03:24:19 -05:00
2020-08-03 05:01:20 -05:00
**Response**: Returns an array of VODs inside a JSON object with the format `{"vods": [{"name":"yote.mp4"},{"name":"yeet.mp4"}] }`
2020-07-29 03:24:19 -05:00
2020-10-18 02:16:54 -05:00
**Notes**: VODs are always available at http://domain/publicEndpoint/username/filename
2020-07-29 03:40:53 -05:00
2020-07-30 02:55:33 -05:00
## /api/:user/config
2020-07-30 01:34:22 -05:00
Get information about the specified user.
2020-07-29 03:40:53 -05:00
2020-07-30 02:55:33 -05:00
**Method**: GET
2020-07-29 03:40:53 -05:00
2020-07-30 02:55:33 -05:00
**Authentication**: optional
2020-07-29 03:40:53 -05:00
2020-07-30 02:55:33 -05:00
**Parameters**: user
2020-07-29 03:40:53 -05:00
2020-10-18 02:16:54 -05:00
**Response**: Returns a JSON object with available information about the user. If the user is authenticated and searching for their own information, will return all available information. Otherwise it will return only the stream title, bio, and whether the stream is live. In the case of searching for a user that does not exist, the returned object will contain only the username searched for.
2020-07-29 03:40:53 -05:00
2020-10-18 02:16:54 -05:00
**Example**: `{username: "foo", title: "bar", about: "This is an example bio", live: 0}`
2020-07-29 03:40:53 -05:00
2020-07-30 00:45:08 -05:00
2020-07-30 02:55:33 -05:00
## /api/user/streamkey/current
2020-07-30 00:45:08 -05:00
2020-07-30 02:55:33 -05:00
Returns the current stream key for the authenticated user.
2020-07-30 01:34:22 -05:00
2020-07-30 02:55:33 -05:00
**Method**: GET
2020-07-30 01:34:22 -05:00
2020-07-30 02:55:33 -05:00
**Authentication**: yes
2020-07-30 01:34:22 -05:00
2020-07-30 02:55:33 -05:00
**Parameters**: none
2020-07-30 01:34:22 -05:00
2020-07-30 02:55:33 -05:00
**Response**: returns a JSON object with the stream key
2020-07-30 01:34:22 -05:00
2020-10-18 02:16:54 -05:00
**Example**: `{stream_key: "abcdefghijklmno12345"}` or `{error:"error reason"}`