Edge API Response Parameters

Overview

This section outlines how to make POST requests to the Arkose Labs Edge API, including endpoint structure, required headers, and request body format.

Response Body Parameters

Fields

Sub-Fields

Type

Description

recommended_action

string

Recommended action values: "allow", "block" or "challenge"

Note: "challenge" is a recommendation only. In this Product, Arkose Labs does not trigger any challenge or puzzle. Customer can decide on the appropriate end user action of whether to allow or block the user.

error

string

Error message, if any

session_details

object

Metadata about the evaluated session

session

string

Unique session identifier

session_created

string

Timestamp indicating when session was created

telltale_user

string

Primary telltale reason or label

telltale_list

array

List of all telltales associated with the session

ip_intelligence

object

Information about the IP address and its attributes

user_ip

string

IP address of the user

is_proxy

boolean

True if user is behind a known proxy

is_bot

boolean

True if the user is bot

is_vpn

boolean

True if user is using a VPN

is_tor

boolean

True if user is using Tor

country

string

Country where the IP is located

region

string

Region/state of the IP

city

string

City of the IP

isp

string

Internet Service Provider

public_access_point

boolean

True if connection is from a public access point

connection_type

string

Type of network

latitude

string

Latitude of IP geolocation

longitude

string

Longitude of IP geolocation

timezone

string

Timezone

asn

number

Autonomous System Number associated with the IP

session_risk

object

Risk assessment results.

risk_category

string

Risk classification

risk_band

string

Risk severity level: "Low", "Medium", "High"

global_risk_score

number

Global risk score (0–100)

custom_risk_score

number

Custom-configured risk score (0–100)

aggregations

object

Aggregated request statistics for the IP.

error

string

Error String in case of errors during Aggregations

ip

object

IP-level aggregation

ip.short_term

object

Recent IP activity

ip.short_term.interval_minutes

int

Time window in minutes

ip.short_term.count

int

Number of events seen

ip.short_term.threshold

int

Threshold for flagging

long_term

object

Longer IP activity window (e.g., past 24 hours)

long_term.interval_minutes

int

Time window in minutes

long_term.count

int

Number of events seen

long_term.threshold

int

Threshold for flagging

error

string

Error message if any occurred

Response Schema

The POST request should include a JSON body structure as show in the example below.

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "The edge-api response body schema",
  "type": "object",
  "properties": {
    "recommended_action": {
      "type": "string",
      "enum": ["allow", "block", "challenge"]
    },
    "session_details": {
      "type": "object",
      "properties": {
        "session": {
          "type": "string",
          "pattern": "^[0-9A-Fa-f]+\\.[0-9]{10}$"
        },
        "session_created": {
          "type": [
            "string",
            "null"
          ],
          "format": "date-time",
          "default": null
        },
        "telltale_user": {
          "type": "string",
          "minLength": 0,
          "maxLength": 128
        },
        "telltale_list": {
          "type": "array",
          "items": {
            "type": "string",
            "minLength": 0,
            "maxLength": 128
          }
        }
      },
      "required": [
        "session",
        "session_created",
        "telltale_user",
        "telltale_list"
      ]
    },
    "ip_intelligence": {
      "type": "object",
      "properties": {
        "user_ip": {
          "oneOf": [
            {
              "type": "string",
              "format": "ipv4"
            },
            {
              "type": "string",
              "format": "ipv6"
            },
            {
              "type": "null"
            }
          ],
          "default": null
        },
        "is_tor": {
          "type": "boolean",
          "default": false
        },
        "is_vpn": {
          "type": "boolean",
          "default": false
        },
        "is_proxy": {
          "type": "boolean",
          "default": false
        },
        "is_bot": {
          "type": "boolean",
          "default": false
        },
        "country": {
          "type": [
            "string",
            "null"
          ],
          "default": null
        },
        "region": {
          "type": [
            "string",
            "null"
          ],
          "default": null
        },
        "city": {
          "type": [
            "string",
            "null"
          ],
          "default": null
        },
        "isp": {
          "type": [
            "string",
            "null"
          ],
          "default": null
        },
        "public_access_point": {
          "type": "boolean",
          "default": false
        },
        "connection_type": {
          "type": [
            "string",
            "null"
          ],
          "default": null
        },
        "latitude": {
          "type": [
            "string",
            "null"
          ],
          "default": null
        },
        "longitude": {
          "type": [
            "string",
            "null"
          ],
          "default": null
        },
        "timezone": {
          "type": [
            "string",
            "null"
          ],
          "default": null
        }
      },
      "required": [
        "user_ip",
        "is_tor",
        "is_vpn",
        "is_proxy",
        "is_bot",
        "country",
        "region",
        "city",
        "isp",
        "public_access_point",
        "connection_type",
        "latitude",
        "longitude",
        "timezone"
      ]
    },
    "session_risk": {
      "type": "object",
      "properties": {
        "risk_category": {
          "type": [
            "string",
            "null"
          ],
          "default": null
        },
        "risk_band": {
          "type": [
            "string",
            "null"
          ],
          "default": null
        },
        "global_risk_score": {
          "type": [
            "number",
            "null"
          ],
          "default": null
        },
        "custom_risk_score": {
          "type": [
            "number",
            "null"
          ],
          "default": null
        }
      },
      "required": [
        "risk_category",
        "risk_band",
        "global_risk_score",
        "custom_risk_score"
      ]
    },
    "aggregations": {
      "type": "object",
      "properties": {
        "error": {
          "type": [
            "string",
            "null"
          ]
        },
        "ip": {
          "type": "object",
          "properties": {
            "short_term": {
              "type": "object",
              "properties": {
                "interval_minutes": {
                  "type": [
                    "integer",
                    "null"
                  ]
                },
                "count": {
                  "type": [
                    "integer",
                    "null"
                  ]
                },
                "threshold": {
                  "type": [
                    "integer",
                    "null"
                  ]
                }
              }
            },
            "long_term": {
              "type": "object",
              "properties": {
                "interval_minutes": {
                  "type": [
                    "integer",
                    "null"
                  ]
                },
                "count": {
                  "type": [
                    "integer",
                    "null"
                  ]
                },
                "threshold": {
                  "type": [
                    "integer",
                    "null"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "error": {
      "description": "An description of the error that caused the request to fail (if any)",
      "type": "string"
    }
  },
  "required": [
    "recommended_action",
    "session_details",
    "error"
  ]
}
{
  "recommended_action": "challenge",
  "session_details": {
    "session": "89818455d4249a528.5425182503",
    "session_created": "2025-06-02T23:22:50Z",
    "telltale_user": "g-rta-isp-velocity-short-term-abuse",
    "telltale_list": [
      "g-rta-isp-velocity-short-term-abuse"
    ]
  },
  "ip_intelligence": {
    "user_ip": "18.224.115.223",
    "is_proxy": true,
    "is_vpn": true,
    "is_tor": false,
    "country": "US",
    "region": "Ohio",
    "city": "Columbus",
    "isp": "Amazon.com",
    "public_access_point": false,
    "connection_type": "Data Center",
    "latitude": "39.89",
    "longitude": "-82.96",
    "timezone": "America/New_York",
    "asn": 16509
  },
  "session_risk": {
    "risk_category": "BOT-STD",
    "risk_band": "Medium",
    "global_risk_score": 50,
    "custom_risk_score": 30
  },
  "aggregations": {
    "ip": {
      "short_term": {
        "interval_minutes": 60,
        "count": 2,
        "threshold": 11
      },
      "long_term": {
        "interval_minutes": 1440,
        "count": 3,
        "threshold": 50
      }
    }
  },
  "error": ""
}