Overview

The web API takes the form https://layer7.solutions/api/v1/METHOD.
For example, https://layer7.solutions/api/v1/identity.

All methods must be called using HTTPS. The response will always be in JSON format. The properties within the response are defined in the documentation for the relevant method.

Errors

If an error occurred, there will be two properties: error and error_description. The error code will remain constant for the given error type, whereas the error_description is a human-readable description of the error and may change at any time.

        {
            "error": "ERROR_CODE",
            "error_description": "Something happened",
        }
        

The HTTP status code will also be different from the usual 200. For example, if your request had invalid or missing parameters then the status code will be 400 Bad request, and if you attempt to make a request on a subreddit you don't mod then it'll be 403 Forbidden.

Authenticating

The api uses OAuth 2. If you are unsure of how to use OAuth 2, search for OAuth 2 tutorials.

Our OAuth2 server currently only enables these grant types: client_credentials, authorization_code, refresh_token

To register an application click here.

API Usage Rules

Overall, our API rules aren't too strict. But if there is precedent we may make them more strict overtime. Any changes to this API will be announced on our subreddit.

• Authentication API clients must authenticate using OAuth 2
• Rate Limit: currently we do not have a rate limit, this is subject to change if it becomes a problem. So please use our API responsibly. You shouldn't really be going over 60 requests per minute.
• User-Agent: the client's user-agent should be something unique and descriptive that identifies your application.
  • Do not lie about your user-agent. Such as masquerading as other bots or applications.
• Do not use our API for malicious purposes. We do reserve the right to refuse service to any user or subreddit mod team.

Quick guide on how to integrate with your PRAW bot or other Python applications

With Python 3, requests library, and the client_credentials grant type.
Or you could use a OAuth2 python library.

First click this link and register your OAuth2 application if you haven't done so already. Take note of the generated Consumer ID and Consumer Secret.

Then request an access token:

        >>> import requests
        >>> import json

        >>> r = requests.post('https://layer7.solutions/api/v1/access_token',
                data = {
                    'grant_type': 'client_credentials',
                    'scope': 'identity tsbread' # space-delimited scope list
                },
                auth = (
                    'e0aaV-pQQ_vPpu', # Consumer ID
                    'f4fJPcr6UbpnBolBn_TI4HZZPKwQkYLvtMgvFiZ7oDEA0n5kDs' # Consumer Secret
                ))
        >>> r.status_code
        200
        >>> print(json.dumps(r.json(), indent=2))
        {
          'access_token': 'fc92463c2a1753ed1be23c84b0fd42496bbaf45f',
          'expires_in': 3600,
          'token_type': 'Bearer',
          'scope': 'identity tsbread'
        }
        

