List versions

Returns every published documentation version, newest first. With a valid bearer key, draft and archived versions are included too (each object carries `status`). Hidden working copies (`hidden: true`, `workingCopyOf`) are listed only with `includeWorkingCopies=true`.

Responses

200  Array of version objects.

Example

curl -X GET "https://rikaiso.com/api/help/v1/versions"

Create a version

Creates a documentation version. Answers 409 `conflict` when the slug already exists (use PATCH /versions/{version} to change one).

Request body

{
  "slug": "string, e.g. 2026.1",
  "label": "string, display label",
  "status": "draft (default) | published | archived",
  "languages": "array of language codes (default [en]); the first one is the primary language",
  "sortOrder": "number, optional",
  "isLatest": "boolean, optional — marks this published version as latest"
}

Responses

200  The stored version object.
401  Missing or invalid API key.
409  A version with this slug already exists.

Example

curl -X POST "https://rikaiso.com/api/help/v1/versions" \
  -H "Authorization: Bearer rk_help_xxx" \
  -H "Content-Type: application/json" \
  -d '{"slug":"string, e.g. 2026.1","label":"string, display label","status":"draft (default) | published | archived","languages":"array of language codes (default [en]); the first one is the primary language","sortOrder":"number, optional","isLatest":"boolean, optional — marks this published version as latest"}'

Update a version

Partially updates label, status, languages, sort order or latest flag: only the fields in the body change. `isLatest: true` needs a published version (clears the previous latest). Setting the status of a published version to `archived` unpublishes it.

Request body

{
  "label": "string, optional",
  "status": "draft | published | archived, optional",
  "languages": "array of language codes, optional",
  "sortOrder": "number, optional",
  "isLatest": "boolean, optional"
}

Responses

200  The updated version object.
404  Unknown version.

Example

curl -X PATCH "https://rikaiso.com/api/help/v1/versions/{version}" \
  -H "Authorization: Bearer rk_help_xxx" \
  -H "Content-Type: application/json" \
  -d '{"label":"string, optional","status":"draft | published | archived, optional","languages":"array of language codes, optional","sortOrder":"number, optional","isLatest":"boolean, optional"}'

Delete a version

Removes a version and every node and translation beneath it.

Responses

200  { ok: true }
404  Unknown version.

Example

curl -X DELETE "https://rikaiso.com/api/help/v1/versions/{version}" \
  -H "Authorization: Bearer rk_help_xxx"

Get the contents tree

Returns the nested section/topic tree of a published version. With a valid bearer key, draft and archived versions can be read as well.

Responses

200  { version, tree }
404  Version not published.

Example

curl -X GET "https://rikaiso.com/api/help/v1/versions/{version}/tree"

Get a topic

Returns one topic with its Markdown body, breadcrumbs, neighbours and `versionStatus`. Falls back to English when the requested language is missing. With a valid bearer key, topics of draft and archived versions can be read as well.

Responses

200  Topic object.
404  Topic not found.

Example

curl -X GET "https://rikaiso.com/api/help/v1/versions/{version}/topics/{slug}"

Create a node

Creates a section or topic in the version with its translations. Every translation language must be enabled on the version and the version's primary language (`languages[0]`) is required. Answers 409 `conflict` when the slug exists. The response carries the node's `updatedAt` and one per translation language, all valid as `expectedUpdatedAt` for follow-up writes.

Request body

{
  "slug": "string, unique within the version",
  "kind": "section | topic",
  "parentSlug": "string or null",
  "icon": "icon name or null",
  "sortOrder": "number",
  "translations": "object keyed by language: { title, summary, bodyMd }"
}

Responses

200  { id, slug, kind, parentSlug, icon, sortOrder, updatedAt, translations: { [lang]: { updatedAt } } }
400  A translation language is not enabled on the version, or the primary language is missing.
401  Missing or invalid API key.
409  A node with this slug already exists.

Example

