[BETA] Update a knowledge base category

Change a category of your school's knowledge base so that its structure follows your own system without manual edits in Edusign: rename it, add or drop a translation, move it elsewhere in the tree, change its audience or its cover, hide it.

Partial update: only the fields sent change, at least one is required, and unknown fields are ignored. If a field is set to null → its value is reset (parentId moves to the root, coverImageUrl removes the cover). The response names the fields applied in updatedFields. A category never becomes a publication.

Languages

content replaces the languages of the category as a whole: a sent language keeps its stored row and gets the new title and text, a new language is added, a language not sent is removed, so at least one must be sent. Translations are matched by language, never by an identifier. language is required when more than one item is sent and defaults to the school language otherwise (fr when the school language is not one of the four); a language sent twice answers 400 DUPLICATE_IN_REQUEST. The text is reduced to what the Edusign editor produces and is limited to 65,535 bytes once reduced.

Moves and position

parentId moves the category under a category of your school (404 KNOWLEDGE_BASE_CATEGORY_NOT_FOUND for a publication or an unknown id), or to the root with null, at order or last; the siblings it leaves close the gap and its content moves with it. The category cannot move under itself or one of its descendants (409 KNOWLEDGE_BASE_CIRCULAR_HIERARCHY). order alone moves the category among its current siblings, categories and publications together, and shifts the items in between; a position beyond the last means last.

Audience

audience replaces the audience as a whole: all (everyone), unauthenticated (the public part of your white-label app) or authenticated (the students of the app), restricted to groupIds or groupExternalReferenceIds for authenticated only, so groups never outlive a change of type. all and unauthenticated need the public white-label app (403 PUBLIC_AUDIENCE_REQUIRES_WHITE_LABEL); an unknown group answers 404 GROUP_NOT_FOUND, an archived one 409 GROUP_ARCHIVED, both lists together 400 GROUP_IDENTIFIER_AMBIGUOUS.

A category is never wider than its parent: under an unauthenticated parent it is unauthenticated, under an authenticated one it is authenticated and, when the parent names groups, its groups are a non-empty subset of them. The rule is checked whenever audience or parentId is sent, on the resulting audience and the resulting parent (409 KNOWLEDGE_BASE_PARENT_VISIBILITY_CONFLICT); a category made wider than its parent in Edusign before this rule stays as it is until one of them is sent. When audience is sent, every item filed directly in the category must still fit inside it: widening is always accepted, narrowing is refused while an item would reach more people than the category (409 KNOWLEDGE_BASE_CHILD_VISIBILITY_CONFLICT, one entry per item in errors); the items are never changed for you, narrow them first. The rule is checked on the items as they are when the request runs: an item widened at the same instant by another request is not seen.

Cover

coverImageUrl gives the https URL of a new cover: it is downloaded, checked, scanned and stored after the response, and the category keeps pointing at its current cover until that succeeds; a failure is logged. null removes the cover during the request; when the storage refuses, the request answers 502 KNOWLEDGE_BASE_COVER_DELETE_FAILED and the category is not changed, though the storage may already have dropped some of the stored sizes.

Hiding and the chatbot

hidden: true hides the category from the student app; false shows it again. Neither changes the chatbot index yet: a hidden category synced with the campus chatbot keeps answering until the chatbot follow-up.

When your school has the campus chatbot and the category is synced with it, a change of its texts, its audience or its place is sent to the chatbot after saving, with what Edusign sends: the title and the text of the indexed language. A failed send keeps the change, answers 200 and is repaired later by the index reconciliation. Nothing is sent while the text the chatbot would read is under 10 characters. The sync setting itself is not changed here.

The checks run on the category as the request reads it, and the change is saved only while its parent, audience, chatbot sync and texts still read the same under the lock: when one of them changed meanwhile, the request answers 409 KNOWLEDGE_BASE_CATEGORY_CONFLICT and nothing is saved, except a cover removal, which happens before that check and is not undone; read the category again and send the change again.

Everything except the new cover is saved together, or not at all. A category is found in your school only: an unknown or malformed id, another school's category or a publication answers 404 KNOWLEDGE_BASE_CATEGORY_NOT_FOUND. A request that does not match this description answers 400 VALIDATION_ERROR with the fields in errors; a group reference several active groups of your school carry answers 409 GROUP_EXTERNAL_REFERENCE_NOT_UNIQUE.

Recent Requests
Log in to see full request history
TimeStatusUser Agent
Retrieving recent requests…
LoadingLoading…
Path Params
string
required

The identifier Edusign gave the category or the publication.

Body Params
content
array of objects
length ≤ 4

Replaces the languages of the category: a sent language keeps its stored row, a new one is added, a language not sent is removed. At least one remains. A language sent twice is refused with DUPLICATE_IN_REQUEST.

content
length ≥ 1

Moves the category under this category of your school, at order or last; the siblings it leaves close the gap. If set to null → the category moves to the root. A publication, the category itself or one of its descendants as target is refused.

integer
0 to 9007199254740991

The position among the items of the parent, from 0; the items from that position on move down one. Absent or beyond the last position means last.

audience
object

Replaces the audience as a whole. Never wider than the parent's, never narrower than an item filed in the category. all and unauthenticated need the public white-label app.

boolean

true hides the category from the student app. The chatbot index is not changed.

length ≤ 2048

An https URL of the cover (JPEG, PNG or WebP, 10 MB at most), downloaded, checked, scanned and stored after the response.


An https URL of the cover (JPEG, PNG or WebP, 10 MB at most), downloaded, checked, scanned and stored after the response.

Responses

Language
Credentials
LoadingLoading…
Response
Click Try It! to start a request and see the response here! Or choose an example:
application/json