[BETA] Search the knowledge base categories

Read the structure of your school's knowledge base: the categories, level by level, with their titles in every language, their audience, their position and how many categories and publications are filed directly in them. Use it to know where to file a publication, or to keep your own system in sync with the knowledge base.

It is a read: the filters travel in a JSON body, as on the other :search routes, and an API key or a token with read access only is enough. Filters are combined with AND; an empty body returns the first page of every category.

The list is flat and paginated, 100 categories per page by default and 250 at most. The paginated results are categories only, never news feed posts or other schools’ categories; publications are never listed on their own and appear only inside their category, with includePublications: true. Reading never creates anything: a knowledge base that was never opened answers an empty page.

Walking the tree

parentId names a category and returns the categories filed directly in it; a root category has no parentId in the response. Without it, every category of the school is listed, root categories first: each category object carries parentId, subcategoriesCount and publicationsCount (direct children, hidden ones included), so the tree can be rebuilt from one listing or walked level by level. An unknown parentId, or one of another school, gives an empty page.

Reading the whole knowledge base

With includePublications: true, each category also carries publications: the publications filed directly in it, hidden ones included, in display order, as GET /v3/knowledge-base/publications/:id returns them ([] when there is none). The filters apply to the categories only, never to the publications inside them, and the pagination counts categories only. Each category carries its direct publications: its sub-categories carry theirs.

Filters and sorting

title matches part of the title in any language, case and accents ignored. hidden, audienceType and chatbotSync keep the matching categories; hidden categories are listed by default, as in Edusign.

sortBy is order by default: the order students see, root categories first, then by parent, then by position. title sorts on the title in the school language, or on the first title in the fr, en, es, it order when the category has none in that language, case and accents ignored. createdAt and updatedAt sort by date, most recent first unless sortOrder is asc. Ties are broken on the id, so pages never skip or repeat a category.

The category object

The titles come in a fixed order, fr, en, es, it, and only for the languages the category has, each with its body when the category has a text. The audience is returned as stored: all (everyone), unauthenticated (the public part of your white-label app) or authenticated (the students of the app), with the groups it is restricted to, archived groups left out and groups: [] when nothing restricts it; a category created before audiences were stored is all, and a category wider than its parent is returned as it is. coverImageUrl is present when the category has a cover.

Every invalid body, such as a page size above 250, an unknown sortBy or a field the body does not take, 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
number
Defaults to 1

1-based page number. Defaults to 1.

number
Defaults to 100

Number of categories per page, 1 to 250. Defaults to 100.

string
length ≥ 1

The sub-categories filed directly in this category. An id that is no category of your school gives an empty page.

string
length between 1 and 255

Partial match on the title in any language, case and accents ignored.

boolean

true: hidden categories only. false: visible categories only. Omit for both.

string
enum

all: everyone, unauthenticated: the public part of your white-label app only, authenticated: the students of the app, restricted to groups when some are listed.

Allowed:
boolean

true: categories synchronized with the campus chatbot only. false: the others only. Omit for both.

boolean
Defaults to false

true: each category also carries publications, the publications filed directly in it, hidden ones included, in display order. Defaults to false.

string
enum
Defaults to order

order: the display order (root categories first, then by parent, then by position). title: the title in the school language, or the first one in the fr, en, es, it order, case and accents ignored. createdAt, updatedAt: the dates. Ties are broken on the id, so pages never skip or repeat a category. Defaults to order.

Allowed:
string
enum

Sort direction. Defaults to asc for order and title, to desc (most recent first) for createdAt and updatedAt.

Allowed:
Responses

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