The Agent Surface

The rest of this manual keeps saying “tell your assistant”. This chapter is about what makes that sentence true: the single connection point your AI talks to, the credentials that let it in, and the controls that decide — precisely — what it may read, what it may change, and how you take that access back. You don’t need to be technical to use any of it; connecting your AI to your site takes a few taps on one page.

If you are technical, this chapter is also the receipts. Omumu’s agent surface is an MCP server, and every claim below maps to a scope, a permission, or a tool you can check against the generated catalog at the end of this chapter. That catalog — every tool, its parameters, its write category, its access restrictions, and the full permission list — is regenerated from the platform’s own capability inventory on every build of this manual, and the build fails if that inventory ever drifts from the code — the catalog below cannot quietly go out of date.

Concepts

The agent surface is one door. Every AI client — Claude on the web, ChatGPT, Claude Code in a terminal, a script you wrote — talks to your site through the same endpoint: your site’s address plus /mcp, speaking the Model Context Protocol (MCP), the open standard AI tools use to operate external systems. There is also one shared address for every site, https://omumu.com/mcp. It leads to the same door: it asks for your email first, finds the site you run, and hands you to that site’s own consent page. There is no second, softer API for agents. An agent acts as an authenticated identity on your site and passes the same permission checks the admin UI does; the surface is also advertised in machine-readable form — an API catalog at /.well-known/api-catalog, an MCP server card at /.well-known/mcp/server-card.json, and a plain-text onboarding guide for AI tools at /llms-onboarding.md on your site — so an agent pointed at your domain can find the door on its own. MCP access is a plan feature: it must be enabled on your site’s subscription tier for the surface to be live.

A tool is the unit of capability: one named operation, like omumu_course_create or omumu_offer_list, with typed parameters. What your assistant “can do” is exactly the set of tools its credential can call — nothing more. Discovery is fail-closed: when an agent asks the server what tools exist, it is shown only the ones its credential can actually use. An agent connected with read-only access doesn’t see a greyed-out “delete course” button; it doesn’t see the tool at all. The full catalog lives in the Reference below, grouped by the chapter of this manual that explains it.

There are two ways in, and choosing between them is simple:

An OAuth connection is for interactive assistants like Claude. The AI vendor’s app registers itself with your site, and you approve the connection on a consent screen on your own site — it names the client and your site, lists exactly what it is asking for, and offers Deny and Authorize. Only the people who run the site — its Headmaster and Staff — can approve: a Student who tries is told to ask the site’s owner. The check is not a one-off. It runs again on every call, so a connection stops working the moment its person is blocked, removed, or no longer Staff. Under the hood this is OAuth 2.0 with the current hardening expected of it: authorization code flow with PKCE, and rotating refresh tokens — every refresh issues a new token and retires the old one, and if a retired token is ever replayed (the signature of a stolen token), the site revokes that connection’s entire token family on the spot.

An API key is for headless use: scripts, scheduled jobs, Claude Code on your laptop. A key looks like omumu_ followed by a random secret and your site id, is stored only as a salted hash (like a password — the platform itself cannot recover it), and is shown to you exactly once, at creation. Each key carries its own permission picklist, so a reporting script can hold a key that reads courses and nothing else.

Scopes are the language of consent. An OAuth client asks in scopes — course:read, offer:write, email:read, and so on — and each scope maps to a named site permission that every tool checks. Three rules keep this honest. A write scope implies its read: course:write also grants course:read, because editing blind is useless. A client that asks for nothing gets the minimum: read access to courses, only. And a scope that reads people’s personal data is never implied by another scope: it has to be asked for by name, and you see it on the consent screen as its own line before it’s live. There are two. leads:read unlocks names and emails from your opt-in forms; Omumu doesn’t offer it to connecting apps, so a client must know to ask for it. handin:read unlocks what your students hand in — their text, a text file they upload, the transcript of a recording, the AI’s feedback and your staff’s — and, because reading hand-ins is something a creator connects Claude for, it is offered: an app that asks for everything your site offers will ask for it. Only a Headmaster’s connection can hold it. That rule is a recorded architectural decision, not a habit.

Some permissions no agent can hold at all, whichever way it came in: managing user accounts, changing site settings, and managing the API keys themselves are excluded from both the OAuth scope list and the API-key picklist. The last one matters most: an agent cannot mint, widen, or delete credentials — so a misbehaving agent can’t promote itself, and revoking it is always a decision only you can make.

Every connection can ask where it is. Two read-only tools need no permission at all. omumu_site_context tells the assistant which site this connection works on, your role there, which features the site has, and whether the site is connected to HighLevel, which a quiz needs before it can deliver its respondents there — the assistant is told to call it first. omumu_profile_get gives the connection a name made of the person’s first name and the site’s name, so an AI app that holds several Omumu connections shows each site as its own account.

Writes are categorized and rate-limited. Every tool carries a write category: read-only tools (listing, getting, reporting) have none; the rest are standard writes or skill writes (skills are the platform’s installable agent behaviors — their own chapter). Writes made with an API key pass a per-key, per-category rate limit, so a script stuck in a loop gets slowed down before it can flood your site with half-made courses.

Finally, the catalog also holds a few tools Omumu uses to operate the platform itself. They are not part of this manual, and they are not part of your surface: fail-closed discovery means the agents on your site never even see them.

Stated plainly, the gaps: there are no tools today for site settings, funnels, or analytics dashboards — those are admin-UI work. Files are covered: your assistant can upload anything the admin UI accepts — PDFs, images, audio, documents, archives and video — with omumu_resource_upload_presign, and the file travels straight to storage instead of through the conversation. omumu_generate_image makes new images. The catalog below is the honest inventory: if a tool isn’t in it, your assistant can’t do it, and this manual won’t pretend otherwise.

Hands-on

The walkthroughs continue with Mira from the Selling chapter — she runs her course business by talking to her AI assistant. This is the chapter where that setup actually happens.

Connect your AI from the setup page

Mira opens Integrations → Set up your AI assistant and answers one question: which AI does she use — Claude, ChatGPT, or Other. The page has already named the connector after her site; she can shorten the name, and the buttons below follow her edit.

She picks Claude and taps Add to Claude. Claude’s add-connector dialog opens already filled in with the name and her site’s address; she confirms. Claude finds the OAuth setup on its own and sends her to a consent page on her own site, which names Claude and her site and lists the scopes it wants. The list is already narrowed to what her account can actually grant, and it follows the rules from Concepts: no buyer PII, and reading her students’ hand-ins on a line of its own, nothing a scope didn’t name. She clicks Authorize. Back on the setup page, the status turns green — “Connected!” — and suggests a first message to try.

Every Claude plan can add a custom connector; the free plan allows one, and on Claude Team or Enterprise an owner adds it for the organisation. The consent screen is the grant moment: Deny costs nothing and can be retried; Authorize is what creates the connection.

The other choices work the same way, from the same page. ChatGPT gets numbered steps for making a personal plugin for the site, with the name and address ready to copy. Other has one-tap installs for Cursor and VS Code, and the one-line commands that add the site to Claude Code and Codex. The bare MCP address and the API keys sit under Advanced.

Connect through omumu.com/mcp

An AI app can also be pointed at the shared address, https://omumu.com/mcp, instead of the site’s own. Signing in then starts on Omumu: Mira enters the email she uses on her site and either types the 6-digit code Omumu emails her — it works once, for ten minutes — or uses her password. If that email runs several Omumu sites, she chooses the one this connection should work on; with one, she goes straight on. From there it is her site’s own consent page, exactly as above. Each site she connects this way is its own connection, and in apps that hold several accounts, its own account.

Give a script its own key

For Claude Code — and anything else headless — Mira creates an API key instead. In the admin UI: Integrations → MCP API Keys → create, where she names the key and ticks the permissions this key should carry — for her weekly sales-summary script, read permissions only. The key is displayed once, on the creation page, with a copy-it-now warning; the same page shows the exact one-line command that registers it with Claude Code:

claude mcp add-json omumu '{"type":"http","url":"https://<your site>/mcp","headers":{"Authorization":"Bearer <your key>"}}'

From then on, Claude Code on her laptop operates the site with exactly that key’s permissions. Lose the key and there is nothing to recover — the platform kept only the hash — so she creates a new one and deletes the old. One key per purpose is the honest pattern: the key ticked for writes is not the key her reporting script holds.

Stated plainly: creating and managing API keys is UI-only by design. There is no tool for it — that’s the “no agent manages credentials” rule from Concepts doing its job.

Let your AI read what students hand in

Mira’s course asks each student to record a practice call and hand it in. Every morning she wants her assistant to read the new ones and tell her what people keep getting stuck on, so she can fix the lesson instead of answering the same question ten times.