curl -X POST "https://rikaiso.com/api/help/v1/versions/{version}/nodes" \
  -H "Authorization: Bearer rk_help_xxx" \
  -H "Content-Type: application/json" \
  -d '{"slug":"string, unique within the version","kind":"section | topic","parentSlug":"string or null","icon":"icon name or null","sortOrder":"number","translations":"object keyed by language: { title, summary, bodyMd }"}'

List nodes with translation status

Flat list of every node in document order with id, slug, kind, parentSlug, sortOrder, icon, updatedAt and `translations` keyed by language ({ title, summary, updatedAt, bodyChars }). Published versions are public (no bodies); with a credential drafts are visible and `include=bodies` adds bodyMd.

Responses

200  { version, status, nodes }
404  Unknown version.

Example

curl -X GET "https://rikaiso.com/api/help/v1/versions/{version}/nodes"

Update a node

Partially updates a node (only the fields in the body change) and merges any supplied translations, whose languages must be enabled on the version. Supports `expectedUpdatedAt` / If-Unmodified-Since (409 on conflict); the response carries kind, icon, parentSlug, sortOrder and `updatedAt`.

Request body

{
  "slug": "string, optional — renames the node",
  "kind": "section | topic, optional",
  "parentSlug": "string or null, optional",
  "icon": "icon name or null, optional",
  "sortOrder": "number, optional",
  "translations": "object keyed by language, optional"
}

Responses

200  { id, slug, kind, parentSlug, icon, sortOrder, updatedAt, translations: { [lang]: { updatedAt } } }
404  Unknown node.
409  The node changed after expectedUpdatedAt, or the new slug is taken.

Example

curl -X PATCH "https://rikaiso.com/api/help/v1/versions/{version}/nodes/{slug}" \
  -H "Authorization: Bearer rk_help_xxx" \
  -H "Content-Type: application/json" \
  -d '{"slug":"string, optional — renames the node","kind":"section | topic, optional","parentSlug":"string or null, optional","icon":"icon name or null, optional","sortOrder":"number, optional","translations":"object keyed by language, optional"}'

Delete a node

Removes a node and its descendants; the response lists the removed slugs.

Responses

200  { ok: true, removed: [slug] }
404  Unknown node.

Example

curl -X DELETE "https://rikaiso.com/api/help/v1/versions/{version}/nodes/{slug}" \
  -H "Authorization: Bearer rk_help_xxx"

Get one translation

Returns the stored title, summary, bodyMd and updatedAt of one translation plus the node's availableLanguages. Draft and archived versions need a bearer key.

Responses

200  Translation object.
404  Unknown version, node or translation.

Example

curl -X GET "https://rikaiso.com/api/help/v1/versions/{version}/topics/{slug}/translations/{lang}"

Replace one translation

Full replacement of a translation (created when missing); the language must be enabled on the version. Supports `expectedUpdatedAt` / If-Unmodified-Since (409 on conflict). Use PATCH /nodes/{slug} with `translations` to merge several languages.

Request body

{
  "title": "string, 1–200 characters",
  "summary": "string, optional",
  "bodyMd": "Markdown string, optional",
  "expectedUpdatedAt": "ISO timestamp, optional"
}

Responses

200  { translation: { slug, language, title, summary, bodyMd, updatedAt, created } }
404  Unknown node.
409  The translation changed after expectedUpdatedAt.

Example

curl -X PUT "https://rikaiso.com/api/help/v1/versions/{version}/topics/{slug}/translations/{lang}" \
  -H "Authorization: Bearer rk_help_xxx" \
  -H "Content-Type: application/json" \
  -d '{"title":"string, 1–200 characters","summary":"string, optional","bodyMd":"Markdown string, optional","expectedUpdatedAt":"ISO timestamp, optional"}'

Delete one translation

Removes one language of a node; the response lists the remaining languages.

Responses

200  { ok: true, remainingLanguages }
404  Translation not found.

Example

curl -X DELETE "https://rikaiso.com/api/help/v1/versions/{version}/topics/{slug}/translations/{lang}" \
  -H "Authorization: Bearer rk_help_xxx"

Move and reorder nodes

