URL APIs

1. Overview

This page contains all of the APIs for managing the URL filter.

Available since 3.25.0

The following APIs only operate on the active filter state. There is no approval process for the APIs and everything will be immediately added to the active filter state. Use the Management Interface to manage pending modifications.

1.1. Top Level Domains

The following APIs are provided to manage Top Level Domains inside of CleanSpeak. A Top Level Domain or TLD is a unique name used by various agencies as the root domain of any website. An example of this is the COM TLD. CleanSpeak uses TLDs to identify URLs and this API exists so that you can modify which TLDs CleanSpeak identifies as URLs and their qualities so that bad URLs can be easily tuned.

1.2. Whitelisted URLs

A Whitelisted URL is a Regular Expression or RegEx that when matched will prevent CleanSpeak from flagging that particular URL. This is useful if you are hosting something like a forum where users are only allowed to post URLs to permitted websites. The permitted websites are defined by the Whitelisted URL objects. Additionally you can also tag a Whitelisted URL to be limited in scope to only affect applications that also have those same tags.

1.3. URL Whitelist Tags

URL Whitelist Tags are used to associate Whitelisted URLs with applications that wish to limit their scope. When a Whitelisted URL has a tag it can only affect applications that also contain that same tag.

2. Retrieve a TLD

2.1. Request

Retrieve a TLD by name

URI

GET /filter/url/tld/{name}

Table 1. Request Parameters

name [String] required

The unique name of the TLD to retrieve.

Table 2. Response Codes
Code Description

200

The request was successful. The response will contain a JSON body.

400

The request was invalid and/or malformed. The response will contain an Errors JSON Object with the specific errors.

401

You did not supply a valid Authorization header. The header was omitted or your API key was not valid. The response will be empty. See Authentication.

402

Your license has expired. The response will be empty. Contact sales@cleanspeak.com for assistance.

404

The object you requested doesn’t exist. The response will be empty.

500

There was an internal error. A stack trace is provided and logged in the CleanSpeak log files. The response will be empty.

Table 3. Response Body

tld.name [String]

The name of the TLD

tld.quality [Double]

The quality score of this TLD. Higher values mean a higher likelihood of a match on a URL. Lower values will cause a match to be thrown out more easily.

tld.status [String]

The approval status of the entry.

Example Response JSON
{
  "tld": {
    "name": "COM",
    "quality": 1.0,
    "status": "ACTIVE"
  }
}

3. Retrieve all TLDs

3.1. Request

Retrieve all TLDs

URI

GET /filter/url/tld

3.2. Response

Table 4. Response Codes
Code Description

200

The request was successful. The response will contain a JSON body.

401

You did not supply a valid Authorization header. The header was omitted or your API key was not valid. The response will be empty. See Authentication.

402

Your license has expired. The response will be empty. Contact sales@cleanspeak.com for assistance.

500

There was an internal error. A stack trace is provided and logged in the CleanSpeak log files. The response will be empty.

Table 5. Response Body

tlds[x].name [String]

The name of the TLD

tlds[x].quality [Double]

The quality score of this TLD. Higher values mean a higher likelihood of a match on a URL. Lower values will cause a match to be thrown out more easily.

tlds[x].status [String]

The approval status of the entry.

Example Response JSON
{
  "tlds": [
    {
      "name": "AAA",
      "quality": 0.5,
      "status": "ACTIVE"
    },
    {
      "name": "ABB",
      "quality": 0.5,
      "status": "ACTIVE"
    },
    {
      "name": "ABBOTT",
      "quality": 0.5,
      "status": "ACTIVE"
    },
    {
      "name": "ABOGADO",
      "quality": 0.5,
      "status": "ACTIVE"
    }
  ]
}

4. Create a TLD

4.1. Request

Create a TLD

URI

POST /filter/url/tld

Table 6. Request Body

tld.name [String] required

The name of the tld.

This must be a legal top level domain.

tld.quality [Double] required

The quality score of this TLD. Higher values mean a higher likelihood of a match on a URL. Lower values will cause a match to be thrown out more easily.

This must be a decimal between 0 and 1 (inclusive)

Example Request JSON
{
  "tld": {
    "name": "COM",
    "quality": 1.0
  }
}

4.2. Response

Table 7. Response Codes
Code Description

200

The request was successful. The response will contain a JSON body.

400

The request was invalid and/or malformed. The response will contain an Errors JSON Object with the specific errors.

401