“Which hand-ins came in on the practice-call assignment since yesterday morning, and what are people struggling with?”

The assistant lists the assignment’s hand-ins since that time (omumu_submission_list): who handed in, when, their Light, and whether the AI or her staff have given feedback yet. Then it reads each one (omumu_submission_get): what the student wrote, the transcript of the recording, and the feedback rows. A student who uploads the call’s transcript as a .txt or .md file instead of pasting it gets read too: the assistant sees the file’s text, up to 1 MB. Mentor notes never come back, because they belong to the mentor. Both tools only read: nothing gets marked as seen and nothing is changed. Asking for hand-ins since the time of the last one it saw is how a daily check picks up only the new ones.

This needs handin:read on the connection. A connection made before the scope existed doesn’t have it, and refreshing the connection won’t add it, because a refresh has no consent screen and a personal-data scope is only ever granted on one. To add it, remove the connector in the AI app and add it again. The new consent screen names the hand-ins line, and Mira authorizes it. Only a Headmaster can connect this way; a Staff member’s connection never gets the scope.

Take an agent’s access back

Revoking is the control that makes granting safe, so here is exactly where it stands.

For API keys it is immediate and self-serve: Integrations → MCP API Keys, delete the key, confirm. The hash is gone and every request bearing that key fails from that moment. Nothing the agent did survives as access — only as ordinary site data you can still edit.

For OAuth connections it is self-serve too. The setup page lists Connected AIs: each one with the AI’s name, who connected it, when, and when it was last active. Disconnect ends that connection’s access and refresh tokens, so the AI’s next call fails; using it again means connecting it anew. A Headmaster sees every connection on the site; Staff see only their own. Connecting the same AI again replaces its earlier entry instead of adding a second one. On top of that, the token machinery limits the damage of a stolen token by itself — refresh tokens rotate on every use, and a replayed old token kills the whole family.

A first real conversation

Connected, Mira starts the way anyone should:

“What can you actually do on my site?”

The assistant calls omumu_site_context first, so it knows which site it is on and what Mira may do there, then answers from its live tool list — which, fail-closed, is exactly what her grant allows. Then she gives it the real test, the same pre-sale move from the Selling chapter, end to end:

“Create a course called AI Email Triage — one module, five lesson outlines — and put up a 790 NOK early-bird offer for it.”

The assistant creates the course (omumu_course_create), a module inside it (omumu_module_create), five draft lessons (omumu_lesson_create), then the offer around it (omumu_offer_create, omumu_offer_add_product) and reports back with the checkout URL. Mira opens Products → Courses and Sales and marketing → Offers and finds everything the conversation claimed — the same objects, editable in the same UI, indistinguishable from work done by hand. That is the whole design: the conversation is not a veneer over a separate system. It is your site, through one door, with the keys you chose to hand over.

Reference

Getting Started

omumu_brand_get

Gets the site’s Brand: the published choices and revision the site wears, the draft choices and whether they differ from published, the draft’s derived light and dark color roles and any contrast adjustments, the font catalog identifiers, roundness steps and CTA colors to choose from, and the admin editor URL. Publishing is a human step: the creator publishes the draft in admin at editorUrl.

• Write category: read-only
• Access: requires the BRAND_READ permission

No parameters.

omumu_brand_update

Merges any of the given choices into the site’s Brand draft; choices left out stay as they are, and an invalid color, unknown font or logo that is not this site’s refuses the whole update. Returns the Brand as omumu_brand_get does. The draft is not live: the Site’s pages and its public Brand JSON keep the published Brand until the creator reviews the draft and publishes it themselves in admin, at the returned editorUrl. There is no tool to publish.

• Write category: standard write
• Access: requires the BRAND_WRITE permission

Courses & Content

omumu_answer_create

Creates an answer option for a question. On an outcome quiz, link this answer to one or more buckets using omumu_option_point_create after creating the answer. On a score quiz, set points so choosing this answer adds (or, for a reverse-worded statement, subtracts) that many points from its question’s scale. tag, when set, is applied at completion to an identified respondent who chose this answer, alongside the bucket, door and completion tags — the way a single background answer (“do you have the book?”) becomes a fact on the contact, usable by HAS_TAG.

• Write category: standard write
• Access: requires the QUIZ_WRITE permission

omumu_answer_update

Updates an answer option’s label, value, points (score quizzes only) and/or tag (applied at completion to an identified respondent who chose this answer)

• Write category: standard write
• Access: requires the QUIZ_WRITE permission

omumu_assignment_create

Creates an assignment attached to exactly one scope: a course, a module, a lesson, or the site itself. Provide at most one of courseId, moduleId, or lessonId — more than one is rejected. Omitting all three creates a SITE assignment, shown to creators as All courses: attached to the whole site and handed in on its own page /assignments/{aid}, where students write about everything they have rather than one course. Students find it first on their Assignments page (/assignments); creators find it in the All courses group of /admin/assignments. A new SITE assignment goes last in the All courses order; move it with omumu_assignment_reorder. It counts toward no course’s completion and is rated against each student’s own accessible courses. COURSE scope: the assignment appears on the course homepage and is visible across all its modules and lessons. MODULE scope: the assignment is shown within a specific module and reflects that module’s work. LESSON scope: the assignment is tied to a single lesson and reflects its content. New assignments default to DRAFT status; pass status=PUBLISHED to make the assignment immediately visible to students. Requires the MCP_COURSES feature (Starter tier or above).

• Write category: standard write
• Access: requires the COURSE_WRITE permission

omumu_assignment_list

Returns all assignments (DRAFT and PUBLISHED) for a course, with each assignment’s scope kind (COURSE, MODULE, LESSON, or SITE) and the scope’s id stated explicitly. Without a courseId it returns the site’s SITE assignments only — the All courses assignments, attached to the whole site rather than to any course, each handed in on its own page /assignments/{aid} — in the All courses order, with each one’s 0-based sortOrder; order them with omumu_assignment_reorder. Course, module and lesson assignments report no sortOrder. Requires the MCP_COURSES feature (Starter tier or above).

• Write category: read-only
• Access: requires the COURSE_READ permission

omumu_assignment_reorder

Moves a SITE assignment (an All courses assignment) to a 0-based position in the site’s All courses order, the order students see first on /assignments and the admin sees in the All courses group of /admin/assignments. The other SITE assignments shift to make room; a position past the end places the assignment last. Draft ones hold their place in the order too. Only SITE assignments have an order: a course, module or lesson assignment is refused, as is an assignment of another site. Read the current order with omumu_assignment_list without a courseId. Returns the moved assignment with its new sortOrder. Requires the MCP_COURSES feature (Starter tier or above).

• Write category: standard write
• Access: requires the COURSE_WRITE permission

omumu_assignment_update

Updates an existing assignment’s title, description, ratingPrompt, status, and/or scope. Provide at most one of courseId, moduleId, or lessonId to set the new scope; omitting all three means the SITE scope, so omit them exactly when updating a SITE assignment. The new scope must belong to the same course as the assignment — a scope change across the course boundary (to or from the SITE scope) is rejected: that is a different assignment. A SITE assignment is an All courses assignment, handed in on its own page /assignments/{aid}; its position in the All courses order is changed with omumu_assignment_reorder, not here. Fields not provided are left unchanged. Requires the MCP_COURSES feature (Starter tier or above).

• Write category: standard write
• Access: requires the COURSE_WRITE permission

omumu_bucket_create

Creates a result bucket for the quiz. On an outcome quiz it’s a category users are sorted into by plurality — after creating buckets, link answers to them using omumu_option_point_create. On a score quiz it’s a profile: set minPercent (0-100) and the bucket with the highest minPercent at or below the respondent’s total percent wins; a bucket with no minPercent never wins. Each bucket can trigger actions: send email sequence, grant course access, redirect to URL. description may be Quill delta JSON when descriptionEncoding is QUILL_JSON. On a score quiz, description supports result-copy placeholders (see omumu_note_create for the full set). videoResourceId attaches one video, shown after the description on the result page — the resource must already exist on this site (via the presigned video upload) and be a video.

• Write category: standard write
• Access: requires the QUIZ_WRITE permission

omumu_bucket_update

Updates a bucket’s properties including actions (email sequence, course, redirect, tag) and, for a score quiz, its percent-range profile fields (minPercent, descriptionEncoding). Pass null for an action to remove it, or leave the key out to keep it unchanged. emailSequenceId and courseId must be a sequence or course on this site. videoResourceId attaches one video (must belong to this site and be a video); pass null to remove it.

• Write category: standard write
• Access: requires the QUIZ_WRITE permission

omumu_checklist_batch_create

Creates multiple checklist items for a lesson in one call (max 100). Atomic — all items are created or none. Useful for AI workflows that generate complete checklists at once.