Applies parent and sort order for the listed slugs in one call. Every slug must exist and no node may end up inside its own subtree (400 with code `cycle`); if any row fails the previous order is restored. Returns the new flat order.

Request body

{
  "items": "array of { slug, parentSlug: string | null, sortOrder: number }"
}

Responses

200  { version, items: [{ slug, parentSlug, sortOrder }] } in document order.
400  Unknown slug, unknown parent or cycle.

Example

curl -X POST "https://rikaiso.com/api/help/v1/versions/{version}/reorder" \
  -H "Authorization: Bearer rk_help_xxx" \
  -H "Content-Type: application/json" \
  -d '{"items":"array of { slug, parentSlug: string | null, sortOrder: number }"}'

Duplicate a version

Deep-copies every node and translation into a new version (draft unless `status` says otherwise). The copy is never marked latest.

Request body

{
  "slug": "string, new version slug",
  "label": "string, display label",
  "status": "draft | published | archived, optional (default draft)"
}

Responses

200  { version } — the new version object.
409  The target slug already exists.

Example

curl -X POST "https://rikaiso.com/api/help/v1/versions/{version}/duplicate" \
  -H "Authorization: Bearer rk_help_xxx" \
  -H "Content-Type: application/json" \
  -d '{"slug":"string, new version slug","label":"string, display label","status":"draft | published | archived, optional (default draft)"}'

Search a version

Case-insensitive match on title, summary and body text; up to 50 hits in document order with a snippet. Published versions are public; drafts need a bearer key.

Responses

200  { version, language, query, hits: [{ slug, title, summary, snippet }] }
404  Unknown version.

Example

curl -X GET "https://rikaiso.com/api/help/v1/versions/{version}/search"

Export a version

Full JSON document: { version, nodes } where every node carries slug, kind, parentSlug, icon, sortOrder and all translations including bodies. Published versions are public; drafts need a credential. Large for big versions.

Responses

200  Export document.
404  Unknown version.

Example

curl -X GET "https://rikaiso.com/api/help/v1/versions/{version}/export"

Import a version document

Applies an export document to the version. `merge` upserts nodes and translations; `replace` also deletes nodes and translations the document omits. With `dryRun: true` nothing is written and the diff summary (created/updated/unchanged/deleted slugs) is returned.

Request body

{
  "mode": "merge | replace",
  "dryRun": "boolean, optional",
  "nodes": "array of export nodes (or wrap them in `document: { nodes }`)"
}

Responses

200  { dryRun, mode, diff: { created, updated, unchanged, deleted, updatedTranslations: [{ slug, language }], deletedTranslations: [{ slug, language }] }, version }
400  Invalid document (unknown parent, duplicate slug, cycle, or a translation language the version does not enable — `offending` lists the { slug, language } pairs).

Example

curl -X POST "https://rikaiso.com/api/help/v1/versions/{version}/import" \
  -H "Authorization: Bearer rk_help_xxx" \
  -H "Content-Type: application/json" \
  -d '{"mode":"merge | replace","dryRun":"boolean, optional","nodes":"array of export nodes (or wrap them in `document: { nodes }`)"}'

Import a version from content files

Docs-as-code import used by the content repository's GitHub Action: `{ files: [{ path, content }] }` holding `version.json` and every `{lang}/{slug}.md` of the version (paths may be repository-relative). Files are parsed server-side; `dryRun=true` validates and reports `{ created, updated, deleted }` without writing. A real run replaces the version, marks it published, applies `isLatest`, deletes its working copy and closes matching publish requests. While publishing through pull requests is enabled, a real run needs a publisher key. At most 2,000 files / 10 MB.

Request body

{
  "files": "array of { path, content }",
  "dryRun": "boolean, optional"
}

Responses

200  { dryRun, summary: { created, updated, deleted, unchanged, slugs }, warnings, version: { slug, exists, status, isLatest }, workingCopyDeleted, requestsImported }
400  { error: { code: 'invalid_content', errors: [{ path, line?, message }], warnings } }
403  { error: { code: 'published_read_only' } } — a real run without a publisher key.

Example

