← Back

Identify Agents With the REST API

Request

Call this endpoint to identify agents from their incoming network requests.

Endpoint

HTTP Method POST
URL https://api.knownagents.com/agent-identifications

Headers

Header Value
Authorization A bearer token with your project's access token (e.g. Bearer YOUR_ACCESS_TOKEN). You can get your project's access token by navigating to the Known Agents Projects page, opening your project, and opening its settings page.
Content-Type Set to application/json.

Body

Send either a single object or an array of objects.

Field Type Required Description
request_id string No A string identifier that will be echoed back in the response. Include this when sending an array to match each result to its request.
request_headers object Yes An object containing all available HTTP request headers, including user-agent when present, any IP-related headers like x-forwarded-for or x-real-ip, and HTTP message signature headers like signature-input, signature, and signature-agent.
request_ip string No The IP address of the incoming request. Only include this when a valid IP address will not be available in request_headers.
request_path string No The path of the incoming request (e.g. "/products/123").

Example

curl -X POST https://api.knownagents.com/agent-identifications \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '[
    {
        "request_id": "request-1",
        "request_headers": { "...": "..." }
    },
    {
        "request_id": "request-2",
        "request_headers": { "...": "..." }
    }
]'

Tips

Response

Returns a single object or an array of objects matching the request format.

Fields

Field Type Required Description
request_id string No The identifier from the request (if provided).
result string Yes The identification result:
  • "verified": A known agent was identified and verified (its identity was confirmed as authentic)
  • "verification_failed": A known agent was identified, but failed verification (its identity may have been spoofed)
  • "not_verifiable": A known agent was identified, but its operator does not provide a known verification method
  • "not_identified": No known agent was identified (the request may have come from a human)
agent_id string No The unique ID of the identified agent.
agent_token string No The name of the agent (e.g. "Claude-User") (if identified).
agent_url string No The documentation URL of the agent (if identified).
agent_type_name string No The type of agent (e.g. "AI Assistant") (if identified).
operator_name string No The company operating the agent (e.g. "Anthropic") (if identified).
is_disallowed_by_robots_txt boolean No Whether the identified agent is disallowed by robots.txt from accessing the request_path.
asn number No The autonomous system number associated with the request's IP address.
asn_operator string No The operator of the recognized autonomous system associated with the request's IP address.
asn_type string No The type of the recognized autonomous system associated with the request's IP address:
  • "isp"
  • "hosting"
  • "business"
  • "education"
  • "government"
automation_score number No An integer from 0 to 99 indicating the strength of heuristic evidence that the request was made by an automated client. Higher scores indicate stronger detected automation signals. A score of 0 means that no automation signals were detected, not that the client is certainly human.
automation_signals string[] No Specific automation signals detected for the request. Available to Enterprise plans upon request:
  • "known_agent_ip": The request came from an IP address associated with a known agent, although no specific agent was identified
  • "inconsistency": The request contained inconsistent client or browser attributes
  • "non_browser": The request appears to have been made by a non-browser HTTP client
  • "automated_browser": The request contains indicators of browser automation
  • "cloud_service_provider": The request came from cloud or hosting infrastructure

Example

[
    {
        "request_id": "request-1",
        "result": "verified",
        "agent_id": "697b4527",
        "agent_token": "Claude-User",
        "agent_type_name": "AI Assistant",
        "operator_name": "Anthropic"
    },
    {
        "request_id": "request-2",
        "result": "not_identified"
    }
]