Help JSON API reference · OpenD Documentation

Authentication and CORS

Each request is either a reader's, with a token, or anonymous, on a public site.

With a token: Send an embed token, the same kind the widget uses: Authorization: Bearer <token>. See Sign embed tokens in your backend. The answer is filtered for that reader, on their release line.

Browser requests must come from one of the allowed embed origins; others get 403 {"error":"origin not allowed"}. Requests without an Origin header, such as from your backend, are allowed.

Preflight OPTIONS requests are answered for allowed origins, permitting GET and the authorization header.

Responses are sent with Cache-Control: private, no-store.
Anonymous, on a public site: Send no Authorization header at all. On a site whose access is public (see Make a site public or private), the answer is exactly what an anonymous visitor of the site reads: the public entitlements, on the release the site serves anonymous visitors. Nothing to sign, and no secret to copy into your app.

It works with embedding off: OPEND_EMBED_SECRET and OPEND_EMBED_ORIGINS are not needed, because the answers hold nothing the public site does not show.

Any origin may read it: responses carry Access-Control-Allow-Origin: * and never use credentials. Server-to-server requests, without an Origin, work the same. The help panel itself and token requests keep their origin rules.

Responses are the same for everyone at a version, so they are sent with Cache-Control: public, max-age=60 and Vary: Origin, Authorization. A new release reaches callers within a minute.

On a private site, an anonymous request gets 401, as one with a bad token does. A request with an invalid token never falls back to the anonymous view.

The site's version cookie is ignored; only the version parameter chooses a version.

Choosing a version anonymously

Anonymous requests take an optional version query parameter on every endpoint, such as /api/v1/help/nav?version=0.22. It is honoured exactly as the site honours a reader's choice in the version picker (see Let readers choose the version they read): only a version the picker offers anonymous visitors is served. With the picker set to live, a version is matched by its release line, so 0.22.1 asks for 0.22. Anything else (a version that is not offered, a retired line, a version that never existed, or text that is not a version) is answered from the default release, never with an error, so the answer does not reveal which versions exist. Token requests ignore the parameter.

Which release answered

Every answer from a release, with a token or anonymous, names it in two headers, so a caller that asked for one version and was given the default can tell:

OpenD-Release: 0.23.1
OpenD-Release-Line: 0.23

They are listed in Access-Control-Expose-Headers, so browser scripts can read them. Errors before a release is chosen (401, 403) have neither.

GET /api/v1/help/context

The help for a context. Query parameters: app (required), and key or path. Resolves as described in How a context resolves, and its fallback rules.

curl -H "Authorization: Bearer $TOKEN" \
  "https://docs.example.com/api/v1/help/context?app=opend-console&path=/tenants/acme"

{
  "key": "tenants",
  "via": "parent",
  "fragment": null,
  "topicId": "topics/next/console",
  "title": "Operator console (coming soon)",
  "shortdesc": "…",
  "html": "<article class=\"concept topic\" id=\"console\">…</article>",
  "related": [],
  "fullUrl": "https://docs.example.com/topics/next/console.html",
  "embedUrl": "https://docs.example.com/embed/topics/topics/next/console.html"
}

Field	Meaning
`key`, `via`	The key that matched, and how: `key`, `parent` or `default`.
`fragment`	The element or nested topic to scroll to, or `null`. It is `null` when that element is filtered out for this reader, so it never names a section they cannot see.
`topicId`	The topic's page id, for `/api/v1/help/topics/`.
`title`, `shortdesc`	Plain text, filtered for the reader.
`html`	The topic as an HTML `article`, filtered for the reader, with absolute links to the docs site. Sanitize or sandbox it like any HTML you did not write.
`related`	Up to eight visible children and siblings in the navigation.
`fullUrl`, `embedUrl`	The page on the docs site, and in the panel. `embedUrl` is `null` when embedding is not configured, as there is no panel.

GET /api/v1/help/topics/<topicId>

One topic by page id, such as /api/v1/help/topics/topics/help/widget. Same fields as above, without key, via and fragment.

GET /api/v1/help/nav

The reader's table of contents, for a help sidebar: filtered exactly as the docs site's contents. Topics the reader cannot see are left out, and never lend their title to anything; a heading with nothing visible under it is left out too, and so are toc="no" entries.

{
  "title": "Widget Platform Docs",
  "release": "2.1",
  "line": "2",
  "nav": [
    { "title": "Getting started", "children": [
      { "title": "Overview", "topicId": "topics/overview", "children": [] },
      { "title": "Install the Widget", "topicId": "topics/install", "children": [] } ] }
  ]
}

Field	Meaning
`title`, `release`, `line`	The site's title, and the release and release line the reader is served.
`nav`	The entries, in map order. Each has a `title` and `children`; a topic also has its `topicId`, which `/api/v1/help/topics/` accepts. An entry without `topicId` is a heading, and always has children.

GET /api/v1/help/search?q=

Searches only the topics this reader can see, and only the parts of them this reader can see. Every word must appear, in any form (installing finds install). Quote a phrase ("setup wizard"), use or between alternatives, and put - before a word to exclude it. The last word also matches as a prefix, for search as you type. Title matches weigh most, then the short description, then the body. Up to ten hits, best first; score is a relative rank.

{ "query": "token", "hits": [
  { "topicId": "topics/help/tokens", "title": "Sign embed tokens in your backend",
    "snippet": "…prove that with a short-lived token signed…", "score": 0.6079 } ] }

Errors

Status	When
401	The token is invalid or expired, or there is none and the site is private.
403	The origin is not allowed, the email is not a registered reader of that organization, or the organization has no entitlements.
404	No help for this context, no such topic (or one the reader cannot see), or nothing published yet for the reader's release line.

Errors are JSON: {"error": "..."}.

Images

Image URLs in html point at the docs site. On a public site, the images of anonymous answers at the default version open without signing in, like the site's own pages. Otherwise they need a docs session: if your app renders help natively and the topics contain gated images, proxy them through your backend.