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 |
---|---|---|---|
| string | Recommended action values: Note: | |
| string | Error message, if any | |
| object | Metadata about the evaluated session | |
| string | Unique session identifier | |
| string | Timestamp indicating when session was created | |
| string | Primary telltale reason or label | |
| array | List of all telltales associated with the session | |
| object | Information about the IP address and its attributes | |
| string | IP address of the user | |
| boolean | True if user is behind a known proxy | |
| boolean | True if the user is bot | |
| boolean | True if user is using a VPN | |
| boolean | True if user is using Tor | |
| string | Country where the IP is located | |
| string | Region/state of the IP | |
| string | City of the IP | |
| string | Internet Service Provider | |
| boolean | True if connection is from a public access point | |
| string | Type of network | |
| string | Latitude of IP geolocation | |
| string | Longitude of IP geolocation | |
| string | Timezone | |
| number | Autonomous System Number associated with the IP | |
| object | Risk assessment results. | |
| string | Risk classification | |
| string | Risk severity level: | |
| number | Global risk score (0–100) | |
| number | Custom-configured risk score (0–100) | |
| object | Aggregated request statistics for the IP. | |
| string | Error String in case of errors during Aggregations | |
| object | IP-level aggregation | |
| object | Recent IP activity | |
| int | Time window in minutes | |
| int | Number of events seen | |
| int | Threshold for flagging | |
| object | Longer IP activity window (e.g., past 24 hours) | |
| int | Time window in minutes | |
| int | Number of events seen | |
| int | Threshold for flagging | |
| 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": ""
}
Updated 16 days ago