curl -X POST "https://rikaiso.com/api/help/v1/versions/{version}/import-files" \
  -H "Authorization: Bearer rk_help_xxx" \
  -H "Content-Type: application/json" \
  -d '{"files":"array of { path, content }","dryRun":"boolean, optional"}'

Create a working copy

Duplicates a published version into the hidden draft `{version}-wip` (its `workingCopyOf` points at the original) so it can be edited and published back through a pull request. Returns the existing copy when one already exists. Requires publishing through pull requests to be enabled.

Responses

200  { version, existed: true }
201  { version, existed: false }
409  Publishing through pull requests is disabled.

Example

curl -X POST "https://rikaiso.com/api/help/v1/versions/{version}/working-copy" \
  -H "Authorization: Bearer rk_help_xxx"

Discard a working copy

Deletes the working copy of the version. Refused while a publish request for it is open.

Responses

200  { ok: true, discarded }
409  An open publish request exists.

Example

curl -X DELETE "https://rikaiso.com/api/help/v1/versions/{version}/working-copy" \
  -H "Authorization: Bearer rk_help_xxx"

Open a publish pull request

Exports a draft (new version) or a working copy (changes to its original) as content files, validates them, commits them to a `publish/{target}/{stamp}` branch of the content repository and opens a pull request titled `Publish {target}`. `dryRun=true` returns the validation result and counts without touching GitHub. One open request per target.

Responses

200  { dryRun: true, targetSlug, summary: { created, updated, deleted, unchanged, slugs }, warnings, files }
201  { dryRun: false, request: { id, targetSlug, prNumber, prUrl, status, summary, … } }
400  invalid_content with the error list.
409  A request for the target is already open, or publishing is disabled.
502  GitHub refused the call (the request is recorded as failed).

Example

curl -X POST "https://rikaiso.com/api/help/v1/versions/{version}/publish-request" \
  -H "Authorization: Bearer rk_help_xxx"

List publish requests

Publish requests newest first, optionally filtered by `target`. Each carries the PR number and URL, status (`open | merged | closed | imported | failed`), counts and timestamps.

Responses

200  { requests: [...] }

Example

curl -X GET "https://rikaiso.com/api/help/v1/publish-requests" \
  -H "Authorization: Bearer rk_help_xxx"

Cancel a publish request

Closes the pull request, deletes its branch and marks the request `closed`.

Responses

200  { request }
409  The request is not open.

Example

curl -X DELETE "https://rikaiso.com/api/help/v1/publish-requests/{id}" \
  -H "Authorization: Bearer rk_help_xxx"

Describe the API key

Returns { kind, keyName, keyPrefix, createdAt, lastUsedAt, scopes, canWritePublished, publishViaPr } for the credential in use. `publishViaPr` is true while published versions can only change through a merged pull request; writes to them then answer 403 `published_read_only` unless the key is a publisher key.

Responses

200  Key metadata.
401  Missing or invalid API key.

Example

curl -X GET "https://rikaiso.com/api/help/v1/whoami" \
  -H "Authorization: Bearer rk_help_xxx"

Get the data for a PDF export

Returns { version, language, template, entries, fonts, filename } for a published version, or for a comma-separated selection of topics resolved to document order (sections expand to their descendants, ancestors appear as chapter headings, at most 200 topics). The portal renders the PDF in the browser from this bundle; shareable links look like /support/{version}/{slug}?pdf=1&lang=de&topics=a,b.

Responses

200  PDF bundle object.
400  Invalid selection or more than 200 topics.
404  Version not published.

Example

curl -X GET "https://rikaiso.com/api/help/v1/versions/{version}/pdf-bundle"

Download a PDF (retired)

Rendering now happens in the browser; use /pdf-bundle and a client renderer.

Responses

410  Gone.

Example

curl -X GET "https://rikaiso.com/api/help/v1/versions/{version}/pdf"

Download a PDF (retired)

Rendering now happens in the browser; use /pdf-bundle and a client renderer.

Responses

410  Gone.

Example

curl -X POST "https://rikaiso.com/api/help/v1/versions/{version}/pdf"