> **Building with AI coding agents?** Install the authstack plugin with one command. This equips your agent with accurate Scalekit implementation patterns. > > **Recommended**: > ```bash > npx @scalekit-inc/cli setup > ``` > > Global: > ```bash > npm install -g @scalekit-inc/cli > scalekit setup > ``` > > Supports Claude Code, Cursor, GitHub Copilot, Codex + skills for other Agent Skills-compatible agents. > Skills: integrate-agentkit, implement-saaskit, add-mcp-oauth, implement-sso, implement-scim. > [Full setup guide](https://docs.scalekit.com/dev-kit/build-with-ai/) --- # Connect AI agents to Butterbase The Butterbase connector lets your AI agent act in each user's Butterbase account. Each user connects their own Butterbase access token once, and Scalekit sends it with every call, so your agent never handles credentials. It comes with 210 tools. **Authentication:** Bearer Token **Categories:** Developer Tools, Databases **Tools:** 210: 92 read, 96 write, 22 destructive **Users sign in with:** Access token **Built by:** Scalekit connector **Try it:** [Playground in the Scalekit dashboard](https://app.scalekit.com/ws/signup?sk_intent=playground&provider=BUTTERBASE) ## Setup 1. ### Install the SDK **Node.js** ```bash npm install @scalekit-sdk/node dotenv ``` **Python** ```bash pip install scalekit-sdk-python python-dotenv ``` 2. ### Set your credentials Add your Scalekit credentials to your `.env` file. Find values in **[app.scalekit.com](https://app.scalekit.com)** > **Developers** > **API Credentials**. ```sh title=".env" SCALEKIT_ENVIRONMENT_URL= SCALEKIT_CLIENT_ID= SCALEKIT_CLIENT_SECRET= ``` 3. ### Create the Butterbase connection In **AgentKit > Connections**, create a Butterbase connection. The name you give it is the `connection_name` your code passes. See [Configure connections](/agentkit/connections/). 4. ### Authorize a user and make your first call **Node.js** (`quickstart.mts`) ```typescript import { ScalekitClient } from '@scalekit-sdk/node' import 'dotenv/config' import { createInterface } from 'node:readline/promises' const scalekit = new ScalekitClient( process.env.SCALEKIT_ENVIRONMENT_URL, process.env.SCALEKIT_CLIENT_ID, process.env.SCALEKIT_CLIENT_SECRET, ) const actions = scalekit.actions const connector = 'butterbase' const identifier = 'user_123' // Generate an authorization link for the user const { link } = await actions.getAuthorizationLink({ connectionName: connector, identifier }) console.log('Authorize Butterbase:', link) const rl = createInterface({ input: process.stdin, output: process.stdout }) await rl.question('Press Enter after authorizing...') rl.close() // Make your first call const result = await actions.executeTool({ connector, identifier, toolName: 'butterbase_apps_list', toolInput: {}, }) console.log(result) ``` ```bash npx tsx quickstart.mts ``` **Python** (`quickstart.py`) ```python import os from scalekit import ScalekitClient from dotenv import load_dotenv load_dotenv() scalekit_client = ScalekitClient( env_url=os.getenv("SCALEKIT_ENVIRONMENT_URL"), client_id=os.getenv("SCALEKIT_CLIENT_ID"), client_secret=os.getenv("SCALEKIT_CLIENT_SECRET"), ) actions = scalekit_client.actions connection_name = "butterbase" identifier = "user_123" # Generate an authorization link for the user link_response = actions.get_authorization_link( connection_name=connection_name, identifier=identifier, ) print("Authorize Butterbase:", link_response.link) input("Press Enter after authorizing...") # Make your first call result = actions.execute_tool( tool_input={}, tool_name="butterbase_apps_list", connection_name=connection_name, identifier=identifier, ) print(result) ``` ```bash python quickstart.py ``` Each user opens the link once and enters their Butterbase credentials there. See [Authorize a user](/agentkit/tools/authorize/) for the full flow and statuses. ## Tools Pass the exact name to `execute_tool`, with an input like each tool's example. To ask for a tool that's missing, use the [request form](https://scalekitsupport.portal.usepylon.com/forms/request-a-connector-tool). **Node.js** ```typescript const result = await actions.executeTool({ toolName: 'butterbase_agent_get', toolInput: { app_id: '', name: 'Pro', }, connector: 'butterbase', identifier: 'user_123', }) ``` **Python** ```python result = actions.execute_tool( tool_name="butterbase_agent_get", tool_input={ "app_id": "", "name": "Pro", }, connection_name="butterbase", identifier="user_123", ) ``` `result.data` is the app's response as JSON, and `result.execution_id` (`executionId` in Node.js) is the ID of the call. ### `butterbase_agent_get` Get Agent · Read-only Get a single Butterbase agent's full configuration by name, including its model, graph_spec, visibility, and run limits. Returns the agent object as Butterbase stores it. Use butterbase_agent_get to inspect one specific agent. Use butterbase_agents_list to browse every agent in the app. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `app_id` (`string`, required): The Butterbase app's unique ID the agent belongs to. - `name` (`string`, required): The unique name of the agent to fetch, as given when it was created (or seen in a prior butterbase_agents_list response). Example input: `{"app_id":"","name":"Pro"}` ### `butterbase_agent_run_events_list` List Agent Run Events · Read-only Fetch every event recorded for an agent run as a single JSON array, instead of connecting to the run's live event stream. Returns an array of event objects covering the run's lifecycle — run_start, node_start, node_end, tool_call_start, tool_call_end, llm_token_usage, run_paused, run_cancelled, run_failed, and run_end. Use butterbase_agent_run_events_list to review a run's full event history at any point after it starts. Use butterbase_agent_run_get instead for just the run's current summary state. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `app_id` (`string`, required): The id of the Butterbase app the agent belongs to. - `id` (`string`, required): The id of the run whose events you want to fetch. - `name` (`string`, required): The unique name of the agent whose run's events you want to fetch. Example input: `{"app_id":"","id":"","name":"Pro"}` ### `butterbase_agent_run_get` Get Agent Run · Read-only Get a single agent run's full state by id. Returns the run object, including its status and, once available, its output. Use butterbase_agent_run_get to inspect or poll one specific run. Use butterbase_agent_runs_list to find its id first. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `app_id` (`string`, required): The Butterbase app's unique ID the agent belongs to. - `name` (`string`, required): The unique name of the agent the run belongs to. - `run_id` (`string`, required): The id of the run to fetch, as returned by butterbase_agent_run_create or a prior butterbase_agent_runs_list call. Example input: `{"app_id":"","name":"Pro","run_id":""}` ### `butterbase_agent_runs_list` List Agent Runs · Read-only List an agent's recent runs. Returns an array of run objects with each run's id and status; Butterbase's docs don't itemize further response fields or pagination parameters for this endpoint. Use butterbase_agent_runs_list to see recent activity for one agent. Use butterbase_agent_run_get to fetch one run's full state. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `app_id` (`string`, required): The Butterbase app's unique ID the agent belongs to. - `name` (`string`, required): The unique name of the agent whose runs to list. Example input: `{"app_id":"","name":"Pro"}` ### `butterbase_agents_list` List Agents · Read-only List all agents defined in a Butterbase app. Returns an array of agent objects, each with the agent's name, display name, description, default model, visibility, and run/budget limits. Use butterbase_agents_list to see which agents exist in an app before starting or configuring a run against one of them. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `app_id` (`string`, required): The Butterbase app ID whose agents you want to list. Found in the app's dashboard URL or via Butterbase's apps listing. Example input: `{"app_id":""}` ### `butterbase_ai_config_get` Get AI Config · Read-only Get an app's AI gateway configuration in Butterbase. Returns a config object with the app's default model, its maximum tokens allowed per request, and its list of allowed models. Use butterbase_ai_config_get to check an app's current AI settings before calling butterbase_ai_config_update to change them. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `app_id` (`string`, required): The id of the Butterbase app whose AI configuration to fetch. Example input: `{"app_id":""}` ### `butterbase_ai_models_list` List AI Models · Read-only List the AI models available and allowed for use by one Butterbase app. Returns a JSON array of model objects (exact fields are not published in Butterbase's docs). Use butterbase_ai_models_list to see which model identifiers are valid before calling butterbase_chat_completions_create or butterbase_embeddings_create. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `app_id` (`string`, required): The Butterbase app ID whose allowed AI models to list. Example input: `{"app_id":""}` ### `butterbase_ai_usage_get` Get AI Usage · Read-only Get AI usage and cost statistics for a Butterbase app, optionally scoped to a date range. Returns the total token count, total cost, and a per-model breakdown of tokens, cost, and request count. Use butterbase_ai_usage_get to monitor AI spend for an app over time, narrowing the results with a start and end date. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `app_id` (`string`, required): The id of the Butterbase app whose AI usage to fetch. - `end_date` (`string`, optional): End of the date range to report usage for, as YYYY-MM-DD. If omitted, usage is not bounded on the end date. - `start_date` (`string`, optional): Start of the date range to report usage for, as YYYY-MM-DD. If omitted, usage is not bounded on the start date. Example input: `{"app_id":""}` ### `butterbase_app_config_get` Get App Config · Read-only Get a Butterbase app's current access-mode and visibility configuration. Returns the app's configuration object, including its access mode (public or authenticated) and visibility settings. Use butterbase_app_config_get to read current settings before changing them with butterbase_app_access_mode_update or butterbase_app_visibility_update. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `app_id` (`string`, required): The ID of the app to read configuration for. Example input: `{"app_id":""}` ### `butterbase_app_migration_status_get` Get App Migration Status · Read-only Check the status of a Butterbase app's region-move migration. Returns the migration's current status and progress details; exact response fields beyond status are not published in Butterbase's docs. Use butterbase_app_migration_status_get after calling butterbase_app_move to track when the region move completes. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `app_id` (`string`, required): The ID of the app being moved. - `migration_id` (`string`, required): The migration ID returned by butterbase_app_move when the region move was started. Example input: `{"app_id":"","migration_id":""}` ### `butterbase_apps_list` List Apps · Read-only List every application owned by the authenticated Butterbase account. Returns an array of app objects (Butterbase's docs do not publish the exact per-app fields, such as id, name, and region). Use butterbase_apps_list to discover an app's id before calling any app-scoped tool; use butterbase_app_delete to remove one you no longer need. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: none. Example input: `{}` ### `butterbase_auth_audit_logs_list` List Auth Audit Logs · Read-only Query a Butterbase app's authentication audit log, optionally filtered by user or event type. Returns an array of audit log entries recording authentication activity such as signups, logins, and password resets (the exact per-entry fields are not published in Butterbase's docs). Use this to investigate suspicious activity, review a specific user's authentication history, or audit recent sign-in events for an app. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `app_id` (`string`, required): The unique identifier of the Butterbase app whose authentication audit log should be queried. - `event_type` (`string`, optional): Filter results to a single audit event type, e.g. login, signup, or password_reset. Valid values are not enumerated in Butterbase's docs, so pass the exact event type string used by your app. - `limit` (`integer`, optional): Maximum number of audit log entries to return. Butterbase's docs do not state a default or maximum, so pass a value appropriate for your use case. - `offset` (`integer`, optional): Number of audit log entries to skip before returning results, for paging through a large log. - `user_id` (`string`, optional): Filter results to audit events for one specific end user, by their Butterbase user ID. Example input: `{"app_id":""}` ### `butterbase_auth_jwks_get` Get Auth JWKS · Read-only Get the public JSON Web Key Set (JWKS) Butterbase uses to sign access tokens for a specific app, so tokens can be verified independently of the Butterbase API. Returns a standard JWKS object: an array of public keys under a "keys" field. Use butterbase_auth_jwks_get when you need to validate a Butterbase-issued JWT's signature yourself. Use butterbase_auth_me_get instead if you just want the profile behind a token. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `app_id` (`string`, required): The unique ID of the Butterbase app whose signing keys to fetch. Example input: `{"app_id":""}` ### `butterbase_auth_me_get` Get Current User · Read-only Get the profile of the end-user identified by the access token used to authenticate this call, for a specific Butterbase app. Returns the user's id, email, email-verification status, display name, and avatar URL. Use butterbase_auth_me_get to look up who a Butterbase session belongs to. Use butterbase_auth_login or butterbase_auth_signup first to obtain that session's token. CONFIRMED via a dedicated live investigation: the underlying Butterbase endpoint works correctly and returns a genuine success when called with a valid end-user access token (obtained via butterbase_auth_login) -- this was previously only ever tested with the wrong credential type (this connector's platform key), which always 401s. HOWEVER, this connector has no way to actually supply that end-user token: Scalekit's execution engine controls the Authorization header for a BEARER connection server-side and rejects a client-supplied Authorization header override outright (confirmed via direct SDK-level testing -- a custom header is rejected with its own 401 before ever reaching Butterbase). This tool will therefore always fail via the standard execution path on this connector, by platform design, not due to a fixable tool-JSON defect -- it would need a future Scalekit auth-strategy feature (e.g. a per-call token override) to ever work through this connector. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `app_id` (`string`, required): The unique ID of the Butterbase app to look up the current user in. Example input: `{"app_id":""}` ### `butterbase_auth_oauth_config_get` Get OAuth Provider Config · Read-only Get the configuration for one social-login (OAuth) provider set up on a Butterbase app. Returns the provider's configuration object, including its client ID, redirect URIs, and any provider metadata. Use butterbase_auth_oauth_config_get to inspect a single provider by name. Use butterbase_auth_oauth_configs_list to see all configured providers at once. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `app_id` (`string`, required): The unique ID of the Butterbase app the provider is configured on. - `provider` (`string`, required): The OAuth provider identifier to fetch, e.g. one of google, github, discord, facebook, linkedin, microsoft, apple, x, or a custom provider identifier. Example input: `{"app_id":"","provider":""}` ### `butterbase_auth_oauth_configs_list` List OAuth Provider Configs · Read-only List all social-login (OAuth) provider configurations set up for a Butterbase app. Returns an array of provider configuration objects, each with the provider name, client ID, and redirect URIs. Use butterbase_auth_oauth_configs_list to see every configured provider at once. Use butterbase_auth_oauth_config_get to fetch just one provider's configuration by name. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `app_id` (`string`, required): The unique ID of the Butterbase app whose OAuth provider configurations to list. Example input: `{"app_id":""}` ### `butterbase_billing_connect_status_get` Get Stripe Connect Status · Read-only Check the Stripe Connect onboarding status for a Butterbase app's monetization setup. Returns the app's current onboarding status details. Use butterbase_billing_connect_status_get to poll whether an app has finished Stripe Connect onboarding. Use butterbase_billing_connect_onboard to start or resume onboarding if it isn't complete. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `app_id` (`string`, required): The Butterbase app ID to check Stripe Connect onboarding status for, found in the app's dashboard URL or settings. Example input: `{"app_id":""}` ### `butterbase_billing_dashboard_get` Get Billing Dashboard · Read-only Get the current plan, usage, and limits for your Butterbase platform account as a whole, not a specific app. Returns the account's plan details, current usage metrics, and the limits attached to that plan. Use butterbase_billing_dashboard_get for a snapshot of the account's overall billing status. Use butterbase_billing_usage_get for a day-by-day usage history over a date range instead. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: none. Example input: `{}` ### `butterbase_billing_order_get` Get Order · Read-only Retrieve the details of a single order placed by an end user within a Butterbase app. Returns the order object with its line items, referenced product or plan, and payment status. Use butterbase_billing_order_get to look up one order by ID once you already have it, such as from an order confirmation, a list of the app's order history, or a Stripe webhook event. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `app_id` (`string`, required): The Butterbase app ID that owns the order, as shown in the app's dashboard URL or returned by the app-creation API. - `order_id` (`string`, required): The unique identifier of the order to retrieve, as returned when the order was created or listed in the app's order history. Example input: `{"app_id":"","order_id":""}` ### `butterbase_billing_orders_list` List Orders · Read-only List the current end user's order history for a Butterbase app. Returns an array of order objects for the current end user's past one-time-purchase products. Use butterbase_billing_orders_list to review what the current end user has already bought. Use butterbase_billing_purchase to place a new order, or butterbase_billing_products_list to see what's available to buy. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `app_id` (`string`, required): The unique ID of the Butterbase app to list the current end user's order history for. Example input: `{"app_id":""}` ### `butterbase_billing_plans_list` List Subscription Plans · Read-only List all subscription plans configured for a Butterbase app. Returns an array of plan objects, each with its id, name, price, billing interval, and included features. Use butterbase_billing_plans_list to browse an app's existing plans, find a plan_id for butterbase_billing_plan_update, or see which plans end users can subscribe to. Use butterbase_billing_subscription_get to check one end user's current subscription instead. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `app_id` (`string`, required): The unique ID of the Butterbase app whose subscription plans you want to list. Every Butterbase app has a distinct app_id, shown in the dashboard or returned when the app was created. Example input: `{"app_id":""}` ### `butterbase_billing_products_list` List Products · Read-only List all one-time-purchase products configured for a Butterbase app. Returns an array of product objects, each with its id, name, price, description, and metadata. Use butterbase_billing_products_list to browse an app's existing products or find a product_id for butterbase_billing_product_update or butterbase_billing_purchase. Use butterbase_billing_plans_list to see recurring subscription plans instead. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `app_id` (`string`, required): The unique ID of the Butterbase app whose one-time-purchase products you want to list. Every Butterbase app has a distinct app_id, shown in the dashboard or returned when the app was created. Example input: `{"app_id":""}` ### `butterbase_billing_subscription_get` Get Current Subscription · Read-only Get the current end user's active subscription for a Butterbase app. Returns the current subscription's details, such as the plan it's on and its status. Use butterbase_billing_subscription_get to check whether the current end user has an active subscription before gating access to a feature. Use butterbase_billing_subscribe to start one, or butterbase_billing_cancel to end it. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `app_id` (`string`, required): The unique ID of the Butterbase app to check the current end user's subscription for. Example input: `{"app_id":""}` ### `butterbase_billing_usage_get` Get Billing Usage History · Read-only Get daily usage history for the Butterbase platform account over a date range, optionally filtered to a single usage meter. Returns an array of daily usage data points covering the requested date range. Use butterbase_billing_usage_get to chart usage trends or check consumption against your plan's limits. Use butterbase_billing_dashboard_get for the current plan and limits snapshot instead. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `end_date` (`string`, required): End of the date range to fetch usage for, as an ISO 8601 date. Inclusive. - `start_date` (`string`, required): Start of the date range to fetch usage for, as an ISO 8601 date. Inclusive. - `meter_type` (`string`, optional): Limit results to a single usage meter: "storage_bytes" (file/storage usage), "ai_tokens" (AI gateway token consumption), "lambda_invocations" (serverless function calls), "bandwidth_bytes" (network egress), or "api_calls" (API request count). Omit to return all meters. CONFIRMED via live testing: api_calls was missing from this enum despite being a valid upstream value. One of: `storage_bytes`, `ai_tokens`, `lambda_invocations`, `bandwidth_bytes`, `api_calls`. Example input: `{"end_date":"","start_date":""}` ### `butterbase_clone_job_get` Get Clone Job Status · Read-only Check the status of a template clone job by its job id. Returns the clone job's current status and related details as reported by Butterbase (exact fields vary by job state and are not fully published in Butterbase's docs). Use butterbase_clone_job_get to poll a job started by butterbase_template_clone. Use butterbase_clone_job_retry if the job has failed. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `job_id` (`string`, required): The id of the clone job to check, as returned by butterbase_template_clone or butterbase_clone_job_retry. Example input: `{"job_id":""}` ### `butterbase_custom_domain_status_get` Get Custom Domain Status · Read-only Get a custom domain's current verification and SSL status for a Butterbase app. Returns the domain's verification status and SSL status as reported by Cloudflare. Use butterbase_custom_domain_status_get to poll progress after registering a domain with butterbase_custom_domain_create or after re-triggering a check with butterbase_custom_domain_verify. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `app_id` (`string`, required): The unique identifier of the Butterbase app the custom domain is registered to. - `id` (`string`, required): The unique identifier of the custom domain to check, as returned when the domain was registered. Example input: `{"app_id":"","id":""}` ### `butterbase_custom_domains_list` List Custom Domains · Read-only List custom domains registered for an app. Returns an array of domain objects, each with at least its id, hostname, verification status, and SSL status; the full field-by-field shape isn't published in Butterbase's docs. Use butterbase_custom_domains_list to see which domains are already registered for an app and their status. Use butterbase_custom_domain_create to add a new one. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `app_id` (`string`, required): The Butterbase app whose registered custom domains to list, exactly as shown in the Butterbase dashboard or returned when the app was created. Example input: `{"app_id":""}` ### `butterbase_frontend_deployment_get` Get Frontend Deployment · Read-only Get details and status of a specific frontend deployment. Returns the deployment record; Butterbase's docs don't publish its exact fields, but expect at least the deployment id and a status of WAITING, UPLOADING, BUILDING, READY, ERROR, or CANCELED. Use butterbase_frontend_deployment_get to check one deployment's progress or result. Use butterbase_frontend_deployments_list first if you don't already have the deployment id. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `app_id` (`string`, required): The Butterbase app that owns the frontend deployment, exactly as shown in the Butterbase dashboard or returned when the app was created. - `id` (`string`, required): The unique identifier of the frontend deployment to fetch, as returned when the deployment record was created or from butterbase_frontend_deployments_list. Example input: `{"app_id":"","id":""}` ### `butterbase_frontend_deployments_list` List Frontend Deployments · Read-only List an app's frontend deployment history. Returns an array of deployment records; Butterbase's docs don't publish the exact per-deployment fields, but each includes at least its id and status (WAITING, UPLOADING, BUILDING, READY, ERROR, or CANCELED). No pagination parameters are documented for this endpoint. Use butterbase_frontend_deployments_list to browse or review all deployments for an app. Use butterbase_frontend_deployment_get to fetch full details for one specific deployment by id. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `app_id` (`string`, required): The Butterbase app whose frontend deployment history to list, exactly as shown in the Butterbase dashboard or returned when the app was created. Example input: `{"app_id":""}` ### `butterbase_frontend_env_get` List Frontend Environment Variable Keys · Read-only List a frontend deployment's environment variable key names. Returns the variable key names only — Butterbase encrypts values at rest and never returns them through this or any other endpoint; the exact response shape (array vs. object of keys) isn't published in Butterbase's docs. Use butterbase_frontend_env_get to see which environment variables are already set before replacing them with butterbase_frontend_env_update. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `app_id` (`string`, required): The Butterbase app whose frontend deployment environment variable keys to list, exactly as shown in the Butterbase dashboard or returned when the app was created. Example input: `{"app_id":""}` ### `butterbase_function_get` Get Function · Read-only Get a deployed serverless function's stored configuration together with its current invocation metrics. Returns the function's settings (triggers, resource limits, agent-tool configuration) plus total invocations, error count, error rate, average duration, and last invocation time. Use butterbase_function_get to inspect one specific function by name. Use butterbase_functions_list to browse or find a function's exact name first. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `app_id` (`string`, required): The Butterbase application ID the function belongs to. - `name` (`string`, required): The exact name of the deployed function to retrieve. Example input: `{"app_id":"","name":"Pro"}` ### `butterbase_function_logs_list` List Function Logs · Read-only List historical invocation logs for a deployed Butterbase serverless function, optionally filtered by time, log level, or including soft-deleted functions. Returns an array of log entries, each with the invocation's HTTP method, path, status code, duration in milliseconds, memory used, any error, and the console log lines it produced. Use butterbase_function_logs_list to inspect a function's runtime behavior and diagnose failures. Use butterbase_function_get for the function's current configuration and aggregate metrics instead. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `app_id` (`string`, required): The Butterbase app ID that owns the function, found in the app's dashboard URL or settings. - `name` (`string`, required): The unique name of the deployed function whose logs you want to view. - `include_deleted` (`boolean`, optional): Whether to include log entries from functions that have since been soft-deleted. Defaults to false. Default: `false`. - `level` (`string`, optional): Filter log entries by level: "error" returns only invocations that errored, "all" returns every invocation. Omit to use the API's default. One of: `error`, `all`. - `limit` (`integer`, optional): Maximum number of log entries to return. Omit to use the API's default page size. - `since` (`string`, optional): Only return log entries recorded after this timestamp, as an ISO 8601 datetime. Omit to return the most recent logs regardless of time. Example input: `{"app_id":"","name":"Pro"}` ### `butterbase_functions_list` List Functions · Read-only List every serverless function deployed to an app. Returns an array of function objects with their names and configured settings. Use butterbase_functions_list to browse what's deployed or check whether a name is already taken. Use butterbase_function_get to fetch one function's full configuration and invocation metrics. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `app_id` (`string`, required): The Butterbase application ID whose functions should be listed. Example input: `{"app_id":""}` ### `butterbase_gateway_models_list` List Gateway Models · Read-only List the AI models available to your personal Butterbase gateway API key, in an OpenAI-compatible format. Returns an object with a data array of model entries, each with an id, object type, and display name. Use butterbase_gateway_models_list to see which models your own key can call through the gateway's chat and embeddings endpoints. Use butterbase_public_models_list for the full public catalog with pricing and context-window details. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: none. Example input: `{}` ### `butterbase_image_generation_get` Get Image Generation Job · Read-only Poll the status of a Butterbase AI image-generation job by its job id. Returns the job's status (pending, in_progress, completed, failed, cancelled, or expired) and, once the job is terminal, an array of content URLs for the generated images. Use butterbase_image_generation_get after butterbase_image_generation_create to check whether an image job has finished. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `app_id` (`string`, required): The id of the Butterbase app the image-generation job was submitted under. - `job_id` (`string`, required): The id of the image-generation job to check, as returned by butterbase_image_generation_create. Example input: `{"app_id":"","job_id":""}` ### `butterbase_integration_connections_list` List Integration Connections · Read-only List the third-party integration accounts currently connected for an end user of a Butterbase app. Returns the end user's connected integration accounts (exact response fields are not published in Butterbase's docs). Use butterbase_integration_connections_list to check what's already connected before calling butterbase_integration_connect. Use butterbase_integration_connection_delete to remove a connection you find here. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `app_id` (`string`, required): The Butterbase app ID whose integration connections to list. - `user_id` (`string`, optional): The end user whose connections to list. Butterbase's docs do not explicitly document a user-scoping parameter for this endpoint, but sibling endpoints in the Integrations API (connect, execute) require a userId field when authenticating with an API key rather than a JWT. Since this connector always authenticates with a platform API key, pass the end user's ID here so results are scoped to that user. Example input: `{"app_id":""}` ### `butterbase_integration_tools_list` List Integration Tools · Read-only List the tools exposed by an end user's currently connected third-party integrations for a Butterbase app. Returns the available tool definitions the user's connected accounts expose (exact response fields are not published in Butterbase's docs). Use butterbase_integration_tools_list to discover a toolName and its expected params, then call butterbase_integration_tool_execute to run it. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `app_id` (`string`, required): The Butterbase app ID whose connected-integration tools to list. - `user_id` (`string`, optional): The end user whose connected integrations to list tools for. Butterbase's docs do not explicitly document a user-scoping parameter for this endpoint, but sibling endpoints in the Integrations API (connect, execute) require a userId field when authenticating with an API key rather than a JWT. Since this connector always authenticates with a platform API key, pass the end user's ID here if your app has more than one end user. Example input: `{"app_id":""}` ### `butterbase_integrations_available_list` List Available Integrations · Read-only List or search the catalog of third-party integration toolkits (e.g. Gmail, Slack, Notion) that can be connected to a Butterbase app. Returns an array of toolkit entries, each with its slug, display name, and whether it is a curated (featured) toolkit. Use butterbase_integrations_available_list to browse or search the full catalog; use butterbase_integrations_config_list to see which toolkits are already enabled for this app. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `app_id` (`string`, required): The Butterbase app ID to list the integration catalog for, as shown in the app's dashboard URL or returned by the app-creation API. - `search` (`string`, optional): Search term to filter the integration catalog by toolkit name or slug. Omit to return the full catalog. Example input: `{"app_id":""}` ### `butterbase_integrations_config_list` List Enabled Integrations · Read-only List the third-party integration toolkits currently enabled for a Butterbase app. Returns the app's enabled toolkit configurations; exact response fields are not published in Butterbase's docs. Use butterbase_integrations_config_list to check what's already connected before calling butterbase_integration_configure to enable a new toolkit. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `app_id` (`string`, required): The Butterbase app ID to list enabled integrations for, as shown in the app's dashboard URL or returned by the app-creation API. Example input: `{"app_id":""}` ### `butterbase_kv_audit_recent_get` Get Recent KV Audit Events · Read-only List the most recent key-value store error events (4xx/5xx responses) for an app, for debugging denied or failed KV access. Returns a list of entries, each with the timestamp, HTTP method, path, status code, error code, and the key involved (when applicable). Use butterbase_kv_audit_recent_get when a caller reports unexpected KV access failures, to see whether requests are being rejected and why -- for example due to a missing or misconfigured expose rule. Use butterbase_kv_expose_rules_list to check the rules that might be causing a denial. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `app_id` (`string`, required): The Butterbase application ID whose recent KV error events should be listed. - `limit` (`integer`, optional): Maximum number of recent error events to return. Defaults to 50; the API caps this at 200. Default: `50`. Example input: `{"app_id":""}` ### `butterbase_kv_exists` Check KV Key Exists · Read-only Check whether a key currently exists in a Butterbase app's key-value store. Returns a boolean indicating whether the key is set. Use this as a lightweight presence check before reading or writing a key. Use butterbase_kv_get instead if you need the key's actual value. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `app_id` (`string`, required): The unique identifier of the Butterbase app whose key-value store should be checked. - `key` (`string`, required): The exact key to check for existence. Example input: `{"app_id":"","key":""}` ### `butterbase_kv_expose_rules_list` List KV Expose Rules · Read-only List every key-value expose rule configured for an app -- the glob-style key patterns that grant end-user JWTs read and/or write access, in the order they are evaluated. Returns an array of rules, each with its pattern, read role, write role, and evaluation order. Use butterbase_kv_expose_rules_list to review or audit which key patterns end users can currently reach. Use butterbase_kv_expose_rule_set to add or change a rule, and butterbase_kv_expose_rule_delete to remove one. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `app_id` (`string`, required): The Butterbase application ID whose key-value expose rules should be listed. Example input: `{"app_id":""}` ### `butterbase_kv_get` Get KV Value · Read-only Read the value stored at a key in a Butterbase app's key-value store. Returns the stored value as JSON; the request fails with a 404 error if the key does not exist. Use this to fetch a single KV entry by its exact key. Use butterbase_kv_exists instead if you only need to check whether the key is set, without reading its value. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `app_id` (`string`, required): The unique identifier of the Butterbase app whose key-value store should be read. - `key` (`string`, required): The exact key to read from the key-value store. - `touch` (`boolean`, optional): If true, may refresh the key's time-to-live as a side effect of this read. Butterbase's docs do not detail the exact TTL behavior this triggers. Example input: `{"app_id":"","key":""}` ### `butterbase_kv_scan` Scan KV Keys · Read-only Scan and list keys in a Butterbase app's key-value store, optionally filtered by a prefix, with cursor-based pagination. Returns an array of matching key names plus a cursor to pass into the next call (null when there are no more results). Use butterbase_kv_scan to browse or enumerate keys by prefix. Use butterbase_kv_stats_get for aggregate usage numbers instead of individual keys. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `app_id` (`string`, required): The Butterbase application ID that owns this key-value store. - `cursor` (`string`, optional): Opaque pagination cursor from a previous scan response's cursor field. Leave blank for the first page. - `limit` (`integer`, optional): Maximum number of keys to return in this page. Butterbase applies its own default page size if omitted. - `prefix` (`string`, optional): Only return keys starting with this prefix. Leave blank to scan all keys. Example input: `{"app_id":""}` ### `butterbase_kv_stats_get` Get KV Store Stats · Read-only Get storage usage statistics for a Butterbase app's key-value store. Returns totals such as key count, bytes used, operations per second, and the app's configured KV limits. Use butterbase_kv_stats_get to check overall KV usage. Use butterbase_kv_scan to list or search the individual keys instead. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `app_id` (`string`, required): The Butterbase application ID that owns this key-value store. Example input: `{"app_id":""}` ### `butterbase_kv_ttl_get` Get KV Key TTL · Read-only Get the remaining time-to-live (TTL) for a key in a Butterbase app's key-value store. Returns the number of seconds until the key expires, or null if the key has no expiration set. Use this to check how much longer a KV entry will exist before it is automatically removed. Use butterbase_kv_get if you also need the key's current value. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `app_id` (`string`, required): The unique identifier of the Butterbase app whose key-value store should be queried. - `key` (`string`, required): The exact key to check the time-to-live for. Example input: `{"app_id":"","key":""}` ### `butterbase_mcp_servers_list` List MCP Servers · Read-only List the MCP servers registered as external tool sources for an app's agents. Returns an array of MCP server records, each with its id, name, URL, and configured auth. Use butterbase_mcp_servers_list to see what's already registered before calling butterbase_mcp_server_register or butterbase_mcp_server_delete. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `app_id` (`string`, required): The id of the Butterbase app whose registered MCP servers you want to list. Example input: `{"app_id":""}` ### `butterbase_meeting_bot_get` Get Meeting Bot · Read-only Get a meeting bot's current status and its recording and transcript URLs. Returns the bot's id, lifecycle status (joining, waiting_room, in_call, recording, ended, done, or fatal), start/completion times, duration, bot name, metadata, and short-lived recording/transcript URLs once available. Use butterbase_meeting_bot_get to poll a bot dispatched by butterbase_meeting_bot_create until it reaches a terminal status, and fetch the URLs promptly since they expire quickly. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `app_id` (`string`, required): The unique identifier of the Butterbase app the meeting bot was dispatched under. - `bot_id` (`string`, required): The unique identifier of the meeting bot to check, as returned by butterbase_meeting_bot_create or butterbase_meeting_bots_list. Example input: `{"app_id":"","bot_id":""}` ### `butterbase_meeting_bots_list` List Meeting Bots · Read-only List meeting bots dispatched for a Butterbase app, optionally filtered by lifecycle status. Returns a page of bot records plus a cursor for the next page (nextCursor is null once there are no more). Use butterbase_meeting_bots_list to browse recent bots or find one by status; use butterbase_meeting_bot_get for full details on one specific bot. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `app_id` (`string`, required): The unique identifier of the Butterbase app whose meeting bots should be listed. - `cursor` (`string`, optional): Pagination cursor from a previous response's nextCursor field. Pass it back here to fetch the next page. Omit for the first page. - `limit` (`integer`, optional): Maximum number of bots to return in this page of results. Between 1 and 100; defaults to 20. Default: `20`. - `status` (`string`, optional): Filter results to bots currently in this lifecycle phase, e.g. joining, in_call, recording, ended, done, or fatal. Leave blank to include all statuses. Example input: `{"app_id":""}` ### `butterbase_meeting_cost_estimate` Estimate Meeting Bot Cost · Read-only Estimate the USD cost of a meeting-bot session before dispatching one, based on its expected duration. Returns the estimated cost in US dollars for the given duration and settings. Use butterbase_meeting_cost_estimate before butterbase_meeting_bot_create to check the price of a planned recording, especially for longer calls. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `app_id` (`string`, required): The unique identifier of the Butterbase app the estimate is for. - `durationMinutes` (`integer`, required): Expected length of the meeting-bot session in minutes, from 1 to 1440 (24 hours). - `transcript` (`boolean`, optional): Whether the estimate should include transcription cost. Defaults to true. Default: `true`. Example input: `{"app_id":"","durationMinutes":1}` ### `butterbase_meeting_usage_logs_get` Get Meeting Usage Logs · Read-only Get recent Butterbase meeting-bot usage and billing log rows for an app. Returns up to the last 100 usage rows, each with its id, billed dimension (recording or transcription), seconds used, USD amount charged, and creation time. Use butterbase_meeting_usage_logs_get to review or reconcile meeting-bot billing after the fact; use butterbase_meeting_cost_estimate beforehand to predict cost instead. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `app_id` (`string`, required): The unique identifier of the Butterbase app whose meeting-bot usage logs should be retrieved. Example input: `{"app_id":""}` ### `butterbase_meetings_status_get` Get Meeting Provider Status · Read-only Check whether the Butterbase meeting-bot provider is currently available. This is an unscoped public health check that needs no app id and no credentials. Returns a single boolean flag indicating availability. Use butterbase_meetings_status_get as a lightweight pre-flight check before dispatching meeting bots at scale, independent of any specific app. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: none. Example input: `{}` ### `butterbase_migrations_list` List Migrations · Read-only List the database migrations that have been applied to a Butterbase app. Returns an array of migration records for the app; Butterbase's docs do not publish the exact per-migration fields, but each typically carries an id, a name, and when it was applied. Use butterbase_migrations_list to review migration history. Use butterbase_schema_apply to apply a new migration, and butterbase_schema_get to see the schema's current state. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `app_id` (`string`, required): The Butterbase app's unique ID whose migration history should be listed. Example input: `{"app_id":""}` ### `butterbase_people_email_lookup_get` Get Work Email Lookup Result · Read-only Poll a previously queued work-email lookup by its lookup ID to check whether it has resolved. Returns a status of pending, resolved, failed, or expired, the resolved email address (or null until resolved), and the credits consumed. Use this after calling butterbase_people_profile_email_lookup_start; poll periodically until the status is no longer pending. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `app_id` (`string`, required): The Butterbase app ID the lookup was started under, as shown in the app's dashboard URL or returned by the app-creation API. - `lookup_id` (`string`, required): The UUID of the email lookup job, as returned by butterbase_people_profile_email_lookup_start. Example input: `{"app_id":"","lookup_id":""}` ### `butterbase_people_profile_get` Get Person Profile · Read-only Retrieve or enrich a person's full profile from Butterbase's People database using their LinkedIn profile URL; results are cached for 30 days by default. Returns identity fields (name, headline, occupation, summary, location), work experience, and education history, plus a status flag and whether the result was served from cache. Use butterbase_people_profile_get when you already know someone's LinkedIn URL; use butterbase_people_search_person first if you need to find that URL. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `app_id` (`string`, required): The Butterbase app ID to look up the profile under, as shown in the app's dashboard URL or returned by the app-creation API. - `linkedinProfileUrl` (`string`, required): The person's LinkedIn profile URL. Butterbase normalizes the URL server-side, so minor formatting differences (trailing slash, query params) are tolerated. - `liveFetch` (`string`, optional): Set to 'force' to skip the 30-day cache and make a live provider call for the freshest data. Omit to use the cached result when available. One of: `force`. Example input: `{"app_id":"","linkedinProfileUrl":""}` ### `butterbase_people_search_company` Search Companies · Read-only Search Butterbase's People database for companies using a free-form natural-language query plus structured filters on industry, country, and maximum employee count. Returns a page of matching companies (each with a LinkedIn company URL, name, industry, country, and employee count), a pagination cursor for the next page, and the total matching result count. Use butterbase_people_search_company to find organizations matching criteria; use butterbase_people_search_person to find individual people instead. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `app_id` (`string`, required): The Butterbase app ID to search within, as shown in the app's dashboard URL or returned by the app-creation API. - `country` (`string`, optional): Filter to companies headquartered in this country. - `employeeCountMax` (`integer`, optional): Filter to companies with at most this many employees. - `industry` (`string`, optional): Filter to companies operating in this industry, e.g. 'Financial Services'. - `nextToken` (`string`, optional): Pagination cursor from a previous response's nextPage value. Pass it back to fetch the next page of results; omit for the first page. - `pageSize` (`integer`, optional): Maximum number of results to return in this page, from 1 to 100. If omitted, the API's default page size is used. - `query` (`string`, optional): Free-form natural-language description of the companies you're looking for, e.g. 'seed-stage climate tech startups'. Combines with any other filters supplied. Example input: `{"app_id":""}` ### `butterbase_people_search_person` Search People · Read-only Search Butterbase's People database for individual profiles using a free-form natural-language query plus structured filters on current or past role, company, industry, location, and education. Returns a page of matching results (each with a LinkedIn profile URL, a nested profile summary, and last-updated time), a pagination cursor for the next page, and the total matching result count. Use butterbase_people_search_person to find people matching criteria; use butterbase_people_profile_get once you have a specific LinkedIn URL to fetch or enrich that person's full profile. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `app_id` (`string`, required): The Butterbase app ID to search within, as shown in the app's dashboard URL or returned by the app-creation API. - `city` (`string`, optional): Filter to people located in this city. - `country` (`string`, optional): Filter to people located in this country. - `currentCompanyIndustry` (`string`, optional): Filter to people whose current employer operates in this industry, e.g. 'Financial Services'. - `currentCompanyName` (`string`, optional): Filter to people whose current employer's name matches this value. - `currentRoleTitle` (`string`, optional): Filter to people whose current job title matches this value, e.g. 'VP of Engineering'. - `educationDegreeName` (`string`, optional): Filter to people who earned a degree matching this name, e.g. 'MBA'. - `educationFieldOfStudy` (`string`, optional): Filter to people who studied a field matching this value, e.g. 'Computer Science'. - `educationSchoolName` (`string`, optional): Filter to people who attended a school or university matching this name. - `nextToken` (`string`, optional): Pagination cursor from a previous response's nextPage value. Pass it back to fetch the next page of results; omit for the first page. - `pageSize` (`integer`, optional): Maximum number of results to return in this page, from 1 to 100. If omitted, the API's default page size is used. - `pastRoleTitle` (`string`, optional): Filter to people who previously held a job title matching this value, e.g. 'Product Manager'. - `query` (`string`, optional): Free-form natural-language description of the person you're looking for, e.g. 'senior backend engineers at fintech startups in Europe'. Combines with any other filters supplied. - `region` (`string`, optional): Filter to people located in this region or state/province. Example input: `{"app_id":""}` ### `butterbase_public_models_list` List Public Models · Read-only List Butterbase's public catalog of AI models with per-model pricing and context-window size. Returns an array of models, each with an id, display name, input and output price per million tokens, and context window size. Use butterbase_public_models_list to compare models and estimate cost before picking one. Use butterbase_gateway_models_list to see only the models your own API key is allowed to call. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: none. Example input: `{}` ### `butterbase_public_run_events_list` List Public Run Events · Read-only Fetch every event recorded for a public agent run as a single JSON array, instead of connecting to the run's live event stream. Returns an array of event objects covering the run's lifecycle — run_start, node_start, node_end, tool_call_start, tool_call_end, llm_token_usage, run_paused, run_cancelled, run_failed, and run_end. Use butterbase_public_run_events_list to review a public run's full event history. Use butterbase_public_run_get instead for just the run's current summary state. Butterbase normally authorizes this route with the app's public anon key rather than the platform API key; this connector calls it with your configured platform API key instead. CONFIRMED via a dedicated live investigation: the underlying Butterbase endpoint works correctly and returns a genuine success when called with a valid end-user access token (obtained via butterbase_auth_login) -- this was previously only ever tested with the wrong credential type (this connector's platform key), which always 401s. HOWEVER, this connector has no way to actually supply that end-user token: Scalekit's execution engine controls the Authorization header for a BEARER connection server-side and rejects a client-supplied Authorization header override outright (confirmed via direct SDK-level testing -- a custom header is rejected with its own 401 before ever reaching Butterbase). This tool will therefore always fail via the standard execution path on this connector, by platform design, not due to a fixable tool-JSON defect -- it would need a future Scalekit auth-strategy feature (e.g. a per-call token override) to ever work through this connector. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `app_id` (`string`, required): The id of the Butterbase app the public run belongs to. - `id` (`string`, required): The id of the public run whose events you want to fetch. Example input: `{"app_id":"","id":""}` ### `butterbase_public_run_get` Get Public Run · Read-only Fetch the current state of a public agent run, started via the app's public anon key. Returns the run object, including its status and result once the run finishes. Use butterbase_public_run_get to poll a run started by butterbase_public_agent_run_create. Use butterbase_agent_run_get instead for a run started with platform authentication. Butterbase normally authorizes this route with the app's public anon key rather than the platform API key; this connector calls it with your configured platform API key instead. CONFIRMED via a dedicated live investigation: the underlying Butterbase endpoint works correctly and returns a genuine success when called with a valid end-user access token (obtained via butterbase_auth_login) -- this was previously only ever tested with the wrong credential type (this connector's platform key), which always 401s. HOWEVER, this connector has no way to actually supply that end-user token: Scalekit's execution engine controls the Authorization header for a BEARER connection server-side and rejects a client-supplied Authorization header override outright (confirmed via direct SDK-level testing -- a custom header is rejected with its own 401 before ever reaching Butterbase). This tool will therefore always fail via the standard execution path on this connector, by platform design, not due to a fixable tool-JSON defect -- it would need a future Scalekit auth-strategy feature (e.g. a per-call token override) to ever work through this connector. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `app_id` (`string`, required): The id of the Butterbase app the public run belongs to. - `id` (`string`, required): The id of the public run to fetch, as returned by butterbase_public_agent_run_create. Example input: `{"app_id":"","id":""}` ### `butterbase_rag_collection_get` Get RAG Collection · Read-only Get a single RAG collection's configuration plus its document and chunk counts. Returns the collection's name, description, access mode, chunk size, chunk overlap, timestamps, document count, and chunk count. Use butterbase_rag_collection_get to check one collection's size and settings. Use butterbase_rag_collections_list to browse all collections in the app. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `app_id` (`string`, required): The Butterbase app ID that owns this collection. Found in the app's dashboard URL or via Butterbase's apps listing. - `name` (`string`, required): The name of the RAG collection to fetch, exactly as it was created (lowercase letters, numbers, hyphens, and underscores). Example input: `{"app_id":"","name":"Pro"}` ### `butterbase_rag_collections_list` List RAG Collections · Read-only List all RAG document collections defined in a Butterbase app. Returns an array of collection objects, each with its name, description, access mode, chunk size, chunk overlap, and creation/update timestamps. Use butterbase_rag_collections_list to browse existing collections. Use butterbase_rag_collection_get for one collection's full details, including its document and chunk counts. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `app_id` (`string`, required): The Butterbase app ID whose collections you want to list. Found in the app's dashboard URL or via Butterbase's apps listing. Example input: `{"app_id":""}` ### `butterbase_rag_document_get` Get RAG Document · Read-only Get a single RAG document's ingestion status and metadata by its document id. Returns the document's id, collection id, filename, status (pending, processing, ready, or failed), chunk count, metadata, any error message, and timestamps. Use butterbase_rag_document_get to poll a document after butterbase_rag_document_ingest until its status is ready or failed. Use butterbase_rag_documents_list to see all documents in a collection. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `app_id` (`string`, required): The Butterbase app ID that owns this collection. Found in the app's dashboard URL or via Butterbase's apps listing. - `document_id` (`string`, required): The id of the document to fetch, as returned by butterbase_rag_document_ingest or butterbase_rag_documents_list. - `name` (`string`, required): The name of the RAG collection that contains this document, exactly as it was created. Example input: `{"app_id":"","document_id":"","name":"Pro"}` ### `butterbase_rag_documents_list` List RAG Documents · Read-only List all documents that have been ingested, or are being ingested, into a RAG collection. Returns an array of document objects, each with its id, filename, ingestion status, chunk count, metadata, and timestamps. Use butterbase_rag_documents_list to see every document in a collection. Use butterbase_rag_document_get to check one document's ingestion status in detail. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `app_id` (`string`, required): The Butterbase app ID that owns this collection. Found in the app's dashboard URL or via Butterbase's apps listing. - `name` (`string`, required): The name of the RAG collection whose documents you want to list, exactly as it was created. Example input: `{"app_id":"","name":"Pro"}` ### `butterbase_rag_query` Query RAG Collection · Read-only Run a semantic search over a RAG collection's ingested documents, optionally synthesizing an AI-generated answer from the matched chunks. Returns matching chunks with their text, similarity score, source document id, and metadata; when synthesis is requested, also returns a generated answer and the model used. Use butterbase_rag_query to retrieve relevant context or a synthesized answer for a user's question. Use butterbase_rag_document_get first if you need to confirm a document has finished ingesting before querying. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `app_id` (`string`, required): The Butterbase app ID that owns this collection. Found in the app's dashboard URL or via Butterbase's apps listing. - `name` (`string`, required): The name of the RAG collection to search, exactly as it was created. - `query` (`string`, required): The natural-language search query to run against the collection's ingested chunks. - `filter` (`object`, optional): Optional metadata key/value filter to restrict which documents' chunks are searched, matching values previously attached via butterbase_rag_document_ingest's metadata field. - `model` (`string`, optional): Model to use for answer synthesis, e.g. anthropic/claude-haiku-4.5. Only used when synthesize is true. If omitted, Butterbase auto-selects a model. CONFIRMED via live testing: this tool's own prior placeholder ("anthropic/claude-haiku-4-5", hyphenated) causes a synthesize=true call to fail with a raw HTTP 500 -- the working id uses a period before the minor version instead ("anthropic/claude-haiku-4.5"). Note Butterbase also returns a 500 rather than a clean 4xx for an unrecognized model id on this endpoint -- an upstream API quirk, not something this tool can guard against client-side. - `synthesize` (`boolean`, optional): When true, also generate an AI-synthesized natural-language answer from the matched chunks instead of returning only raw chunks. Defaults to false. Default: `false`. - `threshold` (`number`, optional): Minimum cosine similarity score (0 to 1) a chunk must meet to be included in the results. If omitted, no minimum is enforced. - `topK` (`number`, optional): Maximum number of matching chunks to return. Defaults to 5 if omitted. Default: `5`. Example input: `{"app_id":"","name":"Pro","query":"seed-stage climate tech startups"}` ### `butterbase_regions_list` List Regions · Read-only List the regions available for creating new Butterbase apps. Returns an array of region identifier strings (e.g. us-east-1, us-west-2) that Butterbase currently supports. Use butterbase_regions_list before butterbase_app_create or butterbase_app_move to pick a valid region value. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: none. Example input: `{}` ### `butterbase_repo_blob_get` Get Repo Blob Download URL · Read-only Get a presigned download URL for one app repo blob, looked up by its SHA-256 hash. Returns a presigned URL and its expiry (field names inferred by analogy with Butterbase's Storage API presigned-URL responses; not shown verbatim in the repo docs). Use butterbase_repo_blob_get to download a single known blob. Use butterbase_repo_blobs_batch_presign to get presigned URLs for many blobs in one call. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `app_id` (`string`, required): The id of the app whose repo the blob belongs to. - `sha256` (`string`, required): The SHA-256 hash (64 lowercase hex characters) identifying the blob to download, as it appears in a repo snapshot manifest. Example input: `{"app_id":"","sha256":""}` ### `butterbase_repo_snapshot_get` Get Repo Snapshot · Read-only Get a specific app repo snapshot's manifest by its snapshot id. Returns the manifest object for that snapshot (exact fields are not published in Butterbase's docs, but it lists each tracked file's path, SHA-256 hash, and size). Use butterbase_repo_snapshot_get to fetch one specific snapshot by id. Use butterbase_repo_snapshot_latest_get for the current one, or butterbase_repo_snapshots_list to find snapshot ids to look up. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `app_id` (`string`, required): The id of the app whose repo the snapshot belongs to. - `snapshot_id` (`string`, required): The id of the specific snapshot to fetch, as returned by butterbase_repo_snapshots_list or butterbase_repo_snapshot_commit. Example input: `{"app_id":"","snapshot_id":""}` ### `butterbase_repo_snapshot_latest_get` Get Latest Repo Snapshot · Read-only Get the manifest of an app's current (latest) repo snapshot. Returns the manifest object for the most recent snapshot (exact fields are not published in Butterbase's docs, but it lists each tracked file's path, SHA-256 hash, and size). Use butterbase_repo_snapshot_latest_get to see what's currently committed. Use butterbase_repo_snapshot_get for a specific historical snapshot by id, or butterbase_repo_snapshots_list to browse the full history. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `app_id` (`string`, required): The id of the app whose latest repo snapshot to fetch. Example input: `{"app_id":""}` ### `butterbase_repo_snapshots_list` List Repo Snapshots · Read-only List the snapshot history for an app's repo. Returns an array of snapshot records for the app (exact fields are not published in Butterbase's docs, but each typically includes a snapshot id, commit message, and timestamp). Use butterbase_repo_snapshots_list to browse an app's snapshot history. Use butterbase_repo_snapshot_get to fetch one specific snapshot's manifest by id, or butterbase_repo_snapshot_latest_get for the current one. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `app_id` (`string`, required): The id of the app whose repo snapshot history to list. Example input: `{"app_id":""}` ### `butterbase_schema_get` Get App Schema · Read-only Read an app's current declarative database schema from Butterbase, describing its tables and columns. Returns the app's schema definition (Butterbase's docs do not publish which exact fields are included, such as whether relationships and constraints are shown). Use butterbase_schema_get to inspect an app's data model before writing rows, applying a migration, or confirming a table or column name. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `app_id` (`string`, required): The Butterbase application ID whose database schema you want to read, as returned when the app was created or from butterbase_apps_list. Example: app_abc123. Example input: `{"app_id":""}` ### `butterbase_storage_download_url_get` Get Storage Download URL · Read-only Get a presigned URL for downloading an existing file from a Butterbase app's storage. Returns a short-lived download URL, the file's original filename, and the URL's expiry in seconds (1 hour by default). Use this to obtain a temporary link for a specific file once you have its object ID; use butterbase_storage_objects_list first to find the object ID of the file you want. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `app_id` (`string`, required): The unique identifier of the Butterbase app that owns the file. - `object_id` (`string`, required): The unique identifier of the stored file to generate a download URL for. Get this from butterbase_storage_objects_list or from the objectId returned by butterbase_storage_upload_url_create. Example input: `{"app_id":"","object_id":""}` ### `butterbase_storage_objects_list` List Storage Objects · Read-only List all files stored in a Butterbase app's storage. This endpoint has no documented pagination or filtering and returns the full set of objects for the app. Returns an array of file objects, each with its id, filename, content type, size in bytes, and creation time. Use this to browse or discover the files stored for an app, then use butterbase_storage_download_url_get with a file's id to get a download link for it. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `app_id` (`string`, required): The unique identifier of the Butterbase app whose stored files should be listed. Example input: `{"app_id":""}` ### `butterbase_substrate_action_get` Get Substrate Action · Read-only Get a single Substrate action from the proposal/approval ledger by its ID. Returns the action's capability, payload, verdict, status, and any capability-specific result. Use butterbase_substrate_action_get to check on one action's outcome after proposing it with butterbase_substrate_action_propose, or after finding its ID via butterbase_substrate_actions_list. Requires a Butterbase Substrate-scoped API key (bb_sub_...), not the general platform key. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `action_id` (`string`, required): The unique identifier of the Substrate action to fetch, as returned by butterbase_substrate_action_propose or a list of actions. Example input: `{"action_id":""}` ### `butterbase_substrate_actions_list` List Substrate Actions · Read-only List actions in the Substrate proposal/approval ledger, optionally filtered by status, capability, source app, or source attention rule. Returns an array of action records with each action's id, capability, payload, verdict, and status, newest first, with a before-timestamp cursor for paging further back. Use butterbase_substrate_actions_list to browse or audit the ledger. Use butterbase_substrate_action_get to fetch one specific action by ID. Requires a Butterbase Substrate-scoped API key (bb_sub_...), not the general platform key. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `before` (`string`, optional): Only return actions proposed before this ISO 8601 timestamp. Use the earliest updated_at/created_at value from a previous page to page further back in time (keyset pagination). Omit to start from now. - `capability` (`string`, optional): Filter results to actions proposed with exactly this capability, e.g. record_decision or upsert_entity. Omit to return actions of every capability. - `limit` (`integer`, optional): Maximum number of actions to return, from 1 to 500. Defaults to 100 if omitted. Default: `100`. - `source_app_id` (`string`, optional): Filter results to actions originally proposed by this Butterbase app (via an installed integration). Omit to include actions from every source. - `source_rule_id` (`string`, optional): Filter results to actions that were fired by this Substrate attention rule. Omit to include actions from every source. - `status` (`string`, optional): Filter results to actions in exactly this status. Omit to return actions in every status. One of: `proposed`, `executed`, `rejected`. Example input: `{}` ### `butterbase_substrate_attention_rule_firings_list` List Attention Rule Firings · Read-only List the past firings recorded for one Substrate attention rule — each time its condition matched and it proposed an action. Returns an array of firing records for the rule. Butterbase's docs do not publish the exact per-firing fields or this endpoint's query parameters, so the optional limit and before filters below follow the same limit-plus-before keyset pagination convention used by other Substrate list endpoints, not a shape confirmed for this specific endpoint. Use butterbase_substrate_attention_rule_firings_list to audit or debug when and why a rule fired; each firing's action_id can be looked up in the Substrate actions ledger for full details. Requires a Butterbase Substrate-scoped API key (bb_sub_...) — a standard platform API key is rejected with a 403 on all Substrate endpoints. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `rule_id` (`string`, required): The unique id of the attention rule whose past firings should be listed, as returned by butterbase_substrate_attention_rule_create or a prior list call. - `before` (`string`, optional): Keyset pagination cursor: only return firings recorded before this ISO 8601 timestamp. Not explicitly documented for this endpoint; inferred from the same before-cursor pattern used elsewhere in the Substrate API (e.g. the actions ledger and memory/list). Leave unset to get the most recent firings first. - `limit` (`integer`, optional): Maximum number of firing records to return. Not explicitly documented for this endpoint; other Substrate list endpoints cap this between 1 and 500 with a server-side default around 50-100. Leave unset to use Butterbase's default page size. Example input: `{"rule_id":""}` ### `butterbase_substrate_attention_rule_get` Get Substrate Attention Rule · Read-only Fetch a single Substrate attention rule by its id. Returns the rule's id, name, description, cron schedule, condition mode and predicate, action capability and payload template, enabled state, and daily fire cap. Use butterbase_substrate_attention_rule_get when you already have a rule id. Use butterbase_substrate_attention_rules_list to find that id first. This endpoint requires a Butterbase Substrate-scoped API key (bb_sub_...) — a general platform key (bb_sk_...) is rejected with a 403. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `rule_id` (`string`, required): The unique id of the Substrate attention rule to fetch. Example input: `{"rule_id":""}` ### `butterbase_substrate_attention_rules_list` List Substrate Attention Rules · Read-only List the attention rules configured on your Butterbase Substrate account — automations that run on a cron schedule, evaluate a condition, and propose an action when it fires. Returns an array of rule records, each with its id, name, description, cron schedule, condition mode and predicate, action capability and payload template, enabled state, and daily fire cap. Use butterbase_substrate_attention_rules_list to review configured rules. Use butterbase_substrate_attention_rule_get to fetch one rule's full details by id. This endpoint requires a Butterbase Substrate-scoped API key (bb_sub_...) — a general platform key (bb_sk_...) is rejected with a 403. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: none. Example input: `{}` ### `butterbase_substrate_entities_list` List Substrate Entities · Read-only List entities tracked in your Butterbase Substrate memory (people, companies, funds, workspaces, teams, projects, events, or agents), optionally filtered by type or a display-name search. Returns an array of entity records, each with its id, type, display name, and attributes; pass count=true to also get a total count. Use butterbase_substrate_entities_list to browse or filter entities. Use butterbase_substrate_entity_get to fetch one entity's full details by id. This endpoint requires a Butterbase Substrate-scoped API key (bb_sub_...) — a general platform key (bb_sk_...) is rejected with a 403. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `count` (`boolean`, optional): When true, intended to include a total matching-entity count alongside the results. CONFIRMED via live testing: this currently has no observable effect -- the response is always exactly {"entities": [...]} with no separate count/total field, across every combination tested. Likely a dead/no-op parameter upstream, or the count is only added under conditions not yet identified. Default: `false`. - `limit` (`integer`, optional): Maximum number of entities to return, from 1 to 200. Defaults to 50 when omitted. Default: `50`. - `q` (`string`, optional): Case-insensitive search term matched against each entity's display name. - `type` (`string`, optional): Restrict results to entities of this type. One of: `person`, `company`, `fund`, `workspace`, `team`, `project`, `event`, `agent`, `self`. Example input: `{}` ### `butterbase_substrate_entity_get` Get Substrate Entity · Read-only Fetch a single entity from your Butterbase Substrate memory by its id. Returns the entity's id, type, display name, and its full attributes object. Use butterbase_substrate_entity_get when you already have an entity id. Use butterbase_substrate_entities_list to browse or search for that id first. This endpoint requires a Butterbase Substrate-scoped API key (bb_sub_...) — a general platform key (bb_sk_...) is rejected with a 403. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `entity_id` (`string`, required): The unique id of the Substrate entity to fetch. Example input: `{"entity_id":""}` ### `butterbase_substrate_memory_list` Browse Substrate Memory · Read-only Browse Substrate memory items — decisions, commitments, learnings, and source artifacts — in reverse-chronological order, using structural filters instead of a text search. Returns an array of items, each with its id, kind, title, body text, status, supersession info, and update time, plus a next_before cursor to fetch the next page (null when there are no more pages). Use butterbase_substrate_memory_list to page through memory by recency, restrict to one artifact's extracted items, or exclude superseded/expired items. Use butterbase_substrate_memory_search for a relevance-ranked text query instead. This endpoint requires a Butterbase Substrate-scoped API key (bb_sub_...) — a general platform key (bb_sk_...) is rejected with a 403. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `before` (`string`, optional): Keyset pagination cursor: an ISO 8601 timestamp. Returns items updated before this time. Pass the previous response's next_before to get the next page. - `kinds` (`string`, optional): Comma-separated subset of item kinds to include: decisions, commitments, learnings, source_artifacts. Leave unset to include all kinds. - `limit` (`integer`, optional): Maximum number of items to return, from 1 to 100. Defaults to 25 when omitted. Default: `25`. - `source_artifact_id` (`string`, optional): Restrict results to the decisions, commitments, and learnings extracted from this one source artifact. - `superseded` (`boolean`, optional): Filter by supersession state: false excludes superseded decisions and expired commitments; true includes only those; leave unset to include both. Example input: `{}` ### `butterbase_substrate_memory_search` Search Substrate Memory · Read-only Run a relevance-ranked full-text search across your Butterbase Substrate memory — decisions, commitments, learnings, and source artifacts — for a query string. Returns an array of matching items, each with its id, kind, title, body text, relevance rank, status, and update time; omitting the query returns the most recently updated items instead, with rank set to null. Use butterbase_substrate_memory_search for a relevance-ranked text query. Use butterbase_substrate_memory_list to browse chronologically with structural filters instead of a search term. This endpoint requires a Butterbase Substrate-scoped API key (bb_sub_...) — a general platform key (bb_sk_...) is rejected with a 403. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `kinds` (`string`, optional): Comma-separated subset of item kinds to search: decisions, commitments, learnings, source_artifacts. Leave unset to search all kinds. - `limit` (`integer`, optional): Maximum number of results to return, from 1 to 200. Defaults to 20 when omitted. Default: `20`. - `match` (`string`, optional): How multi-word queries are matched: and (all terms must appear), or (any term may appear), or phrase (terms must appear together, in order). One of: `and`, `or`, `phrase`. Default: `and`. - `q` (`string`, optional): Full-text search query. Omit or pass * to list the most recently updated items instead of searching. Example input: `{}` ### `butterbase_substrate_outbox_targets_list` List Outbox Targets · Read-only List the outbound webhook targets currently registered for your Substrate account, one per capability. Returns an array of target records. Butterbase's docs do not detail the exact fields returned per target beyond what was used to register it (the webhook_url and, if set, the source_app_id scope); the signing_secret itself is not expected to be echoed back. Use butterbase_substrate_outbox_targets_list to check which capabilities already have a webhook configured before calling butterbase_substrate_outbox_target_set to add or replace one. Requires a Butterbase Substrate-scoped API key (bb_sub_...) — a standard platform API key is rejected with a 403 on all Substrate endpoints. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: none. Example input: `{}` ### `butterbase_substrate_settings_get` Get Substrate Settings · Read-only Get the current user's Substrate settings, including whether yolo mode (auto-approve all proposed actions) is enabled. Returns the user's Substrate toggle settings as a JSON object. Use butterbase_substrate_settings_get to check current settings before changing yolo mode with butterbase_substrate_yolo_mode_set. Requires a Butterbase Substrate-scoped API key (bb_sub_...), not the general platform key. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: none. Example input: `{}` ### `butterbase_substrate_snapshots_get` Get Substrate Snapshots · Read-only Get daily rollup snapshots of Substrate activity, the same data attention rules use for their snapshot_predicate conditions. Returns an array of snapshot records, each with a snapshot_date, entity_count, and decision_count (Butterbase's docs do not publish further fields). Use butterbase_substrate_snapshots_get to review recent daily activity trends or to sanity-check a snapshot_predicate condition before creating an attention rule with butterbase_substrate_attention_rule_create. This endpoint requires a Butterbase Substrate-scoped API key (bb_sub_...) — a general platform key (bb_sk_...) is rejected with a 403. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `days` (`integer`, optional): Number of most-recent historical days of snapshots to return. Leave unset to use Butterbase's default range. Example input: `{}` ### `butterbase_substrate_source_artifact_get` Get Substrate Source Artifact · Read-only Fetch a single Substrate source artifact by its id, including its full content rather than the summary shown in list results. Returns the artifact's id, kind, external system and id, title, summary, full content, url, linked entity ids and project tags, attributes, source app, and timestamps. Use butterbase_substrate_source_artifact_get when you already have an artifact id and need its full text. Use butterbase_substrate_source_artifacts_list or butterbase_substrate_memory_search to find that id first. This endpoint requires a Butterbase Substrate-scoped API key (bb_sub_...) — a general platform key (bb_sk_...) is rejected with a 403. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `artifact_id` (`string`, required): The unique id of the Substrate source artifact to fetch. Example input: `{"artifact_id":""}` ### `butterbase_substrate_source_artifacts_list` List Substrate Source Artifacts · Read-only List or full-text-search source artifacts in your Butterbase Substrate memory — ingested content such as meeting transcripts and documents, typically synced in from connected apps. Returns an array of artifact summaries, each with its id, kind, external system and id, title, summary, url, linked entity ids and project tags, attributes, source app, and timestamps. Use butterbase_substrate_source_artifacts_list to browse artifact summaries or run a keyword search. Use butterbase_substrate_source_artifact_get to fetch one artifact's full content by id. This endpoint requires a Butterbase Substrate-scoped API key (bb_sub_...) — a general platform key (bb_sk_...) is rejected with a 403. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `count` (`boolean`, optional): When true, intended to include a total matching-artifact count alongside the results. CONFIRMED via live testing: this currently has no observable effect -- the response is always exactly {"source_artifacts": [...]} with no separate count/total field, tried as both a boolean and a literal "true" string, including against a limit that truncates real results. Likely a dead/no-op parameter upstream (same behavior confirmed on butterbase_substrate_entities_list's identical count field). Default: `false`. - `kind` (`string`, optional): Restrict results to artifacts of this kind, e.g. meeting_transcript. - `limit` (`integer`, optional): Maximum number of artifacts to return, from 1 to 200. Defaults to 50 when omitted. Default: `50`. - `q` (`string`, optional): Full-text search term matched against each artifact's title, summary, and content. Example input: `{}` ### `butterbase_table_row_get` Get Table Row · Read-only Retrieve a single row from a Butterbase app table by its primary key, with optional column selection, extra PostgREST-style filters, sort order, and limit/offset. Returns the matching row's column values (Butterbase's docs do not publish the exact response shape for this endpoint). Use butterbase_table_row_get when you already know the row's id; use butterbase_table_rows_list to search or browse across a table. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `app_id` (`string`, required): The Butterbase application ID that owns the table, as returned when the app was created or from butterbase_apps_list. Example: app_abc123. - `id` (`string`, required): The primary key value of the row to retrieve, matching whatever type the table's primary key column uses (e.g. an integer id or a UUID). Example: 42. - `table` (`string`, required): The name of the table to read from, exactly as defined in the app's schema (see butterbase_schema_get). Example: posts. - `filters` (`object`, optional): Optional extra PostgREST-style filters that the row must also satisfy, as a JSON object mapping any column name to an 'operator.value' string. Supported operators: eq, neq, gt, gte, lt, lte, like, ilike, is, in, and fts (full-text search). Example: {"status": "eq.published"}. KNOWN PLATFORM LIMITATION: this field is currently NOT forwarded to the API (Scalekit's query-parameter mapping only supports a fixed set of named parameters, not arbitrary column names) -- setting it has no effect. Use select/order/limit/offset instead, or filter results client-side. - `limit` (`integer`, optional): Optional maximum number of rows to return. Rarely needed for a single-row lookup by id, but accepted by the underlying endpoint. Example: 1. - `offset` (`integer`, optional): Optional number of matching rows to skip before returning results. Rarely needed for a single-row lookup by id, but accepted by the underlying endpoint. Example: 0. - `order` (`string`, optional): Optional sort order to apply, as 'column.direction'. Rarely needed for a single-row lookup by id, but accepted by the underlying endpoint. Example: created_at.desc. - `select` (`string`, optional): Optional comma-separated list of column names to include in the response, limiting the row to just those columns. Example: id,title,created_at. Leave blank to return all columns. CONFIRMED via live testing: this field is correctly forwarded to the API (verified via a raw query-string check) but the single-row-by-id endpoint currently ignores it and always returns every column regardless -- unlike butterbase_table_rows_list, whose identical select support genuinely works. This is an upstream Butterbase endpoint limitation, not a tool defect. Example input: `{"app_id":"","id":"","table":""}` ### `butterbase_table_rows_list` List Table Rows · Read-only List rows from a table in a Butterbase app, with optional PostgREST-style column filters, sort order, column selection, and offset-based pagination. Returns the matching rows (Butterbase's docs do not publish the exact response envelope for this endpoint, so expect either a bare array or an array wrapped with metadata). Use butterbase_table_rows_list to browse or query many rows at once; use butterbase_table_row_get to fetch one specific row by its primary key. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `app_id` (`string`, required): The Butterbase application ID that owns the table, as returned when the app was created or from butterbase_apps_list. Example: app_abc123. - `table` (`string`, required): The name of the table to list rows from, exactly as defined in the app's schema (see butterbase_schema_get). Example: posts. - `filters` (`object`, optional): Optional PostgREST-style filters to narrow the rows returned, as a JSON object mapping any column name to an 'operator.value' string. Supported operators: eq, neq, gt, gte, lt, lte, like, ilike, is, in, and fts (full-text search). Example: {"status": "eq.published", "age": "gte.18"}. KNOWN PLATFORM LIMITATION: this field is currently NOT forwarded to the API (Scalekit's query-parameter mapping only supports a fixed set of named parameters, not arbitrary column names) -- setting it has no effect. Use select/order/limit/offset instead, or filter results client-side. - `limit` (`integer`, optional): Optional maximum number of rows to return. Example: 20. - `offset` (`integer`, optional): Optional number of matching rows to skip before returning results, for pagination. Example: 40 skips the first 40 rows. - `order` (`string`, optional): Optional sort order for the returned rows, as 'column.direction', comma-separated for multiple columns. Example: created_at.desc or name.asc,created_at.desc. - `select` (`string`, optional): Optional comma-separated list of column names to include in the response, limiting each row to just those columns. Example: id,title,created_at. Leave blank to return all columns. Example input: `{"app_id":"","table":"
"}` ### `butterbase_template_get` Get Template · Read-only Get full details of one public Butterbase app template. Returns the template's detail object as published by Butterbase (its description and configuration; exact fields are not documented). Use butterbase_template_get after finding a template with butterbase_templates_list. Use butterbase_template_clone instead to create a new app from it. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `app_id` (`string`, required): The template's app ID, i.e. the app_id of the public app that serves as this template (as returned by butterbase_templates_list). Example input: `{"app_id":""}` ### `butterbase_templates_list` List Templates · Read-only Discover public Butterbase app templates, optionally filtered by search text or region and sorted. Returns a page of template items alongside the total matching count, limit, and offset used. Use butterbase_templates_list to browse or search templates before cloning one. Use butterbase_template_get instead to fetch full details for one specific template you already know the ID of. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `limit` (`integer`, optional): Maximum number of templates to return in this page of results. Defaults to 20 if omitted. Default: `20`. - `offset` (`integer`, optional): Number of matching templates to skip before returning results, for paging through the list. Defaults to 0. Default: `0`. - `q` (`string`, optional): Free-text search query matched against template name/description. If omitted, all public templates are returned (subject to other filters). - `region` (`string`, optional): Restrict results to templates whose source app lives in this region. Use a region identifier from butterbase_regions_list, e.g. us-east-1. - `sort` (`string`, optional): Sort order for the returned templates. The exact set of accepted sort keys is not published in Butterbase's docs; common values like 'popular' or 'newest' are a reasonable starting point. Example input: `{}` ### `butterbase_video_generation_get` Get Video Generation Job · Read-only Poll the status of a Butterbase AI video-generation job by its job id. Returns the job's status (pending, in_progress, completed, failed, cancelled, or expired) and, once the job is terminal, an array of content URLs for the generated video. Use butterbase_video_generation_get after butterbase_video_generation_create to check whether a video job has finished. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `app_id` (`string`, required): The id of the Butterbase app the video-generation job was submitted under. - `job_id` (`string`, required): The id of the video-generation job to check, as returned by butterbase_video_generation_create. Example input: `{"app_id":"","job_id":""}` ### `butterbase_agent_create` Create Agent · Write Create a new agent in a Butterbase app from a tool-calling graph specification. Returns the created agent's name, model, visibility, and creation timestamp; Butterbase's docs don't publish the full response shape. Use butterbase_agent_create to define a brand-new agent. Use butterbase_agent_validate first to check a graph_spec before saving it, and butterbase_agent_update to change an agent afterward. Read only: no. Destructive: no. Idempotent (safe to retry): no. Inputs: - `app_id` (`string`, required): The Butterbase app's unique ID to create the agent in. - `default_model` (`string`, required): The model this agent's llm nodes use by default, in Butterbase's provider/model id format (e.g. anthropic/claude-haiku-4-5). Individual llm nodes in graph_spec can override this per node. - `graph_spec` (`object`, required): The agent's tool-calling graph specification. FULLY CONFIRMED live via butterbase_agent_validate and an end-to-end agent run (Butterbase's docs previously described a different, incorrect shape). The object requires: spec_version (string, e.g. "1"), entry (the starting node id), nodes (an OBJECT keyed by node id — each llm node needs type:"llm", model, system_prompt, input_template, and output_key (the state key its output is written to); each end node needs type:"end" and output_template), edges (a top-level ARRAY of {"from": "", "to": ""} objects connecting the nodes — node linking is NOT a per-node field), tools (object: {"builtin": [], "mcp_servers": [], "functions": []}), and limits (object with 5 required numeric fields: max_steps, max_tool_calls, max_parallel_tools, timeout_seconds, human_timeout_seconds). Node prompts and templates can reference shared run state via {{ state.key }} templating. Example (validated live, ran to completion): {"spec_version": "1", "entry": "start", "nodes": {"start": {"type": "llm", "model": "anthropic/claude-haiku-4-5", "system_prompt": "You are a helpful assistant.", "input_template": "{{ state.user_question }}", "output_key": "answer"}, "done": {"type": "end", "output_template": "{{ state.answer }}"}}, "edges": [{"from": "start", "to": "done"}], "tools": {"builtin": [], "mcp_servers": [], "functions": []}, "limits": {"max_steps": 10, "max_tool_calls": 10, "max_parallel_tools": 1, "timeout_seconds": 60, "human_timeout_seconds": 3600}} ADDITIONAL CONFIRMED FACTS (from a dedicated live investigation): graph_spec.nodes[id].type actually has THREE valid values, not two -- "llm", "tool", and "end" (confirmed via agent_validate's own invalid_union_discriminator error). A "tool" node calls exactly one tool deterministically as its own graph step (distinct from an "llm" node, where the model decides whether/when to call from its available tools list); it needs {"type": "tool", "tool_ref": , "args_template": , "output_key": ""}. Separately: an "llm" node's per-node "tools" array entries, and a "tool" node's "tool_ref", are NOT plain strings -- they are a discriminated union keyed by "source": {"source": "builtin", "name": ""} for a builtin tool (confirmed real names: delete_row, update_row -- validate does not check tool-name existence, only the runtime does, failing fast with a clean "unknown builtin tool" error if wrong), {"source": "mcp", "server_id": "", "name": ""} for an MCP tool, or {"source": "function", "name": ""} for a Butterbase function. This is a completely separate shape from the top-level graph_spec.tools.{builtin, mcp_servers, functions} registration object, which remains flat string arrays as originally documented -- that object registers what the agent may use overall, while each node's own tools/tool_ref field is where a specific tool is actually referenced and invoked. Confirmed end-to-end: a "tool" node targeting {"source": "builtin", "name": "delete_row"} successfully deleted a real row and produced a full run_start -> node_start -> tool_call_start -> tool_call_end -> node_end -> run_end event trace. - `name` (`string`, required): A unique, URL-safe name for the agent within this app. Used as the {name} path segment in every other agent and run endpoint, so pick something stable. - `safety_acknowledged` (`boolean`, required): Confirms you've reviewed this agent's graph_spec for tool calls that can take real-world action (e.g. sending email, modifying data) and accept the associated risk. Butterbase requires this to be true before it will create the agent. - `visibility` (`string`, required): Whether this agent can be run anonymously through its /public/agents/{name}/runs endpoint (public), only via authenticated calls made with your platform API key (private), or only by a signed-in end-user session (authenticated) -- CONFIRMED via live testing as a valid, accepted third value not previously documented here. One of: `public`, `private`, `authenticated`. - `daily_budget_usd` (`number`, optional): Caps this agent's total spend per day in US dollars; Butterbase stops starting new runs once the cap is hit for the day. Omit for no daily budget cap. - `description` (`string`, optional): A free-text description of what the agent does, for your own reference; not shown to end users. - `display_name` (`string`, optional): A human-friendly label for the agent shown in the Butterbase dashboard. Falls back to name if omitted. - `max_concurrent_runs` (`integer`, optional): Caps how many runs of this agent can be in progress at the same time across all users. Omit for no concurrency limit. - `max_runs_per_user_per_hour` (`integer`, optional): Caps how many runs a single end user can start against this agent per hour, for authenticated per-user rate limiting. Omit for no per-user limit. Example input: `{"app_id":"","default_model":"","graph_spec":{},"name":"Pro","safety_acknowledged":true,"visibility":"public"}` ### `butterbase_agent_run_cancel` Cancel Agent Run · Write Cancel a queued or in-progress run of a Butterbase agent. Returns the run's updated status. Use butterbase_agent_run_cancel to stop a run that's no longer needed. Use butterbase_agent_run_get afterward to confirm it stopped. Read only: no. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `app_id` (`string`, required): The Butterbase app's unique ID the agent belongs to. - `name` (`string`, required): The unique name of the agent the run belongs to. - `run_id` (`string`, required): The id of the run to cancel, as returned by butterbase_agent_run_create or a prior butterbase_agent_runs_list call. Example input: `{"app_id":"","name":"Pro","run_id":""}` ### `butterbase_agent_run_create` Start Agent Run · Write Start an authenticated run of a Butterbase agent with a JSON input payload. Returns the new run's id and initial status. Use butterbase_agent_run_create to kick off a run using your platform API key. Use butterbase_agent_runs_list and butterbase_agent_run_get to track it afterward. Read only: no. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `app_id` (`string`, required): The Butterbase app's unique ID the agent belongs to. - `input` (`object`, required): The run's input payload, made available to the agent's graph_spec via `{{ state.* }}` templating; the keys it should contain depend on how the agent's graph is written. Example: {"user_question": "What's my order status?"}. Butterbase treats this exact request body as an idempotency key: resubmitting the identical input to this agent returns the existing run with HTTP 200 instead of starting a duplicate, while sending different input against that same key returns a 409 Conflict. - `name` (`string`, required): The unique name of the agent to run. Example input: `{"app_id":"","input":{"user_question":"What's my order status?"},"name":"Pro"}` ### `butterbase_agent_run_resume` Resume Agent Run · Write Resume a paused Butterbase agent run with a human-in-the-loop approval decision. Returns the run object after processing your decision. Use butterbase_agent_run_resume when a run's events include a run_paused event carrying an approval_token that needs a decision. Use butterbase_agent_run_cancel instead if you want to stop the run rather than approve or reject its next step. Read only: no. Destructive: no. Idempotent (safe to retry): no. Inputs: - `app_id` (`string`, required): The Butterbase app's unique ID the agent belongs to. - `approval_token` (`string`, required): The one-time approval token carried by the run's run_paused event, identifying the specific tool call awaiting a human decision. - `approved` (`boolean`, required): Whether to approve (true) or reject (false) the tool call the run paused on. Approving lets the run continue and execute it; rejecting stops that step from running. - `name` (`string`, required): The unique name of the agent the run belongs to. - `run_id` (`string`, required): The id of the paused run to resume. Example input: `{"app_id":"","approval_token":"","approved":true,"name":"Pro","run_id":""}` ### `butterbase_agent_update` Update Agent · Write Update an existing Butterbase agent's status, graph_spec, visibility, model, or run limits without recreating it. Returns the agent object with your changes applied. Use butterbase_agent_update to change part of an agent's configuration. Use butterbase_agent_validate first to check a new graph_spec before saving it here, and butterbase_agent_create to make a brand-new agent instead. Read only: no. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `app_id` (`string`, required): The Butterbase app's unique ID the agent belongs to. - `name` (`string`, required): The unique name of the agent to update. - `daily_budget_usd` (`number`, optional): New cap on this agent's total spend per day in US dollars. Omit to leave unchanged. - `default_model` (`string`, optional): New default model id for the agent's llm nodes, in Butterbase's provider/model id format. Individual llm nodes in graph_spec can still override this per node. - `description` (`string`, optional): New free-text description of what the agent does, for your own reference. - `display_name` (`string`, optional): New human-friendly label for the agent shown in the Butterbase dashboard. - `graph_spec` (`object`, optional): The agent's tool-calling graph specification. FULLY CONFIRMED live via butterbase_agent_validate and an end-to-end agent run (Butterbase's docs previously described a different, incorrect shape). The object requires: spec_version (string, e.g. "1"), entry (the starting node id), nodes (an OBJECT keyed by node id — each llm node needs type:"llm", model, system_prompt, input_template, and output_key (the state key its output is written to); each end node needs type:"end" and output_template), edges (a top-level ARRAY of {"from": "", "to": ""} objects connecting the nodes — node linking is NOT a per-node field), tools (object: {"builtin": [], "mcp_servers": [], "functions": []}), and limits (object with 5 required numeric fields: max_steps, max_tool_calls, max_parallel_tools, timeout_seconds, human_timeout_seconds). Node prompts and templates can reference shared run state via {{ state.key }} templating. Example (validated live, ran to completion): {"spec_version": "1", "entry": "start", "nodes": {"start": {"type": "llm", "model": "anthropic/claude-haiku-4-5", "system_prompt": "You are a helpful assistant.", "input_template": "{{ state.user_question }}", "output_key": "answer"}, "done": {"type": "end", "output_template": "{{ state.answer }}"}}, "edges": [{"from": "start", "to": "done"}], "tools": {"builtin": [], "mcp_servers": [], "functions": []}, "limits": {"max_steps": 10, "max_tool_calls": 10, "max_parallel_tools": 1, "timeout_seconds": 60, "human_timeout_seconds": 3600}} ADDITIONAL CONFIRMED FACTS (from a dedicated live investigation): graph_spec.nodes[id].type actually has THREE valid values, not two -- "llm", "tool", and "end" (confirmed via agent_validate's own invalid_union_discriminator error). A "tool" node calls exactly one tool deterministically as its own graph step (distinct from an "llm" node, where the model decides whether/when to call from its available tools list); it needs {"type": "tool", "tool_ref": , "args_template": , "output_key": ""}. Separately: an "llm" node's per-node "tools" array entries, and a "tool" node's "tool_ref", are NOT plain strings -- they are a discriminated union keyed by "source": {"source": "builtin", "name": ""} for a builtin tool (confirmed real names: delete_row, update_row -- validate does not check tool-name existence, only the runtime does, failing fast with a clean "unknown builtin tool" error if wrong), {"source": "mcp", "server_id": "", "name": ""} for an MCP tool, or {"source": "function", "name": ""} for a Butterbase function. This is a completely separate shape from the top-level graph_spec.tools.{builtin, mcp_servers, functions} registration object, which remains flat string arrays as originally documented -- that object registers what the agent may use overall, while each node's own tools/tool_ref field is where a specific tool is actually referenced and invoked. Confirmed end-to-end: a "tool" node targeting {"source": "builtin", "name": "delete_row"} successfully deleted a real row and produced a full run_start -> node_start -> tool_call_start -> tool_call_end -> node_end -> run_end event trace. - `max_concurrent_runs` (`integer`, optional): New cap on how many runs of this agent can be in progress at the same time. Omit to leave unchanged. - `max_runs_per_user_per_hour` (`integer`, optional): New cap on how many runs a single end user can start against this agent per hour. Omit to leave unchanged. - `status` (`string`, optional): New lifecycle status to set on the agent, such as pausing it so it stops accepting new runs. Butterbase's docs don't publish the full set of valid status values — use one you've seen returned by butterbase_agent_get or your dashboard for this agent. - `visibility` (`string`, optional): New visibility for the agent: public to allow anonymous runs through /public/agents/{name}/runs, private to require your platform API key for every run, or authenticated to require a valid end-user session (login/signup) rather than either of those -- CONFIRMED via live testing as a valid, accepted third value not previously documented here. One of: `public`, `private`, `authenticated`. Example input: `{"app_id":"","name":"Pro"}` ### `butterbase_agent_validate` Validate Agent Graph · Write Validate a candidate graph_spec for an existing Butterbase agent without saving it. Returns whether the graph is valid, plus a list of issues (each with a path and message) when it isn't. Use butterbase_agent_validate to check a new or edited graph before committing it with butterbase_agent_create or butterbase_agent_update. Read only: no. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `app_id` (`string`, required): The Butterbase app's unique ID the agent belongs to. - `graph_spec` (`object`, required): The agent's tool-calling graph specification. FULLY CONFIRMED live via butterbase_agent_validate and an end-to-end agent run (Butterbase's docs previously described a different, incorrect shape). The object requires: spec_version (string, e.g. "1"), entry (the starting node id), nodes (an OBJECT keyed by node id — each llm node needs type:"llm", model, system_prompt, input_template, and output_key (the state key its output is written to); each end node needs type:"end" and output_template), edges (a top-level ARRAY of {"from": "", "to": ""} objects connecting the nodes — node linking is NOT a per-node field), tools (object: {"builtin": [], "mcp_servers": [], "functions": []}), and limits (object with 5 required numeric fields: max_steps, max_tool_calls, max_parallel_tools, timeout_seconds, human_timeout_seconds). Node prompts and templates can reference shared run state via {{ state.key }} templating. Example (validated live, ran to completion): {"spec_version": "1", "entry": "start", "nodes": {"start": {"type": "llm", "model": "anthropic/claude-haiku-4-5", "system_prompt": "You are a helpful assistant.", "input_template": "{{ state.user_question }}", "output_key": "answer"}, "done": {"type": "end", "output_template": "{{ state.answer }}"}}, "edges": [{"from": "start", "to": "done"}], "tools": {"builtin": [], "mcp_servers": [], "functions": []}, "limits": {"max_steps": 10, "max_tool_calls": 10, "max_parallel_tools": 1, "timeout_seconds": 60, "human_timeout_seconds": 3600}} ADDITIONAL CONFIRMED FACTS (from a dedicated live investigation): graph_spec.nodes[id].type actually has THREE valid values, not two -- "llm", "tool", and "end" (confirmed via agent_validate's own invalid_union_discriminator error). A "tool" node calls exactly one tool deterministically as its own graph step (distinct from an "llm" node, where the model decides whether/when to call from its available tools list); it needs {"type": "tool", "tool_ref": , "args_template": , "output_key": ""}. Separately: an "llm" node's per-node "tools" array entries, and a "tool" node's "tool_ref", are NOT plain strings -- they are a discriminated union keyed by "source": {"source": "builtin", "name": ""} for a builtin tool (confirmed real names: delete_row, update_row -- validate does not check tool-name existence, only the runtime does, failing fast with a clean "unknown builtin tool" error if wrong), {"source": "mcp", "server_id": "", "name": ""} for an MCP tool, or {"source": "function", "name": ""} for a Butterbase function. This is a completely separate shape from the top-level graph_spec.tools.{builtin, mcp_servers, functions} registration object, which remains flat string arrays as originally documented -- that object registers what the agent may use overall, while each node's own tools/tool_ref field is where a specific tool is actually referenced and invoked. Confirmed end-to-end: a "tool" node targeting {"source": "builtin", "name": "delete_row"} successfully deleted a real row and produced a full run_start -> node_start -> tool_call_start -> tool_call_end -> node_end -> run_end event trace. - `name` (`string`, required): The unique name of the agent to validate the graph against. Example input: `{"app_id":"","graph_spec":{},"name":"Pro"}` ### `butterbase_ai_config_update` Update AI Config · Write Update an app's AI gateway configuration in Butterbase, such as its default model, its per-request token limit, or its list of allowed models. Returns the updated config object with the app's default model, maximum tokens per request, and allowed models. Use butterbase_ai_config_update to change an app's AI settings; any field left blank is unchanged. Use butterbase_ai_config_get first to see the current configuration. Read only: no. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `app_id` (`string`, required): The id of the Butterbase app whose AI configuration to update. - `allowed_models` (`array`, optional): The full list of model ids this app is allowed to use. Replaces the app's current allow-list. Example: ["openai/gpt-4.1", "anthropic/claude-haiku-4-5"]. - `default_model` (`string`, optional): Model id to use by default for this app's AI requests when no model is specified, e.g. anthropic/claude-haiku-4-5. - `max_tokens_per_request` (`integer`, optional): Maximum number of tokens allowed in a single AI request for this app. Example input: `{"app_id":""}` ### `butterbase_api_key_create` Create Gateway API Key · Write Create a personal Butterbase AI gateway API key with a name and a set of access scopes. Returns the created key's details, including its id, name, scopes, and the key value itself (shown only once). Use butterbase_api_key_create to mint a new gateway key for calling butterbase_gateway_models_list or the AI gateway's chat and embeddings endpoints. This endpoint authenticates with a Butterbase platform user session token (JWT) rather than the general platform API key configured for this connector, so it returns 401 if only a service key is available. Read only: no. Destructive: no. Idempotent (safe to retry): no. Inputs: - `name` (`string`, required): A label for the new API key, to help you identify it later. - `scopes` (`array`, required): Array of access scopes to grant the key, e.g. "ai:gateway" for gateway endpoints only. CONFIRMED via live testing: "*" is a RESERVED_SCOPE and the API rejects it with a 400 -- despite what this endpoint's own docs suggest, there is no known wildcard/full-access scope value; use a specific scope like "ai:gateway" instead. Example input: `{"name":"Pro","scopes":[]}` ### `butterbase_app_access_mode_update` Update App Access Mode · Write Toggle a Butterbase app's access mode between public and authenticated. Returns the app's updated access-mode configuration. Use butterbase_app_access_mode_update for a plain mode toggle. Use butterbase_app_secure instead when switching to authenticated mode should also scaffold default row-level-security policies. Read only: no. Destructive: no. Idempotent (safe to retry): no. Inputs: - `access_mode` (`string`, required): The access mode to set for the app's data API. 'public' allows unauthenticated (butterbase_anon) access; 'authenticated' requires a valid end-user session (butterbase_user) or platform key for every request. One of: `public`, `authenticated`. - `app_id` (`string`, required): The ID of the app to update. Example input: `{"access_mode":"public","app_id":""}` ### `butterbase_app_create` Create App · Write Create a new Butterbase app (project), optionally in a specific region. Returns the new app's app_id, its dedicated API base URL, and the region it was created in. Use butterbase_app_create to provision a fresh backend from scratch. Use butterbase_template_clone instead to start a new app from an existing public template. Read only: no. Destructive: no. Idempotent (safe to retry): no. Inputs: - `name` (`string`, required): A human-readable name for the new app. This becomes the app's display name in the Butterbase dashboard and does not need to be globally unique. - `region` (`string`, optional): The region to create the app's infrastructure in. Must be one of the region identifiers returned by butterbase_regions_list (e.g. us-east-1). If omitted, Butterbase assigns a default region. Example input: `{"name":"Pro"}` ### `butterbase_app_move` Move App · Write Move an existing Butterbase app to a different region. Returns a migration_id and a queued status for tracking the region-move job. Use butterbase_app_move to relocate an app's infrastructure and data; poll butterbase_app_migration_status_get with the returned migration_id to check when the move finishes. Read only: no. Destructive: no. Idempotent (safe to retry): no. Inputs: - `app_id` (`string`, required): The ID of the app to move, as returned by butterbase_app_create or butterbase_apps_list. - `dest_region` (`string`, required): The destination region to move the app to. Must be one of the region identifiers returned by butterbase_regions_list (e.g. us-west-2) and should differ from the app's current region. Example input: `{"app_id":"","dest_region":""}` ### `butterbase_app_secure` Secure App · Write Switch a Butterbase app to authenticated mode and optionally scaffold default row-level-security policies for its tables in one step. Returns a confirmation of the updated access mode and any RLS policies that were created. Use butterbase_app_secure to lock down an app and set up per-user row access together. Use butterbase_app_access_mode_update instead for a plain access-mode toggle with no policy changes. Read only: no. Destructive: no. Idempotent (safe to retry): no. Inputs: - `app_id` (`string`, required): The ID of the app to secure. - `tables` (`array`, optional): Tables to scaffold default row-level-security policies for. Each entry names a table plus the column that stores the owning user's ID, and optionally a boolean column marking rows as publicly readable. Example: [{"table_name": "posts", "user_column": "owner_id", "public_read_column": "is_public"}]. Leave blank to switch to authenticated mode without creating any policies. Example input: `{"app_id":""}` ### `butterbase_app_visibility_update` Update App Visibility · Write Update a Butterbase app's public/private visibility and whether it is listed in the public template gallery. Returns the app's updated visibility configuration. Use butterbase_app_visibility_update to control who can see or clone an app. Use butterbase_app_access_mode_update instead to control whether its data API requires end-user authentication. Read only: no. Destructive: no. Idempotent (safe to retry): no. Inputs: - `app_id` (`string`, required): The ID of the app to update. - `visibility` (`string`, required): The visibility to set for the app. 'public' allows the app to be viewed and, if listed, cloned by others; 'private' restricts it to the owning account. One of: `public`, `private`. - `listed` (`boolean`, optional): Whether the app should be listed in Butterbase's public template gallery. Only meaningful when visibility is 'public'; ignored otherwise. Example input: `{"app_id":"","visibility":"public"}` ### `butterbase_auth_config_cors_update` Update CORS Config · Write Update the list of origins allowed to call a Butterbase app's auth endpoints from a browser (CORS), replacing the current list entirely. Returns the app's updated auth configuration. Use butterbase_auth_config_cors_update to add or remove allowed frontend origins. Use butterbase_auth_config_jwt_update instead to change token lifetimes. Read only: no. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `allowed_origins` (`array`, required): The full list of origins allowed to make browser requests to this app's auth endpoints, replacing whatever is currently configured. Each entry should be a scheme+host(+port) origin, e.g. https://app.example.com. - `app_id` (`string`, required): The unique ID of the Butterbase app to update the CORS configuration for. Example input: `{"allowed_origins":[],"app_id":""}` ### `butterbase_auth_config_jwt_update` Update JWT Config · Write Update how long a Butterbase app's issued access and refresh tokens stay valid before expiring. Returns the app's updated auth configuration. Use butterbase_auth_config_jwt_update to shorten or lengthen token lifetimes. Use butterbase_auth_config_cors_update instead to change allowed browser origins. CONFIRMED via live testing: the wire fields are accessTokenTtl (a duration string like "30m") and refreshTokenTtlDays (an integer number of days) -- earlier field names/types (accessTokenTtlSeconds/refreshTokenTtlSeconds as plain integers) were silently ignored by the API and are no longer used. Read only: no. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `app_id` (`string`, required): The unique ID of the Butterbase app to update token lifetime settings for. - `access_token_ttl` (`string`, optional): How long a newly issued access token stays valid before it must be refreshed, as a duration string (e.g. "30m", "1h", "15m"). CONFIRMED via live testing: the real wire field is accessTokenTtl taking a duration string -- NOT a plain integer of seconds as earlier assumed. Omit to leave the current value unchanged. - `refresh_token_ttl_days` (`integer`, optional): How many days a newly issued refresh token stays valid. CONFIRMED via live testing: the real wire field is refreshTokenTtlDays taking an integer number of days -- NOT seconds as earlier assumed. Omit to leave the current value unchanged. Example input: `{"app_id":""}` ### `butterbase_auth_config_pause` Pause Auth · Write Pause or resume all authentication activity for a Butterbase app, blocking every sign-up, login, magic-link, and token request while paused. Returns a confirmation of the app's updated pause state (exact response fields are not published in Butterbase's docs). Use this to immediately halt auth traffic during an incident or maintenance window, then call it again with paused set to false to resume normal operation. Read only: no. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `app_id` (`string`, required): The unique identifier of the Butterbase app whose authentication should be paused or resumed. - `paused` (`boolean`, required): Whether to pause (true) or resume (false) authentication for this app. When paused, all sign-up, login, magic-link, and token-refresh requests are rejected. - `reason` (`string`, optional): Optional free-text note explaining why authentication is being paused or resumed, for audit purposes. Example input: `{"app_id":"","paused":true}` ### `butterbase_auth_forgot_password` Request Password Reset · Write Request a password-reset code for an end-user's email on a Butterbase app. Returns a confirmation message; Butterbase's docs do not distinguish the response for registered vs. unregistered emails. Use butterbase_auth_forgot_password to start a password-reset flow, then use the resulting code with butterbase_auth_reset_password to set a new password. Read only: no. Destructive: no. Idempotent (safe to retry): no. Inputs: - `app_id` (`string`, required): The Butterbase app's unique ID the end-user belongs to. - `email` (`string`, required): The end-user's email address to send the password-reset code to. Example input: `{"app_id":"","email":""}` ### `butterbase_auth_login` Log In End User · Write Sign in an existing end-user with their email and password. Returns an access token, a refresh token, and the user's profile (id, email, verification status, display name, avatar URL). Use butterbase_auth_login for password-based sign-in. Use butterbase_auth_signup to create a new account first, or butterbase_auth_magic_link_request/butterbase_auth_magic_link_verify for passwordless sign-in. Read only: no. Destructive: no. Idempotent (safe to retry): no. Inputs: - `app_id` (`string`, required): The Butterbase app's unique ID to sign the end-user into. - `email` (`string`, required): The end-user's email address used to sign in. - `password` (`string`, required): The end-user's current account password. Example input: `{"app_id":"","email":"","password":""}` ### `butterbase_auth_logout` Log Out End User · Write End an end-user's current session for a Butterbase app. Returns a confirmation that the session was ended. Use butterbase_auth_logout to invalidate an end-user's active access token, for example after a sign-out action in your app. CONFIRMED via a dedicated live investigation: the underlying Butterbase endpoint works correctly and returns a genuine success when called with a valid end-user access token (obtained via butterbase_auth_login) -- this was previously only ever tested with the wrong credential type (this connector's platform key), which always 401s. HOWEVER, this connector has no way to actually supply that end-user token: Scalekit's execution engine controls the Authorization header for a BEARER connection server-side and rejects a client-supplied Authorization header override outright (confirmed via direct SDK-level testing -- a custom header is rejected with its own 401 before ever reaching Butterbase). This tool will therefore always fail via the standard execution path on this connector, by platform design, not due to a fixable tool-JSON defect -- it would need a future Scalekit auth-strategy feature (e.g. a per-call token override) to ever work through this connector. Read only: no. Destructive: no. Idempotent (safe to retry): no. Inputs: - `access_token` (`string`, required): The end-user's current access token to invalidate. Butterbase's docs describe this endpoint as requiring the token as a Bearer Authorization header; this tool sends it as a JSON body field instead, since this connection's Authorization header already carries the platform API key. - `app_id` (`string`, required): The Butterbase app's unique ID the session belongs to. Example input: `{"access_token":"","app_id":""}` ### `butterbase_auth_magic_link_request` Request Magic Link · Write Send a one-time sign-in code to an end-user's email for a Butterbase app. Returns a generic confirmation message that is identical whether or not the email is registered, to prevent account enumeration. Use butterbase_auth_magic_link_request to start passwordless sign-in, then call butterbase_auth_magic_link_verify with the code the user receives. Read only: no. Destructive: no. Idempotent (safe to retry): no. Inputs: - `app_id` (`string`, required): The Butterbase app's unique ID to send the magic-link code for. - `email` (`string`, required): The end-user's email address to send the one-time sign-in code to. Example input: `{"app_id":"","email":""}` ### `butterbase_auth_magic_link_verify` Verify Magic Link · Write Verify a magic-link sign-in code and issue session tokens for an end-user. Returns an access token, a refresh token, and the user's profile; verifying a code for the first time also creates the user account automatically. Use butterbase_auth_magic_link_verify after butterbase_auth_magic_link_request has emailed the user a code. The code expires 15 minutes after it was sent. Read only: no. Destructive: no. Idempotent (safe to retry): no. Inputs: - `app_id` (`string`, required): The Butterbase app's unique ID the magic-link code was requested for. - `code` (`string`, required): The 6-digit one-time sign-in code sent to the user's email. Expires 15 minutes after it was requested. - `email` (`string`, required): The email address the magic-link code was sent to. Example input: `{"app_id":"","code":"","email":""}` ### `butterbase_auth_oauth_config_create` Create OAuth Provider Config · Write Register a social-login (OAuth) provider configuration for a Butterbase app, so end-users can sign in with that provider. Returns the created provider configuration, including the provider name, client ID, redirect URIs, and any extra provider metadata. Use butterbase_auth_oauth_config_create to add a new social-login provider. Use butterbase_auth_oauth_config_update to change an existing one instead of creating a duplicate. Read only: no. Destructive: no. Idempotent (safe to retry): no. Inputs: - `app_id` (`string`, required): The unique ID of the Butterbase app to configure the provider for. - `client_id` (`string`, required): The OAuth client ID issued by the provider for your application. - `client_secret` (`string`, required): The OAuth client secret issued by the provider for your application. Stored by Butterbase and not returned in plain text on later reads. - `provider` (`string`, required): The OAuth provider identifier to configure. Butterbase ships built-in support for google, github, discord, facebook, linkedin, microsoft, apple, and x, and also accepts a custom provider identifier for other OpenID-compatible providers your app already defines. - `redirect_uris` (`array`, required): The list of redirect (callback) URIs Butterbase is allowed to send this provider's authorization response to. Must match what's registered in the provider's developer console. - `provider_metadata` (`object`, optional): Extra provider-specific configuration some providers need beyond client_id/client_secret. For example, Apple's Sign in with Apple requires teamId, keyId, and privateKey here. Omit for providers that don't need extra configuration. Example input: `{"app_id":"","client_id":"","client_secret":"","provider":"","redirect_uris":[]}` ### `butterbase_auth_oauth_config_update` Update OAuth Provider Config · Write Update the configuration for one social-login (OAuth) provider on a Butterbase app. Only the fields you supply are changed; anything omitted keeps its current value. Returns the updated provider configuration object. Use butterbase_auth_oauth_config_update to rotate a client secret or change redirect URIs. Use butterbase_auth_oauth_config_create instead to add a brand-new provider. Read only: no. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `app_id` (`string`, required): The unique ID of the Butterbase app the provider is configured on. - `provider` (`string`, required): The OAuth provider identifier to update, e.g. one of google, github, discord, facebook, linkedin, microsoft, apple, x, or a custom provider identifier. - `client_id` (`string`, optional): New OAuth client ID for this provider. Omit to leave the current client ID unchanged. - `client_secret` (`string`, optional): New OAuth client secret for this provider. Omit to leave the current client secret unchanged. - `provider_metadata` (`object`, optional): New provider-specific metadata (e.g. Apple's teamId, keyId, privateKey), replacing the current metadata entirely. Omit to leave the current metadata unchanged. - `redirect_uris` (`array`, optional): New list of redirect (callback) URIs for this provider, replacing the current list entirely. Omit to leave the current redirect URIs unchanged. Example input: `{"app_id":"","provider":""}` ### `butterbase_auth_refresh` Refresh Access Token · Write Exchange an end-user's refresh token for a new access token. Returns a new access token for continuing the user's session. Use butterbase_auth_refresh when a previously issued end-user access token has expired, instead of asking the user to sign in again. Read only: no. Destructive: no. Idempotent (safe to retry): no. Inputs: - `app_id` (`string`, required): The Butterbase app's unique ID the refresh token was issued for. - `refresh_token` (`string`, required): The end-user's refresh token, previously issued by signup, login, or magic-link verification. Butterbase's docs do not confirm whether this is expected as a request body field or an Authorization header for this endpoint; this tool sends it as a JSON body field since this connection's Authorization header already carries the platform API key. Example input: `{"app_id":"","refresh_token":""}` ### `butterbase_auth_reset_password` Reset Password · Write Reset an end-user's password in a Butterbase app using the reset code that was emailed to them. Returns a success confirmation once the password has been updated. Use butterbase_auth_reset_password to complete a reset after the user has already requested a reset code. Use butterbase_auth_me_get afterward to confirm the account is reachable with the new credentials. Read only: no. Destructive: no. Idempotent (safe to retry): no. Inputs: - `app_id` (`string`, required): The unique ID of the Butterbase app the end-user account belongs to. - `code` (`string`, required): The password-reset code Butterbase emailed to the user after they requested a reset. Codes are short-lived and single-use. - `email` (`string`, required): The email address of the end-user account whose password is being reset. Confirmed required by the live API (not previously documented). - `password` (`string`, required): The new password to set for the account. Must be at least 8 characters and include an uppercase letter, a lowercase letter, a number, and a special character. Example input: `{"app_id":"","code":"","email":"","password":""}` ### `butterbase_auth_signup` Sign Up End User · Write Register a new end-user with an email and password for a Butterbase app. Returns an access token, a refresh token, and the new user's profile (id, email, verification status, display name, avatar URL). Use butterbase_auth_signup to create a brand-new end-user account. Use butterbase_auth_login for an existing user, or butterbase_auth_magic_link_request to sign a user in without a password. Read only: no. Destructive: no. Idempotent (safe to retry): no. Inputs: - `app_id` (`string`, required): The Butterbase app's unique ID to register the new end-user under. - `email` (`string`, required): The new end-user's email address, used as their unique sign-in identifier. - `password` (`string`, required): The new end-user's password. Must be at least 8 characters and include an uppercase letter, a lowercase letter, a number, and a special character. - `display_name` (`string`, optional): An optional display name to store on the new user's profile. Example input: `{"app_id":"","email":"","password":""}` ### `butterbase_auth_verify_email` Verify Email Address · Write Verify an end-user's email address using the verification code they were sent. Returns a confirmation that the email address has been verified. Use butterbase_auth_verify_email after a user signs up, to mark their email address as verified. Read only: no. Destructive: no. Idempotent (safe to retry): no. Inputs: - `app_id` (`string`, required): The Butterbase app's unique ID the end-user belongs to. - `code` (`string`, required): The email verification code sent to the end-user, typically after signup. - `email` (`string`, required): The email address of the end-user account being verified. Confirmed required by the live API (not previously documented). Example input: `{"app_id":"","code":"","email":""}` ### `butterbase_billing_checkout_create` Start Billing Checkout · Write Start a checkout session to upgrade the Butterbase platform account's plan. Returns the checkout session details, including a URL to redirect the account owner to so they can complete the upgrade. Use butterbase_billing_checkout_create to begin a plan upgrade. Use butterbase_billing_portal_create to open the account's existing self-serve billing portal instead. CONFIRMED via live testing: the underlying endpoint requires a plan_id (wire name planId) in the request body and rejects requests without it -- Butterbase's public docs do not document this field. Read only: no. Destructive: no. Idempotent (safe to retry): no. Inputs: - `plan_id` (`string`, required): The ID of the plan to check out for the platform account upgrade. CONFIRMED via live testing: the underlying endpoint requires this field (wire name planId) and rejects requests without it -- Butterbase's docs do not publish this requirement. Example input: `{"plan_id":""}` ### `butterbase_billing_connect_onboard` Start Stripe Connect Onboarding · Write Start Stripe Connect onboarding for a Butterbase app so it can accept and process payments from its own end users. Returns onboarding session details, including a URL to redirect the app owner to so they can complete Stripe's onboarding flow. Use butterbase_billing_connect_onboard to begin or resume onboarding for an app. Use butterbase_billing_connect_status_get to check whether onboarding is already complete instead. Butterbase's docs don't publish a request body for this endpoint, so only the app ID is required. Read only: no. Destructive: no. Idempotent (safe to retry): no. Inputs: - `app_id` (`string`, required): The Butterbase app ID to start Stripe Connect onboarding for, found in the app's dashboard URL or settings. Example input: `{"app_id":""}` ### `butterbase_billing_plan_create` Create Subscription Plan · Write Create a subscription plan that a Butterbase app's end users can subscribe to. Returns the created plan object, including its assigned ID, name, price, billing interval, and feature list. Use butterbase_billing_plan_create to add a new subscription tier for an app's monetization. Requires the app to already exist — create it first with butterbase_app_create if you haven't. Read only: no. Destructive: no. Idempotent (safe to retry): no. Inputs: - `app_id` (`string`, required): The Butterbase app ID to create the plan under, found in the app's dashboard URL or settings. - `features` (`array`, required): A list of feature strings describing what this plan includes, shown to end users on a pricing page. - `interval` (`string`, required): The billing interval this plan recurs on, such as "month" or "year". Butterbase's docs show "month" as the example value but don't enumerate every accepted interval, so pass the value the account's Stripe-based billing setup expects. - `name` (`string`, required): The subscription plan's display name, shown to end users when they choose a plan. - `price_cents` (`integer`, required): The plan's recurring price in cents (integer), in the account's billing currency. For example, 999 for $9.99 per billing interval. Example input: `{"app_id":"","features":[],"interval":"month","name":"Pro","price_cents":1900}` ### `butterbase_billing_plan_update` Update Subscription Plan · Write Update an existing subscription plan for a Butterbase app, replacing its name, price, billing interval, and feature list. Returns the updated plan object with its id, name, price, interval, and features. Use butterbase_billing_plan_update to change a plan's details after finding its plan_id with butterbase_billing_plans_list. Butterbase's docs page doesn't show a distinct example for this endpoint's request body; it's presumed to require the same full payload as creating a plan, and it's unconfirmed whether partial updates are supported, so this tool always resends every field. Read only: no. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `app_id` (`string`, required): The unique ID of the Butterbase app that owns the plan being updated. - `features` (`array`, required): The list of feature strings included in this plan, e.g. ["Unlimited projects", "Priority support"]. Required because Butterbase's update endpoint is presumed to need the full plan payload, not a partial patch. - `interval` (`string`, required): The billing interval for this plan, e.g. "month" or "year". Required because Butterbase's update endpoint is presumed to need the full plan payload, not a partial patch. - `name` (`string`, required): The plan's display name shown to end users, e.g. "Pro" or "Team". Required because Butterbase's update endpoint is presumed to need the full plan payload, not a partial patch. - `plan_id` (`string`, required): The unique ID of the subscription plan to update. Look this up from a prior call to butterbase_billing_plans_list. - `price_cents` (`integer`, required): The plan's price in cents as an integer, e.g. 1900 for $19.00. Required because Butterbase's update endpoint is presumed to need the full plan payload, not a partial patch. Example input: `{"app_id":"","features":[],"interval":"month","name":"Pro","plan_id":"","price_cents":1900}` ### `butterbase_billing_portal_create` Open Billing Portal · Write Open the Butterbase platform account's billing portal, where the account owner can manage payment methods, view invoices, and change plans. Returns the portal session details, including a URL to redirect the account owner to. Use butterbase_billing_portal_create to send an account owner to self-serve billing management. Use butterbase_billing_checkout_create to start a specific plan upgrade instead. Butterbase's docs don't publish a request body for this endpoint, so no input is sent. Read only: no. Destructive: no. Idempotent (safe to retry): no. Inputs: none. Example input: `{}` ### `butterbase_billing_product_create` Create Product · Write Create a one-time-purchase product for a Butterbase app's end users, such as a credits pack or a premium add-on. Returns the created product object with its id, name, price, description, and metadata. Use butterbase_billing_product_create to add a new purchasable product. Use butterbase_billing_products_list to see existing products, or butterbase_billing_product_update to change one afterward. Read only: no. Destructive: no. Idempotent (safe to retry): no. Inputs: - `app_id` (`string`, required): The unique ID of the Butterbase app the product belongs to. - `description` (`string`, required): A short description of what the end user gets when they purchase this product, e.g. "500 in-app credits, added instantly on purchase." - `name` (`string`, required): The product's display name shown to end users, e.g. "500 Credits" or "Pro Add-on". - `price_cents` (`integer`, required): The product's price in cents as an integer, e.g. 999 for $9.99. - `metadata` (`object`, optional): Optional custom key/value pairs to attach to the product, e.g. {"sku": "credits-500"}. Not returned in a specific documented shape by Butterbase -- pass any flat JSON object of your own metadata. Example input: `{"app_id":"","description":"500 in-app credits, added instantly on purchase.","name":"500 Credits","price_cents":999}` ### `butterbase_billing_product_update` Update Product · Write Update an existing one-time-purchase product for a Butterbase app, replacing its name, price, description, and metadata. Returns the updated product object with its id, name, price, description, and metadata. Use butterbase_billing_product_update to change a product's details after finding its product_id with butterbase_billing_products_list. Butterbase's docs page doesn't show a distinct example for this endpoint's request body; it's presumed to require the same full payload as creating a product, and it's unconfirmed whether partial updates are supported, so this tool always resends the core fields. Read only: no. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `app_id` (`string`, required): The unique ID of the Butterbase app that owns the product being updated. - `description` (`string`, required): A short description of what the end user gets when they purchase this product, e.g. "500 in-app credits, added instantly on purchase." Required because Butterbase's update endpoint is presumed to need the same full payload as creating a product. - `name` (`string`, required): The product's display name shown to end users, e.g. "500 Credits" or "Pro Add-on". Required because Butterbase's update endpoint is presumed to need the same full payload as creating a product. - `price_cents` (`integer`, required): The product's price in cents as an integer, e.g. 999 for $9.99. Required because Butterbase's update endpoint is presumed to need the same full payload as creating a product. - `product_id` (`string`, required): The unique ID of the product to update. Look this up from a prior call to butterbase_billing_products_list. - `metadata` (`object`, optional): Optional custom key/value pairs to attach to the product, e.g. {"sku": "credits-500"}. Pass any flat JSON object of your own metadata; omit to leave metadata unset. Example input: `{"app_id":"","description":"500 in-app credits, added instantly on purchase.","name":"500 Credits","price_cents":999,"product_id":""}` ### `butterbase_billing_purchase` Purchase Product · Write Purchase one of a Butterbase app's one-time-purchase products for the current end user. Returns a purchase confirmation with order details for the completed purchase. Use butterbase_billing_purchase to buy a product found with butterbase_billing_products_list. Use butterbase_billing_orders_list afterward to see the resulting order in the current end user's order history. Butterbase's docs page doesn't publish the exact request body for this endpoint; product_id (sent as productId) is this tool's best-effort inference from the product identifiers used elsewhere in the Billing API, and is not confirmed against Butterbase's own documentation. Read only: no. Destructive: no. Idempotent (safe to retry): no. Inputs: - `app_id` (`string`, required): The unique ID of the Butterbase app the product belongs to. - `product_id` (`string`, required): The ID of the product to purchase for the current end user, from butterbase_billing_products_list. This field name is a best-effort inference -- Butterbase's docs do not show the exact request body for this endpoint. Example input: `{"app_id":"","product_id":""}` ### `butterbase_billing_subscribe` Start Subscription · Write Start a subscription for the current end user to one of a Butterbase app's subscription plans. Returns the subscription session or confirmation returned by Butterbase for the new subscription. Use butterbase_billing_subscribe to enroll the current end user in a plan found with butterbase_billing_plans_list. Use butterbase_billing_subscription_get afterward to confirm the subscription is active, or butterbase_billing_cancel to end it later. Butterbase's docs page doesn't publish the exact request body for this endpoint; plan_id (sent as planId) is this tool's best-effort inference from the plan identifiers used elsewhere in the Billing API, and is not confirmed against Butterbase's own documentation. Read only: no. Destructive: no. Idempotent (safe to retry): no. Inputs: - `app_id` (`string`, required): The unique ID of the Butterbase app the plan belongs to. - `plan_id` (`string`, required): The ID of the subscription plan to subscribe the current end user to, from butterbase_billing_plans_list. This field name is a best-effort inference -- Butterbase's docs do not show the exact request body for this endpoint. Example input: `{"app_id":"","plan_id":""}` ### `butterbase_chat_completions_create` Create Chat Completion · Write Create an OpenAI-compatible chat completion using the AI models available to one Butterbase app. Returns a single OpenAI-shaped completion object with the model's reply and token usage; streaming responses are not supported through this tool, so the request always executes and returns as a single non-streaming JSON response. Use butterbase_chat_completions_create to bill usage against a specific app. Use butterbase_gateway_chat_completions_create for a personal gateway key that isn't tied to an app. Read only: no. Destructive: no. Idempotent (safe to retry): no. Inputs: - `app_id` (`string`, required): The Butterbase app ID to bill this completion's usage against. - `messages` (`array`, required): The conversation so far, as an array of messages each with a role (system, user, or assistant) and text content. Example: [{"role": "user", "content": "What is the capital of France?"}]. - `model` (`string`, required): The AI model identifier to use, e.g. openai/gpt-4o-mini or anthropic/claude-haiku-4-5. See butterbase_ai_models_list for the models allowed for this app. - `max_tokens` (`integer`, optional): The maximum number of tokens to generate in the completion. Omit to let the model use its default limit. - `temperature` (`number`, optional): Sampling temperature between 0 and 2. Lower values (e.g. 0.2) make output more deterministic; higher values (e.g. 1.2) make it more random. Omit to use the model's default. Example input: `{"app_id":"","messages":[{"role":"user","content":"What is the capital of France?"}],"model":""}` ### `butterbase_clone_job_retry` Retry Clone Job · Write Retry a template clone job that previously failed, using its clone job id. Returns the clone job's updated status after the retry has been queued. Use butterbase_clone_job_retry after butterbase_clone_job_get shows a failed job. Poll butterbase_clone_job_get again afterward to track the retry. Read only: no. Destructive: no. Idempotent (safe to retry): no. Inputs: - `job_id` (`string`, required): The id of the failed clone job to retry, as returned by butterbase_template_clone or a prior butterbase_clone_job_get check. Example input: `{"job_id":""}` ### `butterbase_custom_domain_create` Add Custom Domain · Write Register a custom domain for a frontend deployment. Returns a domain object (id, hostname, verification status, SSL status) plus the CNAME target to point DNS at and setup instructions. Use butterbase_custom_domain_create to add a new domain to an app, then configure the returned CNAME record with your DNS provider and check butterbase_custom_domains_list to confirm it registered. Read only: no. Destructive: no. Idempotent (safe to retry): no. Inputs: - `app_id` (`string`, required): The Butterbase app to register the custom domain for, exactly as shown in the Butterbase dashboard or returned when the app was created. - `hostname` (`string`, required): The exact custom domain name to register for the app's frontend deployment, e.g. app.example.com. Example input: `{"app_id":"","hostname":""}` ### `butterbase_custom_domain_verify` Verify Custom Domain · Write Re-trigger verification for a custom domain registered to a Butterbase app. Returns the domain's verification and SSL status once Cloudflare re-checks the DNS configuration. Use butterbase_custom_domain_verify after updating a domain's DNS records or when butterbase_custom_domain_status_get still shows a pending status; register the domain first with butterbase_custom_domain_create. Read only: no. Destructive: no. Idempotent (safe to retry): no. Inputs: - `app_id` (`string`, required): The unique identifier of the Butterbase app the custom domain is registered to. - `id` (`string`, required): The unique identifier of the custom domain to re-verify, as returned when the domain was registered. Example input: `{"app_id":"","id":""}` ### `butterbase_embeddings_create` Create Embeddings · Write Generate text embedding vectors using the AI models available to one Butterbase app. Returns a JSON object containing the embedding vector(s) for the given input text. Use butterbase_embeddings_create to bill usage against a specific app. Use butterbase_gateway_embeddings_create for a personal gateway key that isn't tied to an app. Read only: no. Destructive: no. Idempotent (safe to retry): no. Inputs: - `app_id` (`string`, required): The Butterbase app ID to bill this embeddings call's usage against. - `input` (`string`, required): The text to embed. Provide a single string, or an array of strings to embed several pieces of text in one call. - `model` (`string`, required): The embedding model identifier to use, e.g. openai/text-embedding-3-small (1536 dimensions), openai/text-embedding-3-large (3072 dimensions), or openai/text-embedding-ada-002 (1536 dimensions). - `encoding_format` (`string`, optional): The format to return the embedding vectors in: float (a JSON array of numbers) or base64 (a base64-encoded string). Defaults to float if omitted. One of: `float`, `base64`. Example input: `{"app_id":"","input":"","model":""}` ### `butterbase_frontend_deployment_create` Create Frontend Deployment · Write Create a new frontend deployment for a Butterbase app and get a presigned URL to upload its build. Returns the new deployment's id, a short-lived presigned uploadUrl, the URL's expiry in seconds, and the maximum allowed upload size in bytes. Use butterbase_frontend_deployment_create to start deploying a static site or SPA build. Uploading the build itself is a separate raw-binary PUT of a zip file straight to the returned uploadUrl and is not part of this tool; do that afterward with your own HTTP client, then start the build via the deployment's start endpoint. Read only: no. Destructive: no. Idempotent (safe to retry): no. Inputs: - `app_id` (`string`, required): The unique identifier of the Butterbase app to create the frontend deployment for. - `framework` (`string`, required): The frontend framework/build type of the deployment being created, one of react-vite, nextjs-static, static, or other. One of: `react-vite`, `nextjs-static`, `static`, `other`. Example input: `{"app_id":"","framework":"react-vite"}` ### `butterbase_frontend_deployment_start` Start Frontend Deployment · Write Start the build and publish process for a frontend deployment whose zip file has already been uploaded to its presigned upload URL. Returns the deployment's updated status once the build begins; Butterbase's docs do not publish the exact response fields for this endpoint. Use butterbase_frontend_deployment_start right after the zip upload to the presigned URL finishes. Use butterbase_frontend_deployment_get or butterbase_frontend_deployment_sync afterward to track progress toward READY or ERROR. Requires an existing deployment id whose zip has already been uploaded to the presigned URL returned when the deployment was created. Read only: no. Destructive: no. Idempotent (safe to retry): no. Inputs: - `app_id` (`string`, required): The Butterbase app that owns the frontend deployment, exactly as shown in the Butterbase dashboard or returned when the app was created. - `id` (`string`, required): The unique identifier of the frontend deployment to start building, as returned when the deployment record was created (POST /v1/{app_id}/frontend/deployments). Example input: `{"app_id":"","id":""}` ### `butterbase_frontend_deployment_sync` Sync Frontend Deployment Status · Write Force a refresh of a frontend deployment's status. Returns the deployment's refreshed status; exact response fields are not published in Butterbase's docs. Use butterbase_frontend_deployment_sync when a deployment appears stuck in BUILDING or UPLOADING and you want an immediate status check instead of waiting for Butterbase's normal async update. Use butterbase_frontend_deployment_get for a plain read without forcing a refresh. Read only: no. Destructive: no. Idempotent (safe to retry): no. Inputs: - `app_id` (`string`, required): The Butterbase app that owns the frontend deployment, exactly as shown in the Butterbase dashboard or returned when the app was created. - `id` (`string`, required): The unique identifier of the frontend deployment whose status to force-refresh. Example input: `{"app_id":"","id":""}` ### `butterbase_frontend_env_update` Replace Frontend Environment Variables · Write Set or update a frontend deployment's environment variables. Butterbase encrypts every value at rest and never returns it via the API -- only variable key names are returned, and only by butterbase_frontend_env_get; the exact response shape for this endpoint isn't published in Butterbase's docs. Use butterbase_frontend_env_update to set build-time environment variables (e.g. VITE_API_URL, NEXT_PUBLIC_API_KEY) a deployment should use. CORRECTED via live testing: despite this being a PUT endpoint, the underlying API does NOT fully replace the variable set -- omitted keys are NOT removed, they are merged/kept as-is. There is currently no confirmed working way to delete an existing key through this endpoint (an empty object is rejected with a 400, and a null value causes a 500) -- if you need to remove a variable, contact Butterbase support or use their dashboard. Use butterbase_frontend_env_get beforehand if you need to see which keys are already set, since their values are never shown. Read only: no. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `app_id` (`string`, required): The Butterbase app whose frontend deployment environment variables to replace, exactly as shown in the Butterbase dashboard or returned when the app was created. - `env_vars` (`object`, required): Flat JSON object mapping environment variable names to their string values. Each key sets or updates one environment variable for the app's frontend deployment build. CORRECTED via live testing: keys you leave out are NOT removed (this is a merge, not a full replace, despite the PUT method) -- there is no confirmed way to delete a key via this endpoint. Example: {"VITE_API_URL": "https://api.butterbase.ai/v1/app_abc123", "NEXT_PUBLIC_API_KEY": "pk_test_123"}. Example input: `{"app_id":"","env_vars":{"VITE_API_URL":"https://api.butterbase.ai/v1/app_abc123","NEXT_PUBLIC_API_KEY":"pk_test_123"}}` ### `butterbase_function_deploy` Deploy Function · Write Deploy a new serverless function to an app, or redeploy an existing one under the same name with new code or settings. Returns the deployed function's stored configuration, including its triggers, resource limits, and agent-tool settings. Use butterbase_function_deploy to publish a function's source code. Use butterbase_functions_list to check whether a name is already taken, butterbase_function_get to inspect a deployed function's current settings and metrics, and butterbase_function_invoke to test it once deployed. Read only: no. Destructive: no. Idempotent (safe to retry): no. Inputs: - `app_id` (`string`, required): The Butterbase application ID to deploy this function to. - `code` (`string`, required): The function's full source code, including a default export handler that Butterbase invokes on each trigger event. - `name` (`string`, required): A unique name for this function within the app, 1-100 characters. Deploying again with the same name updates that function's code and settings in place. - `agent_tool` (`boolean`, optional): Whether to expose this function as a tool an AI agent can call. Default: `false`. - `agent_tool_description` (`string`, optional): A description of this function shown to the LLM when it decides whether to call it as a tool, up to 500 characters. Only used when agent_tool is true. - `agent_tool_exposed_to` (`string`, optional): Who may invoke this function as an agent tool: developer_only restricts it to the app's own developers/API keys, while end_user also allows the app's end users to trigger it through an agent. Only used when agent_tool is true. Defaults to developer_only. One of: `developer_only`, `end_user`. Default: `developer_only`. - `agent_tool_mode` (`string`, optional): Controls whether an agent calling this function as a tool may only read data (read_only) or may also make changes (read_write). Only used when agent_tool is true. Defaults to read_only. One of: `read_only`, `read_write`. Default: `read_only`. - `allow_service_key_impersonation` (`boolean`, optional): Whether the function accepts the X-Butterbase-As-User header, which lets a caller using a platform API key impersonate a specific end user for this invocation. Defaults to true. Default: `true`. - `description` (`string`, optional): A short human-readable description of what this function does, shown in the Butterbase dashboard. - `env_vars` (`object`, optional): Environment variables to set on the function, as a flat object of key/value string pairs. Values are stored encrypted and injected into the function's runtime environment. Example: {"API_KEY": "sk_live_..."}. - `memory_limit_mb` (`integer`, optional): Memory limit for the function in megabytes, between 64 and 1024. Defaults to 128 if omitted. Default: `128`. - `timeout_ms` (`integer`, optional): Maximum execution time for the function in milliseconds, up to 300000 (5 minutes). Defaults to 30000 (30 seconds) if omitted. Default: `30000`. - `triggers` (`array`, optional): Trigger configurations controlling how this function gets invoked. Each trigger needs a type -- http, cron, s3_upload, webhook, or websocket -- plus the settings that type needs: an http trigger can specify a method, path, and whether auth is required (defaults to required; use none for a public route); a cron trigger needs a schedule and an optional timezone (UTC by default); an s3_upload trigger fires when an object lands in a bucket, with an optional key prefix and content-type filter; a webhook trigger generates a signed URL and can require a shared secret or restrict allowed sources; a websocket trigger takes no extra settings. If omitted, the function gets a single default HTTP trigger. Example: [{"type": "http", "method": "POST", "auth": "required"}]. Example input: `{"app_id":"","code":"","name":"Pro"}` ### `butterbase_function_env_update` Update Function Environment Variables · Write Update a Butterbase serverless function's encrypted environment variables, merging the given key/value pairs into its existing set rather than replacing it. Returns the function's full, updated set of environment variable keys. Use butterbase_function_env_update to add or change one or more variables, or to remove a variable by setting its value to null. Use butterbase_function_deploy to redeploy the function's code or reset its entire environment instead. Read only: no. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `app_id` (`string`, required): The Butterbase app ID that owns the function, found in the app's dashboard URL or settings. - `env_vars` (`object`, required): A JSON object of environment variable key/value pairs to merge into the function's existing environment. Values must be strings, except to delete an existing key: set its value to null and it is removed instead of merged. Example: {"API_KEY": "sk_live_123", "OLD_KEY": null} sets API_KEY and deletes OLD_KEY, while leaving every other existing variable untouched. - `name` (`string`, required): The unique name of the deployed function whose environment variables you want to change. Example input: `{"app_id":"","env_vars":{"API_KEY":"sk_live_123","OLD_KEY":null},"name":"Pro"}` ### `butterbase_function_invoke` Invoke Function · Write Test-invoke a deployed serverless function directly, without going through its normal trigger (e.g. its HTTP route or schedule). Returns whatever the function's own handler code returns for that invocation. Use butterbase_function_invoke to try out a function after deploying it, or to debug its behavior with a specific payload. Use butterbase_function_get to check the function's recent error rate and average duration instead of invoking it again. Read only: no. Destructive: no. Idempotent (safe to retry): no. Inputs: - `app_id` (`string`, required): The Butterbase application ID the function belongs to. - `name` (`string`, required): The exact name of the deployed function to invoke. - `payload` (`object`, optional): Arbitrary JSON payload sent as the request body of the test invocation, forwarded to the function's handler as its invocation input. Butterbase's docs don't publish a fixed schema for this -- send whatever shape your function's own handler code expects to receive. Leave blank to invoke with an empty body. Example input: `{"app_id":"","name":"Pro"}` ### `butterbase_function_settings_update` Update Function Settings · Write Toggle a Butterbase serverless function's runtime settings without redeploying its code. Returns the function's updated settings; the function's runtime cache is invalidated so the new setting takes effect on the next invocation. Use butterbase_function_settings_update to flip a runtime toggle only. Use butterbase_function_deploy to redeploy code or change trigger, timeout, or memory configuration instead. Read only: no. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `app_id` (`string`, required): The Butterbase app ID that owns the function, found in the app's dashboard URL or settings. - `name` (`string`, required): The unique name of the deployed function whose settings you want to change. - `allow_service_key_impersonation` (`boolean`, optional): Whether this function accepts the X-Butterbase-As-User impersonation header when invoked with the platform service key, letting a backend call act on behalf of a specific end user. Set to true to allow it, false to block it. Omit to leave the current setting unchanged. Example input: `{"app_id":"","name":"Pro"}` ### `butterbase_gateway_chat_completions_create` Create Gateway Chat Completion · Write Create an OpenAI-compatible chat completion using a personal Butterbase AI gateway API key, independent of any specific app. Returns a single OpenAI-shaped completion object with the model's reply and token usage; streaming responses are not supported through this tool, so the request always executes and returns as a single non-streaming JSON response. Use butterbase_gateway_chat_completions_create for personal, gateway-key usage. Use butterbase_chat_completions_create to bill usage against a specific app. Read only: no. Destructive: no. Idempotent (safe to retry): no. Inputs: - `messages` (`array`, required): The conversation so far, as an array of messages each with a role (system, user, or assistant) and text content. Example: [{"role": "user", "content": "What is the capital of France?"}]. - `model` (`string`, required): The AI model identifier to use, e.g. openai/gpt-4o-mini or anthropic/claude-haiku-4-5. - `max_tokens` (`integer`, optional): The maximum number of tokens to generate in the completion. Omit to let the model use its default limit. - `temperature` (`number`, optional): Sampling temperature between 0 and 2. Lower values (e.g. 0.2) make output more deterministic; higher values (e.g. 1.2) make it more random. Omit to use the model's default. Example input: `{"messages":[{"role":"user","content":"What is the capital of France?"}],"model":""}` ### `butterbase_gateway_embeddings_create` Create Gateway Embeddings · Write Generate text embedding vectors using a personal Butterbase AI gateway API key, independent of any specific app. Returns a JSON object containing the embedding vector(s) for the given input text. Use butterbase_gateway_embeddings_create for personal, gateway-key usage. Use butterbase_embeddings_create to bill usage against a specific app. Read only: no. Destructive: no. Idempotent (safe to retry): no. Inputs: - `input` (`string`, required): The text to embed. Provide a single string, or an array of strings to embed several pieces of text in one call. - `model` (`string`, required): The embedding model identifier to use, e.g. openai/text-embedding-3-small (1536 dimensions), openai/text-embedding-3-large (3072 dimensions), or openai/text-embedding-ada-002 (1536 dimensions). - `encoding_format` (`string`, optional): The format to return the embedding vectors in: float (a JSON array of numbers) or base64 (a base64-encoded string). Defaults to float if omitted. One of: `float`, `base64`. Example input: `{"input":"","model":""}` ### `butterbase_image_generation_create` Create Image Generation Job · Write Submit an asynchronous AI image-generation job for a Butterbase app. Returns a job object with a job_id, a pending status, and a polling_url. Use butterbase_image_generation_create to start generating one or more images from a text prompt, then poll butterbase_image_generation_get with the returned job_id until the job completes. Read only: no. Destructive: no. Idempotent (safe to retry): no. Inputs: - `app_id` (`string`, required): The id of the Butterbase app to submit the image-generation job under. - `model` (`string`, required): Model id to use for image generation, in provider/model form, e.g. openai/gpt-image-1. - `prompt` (`string`, required): Text prompt describing the image to generate. - `aspect_ratio` (`string`, optional): Aspect ratio of the generated image(s), e.g. 1:1 or 16:9. Supported values depend on the chosen model. - `input_images` (`array`, optional): Array of image URLs to use as reference images, if the chosen model supports image-to-image generation or editing. - `mask` (`string`, optional): URL of a mask image marking the region to edit, for models that support inpainting. - `n` (`integer`, optional): Number of images to generate for this job. Supported values depend on the chosen model. - `negative_prompt` (`string`, optional): Text describing elements to avoid in the generated image(s), for models that support negative prompting. - `provider` (`object`, optional): Provider-specific settings passed through to the underlying image model as-is. The exact fields accepted vary by model and are not published in Butterbase's docs; check the chosen provider's own documentation for supported keys. - `seed` (`integer`, optional): Random seed for reproducible generation. Same seed and inputs should produce similar output. - `size` (`string`, optional): Output image dimensions, e.g. 1024x1024. Supported values depend on the chosen model. Example input: `{"app_id":"","model":"","prompt":""}` ### `butterbase_integration_configure` Enable Integration · Write Enable a third-party integration toolkit (e.g. Gmail, Slack, Notion) for a Butterbase app, optionally giving it a display name and restricting it to specific OAuth scopes. Returns the toolkit's configuration once enabled; exact response fields are not published in Butterbase's docs. Use butterbase_integration_configure to turn on a toolkit found via butterbase_integrations_available_list; use butterbase_integration_configure_delete to turn it back off. Read only: no. Destructive: no. Idempotent (safe to retry): no. Inputs: - `app_id` (`string`, required): The Butterbase app ID to enable the toolkit for, as shown in the app's dashboard URL or returned by the app-creation API. - `toolkit` (`string`, required): The slug of the integration toolkit to enable, as returned by butterbase_integrations_available_list (e.g. 'gmail', 'slack', 'notion'). - `displayName` (`string`, optional): A human-readable name to show for this toolkit in the app's dashboard. If omitted, the toolkit's default catalog name is used. - `scopes` (`array`, optional): Array of OAuth scope strings to restrict this toolkit's connections to. If omitted, the toolkit's default scopes are used. Example input: `{"app_id":"","toolkit":"gmail"}` ### `butterbase_integration_connect` Connect Integration · Write Generate an OAuth authorization URL that lets an end user connect a third-party integration account (e.g. Gmail, Slack, Notion) to a Butterbase app. Returns an authUrl to send the user to and a connectionRequestId for tracking the pending connection. Use butterbase_integration_connect to start a new connection. Use butterbase_integration_connections_list to see accounts already connected. Prerequisite: the toolkit must already be enabled for the app (via the Butterbase dashboard or the integrations configure endpoint) before a user can connect an account for it. Read only: no. Destructive: no. Idempotent (safe to retry): no. Inputs: - `app_id` (`string`, required): The Butterbase app ID that owns the integration connection. Found in the app's settings in the Butterbase dashboard. - `redirect_url` (`string`, required): The URL to redirect the end user to once they complete (or cancel) the OAuth flow at the third-party provider. - `toolkit` (`string`, required): The slug of the integration toolkit to connect, e.g. gmail, slack, or notion. Must already be enabled for the app. - `user_id` (`string`, required): The identifier of the end user who is connecting the account. Required because this connector authenticates with a Butterbase platform API key rather than an end-user JWT, and the API can only infer the user automatically on JWT-authenticated requests. Example input: `{"app_id":"","redirect_url":"","toolkit":"gmail","user_id":""}` ### `butterbase_integration_tool_execute` Execute Integration Tool · Write Execute a specific tool exposed by one of an end user's connected third-party integrations (e.g. send a Slack message, create a Gmail draft) through a Butterbase app. Returns {"successful": true, "data": {...}} on success, or an error object with a code, message, and remediation hint on failure. Use butterbase_integration_tools_list first to find the exact toolName and its expected params, then call butterbase_integration_tool_execute to run it. Read only: no. Destructive: no. Idempotent (safe to retry): no. Inputs: - `app_id` (`string`, required): The Butterbase app ID whose connected integration to execute a tool through. - `params` (`object`, required): The parameters the tool expects, as a JSON object whose shape depends on which integration tool is being run. Check butterbase_integration_tools_list for the exact fields a given tool accepts. Example: {"to": "jane@example.com", "subject": "Hi", "body": "Hello there"}. - `tool_name` (`string`, required): The identifier of the integration tool to run, as listed by butterbase_integration_tools_list, e.g. GMAIL_SEND_EMAIL. - `user_id` (`string`, required): The identifier of the end user whose connected account should be used to execute the tool. Required because this connector authenticates with a Butterbase platform API key rather than an end-user JWT, and the API can only infer the user automatically on JWT-authenticated requests. Example input: `{"app_id":"","params":{"to":"jane@example.com","subject":"Hi","body":"Hello there"},"tool_name":"","user_id":""}` ### `butterbase_kv_batch` Batch KV Operations · Write Perform up to 100 get, set, or delete operations against a Butterbase app's key-value store in a single request. Returns an array of per-operation results in the same order as the submitted operations. Use butterbase_kv_batch to read or write many keys efficiently in one call. Use butterbase_kv_set or butterbase_kv_delete for a single key at a time. Read only: no. Destructive: no. Idempotent (safe to retry): no. Inputs: - `app_id` (`string`, required): The Butterbase application ID that owns this key-value store. - `ops` (`array`, required): The batch of key-value operations to run, in order, up to 100 total. Each item needs an op (get, set, or del) and a key; set operations also need a value. Example: [{"op": "set", "key": "a", "value": 1}, {"op": "get", "key": "b"}, {"op": "del", "key": "c"}] Example input: `{"app_id":"","ops":[{"op":"set","key":"a","value":1},{"op":"get","key":"b"},{"op":"del","key":"c"}]}` ### `butterbase_kv_cas` Compare-And-Swap KV Value · Write Compare-and-swap the value at a key in a Butterbase app's key-value store: update it to a new value only if it currently matches an expected value. Returns a swapped flag indicating whether the update was applied. Use butterbase_kv_cas for optimistic concurrency control. Use butterbase_kv_set to write unconditionally, or butterbase_kv_setnx to write only when the key is absent. Read only: no. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `app_id` (`string`, required): The Butterbase application ID that owns this key-value store. - `expected` (`string`, required): The value the key is expected to currently hold. Pass JSON null to require that the key does not currently exist. Can be a string, number, boolean, object, array, or null. - `key` (`string`, required): The key-value store key to compare and conditionally update. - `next` (`string`, required): The new value to store if the current value matches 'expected'. Can be a string, number, boolean, object, or array. Example input: `{"app_id":"","expected":"","key":"","next":""}` ### `butterbase_kv_decr` Decrement KV Counter · Write Atomically decrement the numeric value stored at a key in a Butterbase app's key-value store, by 1 or by a given amount. Returns the counter's new integer value after the decrement. Use butterbase_kv_decr to subtract from a counter. Use butterbase_kv_incr to add to it, or butterbase_kv_set to overwrite the value directly. Read only: no. Destructive: no. Idempotent (safe to retry): no. Inputs: - `app_id` (`string`, required): The Butterbase application ID that owns this key-value store. - `key` (`string`, required): The key-value store key holding the numeric counter to decrement. - `by` (`integer`, optional): The amount to subtract from the counter. Defaults to 1 if omitted. Default: `1`. Example input: `{"app_id":"","key":""}` ### `butterbase_kv_expire` Set KV Key TTL · Write Set or clear the time-to-live on a key in a Butterbase app's key-value store, without changing its stored value. Returns an applied flag indicating whether the TTL change took effect. Use butterbase_kv_expire to change or remove a key's expiration on its own. Use butterbase_kv_set to change both the value and TTL together. Read only: no. Destructive: no. Idempotent (safe to retry): no. Inputs: - `app_id` (`string`, required): The Butterbase application ID that owns this key-value store. - `key` (`string`, required): The key-value store key whose TTL should be set or cleared. - `ttl` (`integer`, required): The new time-to-live in seconds. Pass JSON null to remove the key's expiration entirely so it never expires. Example input: `{"app_id":"","key":"","ttl":1}` ### `butterbase_kv_expose_rule_set` Set KV Expose Rule · Write Create or update a key-value expose rule that grants end-user JWTs read and/or write access to keys matching a glob-style pattern, optionally using JWT-claim substitution such as {user.id} in the pattern. Returns no content on success; fails with a conflict error if the pattern collides with another rule's precedence. Use butterbase_kv_expose_rule_set to add a new pattern or change an existing one's access roles. Use butterbase_kv_expose_rules_list to see current rules first, and butterbase_kv_expose_rule_delete to remove one. Read only: no. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `app_id` (`string`, required): The Butterbase application ID the key pattern belongs to. - `pattern` (`string`, required): The glob-style key pattern this rule applies to, e.g. session/{user.id}/* or public/*. Supports JWT-claim substitution like {user.id}, which Butterbase resolves against the caller's JWT at request time. The pattern is sent as a URL path segment and is percent-encoded automatically. - `read` (`string`, required): Which role is allowed to read keys matching this pattern. `public` allows anonymous access, `authed` allows any signed-in end user, `owner` restricts access to the user whose JWT claim matches the pattern's placeholder (e.g. {user.id}), and `deny` blocks read access entirely. One of: `public`, `authed`, `owner`, `deny`. - `write` (`string`, required): Which role is allowed to write keys matching this pattern. `public` allows anonymous writes, `authed` allows any signed-in end user, `owner` restricts writes to the user whose JWT claim matches the pattern's placeholder (e.g. {user.id}), and `deny` blocks write access entirely. One of: `public`, `authed`, `owner`, `deny`. Example input: `{"app_id":"","pattern":"","read":"public","write":"public"}` ### `butterbase_kv_incr` Increment KV Counter · Write Atomically increment the numeric value stored at a key in a Butterbase app's key-value store, by 1 or by a given amount. Returns the counter's new integer value after the increment. Use butterbase_kv_incr to add to a counter. Use butterbase_kv_decr to subtract from it, or butterbase_kv_set to overwrite the value directly. Read only: no. Destructive: no. Idempotent (safe to retry): no. Inputs: - `app_id` (`string`, required): The Butterbase application ID that owns this key-value store. - `key` (`string`, required): The key-value store key holding the numeric counter to increment. - `by` (`integer`, optional): The amount to add to the counter. Defaults to 1 if omitted. Default: `1`. Example input: `{"app_id":"","key":""}` ### `butterbase_kv_set` Set KV Value · Write Create or overwrite the value stored at a key in a Butterbase app's key-value store, optionally setting a time-to-live. Returns no content on success (HTTP 204). Use butterbase_kv_set to write a key unconditionally. Use butterbase_kv_setnx to write only when the key is absent, or butterbase_kv_cas to write only when the current value matches an expected one. Read only: no. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `app_id` (`string`, required): The Butterbase application ID that owns this key-value store. - `key` (`string`, required): The key-value store key to write. - `value` (`string`, required): The JSON value to store at this key. Can be a string, number, boolean, object, or array. Example: {"theme": "dark", "notifications": true} - `ephemeral` (`boolean`, optional): Marks the key as ephemeral when true. Butterbase's docs do not fully spell out the resulting behavior, so leave this unset unless you specifically need it. - `ttl` (`integer`, optional): Time-to-live for the key in seconds. Pass null for no explicit expiration; if the field is omitted entirely, Butterbase applies its own default (30 days). Example input: `{"app_id":"","key":"","value":""}` ### `butterbase_kv_setnx` Set KV Value If Not Exists · Write Set a key's value in a Butterbase app's key-value store only if the key does not already exist. Returns a wrote flag: true (HTTP 201) if the key was created, or false (HTTP 200) if it already existed and nothing changed. Use butterbase_kv_setnx to avoid overwriting an existing key. Use butterbase_kv_set to write unconditionally, or butterbase_kv_cas to update only when the current value matches an expected one. Read only: no. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `app_id` (`string`, required): The Butterbase application ID that owns this key-value store. - `key` (`string`, required): The key-value store key to write, only if it does not already exist. - `value` (`string`, required): The JSON value to store at this key if it doesn't already exist. Can be a string, number, boolean, object, or array. Example: {"owner": "worker-3"} - `ephemeral` (`boolean`, optional): Marks the key as ephemeral when true, if it is created. Butterbase's docs do not fully spell out the resulting behavior, so leave this unset unless you specifically need it. - `ttl` (`integer`, optional): Time-to-live for the key in seconds, applied only if the key is created. Pass null for no explicit expiration; if omitted, Butterbase applies its own default (30 days). Example input: `{"app_id":"","key":"","value":""}` ### `butterbase_mcp_server_probe` Probe MCP Server · Write Re-probe a registered MCP server to refresh the list of tools it currently advertises. Returns the server's current tool catalog as reported live by the probe (exact per-tool fields are not published in Butterbase's docs). Use this after registering a new MCP server, or whenever its upstream tools may have changed, so agents pick up the latest catalog without deleting and re-registering the server. Read only: no. Destructive: no. Idempotent (safe to retry): no. Inputs: - `app_id` (`string`, required): The unique identifier of the Butterbase app the MCP server is registered under. - `id` (`string`, required): The unique identifier of the registered MCP server to re-probe, as returned when the server was registered. Example input: `{"app_id":"","id":""}` ### `butterbase_mcp_server_register` Register MCP Server · Write Register an MCP server as a new external tool source that an app's agents can call from their graph_spec. Returns the created MCP server record, including the id Butterbase assigns it. Use butterbase_mcp_server_register to connect a new MCP server. Use butterbase_mcp_servers_list to see what's already registered, or butterbase_mcp_server_delete to remove one. Read only: no. Destructive: no. Idempotent (safe to retry): no. Inputs: - `app_id` (`string`, required): The id of the Butterbase app to register the MCP server under. - `auth` (`object`, required): How Butterbase should authenticate to this MCP server. Provide an object naming the auth scheme plus its credential; the documented scheme is a bearer token, given as a type field set to bearer alongside a token field holding the credential the MCP server expects. Example: {"type": "bearer", "token": "mcp_live_9f2a1c3e"} - `name` (`string`, required): A label for this MCP server registration, used to identify it in the app's agent tooling and graph_spec references. - `transport` (`string`, required): The MCP transport protocol this server uses. CONFIRMED required by the live API (not previously documented) — one of http, sse, or streamable_http. One of: `http`, `sse`, `streamable_http`. - `url` (`string`, required): The MCP server's base URL that Butterbase should connect to in order to discover and call its advertised tools. Example input: `{"app_id":"","auth":{"type":"bearer","token":"mcp_live_9f2a1c3e"},"name":"Pro","transport":"http","url":""}` ### `butterbase_meeting_bot_create` Create Meeting Bot · Write Dispatch a Butterbase notetaker bot to join and record a Zoom, Google Meet, Teams, or Webex meeting, with optional recording and transcription. Returns the new bot's id, its initial lifecycle status, and (once available) start/completion times, duration, recording and transcript URLs, bot name, and metadata. Use butterbase_meeting_bot_create to start capturing a call; poll butterbase_meeting_bot_get afterward for status updates, or call butterbase_meeting_bot_stop to make the bot leave early. Read only: no. Destructive: no. Idempotent (safe to retry): no. Inputs: - `app_id` (`string`, required): The unique identifier of the Butterbase app dispatching the meeting bot. - `meetingUrl` (`string`, required): The full join URL of the video meeting the bot should enter (Zoom, Google Meet, Microsoft Teams, or Webex). - `automaticLeave` (`object`, optional): Optional timeout thresholds (in seconds, each up to 86400) that make the bot leave the call automatically: waitingRoomTimeoutSec (stuck in a waiting room), noOneJoinedTimeoutSec (no one ever joined), everyoneLeftTimeoutSec (everyone else left), and inCallNotRecordingTimeoutSec (in the call but not recording). Leave unset to use Butterbase's defaults. Example: {"waitingRoomTimeoutSec": 600, "noOneJoinedTimeoutSec": 300, "everyoneLeftTimeoutSec": 60, "inCallNotRecordingTimeoutSec": 1800}. - `botName` (`string`, optional): The display name the bot uses inside the meeting, 1-64 characters. Defaults to 'Butterbase Notetaker'. Default: `Butterbase Notetaker`. - `metadata` (`object`, optional): Arbitrary string-to-string key/value pairs to attach to this bot session for your own bookkeeping, e.g. correlating the bot with an internal meeting record. Defaults to an empty object. - `recording` (`string`, optional): How the bot should record the meeting: 'mp4' for full video, 'audio_only' for audio only, or false to disable recording entirely. Defaults to 'mp4'. One of: `mp4`, `audio_only`, `false`. Default: `mp4`. - `transcript` (`boolean`, optional): Whether the bot should generate a transcript of the meeting. Defaults to true. Default: `true`. Example input: `{"app_id":"","meetingUrl":""}` ### `butterbase_meeting_webhook_configure` Configure Meeting Webhook · Write Configure or rotate the webhook forwarding URL and signing secret Butterbase uses to deliver meeting-bot events (bot.done, transcript.done, recording.done, and related events) to your endpoint. Returns the app's current webhook configuration (ok, app_id, forward_url); the response's secret field is populated only the first time a signing secret is created, or when rotate_secret is set to true on this call - every other call returns secret as null. Use butterbase_meeting_webhook_configure to point event delivery at a new URL, or set rotate_secret to true to mint a fresh signing secret; rotating immediately invalidates the previous secret, so update your signature verification right away. Read only: no. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `app_id` (`string`, required): The unique identifier of the Butterbase app whose meeting-bot webhook should be configured. - `forward_url` (`string`, required): The HTTPS URL Butterbase should POST meeting-bot event payloads to. - `rotate_secret` (`boolean`, optional): When true, mints a brand-new webhook signing secret and returns it once in this response's secret field. Every other call - including one that only changes forward_url - returns secret as null, since Butterbase never re-displays a previously issued secret. Rotating also immediately invalidates the old secret, so requests signed with it stop verifying right away. Defaults to false. Default: `false`. Example input: `{"app_id":"","forward_url":""}` ### `butterbase_people_profile_email_lookup_start` Start Work Email Lookup · Write Queue an asynchronous lookup of a person's work email address from their LinkedIn profile URL. Returns a lookup ID (UUID) and a 'pending' status, plus the credits consumed to queue the job. Use this when you need a person's work email but only have their LinkedIn profile URL; poll butterbase_people_email_lookup_get with the returned lookup ID to retrieve the resolved email once processing completes. Read only: no. Destructive: no. Idempotent (safe to retry): no. Inputs: - `app_id` (`string`, required): The Butterbase app ID to run the lookup under, as shown in the app's dashboard URL or returned by the app-creation API. - `linkedinProfileUrl` (`string`, required): The LinkedIn profile URL of the person whose work email should be looked up. Example input: `{"app_id":"","linkedinProfileUrl":""}` ### `butterbase_public_agent_run_create` Start Public Agent Run · Write Start an anonymous run of a public Butterbase agent, without requiring the end user to sign in. Returns the new run's id and initial status. Use butterbase_public_agent_run_create for a public-facing agent (for example, one embedded in a website widget) that visitors can invoke without authentication. Use butterbase_agent_run_create instead to start a run against a private agent using platform authentication. Butterbase normally authorizes this route with the app's public anon key rather than the platform API key; this connector calls it with your configured platform API key instead. CONFIRMED via a dedicated live investigation: the underlying Butterbase endpoint works correctly and returns a genuine success when called with a valid end-user access token (obtained via butterbase_auth_login) -- this was previously only ever tested with the wrong credential type (this connector's platform key), which always 401s. HOWEVER, this connector has no way to actually supply that end-user token: Scalekit's execution engine controls the Authorization header for a BEARER connection server-side and rejects a client-supplied Authorization header override outright (confirmed via direct SDK-level testing -- a custom header is rejected with its own 401 before ever reaching Butterbase). This tool will therefore always fail via the standard execution path on this connector, by platform design, not due to a fixable tool-JSON defect -- it would need a future Scalekit auth-strategy feature (e.g. a per-call token override) to ever work through this connector. Read only: no. Destructive: no. Idempotent (safe to retry): no. Inputs: - `app_id` (`string`, required): The id of the Butterbase app the public agent belongs to. - `input` (`object`, required): The run's input state, given as a JSON object whose keys match whatever the agent's graph_spec templates via `{{ state.key }}` placeholders (for example, a visitor's message or form fields). The shape is defined by each agent, not by a fixed Butterbase schema. Example: {"message": "Hi, I need help resetting my password."} - `name` (`string`, required): The unique name of the public agent to run. Example input: `{"app_id":"","input":{"message":"Hi, I need help resetting my password."},"name":"Pro"}` ### `butterbase_public_run_cancel` Cancel Public Run · Write Cancel a queued or in-progress public agent run. Returns the run's updated status once cancellation has been requested. Use butterbase_public_run_cancel to stop a run started by butterbase_public_agent_run_create. Use butterbase_agent_run_cancel instead for a run started with platform authentication. Butterbase normally authorizes this route with the app's public anon key rather than the platform API key; this connector calls it with your configured platform API key instead. CONFIRMED via a dedicated live investigation: the underlying Butterbase endpoint works correctly and returns a genuine success when called with a valid end-user access token (obtained via butterbase_auth_login) -- this was previously only ever tested with the wrong credential type (this connector's platform key), which always 401s. HOWEVER, this connector has no way to actually supply that end-user token: Scalekit's execution engine controls the Authorization header for a BEARER connection server-side and rejects a client-supplied Authorization header override outright (confirmed via direct SDK-level testing -- a custom header is rejected with its own 401 before ever reaching Butterbase). This tool will therefore always fail via the standard execution path on this connector, by platform design, not due to a fixable tool-JSON defect -- it would need a future Scalekit auth-strategy feature (e.g. a per-call token override) to ever work through this connector. Read only: no. Destructive: no. Idempotent (safe to retry): no. Inputs: - `app_id` (`string`, required): The id of the Butterbase app the public run belongs to. - `id` (`string`, required): The id of the public run to cancel, as returned by butterbase_public_agent_run_create. Example input: `{"app_id":"","id":""}` ### `butterbase_public_run_resume` Resume Public Run · Write Resume a paused public agent run by submitting a human-in-the-loop approval decision. Returns the updated run object after the run resumes. Use butterbase_public_run_resume when a public run's run_paused event carries an approval_token awaiting a decision. Use butterbase_agent_run_resume instead for a run started with platform authentication. Butterbase normally authorizes this route with the app's public anon key rather than the platform API key; this connector calls it with your configured platform API key instead. CONFIRMED via a dedicated live investigation: the underlying Butterbase endpoint works correctly and returns a genuine success when called with a valid end-user access token (obtained via butterbase_auth_login) -- this was previously only ever tested with the wrong credential type (this connector's platform key), which always 401s. HOWEVER, this connector has no way to actually supply that end-user token: Scalekit's execution engine controls the Authorization header for a BEARER connection server-side and rejects a client-supplied Authorization header override outright (confirmed via direct SDK-level testing -- a custom header is rejected with its own 401 before ever reaching Butterbase). This tool will therefore always fail via the standard execution path on this connector, by platform design, not due to a fixable tool-JSON defect -- it would need a future Scalekit auth-strategy feature (e.g. a per-call token override) to ever work through this connector. Separately and additionally: even setting the credential problem aside, this tool's happy path (actually resuming a genuinely paused run) remains unverified -- Butterbase's docs do not document how to configure an agent graph node that triggers a human-in-the-loop pause (e.g. a builtin tool requiring approval), so no real run_paused/approval_token has ever been produced to test against, across multiple rounds of testing. The tool's schema (approval_token + approved boolean) matches what IS documented for this flow; only the end-to-end happy path is unverified. Read only: no. Destructive: no. Idempotent (safe to retry): no. Inputs: - `app_id` (`string`, required): The id of the Butterbase app the public run belongs to. - `approval_token` (`string`, required): The approval token carried in the run's run_paused event, identifying which pending tool-call approval this decision resolves. - `approved` (`boolean`, required): Whether to approve (true) or reject (false) the paused tool call, allowing or blocking the run from continuing with it. - `id` (`string`, required): The id of the paused public run to resume. Example input: `{"app_id":"","approval_token":"","approved":true,"id":""}` ### `butterbase_public_run_stream_token_create` Create Run Stream Token · Write Mint a one-time token that authorizes a live connection to a public agent run's event stream (SSE or WebSocket). Returns a short-lived token string to pass as a `token` query parameter when opening the run's streaming events or WebSocket endpoint. Use butterbase_public_run_stream_token_create right before opening a live connection to a run's events. Use butterbase_public_run_events_list instead if a single JSON snapshot of the events so far is enough. Butterbase normally authorizes this route with the app's public anon key rather than the platform API key; this connector calls it with your configured platform API key instead. CONFIRMED via a dedicated live investigation: the underlying Butterbase endpoint works correctly and returns a genuine success when called with a valid end-user access token (obtained via butterbase_auth_login) -- this was previously only ever tested with the wrong credential type (this connector's platform key), which always 401s. HOWEVER, this connector has no way to actually supply that end-user token: Scalekit's execution engine controls the Authorization header for a BEARER connection server-side and rejects a client-supplied Authorization header override outright (confirmed via direct SDK-level testing -- a custom header is rejected with its own 401 before ever reaching Butterbase). This tool will therefore always fail via the standard execution path on this connector, by platform design, not due to a fixable tool-JSON defect -- it would need a future Scalekit auth-strategy feature (e.g. a per-call token override) to ever work through this connector. Read only: no. Destructive: no. Idempotent (safe to retry): no. Inputs: - `app_id` (`string`, required): The id of the Butterbase app the public run belongs to. - `id` (`string`, required): The id of the public run to open a live event stream for. Example input: `{"app_id":"","id":""}` ### `butterbase_rag_collection_create` Create RAG Collection · Write Create a new RAG document collection in a Butterbase app, configuring its access mode and chunking strategy. Returns the created collection with its name, description, access mode, chunk size, chunk overlap, and creation/update timestamps. Use butterbase_rag_collection_create to set up a collection before ingesting documents into it with butterbase_rag_document_ingest. Use butterbase_rag_collections_list to see collections that already exist. Read only: no. Destructive: no. Idempotent (safe to retry): no. Inputs: - `app_id` (`string`, required): The Butterbase app ID that will own this collection. Found in the app's dashboard URL or via Butterbase's apps listing. - `name` (`string`, required): Name of the new collection. Must use only lowercase letters, numbers, hyphens, and underscores, and must be unique within the app. - `accessMode` (`string`, optional): Who can access this collection: private (only this app's service key), shared, or custom. Defaults to private if omitted. One of: `private`, `shared`, `custom`. Default: `private`. - `chunkOverlap` (`number`, optional): Number of characters of overlap between consecutive chunks, to preserve context across chunk boundaries. Defaults to 64 if omitted. Default: `64`. - `chunkSize` (`number`, optional): Number of characters per text chunk when documents are split for embedding. Defaults to 512 if omitted. Default: `512`. - `description` (`string`, optional): Optional human-readable description of what this collection contains. Example input: `{"app_id":"","name":"Pro"}` ### `butterbase_rag_document_ingest` Ingest RAG Document · Write Enqueue a document for asynchronous ingestion into a RAG collection, from raw text or from a file already uploaded to Butterbase storage. Returns a document id and a pending ingestion status immediately (202 Accepted); the document is not searchable until ingestion finishes. Use butterbase_rag_document_ingest to add a document, then poll butterbase_rag_document_get until its status is ready or failed. Provide exactly one of the raw text or a storage object id — never both, and never neither. Read only: no. Destructive: no. Idempotent (safe to retry): no. Inputs: - `app_id` (`string`, required): The Butterbase app ID that owns the target collection. Found in the app's dashboard URL or via Butterbase's apps listing. - `name` (`string`, required): The name of the RAG collection to ingest this document into, exactly as it was created. - `filename` (`string`, optional): Optional display filename for the ingested document, overriding any name derived from the source. - `metadata` (`object`, optional): Optional metadata object stored alongside the document, returned with query results and usable as a metadata filter in butterbase_rag_query. - `storage_object_id` (`string`, optional): ID of a file already uploaded to Butterbase's separate storage API. Required when text is not provided; provide only one of the two, never both. There is no raw file-upload option on this endpoint — upload the file via Butterbase's storage API first to obtain this id. - `text` (`string`, optional): Raw text content to ingest as a document. Required when storage_object_id is not provided; provide only one of the two, never both. Example input: `{"app_id":"","name":"Pro"}` ### `butterbase_repo_blobs_batch_presign` Batch Presign Repo Blobs · Write Get presigned download URLs for multiple app repo blobs in one call, given their SHA-256 hashes. Returns presigned download URLs for the requested blobs (exact response shape is not published in Butterbase's docs, but each entry pairs a hash with its presigned URL). Use butterbase_repo_blobs_batch_presign to fetch many blob URLs at once. Use butterbase_repo_blob_get when you only need one. Read only: no. Destructive: no. Idempotent (safe to retry): no. Inputs: - `app_id` (`string`, required): The id of the app whose repo the blobs belong to. - `shas` (`array`, required): List of SHA-256 hashes (64 lowercase hex characters each) identifying the blobs to presign, as they appear in a repo snapshot manifest. Example input: `{"app_id":"","shas":[]}` ### `butterbase_repo_snapshot_commit` Commit Repo Snapshot · Write Finalize and commit a previously prepared app repo snapshot using its full manifest. Returns the committed snapshot record (exact fields are not published in Butterbase's docs, but it typically includes a snapshot id and its manifest). Use butterbase_repo_snapshot_commit after butterbase_repo_snapshot_prepare has validated the manifest and you have uploaded any changed blobs to their presigned URLs. Read only: no. Destructive: no. Idempotent (safe to retry): no. Inputs: - `app_id` (`string`, required): The id of the app whose repo this snapshot belongs to. - `manifest` (`object`, required): The full file manifest to commit as the app's new repo snapshot, matching the shape validated by butterbase_repo_snapshot_prepare: an object listing every tracked file's path, SHA-256 hash, and size. Example input: `{"app_id":"","manifest":{}}` ### `butterbase_repo_snapshot_prepare` Prepare Repo Snapshot · Write Validate a file manifest for a new app repo snapshot and get presigned upload URLs for any blobs that changed. Returns a validation result plus presigned upload URLs for changed blobs (exact response fields are not published in Butterbase's docs). Use butterbase_repo_snapshot_prepare before butterbase_repo_snapshot_commit: upload each changed blob to its presigned URL first, then commit the resulting manifest. Read only: no. Destructive: no. Idempotent (safe to retry): no. Inputs: - `app_id` (`string`, required): The id of the app whose repo this snapshot belongs to. - `files` (`array`, required): The full list of files in the app's repo manifest. Each entry needs the file's repo-relative path, the SHA-256 hash of its contents, and its size in bytes. Butterbase compares these hashes against the current snapshot to work out which blobs actually changed and need uploading. - `message` (`string`, optional): Optional commit-style message describing this snapshot, shown later in the app's repo history. Example input: `{"app_id":"","files":[]}` ### `butterbase_schema_apply` Apply Schema Migration · Write Apply a database schema migration to a Butterbase app, or preview it first with a dry run. Returns the result of the migration attempt; Butterbase's docs do not publish an exact response shape, and a dry run returns a preview instead of applying changes. Use butterbase_schema_apply to change an app's tables and columns. Use butterbase_schema_get to read the current schema first, and butterbase_migrations_list to confirm which migrations have already applied. CONFIRMED via live testing: the request body wraps the schema under a "schema" key (not "migration" as earlier assumed) — this tool sends it correctly now. Also confirmed: this is a full declarative sync of the table set; omitting an existing table from a subsequent apply call will trigger a destructive-change rejection unless a top-level "_drop": ["table_name", ...] array explicitly authorizes removing it. CONFIRMED primary key shape (deep-coverage testing): mark a column as the primary key with a column-level, camelCase, boolean flag -- {"columns": {"id": {"type": "uuid", "primaryKey": true}}} -- table-level "primary_key"/"primaryKey" fields are silently accepted but do NOT produce a working primary key (subsequent butterbase_table_row_get/update calls then fail with "Table has no primary key"). Read only: no. Destructive: no. Idempotent (safe to retry): no. Inputs: - `app_id` (`string`, required): The Butterbase app's unique ID whose database schema should be migrated. - `migration` (`object`, required): The schema migration definition to apply, in the shape Butterbase's schema tooling expects for the app (for example, creating a table, adding a column, or changing a column's type). Butterbase's public docs do not publish an exact JSON shape for this field, so build it the same way the app's schema editor or CLI would generate it. Example: {"tables": [{"name": "posts", "columns": [{"name": "title", "type": "text"}]}]} To set a working primary key, use the column-level camelCase boolean shape confirmed by testing: {"tables": [{"name": "posts", "columns": {"id": {"type": "uuid", "primaryKey": true}, "title": {"type": "text"}}}]} - `dry_run` (`boolean`, optional): When true, previews the migration without applying it to the database. Default: `false`. Example input: `{"app_id":"","migration":{}}` ### `butterbase_storage_config_update` Update Storage Config · Write Update an app's storage configuration in Butterbase, such as enabling app-wide public-read access to stored files. Returns a confirmation message plus the app's updated storage configuration, including its max file size, allowed content types, and whether public-read access is enabled. Use this to toggle public-read access for all files in an app at once. To make only a single file public instead, use the public flag on butterbase_storage_upload_url_create. CONFIRMED via live testing: maxFileSizeMb and storageLimitBytes are also real, working settings on this endpoint (not previously exposed here) -- both are now supported as inputs. Read only: no. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `app_id` (`string`, required): The unique identifier of the Butterbase app whose storage configuration should be updated. - `maxFileSizeMb` (`integer`, optional): The maximum size, in megabytes, allowed for a single uploaded file in this app's storage. CONFIRMED via live testing: the API accepts and applies this field. Omit to leave the current limit unchanged. - `publicReadEnabled` (`boolean`, optional): Whether any authenticated user of the app can download any file in storage, regardless of who uploaded it. Uploads and deletes remain scoped to their owning user either way. - `storageLimitBytes` (`integer`, optional): The total storage quota, in bytes, allowed for this app across all uploaded files. CONFIRMED via live testing: the API accepts and applies this field. Omit to leave the current limit unchanged. Example input: `{"app_id":""}` ### `butterbase_storage_upload_url_create` Create Storage Upload URL · Write Request a presigned URL for uploading a new file to a Butterbase app's storage. Returns a short-lived upload URL, the assigned object key and object ID, and the URL's expiry in seconds. This tool only creates the upload URL — the caller must separately send the file bytes with a raw PUT request to that URL (using the same content type), which is not part of this tool. Use this to start uploading a file to Butterbase Storage; after the PUT to the returned URL succeeds, use butterbase_storage_objects_list or butterbase_storage_download_url_get to reference the stored file. Read only: no. Destructive: no. Idempotent (safe to retry): no. Inputs: - `app_id` (`string`, required): The unique identifier of the Butterbase app to upload the file into. - `contentType` (`string`, required): The MIME type of the file being uploaded. This must match the Content-Type header used on the follow-up PUT to the presigned upload URL. - `filename` (`string`, required): The original filename of the file being uploaded, including its extension. - `sizeBytes` (`integer`, required): The exact size of the file in bytes. Uploads are subject to the app's configured max file size (10 MB by default). - `public` (`boolean`, optional): If true, marks the uploaded file as downloadable by any authenticated user of the app, not just the uploader. Defaults to false (private to the uploader) if omitted. Default: `false`. Example input: `{"app_id":"","contentType":"","filename":"","sizeBytes":1}` ### `butterbase_substrate_action_approve` Approve Substrate Action · Write Approve a pending Substrate action so it executes. Returns the updated action record showing its new status; if the action is not currently in proposed status, the request fails with a 409 wrong_status error. Use butterbase_substrate_action_approve after butterbase_substrate_actions_list or butterbase_substrate_action_get shows an action with status proposed and requires_approval true. Requires a Butterbase Substrate-scoped API key (bb_sub_...), not the general platform key. Read only: no. Destructive: no. Idempotent (safe to retry): no. Inputs: - `action_id` (`string`, required): The unique identifier of the pending Substrate action to approve. - `reason` (`string`, optional): An optional free-text note explaining why the action is being approved. Butterbase's docs show this as an example field on the request but do not state whether it is strictly required, so it is treated as optional here. Example input: `{"action_id":""}` ### `butterbase_substrate_action_propose` Propose Substrate Action · Write Propose a Substrate action, such as recording a decision, commitment, learning, or principle, or creating, updating, merging, or deleting an entity, for auto-execution or manual approval. Returns the new action's id, an approval verdict (auto_approved, auto_approved_yolo, requires_approval, or rejected), and, once executed, the capability-specific result. Use butterbase_substrate_action_propose to write to the Substrate memory ledger; if the verdict is requires_approval, follow up with butterbase_substrate_action_approve or butterbase_substrate_action_reject. Requires a Butterbase Substrate-scoped API key (bb_sub_...), not the general platform key. Read only: no. Destructive: no. Idempotent (safe to retry): no. Inputs: - `capability` (`string`, required): The Substrate capability this action proposes. Determines both what fields the payload must contain and the action's default approval policy. One of: record_decision, record_commitment, record_learning, record_principle, supersede_decision, retire_principle, upsert_entity, update_entity, patch_entity, merge_entities, delete_entity, upsert_source_artifact, revert_action, bulk_revert_actions, send_email_draft. One of: `record_decision`, `record_commitment`, `record_learning`, `record_principle`, `supersede_decision`, `retire_principle`, `upsert_entity`, `update_entity`, `patch_entity`, `merge_entities`, `delete_entity`, `upsert_source_artifact`, `revert_action`, `bulk_revert_actions`, `send_email_draft`. - `payload` (`object`, required): A JSON object whose fields depend entirely on the chosen capability. For example, record_decision needs a title and a kind; upsert_entity needs a type and display_name; patch_entity needs an id and a JSON merge-patch of the fields to change; send_email_draft needs to, subject, and body; delete_entity needs an id and a reason (CONFIRMED required via live testing, not previously documented here); record_principle needs applies_to and constraint_spec (CONFIRMED required via live testing, not previously documented here). Consult Butterbase's Substrate API capability-payload reference for the exact required and optional fields for your chosen capability. - `idempotency_key` (`string`, optional): An optional client-chosen string that makes repeated proposals with the same intent idempotent. Reusing the same key returns the original action's verdict and result without re-executing it, with the response's replay field set to true; the key is remembered indefinitely (no stated expiry) per Substrate user. Example input: `{"capability":"record_decision","payload":{}}` ### `butterbase_substrate_action_reject` Reject Substrate Action · Write Reject a pending Substrate action so it will not execute. Returns the updated action record showing its new status; if the action is not currently in proposed status, the request fails with a 409 wrong_status error. Use butterbase_substrate_action_reject to decline an action that butterbase_substrate_actions_list or butterbase_substrate_action_get shows as status proposed and requires_approval true. Requires a Butterbase Substrate-scoped API key (bb_sub_...), not the general platform key. Read only: no. Destructive: no. Idempotent (safe to retry): no. Inputs: - `action_id` (`string`, required): The unique identifier of the pending Substrate action to reject. - `reason` (`string`, required): An optional free-text note explaining why the action is being rejected. Butterbase's docs show this as an example field on the request but do not state whether it is strictly required, so it is treated as optional here. Example input: `{"action_id":"","reason":""}` ### `butterbase_substrate_attention_rule_create` Create Attention Rule · Write Create a new Substrate attention rule that evaluates a condition on a cron schedule and, when it matches, proposes an action through the Substrate actions ledger. Returns the created rule record, including its rule_id, schedule, and whether it starts enabled. Use butterbase_substrate_attention_rule_create to set up ongoing monitoring, such as a weekly digest email or an alert when a snapshot metric crosses a threshold. Use butterbase_substrate_attention_rule_preview first to dry-run the same rule body against current data before saving it. Requires a Butterbase Substrate-scoped API key (bb_sub_...) — a standard platform API key is rejected with a 403 on all Substrate endpoints. Read only: no. Destructive: no. Idempotent (safe to retry): no. Inputs: - `action_capability` (`string`, required): Which Substrate capability to propose (through the actions ledger) when the rule's condition matches. Must be one of the capability names Substrate accepts on POST /v1/me/substrate/actions/propose. Capabilities such as send_email_draft, record_principle, supersede_decision, retire_principle, merge_entities, delete_entity, and bulk_revert_actions require an explicit approval before they execute; the rest normally auto-execute. One of: `record_decision`, `record_commitment`, `record_learning`, `record_principle`, `supersede_decision`, `retire_principle`, `upsert_entity`, `update_entity`, `patch_entity`, `merge_entities`, `delete_entity`, `upsert_source_artifact`, `revert_action`, `bulk_revert_actions`, `send_email_draft`. - `action_payload_template` (`object`, required): Template for the payload sent to action_capability when the rule fires. Supports {{var}} placeholder interpolation using fields from the matched data at fire time (e.g. {{entity_count}}). Its shape must match what action_capability expects, e.g. {"to": "...", "subject": "...", "body": "..."} for send_email_draft. - `condition` (`object`, required): The rule's trigger condition, expressed as a JSON-Logic predicate object evaluated against the data selected by condition_mode. Example: {">": [{"var": "entity_count"}, 0]} matches when entity_count is greater than 0. - `condition_mode` (`string`, required): Which data source the condition is evaluated against. 'snapshot_predicate' checks fields from Butterbase's daily rollup snapshots (e.g. entity_count, decision_count). 'row_query' evaluates the condition against live Substrate data instead of a snapshot. One of: `snapshot_predicate`, `row_query`. - `name` (`string`, required): Display name for the attention rule, shown in the Butterbase dashboard and used to recognize it in the actions ledger. - `trigger_cron` (`string`, required): 5-field cron expression (minute hour day-of-month month day-of-week), evaluated in UTC, controlling how often Butterbase checks this rule's condition. Example: '0 9 * * 1' runs every Monday at 09:00 UTC. - `description` (`string`, optional): Free-text explanation of what the rule watches for and why. Shown alongside the rule in the dashboard; it does not affect evaluation. - `enabled` (`boolean`, optional): Whether the rule is active immediately after creation. Set to false to save it without evaluating it yet. Defaults to true. Default: `true`. - `max_fires_per_day` (`integer`, optional): Maximum number of times this rule is allowed to fire (propose an action) within a single day, to guard against runaway repeated firings. Leave unset for no daily cap. Example input: `{"action_capability":"record_decision","action_payload_template":{},"condition":{},"condition_mode":"snapshot_predicate","name":"Pro","trigger_cron":"0 9 * * 1"}` ### `butterbase_substrate_attention_rule_disable` Disable Attention Rule · Write Disable an active Substrate attention rule so it stops evaluating its condition and firing, without deleting its definition. Returns the updated rule record with its enabled flag set to false. Use butterbase_substrate_attention_rule_disable to pause a rule temporarily. Use butterbase_substrate_attention_rule_delete instead to remove it permanently, or butterbase_substrate_attention_rule_enable to resume it later. Requires a Butterbase Substrate-scoped API key (bb_sub_...) — a standard platform API key is rejected with a 403 on all Substrate endpoints. Read only: no. Destructive: no. Idempotent (safe to retry): no. Inputs: - `rule_id` (`string`, required): The unique id of the attention rule to disable, as returned by butterbase_substrate_attention_rule_create or a prior list call. Example input: `{"rule_id":""}` ### `butterbase_substrate_attention_rule_enable` Enable Attention Rule · Write Enable a disabled Substrate attention rule so it resumes evaluating its condition on its cron schedule. Returns the updated rule record with its enabled flag set to true. Use butterbase_substrate_attention_rule_enable to resume a rule paused earlier with butterbase_substrate_attention_rule_disable, without redefining it. Use butterbase_substrate_attention_rule_update instead if you also need to change the rule's condition, schedule, or action. Requires a Butterbase Substrate-scoped API key (bb_sub_...) — a standard platform API key is rejected with a 403 on all Substrate endpoints. Read only: no. Destructive: no. Idempotent (safe to retry): no. Inputs: - `rule_id` (`string`, required): The unique id of the attention rule to enable, as returned by butterbase_substrate_attention_rule_create or a prior list call. Example input: `{"rule_id":""}` ### `butterbase_substrate_attention_rule_preview` Preview Attention Rule · Write Dry-run a Substrate attention rule's definition against current data without saving the rule or firing any real actions. Returns bindings_count (how many data bindings matched the condition), sample_proposals (a small sample of what would have been proposed, including whether each would require approval), and skip_reason (set if the rule would not have fired). Use butterbase_substrate_attention_rule_preview before butterbase_substrate_attention_rule_create or butterbase_substrate_attention_rule_update to check a rule's condition and payload template behave as expected before persisting it. Requires a Butterbase Substrate-scoped API key (bb_sub_...) — a standard platform API key is rejected with a 403 on all Substrate endpoints. Read only: no. Destructive: no. Idempotent (safe to retry): no. Inputs: - `action_capability` (`string`, required): Which Substrate capability would be proposed if this rule matched. Must be one of the capability names Substrate accepts on POST /v1/me/substrate/actions/propose. One of: `record_decision`, `record_commitment`, `record_learning`, `record_principle`, `supersede_decision`, `retire_principle`, `upsert_entity`, `update_entity`, `patch_entity`, `merge_entities`, `delete_entity`, `upsert_source_artifact`, `revert_action`, `bulk_revert_actions`, `send_email_draft`. - `action_payload_template` (`object`, required): Template for the payload that would be sent to action_capability if the rule fired. Supports {{var}} placeholder interpolation using fields from the matched data (e.g. {{entity_count}}). Its rendered form for each match is returned in sample_proposals. - `condition` (`object`, required): The condition to test, expressed as a JSON-Logic predicate object evaluated against the data selected by condition_mode. Example: {">": [{"var": "entity_count"}, 0]} matches when entity_count is greater than 0. - `condition_mode` (`string`, required): Which data source the condition is evaluated against for this preview. 'snapshot_predicate' checks fields from Butterbase's daily rollup snapshots (e.g. entity_count, decision_count). 'row_query' evaluates the condition against live Substrate data instead of a snapshot. One of: `snapshot_predicate`, `row_query`. - `trigger_cron` (`string`, required): 5-field cron expression (minute hour day-of-month month day-of-week), evaluated in UTC. Included for schema parity with the saved rule; the preview evaluates the condition against current data immediately regardless of this schedule. - `description` (`string`, optional): Free-text explanation of what the rule watches for and why. Optional; not used in evaluation. - `enabled` (`boolean`, optional): Included for schema parity with the saved rule body. Has no effect on the preview itself, which always evaluates the condition regardless of this value. Default: `true`. - `max_fires_per_day` (`integer`, optional): Included for schema parity with the saved rule body. Has no effect on the preview itself. - `name` (`string`, optional): Display name for the rule being previewed. Optional for a preview since the rule is never saved. Example input: `{"action_capability":"record_decision","action_payload_template":{},"condition":{},"condition_mode":"snapshot_predicate","trigger_cron":"0 9 * * 1"}` ### `butterbase_substrate_attention_rule_update` Update Attention Rule · Write Replace an existing Substrate attention rule's schedule, condition, and action with a new definition. Returns the updated rule record. Use butterbase_substrate_attention_rule_update to change what a rule watches for or does. Use butterbase_substrate_attention_rule_enable or butterbase_substrate_attention_rule_disable instead if you only need to toggle it on or off without changing its definition. Requires a Butterbase Substrate-scoped API key (bb_sub_...) — a standard platform API key is rejected with a 403 on all Substrate endpoints. Read only: no. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `action_capability` (`string`, required): Which Substrate capability to propose (through the actions ledger) when the rule's condition matches. Must be one of the capability names Substrate accepts on POST /v1/me/substrate/actions/propose. Capabilities such as send_email_draft, record_principle, supersede_decision, retire_principle, merge_entities, delete_entity, and bulk_revert_actions require an explicit approval before they execute; the rest normally auto-execute. One of: `record_decision`, `record_commitment`, `record_learning`, `record_principle`, `supersede_decision`, `retire_principle`, `upsert_entity`, `update_entity`, `patch_entity`, `merge_entities`, `delete_entity`, `upsert_source_artifact`, `revert_action`, `bulk_revert_actions`, `send_email_draft`. - `action_payload_template` (`object`, required): Template for the payload sent to action_capability when the rule fires. Supports {{var}} placeholder interpolation using fields from the matched data at fire time (e.g. {{entity_count}}). Its shape must match what action_capability expects, e.g. {"to": "...", "subject": "...", "body": "..."} for send_email_draft. - `condition` (`object`, required): The rule's trigger condition, expressed as a JSON-Logic predicate object evaluated against the data selected by condition_mode. Example: {">": [{"var": "entity_count"}, 0]} matches when entity_count is greater than 0. - `condition_mode` (`string`, required): Which data source the condition is evaluated against. 'snapshot_predicate' checks fields from Butterbase's daily rollup snapshots (e.g. entity_count, decision_count). 'row_query' evaluates the condition against live Substrate data instead of a snapshot. One of: `snapshot_predicate`, `row_query`. - `name` (`string`, required): Display name for the attention rule, shown in the Butterbase dashboard and used to recognize it in the actions ledger. - `rule_id` (`string`, required): The unique id of the attention rule to update, as returned by butterbase_substrate_attention_rule_create or a prior list call. - `trigger_cron` (`string`, required): 5-field cron expression (minute hour day-of-month month day-of-week), evaluated in UTC, controlling how often Butterbase checks this rule's condition. Example: '0 9 * * 1' runs every Monday at 09:00 UTC. - `description` (`string`, optional): Free-text explanation of what the rule watches for and why. Shown alongside the rule in the dashboard; it does not affect evaluation. - `enabled` (`boolean`, optional): Whether the rule is active after this update. Defaults to true. Default: `true`. - `max_fires_per_day` (`integer`, optional): Maximum number of times this rule is allowed to fire (propose an action) within a single day, to guard against runaway repeated firings. Leave unset for no daily cap. Example input: `{"action_capability":"record_decision","action_payload_template":{},"condition":{},"condition_mode":"snapshot_predicate","name":"Pro","rule_id":"","trigger_cron":"0 9 * * 1"}` ### `butterbase_substrate_entity_update` Update Substrate Entity · Write Update fields on a Substrate entity by its id — change its display name, primary email, or attributes via a partial (RFC 7396 JSON merge-patch) update. Butterbase routes this through its internal action-proposal flow rather than writing directly. Returns the resulting action record, including its action_id and verdict (whether the update auto-applied or still needs approval). Use butterbase_substrate_entity_update to make a partial edit to one entity's fields. Use butterbase_substrate_entity_get first to see its current attributes and updated_at timestamp. This endpoint requires a Butterbase Substrate-scoped API key (bb_sub_...) — a general platform key (bb_sk_...) is rejected with a 403. KNOWN ISSUE: a live test against a real entity id returned a framework-level "Route PATCH: ... not found" 404, suggesting this direct PATCH endpoint may not actually exist and updates may need to go through butterbase_substrate_action_propose with capability patch_entity instead — unconfirmed, flagged for follow-up. Read only: no. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `entity_id` (`string`, required): The unique id of the Substrate entity to update. - `attrs_patch` (`object`, optional): A JSON merge-patch (RFC 7396) applied on top of the entity's existing attributes object: each key you include sets that attribute to the given value, and setting a key's value to null removes that attribute. Keys you leave out are untouched. - `display_name` (`string`, optional): New display name for the entity. Leave unset to keep the current name. - `if_updated_at` (`string`, optional): Optimistic-concurrency guard: an ISO 8601 timestamp that must match the entity's current updated_at for the patch to apply. Leave unset to skip this check. - `primary_email` (`string`, optional): New primary email address for the entity. Leave unset to keep the current value. Example input: `{"entity_id":""}` ### `butterbase_substrate_outbox_target_set` Set Outbox Target · Write Register or replace the outbound webhook target for a Substrate capability, so Butterbase POSTs a notification whenever an action for that capability executes. Returns the saved target configuration for the capability. Use butterbase_substrate_outbox_target_set to add a new webhook for a capability or update an existing one's URL, signing secret, or app scope. Use butterbase_substrate_outbox_target_delete instead to remove a capability's target entirely. Requires a Butterbase Substrate-scoped API key (bb_sub_...) — a standard platform API key is rejected with a 403 on all Substrate endpoints. Read only: no. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `capability` (`string`, required): Which Substrate capability this webhook target delivers notifications for. When an action for this capability executes, Butterbase POSTs its details to webhook_url. Must be one of the capability names Substrate accepts on POST /v1/me/substrate/actions/propose. One of: `record_decision`, `record_commitment`, `record_learning`, `record_principle`, `supersede_decision`, `retire_principle`, `upsert_entity`, `update_entity`, `patch_entity`, `merge_entities`, `delete_entity`, `upsert_source_artifact`, `revert_action`, `bulk_revert_actions`, `send_email_draft`. - `signing_secret` (`string`, required): A secret string, at least 8 characters long, used to sign each webhook delivery with HMAC-SHA-256. Verify incoming deliveries by comparing this signature against the X-Butterbase-Signature header (format sha256=) computed over the raw request body. - `webhook_url` (`string`, required): The HTTPS URL Butterbase POSTs to whenever an action for this capability executes. The delivered body includes action_id, capability, payload, and executed_at, and is signed with signing_secret. - `source_app_id` (`string`, optional): Restrict this webhook target to only fire for actions attributed to one Butterbase app (its source_app_id). Leave unset to receive this capability's webhooks for actions from any app. Example input: `{"capability":"record_decision","signing_secret":"","webhook_url":""}` ### `butterbase_substrate_yolo_mode_set` Set Substrate Yolo Mode · Write Toggle Substrate yolo mode for the current user, which auto-approves all proposed Substrate actions instead of holding approval-required ones for review. Returns the updated Substrate settings reflecting the new yolo mode state. Use butterbase_substrate_yolo_mode_set to turn yolo mode on for hands-off automation or off to require approval again; check the current state first with butterbase_substrate_settings_get. Requires a Butterbase Substrate-scoped API key (bb_sub_...), not the general platform key. Read only: no. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `yolo_mode` (`boolean`, required): Whether Substrate yolo mode should be enabled. When true, every proposed action auto-executes immediately, including capabilities that would normally require manual approval; when false, approval-required capabilities go back to waiting for an explicit approve/reject call. Example input: `{"yolo_mode":true}` ### `butterbase_suggestion_submit` Submit Suggestion · Write Submit product feedback or a feature suggestion to the Butterbase team, categorized by type and severity. Returns a confirmation that the suggestion was received (Butterbase's docs do not publish the exact response shape for this endpoint). Use butterbase_suggestion_submit to report a bug, request a feature, or propose an improvement directly to Butterbase. Read only: no. Destructive: no. Idempotent (safe to retry): no. Inputs: - `category` (`string`, required): The type of feedback being submitted. CONFIRMED live enum: bug_report, feature_request, improvement, or documentation. One of: `bug_report`, `feature_request`, `improvement`, `documentation`. - `description` (`string`, required): A clear description of the feedback, bug, or suggestion being submitted. - `affected_tool` (`string`, optional): Optional name of the specific Butterbase feature or API this feedback concerns, e.g. Data API, Storage, or Dashboard. - `proposed_solution` (`string`, optional): Optional suggested fix or improvement for the issue described. - `severity` (`string`, optional): Optional severity or urgency level for the feedback, e.g. low, medium, high, or critical. Leave blank if not applicable. - `source` (`string`, optional): Optional origin of this feedback, e.g. dashboard, api, or support-ticket. Example input: `{"category":"bug_report","description":"500 in-app credits, added instantly on purchase."}` ### `butterbase_table_row_create` Create Table Row · Write Create a new row in a Butterbase app table by supplying a JSON object of column names and values that match the table's schema. Returns the created row (Butterbase's docs show only a request body example for this endpoint, not the response shape). Use butterbase_table_row_create to insert a brand-new row; use butterbase_table_row_update to change columns on a row that already exists. Read only: no. Destructive: no. Idempotent (safe to retry): no. Inputs: - `app_id` (`string`, required): The Butterbase application ID that owns the table, as returned when the app was created or from butterbase_apps_list. Example: app_abc123. - `row` (`object`, required): A JSON object of column name/value pairs for the new row, matching the columns defined in the table's schema. Example: {"title": "Hello World", "body": "My first post", "published": true}. - `table` (`string`, required): The name of the table to insert the new row into, exactly as defined in the app's schema (see butterbase_schema_get). Example: posts. Example input: `{"app_id":"","row":{"title":"Hello World","body":"My first post","published":true},"table":"
"}` ### `butterbase_table_row_update` Update Table Row · Write Update one or more columns of an existing row in a Butterbase app table by its primary key, sending only the columns that should change. Returns the updated row (Butterbase's docs do not publish the exact response shape for this endpoint). Use butterbase_table_row_update for a partial change to a row that already exists; use butterbase_table_row_create to insert a new one. Read only: no. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `app_id` (`string`, required): The Butterbase application ID that owns the table, as returned when the app was created or from butterbase_apps_list. Example: app_abc123. - `id` (`string`, required): The primary key value of the row to update, matching whatever type the table's primary key column uses (e.g. an integer id or a UUID). Example: 42. - `row` (`object`, required): A JSON object of the column name/value pairs to change on the row. Only the columns you include are updated; any column left out keeps its current value. Example: {"published": false}. - `table` (`string`, required): The name of the table containing the row to update, exactly as defined in the app's schema (see butterbase_schema_get). Example: posts. Example input: `{"app_id":"","id":"","row":{"published":false},"table":"
"}` ### `butterbase_template_clone` Clone Template · Write Clone a public Butterbase template into a new app, optionally naming it and choosing a region. Returns a clone job id and a pending status; the new app is not ready until the job completes. Use butterbase_template_clone to start a clone from a discovered template. Use butterbase_clone_job_get to check its progress, and butterbase_clone_job_retry if the job fails. Read only: no. Destructive: no. Idempotent (safe to retry): no. Inputs: - `source_app_id` (`string`, required): The app id of the public template to clone. This is the template app's own app_id, discoverable via Butterbase's template listing endpoints. - `name` (`string`, optional): Name for the new app created from the template. If omitted, Butterbase assigns a default name based on the template. - `region` (`string`, optional): Region to create the cloned app in, using one of Butterbase's supported region codes (see butterbase_regions_list). If omitted, Butterbase picks a default region. Example input: `{"source_app_id":""}` ### `butterbase_video_generation_create` Create Video Generation Job · Write Submit an asynchronous AI video-generation job for a Butterbase app. Returns a job object with a job_id, a pending status, and a polling_url. Use butterbase_video_generation_create to start generating a video from a text prompt, then poll butterbase_video_generation_get with the returned job_id until the job completes. Read only: no. Destructive: no. Idempotent (safe to retry): no. Inputs: - `app_id` (`string`, required): The id of the Butterbase app to submit the video-generation job under. - `model` (`string`, required): Model id to use for video generation, in provider/model form, e.g. google/veo-3. - `prompt` (`string`, required): Text prompt describing the video to generate. - `aspect_ratio` (`string`, optional): Aspect ratio of the generated video, e.g. 16:9 or 9:16. Supported values depend on the chosen model. - `duration` (`number`, optional): Length of the generated video in seconds. Supported values depend on the chosen model. - `generate_audio` (`boolean`, optional): Whether the model should also generate an audio track for the video. - `input_images` (`array`, optional): Array of image URLs to use as reference or starting frames for the video, if the chosen model supports image-to-video. - `resolution` (`string`, optional): Output resolution of the generated video, e.g. 720p or 1080p. Supported values depend on the chosen model. - `seed` (`integer`, optional): Random seed for reproducible generation. Same seed and inputs should produce similar output. Example input: `{"app_id":"","model":"","prompt":""}` ### `butterbase_agent_delete` Delete Agent · Destructive Soft-delete a Butterbase agent by name, removing it from the app. Returns no response body on success. Use butterbase_agent_delete once an agent is no longer needed. Use butterbase_agent_update to pause it instead if you might want it back. Read only: no. Destructive: yes. Idempotent (safe to retry): yes. Inputs: - `app_id` (`string`, required): The Butterbase app's unique ID the agent belongs to. - `name` (`string`, required): The unique name of the agent to delete. Example input: `{"app_id":"","name":"Pro"}` ### `butterbase_app_delete` Delete App · Destructive Permanently delete a Butterbase application, along with its database, auth users, storage files, and every other app-scoped resource. Returns a confirmation of the deletion (Butterbase's docs do not publish the exact response shape for this endpoint). Use butterbase_app_delete only when you intend to remove the entire app; this action is irreversible and cannot be undone. Read only: no. Destructive: yes. Idempotent (safe to retry): yes. Inputs: - `app_id` (`string`, required): The Butterbase application ID to permanently delete, as returned when the app was created or from butterbase_apps_list. Example: app_abc123. Example input: `{"app_id":""}` ### `butterbase_auth_oauth_config_delete` Delete OAuth Provider Config · Destructive Remove a social-login (OAuth) provider configuration from a Butterbase app. End-users will no longer be able to sign in through that provider. Returns a success confirmation once the configuration is removed. Use butterbase_auth_oauth_config_delete to fully remove a provider. Use butterbase_auth_oauth_config_update instead if you just need to change its credentials. Read only: no. Destructive: yes. Idempotent (safe to retry): yes. Inputs: - `app_id` (`string`, required): The unique ID of the Butterbase app the provider is configured on. - `provider` (`string`, required): The OAuth provider identifier to remove, e.g. one of google, github, discord, facebook, linkedin, microsoft, apple, x, or a custom provider identifier. Example input: `{"app_id":"","provider":""}` ### `butterbase_billing_cancel` Cancel Subscription · Destructive Cancel the current end user's subscription for a Butterbase app, ending it at the end of the current billing period. Returns a cancellation confirmation for the subscription. Use butterbase_billing_cancel to stop a subscription's automatic renewal. Use butterbase_billing_subscription_get first to confirm which subscription is active, or butterbase_billing_subscribe to start a new one afterward. Read only: no. Destructive: yes. Idempotent (safe to retry): no. Inputs: - `app_id` (`string`, required): The unique ID of the Butterbase app whose current end user's subscription you want to cancel. Example input: `{"app_id":""}` ### `butterbase_custom_domain_delete` Delete Custom Domain · Destructive Remove a custom domain registration from a Butterbase app. This detaches the domain from the app's deployment and cannot be undone. Returns a confirmation; Butterbase's docs do not show an explicit response body for this endpoint, so it may return an empty response. Use butterbase_custom_domain_delete to permanently remove a domain you no longer want to serve traffic on; find its ID first from the app's list of registered custom domains. Read only: no. Destructive: yes. Idempotent (safe to retry): yes. Inputs: - `app_id` (`string`, required): The unique identifier of the Butterbase app the custom domain is registered to. - `id` (`string`, required): The unique identifier of the custom domain to remove. Example input: `{"app_id":"","id":""}` ### `butterbase_frontend_deployment_cancel` Cancel Frontend Deployment · Destructive Cancel an in-progress frontend deployment. Returns the deployment's updated status, expected to move to CANCELED; exact response fields are not published in Butterbase's docs. Use butterbase_frontend_deployment_cancel to abort a deployment that's stuck or was started by mistake while it's still WAITING, UPLOADING, or BUILDING. Use butterbase_frontend_deployment_delete afterward if you also want to remove the deployment record entirely. Read only: no. Destructive: yes. Idempotent (safe to retry): no. Inputs: - `app_id` (`string`, required): The Butterbase app that owns the frontend deployment, exactly as shown in the Butterbase dashboard or returned when the app was created. - `id` (`string`, required): The unique identifier of the in-progress frontend deployment to cancel. Example input: `{"app_id":"","id":""}` ### `butterbase_frontend_deployment_delete` Delete Frontend Deployment · Destructive Remove a frontend deployment record. Butterbase's docs don't publish a response body for this endpoint; expect an empty success response. Use butterbase_frontend_deployment_delete to clean up a deployment record you no longer need, such as a failed or canceled one. Use butterbase_frontend_deployment_cancel first if the deployment is still actively building. Read only: no. Destructive: yes. Idempotent (safe to retry): yes. Inputs: - `app_id` (`string`, required): The Butterbase app that owns the frontend deployment, exactly as shown in the Butterbase dashboard or returned when the app was created. - `id` (`string`, required): The unique identifier of the frontend deployment record to delete. Example input: `{"app_id":"","id":""}` ### `butterbase_function_delete` Delete Function · Destructive Permanently delete a deployed serverless function, including its code, triggers, and stored environment variables. Returns a confirmation once removed (Butterbase's docs don't publish the exact response shape). Use butterbase_function_delete to remove a function that is no longer needed. Use butterbase_functions_list or butterbase_function_get first to confirm the exact function name before deleting. Read only: no. Destructive: yes. Idempotent (safe to retry): yes. Inputs: - `app_id` (`string`, required): The Butterbase application ID the function belongs to. - `name` (`string`, required): The exact name of the deployed function to permanently delete. Example input: `{"app_id":"","name":"Pro"}` ### `butterbase_integration_configure_delete` Disable Integration · Destructive Disable a previously enabled third-party integration toolkit for a Butterbase app, removing its configuration. Returns a confirmation; exact response fields are not published in Butterbase's docs. Use butterbase_integration_configure_delete to turn off a toolkit that was enabled via butterbase_integration_configure. Any tool execution against this toolkit will fail until it is re-enabled. Read only: no. Destructive: yes. Idempotent (safe to retry): yes. Inputs: - `app_id` (`string`, required): The Butterbase app ID the toolkit is configured under, as shown in the app's dashboard URL or returned by the app-creation API. - `toolkit` (`string`, required): The slug of the integration toolkit to disable, matching how it was enabled via butterbase_integration_configure. Example input: `{"app_id":"","toolkit":"gmail"}` ### `butterbase_integration_connection_delete` Disconnect Integration · Destructive Disconnect one of an end user's connected third-party integration accounts from a Butterbase app. Returns a confirmation of the disconnection (exact response fields are not published in Butterbase's docs). Use butterbase_integration_connections_list first to find the connection id, then call butterbase_integration_connection_delete to revoke it. Read only: no. Destructive: yes. Idempotent (safe to retry): yes. Inputs: - `app_id` (`string`, required): The Butterbase app ID that owns the connection. - `connection_id` (`string`, required): The ID of the connected integration account to disconnect, as returned by butterbase_integration_connections_list. - `user_id` (`string`, optional): The end user who owns the connection. Butterbase's docs do not explicitly document a user-scoping parameter for this endpoint, but sibling endpoints in the Integrations API (connect, execute) require a userId field when authenticating with an API key rather than a JWT. Since this connector always authenticates with a platform API key, pass the end user's ID here if your app has more than one end user. Example input: `{"app_id":"","connection_id":""}` ### `butterbase_kv_delete` Delete KV Key · Destructive Delete a single key from a Butterbase app's key-value store. Returns a deleted count (0, 1, or 2) indicating whether the key existed and was removed. Use butterbase_kv_delete to remove one key by name. Use butterbase_kv_batch to delete (or get/set) many keys in a single request. Read only: no. Destructive: yes. Idempotent (safe to retry): yes. Inputs: - `app_id` (`string`, required): The Butterbase application ID that owns this key-value store. - `key` (`string`, required): The key-value store key to delete. Example input: `{"app_id":"","key":""}` ### `butterbase_kv_expose_rule_delete` Delete KV Expose Rule · Destructive Remove a key-value expose rule so its key pattern is no longer reachable by end-user JWTs. Returns whether a matching rule was actually found and deleted. Use butterbase_kv_expose_rule_delete to revoke end-user access to a specific key pattern. Use butterbase_kv_expose_rules_list first to find the exact pattern, and butterbase_kv_expose_rule_set to change a rule's roles instead of removing it. Read only: no. Destructive: yes. Idempotent (safe to retry): yes. Inputs: - `app_id` (`string`, required): The Butterbase application ID the expose rule belongs to. - `pattern` (`string`, required): The exact glob-style key pattern of the expose rule to remove, e.g. session/{user.id}/*. This must match the pattern as it was created; it is sent as a URL path segment and is percent-encoded automatically. Example input: `{"app_id":"","pattern":""}` ### `butterbase_kv_flush` Flush KV Store · Destructive Delete every key in an app's key-value store in a single irreversible operation, optionally also wiping its configured expose rules. Returns the number of keys that were deleted. Use butterbase_kv_flush only to wipe an app's entire KV store at once, such as before decommissioning an app or resetting a development environment -- not to remove a single key or a single expose rule. Requires the confirm field to be set to true, and only works with a Butterbase function key or platform-level API key -- end-user tokens cannot call this endpoint. Read only: no. Destructive: yes. Idempotent (safe to retry): no. Inputs: - `app_id` (`string`, required): The Butterbase application ID that owns the key-value store to flush. - `confirm` (`boolean`, required): Explicit confirmation that you intend to permanently delete every key in this app's KV store. Must be set to true or the request is rejected -- there is no other safeguard against accidental data loss. - `include_config` (`boolean`, optional): Whether to also delete the app's configured KV expose rules (the glob patterns that grant end-user JWTs access to specific keys) as part of the flush. Defaults to false, which flushes only key/value data and leaves expose rules intact. Default: `false`. Example input: `{"app_id":"","confirm":true}` ### `butterbase_mcp_server_delete` Delete MCP Server · Destructive Remove a registered MCP server so it's no longer available as a tool source for the app's agents. Returns no content on success. Use butterbase_mcp_server_delete to permanently unregister an MCP server found via butterbase_mcp_servers_list. Read only: no. Destructive: yes. Idempotent (safe to retry): yes. Inputs: - `app_id` (`string`, required): The id of the Butterbase app the MCP server is registered under. - `id` (`string`, required): The id of the MCP server registration to remove, as returned by butterbase_mcp_server_register or butterbase_mcp_servers_list. Example input: `{"app_id":"","id":""}` ### `butterbase_meeting_bot_stop` Stop Meeting Bot · Destructive Force a meeting bot to immediately leave its call. Returns no content; the bot's status transitions to ended shortly after the call is made. Use butterbase_meeting_bot_stop to end a recording early. Calling it again on an already-stopped bot is safe and has no further effect. Read only: no. Destructive: yes. Idempotent (safe to retry): yes. Inputs: - `app_id` (`string`, required): The unique identifier of the Butterbase app the meeting bot was dispatched under. - `bot_id` (`string`, required): The unique identifier of the meeting bot to stop, as returned by butterbase_meeting_bot_create or butterbase_meeting_bots_list. Example input: `{"app_id":"","bot_id":""}` ### `butterbase_rag_collection_delete` Delete RAG Collection · Destructive Permanently delete a RAG collection along with all of its documents, text chunks, and embeddings. Returns no content on success. Use butterbase_rag_collection_delete only when you want to remove an entire collection — this cannot be undone. Use butterbase_rag_document_delete to remove a single document instead of the whole collection. Read only: no. Destructive: yes. Idempotent (safe to retry): yes. Inputs: - `app_id` (`string`, required): The Butterbase app ID that owns this collection. Found in the app's dashboard URL or via Butterbase's apps listing. - `name` (`string`, required): The name of the RAG collection to permanently delete, exactly as it was created. Example input: `{"app_id":"","name":"Pro"}` ### `butterbase_rag_document_delete` Delete RAG Document · Destructive Delete a single document and all of its vector chunks from a RAG collection. Returns no content on success. Use butterbase_rag_document_delete to remove one document while keeping the rest of the collection intact. Use butterbase_rag_collection_delete to remove an entire collection instead of a single document. Read only: no. Destructive: yes. Idempotent (safe to retry): yes. Inputs: - `app_id` (`string`, required): The Butterbase app ID that owns this collection. Found in the app's dashboard URL or via Butterbase's apps listing. - `document_id` (`string`, required): The id of the document to permanently delete, as returned by butterbase_rag_document_ingest or butterbase_rag_documents_list. - `name` (`string`, required): The name of the RAG collection that contains this document, exactly as it was created. Example input: `{"app_id":"","document_id":"","name":"Pro"}` ### `butterbase_repo_delete` Delete App Repo · Destructive Permanently wipe an app's entire repo (its versioned file-manifest/snapshot history) in Butterbase. Returns a confirmation response (Butterbase's docs do not publish the exact response fields for this endpoint). Use butterbase_repo_delete only to erase all snapshot/version history for the app; the app itself and its database, auth, and storage data are unaffected, and the action cannot be undone. Read only: no. Destructive: yes. Idempotent (safe to retry): yes. Inputs: - `app_id` (`string`, required): The Butterbase application ID whose entire repo (versioned snapshot history) will be permanently wiped. Example: app_abc123. Example input: `{"app_id":""}` ### `butterbase_storage_object_delete` Delete Storage Object · Destructive Delete a file from a Butterbase app's storage. This permanently removes the file and cannot be undone. Returns a confirmation; Butterbase's docs do not show an explicit response body for this endpoint, so it may return an empty response. Use this to permanently remove a specific file once you have its object ID; use butterbase_storage_objects_list first to find the object ID of the file to delete. Read only: no. Destructive: yes. Idempotent (safe to retry): yes. Inputs: - `app_id` (`string`, required): The unique identifier of the Butterbase app that owns the file. - `object_id` (`string`, required): The unique identifier of the stored file to permanently delete. Get this from butterbase_storage_objects_list. Example input: `{"app_id":"","object_id":""}` ### `butterbase_substrate_attention_rule_delete` Delete Attention Rule · Destructive Permanently delete a Substrate attention rule. This cannot be undone and stops the rule from ever firing again. Returns a confirmation; Butterbase's docs do not show an explicit response body for this endpoint, so it may return an empty response. Use butterbase_substrate_attention_rule_disable instead if you just want to pause a rule without losing its definition. Requires a Butterbase Substrate-scoped API key (bb_sub_...) — a standard platform API key is rejected with a 403 on all Substrate endpoints. Read only: no. Destructive: yes. Idempotent (safe to retry): yes. Inputs: - `rule_id` (`string`, required): The unique id of the attention rule to permanently delete, as returned by butterbase_substrate_attention_rule_create or a prior list call. Example input: `{"rule_id":""}` ### `butterbase_substrate_outbox_target_delete` Delete Outbox Target · Destructive Remove the outbound webhook target registered for a Substrate capability. Butterbase stops sending webhook notifications for that capability's actions once removed. Returns a confirmation; Butterbase's docs do not show an explicit response body for this endpoint, so it may return an empty response. Use butterbase_substrate_outbox_target_delete to stop notifications for a capability. Call butterbase_substrate_outbox_target_set again instead if you only need to point the target at a new URL or secret. Requires a Butterbase Substrate-scoped API key (bb_sub_...) — a standard platform API key is rejected with a 403 on all Substrate endpoints. Read only: no. Destructive: yes. Idempotent (safe to retry): yes. Inputs: - `capability` (`string`, required): Which Substrate capability's webhook target to remove. Must be one of the capability names Substrate accepts on POST /v1/me/substrate/actions/propose. One of: `record_decision`, `record_commitment`, `record_learning`, `record_principle`, `supersede_decision`, `retire_principle`, `upsert_entity`, `update_entity`, `patch_entity`, `merge_entities`, `delete_entity`, `upsert_source_artifact`, `revert_action`, `bulk_revert_actions`, `send_email_draft`. Example input: `{"capability":"record_decision"}` ### `butterbase_table_row_delete` Delete Table Row · Destructive Delete a single row from a Butterbase app table by its primary key. Returns a confirmation of the deletion (Butterbase's docs do not confirm whether the response body is empty or a JSON object). Use butterbase_table_row_delete to permanently remove one row; this action cannot be undone. Read only: no. Destructive: yes. Idempotent (safe to retry): yes. Inputs: - `app_id` (`string`, required): The Butterbase application ID that owns the table, as returned when the app was created or from butterbase_apps_list. Example: app_abc123. - `id` (`string`, required): The primary key value of the row to delete, matching whatever type the table's primary key column uses (e.g. an integer id or a UUID). Example: 42. - `table` (`string`, required): The name of the table containing the row to delete, exactly as defined in the app's schema (see butterbase_schema_get). Example: posts. Example input: `{"app_id":"","id":"","table":"
"}` ## Related Other Developer Tools connectors ([all 92](/agentkit/connectors/?category=developer-tools)): - [GitHub](/agentkit/connectors/github/): Scalekit connector, OAuth, 217 tools - [Datadog](/agentkit/connectors/datadog/): Scalekit connector, API key, 105 tools - [Linear](/agentkit/connectors/linear/): Scalekit connector, OAuth, 62 tools --- ## More Scalekit documentation | Resource | What it contains | When to use it | |----------|-----------------|----------------| | [/llms.txt](/llms.txt) | Structured index with routing hints per product area | Start here — find which documentation set covers your topic before loading full content | | [/llms-full.txt](/llms-full.txt) | Complete documentation for all Scalekit products in one file | Use when you need exhaustive context across multiple products or when the topic spans several areas | | [sitemap-0.xml](https://docs.scalekit.com/sitemap-0.xml) | Full URL list of every documentation page | Use to discover specific page URLs you can fetch for targeted, page-level answers |