← Back

Connect Your Backend to Agent & LLM Analytics

Overview

Use the REST API to connect your website with a backend written in any programming language. Please contact us if you need help getting set up.

Step 1: Start Tracking Visits

In the endpoints where you serve your pages, make an HTTP request to the REST API with information about incoming pageview requests.

URL
URL https://api.knownagents.com/visits
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 This needs to be set to application/json.
Body
Send either a single object or an array of objects with the fields below. High traffic websites should batch multiple visits together and send them periodically (e.g. every 30 seconds).
request_path The URL path of the incoming pageview request.
request_method The HTTP method of the incoming pageview request (e.g. GET).
request_headers The HTTP headers of the incoming pageview request, as a key-value object. This should at least include user-agent, referer, and any IP-related headers (e.g. x-forwarded-for).
response_status_code Optional. The HTTP status code of the response (e.g. 200, 404).
response_headers Optional. The HTTP headers of the response, as a key-value object. This should at least include content-type if available (e.g. {"content-type": "text/html"}).
response_duration_in_milliseconds Optional. The time taken to process the request and generate the response, in milliseconds.

Example

curl -X POST https://api.knownagents.com/visits \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '[
    {
        "request_path": "/pages/1234",
        "request_method": "GET",
        "request_headers": {
            "user-agent": "Mozilla/5.0...",
            "referer": "https://www.google.com",
            "x-forwarded-for": "203.0.113.42"
        },
        "response_status_code": 200,
        "response_headers": {
            "content-type": "text/html"
        },
        "response_duration_in_milliseconds": 45
    },
    {
        "request_path": "/about?foo=bar",
        "request_method": "GET",
        "request_headers": {
            "user-agent": "Mozilla/5.0...",
            "x-forwarded-for": "198.51.100.73"
        },
        "response_status_code": 200,
        "response_headers": {
            "content-type": "text/html"
        },
        "response_duration_in_milliseconds": 32
    }
]'

Tips

Step 2: Test Your Integration

If your website is correctly connected, you should see visits from a test agent in the realtime timeline within a few seconds.