Valuverse Docs

Appearance

On this page

Intents Reference ​

Auto-generated from application and service manifests.
Generated on: 2026-10-29

Table of Contents ​

Applications ​

Services ​

Application Intents ​

Auth (auth) ​

User login flow

logout ​

Logout from system

Availability: Developer

No parameters.

Calendar (events) ​

open-calendar ​

Opens the calendar view, optionally filtered by a specific source type (all, room, group, user, or community event).

Availability: AI, Developer

ParameterTypeRequiredDescription
sourcestringYesThe source type for the calendar filter. Must be one of: all, room, group, user, community. Use "all" to show meetings from every source type.
idstringNoThe unique identifier of the room, group, or user.
fullNamestringNoThe display name of the room, group, or user.
communityIdstringNoThe unique identifier of the community (used when source is community).
communityFullNamestringNoThe display name of the community.
eventIdstringNoThe unique identifier of the community event.
eventFullNamestringNoThe display name of the community event.

Calls (videochat) ​

connect-to-meeting ​

Connects to a specific meeting by room, prop, group, or user and manages video chat and presentation settings.

Availability: AI, Developer

ParameterTypeRequiredDescription
roomIdstringNoThe unique identifier of the room to connect to.
propIdstringNoThe unique identifier of the prop to connect to.
groupIdstringNoThe unique identifier of the group to connect to.
userIdstringNoThe unique identifier of the user to connect to.
withLocalTracksbooleanNoIf true, view shared screens or presenter content without joining the video chat.
autoConnectToVideochatbooleanNoIf true, automatically join the video chat after connecting.

leave-meeting ​

Leaves the current call only when it is the given prop's call (roomId + propId); otherwise does nothing. Returns {left: boolean}. Used by Metaverse 2D video chat zones.

Availability: Developer

ParameterTypeRequiredDescription
roomIdstringYesThe room of the prop whose call to leave.
propIdstringYesThe prop whose call to leave; any other call is left as it is.

open-source-picker ​

Opens the "Open Videochat from" source picker (Rooms, Groups, Contacts, Textchats) as the inline full-view list. Selecting an item starts a video chat with that source.

Availability: AI, Developer

ParameterTypeRequiredDescription
standalonebooleanNoIf true, render the picker as a standalone window with no back button (e.g. when launched from the native app, where there is no video chat to return to).

Chats (textchat) ​

open-channel ​

Opens a text chat session based on channel, user, group, room, or prop.

Availability: AI, Developer

ParameterTypeRequiredDescription
channelIdstringNoThe unique identifier of the text channel to open.
userIdstringNoThe unique identifier of the user for a direct chat.
groupIdstringNoThe unique identifier of the group to open a group chat.
roomIdstringNoThe unique identifier of the room to open a room chat.
propIdstringNoThe unique identifier of the prop to open a prop-specific chat.

close-channel ​

Closes the currently open channel and returns to the channel list. Mirrors the toolbar back button used on mobile/narrow layouts.

Availability: AI, Developer

No parameters.

share-card ​

Shares one or more entities into a chat as rich, interactive cards — Rooms, Groups, Communities, Meetings, or Contacts — instead of plain links. Pass "id" for a single card or "ids" for several in one message. All cards in one call must be the SAME cardType (mixed types need separate calls). Posts into the currently open channel by default; pass channelId to target a specific channel.

Availability: AI, Developer

ParameterTypeRequiredDescription
cardTypestringYesThe entity type to share: "room", "group", "community", "meeting", or "contact". Applies to every id in this call.
idstringNoA single entity id to share (room/group/community id, user id for a contact, or — for meetings — the occurrence id from list-events; a one-off meeting id also works). Use this OR "ids".
idsstring[]NoSeveral entity ids to share as multiple cards in one message — all of the given cardType (for meetings, occurrence ids from list-events). Use this OR "id".
channelIdstringNoTarget channel id. Defaults to the currently active channel.
networkIdstringNoThe network the entities belong to. Defaults to the active network.

get-ui-state ​

Read-only. Returns a snapshot of what the chat is currently showing — the channels list, an open channel, or both side by side (wide layout) — plus the in-app back action. Lets non-web clients (e.g. the Android device back button) mirror the toolbar back-button navigation. Changes nothing. Returns { view: "list" | "channel" | "list-and-channel", isWide, activeChannelId, openThreadId, threadTakeover, canNavigateBack, backAction: "close-thread" | "close-channel" | null }.

Availability: AI, Developer

No parameters.

options ​

Sets the text‑chat view layout (e.g. wide or narrow mode).

Availability: Developer

ParameterTypeRequiredDescription
isWidebooleanYesWhether to enable wide‑mode layout in the chat view.

open-room-ai-chat ​

Opens an AI‑powered chat session scoped to a specific room.

Availability: Developer

ParameterTypeRequiredDescription
roomIdstringYesThe unique identifier of the room in which to start the AI chat.

send-message ​

Sends a rich text message to a text-chat channel on behalf of an initiator (e.g. an AI agent or automated service). Silent — does NOT open or change the visible chat. Use channelId when you know it; otherwise provide userId for a direct message.

Availability: Developer

ParameterTypeRequiredDescription
textstringYesThe message body to send.
channelIdstringNoTarget channel ID. Takes precedence over userId.
userIdstringNoTarget user ID for a direct message. Ignored if channelId is provided.
buttonsobject[]NoOptional interactive buttons to attach to the message as a rich card.

Contacts (contacts) ​

Manage and chat with your personal connections.

show-user-connections ​

Open the connections view for the specified user

Availability: AI, Developer

ParameterTypeRequiredDescription
userIdstringYesThe unique identifier of the user to display

Content Studio (content-studio) ​

open-create ​

Open the content upload page with an optional upload destination

Availability: none (platform-internal)

ParameterTypeRequiredDescription
roomIdstringNoID of the room to upload to
communityIdstringNoID of the community to upload to
channelIdstringNoID of the channel to upload to
groupIdstringNoID of the group to upload to
labelstringNoLabel to apply to the content
departmentstringNoDepartment associated with the content
themestringNoTheme to apply to the upload page

open-edit ​

Open the edit page for a specific content item

Availability: none (platform-internal)

ParameterTypeRequiredDescription
contentItemIdstringYesID of the content item to edit
roomIdstringNoID of the room context
communityIdstringNoID of the community context
channelIdstringNoID of the channel context
groupIdstringNoID of the group context
labelstringNoLabel to apply to the content
departmentstringNoDepartment associated with the content
themestringNoTheme to apply to the edit page

Open the search page

Availability: none (platform-internal)

No parameters.

Navigate to a specific route within Content Studio

Availability: none (platform-internal)

ParameterTypeRequiredDescription
routestringYesThe route path to navigate to within Content Studio

Content Studio (staging-content-studio) ​

open-create ​

Open the content upload page with an optional upload destination

Availability: none (platform-internal)

ParameterTypeRequiredDescription
roomIdstringNoID of the room to upload to
communityIdstringNoID of the community to upload to
channelIdstringNoID of the channel to upload to
groupIdstringNoID of the group to upload to
labelstringNoLabel to apply to the content
departmentstringNoDepartment associated with the content
themestringNoTheme to apply to the upload page

open-edit ​

Open the edit page for a specific content item

Availability: none (platform-internal)

ParameterTypeRequiredDescription
contentItemIdstringYesID of the content item to edit
roomIdstringNoID of the room context
communityIdstringNoID of the community context
channelIdstringNoID of the channel context
groupIdstringNoID of the group context
labelstringNoLabel to apply to the content
departmentstringNoDepartment associated with the content
themestringNoTheme to apply to the edit page

open-search ​

Open the search page

Availability: none (platform-internal)

No parameters.

Navigate to a specific route within Content Studio

Availability: none (platform-internal)

ParameterTypeRequiredDescription
routestringYesThe route path to navigate to within Content Studio

Groups (groups) ​

open ​

Opens the groups view and navigates to a specific group.

Availability: Developer

ParameterTypeRequiredDescription
groupIdstringYesThe unique identifier of the group to open.

LLM Debug (iframe_llm_debug) ​

Live LLM / agent activity debug panel (your own agents)

open-session ​

Opens the LLM Debug panel and navigates to a specific debug session (chat, agent, or sub-agent) by its session ID.

Availability: Developer

ParameterTypeRequiredDescription
sessionIdstringYesThe LLM debug session ID to open.

open-agent ​

Opens the LLM Debug panel and navigates to a specific agent's page by its agent ID (its persistent session). Pass sessionId to target one of the agent's runs instead.

Availability: Developer

ParameterTypeRequiredDescription
agentIdstringYesThe agent ID (its persistent agent session ID) to open.
sessionIdstringNoA specific session of the agent to open instead of its main page.

open-run ​

Opens the LLM Debug panel on a specific agent/chatbot RUN by its run id. Pass the entity kind + id and the run id from the originating message.

Availability: Developer

ParameterTypeRequiredDescription
entityKindstringYesThe entity kind: "agent" or "chatbot".
entityIdstringYesThe agent or chatbot id the run belongs to.
runIdstringYesThe run id (agentRunId/chatbotRunId) to open.

Media (cms) ​

Content management module

show-chat-channel ​

Open and display the specified chat channel

Availability: AI, Developer

ParameterTypeRequiredDescription
channelIdstringYesThe unique identifier of the chat channel to display

show-folder ​

Navigate to and open a specific folder in the CMS by its folder ID

Availability: AI, Developer

ParameterTypeRequiredDescription
folderIdstringYesThe unique identifier of the folder to open
resourceIdstringNoA resource inside that folder to open in the Edit side panel after navigating.

show-resource ​

Reveal a resource in the CMS file browser by its resource ID — navigates to the folder holding it (or to its section root when it is not in a folder), selects it and opens its Edit side panel. Use this when you only have a resource id and want to show the user where that file lives; use preview-resource instead to just view its contents.

Availability: AI, Developer

ParameterTypeRequiredDescription
resourceIdstringYesThe unique identifier of the resource to reveal

preview-resource ​

Open a resource (file) in the CMS preview viewer by its resource ID

Availability: AI, Developer

ParameterTypeRequiredDescription
resourceIdstringYesThe unique identifier of the resource to preview

show-my-files ​

Navigate to the user's own files in the CMS (the "My Files" / "My Content" view). Use this when the user asks about their files, uploads, or personal content — do not use show-folder for this.

Availability: AI, Developer

No parameters.

show-application-storage ​

Open an application's storage folder in the CMS — the files that app has stored under the current user, shown at Applications › <app>. Provide the application id (e.g. "valuguru"). The app must declare storage: true in its manifest.

Availability: AI, Developer

ParameterTypeRequiredDescription
applicationIdstringYesThe id of the application whose storage folder to open (e.g. "valuguru").
resourceIdstringNoA resource inside that storage folder to open in the Edit side panel after navigating.

show-community-channel ​

Open and display the specified community channel

Availability: Developer

ParameterTypeRequiredDescription
communityIdstringYesThe unique identifier of the community
communityChannelIdstringYesThe unique identifier of the channel within the community

Merchant Console (merchant) ​

Sell in Valu: list products and bundles, choose where they sell, and moderate a network's commerce

open-section ​

Open the Merchant Console on one of its tabs. The tab becomes part of the address, so the place it opens on can be linked to and comes back on a reload. Home is the setup checklist until the store can sell, then the overview. Promotions, Analytics and Store need a store; Moderation is for network admins. Bundles opens Products filtered to bundles; the old names overview and api-access still work (Home, Store).

Availability: AI, Developer

ParameterTypeRequiredDescription
sectionstringYesWhich tab to open: home, products, bundles, promotions, analytics, store or moderation.
popupbooleanNotrue draws the product list over the pane of the app that asked instead of docking the console, so the app the seller came from stays visible behind it. Products is the only tab with a popup form; any other section docks the console as usual. Where the caller is not on screen the popup falls back to a window over the whole page.

open-products ​

Open the seller's product list. With popup it is drawn over the calling app instead of docking the console.

Availability: AI, Developer

ParameterTypeRequiredDescription
popupbooleanNotrue draws the product list over the pane of the app that asked instead of docking the console, so the app the seller came from stays visible behind it. Products is the only tab with a popup form; any other section docks the console as usual. Where the caller is not on screen the popup falls back to a window over the whole page.

open-product ​

Open one of the seller's own products for editing.

Availability: AI, Developer

ParameterTypeRequiredDescription
productIdstringYesthe product to open

open-moderation ​

Open the moderation tab for the current network: who may sell here, what content is allowed, and the sellers waiting for a decision. Network admins only.

Availability: Developer

No parameters.

Metaverse (metaverse) ​

set-route ​

initiate the opening of the Metaverse 3d application with spsific route

Availability: AI, Developer

ParameterTypeRequiredDescription
routestringYesThe route to set. Defines the current view or action in the application. If not provided, the default application state will open.

open-room ​

Open a specific room in the ValuVerse 3D environment. Both networkId and roomId are required. Use the networkId provided in context.

Availability: AI, Developer

ParameterTypeRequiredDescription
networkIdstringYesThe network the room belongs to. Use the networkId from context.
roomIdstringYesThe ID of the room to open.

preview-prop ​

Navigate the camera to a specific prop in a room, opening the Metaverse view. networkId, roomId, and propId are all required. Only call this when the user explicitly asks to show, open, navigate to, or view a prop. Do not call this automatically when listing or describing props.

Availability: AI, Developer

ParameterTypeRequiredDescription
networkIdstringYesThe network the room belongs to. Use the networkId from context.
roomIdstringYesThe ID of the room containing the prop.
propIdstringYesThe ID of the prop to navigate to.

Metaverse 2D (hubs) ​

See who is in a room hub, join or switch hubs, and create a private hub

open ​

Opens the Metaverse 2D app (the 2D room maps and their hubs), optionally preselecting a room. Joining a hub stays a user action.

Availability: AI, Developer

ParameterTypeRequiredDescription
roomIdstringNoRoom to preselect in the room picker.

enter-room ​

Opens the Metaverse 2D app on a room and joins that room's public hub, as picking the room there does (Rooms → Room Info → Go in 2D, the user card → Go in 2D).

Availability: Developer

ParameterTypeRequiredDescription
roomIdstringYesThe room to enter. Metaverse 2D checks that the user may join it.
hubIdstringNoA hub of that room to switch to once its public hub is joined, when it is still there and has room (the user card's location).

agent-enter-room ​

Brings your agent into a room's hub as its own character: you enter that room in Metaverse 2D (its public hub, or your group's hub in group mode) and the agent appears a metre beside you. Needs the same join rights as you. Use find-people first to choose a room.

Availability: AI

ParameterTypeRequiredDescription
roomIdstringYesThe room to enter.

agent-people ​

Lists who is in the hub with the agent: userId, name, whether they are your friend or connection, whether they are in 3D, and how many metres they are from the agent. Includes you (isYou).

Availability: AI

No parameters.

agent-walk-to ​

Walks the agent on the room's 2D map, around walls and props: to a person (stopping 1.5 m short, by userId from agent-people) or to a point (x, z in metres). Returns at once with the distance and seconds the walk takes; check agent-status.

Availability: AI

ParameterTypeRequiredDescription
userIdstringNoWalk to this person (from agent-people).
xnumberNoOr walk to this point: x in metres.
znumberNoAnd z in metres.

agent-say ​