You did not supply a valid Authorization header. The header was omitted or your API key was not valid. The response will be empty. See Authentication.

402

Your license has expired. The response will be empty. Contact sales@cleanspeak.com for assistance.

500

There was an internal error. A stack trace is provided and logged in the CleanSpeak log files. The response will be empty.

Table 8. Response Body

tld.name [String]

The name of the TLD

tld.quality [Double]

The quality score of this TLD. Higher values mean a higher likelihood of a match on a URL. Lower values will cause a match to be thrown out more easily.

tld.status [String]

The approval status of the entry.

Example Response JSON
{
  "tld": {
    "name": "COM",
    "quality": 1.0,
    "status": "ACTIVE"
  }
}

5. Create bulk TLDs

5.1. Request

Create many TLDs

URI

POST /filter/url/tld

Since both of the create TLD APIs use the same URL, providing both tld and tlds in the request will prefer the create single TLD variant.

Table 9. Request Body

tlds[x].name [String] required

The name of the TLD

tlds[x].quality [Double] required

The quality score of this TLD. Higher values mean a higher likelihood of a match on a URL. Lower values will cause a match to be thrown out more easily.

This must be a decimal between 0 and 1 (inclusive)

Example Request JSON
{
  "tlds": [
    {
      "name": "AAA",
      "quality": 0.5
    },
    {
      "name": "ABB",
      "quality": 0.5
    },
    {
      "name": "ABBOTT",
      "quality": 0.5
    },
    {
      "name": "ABOGADO",
      "quality": 0.5
    }
  ]
}

5.2. Response

Table 10. Response Codes
Code Description

200

The request was successful. The response will contain a JSON body.

400

The request was invalid and/or malformed. The response will contain an Errors JSON Object with the specific errors.

401

You did not supply a valid Authorization header. The header was omitted or your API key was not valid. The response will be empty. See Authentication.

402

Your license has expired. The response will be empty. Contact sales@cleanspeak.com for assistance.

500

There was an internal error. A stack trace is provided and logged in the CleanSpeak log files. The response will be empty.

Table 11. Response Body

tlds[x].name [String]

The name of the TLD

tlds[x].quality [Double]

The quality score of this TLD. Higher values mean a higher likelihood of a match on a URL. Lower values will cause a match to be thrown out more easily.

tlds[x].status [String]

The approval status of the entry.

Example Response JSON
{
  "tlds": [
    {
      "name": "AAA",
      "quality": 0.5,
      "status": "ACTIVE"
    },
    {
      "name": "ABB",
      "quality": 0.5,
      "status": "ACTIVE"
    },
    {
      "name": "ABBOTT",
      "quality": 0.5,
      "status": "ACTIVE"
    },
    {
      "name": "ABOGADO",
      "quality": 0.5,
      "status": "ACTIVE"
    }
  ]
}

6. Update a TLD

6.1. Request

Update a TLD by name

URI

PUT /filter/url/tld/{name}

Table 12. Request Parameters

name [String] required Available since 3.26.0

The unique name of the TLD to update.

Table 13. Request Body

tld.name [String] required Deprecated in 3.26.0

The name of the tld to update.

In version 3.26.0 and beyond, the name is provided on the request url.

tld.quality [Double] required

The quality score of this TLD. Higher values mean a higher likelihood of a match on a URL. Lower values will cause a match to be thrown out more easily.

This must be a decimal between 0 and 1 (inclusive)

Example Request JSON
{
  "tld": {
    "quality": 1.0
  }
}

6.2. Response

Table 14. Response Codes
Code Description

200

The request was successful. The response will contain a JSON body.

400

The request was invalid and/or malformed. The response will contain an Errors JSON Object with the specific errors.

401

You did not supply a valid Authorization header. The header was omitted or your API key was not valid. The response will be empty. See Authentication.

402

Your license has expired. The response will be empty. Contact sales@cleanspeak.com for assistance.

404

The object you are trying to update doesn’t exist. The response will be empty.

500

There was an internal error. A stack trace is provided and logged in the CleanSpeak log files. The response will be empty.

Table 15. Response Body

tld.name [String]

The name of the TLD

tld.quality [Double]

The quality score of this TLD. Higher values mean a higher likelihood of a match on a URL. Lower values will cause a match to be thrown out more easily.

tld.status [String]

The approval status of the entry.

Example Response JSON
{
  "tld": {
    "name": "COM",
    "quality": 1.0,
    "status": "ACTIVE"
  }
}

