← Back

Identify Agents With the REST API

Overview

Use the REST API to identify and verify legitimate AI agents, crawlers, and bots from a network request. Known Agents identifies agents using Web Bot Auth (HTTP message signatures), IP matching, or other available methods. This can be useful for implementing access policies based on verified agent identity. Please contact us if you need help getting set up.

Request

URL
URL https://api.knownagents.com/agent-identifications
HTTP Method POST
Headers
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 with the fields below.
id 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 An object containing all HTTP request headers, including user-agent, any IP-related headers like x-forwarded-for or x-real-ip, and HTTP message signature headers like signature-input, signature, and signature-agent.

Example

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

Tips

Response

Body
Returns a single object or an array of objects (matching the request format) with the fields below.
id The identifier from the request (if provided).
result The verification result:
  • "verified": The agent was identified and verified
  • "verification_failed": The agent was identified, but failed verification (it was spoofed)
  • "not_verifiable": The agent was identified, but could not be verified (no verification method available)
  • "unknown_agent": The request was from a human, or an agent not yet in our database
agent_id The unique ID of the agent (if identified).
agent_token The name of the agent (if identified).
agent_url The documentation URL of the agent (if identified).
agent_type_name The type of agent (if identified).
operator_name The company behind the agent (if identified).

Example

[
    {
        "id": "request-1",
        "result": "verified",
        "agent_id": "697b4527",
        "agent_token": "Claude-User",
        "agent_url": "https://knownagents.com/agents/claude-user",
        "agent_type_name": "AI Assistant",
        "operator_name": "Anthropic"
    },
    {
        "id": "request-2",
        "result": "unknown_agent"
    }
]