• Write category: standard write
• Access: requires the COURSE_WRITE permission

omumu_checklist_item_create

Adds a new checklist item to a lesson. Checklist items are actionable tasks that students complete to earn XP. Items are auto-appended at the end of the list.

• Write category: standard write
• Access: requires the COURSE_WRITE permission

omumu_checklist_item_delete

Permanently deletes a checklist item and any associated user progress. Remaining items are re-sorted automatically.

• Write category: standard write
• Access: requires the COURSE_WRITE permission

omumu_checklist_item_list

Lists all checklist items for a specific lesson, ordered by sort order.

• Write category: read-only
• Access: requires the COURSE_READ permission

omumu_checklist_item_reorder

Changes the sort order of a checklist item within its lesson.

• Write category: standard write
• Access: requires the COURSE_WRITE permission

omumu_checklist_item_update

Updates the description and/or XP value of an existing checklist item.

• Write category: standard write
• Access: requires the COURSE_WRITE permission

omumu_course_create

Creates a new course in the user’s site with the specified title and tagline. The course is live immediately for learners with access — there is no draft step — and the result’s publicUrl is the address of its learner-facing course page, which requires sign-in and access to the course. After creating, add modules (omumu_module_create) and lessons (omumu_lesson_create) to build the course structure. To grant access via an opt-in form, pass the course ID to omumu_optinform_update(courseId).

• Write category: standard write
• Access: requires the COURSE_WRITE permission

omumu_course_delete

Permanently deletes a course and all its content

• Write category: standard write
• Access: requires the COURSE_DELETE permission

omumu_course_duplicate

Creates a complete copy of an existing course including all modules and lessons

• Write category: standard write
• Access: requires the COURSE_WRITE permission

omumu_course_get

Retrieves detailed information about a specific course

• Write category: read-only
• Access: requires the COURSE_READ permission

omumu_course_list

Lists all courses in the user’s site with optional module inclusion

• Write category: read-only
• Access: requires the COURSE_READ permission

omumu_course_update

Updates the basic information of a course. The change is live immediately for learners with access — there is no draft step — and the result’s publicUrl is the address of its learner-facing course page, which requires sign-in and access to the course.

• Write category: standard write
• Access: requires the COURSE_WRITE permission

omumu_door_create

Creates a door on a quiz: the next step (heading, text, button label/URL or an embedded checkout, optional tag) offered on the result page, chosen from the respondent’s answers rather than the score. Doors are tried in sortOrder and the first whose condition holds wins; a door with empty clauses always holds and is the default — put it last. A clause is {kind: “ANSWER_CHOSEN”, questionId, answerId} (a specific answer was chosen) or {kind: “QUESTION_ANSWERED”, questionId} (the question has any answer, non-blank for free text). Every clause in a door’s condition must hold (AND only — no OR, no NOT); express “either of these answers” as two doors with the same copy. Every clause’s question (and answer, for ANSWER_CHOSEN) must belong to this quiz. Works on both outcome and score quizzes. On a score quiz, heading and text support placeholders: Result-copy placeholders, substituted at render time in this text: [firstName] (the respondent’s first name), [answer:] (the chosen answer label(s), or the free text, for that question), [scale:] (that scale’s percent, e.g. “72 %”), [highestScale] and [lowestScale] (scale names), [highestQuestion] (the header of the question with the highest-scoring answer). An unknown placeholder or one that resolves empty renders as nothing.

• Write category: standard write
• Access: requires the QUIZ_WRITE permission

omumu_door_delete

Deletes a door and its clauses.

• Write category: standard write
• Access: requires the QUIZ_WRITE permission

omumu_door_update

Updates a door’s copy, checkout embed, sort order, tag and/or clauses. A clauses array replaces this door’s condition wholesale rather than appending to it — include every clause you want kept. Result-copy placeholders, substituted at render time in this text: [firstName] (the respondent’s first name), [answer:] (the chosen answer label(s), or the free text, for that question), [scale:] (that scale’s percent, e.g. “72 %”), [highestScale] and [lowestScale] (scale names), [highestQuestion] (the header of the question with the highest-scoring answer). An unknown placeholder or one that resolves empty renders as nothing.

• Write category: standard write
• Access: requires the QUIZ_WRITE permission

omumu_generate_image

Generates an image from a text prompt using AI and stores it as a resource. Optionally attach the generated image directly to a course, module, or lesson. When targeting an entity, aspect ratio defaults to 16:9 (ideal for course illustrations).

• Write category: standard write
• Access: requires the MEDIA_GENERATE permission

omumu_lesson_create

Creates a new lesson within a module. Returns a compact summary {id, title, sortOrder} only — the submitted description is not echoed back, to keep responses small when authoring long-form content.

• Write category: standard write
• Access: requires the COURSE_WRITE permission

omumu_lesson_resource_create

Creates a new content block within a lesson. Content can be Markdown or QuillDelta JSON (auto-detected). Optionally attaches an uploaded SiteResource (e.g. a video) via resourceId. Use this to add rich text content to lessons - the ‘meat’ of course content.

• Write category: standard write
• Access: requires the COURSE_WRITE permission

omumu_lesson_resource_delete

Permanently deletes a content block from a lesson.

• Write category: standard write
• Access: requires the COURSE_WRITE permission

omumu_lesson_resource_list

Lists all content blocks for a specific lesson.

• Write category: read-only
• Access: requires the COURSE_READ permission

omumu_lesson_resource_update

Updates an existing content block. Content can be Markdown or QuillDelta JSON (auto-detected). Optionally replaces the attached SiteResource. Pass an empty string for resourceId to clear the attachment.

• Write category: standard write
• Access: requires the COURSE_WRITE permission

omumu_lesson_update

Updates a lesson’s title and/or description. Description can be Markdown or QuillDelta JSON (auto-detected). Returns a compact summary {id, title, sortOrder} only — the submitted description is not echoed back, to keep responses small when authoring long-form content.

• Write category: standard write
• Access: requires the COURSE_WRITE permission

omumu_module_copy

Copies a module (including all its lessons and resources) from its current course into a different target course. Both the source module’s course and the target course must belong to the user’s site.

• Write category: standard write
• Access: requires the COURSE_WRITE permission

omumu_module_create

Creates a new module within a course

• Write category: standard write
• Access: requires the COURSE_WRITE permission

omumu_module_list

Lists all modules in a specific course with optional lesson inclusion

• Write category: read-only
• Access: requires the COURSE_READ permission

omumu_module_update

Updates a module’s title and/or description. Description can be Markdown or QuillDelta JSON (auto-detected).

• Write category: standard write
• Access: requires the COURSE_WRITE permission

omumu_note_create

Creates a note on a quiz: answer-conditioned copy shown on the result page between the lowest-scale section and the door, whenever its condition holds. Unlike a door, every matching note is shown, in sortOrder (notes compose rather than compete) — there is no first-match-wins and no default note. A clause is {kind: “ANSWER_CHOSEN”, questionId, answerId} (a specific answer was chosen) or {kind: “QUESTION_ANSWERED”, questionId} (the question has any answer, non-blank for free text; use this to quote a free-text answer back with [answer:]). Every clause in a note’s condition must hold (AND only — no OR, no NOT). Empty or omitted clauses makes the note always show. Every clause’s question (and answer, for ANSWER_CHOSEN) must belong to this quiz. A note has no button and no tag. Result-copy placeholders, substituted at render time in this text: [firstName] (the respondent’s first name), [answer:] (the chosen answer label(s), or the free text, for that question), [scale:] (that scale’s percent, e.g. “72 %”), [highestScale] and [lowestScale] (scale names), [highestQuestion] (the header of the question with the highest-scoring answer). An unknown placeholder or one that resolves empty renders as nothing.

• Write category: standard write
• Access: requires the QUIZ_WRITE permission

omumu_note_delete

Deletes a note and its clauses.

• Write category: standard write
• Access: requires the QUIZ_WRITE permission

omumu_note_update

Updates a note’s text, sort order and/or clauses. A clauses array replaces this note’s condition wholesale rather than appending to it — include every clause you want kept. Result-copy placeholders, substituted at render time in this text: [firstName] (the respondent’s first name), [answer:] (the chosen answer label(s), or the free text, for that question), [scale:] (that scale’s percent, e.g. “72 %”), [highestScale] and [lowestScale] (scale names), [highestQuestion] (the header of the question with the highest-scoring answer). An unknown placeholder or one that resolves empty renders as nothing.

• Write category: standard write
• Access: requires the QUIZ_WRITE permission

omumu_option_point_batch

Outcome quizzes only. Efficiently set up quiz scoring by creating or updating multiple option points in a single call. If an answer-bucket pair already exists, updates its weight. Use this after creating questions, answers, and buckets to configure the scoring matrix. Example: [{answerId: ‘a1’, bucketId: ‘b1’, weight: 2.0}, {answerId: ‘a1’, bucketId: ‘b2’, weight: 1.0}]