7. Delete a TLD

7.1. Request

Delete a TLD by name

URI

DELETE /filter/url/tld/{name}

Table 16. Request Parameters

name [String] required

The unique name of the TLD to delete.

7.2. Response

Table 17. Response Codes
Code Description

200

The request was successful. The response will be empty.

401

You did not supply a valid Authorization header. The header was omitted or your API key was not valid. The response will be empty. See Authentication.

402

Your license has expired. The response will be empty. Contact sales@cleanspeak.com for assistance.

404

The object you are trying to delete doesn’t exist. The response will be empty.

500

There was an internal error. A stack trace is provided and logged in the CleanSpeak log files. The response will be empty.

8. Retrieve a Whitelisted URL

8.1. Request

Retrieve a whitelisted URL by Id

URI

GET /filter/url/{id}

Table 18. Request Parameters

id [String] required

The unique id of the whitelisted URL to retrieve.

8.2. Response

Table 19. Response Codes
Code Description

200

The request was successful. The response will contain a JSON body.

400

The request was invalid and/or malformed. The response will contain an Errors JSON Object with the specific errors.

401

You did not supply a valid Authorization header. The header was omitted or your API key was not valid. The response will be empty. See Authentication.

402

Your license has expired. The response will be empty. Contact sales@cleanspeak.com for assistance.

404

The object you requested doesn’t exist. The response will be empty.

500

There was an internal error. A stack trace is provided and logged in the CleanSpeak log files. The response will be empty.

Table 20. Response Body

entry.id [Integer]

The unique identifier of the entry

entry.status [String]

The approval state of the entry

entry.tags [Array<String>]

The names of url whitelist tags associated with the entry

If the entry contains any tags, they will only be applicable to requests that use an application with the same tag(s). Tags allow you to scope whitelisted urls.

entry.url [String]

A regular expression that will ignore any urls in the content that match

Example Response JSON
{
  "entry": {
    "id": 42,
    "status": "ACTIVE",
    "tags": [
      "tag1"
    ],
    "url": "example\\.com/.+"
  }
}

9. Retrieve all Whitelisted URLs

9.1. Request

Retrieve all Whitelisted URLs

URI

GET /filter/url

9.2. Response

Table 21. Response Codes
Code Description

200

The request was successful. The response will contain a JSON body.

401

You did not supply a valid Authorization header. The header was omitted or your API key was not valid. The response will be empty. See Authentication.

402

Your license has expired. The response will be empty. Contact sales@cleanspeak.com for assistance.

500

There was an internal error. A stack trace is provided and logged in the CleanSpeak log files. The response will be empty.

Table 22. Response Body

entries[x].id [Integer]

The unique identifier of the entry

entries[x].status [String]

The approval state of the entry

entries[x].tags [Array<String>]

The names of url whitelist tags associated with the entry

If the entry contains any tags, they will only be applicable to requests that use an application with the same tag(s). Tags allow you to scope whitelisted urls.

entries[x].url [String]

A regular expression that will ignore any urls in the content that match

Example Response JSON
{
  "entries": [
    {
      "id": 42,
      "status": "ACTIVE",
      "tags": [],
      "url": "example\\.com/.+"
    },
    {
      "id": 69,
      "status": "ACTIVE",
      "tags": [
        "tag1"
      ],
      "url": "example\\.io/.+"
    }
  ]
}

10. Create a Whitelisted URL

10.1. Request

Create a Whitelisted URL

URI

POST /filter/url

Table 23. Request Body

entry.tags [Array<String>]

The names of url whitelist tags associated with the entry

If the entry contains any tags, they will only be applicable to requests that use an application with the same tag(s). Tags allow you to scope whitelisted urls.

All tags provided must already exist.

entry.url [String]

A regular expression that will ignore any urls in the content that match

Example Request JSON
{
  "entry": {
    "tags": [
      "tag1"
    ],
    "url": "example\\.com/.+"
  }
}

10.2. Response

Table 24. Response Codes
Code Description

200

The request was successful. The response will contain a JSON body.

400

The request was invalid and/or malformed. The response will contain an Errors JSON Object with the specific errors.

401

You did not supply a valid Authorization header. The header was omitted or your API key was not valid. The response will be empty. See Authentication.

402

Your license has expired. The response will be empty. Contact sales@cleanspeak.com for assistance.

500

There was an internal error. A stack trace is provided and logged in the CleanSpeak log files. The response will be empty.

Table 25. Response Body

