Users & organization
user_create
Provision a new user in this tenant. Link-based onboarding: an invite / set-password link is emailed to the user — no password is ever returned over the API. Sets tenant, workspace and role and adds them to the General department. Rejects duplicate emails and enforces the tenant user limit.
Returns:
{ user, invite_sent:true, note, warning? }. user is the linked row (id, email, name, role, global_role, position, is_active, auth_uid). No password is ever returned; a set-password link is emailed. warning appears only if the auto General-department membership step failed.
Permissions: write; Company-Admin only.
department_list
List the tenant’s departments (id, name, slug). Call before setting an agent’s department_id — pass a listed id, never invent one.
Parameters: none.
Returns: { departments: [{id, name, slug}], count, note }.
Permissions: read.
category_list
List the category options (id, slug, name) for one entity type. Call before setting a category on memory_save / knowledge_save / skill_save — use a listed slug/name.
Returns:
{ entity, categories: [{id, slug, name}], count }.
Permissions: read.
grantable_list
The agent toolbox: every name valid in an agent’s tools_access[] (the capability grant list). Returns data tools (query_/update_ on catalog tables), the tenant’s registered MCP servers (mcp:<id>), vertical tools the user already has, and built-in control tools. composio:<TOOLKIT|ACTION> names from the user’s connections are also valid. Grant only from what exists here — never invent a tool string.
Parameters: none.
Returns: { grantable: [...], count, note }. Each entry is {name, label, kind} where kind is data (query_/update_ tools), mcp_server (mcp:<id> grants), federated (vertical tools), or control (built-in). Control entries also carry display_name, description, category, audience. composio:<TOOLKIT|ACTION> names are valid too but sourced from the user’s Connections, not listed here.
Permissions: read.
Governance
guardrails_get
The always-load governance rules (the “Operating Manual” layer) this caller is expected to honor: knowledge entries flagged always-load or with importance ≥ 8, currently valid, non-archived — the exact set that agent runs and the in-app chat inject automatically. MCP clients do not get this injected (pull-only): call once at session start and keep the rules in context. Full text via knowledge_get.
Returns:
{ guardrails: [...], count, note } — same lean columns as knowledge_search rows (id, title, intro, category, importance, tags, scope, …), ordered by importance. Fetch full text via knowledge_get.
Permissions: read; rights-scoped.
self_learning_enable
Provision (or disable) the Company-Brain self-learning harness for this tenant from built-in templates: one Brain Keeper (nightly learning sweep) + one Department Summarizer per department with data (weekly knowledge digest), including schedules and review flags. Idempotent — existing template agents are skipped, never duplicated. enabled:false is a reversible disable (schedules off, agents deactivated — never deletes).
Returns:
{ ok, agents, tenant_defaults, estimated_weekly_budget_usd, notes }. agents is a per-agent receipt ({action: "created"|"reactivated"|"skipped_exists"|"failed", agent_id?, template_id, reason?}); tenant_defaults reports the defaults upsert action; notes is a human-readable summary array. ok is true only when no agent failed and the defaults upsert succeeded.
Permissions: write; Company-Admin only.
Credits & operations
credit_log_list
Recent credit movements (kind, amount, balance before/after) for this workspace.
Returns:
{ credit_logs: [{id, amount, kind, reference, balance_before, balance_after, created_at, user_id}], count }.
Permissions: read.
failed_import_list
Recent failed data imports (source, type, error) for this workspace.
Returns:
{ failed_imports: [{id, source, type, external_id, note, error, received_at}], count }.
Permissions: read.
Platform pricing (Superadmin)
These tools operate platform-level pricing and are rejected for anyone who is not a Superadmin, regardless of scopes.pricing_config_get
Read the platform pricing config: plan limits (per plan key: price USD, included credits, max agents, max departments, billing price id) and top-up packages (per slug: price USD, credits, active).
Parameters: none.
Returns: { plan_limits: [{plan_key, price_usd, included_credits, max_agents, max_departments, updated_at}], topup_packages: [{slug, price_usd, credits, active, stripe_price_id}] }.
Permissions: read; Superadmin only.
pricing_config_update
Update one pricing row (partial; only supplied fields change). kind:'plan' patches a plan by plan_key; kind:'topup' patches a top-up package by slug. The billing price id is read-only.
Returns:
{ ok:true, kind, plan_key | slug, updated } — updated lists the field names actually patched. Nothing to change or a bad field → { error }.
Permissions: write; Superadmin only.
provider_ledger_get
Read the provider margin ledger (Merchant-of-Record accounting for white-label providers). Without arguments: every provider with its outstanding balance plus the total owed. With provider_id: that provider’s balance, total earned, total paid out, credits sold and the 20 most recent bookings. Read-only — payouts are booked in the app.
Returns: without
provider_id → { providers: [{provider_id, name, balance_usd}], total_owed_usd }. With provider_id → { provider_id, ...summary } where summary carries the provider’s balance, total earned, total paid out, credits sold and the 20 most recent bookings.
Permissions: read; Superadmin only.