NAV Navbar
Python NodeJS Crystal CSharp Go

Authentication

To authorize, use this code:

import spamwatch

client = spamwatch.Client('API_KEY')

const SpamWatch = require('spamwatch');

const client = new SpamWatch.Client("API_KEY");

require "spamwatch"

token = "API_KEY"
client = SpamWatch::Client.new(token)

using SpamWatch;

var client = new SpamWatch.Client("API_KEY");

Make sure to replace API_KEY with your API key.

The API uses API keys to allow access to the API. You can get a API key here.

The API expects the API key to be included in all API requests to the server in a header that looks like the following:

Authorization: Bearer $API_KEY

Permissions

Each endpoint (except /version) requires a certain permission level. The required level is mentioned in the documentation of the endpoint.

The API has three permission levels:

Level Rights
Root Can do everything
Admin Can query and update the banlist
User Can query the Banlist

To find out your Tokens Permission level go here: Getting your own Token

Root

Root is the highest permission level. A token with Root permission can do the following:

/banlist

Request Path
GET /banlist
GET /banlist/all
GET /banlist/$id
POST /banlist
DELETE /banlist/$id

/tokens

Request Path
GET /tokens
GET /tokens/$id
GET /tokens/userid/$id
POST /tokens
DELETE /tokens/$id

/

Request Path
GET /version
GET /stats

Admin

A token with Admin permission can do the following:

/banlist

Request Path
GET /banlist/all
GET /banlist/$id
POST /banlist
DELETE /banlist/$id

/

Request Path
GET /version
GET /stats

User

A token with User permission can do the following:

/banlist

Request Path
GET /banlist/all
GET /banlist/$id

/

Request Path
GET /version
GET /stats

Banlist

Getting a specific ban

import spamwatch

client = spamwatch.Client('API_KEY')
ban = client.get_ban(777000)

const SpamWatch = require('spamwatch');

const client = new SpamWatch.Client("API_KEY");
let ban = client.getBan(777000)

require "spamwatch"

token = "API_KEY"
client = SpamWatch::Client.new(token)

ban = client.get_ban(777000)

using SpamWatch;

var client = new SpamWatch.Client("API_KEY");
var ban = client.GetBan(777000);

package main

import (
    "fmt"

    "github.com/SpamWatch/spamwatch-go"
)

var client = spamwatch.Client("API_KEY", nil)

func main() {
    ban, err := client.GetBan(777000)
    if err != nil {
        fmt.Println(err.Error())
        return
    }
    fmt.Println(ban)
}

The returned JSON:

{
    "admin": 2,
    "date": 1570674252,
    "id": 777000,
    "reason": "Ban reason",
    "message": "abc"
}

Check the ban status of a specific User.

HTTP Request

GET https://api.spamwat.ch/banlist/$id

URL Parameters

Parameter Description
$id The id of the user to check

Required permission level

User

Getting all bans

import spamwatch

client = spamwatch.Client('API_KEY')
bans = client.get_bans()

const SpamWatch = require('spamwatch');

const client = new SpamWatch.Client("API_KEY");
let bans = client.getBans();

require "spamwatch"

token = "API_KEY"
client = SpamWatch::Client.new(token)

bans = client.get_bans()

using SpamWatch;

var client = new SpamWatch.Client("API_KEY");
var allBans = client.GetBans();


package main

import (
    "fmt"

    "github.com/SpamWatch/spamwatch-go"
)

var client = spamwatch.Client("API_KEY", nil)

func main() {
    bans, err := client.GetBans()
    if err != nil {
        fmt.Println(err.Error())
        return
    }
    fmt.Println(bans)
}

The returned JSON:

[
    {
        "admin": 2,
        "date": 1570416028,
        "id": 12345,
        "reason": "Ban reason 1"
    },
    {
        "admin": 2,
        "date": 1570416445,
        "id": 6789,
        "reason": "Ban reason 2",
        "message": "abc"
    }
]

This returns a list of all Bans.

HTTP Request

GET https://api.spamwat.ch/banlist

Required permission level

Root

Getting a list of banned ids

import spamwatch

client = spamwatch.Client('API_KEY')
bans = client.get_bans_min()

// TODO

// TODO

using SpamWatch;

var client = new SpamWatch.Client("API_KEY");
var bans = client.GetBansMin();

package main

import (
    "fmt"

    "github.com/SpamWatch/spamwatch-go"
)

var client = spamwatch.Client("API_KEY", nil)

func main() {
    bans, err := client.GetBansMin()
    if err != nil {
        fmt.Println(err.Error())
        return
    }
    fmt.Println(bans)
}

The returned Content:

12345
6789

This returns a newline seperated list of all Bans. This method currently ignores the Accept header and will always return a newline seperated list. In the future it might return a JSON with the corresponding content type.

HTTP Request

GET https://api.spamwat.ch/banlist/all

Required permission level

User

Adding a ban

import spamwatch

client = spamwatch.Client('API_KEY')
client.add_ban(777000, "reason", "message")

const SpamWatch = require('spamwatch');

const client = new SpamWatch.Client("API_KEY");

