Knowledge Center

A hosted, public help site fed by your videos. Articles live in sections, get translated into your enabled locales, and answer questions through a retrieval endpoint you can wire into a support bot.

The Knowledge Center is a paid add-on. Without it, every endpoint here returns 403. One knowledge base per workspace, so this is a singular resource - /v1/knowledge-base, not /v1/knowledge-bases.

The knowledge base

GET /v1/knowledge-base · POST /v1/knowledge-base · PATCH /v1/knowledge-base · DELETE /v1/knowledge-base

curl -X POST https://api.vidocu.ai/v1/knowledge-base \
  -H "Authorization: Bearer vdo_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"name": "Acme Help", "slug": "acme", "defaultLocale": "en"}'

{
  "id": "0b0f...",
  "name": "Acme Help",
  "slug": "acme",
  "url": "https://acme.vidocu.help",
  "defaultLocale": "en",
  "enabledLocales": ["en"],
  "visibility": "public"
}

The slug is the public address. Changing it changes every URL on the site, so add redirects for anything already published. 409 if the workspace already has a knowledge base or the slug is taken.

DELETE is a soft delete: the site stops resolving, the articles are kept.

Sections

GET /v1/knowledge-base/sections · POST /v1/knowledge-base/sections · PATCH /v1/knowledge-base/sections/:id · DELETE /v1/knowledge-base/sections/:id · POST /v1/knowledge-base/sections/reorder

Every article belongs to a section. New sections are appended to the end of their siblings; reorder takes the full list of section ids in the order you want them displayed.

Sub-sections

Sections nest one level deep. A section carries parentId: null (or absent, on sections created before this existed) for a top-level section, or the id of the top-level section it sits under.

curl -X POST https://api.vidocu.ai/v1/knowledge-base/sections \
  -H "Authorization: Bearer $VIDOCU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Billing", "slug": "billing", "parentId": "sec_account"}'

The rules, each answered with 400 when broken:

• The parent must exist and belong to the same knowledge base.
• The parent must itself be top-level. A sub-section cannot have sub-sections.
• A section cannot be its own parent.
• A section that already has sub-sections cannot be moved under another section.
• Deleting a section that still has sub-sections is refused. Move them (PATCH with a new parentId, or null to make them top-level) or delete them first.

What does not change: slugs stay unique across every section of the knowledge base, and public URLs stay flat (/{section-slug}), so nesting a section never breaks a link. Articles can live in a top-level section or a sub-section. position orders siblings, so reorder numbers top-level sections and each parent's sub-sections as separate groups. On the public site a sub-section is never shown to someone who cannot see its parent: the effective visibility is the more restrictive of the two.

Deleting a section that still holds articles returns 409 - orphaned articles would vanish from the site with no trace, so move them first.

Tags

Tags are private labels on articles. They never appear on the public site; they are how you file articles for yourself, and how you choose which articles go into an offline export. The list lives on the knowledge base and articles point at it by id.

PATCH /v1/knowledge-base takes the full tags list: a row with a known id is renamed or recolored, a row without one is created, and a tag left out of the list is deleted and removed from every article that carried it. A knowledge base holds up to 50 tags; names are unique (case-insensitive) and up to 40 characters; color is a hex value.

curl -X PATCH https://api.vidocu.ai/v1/knowledge-base \
  -H "Authorization: Bearer $VIDOCU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"tags": [
    {"id": "tag_existing", "name": "Customer: Acme", "color": "#007A7A"},
    {"name": "Internal", "color": "#7C3AED"}
  ]}'

Assign tags with tagIds on POST /v1/knowledge-base/articles and PATCH /v1/knowledge-base/articles/:id. Unknown ids return 400. Filter the list with GET /v1/knowledge-base/articles?tagId=.... Tags are filing metadata, so they stay editable on a locked article.

Articles

GET /v1/knowledge-base/articles · POST /v1/knowledge-base/articles · GET /v1/knowledge-base/articles/:id · PATCH /v1/knowledge-base/articles/:id · DELETE /v1/knowledge-base/articles/:id

Content is Markdown. The list endpoint returns metadata without article bodies - fetch a single article for its content. It's cursor-paginated and filterable by state, sectionId, visibility, linkedVideoId and tagId.

curl -X POST https://api.vidocu.ai/v1/knowledge-base/articles \
  -H "Authorization: Bearer vdo_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "sectionId": "sec_...",
    "title": "Resetting your password",
    "slug": "resetting-your-password",
    "content": "## Steps\n\n1. Open Settings...",
    "state": "published"
  }'

Locked articles

An article that came from a locked video is a permanent record. It stays organizable - sectionId, state, seo and tagIds can still change, so it can be filed and surfaced - but everything else is frozen and returns 423. Locked articles can't be deleted at all.

Publishing and approvals

Publishing an article whose source video is under review is blocked with 409 until every approver has approved. An approval also goes stale: if the source video was unlocked and edited after being approved, publishing is refused until a fresh approval round passes.

