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_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`	object	Covers the information related to Global Telltales
	`global.score`	number	Global risk score (0–100)
	`global.telltales`	array	Provides the breakdown of the telltales and the weight of each
	`global.telltales.name`	string	Provides the global telltale name
	`global.telltales.weight`	number	Provides the score associated with the global telltale
	`custom`	object	Covers the information related to Custom Telltales
	`custom.score`	number	Custom risk score (0–100)
	`custom.telltales`	array	Provides the breakdown of the telltales and the weight of each
	`custom.telltales.name`	string	Provides the custom telltale name
	`custom.telltales.weight`	number	Provides the score associated with the custom telltale
`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",
          "default": ""
        },
        "session_created": {
          "type": [
            "string",
            "null"
          ],
          "format": "date-time",
          "default": null
        },
        "telltale_user": {
          "type": "string",
          "minLength": 0,
          "maxLength": 128
        },
        "telltale_list": {
          "type": [
            "array",
            "null"
          ],
          "items": {
            "type": "string",
            "minLength": 0,
            "maxLength": 128
          }
        }
      },
      "required": [
        "session",
        "session_created",
        "telltale_user",
        "telltale_list"
      ]
    },
    "ip_intelligence": {
      "type": "object",
      "properties": {
        "user_ip": {
          "anyOf": [
            {
              "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
        },
        "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",
        "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": {
          "type": "object",
          "properties": {
            "score": {
              "type": "number"
            },
            "telltales": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string"
                  },
                  "weight": {
                    "type": "number"
                  }
                }
              }
            }
          }
        },
        "custom": {
          "type": "object",
          "properties": {
            "score": {
              "type": "number"
            },
            "telltales": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string"
                  },
                  "weight": {
                    "type": "number"
                  }
                }
              }
            }
          }
        }
      },
      "required": [
        "risk_category",
        "risk_band",
        "global",
        "custom"
      ]
    },
    "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": "Low",
    "global": {
      "score": 20,
      "telltales": [
        {
            "name": "g-rta-isp-velocity-short-term-abuse",
            "weight": 20
        }
      ]
    },
    "custom": {
      "score": 0,
      "telltales": []
    }
  },
  "aggregations": {
    "ip": {
      "short_term": {
        "interval_minutes": 60,
        "count": 2,
        "threshold": 11
      },
      "long_term": {
        "interval_minutes": 1440,
        "count": 3,
        "threshold": 50
      }
    }
  },
  "error": ""
}