← Back
Verify 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 verifies 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-verifications |
| 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 | |
request_path |
The request path (e.g. "/" or "/datasets/articles"). |
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-verifications \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"request_path": "/",
"request_headers": {
"user-agent": "Mozilla/5.0 (compatible; Googlebot/2.1; +http://www.google.com/bot.html)",
"x-forwarded-for": "66.249.66.1",
"signature-input": "sig1=(\"@method\" \"@authority\" \"@path\");created=1618884475;keyid=\"test-key-rsa-pss\"",
"signature": "sig1=:K2qGT5srn2OGbOIDzQ6kYT+ruaycnDAAUpKv+ePFfD0RAxn/1BUeZx/Kdrq32DrfakQ6bPsvB9aqZqognNT6be4olHROIkeV879RrsrObury8L9SCEibeoHyqU/yCjphSmEdd7WD+zrchK57quskKwRefy2iEC5S2uAH0EPyOZKWlvbKmKu5q4CaB8X/I5/+HLZLGvDiezqi6/7p2Gngf5hwZ0lSdy39vyNMaaAT0tKo6nuVw0S1MVg1Q7MpWYZs0soHjttq0uLIA3DIbQfLiIvK6/l0BdWTU7+2uQj7lBkQAsFZHoA96ZZgFquQrXRlmYOh+Hx5D4m8WyKQfnj=",
"signature-agent": "https://www.google.com"
}
}'
Tips
- Make this non-blocking to avoid adding latency to your page response.
- Handle errors in a way that doesn't make your page response fail too.
- Strip out any sensitive HTTP headers you don't want to send.
Response
The API returns a JSON response with the following fields:
result: The verification result:"verified": The agent is identified and verified"verification_failed": The agent was identified but could not be verified"unknown_agent": The agent is not in our database"not_verifiable": The agent cannot be verified (no verification method available)
agent_id: The unique ID of the agent (if identified)agent_token: The name of the agent (e.g."Googlebot") (if identified)agent_url: The documentation URL of the agent (if identified)agent_type_name: The type of agent (e.g."AI Agent") (if identified)operator_name: The company behind the agent (e.g."Google") (if identified)