Send Visit Events With the REST API

Request

Call this endpoint for every pageview, MCP call, and agentic commerce interaction using ACP or UCP.

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. MCP requires `mcp-protocol-version`; ACP requires `api-version`; UCP requires `ucp-agent`.
`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.
`metadata`	`object`	No	Key-value pairs to associate with the event. Values can be strings, numbers, or booleans.

MCP Fields (Optional)

Field	Type	Required	Description
`mcp_request_method`	`string`	No	The MCP `mcp_request_body.method`, if it exists.
`mcp_request_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, pass the parsed JSON response body. For MCP, pass `mcp_response_body.result`.
`ucp_response_body`	`object`	No	The UCP response body, if it exists. For REST, pass the parsed JSON response body. For MCP, pass `mcp_response_body.result`.

Tips

Add this in middleware to track pageviews and supported interactions from a single place.
Send analytics outside your page response path. Use a background task or queue when available, and never let analytics failures affect the response.
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_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_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.