---
title: "Look up a help desk by its host"
method: GET
path: "/hd/desks"
tags: ["hd"]
---

# Look up a help desk by its host

`GET /hd/desks`

## Request

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

Which desk the host a portal runs on is, and how its customers sign in: the portal sends the host name it is served on, then names the desk by `desk_id` in every customer route. A host the organization has moved away from answers where it moved. Every host that is no desk answers the same 404, and every desk that does not take customers now the same 503, whatever the reason. Needs no credential; each client address spends a budget of lookups a minute.

## Query parameters

- `host` string, required

## Response `200`

The desk, or where it moved.

- object
  - `data` union, required: The desk a portal host is, or where a changed address moved to.
    - object
      - `kind` 'desk', required
      - `desk_id` string, required: The desk: every customer route names it in its path.
      - `handle` string, required
      - `canonical_host` string, required: The desk's address in links and email.
      - `organization_name` string, nullable, required
      - `branding` object, required
        - `color` string, nullable, required
      - `auth_mode` 'identity' | 'email_pin' | 'identity_unavailable', required: How customers sign in now; identity_unavailable: they cannot sign in at the moment.
      - `identity` object, nullable, required: The Secure Identity client customers sign in with; null unless `auth_mode` is identity.
        - `issuer_account_id` string, required
        - `client_id` string, required
      - `customer_can_mark_resolved` boolean, required
      - `knowledge_base_enabled` boolean, required: Whether the published knowledge base is enabled and not paused by a lifecycle change. False by default; the portal can link to the static root when true.
      - `portal_client` 'help-desk-portal', required: The X-SV-Client value the portal sends.
    - object
      - `kind` 'moved', required
      - `moved_to` string, required: The desk's address now: the organization changed its handle.
  - `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 — `host` is missing or is no host name.
- `404`: DESK_NOT_FOUND — no help desk is at this address.
- `429`: RATE_LIMIT_EXCEEDED — this client address has spent its lookups for the minute. `Retry-After` carries the seconds until the budget reopens, and `details` carries `limit` and `resets_at`.
- `503`: HELP_DESK_UNAVAILABLE — the desk does not take customers right now. BUDGET_UNAVAILABLE — a budget the request spends could not be counted, so the request was refused rather than let through uncounted; `Retry-After` carries the seconds to wait before trying again.

## Changes

- **2026-10-28** `a9a10e328ba5`: 16 info
  - the response property `error/details` became required for the status `400`
  - the response property `error/details` became required for the status `404`
  - the response property `error/details` became required for the status `429`
  - the response property `error/details` became required for the status `503`
  - …12 more
- **2026-10-28** `56d7c265a77a`: 4 breaking
  - the response property `error/details` became nullable for the status `400`
  - the response property `error/details` became nullable for the status `404`
  - the response property `error/details` became nullable for the status `429`
  - the response property `error/details` became nullable for the status `503`
- **2026-10-27** `ac44ec1f8cfa`: 1 info
  - added the required property `data/oneOf[subschema #1]/knowledge_base_enabled` to the response with the `200` status
- **2026-10-22** `f5ac9c809ef7`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/sparkvault/apis/sparkvault-api/changes/hd/desks/get.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)