Edge API Response Parameters

ℹ️

Coming Soon:

The Edge API is part of the Arkose Edge Product and is currently under development. It is expected to launch in early Q3-2025. The specifications below are tentative and might change.

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

Name

Type

Required / Optional

Description

recommended_action

string

Required

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

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

error

string

Required

Error message, if any.

session_details

object

Required

Metadata about the evaluated session.

ip_intelligence

object

No

Information about the IP address and its attributes.

session_risk

object

No

Risk assessment results.

aggregations

object

No

Aggregated request statistics for the IP.

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": {
        "global": {
          "type": "object",
          "properties": {
            "score": {
              "type": "number"
            },
            "telltales": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string"
                  },
                  "weight": {
                    "type": "number"
                  }
                },
                "required": [
                  "name",
                  "weight"
                ]
              }
            }
          },
          "required": [
            "score",
            "telltales"
          ]
        },
        "custom": {
          "type": "object",
          "properties": {
            "score": {
              "type": "number"
            },
            "telltales": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string"
                  },
                  "weight": {
                    "type": "number"
                  }
                },
                "required": [
                  "name",
                  "weight"
                ]
              }
            }
          },
          "required": [
            "score",
            "telltales"
          ]
        },
        "risk_category": {
          "type": "string"
        },
        "risk_band": {
          "type": "string"
        }
      },
      "required": [
        "global",
        "custom",
        "risk_band"
      ]
    },
    "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"
  ]
}