[BETA] Create a knowledge base category

Create a category of your school's knowledge base, at the root or inside another category, so that the structure students browse in the app follows your own system. The response carries the identifier only: read the category back, with its position, its inherited audience and its cover, with GET /v3/knowledge-base/categories/:id.

Your school needs the API option and the knowledge base feature. The call works on a school whose knowledge base was never opened in Edusign.

Languages

content gives the title, and optionally the text, of the category in each of its languages: fr, en, es or it. 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 (scripts, event handlers and unknown tags are removed) and is limited to 65,535 bytes once reduced.

Audience

audience.type is all (everyone), unauthenticated (the public part of your white-label app only) or authenticated (the students of the app), restricted to groupIds or groupExternalReferenceIds for authenticated only. Every group must be an active group of your school: an unknown one answers 404 GROUP_NOT_FOUND, an archived one 409 GROUP_ARCHIVED, a reference carried by several active groups 409 GROUP_EXTERNAL_REFERENCE_NOT_UNIQUE, both lists together 400 GROUP_IDENTIFIER_AMBIGUOUS. all and unauthenticated need a public white-label app (403 PUBLIC_AUDIENCE_REQUIRES_WHITE_LABEL).

When audience is absent, the category takes its parent's audience and groups; at the root it is all when your school has a public white-label app, authenticated otherwise, and that inherited audience is never refused.

A category is never wider than its parent: under an all parent, any audience; under an authenticated parent without groups, authenticated with or without groups; under an authenticated parent with groups, authenticated with groups that are a non-empty subset of the parent's; under an unauthenticated parent, unauthenticated only. Anything wider answers 409 KNOWLEDGE_BASE_PARENT_VISIBILITY_CONFLICT.

Position

The category is placed at order among the items of its parent, categories and publications together, from 0: the items from that position on move down one. Without order, or with one beyond the last position, it goes last. Two creations at the same moment never get the same position.

Cover

coverImageUrl gives the https URL of the cover: it is downloaded, checked (JPEG, PNG or WebP, 10 MB at most), scanned for viruses, resized and stored after the response, with its original kept so it can be re-cropped in Edusign. The cover appears once that succeeds; when it fails, the category has no cover, the failure is logged and the creation stands.

A new category is never synchronized with the campus chatbot. The category and its texts are saved together, or not at all. A parent is found in your school only: an unknown id, another school's category or a publication answers 404 KNOWLEDGE_BASE_CATEGORY_NOT_FOUND. Every other invalid request answers 400 VALIDATION_ERROR with the fields in errors.

Recent Requests
Log in to see full request history
TimeStatusUser Agent
Retrieving recent requests…
LoadingLoading…
Body Params
content
array of objects
required
length ≤ 4

The title, and optionally the text, of the category in each of its languages. A language sent twice is refused with DUPLICATE_IN_REQUEST.

content*
string
length ≥ 1

The category to file this one in; absent for a category at the root. A publication as parent answers 404 KNOWLEDGE_BASE_CATEGORY_NOT_FOUND.

audience
object

Who reads the category. Inherited from the parent when absent; at the root, all when your school has a public white-label app, authenticated otherwise. Never wider than the parent's.

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.

uri
length ≤ 2048

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