The agent says a short text in a speech bubble over its character, seen by everyone on the web map of that hub (not by people in 3D yet). At most 140 characters, at most once a second. It speaks in your name, labelled as your agent: keep it friendly and brief.

Availability: AI

ParameterTypeRequiredDescription
textstringYesWhat to say, up to 140 characters.

agent-status ​

The agent's state in Metaverse 2D: whether it is in a hub, its room and hub, its position, and whether it is still walking.

Availability: AI

No parameters.

agent-leave ​

Takes the agent out of the hub.

Availability: AI

No parameters.

find-people ​

Counts the people in each hub of some rooms in this network (default: the room on the map and its linked rooms, at most 9). Needs you to be in a hub. Use it to choose where the agent goes.

Availability: AI

ParameterTypeRequiredDescription
roomIdsstring[]NoThe rooms to look into.

My Cart (cart) ​

Everything you added in any Valu app, in one cart, paid for with one QR scan

open-section ​

Open My Cart on one of its tabs. The tab becomes part of the address, so the place it opens on can be linked to and comes back on a reload.

Availability: AI, Developer

ParameterTypeRequiredDescription
sectionstringYesWhich tab to open: discover, cart, purchased (what the user owns) or orders (receipts).

open-cart ​

Open the cart. Pass an app id to show only that app's items and check them out on their own, and popup to draw it over the calling app instead of docking My Cart.

Availability: AI, Developer

ParameterTypeRequiredDescription
appIdstringNoshow only the items added from this app
popupbooleanNotrue draws this over the pane of the app that asked instead of docking My Cart, so the app the buyer came from stays visible and usable behind it. Where the caller is not on screen the popup falls back to a window over the whole page.
promoCodestringNoa discount code to type into the cart and apply, as if the buyer had typed it; they see whether it applies and can remove it. Paying is still their own press of Pay.

open-orders ​

Open the order history — every purchase made across Valu apps, with its receipt. With popup it is drawn over the calling app instead of docking My Cart.

Availability: AI, Developer

ParameterTypeRequiredDescription
popupbooleanNotrue draws this over the pane of the app that asked instead of docking My Cart, so the app the buyer came from stays visible and usable behind it. Where the caller is not on screen the popup falls back to a window over the whole page.

open-purchased ​

Open what the user OWNS — every product they bought or got free, with its files, how far through them they are, and their rating. With productId, that product opened and shown. Orders (open-orders) are the receipts only.

Availability: AI, Developer

ParameterTypeRequiredDescription
productIdstringNoa product the user owns, to open and show
popupbooleanNotrue draws this over the pane of the app that asked instead of docking My Cart, so the app the buyer came from stays visible and usable behind it. Where the caller is not on screen the popup falls back to a window over the whole page.

open-order ​

Open one order and show its receipt.

Availability: AI, Developer

ParameterTypeRequiredDescription
orderIdstringYesthe order to show
popupbooleanNotrue draws this over the pane of the app that asked instead of docking My Cart, so the app the buyer came from stays visible and usable behind it. Where the caller is not on screen the popup falls back to a window over the whole page.

open-product ​

Open a product's page — what it is, what it is made of, what makes up its price, and whether this buyer can buy it.

Availability: AI, Developer

ParameterTypeRequiredDescription
productIdstringYesthe product to show

add-to-cart ​

Add a product to the cart and open it. The item is credited to the app that asks — the platform knows which one, so there is no app to name — or to My Cart itself when the asker is not an app. The server re-checks that the product can be bought in this network before accepting it.

Availability: AI, Developer

ParameterTypeRequiredDescription
productIdstringYesthe product to add
qtynumberNohow many, at least 1

Profile (profile) ​

Your user profile

show-current-user ​

Opens the profile view for the currently signed-in user.

Availability: AI, Developer

No parameters.

show-user ​

Shows the profile view for a specific user, or the current user if no userId is provided.

Availability: AI, Developer

ParameterTypeRequiredDescription
userIdstringNoThe unique identifier of the user whose profile to open. Defaults to the current user.

open-profile-with-mode ​

Opens the profile view for a user and optionally navigates to a specific mode such as the marketplace.

Availability: AI, Developer

ParameterTypeRequiredDescription
userIdstringNoThe unique identifier of the user whose profile to open. Defaults to the current user.
offerIdstringNoThe identifier of the marketplace offer to display.

Resources Viewer (preview) ​

preview ​

Opens the resource viewer to preview a specific resource.

Availability: Developer

ParameterTypeRequiredDescription
resourceIdstringYesThe unique identifier of the resource to preview.

Rooms (rooms) ​

View and manage rooms

open ​

Opens the Rooms app on a chosen list. With no parameter the app simply opens on whatever it was last showing.

Availability: AI, Developer

ParameterTypeRequiredDescription
tabstringNoWhich list to show. Defaults to the currently visible one.

show-room ​

Opens the Rooms app on a specific room's detail view — info, members and settings.

Availability: AI, Developer

ParameterTypeRequiredDescription
roomIdstringYesThe unique identifier of the room to show.

invite-to-room ​

Opens the room invitation dialog for a specific room.

Availability: AI, Developer

ParameterTypeRequiredDescription
roomIdstringYesThe unique identifier of the room to invite users to.

Social (community) ​

create-post ​

Open view and open post editor

Availability: Developer

ParameterTypeRequiredDescription
resourceIdstringYesResource id for post attachment
rootChannelobjectYesRoot chanel of community
communityobjectYesCommunity data
pathstringYesFull path to channel or subchannel
titlestringNoPre-fills the post title in the editor. Optional; the editor opens with this title instead of blank.
bodystringNoPre-fills the post body (Markdown) in the editor. Optional; the editor opens with this body instead of blank.

create-channel ​

Opens the community view and starts channel creation in a specific community context.

Availability: Developer

ParameterTypeRequiredDescription
communityobjectYesCommunity data object.
contentDirectoryIdstringNoThe content directory identifier for the new channel.
rootChannelobjectNoRoot channel of the community.
subChannelIdstringNoThe sub-channel identifier to navigate to.
modestringNoThe creation mode for the channel.
contentDirectoryTitlestringNoDisplay title for the content directory.

open-community ​

Opens the community view and navigates to a community by its ID. Use when you only have a communityId and no specific channel to target — the app will land on the first available channel.

Availability: AI, Developer

ParameterTypeRequiredDescription
communityIdstringYesThe community id.

show-channel ​

Opens the community view and navigates to a specific channel. Use communityId from AI context. For a root channel: pass its id as rootChannelId, omit subChannelId. For a sub-channel: the sub-channel object in AI context has a rootChannelId field — pass that as rootChannelId, and the sub-channel id as subChannelId.

Availability: AI, Developer

ParameterTypeRequiredDescription
communityIdstringYesThe community id from AI context.
rootChannelIdstringYesThe top-level root channel id. Never a sub-channel id.
subChannelIdstringNoThe sub-channel id to navigate into. Omit when navigating to the root channel itself.

show-post ​

Opens the community view and navigates to a specific post. Use communityId from AI context. For a post in a root channel: pass the channel id as rootChannelId, omit subChannelId. For a post in a sub-channel: pass the sub-channel's rootChannelId as rootChannelId, and the sub-channel id as subChannelId. Pass the post id as messageId.

Availability: AI, Developer

ParameterTypeRequiredDescription
communityIdstringYesThe community id from AI context.
rootChannelIdstringYesThe top-level root channel id. Never a sub-channel id.
messageIdstringYesThe post id from AI context.
subChannelIdstringNoThe sub-channel id containing the post. Omit when the post is in the root channel itself.

User Card (user-card) ​

Contextual profile card shown when tapping a user avatar

show ​

Shows the contextual profile card for a user.

Availability: Developer

ParameterTypeRequiredDescription
userIdstringYesThe unique identifier of the user whose card to show.
anchorobjectNoViewport rect {left, top, right, bottom, width, height} of the tapped avatar, used to position the card in web. Ignored by native hosts, which anchor the card their own way. Omitted, the card is centred.
hostApplicationIdstringNoThe application the card is opened from, and so the view a native host should present it above (e.g. "textchat"). Absent when the caller could not name one — present over the topmost view in that case.

Valu Games (games) ​

Valu board games

open ​

Open the Valu Games app.

Availability: AI, Developer

No parameters.

Valu Guru (valuguru) ​

open ​

Opens the Valu Guru app on a chat with the built-in Valu Guru assistant, without sending anything. Resumes the most recent built-in-assistant conversation, or lands on the empty new-chat screen when there is none. Custom chatbot conversations are never resumed, and nothing is created on the server — a session appears only once a message is sent.

Availability: Developer

ParameterTypeRequiredDescription
newChatbooleanNoWhen true, always lands on the empty new-chat screen instead of resuming the most recent Valu Guru conversation.

start-session ​

Opens the Valu Guru app and starts a brand-new conversation session with an initial message. Always creates a new session regardless of existing ones.

Availability: Developer

ParameterTypeRequiredDescription
messagestringYesThe initial user message to send in the new session.
chatbotIdstringNoChatbot ID to start the session with. Accepts a personal "my chatbots" id, a published LIBRARY chatbot id (auto-added to "my chatbots" if not already there), or 'default'. Defaults to the default Valu Guru chatbot ('default').

show-agents ​

Opens the Valu Guru app and switches to the Agents tab in the left panel.

Availability: Developer

No parameters.

open-chat ​

Opens the Valu Guru app and navigates to a specific chat session by ID.

Availability: Developer

ParameterTypeRequiredDescription
chatIdstringYesThe chat session ID to open.

open-agent ​

Opens the Valu Guru app and navigates to a specific agent chat by ID.

Availability: Developer

ParameterTypeRequiredDescription
agentIdstringYesThe agent ID to open.

open-chatbot ​

Opens the Valu Guru app on a library chatbot's detail page. Unlike open-chat, the target is not personal — any user in the network can view it (used e.g. by the bot badge on shared chatbot replies).

Availability: Developer

ParameterTypeRequiredDescription
chatbotIdstringYesThe library chatbot ID whose detail page to open.

create-chatbot ​

Opens the Valu Guru app on the new-chatbot creation wizard, optionally pre-filled. Pass instructions to land on the Design step fully filled in, or just prompt to land on the Describe step with the task pre-typed and ready to generate.

Availability: Developer

ParameterTypeRequiredDescription
promptstringNoPlain-language task description to seed the Describe step (e.g. "a bot that answers HR policy questions"). Ignored if instructions is also given.
instructionsstringNoFull system-prompt instructions for the chatbot. When given, the wizard opens straight on the Design step instead of Describe.
namestringNoChatbot display name.
descriptionstringNoShort chatbot description shown in the library/list.
iconstringNoFont Awesome icon class (e.g. "fa-light fa-robot") or a DiceBear avatar URL.
skillIdsstring[]NoIDs of skills (from the shared Skills Catalogue) to pre-select for the chatbot.

Valu Puzzles (puzzles) ​

Valu puzzle games

start-puzzle ​

Open Valu Puzzles and launch a specific puzzle, optionally with a score-to-beat challenge from another user.

Availability: Developer

ParameterTypeRequiredDescription
puzzleIdstringYesWhich puzzle to start. One of: "sliding" (Sliding Puzzle), "memory" (Memory Match), "sudoku" (Mini Sudoku), "wordscramble" (Word Scramble).
scoreToBeatnumberNoTarget score (0–999) the recipient should try to beat. Shown as a challenge banner above the puzzle; if the player exceeds it the result screen reads "Beat <challengerName>!".
challengerNamestringNoDisplay name of the user who issued the challenge. Shown on the challenge banner alongside the target score.

Service Intents ​

Application Service (Application) ​

Issues short-lived signed identity JWTs for iFrame (mini-app) applications. Allows an embedded application to obtain a signed token proving the current user's identity to the mini-app's own backend.

Source: src/Services/Application/ApplicationService.js

get-identity-token ​

Issues a short-lived signed identity JWT for the calling mini-app. The target application is inferred from the intent sender — no parameters needed. Requires the user to be authenticated. JWT claims: sub=userId, aud=callingApplicationId, iss=platform, exp=5min.

Availability: Developer

No parameters.

close_all ​

Closes all currently loaded applications and clears all docks. Unlike the normal close flow, does not re-open the default application — the UI stays blank with no application displayed.

Availability: Developer

No parameters.

expand-application ​

Expands the calling application to fill the dock by closing every other loaded application. The target application is inferred from the intent sender — no parameters needed. Mirrors the "Expand Application" default header action for iframe apps that render their own context menu (header: false).

Availability: Developer

No parameters.

close-application ​

Closes the calling application (unloads it from its dock), then re-opens the default network application if nothing is left docked. The target application is inferred from the intent sender — no parameters needed. Mirrors the "Close Application" default header action for iframe apps that render their own context menu (header: false).

Availability: Developer

No parameters.

Application Storage Service (ApplicationStorage) ​

Per-application file storage service for uploading, searching, and deleting resources scoped to the calling application and current user.

Source: src/Services/UploadManager/ApplicationStorageService.js

resource-upload ​

Uploads files to the calling application's storage for the current user.

Availability: Developer

ParameterTypeRequiredDescription
filesFileListYesThe files to upload.

Searches resources in the calling application's storage for the current user.

Availability: Developer

ParameterTypeRequiredDescription
limitnumberNoMaximum number of results to return. Defaults to 10.
querystringNoSearch query string.
cursorstringNoPagination cursor for fetching the next page of results.

resource-delete ​

Deletes a resource from the calling application's storage.

Availability: Developer

ParameterTypeRequiredDescription
resourceIdstringYesThe unique identifier of the resource to delete.

CBAC Service (Cbac) ​

Badge-based access control (CBAC). Manages policies that grant a permission on a target entity (room, community, or group) to users holding specific badges. Policy mutations require manage permission on the target.

Source: src/Services/Cbac/CbacService.js

list-policies ​

Lists all CBAC policies configured for a target entity.

Availability: Developer

ParameterTypeRequiredDescription
networkIdstringYesID of the network the target belongs to.
targetTypestringYesType of the target entity: "room", "community", or "group".
targetIdstringYesID of the target entity.

create-policy ​

Creates a CBAC policy on a target entity. Valid grantedPermission values depend on targetType: room → room.view / room.comment / room.contribute / room.edit; community → community.join; group → group.join. Requires manage permission on the target.

Availability: Developer

ParameterTypeRequiredDescription
networkIdstringYesID of the network the target belongs to.
targetTypestringYesType of the target entity: "room", "community", or "group".
targetIdstringYesID of the target entity.
badgeIdsarrayYesOne or more badge IDs required to gain access; must not be empty.
badgeMatchModestringYesHow badges are evaluated: "any" (one badge suffices) or "all" (every badge required).
grantedPermissionstringYesPermission granted when the badge requirement is met. Must be valid for the targetType (see intent description).

delete-policy ​

Deletes a single CBAC policy by ID. Requires manage permission on the target.

Availability: Developer

ParameterTypeRequiredDescription
policyIdstringYesID of the policy to delete.
networkIdstringYesID of the network the target belongs to.
targetTypestringYesType of the target entity: "room", "community", or "group".
targetIdstringYesID of the target entity.

list-badges ​

Lists every badge visible to the current user — badges scoped to their networks plus global ones. Returns an array of {networkId, badgeId, badgeName, badgeDescription, thumbnailId}, where networkId is "all" for a global badge. Use this to resolve a badge name to the badgeId required by search-users-by-badge-id and the policy intents.

