Send Visit Events With the REST API

Request

Call this endpoint for every pageview, MCP call, and agentic commerce interaction using ACP or UCP. See the Cloudflare Worker guide for an example that populates all of the fields.

Endpoint

HTTP Method	`POST`
URL	`https://api.knownagents.com/visits`

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

Field	Type	Required	Description
`request_path`	`string`	Yes	The URL path of the incoming request.
`request_method`	`string`	Yes	The HTTP method of the incoming request (e.g. `GET`, `POST`).
`request_headers`	`object`	Yes	The HTTP headers of the incoming request, as a key-value object. This should at least include `user-agent`, any IP-related headers (e.g. `x-forwarded-for`), and `referer` when available.
`response_status_code`	`number`	No	The HTTP status code of the response (e.g. `200`, `404`).
`response_headers`	`object`	No	The HTTP headers of the response, as a key-value object. This should at least include `content-type` if available.
`response_duration_in_milliseconds`	`number`	No	The time taken to process the request and generate the response, in milliseconds.

MCP Fields (Optional)

Field	Type	Required	Description
`mcp_request_method`	`string`	No	The MCP `mcp_request_body.method`, if it exists.
`mcp_request_tool_name`	`string`	No	The MCP `mcp_request_body.params.name`, if it exists.
`mcp_request_client_info_name`	`string`	No	The MCP `mcp_request_body.params.clientInfo.name`, if it exists.
`mcp_request_client_info_version`	`string`	No	The MCP `mcp_request_body.params.clientInfo.version`, if it exists.
`mcp_response_result_is_error`	`boolean`	No	The MCP `mcp_response_body.result.isError`, if it exists.
`mcp_response_error_code`	`number`	No	The MCP `mcp_response_body.error.code`, if it exists.
`mcp_response_error_message`	`string`	No	The MCP `mcp_response_body.error.message`, if it exists.

Agentic Commerce Fields (Optional)

Field	Type	Required	Description
`acp_response_body`	`object`	No	The ACP response body, if it exists. For REST responses, pass the JSON response body. For MCP tool call responses, pass `mcp_response_body.result`.
`ucp_response_body`	`object`	No	The UCP response body, if it exists. For REST responses, pass the JSON response body. For MCP tool call responses, pass `mcp_response_body.result.structuredContent`.

Tips

Add this in middleware to track pageviews and supported interactions from a single place.
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.
Strip out any sensitive fields from ACP and UCP response bodies before sending them.

Example

curl -X POST https://api.knownagents.com/visits \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '[
    {
        "request_path": "/articles/1234",
        "request_method": "GET",
        "request_headers": { "...": "..." },
        "response_status_code": 200,
        "response_headers": { "...": "..." },
        "response_duration_in_milliseconds": 45
    },
    {
        "request_path": "/mcp",
        "request_method": "POST",
        "request_headers": { "...": "..." },
        "response_status_code": 200,
        "response_headers": { "...": "..." },
        "response_duration_in_milliseconds": 32,
        "mcp_request_method": "tools/call",
        "mcp_request_tool_name": "get_weather",
        "mcp_request_client_info_name": "Claude",
        "mcp_request_client_info_version": "1.0.0",
        "mcp_response_result_is_error": false
    },
    {
        "request_path": "/acp",
        "request_method": "POST",
        "request_headers": { "...": "..." },
        "response_status_code": 200,
        "response_headers": { "...": "..." },
        "response_duration_in_milliseconds": 38,
        "mcp_request_method": "tools/call",
        "mcp_request_tool_name": "complete_checkout_session",
        "mcp_request_client_info_name": "ChatGPT",
        "mcp_request_client_info_version": "1.0.0",
        "mcp_response_result_is_error": false,
        "acp_response_body": { "...": "..." }
    }
]'

Response

The endpoint returns 204 No Content when events are accepted.

Test Your Integration

Navigate to the Projects page
Select your project
Click Settings
Click Send a Test Visit
Click Realtime

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