• Write category: standard write
• Access: requires the QUIZ_WRITE permission

omumu_option_point_create

Outcome quizzes only. Creates an option point linking an answer to a bucket with a weight. When a user selects this answer, the weight is added to the bucket’s score. After all questions, the bucket with the highest total score becomes the user’s result. Example: Answer ‘I exercise daily’ → Bucket ‘Fitness Enthusiast’ with weight 2.0. A score quiz does not use option points — give its answers points instead.

• Write category: standard write
• Access: requires the QUIZ_WRITE permission

omumu_option_point_delete

Outcome quizzes only. Removes the link between an answer and a bucket, so selecting this answer no longer contributes to that bucket’s score.

• Write category: standard write
• Access: requires the QUIZ_WRITE permission

omumu_option_point_list

Outcome quizzes only. Lists all option points for a specific question, showing which answers are linked to which buckets and their weights.

• Write category: read-only
• Access: requires the QUIZ_READ permission

omumu_option_point_update

Outcome quizzes only. Updates an option point’s weight to adjust scoring influence.

• Write category: standard write
• Access: requires the QUIZ_WRITE permission

omumu_question_create

Creates a new question in a quiz. After creating a question, add answer options with omumu_answer_create. RADIO type shows single-choice radio buttons, CHECKBOX allows multiple selections. On a score quiz, assign the question to a scale with scaleId (created with omumu_scale_create) so its answers’ points feed that scale; a question with no scaleId is an unscored background question.

• Write category: standard write
• Access: requires the QUIZ_WRITE permission

omumu_question_update

Updates a question’s header, type and/or scale assignment (score quizzes only). The scale must belong to the same quiz.

• Write category: standard write
• Access: requires the QUIZ_WRITE permission

omumu_quiz_build

Creates a whole quiz — fields, scales, questions with answers, result buckets, doors, notes and (outcome quizzes) option points — from a single definition object, all or nothing: every cross-reference is validated before anything is written, and a bad reference fails the call naming every problem found, leaving no quiz, scale, question, answer, bucket, door, note or option point behind. Use this instead of the granular tools (omumu_quiz_create, omumu_scale_create, omumu_question_create, omumu_answer_create, omumu_bucket_create, omumu_door_create, omumu_note_create, omumu_option_point_create) when authoring a quiz from scratch; those granular tools remain the way to edit an existing quiz afterwards — this tool only creates. definition.quiz mirrors omumu_quiz_create’s fields: {label (required), scoring: OUTCOME|SCORE, completionTag?, captureTag?, askFirstName?, noClearLowestText?, noClearLowestTextEncoding?, preQuizOptinFormId?, postQuizOptinFormId?, destinations? (e.g. [“HIGHLEVEL”]), highLevelResultLinkField?}. destinations lists where, besides Omumu, the quiz delivers each identified respondent once their result is saved; the only destination is HIGHLEVEL, which upserts the respondent as a contact (first name, email, phone) in the site’s HighLevel sub-account with the tags this quiz applied to them. Adding HIGHLEVEL is refused unless the site’s plan includes CRM_DESTINATIONS and a Headmaster has connected HighLevel (omumu_site_context reports highLevelConnected); no tool reads or writes the connection itself. highLevelResultLinkField names a custom contact field in that sub-account (its field key, e.g. contact.quiz_result_link; the contact. prefix is dropped) that receives the respondent’s result link at completion, written before the tags so a workflow fired by the completion tag can use it; it needs the HIGHLEVEL destination, and null removes it. definition.scales (SCORE quizzes only) is [{key (required, your own id — any string unique among scales), name, sortOrder?, lowestScaleText?, lowestScaleTextEncoding?, levels?: [{name, minPercent (0-100), text?, textEncoding?, sortOrder?}]}]. definition.questions is [{key (required, unique among questions), header, type: RADIO|CHECKBOX|TEXTAREA|RADIO_OTHER|CHECKBOX_OTHER, sortOrder?, scaleKey? (must name a scale in this same definition), answers: [{key (required, unique among every answer in this definition), label, value?, points? (SCORE quizzes), sortOrder?, tag? (applied at completion to an identified respondent who chose this answer)}]}]. definition.buckets is [{key (required, unique among buckets), name, description?, descriptionEncoding?, minPercent? (SCORE quizzes, 0-100), tag?, redirectUrl?, successMessage?, emailSequenceId?, courseId?, videoResourceId?}] — emailSequenceId, courseId and videoResourceId must already exist on this site. definition.doors is [{name, heading?, text?, textEncoding?, buttonLabel?, buttonUrl?, checkoutEmbedUrl?, tag?, sortOrder?, clauses?: [{kind: ANSWER_CHOSEN|QUESTION_ANSWERED, questionKey, answerKey?}]}] — doors have no key, nothing references one; tried in sortOrder, first matching condition wins, empty clauses is the default door. definition.notes is [{text, textEncoding?, sortOrder?, clauses?: […]}] — same clause shape as doors, but every matching note is shown, not just the first. A clause’s questionKey/answerKey name a question/answer in this same definition, never a real id; an ANSWER_CHOSEN clause’s answerKey must belong to its questionKey’s question. All clauses in a condition must hold (AND only). definition.optionPoints (OUTCOME quizzes only) is [{answerKey, bucketKey, weight?}], both keys naming entries in this same definition. scales is only valid on a SCORE quiz; optionPoints is only valid on an OUTCOME quiz. The response returns quizId, publicUrl (the quiz’s result/take link), and the real ids created for every key you chose: scaleIds, questionIds, answerIds, bucketIds (each a {yourKey: realId} map), plus doorIds and noteIds (plain lists, since doors and notes have no keys). omumu_quiz_get is this tool’s natural counterpart: fetch an existing quiz with includeQuestions, includeScales, includeBuckets, includeDoors and includeNotes all true, and its output — with ids used in place of keys — is already shaped like a definition you could feed back into this tool (minus doors’/notes’ clauses, which name questions/answers by id there and must be rekeyed). Result-copy placeholders, substituted at render time in this text: [firstName] (the respondent’s first name), [answer:] (the chosen answer label(s), or the free text, for that question), [scale:] (that scale’s percent, e.g. “72 %”), [highestScale] and [lowestScale] (scale names), [highestQuestion] (the header of the question with the highest-scoring answer). An unknown placeholder or one that resolves empty renders as nothing.

• Write category: standard write
• Access: requires the QUIZ_WRITE permission

omumu_quiz_create

Creates a new quiz (question set). The scoring mode decides how it’s judged: OUTCOME (default) sorts the respondent into one of several named buckets by plurality; SCORE accumulates points per named scale (see omumu_scale_create) and reports a percent per scale plus a total. Quizzes can optionally link to opt-in forms for email capture: preQuizOptinFormId shows an email capture form before the quiz starts (for non-logged-in users), postQuizOptinFormId shows one after quiz completion — that post-quiz form also submits itself as soon as the email field validates, before the respondent presses the final button (early contact capture), so the contact exists even if they never finish. After creating an outcome quiz, add questions with omumu_question_create, then add answer options with omumu_answer_create, create result buckets with omumu_bucket_create, and finally link answers to buckets using omumu_option_point_create. After creating a score quiz, create its scales with omumu_scale_create, then questions assigned to a scale, then answers carrying points. On a score quiz, noClearLowestText is shown on the result page when the respondent’s scales are tied or there are fewer than two scales (no clear lowest); leave unset for no such section. noClearLowestText supports result-copy placeholders (see omumu_note_create for the full set). When askFirstName is true, an anonymous taker sees a first-name field on the start screen before the first question; the name is stored on the lead, copied to the user record on identification (never overwriting an existing name), and used for the [firstName] placeholder and the result page’s greeting. completionTag, when set, is applied to an identified respondent when their result is saved, regardless of which bucket won — so an automation can tell a finisher apart from someone who only left an email (e.g. FORM_SUBMIT on the post-quiz form, then WAIT, then HAS_TAG on this tag to find abandoners). captureTag, when set, is applied to the respondent at early contact capture — the moment the post-quiz form’s email is valid, before the final button — and is never removed at completion, so a CRM workflow or automation has a tag to fire on for someone who left their email but may not finish. A respondent who never reaches the form never gets it. Each answer can carry its own tag too (see omumu_answer_create).

• Write category: standard write
• Access: requires the QUIZ_WRITE permission

omumu_quiz_get

