API

SickGear Wiki: Home | Reporting Issues | Frequently Answered Questions | Install Guides

SickGear API Functions

• The Sick-Beard API functions are retained for basic use
• SickGear has another level of API function to extend flexibility

As a reference point:

In-app documentation for all current endpoints can be found under: <sickgear:port>/api/builder
simply, select "List Commands" then press the "Go" Button.

To identify SickGear, both "sg" and "sb" commands return: "fork": "SickGear"

The response headers contain: 'X-Application': 'SickGear', 'X-API-Version', 13

• Legacy Sick-Beard compatibility commands only return thetvdb shows, and can only be used with those shows
• The SickGear API requires both indexer and indexerid, to support other indexers too

The core functions of the API can also be tried and tested at <sickgear:port>/api/builder

The following SG features are not yet listed in the builder...

• sg.updatewatchedstate

---

Update Watched State

Purpose: Update SickGear with details of media file that is watched or unwatched.

This feature was first made and tested with Kodi, then once the core functionality proved viable, this API method was added to enable anyone to signal via any language script or batch file by attaching to the Media Player or Application Event that notifies "Hey, i just marked file ABC as watched" or "unwatched".

The data supplied to this endpoint is displayed under layout drop down "Watched" item of the
History page. The value in this feature is clear when deciding what to delete based on what has been watched.

:param payload: Payload is a dict of dicts
:type payload: JSON or dict
Each dict key in payload is an arbitrary value used to return its associated success or fail response.
Each dict value in payload comprises a dict of key value pairs where,
* key: path_file: Path and filename of media, required for media to be found.
type: path_file: String
* key: media_id: Optional default=''. Client episode id of media.
type: path_file: String
* key: played: Optional default=100. Percentage of times media has played. If 0, show is set as unwatched, 200=played twice, 150=played one and half times. 33=a third played
type: played: Number
* key: label: Optional default=''. Profile name or label in use while playing media.
type: label: String
* key: date_watched: Optional default=current time. Datetime stamp that episode changed state.
type: date_watched: Timestamp

Payload example as a Python dict:

dict(  
    key01=dict(path_file='\\media\\path\\', played=100, label='Bob', date_watched=1509850398.0),  
    key02=dict(path_file='\\media\\path\\file-played1.mkv', played=100, label='Sue', date_watched=1509850398.0),  
    key03=dict(path_file='\\media\\path\\file-played2.mkv', media_id='1234', played=33, label='Rita', date_watched=1509850398.0)  
)

Payload example as JSON:

'{"key01": {"path_file": "\\media\\path\\file_played1.mkv", "played": 100, "label": "Bob", "date_watched": 1509850398.0}}'  

:return: if OK, the value of each dict is '' else fail reason string else None if payload is invalid.
:rtype: String
Examples:
'{"key123": {""}}' : on success
'{"key123": {"error reason"}}'
'{"error": {"error reason"}}' : 'error' used as default key when bad key, value, or json

Example case code using API endpoint,
copy/paste, edit to suit, save, then run with: python sg_watched.py

import json
import urllib2

# SickGear APIkey
sg_apikey = '0123456789abcdef'
# SickGear server detail
sg_host = 'http://localhost:8081'

url = '%s/api/%s/?cmd=sg.updatewatchedstate' % (sg_host, sg_apikey)
payload = json.dumps(dict(
    key01=dict(path_file='\\media\\path\\', played=100, label='Bob', date_watched=1509850398.0),
    key02=dict(path_file='\\media\\path\\file-played1.mkv', played=100, label='Sue', date_watched=1509850398.0),
    key03=dict(path_file='\\media\\path\\file-played2.mkv', media_id='1234', played=33, label='Rita', date_watched=1509850398.0)
))
# payload is POST'ed to SG
rq = urllib2.Request(url, data=payload)
r = urllib2.urlopen(rq)
print json.load(r)
r.close()

You could just as easily use CURL or WGET to post the data in the above example to SG

---