---
title: "Record a visible article view or submitted search"
method: POST
path: "/hd/desks/{desk_id}/kb/events"
tags: ["hd"]
---

# Record a visible article view or submitted search

`POST /hd/desks/{desk_id}/kb/events`

## Request

- Base URL: `https://api.sparkvault.com/v1`
- URL: `https://api.sparkvault.com/v1/hd/desks/{desk_id}/kb/events`
- Auth: none required
- TypeScript: <https://skmtc.dev/sparkvault/apis/sparkvault-api/docs/hd/desks/:desk_id/kb/events/post.ts> (a function with typed inputs; its response is checked against the schema)

Called by the public knowledge base after page paint or an explicit interaction, never by its HTML/HEAD renderer. No bearer token or cookie is required. The Origin must be an approved HTTPS host for this desk, and the current publication must still be enabled. Rate limits apply before visitor draws and interaction writes; no raw IP, user-agent, referrer or search text is stored in analytics. A retry records no second count. Article/category attribution comes from the current published membership, never caller-supplied metadata. Search counts describe the results the static browser search showed. No GET records events.

## Path parameters

- `desk_id` string, required

## Headers

- `Origin` string, uri, required

## Request body

- union
  - object
    - `visitor_id` string, required: The 30-day pseudonym returned by POST /kb/visitor. It is scoped to this desk, never an authentication credential.
    - `release_id` string, required: The immutable release ID embedded in the page.
    - `event_id` string, required: Milliseconds since epoch, a hyphen and a page ordinal. Retry the original ID and body. Accepted for 24 hours, with at most 60 seconds future skew; receipts survive 48 hours so old replays cannot outlive them.
    - `type` 'view', required
    - `article_id` string, required
  - object
    - `visitor_id` string, required: The 30-day pseudonym returned by POST /kb/visitor. It is scoped to this desk, never an authentication credential.
    - `release_id` string, required: The immutable release ID embedded in the page.
    - `event_id` string, required: Milliseconds since epoch, a hyphen and a page ordinal. Retry the original ID and body. Accepted for 24 hours, with at most 60 seconds future skew; receipts survive 48 hours so old replays cannot outlive them.
    - `type` 'search', required
    - `result_count` integer, required

## Response `200`

The saved result.

- object
  - `data` object, required
    - `recorded` boolean, required
  - `meta` ResponseMeta: Envelope metadata present on every successful response.
    - `api_version` string
    - `request_id` string
    - `response_ms` integer
    - `timestamp` integer: Unix seconds.
    - `pools` object: Storage and bandwidth capacity snapshot for the account.
    - `billing` object
      - `past_due` boolean
    - `quota` object: This minute of the account request budget. Present on authenticated success responses that passed the throttle; absent otherwise.
      - `limit` integer
      - `used` integer
      - `remaining` integer
      - `resets_at` integer: Unix seconds.

## Other responses

- `400`: VALIDATION_ERROR — the request contains an invalid or unsupported value.
- `403`: KB_ORIGIN_REQUIRED — the Origin is missing, unsafe or belongs to another desk.
- `409`: KB_PUBLICATION_CHANGED or CONFLICT — reload a changed publication, or renew an expired visitor.
- `413`: PAYLOAD_TOO_LARGE — a JSON interaction body is at most 1024 bytes.
- `429`: RATE_LIMIT_EXCEEDED — wait for the Retry-After interval.
- `503`: The desk is unavailable or its budget/publication store could not be read. Try again later.

## Changes

- **2026-10-28** `a9a10e328ba5`: 1 breaking, 24 info
  - added the new path request parameter `desk_id`
  - the response property `error/details` became required for the status `400`
  - the response property `error/details` became required for the status `403`
  - the response property `error/details` became required for the status `409`
  - …21 more
- **2026-10-28** `56d7c265a77a`: 6 breaking
  - the response property `error/details` became nullable for the status `400`
  - the response property `error/details` became nullable for the status `403`
  - the response property `error/details` became nullable for the status `409`
  - the response property `error/details` became nullable for the status `413`
  - …2 more
- **2026-10-27** `ac44ec1f8cfa`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/sparkvault/apis/sparkvault-api/changes/hd/desks/:desk_id/kb/events/post.md)

---

[API](https://skmtc.dev/sparkvault/apis/sparkvault-api.md) - [All operations](https://skmtc.dev/sparkvault/apis/sparkvault-api/llms.txt) - [OpenAPI document](https://skmtc.dev/sparkvault/apis/sparkvault-api/revisions/97cfadccd0c0?raw)