API Usage & Credits

Overview

The LMCS API provides dedicated endpoints for traffic filtering and validation. These endpoints help you to detect if incoming requests originate from automated bots, vulnerability scanners, or other unwanted sources.

Request validation endpoint

Endpoint URL: https://faray.tech/api/lmcscloud/urls/validate/request

This endpoint allows you to check if a requested path or User-Agent is commonly used by automated bots. It cross-references the input against our extensive, continuously updated blocklists. This is highly recommended as a preliminary step before executing resource-intensive operations on your server.

Pricing

The cost for a validation API request is a flat rate of 1 credit per request, regardless of the amount of pages or the length of the input.

You will not be charged for failed API requests (e.g., if a system error occurs).

Response latency

This API endpoint is heavily optimized for low-latency applications. Because it relies on local hash lookups and optimized regex patterns rather than complex matching algorithms, response times typically range between 15ms and 35ms.

Rate-limits

Because this endpoint is designed to handle raw traffic filtering, it offers significantly higher rate limits.

Rate limit level Limits
Level 1 50 RPM | 500 RPH | 10,000 RPW
Level 2 100 RPM | 1000 RPH | 10,000 RPD
Level 3 (default) 200 RPM | 5000 RPH | 100,000 RPD
Level 4 1000 RPM | 30000 RPH | 500,000 RPD
Level 5 3000 RPM | 100000 RPH | 2,500,000 RPD

All faray.tech accounts have rate limit level 3 selected by default. You can manually set stricter rate limits if you prefer to do so. Please Contact us if you need a higher rate limit.

Input arguments

The endpoint accepts a JSON payload with the following arguments:

Parameter Type Required Description
input String Yes The URL path that the user attempted to visit.
pages Array or String No A list of valid, discoverable pages on your website. Used to determine if the requested path conflicts with an existing file. Can be an array of strings or one large newline-separated string. Maximum 50,000 pages.
user_ua String No The User-Agent of the client to validate against our malicious bot blocklists.
validation_mode String No Limits the request validation scope. Options: normal, standard, uaonly (only verify the User-Agent), bponly (only verify the input path). Defaults to normal.
block_output String No Configures the amount of additional information that is output for requests which failed the validity checks. Options: normal, standard, omit, debug. Defaults to normal.
strip_exts Array No File extensions to strip from each page name before validation processing.
reject_exts Array No File extensions that should cause pages to not be considered during validation processing.
cms_installed Array No A list of CMS systems installed on your server (e.g., ["wp", "typo3"]) to set predefined path exclusions.

JSON Output

The endpoint returns a JSON response indicating whether the request is valid or blocked, along with detailed metadata.

Field Type Description
success Boolean Returns true if the request was processed successfully.
validity Boolean Returns true if the request passed validation, or false if it failed validation.
input String The original URL path provided in the request.
output String The original URL path if the request is valid. If the request is blocked, this will return 404.
blockreason String (Optional) The reason the request was blocked (e.g., blockedua, blockedpath). Only present if validity is false.
blockedfor Array (Optional) The specific rules or hashes that triggered the block. Omitted if block_output is set to omit.
blockedpaths Array (Optional) The specific pages that were blocked. Only present if block_output is set to debug.
metadata Object Detailed metadata about the request execution.
Meta Field Type Description
pages_amount Integer The number of pages processed during the validation check.
cms_installed Array The validated list of CMS systems used for path blocking.
blocklists Object Information about the blocklists used. Format: filename => hash:%rules (the xxh3 hash of our internal block list file, useful to track changes over time, followed by the amount of rules).
latency_ms Integer Total processing time in milliseconds.
cost Integer Amount of credits consumed by the request.
method String Always returns none as no link correction is performed.
mode String Always returns standard.

Example responses

Example Output 1 (successful validation, safe request)