Availability: AI, Developer

No parameters.

search-users-by-badge-id ​

Lists the users holding a given badge, optionally filtered by a name query. The reverse of looking up which badges a single user holds. Call list-badges first to resolve a badge name to its badgeId. Returns {users, total} where total is the full match count across all pages — page through it with offset/size rather than assuming the first page is everything.

Availability: AI, Developer

ParameterTypeRequiredDescription
badgeIdstringYesID of the badge whose holders are returned.
querystringNoSearch query to filter badge holders by name. Defaults to an empty string, which returns all holders.
offsetnumberNoPagination offset. Defaults to 0.
sizenumberNoNumber of results to return. Defaults to 10.

CMS Service (CMS) ​

Content management service for uploading, searching, and deleting resources scoped to rooms, props, communities, channels, and directories.

Source: src/Services/CMS/CMSService.js

resource-upload ​

Uploads files to a resource storage scoped by belonging (room, prop, community, channel, directory, or post).

Availability: Developer

ParameterTypeRequiredDescription
filesFileListYesThe files to upload.
communityIdstringNoThe community to associate the uploaded resources with.
channelIdstringNoThe channel to associate the uploaded resources with.
directoryIdstringNoThe directory to associate the uploaded resources with. If omitted and channelId is provided, it is resolved automatically from the channel's contentDirectoryId.
postIdstringNoThe post to attach the uploaded resources to.
roomIdstringNoThe room to associate the uploaded resources with.
propIdstringNoThe prop to move the uploaded resources into.

resource-search ​

Searches for resources within a given scope (room, prop, community, channel, directory, or post). Each returned resource has an id (and a title/name) — tag every resource you reference in your reply as @[cms-resource:id|title].

Availability: AI, Developer

ParameterTypeRequiredDescription
communityIdstringNoThe community to search resources in.
channelIdstringNoThe channel to search resources in.
directoryIdstringNoThe directory to search resources in. If omitted and channelId is provided, it is resolved automatically from the channel's contentDirectoryId.
postIdstringNoThe post to load resources for.
roomIdstringNoThe room to search resources in.
propIdstringNoThe prop to search resources in.
limitnumberNoMaximum number of results to return. Defaults to 10.
querystringNoSearch query string.
cursorstringNoPagination cursor for fetching the next page of results.

resource-delete ​

Deletes a resource or removes it from a prop or post.

Availability: Developer

ParameterTypeRequiredDescription
resourceIdstringYesThe unique identifier of the resource to delete.
communityIdstringNoThe community the resource belongs to.
channelIdstringNoThe channel the resource belongs to.
postIdstringNoThe post to remove the resource from (removes association, does not delete the resource).
roomIdstringNoThe room the resource belongs to.
propIdstringNoThe prop to remove the resource from (removes association, does not delete the resource).

pick-resource ​

Opens a file picker over the Network Resources of the current network so a network admin can choose ONE file, and waits for the choice. The popup opens over whatever is on screen and does not open Media. BLOCKS until the user picks or cancels. Returns the picked resource {id, title, contentType, thumbnailUrl} or null when the user cancels or closes the popup. Refused (an error, and no popup) for anyone who is not an admin of the network, for an unknown source, and for a folderId outside the requested sources. The returned resource is always inside the requested sources.

Availability: Developer

ParameterTypeRequiredDescription
sourcesstring[]YesWhere files may be picked from. Only "networkResources" (the public files of the network, networkPublic:{networkId}) is supported. Nothing outside these sources is shown or reachable.
acceptstring[]NoFile types that can be picked: a family ("image"), a family wildcard ("image/*") or an exact type ("image/png"). Other files are shown disabled. Omit to allow any file.
folderIdstringNoFolder to open in. Must be a folder inside the requested sources, otherwise the call is refused.
titlestringNoPopup title. Defaults to "Choose a file".

Commerce (Commerce) ​

Products, the cart, orders and the seller's own store, shared across apps. An app shows the network's products and adds them to the one cart the user pays for with a single QR scan, and it can run the signed-in seller's store: products, publishing, promotions and analytics. Prices, totals and payouts are decided server-side. Paying is never an action here: checkout hands the buyer to My Cart, where they press Pay and scan the code themselves, and answers with what they did. A write that costs the user money, gives goods away, cannot be undone or speaks for them in public waits for their yes in a dialog the platform draws.

Source: src/Services/Commerce/CommerceService.js

list-products ​

Search the live products available in the user's current network — the buyer's shelf, every seller's goods, not only yours. Products the network or its admins have refused are simply absent from the answer. Each product names its seller, who is a PERSON, not a store: sellerName (their profile name), sellerUserId (draw their avatar with the users API's getIcon({userId: sellerUserId})) and sellerIdentityName (the Verus ID payments go to). storeName carries the same person's name, for older callers; show the person, never a store. For the signed-in seller's OWN products, drafts included, use list-seller-products.

Availability: AI, Developer