And then add the Authorization: Bearer <ACCESS TOKEN HERE> header to your requests:

        >>> r2 = requests.get('https://layer7.solutions/api/v1/videos/blacklist/reports',
                params = {
                    'type': 'channel_name',
                    'subject': 'funny videos',
                    'amount': 5
                },
                headers = {
                    'Authorization': r.json()['token_type'] + ' ' + r.json()['access_token']
                })
        >>> r2.status_code
        200
        >>> print(json.dumps(r2.json(), indent=2))
        {
          "matter": [
            {
              "subject": "funny videos",
              "type": "channel_name",
              "matter_id": "channel_name;funny videos"
            }
          ],
          "listing": [
            {
              "id": 64925062,
              "removed": false,
              "action_utc": 1513598213.2133,
              "subreddit": "videos",
              "author": "ngochaivp91",
              "thing_id": "t3_7kkrmd",
              "thing_title": "Funny videos 2017!Secret of doing stupid actions - HD sex Dino 2017 #3",
              "thing_data": "",
              "thing_created": 1513598163,
              "permalink": "http://reddit.com/7kkrmd",
              "media_author": "Funny Videos",
              "media_channel_id": "UCh6EkQQCkxOX_aEIJs0Ftew",
              "media_link": "https://www.youtube.com/attribution_link?a=vQhiRShsXZc&u=%2Fwatch%3Fv%3DvdnT4kqmP0s%26feature%3Dshare",
              "media_platform_id": 1,
              "media_channel_url": null,
              "media_platform": "YouTube",
            },
            {
              "id": 64526546,
              "removed": false,
              "action_utc": 1513412690.6086,
              "subreddit": "videos",
              "author": "Isadoscomedy",
              "thing_id": "t1_drbtfws",
              "thing_title": null,
              "thing_data": "Most funniest video https://youtu.be/PCnw7y_7x2k",
              "thing_created": 1513412664,
              "permalink": "http://reddit.com/comments/7k3eeu/-/drbtfws",
              "media_author": "Most Funny Videos Latest",
              "media_channel_id": "UCYytxrvf1C5TIN0Macafw4g",
              "media_link": "https://youtu.be/PCnw7y_7x2k",
              "media_platform_id": 1,
              "media_channel_url": null,
              "media_platform": "YouTube",
            },
            {
              "id": 64525973,
              "removed": false,
              "action_utc": 1513412324.8388,
              "subreddit": "videos",
              "author": "Isadoscomedy",
              "thing_id": "t1_drbtb1e",
              "thing_title": null,
              "thing_data": "Are you interested in laughing out your sorrow? Then click here https://youtu.be/S6e1XJcRWVM",
              "thing_created": 1513412308,
              "permalink": "http://reddit.com/comments/7k1qia/-/drbtb1e",
              "media_author": "Most Funny Videos Latest",
              "media_channel_id": "UCYytxrvf1C5TIN0Macafw4g",
              "media_link": "https://youtu.be/S6e1XJcRWVM",
              "media_platform_id": 1,
              "media_channel_url": null,
              "media_platform": "YouTube",
            },
            {
              "id": 64525902,
              "removed": false,
              "action_utc": 1513412272.9849,
              "subreddit": "videos",
              "author": "Isadoscomedy",
              "thing_id": "t1_drbta4n",
              "thing_title": null,
              "thing_data": "Are you interested in laughing out your sorrow? Then click here https://youtu.be/S6e1XJcRWVM",
              "thing_created": 1513412241,
              "permalink": "http://reddit.com/comments/7k3wwc/-/drbta4n",
              "media_author": "Most Funny Videos Latest",
              "media_channel_id": "UCYytxrvf1C5TIN0Macafw4g",
              "media_link": "https://youtu.be/S6e1XJcRWVM",
              "media_platform_id": 1,
              "media_channel_url": null,
              "media_platform": "YouTube",
            },
            {
              "id": 64525799,
              "removed": false,
              "action_utc": 1513412193.3,
              "subreddit": "videos",
              "author": "Isadoscomedy",
              "thing_id": "t1_drbt981",
              "thing_title": null,
              "thing_data": "Are you interested in laughing out your sorrow? Then click here https://youtu.be/S6e1XJcRWVM",
              "thing_created": 1513412174,
              "permalink": "http://reddit.com/comments/7k28dr/-/drbt981",
              "media_author": "Most Funny Videos Latest",
              "media_channel_id": "UCYytxrvf1C5TIN0Macafw4g",
              "media_link": "https://youtu.be/S6e1XJcRWVM",
              "media_platform_id": 1,
              "media_channel_url": null,
              "media_platform": "YouTube",
            }
          ],
          "amount": 5,
          "offset": 0,
          "total": 1297
        }
        >>>
        

And that's it! And don't forget about the 'expires_in': 3600 part of the access_token response. You'll have to fetch a new access token every hour.

Here's a list of all our scopes for ease of copying:

Subreddit Notation

Take note that wherever you see {subreddit}, whether as part of the path or as a query parameter value, you can use our Subreddit Notation

However, wherever you see {srname} allows only one subreddit.