Gets a quiz with optional questions, result buckets and scales. Always returns the scoring mode, askFirstName, completionTag, captureTag, destinations, highLevelResultLinkField (when set) and, for a score quiz, noClearLowestText/noClearLowestTextEncoding. Returns preQuizOptinFormId and postQuizOptinFormId if linked opt-in forms are configured for email capture. For an outcome quiz, set includeQuestions=true, includeBuckets=true, and includeOptionPoints=true to see the complete scoring configuration — option points link answers to buckets with weights, and the bucket with the highest total weight from selected answers wins. With includeQuestions=true each answer also returns its tag, if any. For a score quiz, set includeQuestions=true and includeScales=true — each question returns its scaleId and each answer its points; each scale also returns its levels, lowestScaleText and lowestScaleTextEncoding; includeBuckets=true also returns each bucket’s minPercent, descriptionEncoding and videoResourceId (its profile configuration). Result-copy placeholders, substituted at render time in this text: [firstName] (the respondent’s first name), [answer:] (the chosen answer label(s), or the free text, for that question), [scale:] (that scale’s percent, e.g. “72 %”), [highestScale] and [lowestScale] (scale names), [highestQuestion] (the header of the question with the highest-scoring answer). An unknown placeholder or one that resolves empty renders as nothing.

• Write category: read-only
• Access: requires the QUIZ_READ permission

omumu_quiz_list

Lists all quizzes for the current site

• Write category: read-only
• Access: requires the QUIZ_READ permission

No parameters.

omumu_quiz_update

Updates a quiz’s properties including label, scoring mode, linked opt-in forms for email capture, (score quizzes only) the no-clear-lowest text, the ask-first-name flag, the completion tag, the capture tag and the destinations. Pre-quiz opt-in forms appear before the quiz starts for non-logged-in users. Post-quiz opt-in forms appear after completion. Set to null to remove the link. destinations lists where, besides Omumu, the quiz delivers each identified respondent once their result is saved; the only destination is HIGHLEVEL, which upserts the respondent as a contact (first name, email, phone) in the site’s HighLevel sub-account with the tags this quiz applied to them. Adding HIGHLEVEL is refused unless the site’s plan includes CRM_DESTINATIONS and a Headmaster has connected HighLevel (omumu_site_context reports highLevelConnected); no tool reads or writes the connection itself. highLevelResultLinkField names a custom contact field in that sub-account (its field key, e.g. contact.quiz_result_link; the contact. prefix is dropped) that receives the respondent’s result link at completion, written before the tags so a workflow fired by the completion tag can use it; it needs the HIGHLEVEL destination, and null removes it.

• Write category: standard write
• Access: requires the QUIZ_WRITE permission

omumu_resource_delete

Permanently deletes a SiteResource. Fails if the resource is currently referenced by any lesson, page, or other entity — remove those references first.

• Write category: standard write
• Access: requires the RESOURCE_DELETE permission

omumu_resource_get

Returns the full metadata for a single SiteResource, including CDN URI, thumbnail, MIME type, file size, and video processing status (when applicable).

• Write category: read-only
• Access: requires the RESOURCE_READ permission

omumu_resource_list

Lists uploaded files (videos, images, PDFs, etc.) on the current site. Optionally filter by a MIME type prefix (e.g. ‘video/’ or ‘image/png’) and paginate with limit/offset. Returns total count so callers can implement ‘load more’ paging.

• Write category: read-only
• Access: requires the RESOURCE_READ permission

omumu_resource_update

Updates the title and/or description of a SiteResource. Does not change the underlying file — re-upload for that. At least one of title/description must be provided.

• Write category: standard write
• Access: requires the RESOURCE_WRITE permission

omumu_resource_upload_presign

Prepares the upload of any file type the site accepts (PDF, image, audio, text, office document, archive, video) without the bytes passing through the MCP channel. Check ‘uploadProtocol’ in the result. ‘put’: send exactly ‘length’ bytes of the file as the body of an HTTP PUT to ‘uploadUrl’ (no Authorization header; the URL is a single-use ticket that expires at ‘expiresAt’). The response is 201 with the new resource (id, fileName, fileSize, uri); use its id with omumu_lesson_resource_create or omumu_set_image. A failed PUT needs a new presign. ‘tus’: a video; follow omumu_resource_upload_video_presign’s instructions with the same fields (resourceId is usable right away). Uploads count against the site’s per-file and total storage limits.

• Write category: standard write
• Access: requires the RESOURCE_WRITE permission

omumu_resource_upload_video_presign

Creates a SiteResource for a video (videoProcessingStatus QUEUED) and returns a presigned TUS (tus.io) upload the caller PATCHes bytes to directly — the video never passes through the MCP server or the JSON-RPC channel. Use the returned resourceId right away with omumu_lesson_resource_create or omumu_set_image; poll omumu_resource_get for videoProcessingStatus once the upload finishes and Bunny’s webhook reconciles it. To perform the upload: POST to the returned ‘endpoint’ with headers AuthorizationSignature, AuthorizationExpire, VideoId (the ‘guid’ field), LibraryId, Upload-Length (the file size), and Tus-Resumable: 1.0.0 — Bunny responds with a Location header, which is the URL to PATCH the file bytes to (Content-Type: application/offset+octet-stream, Upload-Offset: 0, Tus-Resumable: 1.0.0).

• Write category: standard write
• Access: requires the RESOURCE_WRITE permission

omumu_scale_create

Creates a named scale on a score quiz (e.g. “Listening”). Assign questions to it with omumu_question_create/update’s scaleId; the scale’s maximum is derived from its questions’ answer points, never set here. Optionally carries its levels inline and a lowest-scale text. Each level is a percent range with copy only (no tags, sequences or grants): the level with the highest minPercent at or below the respondent’s percent on this scale is shown on its result card. lowestScaleText is shown once on the result page when this scale is the respondent’s lowest by percent. Level text and lowestScaleText support result-copy placeholders (see omumu_note_create for the full set).

• Write category: standard write
• Access: requires the QUIZ_WRITE permission

omumu_scale_delete

Deletes a scale. Questions assigned to it become unscored background questions rather than being deleted.

• Write category: standard write
• Access: requires the QUIZ_WRITE permission

omumu_scale_update

Updates a scale’s name, sort order, levels and/or lowest-scale text. A levels array replaces the scale’s levels wholesale rather than appending to them — include every level you want kept.

• Write category: standard write
• Access: requires the QUIZ_WRITE permission

omumu_set_image

Attach an existing image resource to a course, module, or lesson. Use this to reuse an already generated image or to change an entity’s image.

• Write category: standard write
• Access: requires the COURSE_WRITE permission

Selling

omumu_offer_add_bump

Adds a bump offer to an existing offer. The bump appears as a checkbox on the checkout page. Both offers must belong to the same site. An offer cannot be its own bump.

• Write category: standard write
• Access: requires the OFFER_WRITE permission

omumu_offer_add_product

Adds a product (course or skill) to an existing offer. The offer must not be live or ended. Subscription plans (SAAS) are added via omumu_offer_add_subscription_plan instead.

• Write category: standard write
• Access: requires the OFFER_WRITE permission

omumu_offer_add_subscription_plan

Adds a subscription plan (Omumu platform access) to an existing offer. When the offer is purchased, the buyer gets a new Omumu site provisioned on the plan’s tier. Use SAAS_BASIC for the Omumu Basic plan.

• Write category: standard write
• Access: requires the OFFER_WRITE permission

omumu_offer_create

Creates a purchasable offer with title, price, courses, and payment providers. Setting validFrom to now or a past time publishes the offer. status is ‘live’ only when checkout takes orders; otherwise ‘paused’ with pausedReason. A payment provider the site hasn’t connected is refused (Invoice always works). If the sales page still holds unrewritten placeholders, a validFrom is dropped rather than failing the creation: the offer comes back not_published with salesPagePlaceholders filled and a matching warnings message — rewrite the page with omumu_page_update, then publish with omumu_offer_update. Returns the offer with its checkout URL.

• Write category: standard write
• Access: requires the OFFER_WRITE permission

omumu_offer_delete

Deletes an offer. Only offers that have not been sold can be deleted.

• Write category: standard write
• Access: requires the OFFER_DELETE permission

omumu_offer_dna_architect_brief

Returns the complete offer-architecture task for a DNA — the method rules, the embedded research verbatim, interview context, the format-intent constraint when declared, the freshly-resolved fenced existing material, and the exact output schema. Pure read: no AI call, no budget interaction. Run your own architecture using the instructions and context, then submit with omumu_offer_dna_architect_submit. Step order: omumu_offer_dna_research_submit → omumu_offer_dna_architect_brief → omumu_offer_dna_architect_submit → omumu_offer_create and omumu_page_create.

• Write category: read-only
• Access: requires the OFFER_READ permission

omumu_offer_dna_architect_submit

