Build a coaching catalogue

The coaching catalogue is what a learner browses on the coaching portal. It is a tree of directories; each directory is one page at /catalogue/<id> on your coaching domain, and it can hold two things:

Sub-directories — listed explicitly in the directory’s tags_sub.
Coaching sessions — not listed explicitly. A session appears because its own tags match the directory’s tags_interview_set_filter.

That indirection is the whole design: you tag a session once, and it shows up in every directory whose filter it satisfies. Nothing has to be re-linked when you add a session.

Coaching-platform feature. Directories only render on a coaching portal; they have no effect on the recruiting/interview portal.

The mental model

merchant.catalogue_tag_start          →  the directory the catalogue opens on
└── home                                 (is_start_directory: true)
    ├── tags_sub: [sales-coaching, interview-prep]
    │   ├── sales-coaching
    │   │   ├── tags_interview_set_filter: ["sales-en"]
    │   │   ├── lists every active coaching/persona session tagged "sales-en"
    │   │   └── translations.sk: its Slovak version, with its own filter ["sales-sk"]
    │   └── interview-prep
    └── content_md: optional custom page that lays the above out by hand

Every directory can carry several languages. Its top-level fields are its default language (mojito_language_code); translations holds the others, each a page of its own. See Several languages in one directory.

Tool	What it is for
`list_catalogue_directories` (`GET /catalogue-tag-list`)	Find directories; walk the tree with `parent_tag`; spot the root with `is_start_directory`.
`get_catalogue_directory` (`GET /catalogue-tag-get`)	One directory in full — its `content_md`, its sub-directories, and the sessions it currently lists.
`create_catalogue_directory` (`POST /catalogue-tag-create`)	Create a directory, optionally nested under a `parent_tag`.
`update_catalogue_directory` (`POST /catalogue-tag-update`)	Change a directory, its filter, its children, or its custom page.
`update_interview` (`POST /job-interview-update`)	Set `tags` on an existing session so it lands in a directory.

How a session gets into a directory

A session is listed when all of these are true:

Condition	Where it comes from
Its `tags` contain every tag in the directory’s `tags_interview_set_filter`	`tags` on the session, `tags_interview_set_filter` on the directory
Its `type` is `coaching` or `persona`	`type` on create; `persona-create` with `portal: "coaching"` (the default)
Its `status` is `active`	`status` on create, or `set_interview_state`
Its `visibility` is `public` or `merchant_public`	`visibility` on create/update

The tag filter is an AND, not an OR. A directory filtering on ["sales", "objection-handling"] lists only sessions carrying both tags. A session may carry extra tags — that is what lets one session appear in several directories.

Two edge cases are worth knowing:

tags_interview_set_filter: [] (empty array) matches every tagged session — a useful “everything” directory, and an easy accident.
tags_interview_set_filter: null matches nothing. A brand-new directory created without the field lists no sessions until you set it.

Walkthrough

See what already exists

Start from the root and walk down, rather than guessing ids.

# Everything you can see, newest ids first — is_start_directory marks the root
curl "https://cool.jobmojito.com/functions/v1/catalogue-tag-list?mojito_language_code=en" \
  -H "Authorization: Bearer $SUPABASE_JWT"

# Just the children of one directory, in the order they are rendered
curl "https://cool.jobmojito.com/functions/v1/catalogue-tag-list?parent_tag=home-employee-en" \
  -H "Authorization: Bearer $SUPABASE_JWT"

include_public=true (the default) also returns the platform-wide directories shared across merchants. Set it to false to see only your own. mojito_language_code matches a directory’s default language or any of its language versions; each row’s languages lists them, default first.

Create the directory

The id is the URL segment and the value other directories reference in their tags_sub. Use lowercase letters, digits and single -/_ separators. A directory that will hold several languages is better named without a language suffix (sales-coaching, not sales-coaching-en): the same address serves every language. The API cannot change an id afterwards; a merchant can, in the admin catalogue editor (see Gotchas).

curl -X POST https://cool.jobmojito.com/functions/v1/catalogue-tag-create \
  -H "Authorization: Bearer $SUPABASE_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "sales-coaching-en",
    "name": "Sales coaching",
    "description": "Practice discovery, objection handling and closing.",
    "mojito_language_code": "en",
    "visibility": "merchant_public",
    "status": "active",
    "parent_tag": "home-employee-en",
    "tags_interview_set_filter": ["sales"]
  }'

parent_tag appends the new id to that directory’s tags_sub, so the page is reachable immediately. Omit it and the directory exists but is only reachable by direct link until you add it to a parent.The response returns catalogue_url — the live page — when your merchant has a coaching domain configured.

Tag the sessions

A new session takes its tags on create. All three creation endpoints accept tags:

curl -X POST https://cool.jobmojito.com/functions/v1/job-interview-create \
  -H "Authorization: Bearer $SUPABASE_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Handling price objections",
    "location": "remote",
    "interview_template_id": "TEMPLATE_UUID",
    "mojito_language_code": "en",
    "status": "active",
    "type": "coaching",
    "visibility": "merchant_public",
    "tags": ["sales", "objection-handling"]
  }'

