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.

Retrieve a TLD
Retrieve all TLDs
Create a TLD
Create bulk TLDs
Update a TLD
Delete a TLD

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.

Retrieve a Whitelisted URL
Retrieve all Whitelisted URLs
Create a Whitelisted URL
Update a Whitelisted URL
Delete a Whitelisted URL

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.

Retrieve a URL Whitelist Tag
Retrieve all URL Whitelist Tags
Create a URL Whitelist Tag
Update a URL Whitelist Tag
Delete a URL Whitelist Tag

2. Retrieve a TLD

2.1. Request

Retrieve a TLD by name

URI (3.x, deprecated in 4.0.0)

GET /filter/url/tld/{name}

URI (4.x)

GET /api/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 (3.x, deprecated in 4.0.0)

GET /filter/url/tld

URI (4.x)

GET /api/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 (3.x, deprecated in 4.0.0)

POST /filter/url/tld

URI (4.x)

POST /api/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 (3.x, deprecated in 4.0.0)

POST /filter/url/tld

URI (4.x)

POST /api/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 (3.x, deprecated in 4.0.0)

PUT /filter/url/tld/{name}

URI (4.x)

PUT /api/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 (3.x, deprecated in 4.0.0)

DELETE /filter/url/tld/{name}

URI (4.x)

DELETE /api/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 (3.x, deprecated in 4.0.0)

GET /filter/url/{id}

URI (4.x)

GET /api/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 (3.x, deprecated in 4.0.0)

GET /filter/url

URI (4.x)

GET /api/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 (3.x, deprecated in 4.0.0)

POST /filter/url

URI (4.x)

POST /api/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 (3.x, deprecated in 4.0.0)

PUT /filter/url/{id}

URI (4.x)

PUT /api/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 (3.x, deprecated in 4.0.0)

DELETE /filter/url/{id}

URI (4.x)

DELETE /api/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 (3.x, deprecated in 4.0.0)

GET /filter/url/tag/{id}

URI (4.x)

GET /api/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 (3.x, deprecated in 4.0.0)

GET /filter/url/tag/{name}

URI (4.x)

GET /api/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 (3.x, deprecated in 4.0.0)

GET /filter/url/tag

URI (4.x)

GET /api/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 (3.x, deprecated in 4.0.0)

POST /filter/url/tag

URI (4.x)

POST /api/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 (3.x, deprecated in 4.0.0)

PUT /filter/url/tag/{id}

URI (4.x)

PUT /api/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 (3.x, deprecated in 4.0.0)

DELETE /filter/url/tag/{id}

URI (4.x)

DELETE /api/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.