REST API reference · Henkan Vision Docs

Read sites, sessions, timelines, summaries and patterns over HTTPS with an API key. Every endpoint is read-only and returns JSON.

The REST API exposes the same data as the MCP server. Use it for reports, notebooks or your own tools.

The tool reference on the API & MCP page, with search_sessions expanded.

Authentication#

Send your API key as a Bearer token. Base URL: https://vision.henkanpartners.ai/api/v1.

curl -H "Authorization: Bearer <your-api-key>" https://vision.henkanpartners.ai/api/v1/sites

Keys look like hv_live_ followed by 43 characters. See API keys.

Endpoints#

Method and path	MCP tool	Returns
`GET /api/v1/sites`	`list_sites`	Sites of your organisation.
`GET /api/v1/sites/:siteId/overview`	`get_site_overview`	Figures for a period.
`GET /api/v1/sessions`	`search_sessions`	Sessions, newest first.
`GET /api/v1/sessions/:id/timeline`	`get_session_timeline`	Steps and friction tags of a session.
`GET /api/v1/sessions/:id/summary`	`get_session_summary`	The existing AI summary of a session.
`GET /api/v1/patterns`	`list_patterns`	Patterns over the last 30 days.
`GET /api/v1/patterns/:id`	`get_pattern`	One pattern with example sessions.

Parameters#

Endpoint	Parameter	Type	Description
Sites	`cursor`, `limit`	string, integer	Paging. `limit` is 1–100, default 50.
Site overview	`range`	`24h`, `7d` or `30d`	Period. Defaults to `7d`.
Sessions	`site`	UUID	Only this site.
Sessions	`from`, `to`	ISO date-time	Start and end, for example `2026-10-01T00:00:00Z`.
Sessions	`friction`	string	A friction type such as `rage_click` or `checkout_exit`, or `any`.
Sessions	`kind`	`human`, `ai_agent` or `all`	Visitor type. Defaults to `human`.
Sessions	`converted`	boolean	Only converted, or only not converted, sessions.
Sessions	`entry`, `device`, `q`	string	Entry page, `desktop` / `mobile` / `tablet`, and text matched against the entry page.
Sessions	`cursor`, `limit`	string, integer	Paging. `limit` is 1–100, default 50.
Timeline	`cursor`, `limit`	string, integer	Paging of steps. `limit` is 1–400, default 200.
Patterns	`site`, `kind`	UUID, `human` or `ai_agent`	Filters. `kind` defaults to `human`.
Patterns	`cursor`, `limit`	string, integer	Paging. `limit` is 1–100, default 50.

Examples#

Mobile sessions that left from the checkout since 1 October:

curl -H "Authorization: Bearer <your-api-key>" \
  "https://vision.henkanpartners.ai/api/v1/sessions?friction=checkout_exit&device=mobile&from=2026-10-01T00:00:00Z"

{
  "sessions": [
    {
      "id": "6f1c2b9e-…",
      "site_id": "3b8d4a6f-…",
      "started_at": "2026-10-15T07:42:10Z",
      "duration_s": 79,
      "status": "ready",
      "pages": 2,
      "device": "mobile",
      "browser": "Safari",
      "os": "iOS",
      "country": "FR",
      "converted": false,
      "friction_types": ["dead_click", "checkout_exit"],
      "visitor_kind": "human",
      "agent_verified": false,
      "data": { "entry_path": "/products/linen-blazer", "agent_name": null }
    }
  ],
  "next_cursor": "…"
}

The timeline of one session:

curl -H "Authorization: Bearer <your-api-key>" \
  https://vision.henkanpartners.ai/api/v1/sessions/6f1c2b9e-…/timeline

{
  "session_id": "6f1c2b9e-…",
  "total_steps": 10,
  "truncated": false,
  "next_cursor": null,
  "data": {
    "steps": [
      { "t_ms": 0, "kind": "page_view", "page": "/products/linen-blazer" },
      { "t_ms": 26600, "kind": "click", "page": "/products/linen-blazer", "target": "Add to bag" }
    ],
    "friction_tags": [
      { "type": "dead_click", "at_ms": 26600, "page": "/products/linen-blazer", "detail": "Add to bag" }
    ]
  }
}

Paging#

Lists return up to 100 items per call. When there are more, the response has a next_cursor value: pass it as cursor to get the next page. When next_cursor is null, you have everything.

Errors#

Errors return a JSON body { "error": { "code": "…", "message": "…" } }.

Status	Code	When
400	`bad_request`, `invalid_cursor`	A parameter has the wrong format, or the cursor is not one the API returned.
401	`unauthorized`	The key is missing, malformed or revoked.
404	`not_found`	Unknown endpoint, or an id that does not exist in your organisation. Ids of other organisations always return 404.
404	`no_summary`	The session has no AI summary yet.
429	`rate_limited`	Too many requests. Wait for the number of seconds in the `Retry-After` header.
500	`internal`	Something went wrong on our side. Try again later.