(
    [success] => true
    [validity] => true
    [input] => /about-our-company
    [output] => /about-our-company
    [metadata] =>
        (
            [pages_amount] => 4
            [cms_installed] => []
            [blocklists] =>
                (
                    [blockedua] =>
                        (
                            [commonbots-fullstring-hashed.txt] => df8e1326ad3014b3:%43
                            [maliciousbots-fullstring-hashed.txt] => 97f5413a457aa694:%15
                            [maliciousbots-wildcard-hashed.txt] => 4a810bf527d20875:%14
                        )
                    [blockedpaths] =>
                        (
                            [arguments.txt] => 3126634b36652552:%10
                            [config-anywhere-block.txt] => 72f37d1fb5898179:%86
                            [general-anywhere-hardblock.txt] => 38cd5298344e25ee:%390
                            [general-rootdir-softblock.txt] => 90e0138f282976dc:%791
                            [typo3.txt] => 2bcb0804b1e96067:%12
                            [wp.txt] => d60249f2ea529a58:%35
                        )
                )
            [latency_ms] => 21
            [cost] => 1
            [method] => none
            [mode] => standard
        )
)

Example Output 2 (blocked request, malicious path detected)

(
    [success] => true
    [validity] => false
    [input] => /.env
    [output] => 404
    [blockreason] => blockedpath
    [blockedfor] =>
        (
            [0] => /(^|\/).*\.env($|\/)/i
        )
    [blockedpaths] =>
        (
            [0] => /app/v1/.env
            [1] => /api_keys.yml
        )
    [metadata] =>
        (
            [pages_amount] => 6
            [cms_installed] => []
            [blocklists] =>
                (
                    [blockedua] =>
                        (
                            [commonbots-fullstring-hashed.txt] => df8e1326ad3014b3:%43
                            [maliciousbots-fullstring-hashed.txt] => 97f5413a457aa694:%15
                            [maliciousbots-wildcard-hashed.txt] => 4a810bf527d20875:%14
                        )
                    [blockedpaths] =>
                        (
                            [arguments.txt] => 3126634b36652552:%10
                            [config-anywhere-block.txt] => 72f37d1fb5898179:%86
                            [general-anywhere-hardblock.txt] => fdb85702bd146156:%390
                            [general-rootdir-softblock.txt] => d04c81047a6cd9bd:%791
                            [typo3.txt] => 2bcb0804b1e96067:%12
                            [wp.txt] => 19dcf66533de7b24:%35
                        )
                )
            [latency_ms] => 24
            [cost] => 1
            [method] => none
            [mode] => standard
        )
)

Example Output 3 (blocked request, malicious User-Agent detected)

(
    [success] => true
    [validity] => false
    [input] => /phpmyadmin
    [output] => 404
    [blockreason] => blockedua
    [blockedfor] =>
        (
            [0] => 93c431d3eb999b7ef7fd85bc32d862e8ecb4990d91f8f5b8db1c38c1790e39ee
//User-Agent used in this test: sqlmap/1.0.9#dev (http://sqlmap.org)
        )
    [metadata] =>
        (
            [pages_amount] => 2
            [cms_installed] =>
                (
                    [0] => wp
                )
            [blocklists] =>
                (
                    [blockedua] =>
                        (
                            [commonbots-fullstring-hashed.txt] => df8e1326ad3014b3:%43
                            [maliciousbots-fullstring-hashed.txt] => 97f5413a457aa694:%15
                            [maliciousbots-wildcard-hashed.txt] => 4a810bf527d20875:%14
                        )
                    [blockedpaths] =>
                        (
                            [arguments.txt] => 3126634b36652552:%10
                            [config-anywhere-block.txt] => 72f37d1fb5898179:%86
                            [general-anywhere-hardblock.txt] => 56a4cc45348b0bbe:%390
                            [general-rootdir-softblock.txt] => c8cede5cc5e5fc38:%791
                            [typo3.txt] => 2bcb0804b1e96067:%12
                            [wp_installed.txt] => d60249f2ea529a58:%35
                        )
                )
            [latency_ms] => 23
            [cost] => 1
            [method] => none
            [mode] => standard
        )
)