ParameterTypeRequiredDescription
querystringNofree-text search over the product title, or a whole tag
storeIdstringNoonly this seller's products: a product's storeId, from list-products or get-product. Every user has one store, so this is everything one person sells (My Cart's "Everything from this store")
categorystringNoone of the platform's category ids — see list-categories
tagstringNoone tag, matched exactly (case and spacing do not matter)
attributesobjectNoapp-defined facets to filter by, e.g.
sortstringNonewest | popular | priceAsc | priceDesc | rating
limitnumberNopage size, up to 100 (default 24)
offsetnumberNowhere the page starts

get-product ​

One product with its price, its parts when it is a bundle, its seller, its reviews and whether the current user already owns it. The seller is a PERSON, as in list-products: sellerName, sellerUserId (their avatar through the users API's getIcon) and sellerIdentityName; the store record's name is that person too. contents is what the product holds, as a tree to draw: {type: "folder", title, items}, {type: "file", resourceId, title, kind, contentType, fileSize} and {type: "product", productId, title}. children is NOT the content: it is only the products a bundle includes, empty for anything else. items is the same content as flat database rows, kept for older callers. A file's resourceId (and resource_id in items) is null unless the user owns the product or sells it: titles and types are the shop window, the ids open the paid files. For something the user bought, use get-purchase-contents.

Availability: AI, Developer

ParameterTypeRequiredDescription
productIdstringYesthe product to read

list-categories ​

The platform's product categories as {categories: [{id, label}]}. Every product is filed under exactly one; pass an id to list-products as category, and show the label.

Availability: AI, Developer

No parameters.

add-to-cart ​

Put a product in the user's cart, credited to your app. The server re-checks that it can be bought here before accepting it, so a refusal comes back with a code to show.

Availability: AI, Developer

ParameterTypeRequiredDescription
productIdstringYesthe product to add
qtynumberNohow many, at least 1 (default 1)

check-entitlements ​

Which of these products the current user owns. This is how an app unlocks a ticket, a seat or an in-app good it sold through the shared cart.

Availability: AI, Developer

ParameterTypeRequiredDescription
productIdsarrayYesthe product ids to check

get-cart ​

Reads the user's cart — every item in it, from every app, as the buyer will check it out. Returns {items, count} where count excludes anything saved for later. Use it to show a badge, a summary, or to tell whether something this app sells is already in there. Each item's appId says which app added it. An app changes only its own rows: add-to-cart adds one, update-cart-item changes one, remove-from-cart and clear-cart take them out. Every other app's items are the buyer's to change in My Cart: send them there with open-cart.

Availability: AI, Developer

No parameters.

create-product ​

Create a product for the seller, as a DRAFT. Two ways in. With no params it opens the platform's own 'list something for sale' form in a modal and BLOCKS until the seller creates a product or cancels. With a title it creates the draft directly from the fields given — name, description, price, category, tags, cover and content — without a form: use this when you already have the resource ids (a generated cover, files found in Media). Either way returns {success: true, product} (or {success: false, product: null, code}; cancelled when the seller backed out of the form), and the product is already in the seller's catalogue. It is NEVER published here: publishing decides money and networks, so the seller confirms it separately — in the publish dialog an app opens with publish-product, or in the Merchant Console. Opening a store first (a verified Verus identity) is handled inside.

Availability: AI, Developer

ParameterTypeRequiredDescription
titlestringNothe product's name; giving one creates the draft directly instead of opening the form
descriptionstringNowhat a buyer reads before paying
priceAmountnumberNothe price; 0 or omitted is a free product. When items include other products, this is the price ON TOP of theirs
priceCurrencystringNoVRSC (default) or USD
categorystringNoone of the platform's category ids — see list-categories; required before the seller can publish
tagsarrayNoup to 10 tags of up to 24 characters; normalised (lowercase, trimmed)
imageResourceIdstringNothe cover: a resource id in the seller's own Media, e.g. one you generated
itemsarrayNothe content a buyer receives: resource ids ("res_1"), named files ({resourceId, title}), folders ({folder: "Unit 1", items: […]}) or other products ({productId}) for a bundle
stocknumberNohow many may be sold; omit for unlimited

list-seller-products ​

Every product the SIGNED-IN user sells, from their own store, so an app can show a seller their own products: live, draft (unlisted ones included), archived and broken, in every network, including ones a network blocked. Unlike list-products, the buyer's shelf of live products allowed here. The store is always the current user's; there is no way to name another. Read-only, newest change first. Returns {hasStore, products}; hasStore is false (and products empty) when the user has no store. Each product: id, title, description, status, category, tags, priceAmount, priceCurrency, totalPriceAmount, isBundle, coverResourceId, stock (null = unlimited), soldCount, contentCount. Show totalPriceAmount as the price: on a bundle priceAmount is only the seller's part on top of what it includes, and totalPriceAmount is null when the server could not price the bundle.

Availability: Developer

ParameterTypeRequiredDescription
statusstringNoonly products in this state
limitnumberNohow many to return: 100 by default, up to 500

list-my-products ​

List the SELLER's own products in their store — drafts, unlisted, live and archived — unlike list-products, which is the buyer's shelf and never shows drafts. Use it to find the productId to edit. Each product carries editable: true only for a draft (never published, or unlisted by the seller). Returns {hasStore, products}.

Availability: AI

ParameterTypeRequiredDescription
statusstringNoonly products in this state
limitnumberNohow many to return

get-my-product ​

One of the seller's own products with its content, in exactly the shape update-product takes: {product, items}. Read it before changing the content — items in update-product REPLACES the whole tree, so edit this list and send it back rather than sending only the new files. product.editable is true for a draft, whose fields and content may change; a broken product (needs attention: something it included was archived) takes new content only.

Availability: AI, Developer

ParameterTypeRequiredDescription
productIdstringYesthe product, from list-seller-products (an app) or list-my-products (the AI)

update-product ​

Edit one of the seller's own DRAFT products — one never published, or one the seller unlisted. A live or archived product is refused with code not_editable (a live one must be unlisted first: unlist-product, or the seller in the Merchant Console). A broken product (needs attention: something it included was archived) accepts items only — its other fields are not_editable — and goes back on sale when it is published again (publish-product). Only the fields given change. items REPLACES the content: call get-my-product first and send back the edited list; an empty list is refused. Never publishes. Returns {success: true, product} or {success: false, code, error}.

Availability: AI, Developer

ParameterTypeRequiredDescription
productIdstringYesthe draft (or broken product) to edit, from list-seller-products (an app) or list-my-products (the AI)
titlestringNothe product's name
descriptionstringNowhat a buyer reads before paying; an empty string clears it
priceAmountnumberNothe price; 0 makes it free. On a product that includes other products this is the price ON TOP of theirs (a buyer pays the included products plus this)
priceCurrencystringNoVRSC or USD
stocknumberNohow many may be sold (the quantity on sale)
unlimitedStockbooleanNotrue removes the quantity limit
categorystringNoone of the platform's category ids — see list-categories; an empty string clears it
tagsarrayNothe full tag list (replaces the current one): up to 10 tags of up to 24 characters
imageResourceIdstringNothe cover: a resource id in the seller's own Media
itemsarrayNothe WHOLE new content: resource ids ("res_1"), named files ({resourceId, title}), folders ({folder: "Unit 1", items: […]}) or other products ({productId}) for a bundle

list-purchases ​

What the signed-in user OWNS — every product they bought, wherever they bought it, as My Cart's Orders tab lists it. Returns {purchases: [{productId, title, coverResourceId, purchasedAt, orderId, boughtInAppId, isBundlePart, delivered, deletedBySeller, progress}]}. delivered is true once the buyer's own copy is in their Media; isBundlePart marks a product that came inside a bundle; a purchase the seller deleted is still theirs. progress is {openedFiles, totalFiles, complete} — how many of its files the user has opened (a bundle counts its parts); complete marks a purchase read to the end. Null when unknown.

Availability: Developer

ParameterTypeRequiredDescription
thisAppOnlybooleanNotrue lists only what was bought in YOUR app

get-purchase-contents ​

One purchase opened up: the version the user BOUGHT (frozen at purchase, not the product as it is now), as a tree to draw. Returns {productId, title, deletedBySeller, contents, progress}; contents nodes are {type: "folder", title, items}, {type: "file", resourceId, title, kind, contentType, fileSize, deliveredResourceId, seen} and {type: "product", productId, title} (a product inside a bundle — open it with its own get-purchase-contents). deliveredResourceId is the buyer's own copy in Media, null until delivered. seen is true once the user has opened that file (draw a green check — bought products are often lessons); a file whose kind is "folder" has no seen. progress is {openedFiles, totalFiles, complete} (a bundle counts its parts; complete once every file is opened), null when unknown. Refused with code not_owned when the user does not own the product — the server decides.

Availability: Developer

ParameterTypeRequiredDescription
productIdstringYesa product the user owns, from list-purchases

preview-purchase ​

Open the platform's previewer on what the user bought — the Orders tab's click on a file. It holds every file of the purchase in tree order, with previous / next arrows between them, and opens on resourceId when given (it must be in the purchase: its resourceId or deliveredResourceId from get-purchase-contents), on the first file otherwise. Every file the user lands on is marked as opened (seen in get-purchase-contents). A folder resource is shown on its own. Returns {success: true, count}, or {success: false, code} with not_owned, not_in_purchase or empty. The previewer is a window over the whole page.

Availability: Developer

ParameterTypeRequiredDescription
productIdstringYesa product the user owns
resourceIdstringNothe file of that purchase to open on

mark-purchase-file-seen ​

Mark one of the user's purchased files as OPENED, for an app that shows a purchase's files itself (preview-purchase marks the files it shows by itself). The file must be in the purchase (its resourceId or deliveredResourceId from get-purchase-contents) and not a folder. Returns {success: true, resourceId, progress} — progress as in get-purchase-contents — or {success: false, code} with not_owned or not_in_purchase.

Availability: Developer

ParameterTypeRequiredDescription
productIdstringYesa product the user owns
resourceIdstringYesthe file of that purchase the user opened

open-purchase-in-media ​

Open a purchase where it lives, in Media's Purchased section — the Orders tab's "Show in Media". The buyer's delivered folder when there is one, otherwise a read-only view of the version they bought. Without productId, the whole Purchased section. Media docks beside your app. Returns {success: true}, or {success: false, code: "not_owned"} without opening anything.

Availability: Developer

ParameterTypeRequiredDescription
productIdstringNoa product the user owns; omit for everything they bought

open-cart ​

Open My Cart for the user, scoped to your app's items. With popup it is drawn over your own app instead of docking My Cart — mid-purchase, that keeps the user where they were. It answers as soon as the cart is open; for a Pay button use checkout, which opens the same cart and answers with what the buyer did there.

Availability: Developer

ParameterTypeRequiredDescription
popupbooleanNotrue draws the surface over YOUR app's own pane instead of docking the application, so the page the user was on stays visible and usable behind it. Where your app is not on screen it falls back to a window over the whole page.

open-purchases ​

Open what the user OWNS in My Cart's Purchased tab — each product with its files, how far through them they are, and their rating; with productId, that product opened and shown. Receipts are open-order. With popup it is drawn over your own app instead of docking My Cart.

Availability: Developer

ParameterTypeRequiredDescription
productIdstringNoa product the user owns, to open and show
popupbooleanNotrue draws the surface over YOUR app's own pane instead of docking the application, so the page the user was on stays visible and usable behind it. Where your app is not on screen it falls back to a window over the whole page.

open-products ​

Open the seller's own products in the Merchant Console — the seller's side of open-cart. Use it for a "My products" link: it shows everything they sell across every app, not just yours, and whether they may sell at all is the platform's decision, not your app's. With popup it is drawn over your own app instead of docking the console.

Availability: Developer

ParameterTypeRequiredDescription
popupbooleanNotrue draws the surface over YOUR app's own pane instead of docking the application, so the page the user was on stays visible and usable behind it. Where your app is not on screen it falls back to a window over the whole page.

update-cart-item ​

Change one of YOUR app's rows in the user's cart: its quantity, whether it is selected for checkout, or whether it is saved for later. Give at least one of them; only the fields given change. A row added by another app is refused with code not_yours — the buyer changes those in My Cart (open-cart) — and a row the cart does not hold with not_found. Returns the whole cart as get-cart reads it: {success: true, items, count}, count excluding what is saved for later. The server re-checks stock and availability and refuses with its own code.

Availability: Developer

ParameterTypeRequiredDescription
itemIdstringYesthe cart row to change: an item id from get-cart, one your app added
qtynumberNothe new quantity, a whole number of at least 1
selectedbooleanNotrue to include it in the next checkout, false to leave it out
savedForLaterbooleanNotrue moves it out of the cart into saved for later; false brings it back

remove-from-cart ​

Take one of YOUR app's rows out of the user's cart. Another app's row is refused with code not_yours (the buyer removes those in My Cart), a row the cart does not hold with not_found. Returns the whole cart: {success: true, items, count}.

Availability: Developer

ParameterTypeRequiredDescription
itemIdstringYesthe cart row to remove: an item id from get-cart, one your app added

clear-cart ​

Remove every row YOUR app added to the user's cart, saved-for-later ones included. Other apps' rows are never touched. No dialog: they are your own rows. Returns what is left — {success: true, items, count} — so an empty items means the cart held only your rows.

Availability: Developer

No parameters.

preview-promo ​

What a discount code would do to the items YOUR app has selected in the cart — exactly what checkout will charge for them. Returns {valid, reason, discounts: [{kind, label, amountVrsc}], subtotalVrsc, totalVrsc}. reason is null when valid, else promo_invalid, promo_expired, promo_exhausted or not_applicable (a real code that takes nothing off this selection, e.g. under its minimum). discounts lists everything that takes money off, the code and any volume discount or sale alike. Read-only: nothing is reserved, and My Cart prices the code again when the buyer pays. With nothing of yours selected the server refuses validation_failed.

Availability: Developer

ParameterTypeRequiredDescription
codestringYesthe code as the buyer typed it; case and surrounding spaces do not matter

get-display ​

How this network SHOWS prices: {currency, vrscUsd}, where currency is USD or VRSC (the network admins' choice) and vrscUsd is the server's VRSC→USD rate, null when it is unknown. Every amount Commerce answers with stays in VRSC (…Vrsc); multiply by vrscUsd to show dollars, and show VRSC when the rate is null.

Availability: Developer

No parameters.

checkout ​

Your app's Pay button. Your app never takes a payment: this opens My Cart's own cart over your app, showing your items with promoCode typed in and applied, and the BUYER presses Pay and scans the code there — only My Cart creates the order. It answers when the buyer closes it: {success: true, outcome, orderId?, status?}. outcome is paid (a free order too: unlock it), pending (an order was made but is not paid yet — follow it with get-order or the order-updated event), cancelled (the order will not be paid: the buyer cancelled it, or it expired or failed — status says which — and its items are back in the cart) or dismissed (closed without making an order). Refused with code empty, and nothing opens, when none of your items is selected in the cart (add them first). With popup: false My Cart docks instead and it answers at once with outcome: "opened", as it does where there is no popup to draw. A second checkout while one is open replaces it; the first answers at once — dismissed, unless an order was already made in it.

Availability: Developer

ParameterTypeRequiredDescription
promoCodestringNoa discount code to type in and apply for the buyer; check it first with preview-promo
popupbooleanNofalse docks My Cart instead of drawing its cart over your app (default true)

open-order ​

Open one of the user's orders in My Cart, expanded: where the buyer resumes a pending payment ("Show code"), cancels or deletes an unpaid order, or reads a receipt. Those are the buyer's own actions in My Cart; your app cannot take them. With popup it is drawn over your own app instead of docking My Cart. Returns {success: true, popup}.

Availability: Developer

ParameterTypeRequiredDescription
orderIdstringYesthe order to show, e.g. from list-orders or checkout
popupbooleanNotrue draws the surface over YOUR app's own pane instead of docking the application, so the page the user was on stays visible and usable behind it. Where your app is not on screen it falls back to a window over the whole page.

list-orders ​

The user's orders, newest first, with their whole receipt as frozen at checkout. Returns {orders: [{id, status, createdAt, paidAt, expiresAt, isTest, subtotalVrsc, totalVrsc, rateVrscUsd, items: [{productId, appId, title, qty, unitPriceVrsc, lineTotalVrsc, imageResourceId, deletedBySeller, parts: [{productId, title}], bundleFeeVrsc}], discounts: [{kind, label, amountVrsc}], notCharged: [{productId, title, amountVrsc}], payouts: [{kind, identityName, storeId, amountVrsc, status, donationPercent, donationMemberCount}], payment: {method, transactionId, failureReason} | null}]}. status is pending_payment, paid, expired, cancelled or failed; without status you get pending and paid orders (a cancelled order is deleted). notCharged are parts of a bundle the user already owned. An order never carries a way to pay it: send the buyer to it with open-order.

Availability: Developer

ParameterTypeRequiredDescription
statusstringNoonly orders in this state
limitnumberNohow many orders to read, newest first; counted before thisAppOnly narrows them
thisAppOnlybooleanNotrue keeps only orders with at least one item bought in YOUR app

get-order ​

One of the user's orders, in the shape list-orders answers: {order}. Use it to follow an order checkout answered with. An order that is not the user's is refused not_found, exactly like one that does not exist. imageResourceId is null here; list-orders resolves the pictures.

Availability: Developer

ParameterTypeRequiredDescription
orderIdstringYesthe order to read

rate-product ​

Rate a product the user owns, one to five stars with an optional review. A rating is public (it shows on the product's page), so the platform asks the user first in its own dialog over your app: score and text only pre-fill it, the user can change both, and what they confirm is what is saved. Returns {success: true, review: {score, text}} — what was saved. Refused with cancelled when the user closes the dialog (nothing is saved; do not ask again on your own), not_owned when they do not own the product (no dialog), busy while another platform dialog is waiting, and unsupported where there is no dialog to ask with.

Availability: Developer

ParameterTypeRequiredDescription
productIdstringYesa product the user owns, e.g. from list-purchases
scorenumberNothe stars to propose, a whole number from 1 to 5
textstringNothe review to propose, up to 4000 characters

get-my-store ​

The signed-in user's own store and where they stand to sell — with list-seller-products, enough to draw the Merchant Console's setup checklist (verified identity → store → donation set → a product → one published). Returns {hasStore, identityVerified, sellerName, sellerUserId, store, network}. Buyers see a PERSON as the seller, not a store: show sellerName (the owner's profile name) and draw their avatar from sellerUserId with the users API's getIcon. store is {id, name, description, status, payoutIdentityName, donationTiers: [{minMembers, percent}], donationUpdatedAt}, or null — its name is kept for older callers and is not what buyers see; an empty donationTiers means no donation is set, and such a store sells nowhere. identityVerified says whether the user can open a store (a Verified Verus identity; when false, send them to their Profile). network is the network the user is in now: {id, memberCount, mode, allowedRatings, displayCurrency, donationTierIndex} — mode is open | approval_required | closed, donationTierIndex which of the store's four donation tiers this network takes (null without a store or a known size). Read-only.

Availability: Developer

No parameters.

create-store ​

Open the signed-in user's store — what lets them sell; buyers see the user themselves as the seller, so it needs no name. It needs a Verified Verus identity: without one it is refused with code not_eligible_kyc — send the user to their Profile. A user who already has a store gets it back unchanged. Returns {success: true, store} in get-my-store's shape. No dialog. Next steps: set-donation-tiers (a store with no donation sells nowhere), then create-product.

Availability: Developer

ParameterTypeRequiredDescription
namestringNorarely needed — the user's own profile name is used without it; at most 120 characters
descriptionstringNowhat they sell, at most 2000 characters

set-donation-tiers ​

Set the store's network donation — the share of every sale that goes to the network it is sold in, one percentage per network size; a store with none sells nowhere. OPENS A PLATFORM DIALOG over your app showing each tier old → new (this network's marked) and saves only if the user confirms. {success: false, code: "cancelled"} is a normal answer: the user said no — do not ask again yourself. Lowering any tier sends the store back for approval in every network that approved it (its products hide there until an admin approves again), and the dialog says so. Sending what is already saved asks nothing and changes nothing. Returns {success: true, store, reopenedNetworks} — the networks that must approve the store again. Refused busy while another dialog from your app is open, unsupported where the platform cannot show one.

Availability: Developer

ParameterTypeRequiredDescription
tiersarrayYesexactly four {minMembers, percent}, one per network size — minMembers 0, 100, 1000 and 10000 — each percent 0 to 100 with at most two decimals

list-network-access ​

Where the store stands in each network it asked to sell in: {networks: [{networkId, status, requestedAt, decidedAt, note, message}]}. status is pending | approved | rejected | suspended; note is the admins' word on their decision, message the seller's on the request. The network the user is in now may be missing: in an open one (get-my-store network.mode) a store sells without asking. Read-only.

Availability: Developer

No parameters.

request-network-access ​

Ask a network's admins to let the store sell there, with an optional message; they decide, and list-network-access shows the outcome. Returns {success: true, request} in list-network-access's shape (status: "pending"). No dialog.

Availability: Developer

ParameterTypeRequiredDescription
networkIdstringYesthe network to sell in
messagestringNoa word to the admins, at most 2000 characters

quote-bundle ​

What a product made of these products would cost a buyer, priced by the server exactly as checkout prices it (sales, bundles inside bundles, a part reached twice). Returns {currency, parts: [{productId, amount}], included, own, total, duplicates, unavailable}: included is the parts' sum, own the seller's price on top, total what a buyer pays; duplicates are parts reached twice, unavailable ids that are neither on sale nor the seller's own. Read-only — show it while the seller assembles a bundle; create-product with {productId} items makes one.

Availability: Developer

ParameterTypeRequiredDescription
productIdsarrayYesthe products the bundle would include
priceCurrencystringNothe currency to quote in (default VRSC)
ownPricenumberNothe seller's own price on top of the parts, zero or more

publish-product ​

Put one of the seller's products on sale. OPENS THE MERCHANT CONSOLE'S PUBLISH DIALOG over your app: the user picks the networks to sell in — networkIds start ticked where the store may sell, by default this network — and confirms. Only then is the product listed (in My Cart and in YOUR app) and published, freezing this version for buyers. {success: false, code: "cancelled"} is a normal answer: the user did not publish — do not ask again yourself. Only a draft or a broken product (its content fixed with update-product) can be published; no content, no category, or a store with no donation set is refused validation_failed before any dialog, saying which. Returns {success: true, product, version: {id, version, status, vaultStatus, publishedAt}}. Refused busy while another dialog from your app is open, unsupported where the platform cannot show one.

Availability: Developer

ParameterTypeRequiredDescription
productIdstringYesthe product, from list-seller-products
networkIdsarrayNonetworks to start ticked in the dialog; the user decides

unlist-product ​

Take a product that is on sale off every shelf: it becomes a draft again, its published version intact — buyers keep what they bought, and publishing again puts it back. OPENS THE MERCHANT CONSOLE'S UNLIST DIALOG over your app and unlists only if the user confirms; {success: false, code: "cancelled"} is a normal answer. Only an active product can be unlisted. Returns {success: true, product}. Unlist a live product before editing it with update-product.

Availability: Developer

ParameterTypeRequiredDescription
productIdstringYesa product on sale, from list-seller-products

archive-product ​

Withdraw a product from sale for good. OPENS A PLATFORM DIALOG over your app saying it leaves every shelf and cannot be undone, and naming the products that include it — they stop selling too until each is published again without it. Archives only if the user confirms; {success: false, code: "cancelled"} is a normal answer. Anyone who bought it keeps it. Returns {success: true, product, brokeBundles} — brokeBundles the ids of the products that stopped selling.

Availability: Developer

ParameterTypeRequiredDescription
productIdstringYesthe product, from list-seller-products

delete-product ​

Delete a product for good. OPENS THE MERCHANT CONSOLE'S DELETE DIALOG over your app, where the user types the product's name to confirm; deletes only then. {success: false, code: "cancelled"} is a normal answer. A product that is part of another product cannot be deleted: the dialog names those products and the answer is {success: false, code: "conflict"} — take it out of them first (update-product on each). Buyers keep what they bought. Returns {success: true}.

Availability: Developer

ParameterTypeRequiredDescription
productIdstringYesthe product, from list-seller-products

list-promotions ​

Every sale, volume discount and discount code of the store: {sales: [{id, productId, salePriceAmount, salePriceCurrency, startsAt, endsAt, status}], tiers: [{id, minItems, percentOff, status}], codes: [{id, code, kind, value, currency, minSubtotalVrsc, maxRedemptions, redeemedCount, reservedCount, perBuyerLimit, startsAt, endsAt, status}]}. status is active | ended for a sale and active | disabled for a tier or a code. A buyer's price takes a sale first, then at most one volume discount, then at most one code — they never stack beyond that. Read-only.

Availability: Developer

No parameters.

set-sale ​

Put one product on sale at a lower price. OPENS A PLATFORM DIALOG over your app showing the sale price against the usual one and when it runs; starts it only if the user confirms. {success: false, code: "cancelled"} is a normal answer. The sale price must be below the product's own and in its currency, and a bundle (priced by its parts) cannot go on sale — each refused validation_failed before any dialog. A product with a sale running gets this one instead. Returns {success: true, sale} in list-promotions' shape.

Availability: Developer

ParameterTypeRequiredDescription
productIdstringYesthe product, from list-seller-products
salePriceAmountnumberYesthe sale price, below the product's own
salePriceCurrencystringNomust be the product's own price currency (the default)
startsAtstringNoISO date it starts; omit for now
endsAtstringNoISO date it ends; omit to run until end-sale

end-sale ​

End a sale now. Direct — stopping a discount needs no dialog. Returns {success: true, sale} with status: "ended".

Availability: Developer

ParameterTypeRequiredDescription
saleIdstringYesthe sale's id (not the product's), from list-promotions

set-volume-tier ​

A store-wide volume discount: every order with at least minItems of the seller's items gets percentOff off, in every app and network the store sells in. OPENS A PLATFORM DIALOG over your app ("N or more items → P% off, every order in your store") and saves only if the user confirms; {success: false, code: "cancelled"} is a normal answer. With tierId it edits that discount (the dialog shows what it was); without, it adds one — or replaces the one at the same minItems. Returns {success: true, tier} in list-promotions' shape.

Availability: Developer

ParameterTypeRequiredDescription
minItemsnumberYeshow many items an order needs, a whole number of at least 2
percentOffnumberYesthe discount, more than 0 and at most 100
tierIdstringNothe discount to edit, from list-promotions

remove-volume-tier ​

Remove a volume discount. Direct — no dialog. Returns {success: true}.

Availability: Developer

ParameterTypeRequiredDescription
tierIdstringYesthe discount, from list-promotions

create-discount-code ​

A discount code buyers type at checkout — on the seller's own products only. OPENS A PLATFORM DIALOG over your app with the code, its value, limits and dates, and creates it only if the user confirms; {success: false, code: "cancelled"} is a normal answer. The code is stored upper-case; one the store already has is refused conflict. Returns {success: true, discountCode} in list-promotions' code shape — named discountCode because code is the refusal field.

Availability: Developer

ParameterTypeRequiredDescription
codestringYes3 to 32 letters, digits and hyphens
kindstringYespercent off, or a fixed amount off
valuenumberYesthe percent (at most 100) or the amount, more than 0
currencystringNoa fixed amount's currency (default VRSC)
minSubtotalVrscnumberNothe smallest order it applies to, in VRSC
maxRedemptionsnumberNohow many times it can be used in all; omit for unlimited
perBuyerLimitnumberNohow many times one buyer can use it; omit for unlimited
startsAtstringNoISO date it starts; omit for now
endsAtstringNoISO date it ends; omit for no end

update-discount-code ​

Change a discount code. DIRECT when it only stops the discount: status: "disabled", or an endsAt sooner than the one it has (any end, for a code that has none). Anything that gives more — status: "active" again, a later end or none (endsAt: null), more uses, more per buyer — OPENS A PLATFORM DIALOG over your app with each change before → after, and saves only if the user confirms; {success: false, code: "cancelled"} is a normal answer. Returns {success: true, discountCode}.

Availability: Developer

ParameterTypeRequiredDescription
codeIdstringYesthe code's id, from list-promotions
statusstringNodisabled turns it off; active turns it back on
endsAtstringNoISO date it ends, or null for no end
maxRedemptionsnumberNohow many times it can be used in all, at least 1
perBuyerLimitnumberNohow many times one buyer can use it, at least 1

delete-discount-code ​

Delete a code nothing ever used. Direct — no dialog. A code that was used is part of the record and is refused conflict: turn it off instead (update-discount-code with status: "disabled"). Returns {success: true}.

Availability: Developer

ParameterTypeRequiredDescription
codeIdstringYesthe code's id, from list-promotions

get-analytics ​

The store's own numbers over a range — the Merchant Console's Analytics — exactly as the server sends them: {range, totals: {revenueVrsc, orders, units, curatorFeeVrsc, revenueApproximate}, series: [{day, revenueVrsc, orders, suppressed}], topProducts: [{productId, title, revenueVrsc, units, suppressed}], byNetwork: [{networkId, revenueVrsc, orders, suppressed}], suppressedCells}. A row with suppressed: true was built from too few orders and is WITHHELD: its numbers are not figures — show it as withheld, never as 0. orders counts order lines touched, an upper bound, not distinct orders. Read-only.

Availability: Developer

ParameterTypeRequiredDescription
fromstringNoISO date the range starts
tostringNoISO date the range ends
testOnlybooleanNotrue reads the test orders' figures instead of the real ones (never mixed)

subscribe-events ​

Be told when commerce changes instead of polling. Name the events you want; the answer is {success: true, events}, your app's whole set now: each call REPLACES the previous one, and an empty list stops them all. An unknown name is refused with validation_failed and nothing changes; a caller that is not an embedded app is refused with unsupported. Each event arrives as a host push, api:trigger with {action: "commerce", data: {event, …}} (the SDK emits ValuApi.ON_COMMERCE with that data). The events and their data: cart-updated {count} — the cart changed; count is what the cart badge shows (saved-for-later excluded), never which items: re-read with get-cart. order-updated {orderId, status} — an order holding at least one of YOUR app's items changed: pending_payment, paid, failed, expired, cancelled or deleted. Orders without your items are never sent to you. delivery-updated {orderId, status} — that order's files: delivered (they are in the buyer's Media; re-read with list-purchases), unavailable or failed. catalogue-updated {productId, change} — the shelf of this network changed: change is added, updated or removed; productId null means re-read the whole shelf with list-products. seller-product-updated {productId, change} — one of the signed-in seller's own products: created, updated, content-updated, published, unlisted, archived, deleted, broken, sale-started, sale-ended, blocked or unblocked; re-read with list-seller-products. seller-store-updated {change, networkId?} — their store: created, updated, donation-updated or network-access-updated (networkId names the network when there is one). seller-promotions-updated {change} — a promotion changed: sale, tier or code. An event says WHAT changed, never the new state: treat it as a hint to re-read with the matching intent, never as data, and expect to miss one now and then (a missed event is a stale screen until the next read). Subscriptions last until unsubscribe-events, until your app's frame closes or until it reloads — moving the app to another dock reloads its frame — so subscribe again every time your app starts, after api:ready.

Availability: Developer

ParameterTypeRequiredDescription
eventsarrayYesthe event names to receive, replacing any earlier subscription: cart-updated, order-updated, delivery-updated, catalogue-updated, seller-product-updated, seller-store-updated, seller-promotions-updated

unsubscribe-events ​

Stop receiving commerce events. Without events, every one your app subscribed to; with it, only those. Answers {success: true, events}: what your app still receives (empty when nothing). An unknown name is refused with validation_failed and nothing changes. There is no need to call it before your app closes: a subscription ends with the frame that made it.

Availability: Developer

ParameterTypeRequiredDescription
eventsarrayNothe event names to stop receiving (see subscribe-events); omit to stop them all

Community Service (Community) ​

Community service for browsing communities, listing channels, and loading posts within channels.

Source: src/Services/Community/CommunityService.js

search-communities ​

Search for available communities. Returns community objects with communityId, name, description, and other properties.

Availability: AI, Developer

ParameterTypeRequiredDescription
querystringNoSearch query to filter communities by name.
limitnumberNoNumber of results to return. Defaults to 10.
afterCommunityIdstringNoPagination cursor — ID of the last community from previous page.

get-community-info ​

Retrieves detailed information about a specific community by its ID.

Availability: AI, Developer

ParameterTypeRequiredDescription
communityIdstringYesThe unique community identifier.

get-channels ​

Lists channels within a specific community. Returns {communityId, channels[]} where each channel has channelId, rootChannelId (same as channelId — use this for entity tags), title, and other properties.

Availability: AI, Developer

ParameterTypeRequiredDescription
communityIdstringYesThe unique community identifier.
limitnumberNoMaximum number of channels to return. Defaults to 100.

get-posts ​

Loads posts/messages in a specific channel or sub-channel. Returns {communityId?, rootChannelId, subChannelId?, messages[]}. The rootChannelId and subChannelId in the response are the exact values to use when constructing community-post or community-sub-channel-post entity tags — no need to track them separately.

Availability: AI, Developer

ParameterTypeRequiredDescription
channelIdstringYesThe root channel ID (use rootChannelId from get-channels result).
communityIdstringNoThe community ID. Pass this so the response echoes it back for entity tag construction.
subChannelIdstringNoSub-channel ID when loading posts from a nested channel. Use the subChannelId field from the app context sub-channel entry.
limitnumberNoNumber of posts to return. Defaults to 10.
afterMessageIdstringNoPagination cursor — ID of the last message from previous page.

Data Provider Service (DataProvider) ​

Picker service for selecting items from data providers (rooms, contacts, etc.) via modal or inline overlay.

Source: src/Services/DataProvider/DataProviderService.js

pick-single ​

Opens an interactive picker so the END USER can choose ONE item (a room, contact, group, etc.) and returns their selection. BLOCKS until the user picks or cancels. Returns the selected item object (its shape depends on the provider — typically {id, name, ...}) or null if the user cancelled. Use this when the user's request needs an entity reference and they have NOT named a specific one — e.g. "share this in a group" without naming the group → call with providers: ["groups"]. Do not use to search programmatically; use the provider's own search/list service intent for that.

Availability: AI, Developer

ParameterTypeRequiredDescription
providersstring[]YesProvider IDs to show as picker sources. Available IDs include: "rooms", "contacts", "groups", "communities", "props", "events". Pass one entry for a single-source picker, or multiple to let the user switch sources via tabs. Example: ["rooms"] or ["contacts", "groups"].
titlestringNoDialog title shown above the picker. Defaults to the provider's built-in title.
widthstringNoCSS width for the modal (desktop only).
heightstringNoCSS height for the modal (desktop only).

pick-multiple ​

Same as pick-single but lets the END USER select MORE THAN ONE item. BLOCKS until they confirm or cancel. Returns an array of selected items ([{id, name, ...}, ...]) or null if cancelled. Use when the user's request implies multiple targets — e.g. "invite some people to the room" → call with providers: ["contacts"].

Availability: AI, Developer

ParameterTypeRequiredDescription
providersstring[]YesProvider IDs to show. Same set as pick-single.
titlestringNoDialog title.
confirmLabelstringNoConfirm button label (e.g. "Invite", "Share with"). Defaults to "Select".
confirmIconstringNoConfirm button icon class (Font Awesome, e.g. "fa-light fa-paper-plane-top").
widthstringNoCSS width for the modal (desktop only).
heightstringNoCSS height for the modal (desktop only).

Developer Service (Developer) ​

Developer Portal service for creating and listing the current user's applications.

Source: src/Applications/DeveloperPortal/Services/DeveloperService.js

create-application ​

Creates a new application in the Developer Portal. By default the application is served in an iframe from https://{appSlug}-{userId}.valuguru.app/ — a host of its own, the slug and the user id joined with a dash (the slug is derived from the name — lowercased, dashes; deduplicated with -2, -3, … on collision) — and that site needs code deployed to it before it shows anything. Pass the optional url to instead point the app's iframe DIRECTLY at an existing external page (no code/build needed) — the created app then opens straight to that URL. Returns the created app's id, devId, slug, URL, and a ready-made tag — a chat entity tag of the form @[application:<appId>|<Name>]. To give the user a clickable link that opens the application inside the platform, paste that tag value verbatim into your reply (do NOT link the raw URL).

Availability: AI, Developer

ParameterTypeRequiredDescription
namestringYesHuman-readable name for the application. Also used to derive the URL slug.
descriptionstringNoShort description of what the application does.
urlstringNoOptional external URL (http/https) to embed directly in the app's iframe, e.g. https://example.com. When provided, the app frames this page as-is with no build/deploy — the created app opens straight to it. The target site MUST allow third-party framing: many major sites (news portals, Google, most social networks) send X-Frame-Options or a CSP frame-ancestors directive that forbids embedding, and the browser will render them blank. Prefer a site known to permit framing.
iconstringNoFont Awesome icon for the application, in the "fa-light fa-<name>" format (e.g. "fa-light fa-newspaper"). Set this for EVERY app you create, choosing an icon that represents what the app does — if omitted it falls back to a generic lightbulb. Pick the best match from this set: fa-light fa-robot, fa-light fa-brain-circuit, fa-light fa-microchip-ai, fa-light fa-user-robot, fa-light fa-message-bot, fa-light fa-cpu, fa-light fa-binary, fa-light fa-code, fa-light fa-terminal, fa-light fa-database, fa-light fa-network-wired, fa-light fa-satellite-dish, fa-light fa-palette, fa-light fa-pen-fancy, fa-light fa-paintbrush, fa-light fa-music, fa-light fa-camera, fa-light fa-film, fa-light fa-photo-film, fa-light fa-wand-magic-sparkles, fa-light fa-sparkles, fa-light fa-stars, fa-light fa-hat-wizard, fa-light fa-crystal-ball, fa-light fa-graduation-cap, fa-light fa-book-open, fa-light fa-books, fa-light fa-lightbulb, fa-light fa-magnifying-glass-chart, fa-light fa-chart-mixed, fa-light fa-flask, fa-light fa-microscope, fa-light fa-atom, fa-light fa-dna, fa-light fa-briefcase, fa-light fa-user-tie, fa-light fa-user-astronaut, fa-light fa-user-secret, fa-light fa-user-ninja, fa-light fa-users, fa-light fa-handshake, fa-light fa-comments, fa-light fa-bullhorn, fa-light fa-headset, fa-light fa-shield-check, fa-light fa-dragon, fa-light fa-unicorn, fa-light fa-cat, fa-light fa-dog, fa-light fa-rocket, fa-light fa-planet-ringed, fa-light fa-fire-flame-curved, fa-light fa-bolt, fa-light fa-leaf, fa-light fa-gem, fa-light fa-trophy. Any other valid Font Awesome 6 icon name is accepted too — always keep the "fa-light" weight.

list-applications ​

Lists the current user's applications in the Developer Portal. Returns each application's appId, devId, name, slug, url, description, createdAt timestamp, and a ready-made tag — a chat entity tag of the form @[application:<appId>|<Name>]. To give the user a clickable link that opens an application inside the platform, paste its tag value verbatim into your reply (do NOT link the raw URL).

Availability: AI, Developer

No parameters.

list-application-apis ​

Lists every application published in the current network that declares a REST API in its manifest. Returns {success, networkId, apis}; each api carries applicationId, address (the gateway path and token audience), title, description, gatewayUrl (where callers send requests, through the Valu Guru gateway), documentUrl (its OpenAPI document, read through the gateway), scopes, callers, availability, userContext, docsUrl and routable. Read-only: it describes the APIs, it calls none of them.

Availability: AI, Developer

No parameters.

list-my-application-apis ​

Lists the REST APIs of the applications the current user develops or tests, unreleased drafts included — what list-application-apis does not show. Returns {success, apis}; each api carries the same fields as list-application-apis plus devId, version (the version that describes the API: the released one when it declares an API, otherwise the newest that does) and live (true when that version is the released one). Read-only.

Availability: AI, Developer

No parameters.

Events Service (Events) ​

Calendar service for listing, creating, and editing meetings.

Source: src/Applications/EventsApplication/Services/EventsService.js

list-events ​

Returns a list of calendar events for the specified date range and optional meeting filter, sorted by start time ascending.

Availability: AI, Developer

ParameterTypeRequiredDescription
rangestringNoDate range to fetch. Must be one of: day, week, month, year. Defaults to month.
startDatestringNoISO 8601 anchor date (e.g. "2026-04-07"). Defaults to today.
filterstringNoMeeting source filter. Must be one of: all, room, group, user, community. Defaults to all.
idstringNoID of the room, group, user, or community. Used when filter is not all.

create-meeting ​

Creates a new meeting on the calendar with the specified title, type, time range, and optional participants, description, color, and recurrence.

Availability: AI, Developer

ParameterTypeRequiredDescription
titlestringYesThe title of the meeting.
typestringYesThe meeting type. Must be one of: room, group, community, direct (private).
startDatestringNoThe meeting start date/time as a UTC ISO 8601 string (e.g. "2026-04-10T14:00:00.000Z"). Always use UTC — convert from local time if needed. Defaults to today's current time rounded up to the next 15-minute mark.
endDatestringNoThe meeting end date/time as a UTC ISO 8601 string (e.g. "2026-04-10T15:00:00.000Z"). Always use UTC — convert from local time if needed. Defaults to 1 hour after startDate.
descriptionstringNoAn optional description for the meeting.
colorstringNoHex color code for the meeting (e.g. "#4299f5"). Defaults to the type's default color when omitted.
participantsstring[]NoArray of user IDs to invite to the meeting. For private meetings with multiple participants, a group is created automatically.
recurringWeeklybooleanNoIf true, the meeting repeats every week at the same time. Not supported for community meetings.
roomIdstringNoThe room ID. Required when type is "room".
groupIdstringNoThe group ID. Required when type is "group".
communityIdstringNoThe community ID. Required when type is "community".
globalEventIdstringNoThe community global event ID. Required when type is "community".

edit-meeting ​

Updates an existing meeting's fields (title, description, time, participants, or color) by meeting ID.

Availability: AI, Developer

ParameterTypeRequiredDescription
meetingIdstringYesThe unique identifier of the meeting to update.
titlestringNoNew title for the meeting.
descriptionstringNoNew description for the meeting.
startDatestringNoNew start date/time as a UTC ISO 8601 string (e.g. "2026-04-10T14:00:00.000Z"). Always use UTC — convert from local time if needed.
endDatestringNoNew end date/time as a UTC ISO 8601 string (e.g. "2026-04-10T15:00:00.000Z"). Always use UTC — convert from local time if needed.
colorstringNoNew hex color code for the meeting (e.g. "#4299f5").
participantsstring[]NoUpdated list of invited participant user IDs.

Groups Service (Groups) ​

Group management service for listing groups the current user belongs to and their participants.

Source: src/Services/Groups/GroupsService.js

list-groups ​

Returns groups the current user belongs to. Supports search and cursor-based pagination.

Availability: AI, Developer

ParameterTypeRequiredDescription
querystringNoSearch query to filter groups by name.
limitnumberNoMaximum number of groups to return. Defaults to 20.
cursorstringNoPagination cursor for fetching the next page of results.

list-group-participants ​

Returns participants of a specific group. Supports search and cursor-based pagination.

Availability: AI, Developer

ParameterTypeRequiredDescription
groupIdstringYesThe unique identifier of the group.
querystringNoSearch query to filter participants by name.
limitnumberNoMaximum number of participants to return. Defaults to 20.
cursorstringNoPagination cursor for fetching the next page of results.

discover-groups ​

Returns groups the current user can join via CBAC — groups whose badge policy is satisfied by the badges the user holds. Each result includes the cbacPolicies that grant access. Supports search and cursor-based pagination.

Availability: AI, Developer

ParameterTypeRequiredDescription
querystringNoSearch query to filter groups by name.
limitnumberNoMaximum number of groups to return. Defaults to 20.
cursorstringNoPagination cursor for fetching the next page of results.

join-group ​

Joins the current user to a group via CBAC. The user must hold a badge that satisfies a badge policy on the target group (use discover-groups to find eligible groups first).

Availability: AI, Developer

ParameterTypeRequiredDescription
groupIdstringYesThe unique identifier of the group to join.

HTTP Service (Http) ​

Generic HTTP utility: reachability ping, GET, and POST against any URL. Requests are sent without user credentials (cookies are stripped); responses include status, headers, and body. Timeouts are capped server-side.

Source: src/Services/Http/HttpService.js

ping ​

Pings a URL with HEAD and returns whether it is reachable, the response latency in ms, and the HTTP status code (0 for cross-origin or unreachable servers). Returns: { up: boolean, latency: number, status: number, error?: string }.

Availability: Developer

ParameterTypeRequiredDescription
urlstringYesThe URL to ping.
timeoutnumberNoRequest timeout in milliseconds. Defaults to 10000, max 60000.

get ​

Performs an HTTP GET against the URL and returns the response. Body is auto-parsed as JSON when the response Content-Type is application/json (or *+json), otherwise as text. Returns: { ok: boolean, status: number, statusText: string, headers: object, body: any, bodyType: "json"|"text", latency: number, error?: string }.

Availability: Developer

ParameterTypeRequiredDescription
urlstringYesAbsolute URL to GET.
headersobjectNoMap of request headers to send (e.g. { "Accept": "application/json" }).
timeoutnumberNoRequest timeout in milliseconds. Defaults to 30000, max 60000.
responseTypestringNoHow to parse the response body: "auto" (default — JSON if Content-Type matches, else text), "json", or "text".

post ​

Performs an HTTP POST against the URL with the given body and returns the response (same shape as get). If body is a plain object it is JSON-stringified and Content-Type defaults to application/json; strings are sent verbatim with the supplied or existing Content-Type.

Availability: Developer

ParameterTypeRequiredDescription
urlstringYesAbsolute URL to POST to.
bodyobjectNoRequest body. Plain object → JSON-stringified; string → sent verbatim. Omit for an empty-body POST.
headersobjectNoMap of request headers to send.
contentTypestringNoOverride the Content-Type header (defaults to application/json when body is an object).
timeoutnumberNoRequest timeout in milliseconds. Defaults to 30000, max 60000.
responseTypestringNoHow to parse the response body: "auto" (default), "json", or "text".

Logging Service (Logging) ​

Exposes the in-memory console log buffer captured by ConsoleLogCapture for diagnostics and bug reporting.

Source: src/Services/Logging/LoggingService.js

get-logs ​

Returns the captured console log buffer (log, info, warn, error) since app start. Choose the format: "text" returns { format: "text", text: <string> } with one line per entry; "file" returns { format: "file", filename, mimeType, size, file: File } — the File is for direct callers (upload/download) and is omitted in the AI/MCP serialized response, which still includes filename, mimeType, and size.

Availability: Developer

ParameterTypeRequiredDescription
formatstringNoOutput format. Must be one of: "text", "file". Defaults to "text".

Networks Service (Networks) ​

Network management service for retrieving information about the current network.

Source: src/Applications/NetworksApplication/Services/NetworksService.js

get-current-network ​

Returns the id and name of the network the user is currently in. Call this to get the current networkId before making any room or network-related calls.

Availability: AI, Developer

No parameters.

Profile Service (Profile) ​

Read-only access to a user's public profile artifacts — Verus verifiable credentials and network badges — addressed by userId. No UI side effects.

Source: src/Services/Profile/ProfileService.js

get-user-credentials ​

Returns the Verus verifiable credentials published on a user's profile, by their userId. These are the attestation claims of type "credential" shown in the profile Credentials view. Revoked credentials are returned only when the userId is the current user. Visibility is enforced by the backend against the current user.

Availability: AI, Developer

ParameterTypeRequiredDescription
userIdstringYesThe unique identifier of the user whose credentials to list.
statusstringNoOptional claim status filter (e.g. "Verified And Persisted"). Omit to return credentials of all statuses the caller may see.

get-user-badges ​

Returns the badges assigned to a user by their userId. Each badge includes badgeId, badgeName, badgeDescription, thumbnailId, and networkId. Visibility is enforced by the backend against the current user.

Availability: AI, Developer

ParameterTypeRequiredDescription
userIdstringYesThe unique identifier of the user whose badges to list.
networkIdstringNoNetwork scope for the badges. Defaults to "all", which fetches badges from every network shared with the target user.

Resource Service (Resources) ​

Low-level resource service for generating URLs (thumbnails, public links, direct downloads) for resources.

Source: src/Services/Resources/ResourceService.js

get-thumbnail-url ​

Returns a thumbnail URL for a resource at the specified size.

Availability: Developer

ParameterTypeRequiredDescription
resourceIdstringYesThe unique identifier of the resource.
thumbnailSizenumberNoThe desired thumbnail size in pixels. Defaults to 256.

generate-public-url ​

Generates a public preview URL for a resource.

Availability: AI, Developer

ParameterTypeRequiredDescription
resourceIdstringYesThe unique identifier of the resource.

generate-best-view-url ​

Generates an optimized view URL for a resource.

Availability: AI, Developer

ParameterTypeRequiredDescription
resourceIdstringYesThe unique identifier of the resource.

generate-direct-public-url ​

Generates a direct public API URL for downloading a resource.

Availability: AI, Developer

ParameterTypeRequiredDescription
resourceIdstringYesThe unique identifier of the resource.

list-bot-avatars ​

Returns the network-allowed bot avatar collection (id, name, tags) from the shared bot-avatars directory. Avatars carrying the current network's denied tags (same modesty/policy filter as the user avatar picker) are excluded. Use a returned id as a 3D avatar resource id (e.g. an agent's avatarResourceId).

Availability: AI, Developer

ParameterTypeRequiredDescription
limitnumberNoMax avatars to return. Defaults to 50.

Room Points Service (RoomPoints) ​

GoTo points of a room (server name "cameraPosition"): list them, save or delete one directly, or open the point editor and let the user do it. Editing points requires the room's edit permission. Position and rotation are metres and EULER DEGREES in the room's own space — they cannot be computed from outside the 3D scene, so prefer create-point / edit-point (which receive the live camera pose from Unity) over save-point unless you are re-using a pose you already read.

Source: src/Services/RoomPoints/RoomPointsService.js

list-room-points ​

Returns every saved GoTo point of a room, in server order: {status: "ok", points}. Each point carries id, name, position {x,y,z}, rotation {x,y,z,w} (EULER DEGREES, w is always 0 — NOT a quaternion), cameraMode (0 = do not change, 1 = fly, 2 = third person) and the server timestamps. A room with no saved points returns an empty list — the "Home" point Unity shows in that case exists only in its memory.

Availability: AI, Developer

ParameterTypeRequiredDescription
roomIdstringYesThe room whose points to list.
networkIdstringNoNetwork the room belongs to. Defaults to the current network.

create-room-point ​

Opens the point editor for a NEW point and BLOCKS until the user saves or cancels. Needs a pose to save the point at: pass camera (the live 3D camera pose) or a point to copy the pose from — the web layer cannot read the camera itself. Resolves {status: "ok", point, persisted, savePreview} once the point is written, or {status: "cancelled"} / {status: "error", message}.

Availability: AI, Developer

ParameterTypeRequiredDescription
roomIdstringYesThe room the point belongs to.
cameraobjectNoThe pose the point is saved at: {position: {x,y,z}, rotation: {x,y,z,w}} with the rotation in EULER DEGREES. Required unless point carries a pose.
pointobjectNoA cameraPosition to pre-fill the form with (name, camera mode, pose). Its id is ignored for a create.
namestringNoPre-fills the point name. Wins over the name the point carried.
cameraModenumberNoPre-fills the camera mode: 0 — do not change, 1 — free fly, 2 — third person.
savePreviewbooleanNoPre-fills the "Make preview" toggle. Defaults to true. The screenshot and parallax capture themselves are done by the 3D scene, not here.
persistbooleanNoWhether this service writes the point to the server. Defaults to true; pass false to use the editor as pure UI and save the returned point yourself.
networkIdstringNoNetwork the room belongs to. Defaults to the current network.

edit-room-point ​

Opens the point editor for an EXISTING point and BLOCKS until the user saves, deletes or cancels. Resolves {status: "ok", point, persisted, savePreview}, {status: "deleted", point: {id}, persisted}, {status: "cancelled"} or {status: "error", message}. A point whose id is empty is treated as a create.

Availability: AI, Developer

ParameterTypeRequiredDescription
roomIdstringYesThe room the point belongs to.
pointobjectYesThe point being edited, in the cameraPosition shape list-points returns.
cameraobjectNoThe live 3D camera pose, {position: {x,y,z}, rotation: {x,y,z,w}} in EULER DEGREES. When present the editor offers to move the point here, ticked by default.
deletablebooleanNoWhether the editor may offer Delete. Defaults to false — a room should keep at least one point.
namestringNoPre-fills the point name. Wins over the name the point carried.
cameraModenumberNoPre-fills the camera mode: 0 — do not change, 1 — free fly, 2 — third person.
savePreviewbooleanNoPre-fills the "Make preview" toggle. Defaults to true.
persistbooleanNoWhether this service writes the change to the server. Defaults to true.
networkIdstringNoNetwork the room belongs to. Defaults to the current network.

save-room-point ​

Writes a point WITHOUT opening any UI: creates it when point.id is empty or missing, otherwise overwrites the saved point with that id. An update REPLACES the whole point, so send a complete one (read it with list-room-points first) — fields left out are not kept. Returns {status: "ok", point} with the server copy, whose id is the one to keep after a create.

Availability: Developer

ParameterTypeRequiredDescription
roomIdstringYesThe room the point belongs to.
pointobjectYesThe complete point: {id?, name, position {x,y,z}, rotation {x,y,z,w} in EULER DEGREES, cameraMode}.

delete-room-point ​

Deletes one saved point by id. Returns {status: "ok"}. The point parallax preview resource is cleaned up by the 3D scene, not here.

Availability: Developer

ParameterTypeRequiredDescription
roomIdstringYesThe room the point belongs to.
pointIdstringYesId of the point to delete.

Room Zones Service (RoomZones) ​

Zones of a room and the claims on them (docs/superpowers/specs/2026-10-16-room-claiming-zones-design.md). A zone is an invisible box in a room: it can join its video call when someone walks in, it can be claimed as somebody's personal space, or both. A CLAIM IS A PROP INVITATION on the master server — there is no other store — so the occupant also gets edit rights on the zone prop. The server does not enforce exclusivity: the earliest claim wins and the loser is withdrawn, so always read the occupancy back rather than assuming a claim held.

Source: src/Services/RoomZones/RoomZonesService.js

list-room-zones ​

Every zone of a room: {status: "ok", zones}. Each zone carries id (the prop id), title, its box in room metres (x, z, rotY in degrees, width, depth, height, floorOffset), the two capabilities (call, claim) and its claim policy (settings.audience is "members" or "listed"). A room with no zones returns an empty list.

Availability: AI, Developer

ParameterTypeRequiredDescription
roomIdstringYesThe room whose zones to list.
claimableOnlybooleanNoOnly the zones that can be claimed (the "spaces"). Default false.

zone-occupancy ​

Who holds the room's claimable zones right now: {status: "ok", occupancy} keyed by zone id, each {claim, conflicts, stale}. claim is null when the zone is free, else {userId, claimedAt, source, doorPolicy, displayName, status}. stale means the occupant no longer has access to the room, so the zone is effectively free. conflicts are losing claims a moderator should clear. This reads the server every time — there is no push for prop invitations.

Availability: AI, Developer

ParameterTypeRequiredDescription
roomIdstringYesThe room to read.

claim-zone ​

Claims a zone for the SIGNED-IN user. Returns {status: "ok", claim} when it worked, or {status: "refused", reason, message} when it did not — "taken", "limit", "not-listed", "not-claimable", "no-access" or "cooldown". A user who may not write prop invitations at all gets {status: "refused", reason: "needs-request"}: they must ask a room owner to assign it instead. Never claims on behalf of somebody else — use assign-zone for that.

Availability: AI, Developer

ParameterTypeRequiredDescription
roomIdstringYesThe room the zone belongs to.
zoneIdstringYesThe zone to claim (its prop id, as list-room-zones returns it).
displayNamestringNoWhat to call the space, shown instead of the claimant's name.
statusstringNoA one-line status shown next to the space, e.g. "in focus until 4".
doorPolicystringNoWho may come in: "open" (default), "knock" or "closed". Shown, not yet enforced.

release-zone ​

Releases the signed-in user's own claim on a zone: {status: "ok"}. Starts a one-minute cooldown before the same user may claim that zone again. Releasing a zone somebody else holds is not possible here — a room owner uses assign-zone or the Spaces app.

Availability: AI, Developer

ParameterTypeRequiredDescription
roomIdstringYesThe room the zone belongs to.
zoneIdstringYesThe zone to release.

assign-zone ​

Gives a zone to a particular user. Requires the caller to OWN the room (manage rights) or be a network admin; anything less is refused. Bypasses the zone's audience, the room's per-user limit and the cooldown by design — this is how offices are handed out. Returns {status: "ok"}.

Availability: Developer

ParameterTypeRequiredDescription
roomIdstringYesThe room the zone belongs to.
zoneIdstringYesThe zone to assign.
userIdstringYesWho gets it.

Rooms Service (Rooms) ​

Room management service for searching rooms, browsing room templates, creating rooms from templates, retrieving room details, managing prop content, and checking permissions.

Source: src/Applications/RoomsApplication/Services/RoomsService.js

search-rooms ​

Searches all public/discoverable rooms in the current network using the explorer service. Returns rooms anyone can find and join, regardless of membership. Use this when the user wants to discover or browse rooms. Every room in the result carries a ready-made entity link in its tag field (@[room:networkId/roomId|Name]) plus the resolved networkId — paste that tag verbatim when linking to the room and NEVER assemble one from ids yourself.

Availability: AI, Developer

ParameterTypeRequiredDescription
querystringNoSearch query to filter rooms by name.
offsetnumberNoPagination offset. Defaults to 0.
sizenumberNoNumber of results to return. Defaults to 10.

search-my-rooms ​

Searches rooms belonging to the current user within the current network — their joined rooms, favorites, or pending invitations. Use this when the user asks about their own rooms. Every room in the result carries a ready-made entity link in its tag field (@[room:networkId/roomId|Name]) plus the resolved networkId — paste that tag verbatim when linking to the room and NEVER assemble one from ids yourself.

Availability: AI, Developer

ParameterTypeRequiredDescription
filterstringYesRoom filter. Must be one of: "all" — all rooms the current user belongs to; "favourite" — user's favorite rooms only; "invites" — rooms the user has been invited to but not yet joined.
querystringNoSearch query to filter rooms by name.
offsetnumberNoPagination offset. Defaults to 0.
sizenumberNoNumber of results to return. Defaults to 10.

get-room ​

Retrieves basic room model data by room ID including name, description, settings, and metadata.

Availability: Developer

ParameterTypeRequiredDescription
roomIdstringYesThe unique room identifier.
networkIdstringNoNetwork ID the room belongs to.

get-permissions ​

Retrieves the current user permissions for a room (view, comment, contribute, edit, manage).

Availability: AI, Developer

ParameterTypeRequiredDescription
roomIdstringYesThe unique room identifier.

get-room-props ​

Lists all props (interactive objects) in a room. Returns prop objects with id, name (what the prop SHOWS, and the label on its tag: the prop's own title, else the title of its FIRST resource — a filled frame is named after its content, because a content prop carries no title of its own — else the asset's catalog name, else the bare id when nothing names it), assetTitle (the asset's catalog name, e.g. "Gold Picture Frame" or "Presentation Board" — tells you what kind of object the prop is even when the author renamed it), type (array of content types the prop can hold — empty means it cannot hold content), thumbnailCount (number of visual display canvases — a picture frame has thumbnailCount > 0), isPresentationBoard (true = a live screen-share board, NEVER a target for pasted content; null = unknown), invokeType (Default/Container/Bookshelf/FileCabinet), tags, contentCount, assetId, and tag — a ready-made entity link for the prop (@[prop:networkId/roomId/propId|Name]) that you paste verbatim when referring to it, never assembling one from ids yourself. Match the user's words against tags, name and assetTitle to find the prop they mean (e.g. "logo", "team", "the gold frame"). Each prop also carries groupId — the id of its prop group (props sharing the same tag set; see get-room-prop-groups). For PLACING content prefer get-room-prop-groups: it returns these same props already grouped, and paste-resources-into-prop-group spreads content over a group for you. Props are returned in the room's NAVIGATION ORDER and each carries navIndex (0-based position): normally that is the props-group order the room stores, but when the room's settings select a storyline to override Next/Previous navigation, THAT storyline's frame order is the source of truth for prop order — props the storyline never visits come last with navIndex: null.

Availability: AI, Developer

ParameterTypeRequiredDescription
roomIdstringYesThe unique room identifier.
networkIdstringNoNetwork ID the room belongs to.

get-prop ​

Returns details for a single prop by ID (name, assetTitle, type, thumbnailCount, isPresentationBoard, contentCount, assetId, navIndex — the prop's 0-based position in the room's navigation order, null when a Next/Previous storyline override never visits it — and the ready-made entity link tag — same fields as get-room-props) with no navigation or UI side effects. Use this to read prop data. Only use preview-prop when the user explicitly asks to show, open, or navigate to a prop.

Availability: AI, Developer

ParameterTypeRequiredDescription
propIdstringYesThe unique prop identifier.
roomIdstringYesThe room the prop belongs to.
networkIdstringNoNetwork ID the room belongs to.

list-prop-team-members ​

Lists all team member invitations for a prop in a room. Returns an array of invitation records, each containing the invited user's ID, their permissions (view/comment/contribute/edit/manage), and any stored custom metadata. Agent assignments are stored id-only as customParams.agentInfo.id (string). Older rows may still carry the full snapshot customParams.agentInfo: { id, name, description, avatarUrl } — only id is read; everything else is resolved from the live agent.

Availability: AI, Developer

ParameterTypeRequiredDescription
roomIdstringYesThe room the prop belongs to.
propIdstringYesThe prop whose team members to list.

invite-to-prop ​

Adds a user to a prop's team, or updates an existing team member's permissions and metadata. When called for a user already in the team this acts as an update — the invitation is replaced with the new permissions and customParams. Use list-prop-team-members first to check current membership before inviting.

Availability: AI, Developer

ParameterTypeRequiredDescription
roomIdstringYesThe room the prop belongs to.
propIdstringYesThe prop to invite the user to.
invitedUserstringYesUser ID of the person to invite or update.
permissionsobjectNoPermission flags for the team member: { view: boolean, comment: boolean, contribute: boolean, edit: boolean, manage: boolean }. Defaults to view-only (view: true, all others false) when omitted.
customParamsobjectNoArbitrary metadata stored on the invitation. To assign an AI agent to this team member, pass customParams: { agentInfo: { id: "<agent-id>", avatarResourceId: "<picked-3d-avatar-resource-id>" | null } } (id-only — do NOT include name/description/avatarUrl, those are resolved from the live agent). avatarResourceId is the team member's picked 3D avatar for this prop, or null when nothing has been picked — readers fall back to the user's own 3D profile avatar in that case. Pass customParams: null to clear a previously assigned agent. The full-snapshot shape agentInfo: { id, name, description, avatarUrl } is still read for backwards compatibility but only id is used.

delete-prop-invitation ​

Removes a user from a prop's team by deleting their invitation. Use list-prop-team-members first to confirm the user is currently a team member.

Availability: AI, Developer

ParameterTypeRequiredDescription
roomIdstringYesThe room the prop belongs to.
propIdstringYesThe prop to remove the user from.
invitedUserstringYesUser ID of the team member to remove.

list-room-templates ​

Lists the room templates the AI is allowed to build from: ONLY templates tagged both "community" and "ai-friendly" are returned — every other template is skipped by design, never look for or suggest one (filteredOutCount says how many of the page were skipped). Each template has an id, name, tags (e.g. "office", "gallery", "community"), price in USD (0 or missing = free; paid templates CAN be created too — the room then has to be purchased by the user within 15 minutes, see create-room-from-template), subscriptionStatus, and groupCount — the number of prop groups (tagged sections of frames) the template's room contains, read from a tag of the form "prop-groups_N" (e.g. prop-groups_5; null when the template carries no such tag). Choose a template by groupCount: prefer the one equal to the number of content sections the user has, else the smallest larger one; a template with more groups than sections leaves the extra groups on their placeholders, one with fewer forces sections to be merged — say so when you propose it. Supports text search and server-side tag filtering with pagination. Use this before create-room-from-template to find a template id, its groupCount and its price.

Availability: AI, Developer

ParameterTypeRequiredDescription
querystringNoSearch query to filter templates by name.
tagsstring[]NoFilter templates by tags (server-side), e.g. ["community"].
offsetnumberNoPagination offset. Defaults to 0.
sizenumberNoNumber of results to return. Defaults to 20.

create-room-from-template ​

Creates a new 3D room in the current network from a room template — FREE or PAID. The tool looks the template up in the AI-approved list itself and uses the listed price (pass price too when you have it; it is the fallback if the lookup fails). For a paid template the room is created immediately with a one-time-payment plan and the platform keeps it only if the user completes the purchase within 15 minutes; this tool never pays anything. Returns { roomId, name, networkId, tag, price, isFree, paymentRequired } for the NEW room plus, when paymentRequired is true, paymentWindowMinutes (15) and paymentInstructions. When paymentRequired is true you MUST tell the user right away: the price, that the room is temporary until it is bought within 15 minutes, and how to pay (Valu web app -> Rooms -> open the new room -> "Pay for Room"); never claim it is paid. Creating the room and linking to it are two separate steps: to link, paste the returned tag (@[room:networkId/roomId|Name]) VERBATIM — never rebuild it from ids, never reuse a roomId from an earlier call or a template id, and never guess the networkId. Use list-room-templates first to find the template id and its price.

Availability: AI, Developer

ParameterTypeRequiredDescription
templateIdstringYesThe room template id (from list-room-templates).
roomNamestringYesName for the new room.
pricenumberNoThe template's price in USD as list-room-templates returned it (0 = free). Optional: the tool resolves the price from the approved list itself and only falls back to this value when the template cannot be found there. A price above 0 creates a PAID room that the user must purchase within 15 minutes to keep.

paste-resources-into-prop ​

Places one or more existing CMS resources into a prop in a room. Resources are link-copied (the originals stay in their current folder) and added to the prop's content list. IDEMPOTENT: a resource already on the prop (itself, or as a link copy) is skipped and listed in skippedAlreadyPresent — so repeating a paste after a timeout can never duplicate content; when everything was already there the result carries alreadyPresent=true and nothing is changed. Template placeholder resources still sitting on the prop (from the room template) are removed first so they never mix with the user's content (removedTemplateStubs in the result lists them; set removeTemplateStubs=false to keep them). When the paste leaves more than one resource on a non-container prop, the tool automatically enables the prop's auto content slider so the items cycle as a slideshow (result field sliderEnabled reports it; sliderError appears if the paste succeeded but the slider toggle failed). The tool also CLEARS the prop's title (content props carry no caption — a section's name lives on its sign; titleCleared reports it, titleClearError if that save failed). Use this tool ONLY when the user named exactly one prop. When the target is a GROUP — a row of frames, a tagged section, several props — call paste-resources-into-prop-group instead: it spreads the content across the group's props in navigation order itself, so never hand-split content into per-prop calls. The prop must support content — check via get-room-props that its type array is non-empty and isPresentationBoard is false: presentation (screen-share) boards are rejected, they are reserved for live screen sharing. Prefer props with thumbnailCount > 0 (picture frames / display canvases). Use service__CMS__resource_search to find resource ids first. Returns the paste result plus name and tag read back AFTER the paste, so they name what the prop now shows (its first resource) — paste that tag verbatim when linking to the prop.

Availability: AI, Developer

ParameterTypeRequiredDescription
roomIdstringYesThe room the prop belongs to.
propIdstringYesThe prop to place the resources into.
resourceIdsstring[]YesCMS resource ids to place into the prop, in display order.
appendToListEndbooleanNoWhen true (default) new resources are appended to the end of the prop's content list; when false they are inserted at the front.
removeTemplateStubsbooleanNoWhen true (default) placeholder resources the prop inherited from the room template are removed before pasting. Pass false only when the user explicitly wants to keep the template content.
networkIdstringNoNetwork ID the room belongs to. Defaults to the current network.

get-room-prop-groups ​

Lists a room's props ALREADY GROUPED by their tag set, in the room's navigation order — use this (not get-room-props) whenever content is to be placed. Returns { roomId, networkId, propOrder, groupIds, groups } — groupIds is the ordered list of every group id, read it first. A group is the set of props whose normalized tags (lowercase, spaces -> "-") are identical; its id is those tags sorted and joined with "+" (e.g. "building1+floor0+team"), so multi-tag rooms yield one group per tag combination ("building1+floor0+team" and "building1+floor1+team" are different groups). A SINGLE tagged prop is a group of one — the lone "logo" frame is the group "logo". Props WITHOUT tags belong to no group and are skipped entirely (never listed, never filled). Each group carries id, tags, label, isLogoGroup (true when the tags include "logo": every logo frame shows EVERY logo, so paste-resources-into-prop-group replicates there by default), navIndex (the group's first position in the room's walk; null = outside it), propCount, eligiblePropCount (props that can take content), decorativePropCount (props with no content type — walls, plants, signs — counted but NOT listed), totalContentCount, labels — the section's SIGNS: Text props (recognised by an asset tag containing "Text", or as a titled prop with no content type) whose title is the text shown in the room, members of the group because they carry its tags (an untagged sign is invisible to these tools); each { propId, text } — and props — only the props that can hold content (presentation boards included, flagged), each as a compact entry: id, name (what the prop SHOWS: its own title, else the title of its FIRST resource, else the asset's catalog name, else the bare id when nothing names it — an id-only name means an empty, unnamed frame), assetTitle, type, thumbnailCount, logoCount, invokeType, isPresentationBoard, acceptsContent (true = type non-empty and not a presentation board), contentCount, navIndex, tag. Match the user's words against group tags/label first ("the team wall on floor 0" -> tags contain team and floor0), then against prop name/assetTitle when they mean one exact prop. Pass group ids to paste-resources-into-prop-group; when the user's content is coarser than the groups ("team" over per-floor team groups) pass every group whose tags contain the facet. The ready-made tag on each prop is pasted verbatim when linking to it — never assemble one. propOrder says where the order came from ({ source: "storyline" | "props-group", storylineId?, storylineTitle? }).

Availability: AI, Developer

ParameterTypeRequiredDescription
roomIdstringYesThe unique room identifier.
networkIdstringNoNetwork ID the room belongs to.

paste-resources-into-prop-group ​

Spreads existing CMS resources across the props of one or more prop GROUPS (ids from get-room-prop-groups), in the room's navigation order, as contiguous, order-preserving shares — one slideshow per prop. The tool does ALL the chunking (7 resources over 3 frames -> 3/2/2; 2 over 5 -> the first two frames get one each), so call it ONCE per content group with all of that group's resources — never once per prop, and never split the resources yourself. Pass several groupIds when the content is coarser than the room's groups (e.g. "team" photos over "building1+floor0+team" and "building1+floor1+team"); their props are pooled in walk order. Frames that still show only their template placeholder come FIRST (lowest navIndex first), frames that already hold user content come after — so a later top-up fills the empty slots before joining existing slideshows; each placement reports hadUserContent (true/false, null when the prop's content could not be read). distribution: "spread" (default — contiguous shares), "stack" (everything onto the first eligible prop as one slideshow — only when the user explicitly asked for a single slideshow) or "replicate" (EVERY resource onto EVERY eligible prop — the default when every selected group is a LOGO group, isLogoGroup true, so all logos show on all logo frames; never spread logos unless the user asks). Presentation boards are skipped automatically and listed in skippedProps; decorative members (walls, signs) are never candidates. Per prop this behaves exactly like paste-resources-into-prop: resources are link-copied (originals stay), a resource already on the prop (itself or as a link copy) is skipped rather than duplicated (per placement and top-level skippedAlreadyPresent — a repeat after a timeout is safe), template placeholder stubs are removed first, the auto content slider is enabled when a prop ends up with more than one item, and titles are cleared on EVERY content prop of the selected groups — the pasted ones and the untouched ones alike (content props carry no caption; the section's name lives on its sign; clearedTitlePropIds lists them, titleClearErrors any that failed). Returns { roomId, groupIds, distribution, placements: [{ groupId, propId, name, tag, navIndex, hadUserContent, resourceIds, addedResourceIds, failed, removedTemplateStubs, sliderEnabled, titleCleared, sliderError?, titleClearError?, stubCleanupError?, error? }], clearedTitlePropIds, titleClearErrors?, unplacedResourceIds (resources that landed on no prop at all), eligiblePropCount, skippedProps } — each placement's name and tag are read back AFTER the paste, so they name what the prop now shows (its first resource), not the empty frame it was. It throws only when nothing could be attempted: an unknown group id (the message lists the valid ids), no eligible prop in the selected groups, or empty input. Report failed/unplaced items honestly; paste each placement's tag verbatim when linking. Use paste-resources-into-prop only when the user named exactly one prop.

Availability: AI, Developer

ParameterTypeRequiredDescription
roomIdstringYesThe room the groups belong to.
groupIdsstring[]YesOne or more prop group ids from get-room-prop-groups (e.g. ["building1+floor0+team"]). Several ids pool their props into one navigation-ordered row.
resourceIdsstring[]YesCMS resource ids to place, in display order. The tool splits them across the props itself.
distributionstringNo"spread": contiguous, order-preserving shares across the eligible props in navigation order (default for every group except logo groups). "stack": everything onto the first eligible prop as a single slideshow — only when the user asked for one. "replicate": every resource onto every eligible prop (default for a logo group). Omit to get the default for the selected groups.
appendToListEndbooleanNoWhen true (default) new resources are appended to the end of each prop's content list; when false they are inserted at the front.
removeTemplateStubsbooleanNoWhen true (default) placeholder resources a prop inherited from the room template are removed before pasting. Pass false only when the user explicitly wants to keep the template content.
networkIdstringNoNetwork ID the room belongs to. Defaults to the current network.

rename-prop-group ​

Gives a prop GROUP a display name by retitling its section SIGNS — the group's labels from get-room-prop-groups, i.e. the tagged Text props that show the section name in the room. Content props (frames, boards) are never touched: they carry no title at all (pasting clears any they had), the name lives on the sign. Use it in the guided build once the section's name is settled (listed by the user up front, self-evident from the tag, or confirmed from your proposal — or chosen by you when the user asked you to decide everything). The group id itself comes from tags and does not change. Returns { roomId, groupId, name, hasLabels, renamedLabelPropIds, failed } — hasLabels false means the group has no sign, so there was nothing to rename (say so); renamedLabelPropIds are the signs that now show the name; failed lists signs that could not be saved. Never rename a group the user did not name or ask you to name.

Availability: AI, Developer

ParameterTypeRequiredDescription
roomIdstringYesThe room the group belongs to.
groupIdstringYesThe prop group id from get-room-prop-groups (e.g. "team" or "building1+floor0+team").
namestringYesThe display name for the section; becomes the text of the group's signs.
networkIdstringNoNetwork ID the room belongs to. Defaults to the current network.

Text Chat Service (TextChat) ​

Headless text-chat I/O for non-UI callers (agents, sub-agents, scripts). Read channel history and send messages without opening the TextChat application or changing the active channel. Encryption and decryption are handled automatically.

Source: src/Services/TextChat/TextChatService.js

get-channel-history ​

Fetches the most recent messages for a text-chat channel by channelId, decrypted and ready to read. Returns a plain list of messages with authorId, body, timestamp, and messageType. Does not open any UI or change the active channel.

Availability: Developer

ParameterTypeRequiredDescription
channelIdstringYesThe text-chat channel ID to load messages from.
limitnumberNoMaximum number of messages to return. Defaults to 20.
beforeMessageIdstringNoLoad messages older than this messageId (for paginating backwards).
afterMessageIdstringNoLoad messages newer than this messageId (for paginating forwards).

send-message ​

Sends a text message to a text-chat channel. You must provide EITHER a channelId (preferred when you already have one) OR a userId (for a direct message — the service resolves the direct channel automatically). Silent — does NOT open the TextChat application, does NOT change the active channel, does NOT affect any UI. Encryption is handled automatically if the channel is encrypted.

Availability: Developer

ParameterTypeRequiredDescription
textstringYesThe message body to send.
channelIdstringNoTarget channel ID. Use this when you already know the channel (e.g. from a platform event). Takes precedence over userId.
userIdstringNoTarget user ID for a direct message. The service resolves the direct channel by calling channel:getDirectChannel under the hood. Ignored if channelId is also provided.
buttonsobject[]NoOptional interactive buttons rendered below the message body. Pass a real JSON array (NOT a JSON-stringified array). Each entry MUST be an object with this exact NESTED shape: {text: string, intent: {applicationId: string, action: string, params?: object}}. Do NOT flatten applicationId/action onto the button itself — intent is a sub-object. text is the visible label. Clicking dispatches intent via Application.run on the recipient's client (use an applicationId + action the recipient's app exposes — see other service manifests for valid pairs). Entries that are malformed are repaired-or-dropped by the service and reported back in buttonWarnings; check that field on the response and use the canonical shape going forward. Example: [{"text":"Open profile","intent":{"applicationId":"valuguru","action":"open-agent","params":{"agentId":"agent_xxx"}}}].
customParamsobjectNoOptional message customParams. Only the key open-thread is accepted (any other key is dropped by the service). Pass {"open-thread": true} ONLY when the recipient explicitly expects your outreach (e.g. you are responding to their team-member avatar click) — it force-opens the chat thread on their screen, which is invasive.

message-owner ​

Delivers a message authored by the AI agent itself (NOT by the logged-in user) into a user's dedicated agent-to-user channel, resolved from source userAIAgent:{userId}:{agentId}. The recipient sees the agent as the author and the channel is created on first use. This is the INVASIVE owner-notification channel: use it to ping/notify the owner (pass the owner's userId) — or, occasionally, any other user. Unlike send-message (which sends as the logged-in user), this is authored by the agent. Silent toward the UI — does NOT open the TextChat application or change the active channel.