Validates and stores an offer architecture the calling agent produced itself — no AI budget is spent. The proposal object must have architecture, compression, and score matching the schema returned by omumu_offer_dna_architect_brief. Degenerate, empty (no solutions and no stack), or malformed submissions are rejected with a descriptive error; nothing is stored on failure. Re-submitting replaces all three prior sections. Next step: create the offer with omumu_offer_create and its sales page with omumu_page_create, using the DNA’s architecture.

• Write category: standard write
• Access: requires the OFFER_WRITE permission

omumu_offer_dna_create

Starts a research-based offer document (ADR-0034) from a creator interview. Returns its id; follow with omumu_offer_dna_research_brief.

• Write category: standard write
• Access: requires the OFFER_WRITE permission

omumu_offer_dna_get

Returns the full Offer DNA document: interview, cited research, architecture, compression (touchstone + big four), and score.

• Write category: read-only
• Access: requires the OFFER_READ permission

omumu_offer_dna_list

Lists the site’s Offer DNA documents, newest first, with their completion state.

• Write category: read-only
• Access: requires the OFFER_READ permission

No parameters.

omumu_offer_dna_research_brief

Returns the complete voice-of-customer research task for a DNA — the method rules, interview context and the exact output schema the submission must match. Pure read: no AI call, no budget interaction. Run your own web research using the instructions and context, then submit with omumu_offer_dna_research_submit. Next step after submitting: omumu_offer_dna_architect_brief.

• Write category: read-only
• Access: requires the OFFER_READ permission

omumu_offer_dna_research_submit

Validates and stores research the calling agent ran itself — no AI budget is spent. The research object must match the schema returned by omumu_offer_dna_research_brief. Degenerate, empty-findings, or malformed submissions are rejected with a descriptive error; nothing is stored on failure. Re-submitting replaces the research section while leaving any existing architecture untouched. Next step: omumu_offer_dna_architect_brief.

• Write category: standard write
• Access: requires the OFFER_WRITE permission

omumu_offer_get

Gets an offer by ID with full details including checkout URL, status (with pausedReason when paused), products, pricing, payment providers, and salesPagePlaceholders (unrewritten starter prompts still on the sales page, each with section, field, and excerpt; empty when none remain or the offer has no sales page)

• Write category: read-only
• Access: requires the OFFER_READ permission

omumu_offer_grant_access

Grants a user access to all products in an offer WITHOUT requiring payment. This bypasses the normal checkout/payment flow entirely. The user receives the same access as if they had paid: STUDENT role, product access entries, welcome email, and offer-tag execution. An offer containing a SAAS plan can only be granted by Omumu. The user must already exist on the same site as the offer.

• Write category: standard write
• Access: requires the OFFER_WRITE permission

omumu_offer_list

Lists all offers for the current site with their status (not_published/scheduled/live/paused/ended, with pausedReason when paused), products, and pricing

• Write category: read-only
• Access: requires the OFFER_READ permission

No parameters.

omumu_offer_remove_bump

Removes a bump offer from an existing offer.

• Write category: standard write
• Access: requires the OFFER_WRITE permission

omumu_offer_update

Updates an offer’s title, tagline, buttonText, price, payment providers, or validity dates. Only provided fields are updated; others are preserved. Setting validFrom to now or a past time publishes the offer. status is ‘live’ only when checkout takes orders; otherwise ‘paused’ with pausedReason. A payment provider the site hasn’t connected is refused (Invoice always works). Setting validFrom while the sales page still holds unrewritten placeholders fails, listing each one with where to fix it — rewrite the page with omumu_page_update, then retry.

• Write category: standard write
• Access: requires the OFFER_WRITE permission

Pages & Sales Pages

omumu_page_create

Creates a new page. The page is live on the public site immediately — there is no draft step — and the result’s publicUrl is the address it is served at. Two modes:

Slot page (recommended for sales pages): Pass ‘template’ (discriminator from omumu_template_list) and ‘slotJson’ (whole-document slot JSON validated against that template). For SALES templates, also pass ‘offerId’. Wiring fields (offerId, purpose) must be tool parameters — never inside slot contents.

Classic page: Pass ‘contents’ with optional ‘encoding’ (QUILL_JSON or MANAGED_HTML). MANAGED_HTML is available but de-emphasised for selling pages — prefer slot pages instead.

• Write category: standard write
• Access: requires the PAGE_WRITE permission

omumu_page_delete

Deletes a page by ID

• Write category: standard write
• Access: requires the PAGE_DELETE permission

omumu_page_get

Gets a page by ID or slug. At least one of pageId or slug must be provided. The result’s ‘public’ field is false for a sales page whose offer is not published (visitors get a 404 there until it is), true otherwise.

• Write category: read-only
• Access: requires the PAGE_READ permission

omumu_page_list

Lists all pages for the current site, optionally filtered by type

• Write category: read-only
• Access: requires the PAGE_READ permission

omumu_page_update

Updates a page. The change is live on the public site immediately — there is no draft step — and the result’s publicUrl is the address the page is served at. For slot pages (encoding SLOT_JSON), pass ‘slotJson’ with the full updated slot document — wiring (offerId, purpose) is immutable on update and is not re-validated here. For classic pages, pass any combination of ‘title’, ‘tagline’, ‘metaDescription’, ‘contents’, ‘image’, or ‘slug’.

• Write category: standard write
• Access: requires the PAGE_WRITE permission

omumu_template_list

Returns all registered page templates with their section layouts and per-section JSON schema. Call this tool first when building a slot page so you know which template discriminator to pass to omumu_page_create and what slot fields each section expects. Each entry includes: ‘name’ (the discriminator), ‘purpose’ (e.g. SALES), ‘sections’, and ‘schema’.

• Write category: read-only
• Access: requires the PAGE_READ permission

No parameters.

Audience & Email

omumu_email_followup_update

Updates a follow-up message in an email sequence. All fields except followUpId are optional.

• Write category: standard write
• Access: requires the EMAIL_SEQUENCE_WRITE permission

omumu_email_inbox_get

Retrieves full details of a specific email including headers, body content (text and/or HTML), attachments, and metadata. Use omumu_email_inbox_list first to find email IDs.

• Write category: read-only
• Access: requires the EMAIL_INBOX_READ permission

omumu_email_inbox_list

Lists received emails in the inbox with optional filtering by status or search query. Returns email summaries (id, sender, subject, status, date) with pagination. Also returns unread count for quick monitoring.

• Write category: read-only
• Access: requires the EMAIL_INBOX_READ permission

omumu_email_sequence_create

Creates a new email sequence with an initial email and optional follow-up messages. Content can be Markdown or QuillDelta JSON (auto-detected). After creating, link it to an opt-in form via omumu_optinform_update(emailSequenceId) to trigger the sequence when users submit the form. To send a single one-off email to a contact from an automation, create a sequence containing just one message with initialDelay PT0S and start it with the automation’s start_sequence action. Subject and content may use $first_name (the recipient’s first name) and $quiz_result_link (the recipient’s newest quiz result page on this site, for a sequence a quiz’s result bucket starts); a variable that cannot be resolved renders as nothing.

• Write category: standard write
• Access: requires the EMAIL_SEQUENCE_WRITE permission

omumu_email_sequence_get

Retrieves a specific email sequence with all follow-up messages, plus memberCount, sentCount and heldCount. heldCount counts emails not delivered because the site has no sequence email service configured yet. No member identities are included.

• Write category: read-only
• Access: requires the EMAIL_SEQUENCE_READ permission

omumu_email_sequence_list

Lists all email sequences for the current site with their follow-up messages and memberCount (how many people are enrolled). No member identities are included.

• Write category: read-only
• Access: requires the EMAIL_SEQUENCE_READ permission

No parameters.

omumu_email_sequence_update

Updates an existing email sequence’s properties. All fields except sequenceId are optional.

• Write category: standard write
• Access: requires the EMAIL_SEQUENCE_WRITE permission

omumu_invite_get

Gets a single Invite by ID with full config, stage (draft, live, or paused), window state (accepted of quota, next boundary), waitlist size, and placeholders (unrewritten starter prompts still on the invite page or in its delivery, waitlist-welcome, or reopen emails, each with section, field, and excerpt).

• Write category: read-only
• Access: requires the INVITE_READ permission

omumu_invite_launch