curl -X POST https://cool.jobmojito.com/functions/v1/persona-create \
  -H "Authorization: Bearer $SUPABASE_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Objection-handling role-play",
    "interview_template_id": "TEMPLATE_UUID",
    "mojito_language_code": "en",
    "status": "active",
    "visibility": "merchant_public",
    "portal": "coaching",
    "persona_role_avatar": "is to act as a skeptical procurement manager",
    "persona_role_user": "is to be a sales rep booking a follow-up demo",
    "tags": ["sales", "objection-handling"]
  }'

An existing session is re-tagged with update_interview. tags is replaced wholesale, so read the current value first and send the extended list:

# 1. read the current tags
curl "https://cool.jobmojito.com/functions/v1/job-interview-get?position_id=SESSION_UUID" \
  -H "Authorization: Bearer $SUPABASE_JWT"

# 2. send the full list, not just the addition
curl -X POST https://cool.jobmojito.com/functions/v1/job-interview-update \
  -H "Authorization: Bearer $SUPABASE_JWT" \
  -H "Content-Type: application/json" \
  -d '{ "position_id": "SESSION_UUID", "tags": ["sales", "objection-handling"] }'

persona-create defaults to portal: "coaching", which is the variant that belongs in a catalogue. A persona created with portal: "interview" is stored as persona_interview and is never listed in the catalogue — it goes through the recruiting invitation flow instead. See Create an interview.

Verify the mapping

Do not assume the tags matched. get_catalogue_directory returns the sessions the directory actually lists, applying exactly the rules the live portal applies:

curl "https://cool.jobmojito.com/functions/v1/catalogue-tag-get?id=sales-coaching-en" \
  -H "Authorization: Bearer $SUPABASE_JWT"

{
  "id": "sales-coaching-en",
  "tags_interview_set_filter": ["sales"],
  "matched_sessions": [
    { "id": "9c1b…e4f2", "name": "Handling price objections", "type": "coaching",
      "status": "active", "visibility": "merchant_public",
      "tags": ["sales", "objection-handling"] }
  ],
  "sub_directories": [],
  "catalogue_url": "https://coaching.example.com/catalogue/sales-coaching-en"
}

An empty matched_sessions almost always means one of four things: the session is still draft, its visibility is merchant_invite/merchant_unlisted, its type is not coaching/persona, or its tags are missing one of the filter’s tags.

Author a custom page (optional)

By default a directory renders as a plain grid: sub-directories, then sessions. Set content_md and your Markdown takes over the layout instead.

curl -X POST https://cool.jobmojito.com/functions/v1/catalogue-tag-update \
  -H "Authorization: Bearer $SUPABASE_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "sales-coaching-en",
    "content_md": "## Sales coaching\n\nStart with discovery, then work up to objections.\n\n[plan-progress]\n\n### Practise a conversation\n\n[sessions:filter=objection-handling,limit=6]\n\n### Go deeper\n\n[directory:sales-coaching-closing-en]\n"
  }'

Directives must sit alone on their own line — one on a line with other text renders as ordinary text:

Directive	Renders
`[plan-progress]`	The learner’s coaching-plan progress.
`[directory:<tag-id>]`	A card for one sub-directory.
`[session:<interview-id>]`	A card for one session.
`[sessions]`	Every session in this directory.
`[sessions:<term>]`	Sessions matching a term.
`[sessions:filter=<term>,limit=<n>]`	A filtered, capped list.

content_md is replaced wholesale. Read the current page with get_catalogue_directory and send the edited whole — not a fragment. Sending null removes the custom page and restores the default grid.

A directive can only show sessions the directory already lists. If [sessions:filter=…] renders nothing, check matched_sessions first — the filter narrows that set, it does not widen it.

content_md also renders chips, callouts, cards, columns and buttons on top of standard Markdown — see Format content with Markdown for the full vocabulary.

Several languages in one directory

One directory can be offered in several languages. Each language is a version with its own name, description, content_md, cover, sub-directories (tags_sub) and session filter (tags_interview_set_filter) — a page of its own, at the same address. The directory’s top-level fields are its default language (mojito_language_code); translations maps every other language to its version. A learner sees the version in the language they picked in the catalogue’s language switch (remembered across pages), else their portal language; when the directory lacks it, English, then the default. The switch appears only on directories with more than one language.

A coaching session itself has one language (its mojito_language_code). A “multilingual session” is therefore one session per language, gathered into one directory whose versions each list their own language’s sessions.

Create one session per language, with a language-specific tag

The filter is tags-only, so give each language’s sessions their own tag, e.g. sales-en and sales-sk, and set each session’s mojito_language_code.