Availability: AI

ParameterTypeRequiredDescription
userIdstringYesRecipient user ID. The user who will receive the message in their agent channel.
agentIdstringYesThe calling agent's own ID. Used to address the dedicated userAIAgent:{userId}:{agentId} channel so the message is authored by this agent.
textstringYesThe message body to send.
buttonsobject[]NoOptional interactive buttons rendered below the message body. Pass a real JSON array (NOT a JSON-stringified array). Each entry MUST be an object with this exact NESTED shape: {text: string, intent: {applicationId: string, action: string, params?: object}}. Do NOT flatten applicationId/action onto the button itself — intent is a sub-object. text is the visible label. Clicking dispatches intent via Application.run on the recipient's client (use an applicationId + action the recipient's app exposes — see other service manifests for valid pairs). Entries that are malformed are repaired-or-dropped by the service and reported back in buttonWarnings; check that field on the response and use the canonical shape going forward. Example: [{"text":"Open profile","intent":{"applicationId":"valuguru","action":"open-agent","params":{"agentId":"agent_xxx"}}}].
customParamsobjectNoOptional message customParams. Only the key open-thread is accepted (any other key is dropped by the service). Pass {"open-thread": true} ONLY when the recipient explicitly expects your outreach (e.g. you are responding to their team-member avatar click) — it force-opens the chat thread on their screen, which is invasive.

