---
title: "Save whether a published article was helpful"
method: POST
path: "/hd/desks/{desk_id}/kb/articles/{article_id}/helpful"
tags: ["hd"]
---

# Save whether a published article was helpful

`POST /hd/desks/{desk_id}/kb/articles/{article_id}/helpful`

## Request

- Base URL: `https://api.sparkvault.com/v1`
- URL: `https://api.sparkvault.com/v1/hd/desks/{desk_id}/kb/articles/{article_id}/helpful`
- Auth: none required
- TypeScript: <https://skmtc.dev/sparkvault/apis/sparkvault-api/docs/hd/desks/:desk_id/kb/articles/:article_id/helpful/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. Only an explicit click submits a vote. The same vote is a no-op; changing it atomically replaces one sample and advances its version while retaining its original day/category. Vote receipts outlive the visitor by one day; aggregates contain no visitor identifier. Clearing local storage can create a new pseudonym, so these counts do not claim unique people.

## Path parameters

- `desk_id` string, required
- `article_id` string, required

## Headers

- `Origin` string, uri, required

## Request body

- 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.
  - `vote` 'yes' | 'no', required

## Response `200`

The saved result.

- object
  - `data` object, required
    - `vote` 'yes' | 'no', required
    - `version` 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`: 2 breaking, 24 info
  - added the new path request parameter `article_id`
  - 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`
  - …22 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/articles/:article_id/helpful/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)