curl -X POST https://cool.jobmojito.com/functions/v1/job-interview-create \
  -H "Authorization: Bearer $SUPABASE_JWT" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Obchodné námietky", "type": "coaching", "mojito_language_code": "sk",
        "interview_template_id": "TEMPLATE_UUID", "location": "remote",
        "status": "active", "visibility": "merchant_public", "tags": ["sales-sk"] }'

Create the directory with all its languages at once

Top-level fields are the default language; each translations entry is another language’s version. name is required in every version; every other field is optional. A version without tags_interview_set_filter lists no sessions.

curl -X POST https://cool.jobmojito.com/functions/v1/catalogue-tag-create \
  -H "Authorization: Bearer $SUPABASE_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "sales-coaching",
    "parent_tag": "home",
    "mojito_language_code": "en",
    "name": "Sales coaching",
    "tags_interview_set_filter": ["sales-en"],
    "content_md": "## Sales coaching\n\n[sessions]\n",
    "translations": {
      "sk": {
        "name": "Obchodný koučing",
        "tags_interview_set_filter": ["sales-sk"],
        "content_md": "## Obchodný koučing\n\n[sessions]\n"
      }
    }
  }'

Add, replace or remove a language later

translations on update_catalogue_directory is a patch per language — unlike content_md or tags_sub, languages you do not send are kept. An object replaces that language’s version; null removes it.

curl -X POST https://cool.jobmojito.com/functions/v1/catalogue-tag-update \
  -H "Authorization: Bearer $SUPABASE_JWT" \
  -H "Content-Type: application/json" \
  -d '{ "id": "sales-coaching",
        "translations": { "cs": { "name": "Obchodní koučink", "tags_interview_set_filter": ["sales-cs"] },
                          "de": null } }'

A version is replaced whole: to change one field of it, read it from get_catalogue_directory → translations.<lang> and send the edited version. translations: null removes every version but the default.

Verify every language

get_catalogue_directory returns languages (default first) and translations. Its matched_sessions and sub_directories describe the default language; pass mojito_language_code to see them for another version:

curl "https://cool.jobmojito.com/functions/v1/catalogue-tag-get?id=sales-coaching&mojito_language_code=sk" \
  -H "Authorization: Bearer $SUPABASE_JWT"

viewed_language in the response says which version the lists belong to. A language the directory does not have answers 422, so a missing translation cannot pass for a working one.

Changing the default language. Send mojito_language_code on update_catalogue_directory. If the directory already has that language, its version becomes the default and the old default stays as a version. If it does not, the default version is simply relabelled. Top-level fields sent in the same request always describe the default after the change. Sub-directories and cards. A directory id is the same in every language, so tags_sub and [directory:<id>] cards name the same ids in each version; each card renders in the learner’s language.

Coaching plans

coach_plan marks a directory (or a session) as a stage of a guided plan — demo, screening, 2nd, 3rd, closing, job-specific, other. Learners then see their progress through those stages wherever a page carries the [plan-progress] directive. Leave it null for anything that is not part of a plan.

Gotchas

Gotcha	What to do
Tag filter is an AND	Every tag in `tags_interview_set_filter` must be on the session. Filter on one tag unless you deliberately want the intersection.
`tags`, `tags_sub`, `tags_interview_set_filter` and `content_md` are all replace, not merge	Read the current value first, then send the full new value.
An empty `tags_interview_set_filter` matches everything tagged	Set the filter deliberately; `[]` is not “nothing”.
The directory `id` cannot be changed through the API	To rename the page, change `name`. To change the address, a merchant uses Change address in the admin catalogue editor: every `tags_sub`, `[directory:…]` card, `/catalogue/…` link, start directory and coaching-plan step moves with it, and the old address keeps redirecting. `get_catalogue_directory` accepts an old id and returns the directory under its current `id`.
`translations` is a patch per language; everything else is replace	Languages you do not send are kept, `null` removes one. Each version you send replaces that whole version.
A version without `tags_interview_set_filter` lists no sessions	Give every version its own filter — usually its language’s tag (`sales-sk`).
A row has `merged_into` set	It was folded into another directory as one of its languages; its address redirects there. Edit the directory `merged_into` names.
A session in `draft` never appears	Publish it with `set_interview_state` (or `status: "active"` on `update_interview`).
`merchant_invite` / `merchant_unlisted` sessions never appear	The catalogue only lists `public` and `merchant_public`.
An id in `tags_sub` that no longer resolves	`get_catalogue_directory` returns it in `tags_sub` but not in `sub_directories` — compare the two to find broken links.
A session’s `type_credit` decides which consumer credit bucket a learner spends	Set it on `update_interview` if the default (`interview_coach_manager`) is wrong for the session.

Portal branding

The mental model

How a session gets into a directory

Walkthrough

Several languages in one directory

Coaching plans

Gotchas

Next steps

Create an interview

Review results

​The mental model

​How a session gets into a directory

​Walkthrough

​Several languages in one directory

​Coaching plans

​Gotchas

​Next steps

Create an interview

Review results

The mental model

How a session gets into a directory

Walkthrough

Several languages in one directory

Coaching plans

Gotchas

Next steps