Time Service (Time) ​

Returns the current user's local clock context — local ISO with offset, UTC ISO for the same instant, IANA timezone, offset in minutes, day-of-week, and resolved locale. Use this before any "today"/"tomorrow"/"now" reasoning or when converting natural-language times to ISO strings.

Source: src/Services/Time/TimeService.js

get-local-time ​

Returns an object describing the user's current local time: { iso: local ISO 8601 with offset (e.g. "2026-05-28T13:45:30.000+02:00"), utcIso: same instant in UTC (e.g. "2026-05-28T11:45:30.000Z"), timezone: IANA name (e.g. "Europe/Berlin"), offsetMinutes: integer minutes ahead of UTC (e.g. 120), dayOfWeek: long English day name (e.g. "Thursday"), localDate: "YYYY-MM-DD" in local time, localTime: "HH:MM" in local time, locale: resolved BCP 47 locale (e.g. "en-US") }. Takes no parameters.

Availability: Developer

No parameters.

Users Service (Users) ​

User management service for getting current user info, looking up users by ID, searching contacts/followers/following, and managing connection requests.

Source: src/Services/Users/UsersService.js

current ​

Returns the currently authenticated user info (id, firstName, lastName, etc.).

Availability: AI, Developer

No parameters.

get ​

Retrieves a user by their unique ID. Returns user object with id, firstName, lastName, etc.