var newBan = new Ban()
{
    UserId = 777000,
    Reason = "Ban Reason",
    Message = "Telegram Message that got the user banned"
};

client.AddBan(newBan);

require "spamwatch"

token = "API_KEY"
client = SpamWatch::Client.new(token)

client.add_ban(777000, "reason")

using SpamWatch;

var client = new SpamWatch.Client("API_KEY");
client.AddBan(777000, "reason");

package main

import (
    "github.com/SpamWatch/spamwatch-go"
)

var client = spamwatch.Client("API_KEY", nil)

func main() {
    client.AddBan(777000, "reason", "message")
}

HTTP Request

POST https://api.spamwat.ch/banlist

Headers

Key Value
Content-Type application/json

Example Body

[
    {
        "id": 12345,
        "reason": "Ban reason 1"
    },
    {
        "id": 6789,
        "reason": "Ban reason 2",
        "message": "abc"
    }
]

JSON Body

A list of JSON Objects with the following keys:

Key Value
id The id of the User
reason the reason for the ban

Required permission level

Admin

Deleting a ban

import spamwatch

client = spamwatch.Client('API_KEY')
client.delete_ban(777000)

const SpamWatch = require('spamwatch');

const client = new SpamWatch.Client("API_KEY");
client.deleteBan(777000)

require "spamwatch"

token = "API_KEY"
client = SpamWatch::Client.new(token)

client.delete_ban(777000)

using SpamWatch;

var client = new SpamWatch.Client("API_KEY");
client.DeleteBan(777000);

package main

import (
    "github.com/SpamWatch/spamwatch-go"
)

var client = spamwatch.Client("API_KEY", nil)

func main() {
    client.DeleteBan(777000)
}

HTTP Request

DELETE https://api.spamwat.ch/banlist/$id

URL Parameters

Parameter Description
id The id of the user to delete

Required permission level

Admin

Tokens

Getting your own Token

import spamwatch

client = spamwatch.Client('API_KEY')
my_token = client.get_self()

const SpamWatch = require('spamwatch');

const client = new SpamWatch.Client("API_KEY");
let my_token = client.getSelf()

require "spamwatch"

token = "API_KEY"
client = SpamWatch::Client.new(token)

my_token = client.get_self()

using SpamWatch;

var client = new SpamWatch.Client("API_KEY");
var token = client.Token;
// Or by making a request:
var token = client.GetSelf();

package main

import (
    "fmt"

    "github.com/SpamWatch/spamwatch-go"
)

var client = spamwatch.Client("API_KEY", nil)

func main() {
    myToken, err := client.GetSelf()
    if err != nil {
        fmt.Println(err)
        return
    }
    fmt.Println(myToken)
}

The returned JSON:

{
    "id": 1,
    "permission": "Root",
    "retired": false,
    "token": "vN9cBTtO8xgC4Qm",
    "userid": 777000
}

This returns the Token the request was made with. Useful for checking the permission Level of the token.

HTTP Request

GET https://api.spamwat.ch/tokens/self

Required permission level

User

Getting all Tokens

import spamwatch

client = spamwatch.Client('API_KEY')
tokens = client.get_tokens()

const SpamWatch = require('spamwatch');

const client = new SpamWatch.Client("API_KEY");
let tokens = client.getTokens()

require "spamwatch"

token = "API_KEY"
client = SpamWatch::Client.new(token)

tokens = client.get_tokens()

using SpamWatch;

var client = new SpamWatch.Client("API_KEY");
var tokens = client.GetTokens();

package main

import (
    "fmt"

    "github.com/SpamWatch/spamwatch-go"
)

var client = spamwatch.Client("API_KEY", nil)

func main() {
    tokens, err := client.GetTokens()
    if err != nil {
        fmt.Println(err)
        return
    }
    fmt.Println(tokens)
}

The returned JSON:

[
    {
        "id": 1,
        "permission": "Root",
        "retired": false,
        "token": "vN9cBTtO8xgC4Qm",
        "userid": 777000
    },
    {
        "id": 3,
        "permission": "Admin",
        "retired": false,
        "token": "wfsr7EstLz5RGkV",
        "userid": 777000
    }
]

This returns a list of all Tokens.

HTTP Request

GET https://api.spamwat.ch/tokens

Required permission level

Root

Getting a specific Token

import spamwatch

client = spamwatch.Client('API_KEY')
token = client.get_token(1)

const SpamWatch = require('spamwatch');

const client = new SpamWatch.Client("API_KEY");
let token = client.getToken(1)

require "spamwatch"

token = "API_KEY"
client = SpamWatch::Client.new(token)

token = client.get_token(1)

using SpamWatch;

var client = new SpamWatch.Client("API_KEY");
var token = client.GetToken(1);

package main

import (
    "fmt"

    "github.com/SpamWatch/spamwatch-go"
)

var client = spamwatch.Client("API_KEY", nil)

func main() {
    Token, err := client.GetToken(1)
    if err != nil {
        fmt.Println(err)
        return
    }
    fmt.Println(Token)
}

The returned JSON:

{
    "id": 1,
    "permission": "Root",
    "retired": false,
    "token": "vN9cBTtO8xgC4Qm",
    "userid": 777000
}