Creates a complete Honest Scarcity Invite in one call: a course (or attaches an existing one), three seeded email sequences (delivery, waitlist-welcome, reopen), an opt-in form wired to the course grant and delivery sequence, the Invite itself, the waitlist tag action on the reopen sequence, and the invite page — all wired, but created as a draft: its page answers visitors with a 404 and its form refuses submissions until you take it live. Returns status ‘draft’, the page URL, the slot editor path, and placeholders (unrewritten starter prompts still on the page or in its emails, each with section, field, and excerpt) so you can customize copy with omumu_page_update and omumu_email_sequence_update before going live with omumu_invite_update (active: true); going live is refused while any remain. Cadence values: HOUR, DAY, WEEK, MONTH. openingDayOfWeek required for WEEK cadence (e.g. MONDAY). openingDayOfMonth required for MONTH cadence (1-31). openingTime format: HH:MM (24h); defaults to 09:00. zone: IANA timezone id (e.g. ‘Europe/Oslo’); defaults to Europe/Oslo. seedLanguage: ‘nb’ for Norwegian Bokmål, ‘en’ (or omit) for English.

• Write category: standard write
• Access: requires the INVITE_WRITE permission

omumu_invite_list

Lists all Invites for the current site with their stage (draft, live, or paused), window state (accepted of quota, next boundary), and waitlist size.

• Write category: read-only
• Access: requires the INVITE_READ permission

No parameters.

omumu_invite_update

Updates an Invite’s name, quota, schedule (cadence, opening moment, zone), or active flag. Changing cadence, openingDayOfWeek/openingDayOfMonth, openingTime, or zone recomputes the next window boundary. Raising or lowering quota takes effect immediately in the current window without invalidating existing acceptances. active=true takes a draft or paused Invite live (its page and form start working for visitors), but is refused while the invite page or its delivery, waitlist-welcome, or reopen emails still hold unrewritten placeholders — the error lists each one with where to fix it; rewrite with omumu_page_update and omumu_email_sequence_update, then retry. active=false pauses a live Invite (its page 404s for visitors, its form refuses submissions) and lifts any deletion guards on its form and sequences; deactivating is never refused. Cadence values: HOUR, DAY, WEEK, MONTH. Day-of-week values: MONDAY..SUNDAY. openingTime format: HH:MM (24h). zone: IANA timezone id (e.g. ‘Europe/Oslo’).

• Write category: standard write
• Access: requires the INVITE_WRITE permission

omumu_optinform_add_field

Adds a new field to collect user information

• Write category: standard write
• Access: requires the OPTINFORM_WRITE permission

omumu_optinform_create

Creates a new opt-in form for collecting leads. The form comes with default email and name fields. After creating, use omumu_optinform_update to connect it to an email sequence (emailSequenceId) and/or course (courseId). Embed on a page with [optin-form id=“FORM_ID”] on its own line (Markdown, Quill or HTML pages). For templated (SLOT_JSON) pages set the page’s optinFormId instead. Forms can also be linked to quizzes as pre-quiz or post-quiz email capture.

• Write category: standard write
• Access: requires the OPTINFORM_WRITE permission

omumu_optinform_delete

Deletes an opt-in form and all its submissions

• Write category: standard write
• Access: requires the OPTINFORM_WRITE permission

omumu_optinform_get

Gets an opt-in form by ID with all its fields. Returns descriptionEncoding (PLAIN_TEXT, QUILL_JSON, or MANAGED_HTML) and trustLine if configured.

• Write category: read-only
• Access: requires the OPTINFORM_READ permission

omumu_optinform_link_sequence

Connects an opt-in form to an email sequence so submissions trigger subscription

• Write category: standard write
• Access: requires the OPTINFORM_WRITE permission

omumu_optinform_list

Lists all opt-in forms for the current site

• Write category: read-only
• Access: requires the OPTINFORM_READ permission

No parameters.

omumu_optinform_remove_field

Removes a field from a form by its field ID

• Write category: standard write
• Access: requires the OPTINFORM_WRITE permission

omumu_optinform_submissions_list

Lists submissions for an opt-in form, newest first. Each entry contains the submission ID, timestamp, and the full submitted data (all field values). Returns respondent personal data, so it requires the dedicated leads:read scope (not granted by optinform:read).

• Write category: read-only
• Access: requires the LEADS_READ permission

omumu_optinform_update

Updates an opt-in form’s properties. Use this to connect the form to a course and email sequence, configure the submit button, and set up redirect behavior. Typical funnel setup: create sequence -> create form -> update form with emailSequenceId + courseId + redirectUrl -> embed in page.

• Write category: standard write
• Access: requires the OPTINFORM_WRITE permission

Automations

omumu_automation_activate

Activates or deactivates an automation. Active automations will trigger when their conditions are met. Before activating, run automation_simulate for each contact journey that matters and resolve any timing-trap warnings from the save/activate response — activation is the last step of the authoring loop (save, check warnings, simulate, activate).

• Write category: standard write
• Access: requires the AUTOMATION_WRITE permission

omumu_automation_create

Creates a new automation (inactive by default). Recommended authoring loop: 1) automation_save the nodes and connections, 2) read any timing-trap warnings in the save response, 3) automation_simulate the contact journeys that matter (especially ‘contact does X, then Y during a delay’), 4) only then automation_activate.

• Write category: standard write
• Access: requires the AUTOMATION_WRITE permission

omumu_automation_generate_ids

Generates unique IDs for use when creating new nodes and connections in canvas state

• Write category: standard write
• Access: requires the AUTOMATION_WRITE permission

omumu_automation_get

Gets an automation with its full canvas state (nodes, connections, configs). Use this to inspect or modify an existing automation.

• Write category: read-only
• Access: requires the AUTOMATION_READ permission

omumu_automation_list

Lists all automations for the current site with their status

• Write category: read-only
• Access: requires the AUTOMATION_READ permission

No parameters.

omumu_automation_options

Returns all available sequences, courses (with lessons), tags, forms, offers, quizzes, staff recipients, and supported node types. Use this to find valid IDs when building automation configs. Each supported node type carries a settings array describing its config keys: key, required, type, allowed values (when enumerated), and refersTo (which list above an id-valued key must be found in, e.g. “sequences” or “courses[].modules”). quizzes lists the site’s quizzes (id + name) for the quiz_completed trigger. staffRecipients lists who may receive notify_site_staff emails (name + email); defaultRecipient is the authoring user’s email. send_webhook’s settings document its url (https, public address, re-checked at send time) and optional secret (signs the body with X-Omumu-Signature: sha256=); see omumu_automation_save’s description for the posted JSON shape. There is no send_email node: to send a single email to a contact, create an email sequence containing one message with zero initial delay and start it with the start_sequence action.

• Write category: read-only
• Access: requires the AUTOMATION_READ permission

No parameters.

omumu_automation_save

Saves the full canvas state (nodes + connections) for an automation. Saving takes effect immediately, including on an already-active automation — there is no need to deactivate first. Canvas state format: {“nodes”: [{“id”: “…”, “type”: “tag_applied”, “x”: 0, “y”: 0, “config”: {…}}], “connections”: [{“id”: “…”, “from”: “nodeId”, “to”: “nodeId”, “type”: “default”}]}. Use automation_generate_ids to get IDs for new nodes/connections. Use automation_options to get valid IDs for sequences, courses, tags, forms, offers, quizzes, staff recipients — and, for every node type, its settings (config keys, required or optional, allowed values, and what catalog list an id refers to). Completion triggers (module_completed, course_completed) are side-effects only (celebrate, tag, follow up) — on a SEQUENTIAL course the next module unlocks by itself, so do not wire module_completed to unlock_module for gating. Pair submission_received with unlock_module to open the next module when a student posts their work. Pair quiz_completed (or form_submit) with notify_site_staff to email a staff member a digest of every answer, the bucket, and the score. send_webhook posts the run data as JSON to a creator-controlled URL ({“event”, “siteId”, “occurredAt”, “runId”, “contact”: {“userId”,“email”,“firstName”,“lastName”,“phone”} when identified, “input”: the trigger’s run input, and for a quiz-triggered run “quiz”: {“quizId”,“label”,“bucketName”,“totalPercent”,“scalePercents”,“doorName”,“resultUrl”,“answers”:[{“question”,“answers”|“text”}]}}); config url must be https and resolve to a public address (checked again at send time), config secret is optional and signs the body as header X-Omumu-Signature: sha256=; a non-2xx response, a timeout or a refused connection is recorded as a FAILED step and the automation continues. There is no send_email node: to send a single email to a contact, create an email sequence containing one message with zero initial delay (omumu_email_sequence_create, initialDelay PT0S) and start it with the start_sequence action. The response includes timing-trap warnings (e.g. stop-sequence-before-delayed-start: a STOP_SEQUENCE may fire before a WAIT-delayed START_SEQUENCE and silently no-op; fix by starting the sequence immediately and moving the delay into the sequence’s initialDelay). Warnings are non-blocking, but do not activate past one without first proving the funnel correct with automation_simulate.

• Write category: standard write
• Access: requires the AUTOMATION_WRITE permission

omumu_automation_simulate