Availability: AI, Developer

ParameterTypeRequiredDescription
userIdstringYesThe unique user identifier.

search-users ​

Search for users within existing connections (contacts, followers, or following). Use this to find a user ID when you only know their name and they are already in your network. To discover new users outside your network, use find-user instead.

Availability: AI, Developer

ParameterTypeRequiredDescription
filterstringYesUser filter. Must be one of: "contacts" — current user's friends/connections; "followers" — users who follow the current user; "following" — users the current user follows.
querystringNoSearch query to filter users by name.
offsetnumberNoPagination offset. Defaults to 0.
sizenumberNoNumber of results to return. Defaults to 10.

find-user ​

Discover new users to connect with by searching by name. Uses a suggestion engine — distinct from search-users which searches within existing connections.

Availability: AI, Developer

ParameterTypeRequiredDescription
querystringNoSearch query to filter users by name.
offsetnumberNoPagination offset. Defaults to 0.
sizenumberNoNumber of results to return. Defaults to 10.

send-connection-request ​

Sends a connection request to a user by their ID.

Availability: AI, Developer

ParameterTypeRequiredDescription
userIdstringYesThe unique identifier of the user to send a connection request to.

accept-connection-request ​

Accepts a pending connection request from a user.

Availability: AI, Developer

ParameterTypeRequiredDescription
userIdstringYesThe unique identifier of the user whose connection request to accept.