entry.id [Integer]

The unique identifier of the entry

entry.status [String]

The approval state of the entry

entry.tags [Array<String>]

The names of url whitelist tags associated with the entry

If the entry contains any tags, they will only be applicable to requests that use an application with the same tag(s). Tags allow you to scope whitelisted urls.

entry.url [String]

A regular expression that will ignore any urls in the content that match

Example Response JSON
{
  "entry": {
    "id": 42,
    "status": "ACTIVE",
    "tags": [
      "tag1"
    ],
    "url": "example\\.com/.+"
  }
}

11. Update a Whitelisted URL

11.1. Request

Update a Whitelisted URL by name

URI

PUT /filter/url/{id}

Table 26. Request Parameters

id [String] required

The unique id of the Whitelisted URL to retrieve.

Table 27. Request Body

entry.tags [Array<String>]

The names of url whitelist tags associated with the entry

If the entry contains any tags, they will only be applicable to requests that use an application with the same tag(s). Tags allow you to scope whitelisted urls.

All tags provided must already exist.

entry.url [String]

A regular expression that will ignore any urls in the content that match

Example Request JSON
{
  "entry": {
    "tags": [
      "tag1"
    ],
    "url": "example\\.com/.+"
  }
}

11.2. Response

Table 28. Response Codes
Code Description

200

The request was successful. The response will contain a JSON body.

400

The request was invalid and/or malformed. The response will contain an Errors JSON Object with the specific errors.

401

You did not supply a valid Authorization header. The header was omitted or your API key was not valid. The response will be empty. See Authentication.

402

Your license has expired. The response will be empty. Contact sales@cleanspeak.com for assistance.

404

The object you are trying to update doesn’t exist. The response will be empty.

500

There was an internal error. A stack trace is provided and logged in the CleanSpeak log files. The response will be empty.

Table 29. Response Body

entry.id [Integer]

The unique identifier of the entry

entry.status [String]

The approval state of the entry

entry.tags [Array<String>]

The names of url whitelist tags associated with the entry

If the entry contains any tags, they will only be applicable to requests that use an application with the same tag(s). Tags allow you to scope whitelisted urls.

entry.url [String]

A regular expression that will ignore any urls in the content that match

Example Response JSON
{
  "entry": {
    "id": 42,
    "status": "ACTIVE",
    "tags": [
      "tag1"
    ],
    "url": "example\\.com/.+"
  }
}

12. Delete a Whitelisted URL

12.1. Request

Delete a Whitelisted URL by Id

URI

DELETE /filter/url/{id}

Table 30. Request Parameters

id [Integer] required

The unique id of the Whitelisted URL to delete.

12.2. Response

Table 31. Response Codes
Code Description

200

The request was successful. The response will be empty.

400

The request was invalid and/or malformed. The response will contain an Errors JSON Object with the specific errors.

401

You did not supply a valid Authorization header. The header was omitted or your API key was not valid. The response will be empty. See Authentication.

402

Your license has expired. The response will be empty. Contact sales@cleanspeak.com for assistance.

404

The object you are trying to delete doesn’t exist. The response will be empty.

500

There was an internal error. A stack trace is provided and logged in the CleanSpeak log files. The response will be empty.

13. Retrieve a URL Whitelist Tag

13.1. Request by Id

Retrieve a URL Whitelist Tag by Id

URI

GET /filter/url/tag/{id}

Table 32. Request Parameters

id [Integer] required

The unique id of the URL whitelist tag to retrieve.

13.2. Request by Name

Retrieve a URL Whitelist Tag by name

URI

GET /filter/url/tag/{name}

Table 33. Request Parameters

name [String] required

The unique name of the URL whitelist tag to retrieve.

13.3. Response

Table 34. Response Codes
Code Description

200

The request was successful. The response will contain a JSON body.

400

The request was invalid and/or malformed. The response will contain an Errors JSON Object with the specific errors.

401

You did not supply a valid Authorization header. The header was omitted or your API key was not valid. The response will be empty. See Authentication.

402

Your license has expired. The response will be empty. Contact sales@cleanspeak.com for assistance.

404

The object you requested doesn’t exist. The response will be empty.

500

There was an internal error. A stack trace is provided and logged in the CleanSpeak log files. The response will be empty.

Table 35. Response Body

tag.id [Integer]

The Id of the tag

tag.name [String]

The name of the tag. This is only used for UI purposes.

tag.status [String]

The approval state of the entry