Runs a scenario against the site’s automations in memory (no emails sent, nothing written) and returns the effect timeline plus any timing-trap warnings. All of the site’s automations run together so cross-flow races (e.g. a purchase stopping a delayed abandonment sequence) are visible. ‘events’ is an array of {“at”: duration, “trigger”: triggerType, “contact”: alias}: ‘at’ is a duration from t0 as ISO-8601 (PT5M) or a friendly form (0s, 5m, 1h, 2d, 1w); ‘trigger’ is a contact trigger type (form_submit, purchase, tag_applied, page_visit); ‘contact’ is an optional alias (default ‘contact’) so several events can describe one contact’s journey. Each timeline entry is {atSeconds, at, contact, kind, target, effective}: kind is APPLY_TAG, REMOVE_TAG, START_SEQUENCE, STOP_SEQUENCE, EMAIL_SENT, ENROLL_COURSE, UNLOCK_MODULE, GRANT_ROLE or NODE_REJECTED; ‘effective’ is false for a no-op (e.g. a stop with no live subscription). Use this to verify a funnel behaves before activating it: don’t just look for the expected effects — scan the timeline for effective=false on stops/removals and for EMAIL_SENT entries the contact should NOT receive (an ineffective STOP_SEQUENCE followed by a later EMAIL_SENT is the classic cart-abandonment race). Simulating is step 3 of the authoring loop: save, check warnings, simulate the journeys that matter, then activate.

• Write category: read-only
• Access: requires the AUTOMATION_READ permission

Podcasting

omumu_podcast_episode_create

Creates a draft episode on the site’s show from an already-uploaded audio resource (upload the file first with omumu_resource_upload_presign; mp3, m4a, and wav are accepted). Mastering starts automatically and the episode is returned in PROCESSING status; publish it right away and it goes live when mastering ends, or poll omumu_podcast_episode_get until it reaches READY, then publish. With deferMastering the episode is returned UNMASTERED and nothing is mastered yet: start mastering with omumu_podcast_episode_master, or publish it and it is mastered first, then goes live.

• Write category: standard write
• Access: requires the PODCAST_WRITE permission

omumu_podcast_episode_get

Gets one episode by id with its processing status (UNMASTERED, PROCESSING, READY, FAILED, PUBLISHED, SPLITTING while being split into other episodes, SPLIT once it has been), duration, error message when failed, pubDate when published, the latest re-master’s status (NONE, PENDING, FAILED) with its error when failed, masteringMethod: what made the current master (auphonic, omumu_chain, or null when not mastered yet or mastered by an older Omumu chain), masteringFallback: why Auphonic could not master it when Omumu’s chain made it instead (out_of_credits, key_rejected, production_failed, unreachable, timed_out), null when it did not fall back, noiseReduction: whether the episode is mastered with noise reduction, and publishIntent: whether it publishes itself when mastering ends.

• Write category: read-only
• Access: requires the PODCAST_READ permission

omumu_podcast_episode_list

Lists the show’s episodes with their processing status (UNMASTERED, PROCESSING, READY, FAILED, PUBLISHED, SPLITTING while being split into other episodes, SPLIT once it has been), duration, error message when failed, pubDate when published, the latest re-master’s status (NONE, PENDING, FAILED) with its error when failed, masteringMethod: what made the current master (auphonic for the site’s connected Auphonic account, omumu_chain for Omumu’s own chain, null when not mastered yet or mastered by an older Omumu chain), masteringFallback: why Auphonic could not master it when Omumu’s chain made it instead (out_of_credits, key_rejected, production_failed, unreachable, timed_out), null when it did not fall back, noiseReduction: whether the episode is mastered with noise reduction, and publishIntent: whether it publishes itself when mastering ends. The source of a split is listed too; it cannot be edited, published or re-mastered, and its parts are the episodes now.

• Write category: read-only
• Access: requires the PODCAST_READ permission

No parameters.

omumu_podcast_episode_master

Starts mastering an UNMASTERED episode (one created with deferMastering), returning it in PROCESSING status; it reaches READY when mastering ends. Episodes in any other status are refused with their current status: their mastering has already started.

• Write category: standard write
• Access: requires the PODCAST_WRITE permission

omumu_podcast_episode_publish

Publishes a READY episode: the pubDate is stamped now and the episode appears in the RSS feed. A PROCESSING episode records a publish intent instead and is returned unpublished with publishIntent true: it publishes itself when mastering ends, with the pubDate stamped then, and the intent survives a failed mastering and its retry. An UNMASTERED episode starts mastering with a publish intent the same way, so it goes live mastered. Cancel it with omumu_podcast_episode_publish_cancel until then. A FAILED episode is refused with its status.

• Write category: standard write
• Access: requires the PODCAST_WRITE permission

omumu_podcast_episode_publish_cancel

Cancels the publish intent of an episode that is still being mastered, or whose mastering failed: it stays a draft when mastering ends. Refused once the episode is published.

• Write category: standard write
• Access: requires the PODCAST_WRITE permission

omumu_podcast_episode_remaster

Re-masters an episode’s original upload with the current mastering chain. A READY episode returns to PROCESSING. A PUBLISHED episode stays in the feed with its current audio while remasterStatus is PENDING; when the new master lands it replaces the audio and a fresh transcription run starts, and a failure sets remasterStatus FAILED with remasterError and leaves the published audio unchanged. Refused, with the reason, for episodes with applied transcript edits, UNMASTERED, PROCESSING or FAILED episodes, episodes with a re-master already pending, the source of a split (SPLITTING or SPLIT), and the parts of a split.

• Write category: standard write
• Access: requires the PODCAST_WRITE permission

omumu_podcast_episode_retry

Re-runs mastering on a FAILED episode, returning it to PROCESSING. Episodes in any other status are refused with their current status.

• Write category: standard write
• Access: requires the PODCAST_WRITE permission

omumu_podcast_show_get

Gets the site’s podcast show: title, slug, description, language, and the public RSS feed URL. Errors if the site has no show yet (shows are created in the podcast admin).

• Write category: read-only
• Access: requires the PODCAST_READ permission

No parameters.

The Agent Surface

omumu_profile_get

Tells the host who this connection belongs to, so several connected Omumu sites read as separate accounts. Returns your user id on this site (stable, and different on each site), your name, your email and a nickname naming you and the site.

• Write category: read-only
• Access: all agents

No parameters.

omumu_site_context

Tells you which Omumu site this connection acts on. Call it first. Returns the site’s canonical host and public URL, its site id, your role on the site (PLATFORM_ADMIN, HEADMASTER, STAFF, STUDENT, or null when you hold none), the site’s enabled features, and highLevelConnected: whether a Headmaster has connected the site to HighLevel, which a quiz needs before it can deliver its respondents there (it is connected in the admin; no tool reads or writes it). Needs no scope and returns no personal data and no credential.

• Write category: read-only
• Access: all agents

No parameters.

omumu_submission_get

Reads one hand-in: everything its list row carries, plus the assignment’s id and title, the participant’s text, the handed-in file’s name, type and size, the file’s text in file.text when it is a .txt or .md file of at most 1 MB, the transcript of an audio or video file when there is one (its status otherwise), the link to the hand-in’s page, and every feedback row oldest first: its kind (AI_RATING or HUMAN_REVIEW), body, optional score, createdAt, and the author’s name for a staff review. Never includes mentor notes, the rater’s reading trace or a file download link. Requires the handin:read scope. Reading changes nothing, and marks nothing as seen.

• Write category: read-only
• Access: requires the HANDIN_READ permission

omumu_submission_list

Lists the hand-ins (submissions) on an assignment, oldest first by when they were handed in. Pass since to get only those handed in at or after a time: a daily poll passes the submittedAt of the last hand-in it saw and skips the ids it already has. Each row carries the submission id, the participant (userId, name, email), submittedAt, the light (GREEN, YELLOW or RED on a Check-in, null otherwise), the mentor’s reviewState, the transcriptStatus, and hasAiFeedback and hasStaffFeedback. Paginate with limit and offset; totalCount counts every match. Use omumu_submission_get to read one. Returns participants’ personal data, so it requires the dedicated handin:read scope. Reading changes nothing.

• Write category: read-only
• Access: requires the HANDIN_READ permission

Product Skills

omumu_skill_get

Returns the complete SKILL.md instructions for a skill the user is entitled to. Use after omumu_skills_list to load the workflow and follow its steps. Returns an error if the user is not entitled or the skill is not published.

• Write category: read-only
• Access: requires the SKILL_READ permission

omumu_skills_list

Lists every published Omumu skill (workflow for AI assistants) visible to the caller’s site, marking which the user is entitled to read. Use to discover what workflows are available — course creation, validation, sales pages, etc. Set entitledOnly=true to hide skills the user is not entitled to.

• Write category: read-only
• Access: requires the SKILL_READ permission

Permission scopes