Import from a video

POST /v1/knowledge-base/articles/from-video

curl -X POST https://api.vidocu.ai/v1/knowledge-base/articles/from-video \
  -H "Authorization: Bearer vdo_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"videoId": "vid_abc123", "sectionId": "sec_...", "state": "published"}'

The video must already have a help article - generate one with POST /v1/videos/:id/article first, or this returns 409. The dashboard generates one on the fly; the API deliberately doesn't, because that's a metered job that shouldn't fire as a side effect of an import.

The imported article is linked back to its video, and a locked video produces a locked article.

Translation

POST /v1/knowledge-base/articles/:id/translate with {"targetLocales": ["es", "de"]}

Targets must be locales enabled on the knowledge base. Draws on the add-on's AI credit pool (see Billing).

Ask - retrieval-grounded answers

POST /v1/knowledge-base/ask

The endpoint to wire a support bot into. It answers from your published articles, with citations, rather than from a model's general knowledge.

curl -X POST https://api.vidocu.ai/v1/knowledge-base/ask \
  -H "Authorization: Bearer vdo_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"question": "How do I reset my password?"}'

{
  "answer": "Open Settings, choose Security, then...",
  "citations": [{ "articleId": "...", "title": "Resetting your password", "slug": "..." }],
  "noMatches": false,
  "matchedCount": 3
}

Retrieval is cross-lingual: the question is matched against every locale's content, and the answer is written in the requested locale (defaulting to the knowledge base's).

When nothing relevant is found, noMatches is true and answer is empty - surface that as "I don't know" rather than inventing one.

Reindex

POST /v1/knowledge-base/reindex

Rebuilds search embeddings for every published article. Publishing indexes automatically, so this is only for after a bulk import or if search looks stale. It walks the whole knowledge base and can take a while.

Redirects

GET /v1/knowledge-base/redirects · POST /v1/knowledge-base/redirects · DELETE /v1/knowledge-base/redirects/:id

Keep old links working after a slug change. Both paths start with /:

curl -X POST https://api.vidocu.ai/v1/knowledge-base/redirects \
  -H "Authorization: Bearer vdo_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"fromPath": "/articles/old-slug", "toPath": "/articles/new-slug"}'

Analytics

GET /v1/knowledge-base/analytics?days=30

Article counts by state, most-viewed articles, top searches, and searches that returned nothing - the last being the most direct signal of what your documentation is missing.

Offline export

POST /v1/knowledge-base/exports · GET /v1/knowledge-base/exports · GET /v1/knowledge-base/exports/:id

A static copy of the help center as a ZIP, for customers who run documentation on their own network. It carries your branding, sections, articles, images, the exported video for each article and a client-side search box on every page. It opens from index.html with no server and also serves from any static host. AI Ask, reader feedback and quiz scoring need the live site and are left out.

curl -X POST https://api.vidocu.ai/v1/knowledge-base/exports \
  -H "Authorization: Bearer $VIDOCU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"locales": ["en", "de"], "tagIds": ["tag_acme"], "includeVideos": true}'

• locales - a subset of the enabled locales; the default locale is always included. An extra language only carries the articles that have a translation.
• tagIds - restrict to tagged articles. Empty means every published, public article. tagMatch is any (default) or all.
• includeVideos - default true. Each article's exported video is copied in. A video with no export, or one that changed since, is exported first through the normal export path and counted like any other export. A video that cannot be rendered in time is skipped and listed under skippedVideos with the reason; the article gets a "watch it online" link instead.

The build runs in the background: the response is 202 with the export record, and GET /v1/knowledge-base/exports/:id reports progress until status is completed or failed. One build runs at a time per knowledge base; a second POST returns 409.

Each export gets a version: builds with the same tag selection (or none) form a series, and every completed build in it is numbered one higher. The number is in the ZIP filename and in the footer of every page of the exported site, so a customer can tell you which copy they are holding.

A completed export carries a presigned downloadUrl (valid one hour; call the list or get endpoint again for a fresh one), sizeBytes, counts and skippedVideos. Every image an article shows is packaged, including ones hosted outside Vidocu (fetched over HTTPS from public hosts, up to 25 MB each); the few that cannot be fetched stay as online links and are listed in externalImages. The list marks an export stale: true when the articles, sections or translations it selected have changed since it was built.

Billing

Knowledge Center AI operations - ask, translate, reindex - draw on the add-on's own monthly AI credit pool, not the workspace credit balance shown in GET /v1/usage. Article reads, writes and analytics are free.

Errors

Status	Code	Cause
403	limit_exceeded	The Knowledge Center add-on isn't active on this workspace
400	validation_error	Bad parentId: not top-level, wrong knowledge base, or the section has sub-sections
404	not_found	No knowledge base yet, or the section/article/redirect doesn't exist
409	conflict	Slug taken, section not empty, or a linked video is awaiting approval
423	locked	The article is locked