Example Response JSON
{
  "tag": {
    "id": 42,
    "name": "Tag 1",
    "status": "ACTIVE"
  }
}

14. Retrieve all URL Whitelist Tags

14.1. Request

Retrieve all of the URL Whitelist Tags

URI

GET /filter/url/tag

14.2. Response

Table 36. Response Codes
Code Description

200

The request was successful. The response will contain a JSON body.

401

You did not supply a valid Authorization header. The header was omitted or your API key was not valid. The response will be empty. See Authentication.

402

Your license has expired. The response will be empty. Contact sales@cleanspeak.com for assistance.

500

There was an internal error. A stack trace is provided and logged in the CleanSpeak log files. The response will be empty.

Table 37. Response Body

tags[x].id [Integer]

The Id of the tag

tags[x].name [String]

The name of the tag. This is only used for UI purposes.

tags[x].status [String]

The approval state of the entry

Example Response JSON
{
  "tags": [
    {
      "id": 1,
      "name": "Tag 1",
      "status": "ACTIVE"
    },
    {
      "id": 2,
      "name": "Tag 2",
      "status": "ACTIVE"
    },
    {
      "id": 3,
      "name": "Tag 3",
      "status": "ACTIVE"
    }
  ]
}

15. Create a URL Whitelist Tag

15.1. Request

Create a URL Whitelist Tag

URI

POST /filter/url/tag

Table 38. Request Body

tag.name [String] required

The name of the tag

Example Request JSON
{
  "tag": {
    "name": "Tag 1",
  }
}

15.2. Response

Table 39. Response Codes
Code Description

200

The request was successful. The response will contain a JSON body.

400

The request was invalid and/or malformed. The response will contain an Errors JSON Object with the specific errors.

401

You did not supply a valid Authorization header. The header was omitted or your API key was not valid. The response will be empty. See Authentication.

402

Your license has expired. The response will be empty. Contact sales@cleanspeak.com for assistance.

500

There was an internal error. A stack trace is provided and logged in the CleanSpeak log files. The response will be empty.

Table 40. Response Body

tag.id [Integer]

The Id of the tag

tag.name [String]

The name of the tag. This is only used for UI purposes.

tag.status [String]

The approval state of the entry

Example Response JSON
{
  "tag": {
    "id": 42,
    "name": "Tag 1",
    "status": "ACTIVE"
  }
}

16. Update a URL Whitelist Tag

16.1. Request

Update a URL Whitelist Tag

URI

PUT /filter/url/tag/{id}

Table 41. Request Parameters

name [Integer] required

The unique id of the URL whitelist tag to update.

Table 42. Request Body

tag.name [String] required

The name of the tag

Example Request JSON
{
  "tag": {
    "name": "Tag 1",
  }
}

16.2. Response

Table 43. Response Codes
Code Description

200

The request was successful. The response will contain a JSON body.

400

The request was invalid and/or malformed. The response will contain an Errors JSON Object with the specific errors.

401

You did not supply a valid Authorization header. The header was omitted or your API key was not valid. The response will be empty. See Authentication.

402

Your license has expired. The response will be empty. Contact sales@cleanspeak.com for assistance.

404

The object you are trying to update doesn’t exist. The response will be empty.

500

There was an internal error. A stack trace is provided and logged in the CleanSpeak log files. The response will be empty.

Table 44. Response Body

tag.id [Integer]

The Id of the tag

tag.name [String]

The name of the tag. This is only used for UI purposes.

tag.status [String]

The approval state of the entry

Example Response JSON
{
  "tag": {
    "id": 42,
    "name": "Tag 1",
    "status": "ACTIVE"
  }
}

17. Delete a URL Whitelist Tag

17.1. Request

Delete a URL Whitelist Tag by Id

URI

DELETE /filter/url/tag/{id}

Table 45. Request Parameters

id [Integer] required

The unique id of the URL Whitelist tag to delete.

17.2. Response

Table 46. Response Codes
Code Description

200

The request was successful. The response will be empty.

400

The request was invalid and/or malformed. The response will contain an Errors JSON Object with the specific errors.

401

You did not supply a valid Authorization header. The header was omitted or your API key was not valid. The response will be empty. See Authentication.

402

Your license has expired. The response will be empty. Contact sales@cleanspeak.com for assistance.

404

The object you are trying to delete doesn’t exist. The response will be empty.

500

There was an internal error. A stack trace is provided and logged in the CleanSpeak log files. The response will be empty.