This returns a specific Tokens.

HTTP Request

GET https://api.spamwat.ch/tokens/$id

URL Parameters

Parameter Description
id The id of the Token

Required permission level

Root

Getting a Users tokens

# Todo

// Todo

// Todo

// Todo

package main

import (
    "fmt"

    "github.com/SpamWatch/spamwatch-go"
)

var client = spamwatch.Client("API_KEY", nil)

func main() {
    tokens, err := client.GetUserTokens(777000)
    if err != nil {
        fmt.Println(err)
        return
    }
    fmt.Println(tokens)
}

The returned JSON:

[
    {
        "id": 1,
        "permission": "Root",
        "retired": false,
        "token": "J~h1s9tZT7jswRC",
        "userid": 172811422
    },
    {
        "id": 10,
        "permission": "Admin",
        "retired": false,
        "token": "oeTL3IzIKa3YJTv",
        "userid": 172811422
    },
    {
        "id": 11,
        "permission": "User",
        "retired": true,
        "token": "prLyW8c8GzPWwq5",
        "userid": 172811422
    },
    {
        "id": 12,
        "permission": "User",
        "retired": false,
        "token": "_GlJA4jH8y2Jj7J",
        "userid": 172811422
    }
]

This returns a list of all tokens associated with the specified user id.

HTTP Request

GET https://api.spamwat.ch/tokens/userid/$id

URL Parameters

Parameter Description
id The users id

Required permission level

Root

Creating a Token

import spamwatch

client = spamwatch.Client('API_KEY')
client.create_token(777000, Permission.User)

const SpamWatch = require('spamwatch');

const client = new SpamWatch.Client("API_KEY");
// Todo

require "spamwatch"

token = "API_KEY"
client = SpamWatch::Client.new(token)

// Todo

using SpamWatch;

var newToken = new Token()
{
    UserId = 777000,
    Permission = Permissions.User
};

token = client.CreateToken(newToken);

package main

import (
    "github.com/SpamWatch/spamwatch-go"
)

var client = spamwatch.Client("API_KEY", nil)

func main() {
    client.CreateToken(777000, spamwatch.UserPermission)
}

HTTP Request

POST https://api.spamwat.ch/tokens

Headers

Key Value
Content-Type application/json

Example Body

{
    "id": 777000,
    "permission": "Admin"
}

JSON Body

A single JSON Object with the following keys:

Key Value
id The id of the User connected to this Token
permission The permission level of the Token

Possible values for permission are Root, Admin and User

Required permission level

Admin

Retiring a specific Token

import spamwatch

client = spamwatch.Client('API_KEY')
client.delete_token(1)

const SpamWatch = require('spamwatch');

const client = new SpamWatch.Client("API_KEY");
client.deleteToken(1)

require "spamwatch"

token = "API_KEY"
client = SpamWatch::Client.new(token)

client.delete_token(1)

using SpamWatch;

var client = new SpamWatch.Client("API_KEY");
client.DeleteToken(1);

package main

import (
    "github.com/SpamWatch/spamwatch-go"
)

var client = spamwatch.Client("API_KEY", nil)

func main() {
    client.DeleteToken(1)
}

This retires a specific Token. The Token won't be able to make any requests anymore.

HTTP Request

DELETE https://api.spamwat.ch/tokens/$id

URL Parameters

Parameter Description
id The id of the Token

Required permission level

Root

Misc

Getting the API version

import spamwatch

client = spamwatch.Client('API_KEY')
bans = client.version()

const SpamWatch = require('spamwatch');

const client = new SpamWatch.Client("API_KEY");
let bans = client.version()

// Todo

using SpamWatch;

var client = new SpamWatch.Client("API_KEY");
var version = client.Version();

package main

import (
    "fmt"

    "github.com/SpamWatch/spamwatch-go"
)

var client = spamwatch.Client("API_KEY", nil)

func main() {
    v, err := client.Version()
    if err != nil {
        fmt.Println(err.Error())
        return
    }
    fmt.Println(v)
}

The returned JSON:

{
    "major": "0",
    "minor": "1",
    "patch": "0",
    "version": "0.1.0"
}

This returns the major, minor and patch version of the API. This endpoint doesn't need a Authorization Token.

HTTP Request

GET https://api.spamwat.ch/version

Getting some stats

import spamwatch

client = spamwatch.Client('API_KEY')
bans = client.stats()

const SpamWatch = require('spamwatch');

const client = new SpamWatch.Client("API_KEY");
let bans = client.stats()

// Todo

using SpamWatch;

var client = new SpamWatch.Client("API_KEY");
var stats = client.Stats();


package main

import (
    "fmt"

    "github.com/SpamWatch/spamwatch-go"
)

var client = spamwatch.Client("API_KEY", nil)

func main() {
    v, err := client.Stats()
    if err != nil {
        fmt.Println(err.Error())
        return
    }
    fmt.Println(v)
}

The returned JSON:

{
    "total_ban_count":70210
}

This returns general stats about the API. Right now this only returns the total ban count.

HTTP Request

GET https://api.spamwat.ch/stats

Python NodeJS Crystal CSharp Go