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 the scope guarding your buyers’ personal data — leads:read, which unlocks names and emails from your opt-in forms — is never granted by default: a client must ask for it by name, and you must see it on the consent screen before it’s live. That last 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, and which features the site has — 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 Admin → 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 the defaults are the safe ones from Concepts: no buyer PII, 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: Admin → 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.

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: Admin → 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 Admin → Courses and Admin → 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 and roundness steps 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. To enable scoring, link this answer to one or more buckets using omumu_option_point_create after creating the answer.

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

omumu_answer_update

Updates an answer option’s label or value

• 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, or a lesson. Provide exactly one of courseId, moduleId, or lessonId — omitting all or providing more than one is rejected. 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, or LESSON) and the scope’s id stated explicitly. Requires the MCP_COURSES feature (Starter tier or above).

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

omumu_assignment_update

Updates an existing assignment’s title, description, ratingPrompt, status, and/or scope. Provide exactly one of courseId, moduleId, or lessonId to set the new scope. The new scope must belong to the same course as the assignment. 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 (outcome category) for the quiz. Users are sorted into the bucket with the highest score based on their answers. After creating buckets, link answers to them using omumu_option_point_create. Each bucket can trigger actions: send email sequence, grant course access, redirect to URL.

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

omumu_bucket_update

Updates a bucket’s properties including actions (email sequence, course, redirect)

• 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_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_option_point_batch

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

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.

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

omumu_option_point_delete

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

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

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.

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

omumu_question_update

Updates a question’s header or type

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

omumu_quiz_create

Creates a new quiz (question set) for lead generation or segmentation. 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. After creating a 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.

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

omumu_quiz_get

Gets a quiz with optional questions and result buckets. Returns preQuizOptinFormId and postQuizOptinFormId if linked opt-in forms are configured for email capture. To see the complete quiz scoring configuration, set includeQuestions=true, includeBuckets=true, and includeOptionPoints=true. Option points link answers to buckets with weights - the bucket with the highest total weight from selected answers wins.

• 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 and linked opt-in forms for email capture. 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.

• 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_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). 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_get

Gets an offer by ID with full details including checkout URL, status (with pausedReason when paused), products, pricing, and payment providers

• 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).

• 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.

• 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.

• 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.

• 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.

• 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, live window state (accepted of quota, next boundary), and waitlist size.

• 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 a live invite page — all wired and ready to publish. Returns the public page URL and the slot editor path so you can customize copy immediately. 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 live 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. Deactivating the Invite (active=false) lifts any deletion guards on its form and sequences. 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. 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. 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

Ad Validation & Offer DNA

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

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; poll omumu_podcast_episode_get until it reaches READY, then publish.

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

omumu_podcast_episode_get

Gets one episode by id with its processing status, duration, error message when failed, and pubDate when published.

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

omumu_podcast_episode_list

Lists the show’s episodes with their processing status (PROCESSING, READY, FAILED, PUBLISHED), duration, error message when failed, and pubDate when published.

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

No parameters.

omumu_podcast_episode_publish

Publishes a READY episode: the pubDate is stamped now and the episode appears in the RSS feed. A PROCESSING or FAILED episode is refused with its current status.

• 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) and the site’s enabled features. Needs no scope and returns no personal data.

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

No parameters.

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