decline-connection-request ​

Declines a pending connection request from a user.

Availability: AI, Developer

ParameterTypeRequiredDescription
userIdstringYesThe unique identifier of the user whose connection request to decline.

cancel-connection-request ​

Cancels a pending connection request that the current user previously sent.

Availability: AI, Developer

ParameterTypeRequiredDescription
userIdstringYesThe unique identifier of the user to whom the connection request was sent.

Valu Guru Service (AiGuru) ​

System service for managing applications via AI. Provides tools to open, close, list, and check application status.

Source: src/Services/AiGuru/AiGuruService.js

open ​

Opens (loads) an application by its ID into the dock.

Availability: none (platform-internal)

ParameterTypeRequiredDescription
applicationIdstringYesThe unique identifier of the application to open.

close ​

Closes (unloads) an application by its ID from the dock.

Availability: none (platform-internal)

ParameterTypeRequiredDescription
applicationIdstringYesThe unique identifier of the application to close.

has-application ​

Checks whether an application with the given ID exists in the registry.

Availability: none (platform-internal)

ParameterTypeRequiredDescription
applicationIdstringYesThe unique identifier of the application to check.

get-applications ​

Returns a list of all registered applications with their id, slug, icon, and title.

Availability: none (platform-internal)

No parameters.

is-application-loaded ​

Checks whether an application with the given ID is currently loaded (open) in the dock.

Availability: none (platform-internal)

ParameterTypeRequiredDescription
applicationIdstringYesThe unique identifier of the application to check.

get-chat-history ​

Returns the in-memory message history for a chat session. Omit chatId to get the currently active session.

Availability: Developer

ParameterTypeRequiredDescription
chatIdstringNoID of the chat session. Omit to use the currently active session.

get-agent-history ​

Returns the in-memory message history for a background agent.

Availability: Developer

ParameterTypeRequiredDescription
agentIdstringYesID of the background agent whose message history to retrieve.

query-knowledge-base ​

Queries the RAG knowledge base directly over the Valu Guru server's socket connection, bypassing chat entirely. Returns the raw tool result text.

Availability: Developer

ParameterTypeRequiredDescription
querystringYesThe search query text.
toolNamestringNoName of the RAG tool to call. Only needed if the RAG server exposes more than one tool — omit to auto-pick the sole registered tool.
argsobjectNoExtra arguments merged into the RAG tool call alongside query (tool-specific, e.g. scope filters).

Verus Wallet Service (VerusWallet) ​

Executes on-chain transfers from an AI agent's attached Verus wallet identity. Every call takes an agentId — the client resolves which wallet is attached to that agent. Returns an error if the agent has no wallet attached or the wallet has not finished being provisioned on-chain.

Source: src/Services/AiGuru/VerusWalletService.js

transfer ​

Send currency from the agent's attached Verus wallet to a destination address or identity. Call this when the user or agent needs to move funds out of an agent wallet. Fails if the agent has no wallet attached, or if the wallet is still pending creation.

Availability: AI, Developer

ParameterTypeRequiredDescription
agentIdstringYesID of the AI agent performing the transfer. The service looks up which wallet identity is attached to this agent — NEVER pass a wallet ID or i-address here.
destinationstringYesRecipient address, i-address, or Verus identity (e.g. "alice@").
amountnumberYesAmount to send (positive number). Interpreted in the selected currency — defaults to VRSC when currency is omitted.
currencystringNoCurrency ticker or identity (e.g. "VRSC", "VRSC-BTC"). Defaults to the native chain currency.
memostringNoOptional memo attached to the transaction.

get-balance ​

Return the last-known balance of the wallet attached to the specified agent. Reads from the client cache — call verus:getAgentsBalance (via AiGuruStore.refreshAgentBalances) for a fresh value.

Availability: AI, Developer

ParameterTypeRequiredDescription
agentIdstringYesID of the AI agent whose wallet balance should be returned.