---
title: "Create an anonymous knowledge base visitor"
method: POST
path: "/hd/desks/{desk_id}/kb/visitor"
tags: ["hd"]
---

# Create an anonymous knowledge base visitor

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

## Request

- Base URL: `https://api.sparkvault.com/v1`
- URL: `https://api.sparkvault.com/v1/hd/desks/{desk_id}/kb/visitor`
- Auth: none required
- TypeScript: <https://skmtc.dev/sparkvault/apis/sparkvault-api/docs/hd/desks/:desk_id/kb/visitor/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. Minted lazily through the Entropy service, at most 600 per network address per hour across desks. The server stores only its hash for 30 days. Cache-Control is no-store; keep it locally per desk and handle storage failures without blocking content.

## Path parameters

- `desk_id` string, required

## Headers

- `Origin` string, uri, required

## Request body

- object
  - `release_id` string: The immutable release ID embedded in the page.

## Response `200`

The saved result.

- object
  - `data` object, required
    - `visitor_id` string, required: The 30-day pseudonym returned by POST /kb/visitor. It is scoped to this desk, never an authentication credential.
    - `expires_at` integer, 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/visitor/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)