Gumloop MCP Server
A Gumloop MCP server/CLI exposing 92 tools (50 reads, 42 confirmation-gated writes) that let an AI agent or script operate Gumloop flows, agents, sessions, Brain, skills, artifacts, evaluations and organization administration under private, per-call approval.
Flows and runs — list workbooks/saved flows, inspect a flow's input schema, start a run, kill a run, poll run details and fetch run history.
Files — upload single/multiple files (base64 or local path), download run files to a private
output_file, and upload files into a session.Agents — list, create, retrieve and update agents; read version history and snapshots; attach/detach skills and MCP servers.
Sessions — create, retrieve, rename, cancel, send messages, upload attachments, resolve pending approvals, and manage the message queue (list/queue/update/delete/send now).
Chat and models — create OpenAI-style non-streaming chat completions (incl. image modalities and tool calls), list available models, and ask the Chew router which model it would pick.
Brain — hybrid search across indexed sources, list/create/delete sources, upload/list/delete files, read credit estimates and approve a draft source.
Skills and artifacts — list/create/update/delete skills, download a skill archive, list agent artifacts and download one.
MCP servers catalog — list/retrieve servers, enumerate their tools, resources and prompts, read a resource, render a prompt, and execute batched tool calls.
Evaluations — agent-level results, metrics, config and runs; organization-level evaluations with targets, runs, results and metrics.
Administration — audit logs, workspace user management, custom-role membership, role credit limits (list/get/set), data exports and export status.
Discovery/identity — static schema and help, plus local
list_accountsfor private profile labels with no network call.
Confluence spaces connected as Gumloop Brain sources can be searched through the server's hybrid semantic/keyword search, returning ranked, cited snippets from indexed Confluence content.
GitHub repositories connected as Gumloop Brain sources can be searched through the server's hybrid semantic/keyword search, returning ranked, cited snippets from indexed repository content.
Google Drive content connected as a Gumloop Brain source can be searched through the server's hybrid semantic/keyword search, returning ranked, cited snippets from indexed Drive documents.
Notion workspaces connected as Gumloop Brain sources can be queried through the server's hybrid semantic/keyword search tool, which returns ranked, cited snippets from indexed Notion pages.
Slack workspaces connected as Gumloop Brain sources can be searched through the server's hybrid semantic/keyword search, returning ranked, cited snippets from indexed Slack content.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Gumloop MCP Server list my saved flows"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Gumloop MCP Server & CLI
Gumloop MCP server and CLI for Codex and AI agents. 92 tools for current flows, agents, sessions, Brain, skills, artifacts and administration, with private accounts and explicit operation approval. One shared implementation supplies both binaries and a desktop bundle.
Built and maintained by Navid Moazzez. Built on Slipway, which turns one definition of each tool into the MCP server and the CLI. The complete guide is on navid.me.
The terminal illustrates real command names and approval flow. It is not a recording of a provider account run. Gumloop already has official CLI and hosted MCP products; their supported platform, authentication and workflows are compared below.
Requires Node 22+ and eligible Gumloop API access for account operations. Validation: fixture tests, schema validation and protocol/artifact discovery are separate from provider-account and desktop GUI outcomes, which are not claimed. Section 7 has the measured token costs.
Two ways to use it
Command line
npm install -g @thenavidm/gumloop-mcp-cli@latest
gumloop-cli
gumloop-cli list-agents --agent
gumloop-cli schema start-flow
gumloop-cli start-flow --payload-file /absolute/private/approved-flow.json --account work --confirm --agentMCP server, for your AI app
codex mcp add gumloop -- npx -y @thenavidm/gumloop-mcp-cli@latestConfigure private credentials first. Ask: “Inspect this existing run and return its state; do not start another run.” Read INSTALL.md for complete client/OS routes.
Which one
Where you work | Surface |
Codex or shell agent | Shared CLI, local MCP or both |
Desktop chat | Compatible local MCP/desktop archive |
Scripts/CI | CLI or MCP client |
Remote-only client | Official hosted MCP |
Related MCP server: paperclip-mcp
Features
Capability | CLI command | MCP tool |
Saved flows and inputs | list-flows / get-input-schema | list_flows / get_input_schema |
Run and inspect | start-flow / get-run-details | start_flow / get_run_details |
Agents and sessions | list-agents / create-session / retrieve-session | list_agents / create_session / retrieve_session |
Skills and Brain | create-skill / search-brain | create_skill / search_brain |
Private file delivery | download-artifact-file / download-files | download_artifact_file / download_files |
Explicit account selection | list-accounts / --account | list_accounts / account |
Diagnosis/setup | doctor / login | CLI utilities |
Contents
Number | Section | What it covers |
1 | What you can ask it | |
2 | Quick install | |
3 | Set up Gumloop access | |
4 | Connect your client | |
5 | Check it works | |
6 | Output, flags and exit codes | |
7 | MCP or CLI and token cost | |
8 | Every tool and argument | |
9 | Flows, sessions and account workflows | |
10 | Jobs, pagination and private files | |
11 | Several private accounts | |
12 | Writing safely | |
13 | How it works | |
14 | Your data | |
15 | Environment variables | |
16 | Updates and removal | |
17 | Troubleshooting | |
18 | API coverage and comparisons | |
19 | Versions | |
20 | FAQ |
1. What you can ask it
Inspect accessible agents, versions, teams and models.
List saved flows and their exact input schema before approving a run.
Start only the selected flow, keep its returned run ID and read its state.
Create a reviewed agent session, then inspect its approval requirements.
Approve only the selected session checkpoint; do not approve a whole conversation implicitly.
Upload a selected regular file and save an existing run download privately.
Review organization usage, audit records and applicable role credit limits.
Actual discovery supplies 92 tools: 50 reads and 42 confirmation-gated operations, from all 91 reviewed current REST operations plus list_accounts. The shared handlers cover MCP and native Node CLI. This is protocol/schema evidence; account outcomes and desktop GUI installation remain separate.
2. Quick install
npm install -g @thenavidm/gumloop-mcp-cli@latest
gumloop-cli --version
gumloop-cli login
gumloop-cli doctor
gumloop-cli toolsNode 22+ is required for manual installation. The versioned desktop archive bundles production dependencies for a compatible host. Read INSTALL.md before configuring credentials. After private setup:
codex mcp add gumloop -- npx -y @thenavidm/gumloop-mcp-cli@latest
codex mcp list3. Set up Gumloop access
Private credentials and permissions
Open the intended account's Connectors settings. Select Gumloop API Key and create the personal or team key needed for your task.
Read Profile Settings for your user ID. A team ID is optional; older flow endpoints call it project_id. Set GUMLOOP_USER_ID and, when appropriate, GUMLOOP_TEAM_ID in private settings.
Save the credential as a token-only regular file outside repositories. Set GUMLOOP_TOKEN_FILE to its absolute path; GUMLOOP_API_KEY is the alternative. Do not paste real keys into chat or command examples.
Run gumloop-cli doctor, then doctor --network. The network check reads accessible agent metadata without printing account content.
Inspect the exact schema and selected resource before confirming an operation. Runs can spend credits and invoke connected downstream services.
Current authentication docs require Pro or above for API keys. Personal keys act as their owner; team keys can act as team members through the requested user identity. Workflow-step credential settings decide personal/team credentials when project_id is supplied. Local profiles do not bypass account, role or team permissions.
Requests use Authorization: Bearer, with the selected profile user ID as x-auth-key, following the current SDK. Ordinary endpoints use https://api.gumloop.com/api/v1; non-streaming chat uses the separately documented https://ws.gumloop.com/api/v1. No arbitrary host override or redirects are accepted.
For POSIX, use a private 0700 directory and regular 0600 token-only file, no symlink, at most 64 KB. Windows requires a user-only ACL; POSIX checks do not verify it. File credentials override environment credentials and are cached until restart. The package does not read an automatic .env, use the OS keychain or start browser login.
OAuth and rotation
An already authorized OAuth access token can be supplied through the same private Bearer credential path. This wrapper does not register an OAuth app, accept refresh tokens, refresh access tokens or manage consent. OAuth docs describe invite-only client registration, authorization code with PKCE S256 and gumloop_api/userinfo scopes. gumloop_api requires Pro or above; requesting userinfo alone is not API permission. Use an expiry-aware issuer or the official CLI's supported OAuth/keychain workflow when automatic refresh is needed.
Rotate/revoke the intended grant through its provider controls, update private settings and restart. Removing a local package does not revoke provider credentials, undo runs or remove hosted data.
Plans, credits and rate limits
The AGPL wrapper is free; Gumloop account access and processing are billed separately. Credit documentation describes variable charges for model work, connector calls, compute and orchestration; Brain searches can also incur charges. Local read-only mode is an operation policy, not a guarantee of zero provider charges. Credit-consuming Brain search is confirmation-gated here.
Agent concurrency limits are organization-wide, currently 25 on Pro and 100 on Enterprise, with customizable Enterprise limits. Pro rejects excess agent work; Enterprise can queue it. Webhook triggers separately document 100 requests/minute per trigger. These are distinct limits; this wrapper's default 150 ms account/process pacing reserves no provider capacity.
GET 429 retries require an explicit Retry-After at most ten seconds, default two/max five retries. Missing/longer delays return exit 7. Mutations, paid Brain search and network timeouts never retry automatically. Local JSON request cap is 5 MiB; responses/downloads are capped at 10 MiB. These local caps are separate from vendor storage, upload and pagination limits.
4. Connect your client
INSTALL.md gives Codex-first setup, optional Claude Code, desktop archive/manual configuration, Cursor, VS Code/Copilot, Windsurf, Zed, Gemini CLI, Docker and Cline. The local transport is stdio. Configure private credentials in the actual client environment; GUI apps and remote containers do not inherit every shell setting.
The published official gumloop 0.5.2 CLI and current provider docs explicitly refuse native Windows and recommend WSL or the Python SDK. This wrapper targets Node 22+ on native Windows, macOS and Linux. Compatible desktop-host availability and GUI installation are separate from CLI portability. Remote-only clients can use the official https://mcp.gumloop.com/gumloop/mcp endpoint.
npm ships SKILL.md but does not register it automatically. Install it through the client's supported skill location. A connection/client approval and this wrapper's confirm argument are separate controls.
5. Check it works
gumloop-cli --version
gumloop-cli doctor
gumloop-cli doctor --network
gumloop-cli list-accounts --agent
gumloop-cli list-agents --agentDiscovery, schemas/help and account labels need no provider key. Network doctor reads GET /agents and prints only diagnostic status. This validates that request, not every account operation. Full discovery exposes 92 tools; read-only discovery exposes 50. Missing credentials exits 10, invalid input or refused operations exit 2. First validate an existing resource; do not start billable automation merely to test installation.
6. Output, flags and exit codes
Tool results go to stdout. Errors are JSON on stderr. JSON operations return structured results, so --select can retain nested fields. Private download operations return file metadata; binary bytes and signed results stay in the requested private file.
gumloop-cli start-flow --help
gumloop-cli schema start-flow
gumloop-cli list-agents --agent --select agentsFlag | What it does |
| JSON output |
| Single-line JSON |
| Compact JSON and no prompts; never confirms a write |
| Keep selected fields; dotted paths descend and arrays are traversed |
| Confirm the requested flow, session, paid search or account operation |
| Automation switches; none overrides the spending guard |
Global output flags apply to tool commands. doctor has its own --network option and returns a JSON diagnostic.
Exit code | Meaning | What a script should do |
0 | Success | Read stdout |
1 | Unexpected error | Report it with the command that caused it |
2 | Usage, invalid input, a refused write, an unknown command or a hidden write | Fix the input or confirm only the requested action |
3 | Job or local upload file not found | Check the ID/path |
4 | Authentication or entitlement rejected | Check private credential settings and permissions |
5 | API or network failure | Inspect an accepted job before another paid submission |
7 | Rate limited | Wait; do not loop over paid submissions |
10 | Credentials not configured | Complete local setup |
The underscore spelling also works. start_flow and start-flow call the same tool. Nested objects use quoted JSON. Arrays of objects use repeated flags, one JSON object at a time.
7. MCP or CLI and token cost
MCP and CLI use the same catalogue, schemas, handlers and write guard: Slipway builds the MCP server, over stdio or --http, and the CLI from each tool's one definition. Shell scripts can select fields with --select after receipt; this does not change upstream result size or billing.
Measured on 2026-10-05 against 2.0.2, with Claude Code 2.1.286 on Claude Opus 5.5 (one short prompt with and without the server connected, the difference read from the API's own usage figures) and Codex 0.159.3 on gpt-6.1-sol:
Cost | 2.0.2 | 3.0.0 |
Claude Code, every tool loaded, every message | 61,936 | 56,695 |
Claude Code's default, tool search, every message | 1,486 | 1,488 |
| 3,150 | 3,210 |
Codex over the CLI, one task, median of five | 107,376 | 83,661 |
Codex over MCP, the same task, median of five | 78,443 | 78,249 |
The task was "find the command that starts a flow run, and the flags it requires". Every tool loaded costs less because parts that several tools repeated are written once. Over the CLI, every 3.0.0 run asked which, whose answer carries the command's help, where every 2.0.2 run read the command list and then the help: one request fewer. Over MCP, 3.0.0 cost slightly less. SKILL.md costs 60 more because it says how approval works over MCP and what exit codes 1 and 2 cover.
Tool-list bytes or characters divided by four are not API usage, and no other offering was measured.
Provider credits and client-model tokens are separate.
8. Every tool and argument
Every route and argument below comes from actual stdio discovery and the reviewed current schema. Use schema COMMAND for exact inline nested objects and unions.
Tool | Route | Mode |
|
| Confirm exact operation |
|
| Confirm exact operation |
|
| Read |
|
| Read |
|
| Read |
|
| Read |
|
| Read |
|
| Read |
|
| Read |
|
| Confirm exact operation |
|
| Confirm exact operation |
|
| Read |
|
| Confirm exact operation |
|
| Confirm exact operation |
|
| Read |
|
| Read |
|
| Confirm exact operation |
|
| Confirm exact operation |
|
| Read |
|
| Read |
|
| Confirm exact operation |
|
| Read |
|
| Confirm exact operation |
|
| Confirm exact operation |
|
| Read |
|
| Read |
|
| Read |
|
| Read |
|
| Confirm exact operation |
|
| Read |
|
| Confirm exact operation |
|
| Confirm exact operation |
|
| Read |
|
| Confirm exact operation |
|
| Read |
|
| Confirm exact operation |
|
| Confirm exact operation |
|
| Confirm exact operation |
|
| Confirm exact operation |
|
| Confirm exact operation |
|
| Read |
|
| Confirm exact operation |
|
| Confirm exact operation |
|
| Confirm exact operation |
|
| Confirm exact operation |
|
| Read |
|
| Read |
|
| Read |
|
| Read |
|
| Read |
|
| Read |
|
| Read |
|
| Confirm exact operation |
|
| Confirm exact operation |
|
| Read |
|
| Confirm exact operation |
|
| Read |
|
| Confirm exact operation |
|
| Read |
|
| Confirm exact operation |
|
| Confirm exact operation |
|
| Read |
|
| Confirm exact operation |
|
| Read |
|
| Confirm exact operation |
|
| Confirm exact operation |
|
| Confirm exact operation |
|
| Read |
|
| Read |
|
| Read |
|
| Read |
|
| Confirm exact operation |
|
| Read |
|
| Read |
|
| Confirm exact operation |
|
| Read |
|
| Read |
|
| Read |
|
| Confirm exact operation |
|
| Read |
|
| Read |
|
| Read |
|
| Confirm exact operation |
|
| Read |
|
| Confirm exact operation |
|
| Confirm exact operation |
|
| Confirm exact operation |
|
| Confirm exact operation |
|
| Read |
|
| Read |
|
| Read |
| Local, no network | Read |
start_flow
gumloop-cli start-flow
Argument | Required | Type | Details |
| No; body and guard rules apply | string | The id for the user initiating the flow. |
| No; body and guard rules apply | string | (Optional) The id of the project within which the flow is executed. |
| No; body and guard rules apply | string | The id for the saved flow. |
| No; body and guard rules apply | string | Named private Gumloop account; selects private credentials and user/team identity. |
| No; body and guard rules apply | boolean | Set true only when the user asked for exactly this action. |
| No; body and guard rules apply | object | Complete JSON request body instead of body flags. Preserves current endpoint fields and values. |
| No; body and guard rules apply | string | Regular local JSON body file, at most 5 MB. Cannot be mixed with body flags or payload. minLength: |
A body is required. Native body flags, payload and payload_file are mutually exclusive. Required native body fields: saved_item_id, user_id. Profile defaults fill supported user/team identity fields before body validation.
kill_flow
gumloop-cli kill-flow
Argument | Required | Type | Details |
| No; body and guard rules apply | string | The ID of the pipeline run to kill. |
| No; body and guard rules apply | string | The user ID. Required if project_id is not provided. |
| No; body and guard rules apply | string | The project ID. Required if user_id is not provided. |
| No; body and guard rules apply | string | Named private Gumloop account; selects private credentials and user/team identity. |
| No; body and guard rules apply | boolean | Set true only when the user asked for exactly this action. |
| No; body and guard rules apply | object | Complete JSON request body instead of body flags. Preserves current endpoint fields and values. |
| No; body and guard rules apply | string | Regular local JSON body file, at most 5 MB. Cannot be mixed with body flags or payload. minLength: |
A body is required. Native body flags, payload and payload_file are mutually exclusive. Required native body fields: run_id. Profile defaults fill supported user/team identity fields before body validation.
get_run_details
gumloop-cli get-run-details
Argument | Required | Type | Details |
| Yes | string | ID of the flow run to retrieve |
| No; body and guard rules apply | string | The id for the user initiating the flow. Required if project_id is not provided. |
| No; body and guard rules apply | string | The id of the project within which the flow is executed. Required if user_id is not provided. |
| No; body and guard rules apply | string | Named private Gumloop account; selects private credentials and user/team identity. |
list_workbooks
gumloop-cli list-workbooks
Argument | Required | Type | Details |
| No; body and guard rules apply | string | The user ID for which to list workbooks. Required if project_id is not provided. |
| No; body and guard rules apply | string | The project ID for which to list workbooks. Required if user_id is not provided. |
| No; body and guard rules apply | string | Named private Gumloop account; selects private credentials and user/team identity. |
list_flows
gumloop-cli list-flows
Argument | Required | Type | Details |
| No; body and guard rules apply | string | The user ID to for which to list items. Required if project_id is not provided. |
| No; body and guard rules apply | string | The project ID for which to list items. Required if user_id is not provided. |
| No; body and guard rules apply | string | Named private Gumloop account; selects private credentials and user/team identity. |
get_input_schema
gumloop-cli get-input-schema
Argument | Required | Type | Details |
| Yes | string | The ID of the saved item for which to retrieve input schemas. |
| No; body and guard rules apply | string | User ID that created the flow. Required if project_id is not provided. |
| No; body and guard rules apply | string | Project ID that the flow is under. Required if user_id is not provided. |
| No; body and guard rules apply | string | Named private Gumloop account; selects private credentials and user/team identity. |
get_run_history
gumloop-cli get-run-history
Argument | Required | Type | Details |
| No; body and guard rules apply | string | The ID of the workbook to retrieve run history for. Required if saved_item_id is not provided. |
| No; body and guard rules apply | string | The ID of the saved item to retrieve run history for. Required if workbook_id is not provided. |
| No; body and guard rules apply | string | The user ID. Required if project_id is not provided. |
| No; body and guard rules apply | string | The project ID. Required if user_id is not provided. |
| No; body and guard rules apply | string | Named private Gumloop account; selects private credentials and user/team identity. |
download_file
gumloop-cli download-file
Argument | Required | Type | Details |
| No; body and guard rules apply | string | The name of the file to download. |
| No; body and guard rules apply | string | The ID of the flow run associated with the file. |
| No; body and guard rules apply | string | The saved item ID associated with the file. |
| No; body and guard rules apply | string | Optional. The user ID associated with the flow run. |
| No; body and guard rules apply | string | Optional. The project ID associated with the flow run. |
| No; body and guard rules apply | string | Named private Gumloop account; selects private credentials and user/team identity. |
| No; body and guard rules apply | object | Complete JSON request body instead of body flags. Preserves current endpoint fields and values. |
| No; body and guard rules apply | string | Regular local JSON body file, at most 5 MB. Cannot be mixed with body flags or payload. minLength: |
| Yes | string | New absolute result file in a private owner-only directory. Private download or signed credential result stays out of model output; no overwrite. minLength: |
A body is required. Native body flags, payload and payload_file are mutually exclusive. Required native body fields: Inspect endpoint requirements. Profile defaults fill supported user/team identity fields before body validation.
output_file must be new and absolute in a private directory, reserved exclusively before the API call. Binary bytes or signed JSON are kept out of model output. This wrapper never follows a signed external download URL.
download_files
gumloop-cli download-files
Argument | Required | Type | Details |
| No; body and guard rules apply | array | An array of file names to download. Items: string. |
| No; body and guard rules apply | string | The ID of the flow run associated with the files. |
| No; body and guard rules apply | string | The user ID associated with the files. Required if project_id is not provided. |
| No; body and guard rules apply | string | The project ID associated with the files. Required if user_id is not provided. |
| No; body and guard rules apply | string | Optional. The saved item ID associated with the files. |
| No; body and guard rules apply | string | Named private Gumloop account; selects private credentials and user/team identity. |
| No; body and guard rules apply | object | Complete JSON request body instead of body flags. Preserves current endpoint fields and values. |
| No; body and guard rules apply | string | Regular local JSON body file, at most 5 MB. Cannot be mixed with body flags or payload. minLength: |
| Yes | string | New absolute result file in a private owner-only directory. Private download or signed credential result stays out of model output; no overwrite. minLength: |
A body is required. Native body flags, payload and payload_file are mutually exclusive. Required native body fields: Inspect endpoint requirements. Profile defaults fill supported user/team identity fields before body validation.
output_file must be new and absolute in a private directory, reserved exclusively before the API call. Binary bytes or signed JSON are kept out of model output. This wrapper never follows a signed external download URL.
upload_file
gumloop-cli upload-file
Argument | Required | Type | Details |
| No; body and guard rules apply | string | The name of the file to be uploaded. |
| No; body and guard rules apply | string | Base64 encoded content of the file. format: |
| No; body and guard rules apply | string | The user ID associated with the file. Required if project_id is not provided. |
| No; body and guard rules apply | string | The project ID associated with the file. Required if user_id is not provided. |
| No; body and guard rules apply | string | Named private Gumloop account; selects private credentials and user/team identity. |
| No; body and guard rules apply | boolean | Set true only when the user asked for exactly this action. |
| No; body and guard rules apply | object | Complete JSON request body instead of body flags. Preserves current endpoint fields and values. |
| No; body and guard rules apply | string | Regular local JSON body file, at most 5 MB. Cannot be mixed with body flags or payload. minLength: |
| No; body and guard rules apply | string | Regular local file path, no symlink, at most 3 MiB. Encoded as native base64 file_content; cannot mix with file_content or payload routes. minLength: |
A body is required. Native body flags, payload and payload_file are mutually exclusive. Required native body fields: Inspect endpoint requirements. Profile defaults fill supported user/team identity fields before body validation.
upload_files
gumloop-cli upload-files
Argument | Required | Type | Details |
| No; body and guard rules apply | array | See the full input schema. Items: object. |
| No; body and guard rules apply | string | The user ID associated with the files. Required if project_id is not provided. |
| No; body and guard rules apply | string | The project ID associated with the files. Required if user_id is not provided. |
| No; body and guard rules apply | string | Named private Gumloop account; selects private credentials and user/team identity. |
| No; body and guard rules apply | boolean | Set true only when the user asked for exactly this action. |
| No; body and guard rules apply | object | Complete JSON request body instead of body flags. Preserves current endpoint fields and values. |
| No; body and guard rules apply | string | Regular local JSON body file, at most 5 MB. Cannot be mixed with body flags or payload. minLength: |
A body is required. Native body flags, payload and payload_file are mutually exclusive. Required native body fields: Inspect endpoint requirements. Profile defaults fill supported user/team identity fields before body validation.
get_organization_audit_logs
gumloop-cli get-organization-audit-logs
Argument | Required | Type | Details |
| Yes | string | The ID of the organization to retrieve audit logs for. |
| No; body and guard rules apply | string | Your user id -- you must be an organization admin to retrieve organization logs. |
| Yes | string | Start timestamp for log filtering (ISO format). format: |
| Yes | string | End timestamp for log filtering (ISO format). format: |
| No; body and guard rules apply | string | Comma-separated list of event types to filter by (e.g. |
| No; body and guard rules apply | string | Comma-separated list of user IDs whose events should be returned. |
| No; body and guard rules apply | string | Comma-separated list of source IP addresses to filter by. The singular |
| No; body and guard rules apply | string | Comma-separated list of workspace (team) IDs to filter by. The singular |
| No; body and guard rules apply | string | Comma-separated list of entity IDs (agents, workbooks, files) to filter by. The singular |
| No; body and guard rules apply | integer | Page number for pagination. default: |
| No; body and guard rules apply | integer | Number of records per page. default: |
| No; body and guard rules apply | string | Named private Gumloop account; selects private credentials and user/team identity. |
manage_project_users
gumloop-cli manage-project-users
Argument | Required | Type | Details |
| No; body and guard rules apply | string | The ID of the organization that the workspace belongs to. |
| No; body and guard rules apply | string | Your user id -- you must be an organization admin to manage workspace users. |
| No; body and guard rules apply | string | The ID of the workspace to manage users for. |
| No; body and guard rules apply | string | The action to perform - either 'add' or 'remove' a user. Values: |
| No; body and guard rules apply | string | The email address of the target user to add or remove. |
| No; body and guard rules apply | boolean | When adding a user, specify whether they should have admin privileges (default is false). |
| No; body and guard rules apply | string | Named private Gumloop account; selects private credentials and user/team identity. |
| No; body and guard rules apply | boolean | Set true only when the user asked for exactly this action. |
| No; body and guard rules apply | object | Complete JSON request body instead of body flags. Preserves current endpoint fields and values. |
| No; body and guard rules apply | string | Regular local JSON body file, at most 5 MB. Cannot be mixed with body flags or payload. minLength: |
A body is required. Native body flags, payload and payload_file are mutually exclusive. Required native body fields: organization_id, user_id, workspace_id, action, user_email. Profile defaults fill supported user/team identity fields before body validation.
manage_permission_group_users
gumloop-cli manage-permission-group-users
Argument | Required | Type | Details |
| No; body and guard rules apply | string | The ID of the organization that the custom role belongs to. |
| No; body and guard rules apply | string | Your user id -- you must be an organization admin to manage custom role users. |
| No; body and guard rules apply | string | The ID of the custom role to manage users for. |
| No; body and guard rules apply | string | The action to perform - either 'add' or 'remove' a user. Values: |
| No; body and guard rules apply | string | The email address of the target user to add or remove. |
| No; body and guard rules apply | string | Named private Gumloop account; selects private credentials and user/team identity. |
| No; body and guard rules apply | boolean | Set true only when the user asked for exactly this action. |
| No; body and guard rules apply | object | Complete JSON request body instead of body flags. Preserves current endpoint fields and values. |
| No; body and guard rules apply | string | Regular local JSON body file, at most 5 MB. Cannot be mixed with body flags or payload. minLength: |
A body is required. Native body flags, payload and payload_file are mutually exclusive. Required native body fields: organization_id, user_id, group_id, action, user_email. Profile defaults fill supported user/team identity fields before body validation.
list_role_credit_limits
gumloop-cli list-role-credit-limits
Argument | Required | Type | Details |
| Yes | string | The ID of the organization. minLength: |
| No; body and guard rules apply | string | Your user id -- you must be an organization admin to manage custom role credit limits. |
| No; body and guard rules apply | integer | Number of roles per page. maximum: |
| No; body and guard rules apply | string | Opaque cursor from a previous response's |
| No; body and guard rules apply | string | Named private Gumloop account; selects private credentials and user/team identity. |
get_role_credit_limit
gumloop-cli get-role-credit-limit
Argument | Required | Type | Details |
| Yes | string | The ID of the organization the custom role belongs to. minLength: |
| Yes | string | The ID of the custom role (the same ID used as |
| No; body and guard rules apply | string | Your user id -- you must be an organization admin to manage custom role credit limits. |
| No; body and guard rules apply | string | Named private Gumloop account; selects private credentials and user/team identity. |
set_role_credit_limit
gumloop-cli set-role-credit-limit
Argument | Required | Type | Details |
| Yes | string | The ID of the organization the custom role belongs to. minLength: |
| Yes | string | The ID of the custom role (the same ID used as |
| No; body and guard rules apply | integer/null | The monthly credit limit applied to each member of this role, or null to clear the role-level limit. minimum: |
| No; body and guard rules apply | string | Your user id -- you must be an organization admin to manage custom role credit limits. |
| No; body and guard rules apply | string | Named private Gumloop account; selects private credentials and user/team identity. |
| No; body and guard rules apply | boolean | Set true only when the user asked for exactly this action. |
| No; body and guard rules apply | object | Complete JSON request body instead of body flags. Preserves current endpoint fields and values. |
| No; body and guard rules apply | string | Regular local JSON body file, at most 5 MB. Cannot be mixed with body flags or payload. minLength: |
A body is required. Native body flags, payload and payload_file are mutually exclusive. Required native body fields: monthly_credit_limit, user_id. Profile defaults fill supported user/team identity fields before body validation.
export_data
gumloop-cli export-data
Argument | Required | Type | Details |
| No; body and guard rules apply | string | The ID of the user requesting the export. |
| No; body and guard rules apply | string | The type of data to export. Use |
| No; body and guard rules apply | string | Only applicable when |
| No; body and guard rules apply | string | The scope of the export. Use |
| No; body and guard rules apply | array | Array of fields to include in the export. The available fields depend on the |
| No; body and guard rules apply | string | Start date for the export in ISO 8601 format (e.g., |
| No; body and guard rules apply | string | End date for the export in ISO 8601 format (e.g., |
| No; body and guard rules apply | boolean | Whether to include all workspaces in the organization. When |
| No; body and guard rules apply | boolean | Whether to include personal workspaces in the export. Ignored if |
| No; body and guard rules apply | array | An optional array of workspace IDs to include in the export. When |
| No; body and guard rules apply | array | An optional array of specific entity IDs to filter the export. For workflow exports ( |
| No; body and guard rules apply | string | Named private Gumloop account; selects private credentials and user/team identity. |
| No; body and guard rules apply | boolean | Set true only when the user asked for exactly this action. |
| No; body and guard rules apply | object | Complete JSON request body instead of body flags. Preserves current endpoint fields and values. |
| No; body and guard rules apply | string | Regular local JSON body file, at most 5 MB. Cannot be mixed with body flags or payload. minLength: |
A body is required. Native body flags, payload and payload_file are mutually exclusive. Required native body fields: user_id, export_fields, start_date, end_date. Profile defaults fill supported user/team identity fields before body validation.
get_export_status
gumloop-cli get-export-status
Argument | Required | Type | Details |
| No; body and guard rules apply | string | The ID of the user requesting the export status. |
| Yes | string | The unique identifier of the data export job to check (returned by the Export data endpoint). |
| No; body and guard rules apply | boolean | Set to |
| No; body and guard rules apply | string | Named private Gumloop account; selects private credentials and user/team identity. |
| Yes | string | New absolute result file in a private owner-only directory. Private download or signed credential result stays out of model output; no overwrite. minLength: |
output_file must be new and absolute in a private directory, reserved exclusively before the API call. Binary bytes or signed JSON are kept out of model output. This wrapper never follows a signed external download URL.
list_agents
gumloop-cli list-agents
Argument | Required | Type | Details |
| No; body and guard rules apply | string | Scope the listing to a single team. When omitted, returns agents owned by the authenticated user. |
| No; body and guard rules apply | string | Case-insensitive substring match against the agent name. |
| No; body and guard rules apply | string | Filter to agents created by this user ID. |
| No; body and guard rules apply | boolean | When |
| No; body and guard rules apply | string | Filter to agents that use the specified MCP server as a tool. |
| No; body and guard rules apply | string | Filter to agents that use the specified saved flow as a tool. |
| No; body and guard rules apply | string | Sort order for the listing. Defaults to newest first. Values: |
| No; body and guard rules apply | boolean | When |
| No; body and guard rules apply | boolean | When |
| No; body and guard rules apply | integer | Number of agents per page. Sending |
| No; body and guard rules apply | string | Opaque cursor from a previous response's |
| No; body and guard rules apply | string | Named private Gumloop account; selects private credentials and user/team identity. |
create_agent
gumloop-cli create-agent
Argument | Required | Type | Details |
| No; body and guard rules apply | string | Display name for the agent. |
| No; body and guard rules apply | string | ID of the LLM the agent runs on. Use |
| No; body and guard rules apply | string/null | See the full input schema. |
| No; body and guard rules apply | string/null | See the full input schema. |
| No; body and guard rules apply | array | Tools the agent can call. Each tool is an object whose shape depends on the tool type. default: |
| No; body and guard rules apply | array | Resources attached to the agent. default: |
| No; body and guard rules apply | array/null | IDs of skills to attach to the agent. Attachment happens inside the create transaction, so an invalid ID fails the whole request (no orphaned agent). Omit to attach none. The caller must hold |
| No; body and guard rules apply | object/null | Arbitrary key/value metadata stored on the agent. |
| No; body and guard rules apply | string/null | ID of the folder to place the agent in. |
| No; body and guard rules apply | boolean | Whether the agent is active. Defaults to |
| No; body and guard rules apply | string/null | Optional caller-supplied agent ID. When omitted, the server generates one. |
| No; body and guard rules apply | string/null | ID of the team to create the agent under. When omitted, the agent is owned by the authenticated user. |
| No; body and guard rules apply | string | Named private Gumloop account; selects private credentials and user/team identity. |
| No; body and guard rules apply | boolean | Set true only when the user asked for exactly this action. |
| No; body and guard rules apply | object | Complete JSON request body instead of body flags. Preserves current endpoint fields and values. |
| No; body and guard rules apply | string | Regular local JSON body file, at most 5 MB. Cannot be mixed with body flags or payload. minLength: |
A body is required. Native body flags, payload and payload_file are mutually exclusive. Required native body fields: name, model_name. Profile defaults fill supported user/team identity fields before body validation.
retrieve_agent
gumloop-cli retrieve-agent
Argument | Required | Type | Details |
| Yes | string | ID of the agent to retrieve. Also accepts the reserved aliases |
| No; body and guard rules apply | string | Named private Gumloop account; selects private credentials and user/team identity. |
update_agent
gumloop-cli update-agent
Argument | Required | Type | Details |
| Yes | string | ID of the agent to update. Also accepts the reserved aliases |
| No; body and guard rules apply | string/null | See the full input schema. |
| No; body and guard rules apply | string/null | ID of the LLM the agent runs on. Use |
| No; body and guard rules apply | string/null | See the full input schema. |
| No; body and guard rules apply | string/null | See the full input schema. |
| No; body and guard rules apply | array/null | When provided, replaces the agent's tool list. Items: object. |
| No; body and guard rules apply | array/null | When provided, replaces the agent's resource list. Items: object. |
| No; body and guard rules apply | object/null | See the full input schema. |
| No; body and guard rules apply | boolean/null | Setting this to |
| No; body and guard rules apply | string/null | When provided, transfers ownership of the agent to this team. |
| No; body and guard rules apply | string | Named private Gumloop account; selects private credentials and user/team identity. |
| No; body and guard rules apply | boolean | Set true only when the user asked for exactly this action. |
| No; body and guard rules apply | object | Complete JSON request body instead of body flags. Preserves current endpoint fields and values. |
| No; body and guard rules apply | string | Regular local JSON body file, at most 5 MB. Cannot be mixed with body flags or payload. minLength: |
A body is required. Native body flags, payload and payload_file are mutually exclusive. Required native body fields: Inspect endpoint requirements. Profile defaults fill supported user/team identity fields before body validation.
create_chat_completion
gumloop-cli create-chat-completion
Argument | Required | Type | Details |
| No; body and guard rules apply | string | Model slug. Use the |
| No; body and guard rules apply | array | Conversation history. Roles |
| No; body and guard rules apply | boolean | Only non-streaming JSON is supported. Streaming requests are refused before fetch. |
| No; body and guard rules apply | number | Sampling temperature. |
| No; body and guard rules apply | integer | Cap on completion tokens. Replaces the deprecated |
| No; body and guard rules apply | array | Output modalities. Include |
| No; body and guard rules apply | object | Image-generation parameters (size, quality, aspect_ratio, background, output_format, partial_images). Optional. Image-generation models accept either |
| No; body and guard rules apply | object | Constrain the response. |
| No; body and guard rules apply | array | OpenAI-shape tool definitions ( |
| No; body and guard rules apply | Union |
|
| No; body and guard rules apply | object | OpenRouter provider routing config. Caller fields like |
| No; body and guard rules apply | string | Named private Gumloop account; selects private credentials and user/team identity. |
| No; body and guard rules apply | boolean | Set true only when the user asked for exactly this action. |
| No; body and guard rules apply | object | Complete JSON request body instead of body flags. Preserves current endpoint fields and values. |
| No; body and guard rules apply | string | Regular local JSON body file, at most 5 MB. Cannot be mixed with body flags or payload. minLength: |
A body is required. Native body flags, payload and payload_file are mutually exclusive. Required native body fields: model, messages. Profile defaults fill supported user/team identity fields before body validation.
list_models
gumloop-cli list-models
Argument | Required | Type | Details |
| No; body and guard rules apply | string | Scope model availability to a specific team. When omitted, uses the authenticated user's default organization. |
| No; body and guard rules apply | string | Named private Gumloop account; selects private credentials and user/team identity. |
route_model
gumloop-cli route-model
Argument | Required | Type | Details |
| No; body and guard rules apply | Union | The message to route. |
| No; body and guard rules apply | array | Candidate model IDs to choose between. IDs must be nonempty, unique after remapping, and registered. Omit to use Chew's lane-chain union. minItems: |
| No; body and guard rules apply | array | Prior turns, oldest first, for context. maxItems: |
| No; body and guard rules apply | object | Optional context about the agent the message is for. Sharper context produces a sharper route. |
| No; body and guard rules apply | string | Scope model availability and credit attribution to a team the caller belongs to. |
| No; body and guard rules apply | string | Named private Gumloop account; selects private credentials and user/team identity. |
| No; body and guard rules apply | object | Complete JSON request body instead of body flags. Preserves current endpoint fields and values. |
| No; body and guard rules apply | string | Regular local JSON body file, at most 5 MB. Cannot be mixed with body flags or payload. minLength: |
A body is required. Native body flags, payload and payload_file are mutually exclusive. Required native body fields: input. Profile defaults fill supported user/team identity fields before body validation.
list_agent_versions
gumloop-cli list-agent-versions
Argument | Required | Type | Details |
| Yes | string | ID of the agent whose versions to list. Also accepts the reserved aliases |
| No; body and guard rules apply | integer | Number of versions to return per page. Clamped to 1–100. minimum: |
| No; body and guard rules apply | string | Opaque pagination cursor returned by a prior call as |
| No; body and guard rules apply | string | Named private Gumloop account; selects private credentials and user/team identity. |
retrieve_agent_version
gumloop-cli retrieve-agent-version
Argument | Required | Type | Details |
| Yes | string | ID of the agent the version belongs to. Also accepts the reserved aliases |
| Yes | string | ID of the version to retrieve, from |
| No; body and guard rules apply | string | Named private Gumloop account; selects private credentials and user/team identity. |
update_agent_skills
gumloop-cli update-agent-skills
Argument | Required | Type | Details |
| Yes | string | ID of the agent whose skills to update. Also accepts the reserved aliases |
| No; body and guard rules apply | array | Skill IDs to attach. Ignored if already attached. default: |
| No; body and guard rules apply | array | Skill IDs to detach. Ignored if not attached. default: |
| No; body and guard rules apply | string | Named private Gumloop account; selects private credentials and user/team identity. |
| No; body and guard rules apply | boolean | Set true only when the user asked for exactly this action. |
| No; body and guard rules apply | object | Complete JSON request body instead of body flags. Preserves current endpoint fields and values. |
| No; body and guard rules apply | string | Regular local JSON body file, at most 5 MB. Cannot be mixed with body flags or payload. minLength: |
A body is required. Native body flags, payload and payload_file are mutually exclusive. Required native body fields: Inspect endpoint requirements. Profile defaults fill supported user/team identity fields before body validation.
list_agent_mcp_servers
gumloop-cli list-agent-mcp-servers
Argument | Required | Type | Details |
| Yes | string | ID of the agent. Also accepts the reserved aliases |
| No; body and guard rules apply | string | Named private Gumloop account; selects private credentials and user/team identity. |
attach_agent_mcp_server
gumloop-cli attach-agent-mcp-server
Argument | Required | Type | Details |
| Yes | string | ID of the agent. Also accepts the reserved aliases |
| Yes | string | ID of the MCP server from the caller's catalog. minLength: |
| No; body and guard rules apply | string | Named private Gumloop account; selects private credentials and user/team identity. |
| No; body and guard rules apply | boolean | Set true only when the user asked for exactly this action. |
detach_agent_mcp_server
gumloop-cli detach-agent-mcp-server
Argument | Required | Type | Details |
| Yes | string | ID of the agent. Also accepts the reserved aliases |
| Yes | string | ID of the MCP server to detach. minLength: |
| No; body and guard rules apply | string | Named private Gumloop account; selects private credentials and user/team identity. |
| No; body and guard rules apply | boolean | Set true only when the user asked for exactly this action. |
list_sessions
gumloop-cli list-sessions
Argument | Required | Type | Details |
| Yes | string | ID of the agent whose sessions to list. Also accepts the reserved aliases |
| No; body and guard rules apply | integer | Number of sessions to return per page. Defaults to |
| No; body and guard rules apply | string | Cursor for the next page of results. Use the |
| No; body and guard rules apply | string | Free-text search query to filter sessions by name or content. Also accepted as |
| No; body and guard rules apply | string | Sort order for the results (e.g. |
| No; body and guard rules apply | string | Filter sessions by type (e.g. |
| No; body and guard rules apply | string | Filter sessions by state. Values: |
| No; body and guard rules apply | string | Filter sessions by the user who created them. |
| No; body and guard rules apply | string | Filter sessions by the trigger that initiated them. |
| No; body and guard rules apply | string | Named private Gumloop account; selects private credentials and user/team identity. |
create_session
gumloop-cli create-session
Argument | Required | Type | Details |
| Yes | string | ID of the agent to start a session on. Also accepts the reserved aliases |
| No; body and guard rules apply | string | The first user message for the session. Also accepted as |
| No; body and guard rules apply | string | Caller-supplied session ID. When omitted, the server generates one. If provided and the ID already exists, the request returns |
| No; body and guard rules apply | string | Optional display name for the session. Leading and trailing whitespace is removed before the 1-256 character limit is applied, so an empty or whitespace-only value is rejected. A name you supply is kept; the automatic title only fills in sessions created without one. Rename the session later with |
| No; body and guard rules apply | object | Arbitrary key/value metadata attached to the session. Stored under |
| No; body and guard rules apply | boolean | Must be |
| No; body and guard rules apply | string | Named private Gumloop account; selects private credentials and user/team identity. |
| No; body and guard rules apply | boolean | Set true only when the user asked for exactly this action. |
| No; body and guard rules apply | object | Complete JSON request body instead of body flags. Preserves current endpoint fields and values. |
| No; body and guard rules apply | string | Regular local JSON body file, at most 5 MB. Cannot be mixed with body flags or payload. minLength: |
retrieve_session
gumloop-cli retrieve-session
Argument | Required | Type | Details |
| Yes | string | ID of the session to retrieve. minLength: |
| No; body and guard rules apply | string | Named private Gumloop account; selects private credentials and user/team identity. |
rename_session
gumloop-cli rename-session
Argument | Required | Type | Details |
| Yes | string | ID of the session to rename. minLength: |
| No; body and guard rules apply | string | New name for the session. Leading and trailing whitespace is removed before the 1-256 character limit is applied, so a whitespace-only value is rejected. minLength: |
| No; body and guard rules apply | string | Named private Gumloop account; selects private credentials and user/team identity. |
| No; body and guard rules apply | boolean | Set true only when the user asked for exactly this action. |
| No; body and guard rules apply | object | Complete JSON request body instead of body flags. Preserves current endpoint fields and values. |
| No; body and guard rules apply | string | Regular local JSON body file, at most 5 MB. Cannot be mixed with body flags or payload. minLength: |
A body is required. Native body flags, payload and payload_file are mutually exclusive. Required native body fields: name. Profile defaults fill supported user/team identity fields before body validation.
send_message
gumloop-cli send-message
Argument | Required | Type | Details |
| Yes | string | ID of the session to continue. minLength: |
| No; body and guard rules apply | string | The next user message. Required. Also accepted as |
| No; body and guard rules apply | boolean | Must be |
| No; body and guard rules apply | array | Files to attach to the message. Each |
| No; body and guard rules apply | string | Named private Gumloop account; selects private credentials and user/team identity. |
| No; body and guard rules apply | boolean | Set true only when the user asked for exactly this action. |
| No; body and guard rules apply | object | Complete JSON request body instead of body flags. Preserves current endpoint fields and values. |
| No; body and guard rules apply | string | Regular local JSON body file, at most 5 MB. Cannot be mixed with body flags or payload. minLength: |
A body is required. Native body flags, payload and payload_file are mutually exclusive. Required native body fields: input. Profile defaults fill supported user/team identity fields before body validation.
cancel_session
gumloop-cli cancel-session
Argument | Required | Type | Details |
| Yes | string | ID of the session to cancel. minLength: |
| No; body and guard rules apply | string | Named private Gumloop account; selects private credentials and user/team identity. |
| No; body and guard rules apply | boolean | Set true only when the user asked for exactly this action. |
upload_session_file
gumloop-cli upload-session-file
Argument | Required | Type | Details |
| Yes | string | ID of the session to upload the file to. minLength: |
| No; body and guard rules apply | string | Name of the file. Directory components are stripped; the base name is sanitized before storage. |
| No; body and guard rules apply | string | Base64-encoded file contents. Maximum decoded size is 200MB. format: |
| No; body and guard rules apply | string | MIME type of the file. Echoed back in the response. |
| No; body and guard rules apply | string | Named private Gumloop account; selects private credentials and user/team identity. |
| No; body and guard rules apply | boolean | Set true only when the user asked for exactly this action. |
| No; body and guard rules apply | object | Complete JSON request body instead of body flags. Preserves current endpoint fields and values. |
| No; body and guard rules apply | string | Regular local JSON body file, at most 5 MB. Cannot be mixed with body flags or payload. minLength: |
A body is required. Native body flags, payload and payload_file are mutually exclusive. Required native body fields: file_name, file_content. Profile defaults fill supported user/team identity fields before body validation.
resolve_session_approvals
gumloop-cli resolve-session-approvals
Argument | Required | Type | Details |
| Yes | string | ID of the session with pending approvals. minLength: |
| No; body and guard rules apply | array | Answers to pending asks. Each |
| No; body and guard rules apply | string | Named private Gumloop account; selects private credentials and user/team identity. |
| No; body and guard rules apply | boolean | Set true only when the user asked for exactly this action. |
| No; body and guard rules apply | object | Complete JSON request body instead of body flags. Preserves current endpoint fields and values. |
| No; body and guard rules apply | string | Regular local JSON body file, at most 5 MB. Cannot be mixed with body flags or payload. minLength: |
A body is required. Native body flags, payload and payload_file are mutually exclusive. Required native body fields: approval_responses. Profile defaults fill supported user/team identity fields before body validation.
list_queued_messages
gumloop-cli list-queued-messages
Argument | Required | Type | Details |
| Yes | string | ID of the session whose queue to list. minLength: |
| No; body and guard rules apply | string | Named private Gumloop account; selects private credentials and user/team identity. |
queue_session_message
gumloop-cli queue-session-message
Argument | Required | Type | Details |
| Yes | string | ID of the session to queue the message on. minLength: |
| No; body and guard rules apply | string | The message to queue. Cannot be empty. Also accepted as |
| No; body and guard rules apply | string | Named private Gumloop account; selects private credentials and user/team identity. |
| No; body and guard rules apply | boolean | Set true only when the user asked for exactly this action. |
| No; body and guard rules apply | object | Complete JSON request body instead of body flags. Preserves current endpoint fields and values. |
| No; body and guard rules apply | string | Regular local JSON body file, at most 5 MB. Cannot be mixed with body flags or payload. minLength: |
A body is required. Native body flags, payload and payload_file are mutually exclusive. Required native body fields: input. Profile defaults fill supported user/team identity fields before body validation.
update_queued_message
gumloop-cli update-queued-message
Argument | Required | Type | Details |
| Yes | string | ID of the session the queued message belongs to. minLength: |
| Yes | string | ID of the queued message to update. minLength: |
| No; body and guard rules apply | string | The new message content. Cannot be empty. Also accepted as |
| No; body and guard rules apply | string | Named private Gumloop account; selects private credentials and user/team identity. |
| No; body and guard rules apply | boolean | Set true only when the user asked for exactly this action. |
| No; body and guard rules apply | object | Complete JSON request body instead of body flags. Preserves current endpoint fields and values. |
| No; body and guard rules apply | string | Regular local JSON body file, at most 5 MB. Cannot be mixed with body flags or payload. minLength: |
A body is required. Native body flags, payload and payload_file are mutually exclusive. Required native body fields: input. Profile defaults fill supported user/team identity fields before body validation.
delete_queued_message
gumloop-cli delete-queued-message
Argument | Required | Type | Details |
| Yes | string | ID of the session the queued message belongs to. minLength: |
| Yes | string | ID of the queued message to delete. minLength: |
| No; body and guard rules apply | string | Named private Gumloop account; selects private credentials and user/team identity. |
| No; body and guard rules apply | boolean | Set true only when the user asked for exactly this action. |
send_queued_message
gumloop-cli send-queued-message
Argument | Required | Type | Details |
| Yes | string | ID of the session the queued message belongs to. minLength: |
| Yes | string | ID of the queued message to send. minLength: |
| No; body and guard rules apply | string | Named private Gumloop account; selects private credentials and user/team identity. |
| No; body and guard rules apply | boolean | Set true only when the user asked for exactly this action. |
list_mcp_servers
gumloop-cli list-mcp-servers
Argument | Required | Type | Details |
| No; body and guard rules apply | string | Scope the catalog to a single team. When omitted, returns servers visible to the authenticated user. |
| No; body and guard rules apply | string | Named private Gumloop account; selects private credentials and user/team identity. |
retrieve_mcp_server
gumloop-cli retrieve-mcp-server
Argument | Required | Type | Details |
| Yes | string | Identifier of the MCP server to retrieve. minLength: |
| No; body and guard rules apply | string | Scope the lookup to a single team. |
| No; body and guard rules apply | string | Named private Gumloop account; selects private credentials and user/team identity. |
list_mcp_server_tools
gumloop-cli list-mcp-server-tools
Argument | Required | Type | Details |
| Yes | string | Identifier of the MCP server. minLength: |
| No; body and guard rules apply | string | Scope the lookup to a single team. |
| No; body and guard rules apply | string | Named private Gumloop account; selects private credentials and user/team identity. |
list_mcp_server_resources
gumloop-cli list-mcp-server-resources
Argument | Required | Type | Details |
| Yes | string | Identifier of the MCP server. minLength: |
| No; body and guard rules apply | string | Scope the lookup to a single team. |
| No; body and guard rules apply | string | Opaque cursor from a previous response's |
| No; body and guard rules apply | string | Named private Gumloop account; selects private credentials and user/team identity. |
read_mcp_server_resource
gumloop-cli read-mcp-server-resource
Argument | Required | Type | Details |
| Yes | string | See current schema minLength: |
| Yes | string | The resource |
| No; body and guard rules apply | string | See current schema |
| No; body and guard rules apply | string | Named private Gumloop account; selects private credentials and user/team identity. |
list_mcp_server_prompts
gumloop-cli list-mcp-server-prompts
Argument | Required | Type | Details |
| Yes | string | See current schema minLength: |
| No; body and guard rules apply | string | See current schema |
| No; body and guard rules apply | string | Named private Gumloop account; selects private credentials and user/team identity. |
get_mcp_server_prompt
gumloop-cli get-mcp-server-prompt
Argument | Required | Type | Details |
| Yes | string | See current schema minLength: |
| No; body and guard rules apply | string | Prompt name from List MCP server prompts. |
| No; body and guard rules apply | object | Argument values for the template. |
| No; body and guard rules apply | string | Scope the lookup to a single team. |
| No; body and guard rules apply | string | Named private Gumloop account; selects private credentials and user/team identity. |
| No; body and guard rules apply | object | Complete JSON request body instead of body flags. Preserves current endpoint fields and values. |
| No; body and guard rules apply | string | Regular local JSON body file, at most 5 MB. Cannot be mixed with body flags or payload. minLength: |
A body is required. Native body flags, payload and payload_file are mutually exclusive. Required native body fields: name. Profile defaults fill supported user/team identity fields before body validation.
call_mcp_tools
gumloop-cli call-mcp-tools
Argument | Required | Type | Details |
| No; body and guard rules apply | array | Tool calls to execute. Dispatched concurrently; the batch is capped at 5. minItems: |
| No; body and guard rules apply | string/null | Team the calls are scoped to. |
| No; body and guard rules apply | string | Named private Gumloop account; selects private credentials and user/team identity. |
| No; body and guard rules apply | boolean | Set true only when the user asked for exactly this action. |
| No; body and guard rules apply | object | Complete JSON request body instead of body flags. Preserves current endpoint fields and values. |
| No; body and guard rules apply | string | Regular local JSON body file, at most 5 MB. Cannot be mixed with body flags or payload. minLength: |
A body is required. Native body flags, payload and payload_file are mutually exclusive. Required native body fields: calls. Profile defaults fill supported user/team identity fields before body validation.
search_brain
gumloop-cli search-brain
Argument | Required | Type | Details |
| No; body and guard rules apply | string | The natural-language search query. |
| No; body and guard rules apply | integer | Maximum number of results to return. minimum: |
| No; body and guard rules apply | array/null | Restrict results to specific source types. Omit to search every source you can access. Valid values: |
| No; body and guard rules apply | string | Named private Gumloop account; selects private credentials and user/team identity. |
| No; body and guard rules apply | boolean | Set true only when the user asked for exactly this action. |
| No; body and guard rules apply | object | Complete JSON request body instead of body flags. Preserves current endpoint fields and values. |
| No; body and guard rules apply | string | Regular local JSON body file, at most 5 MB. Cannot be mixed with body flags or payload. minLength: |
A body is required. Native body flags, payload and payload_file are mutually exclusive. Required native body fields: query. Profile defaults fill supported user/team identity fields before body validation.
list_brain_sources
gumloop-cli list-brain-sources
Argument | Required | Type | Details |
| No; body and guard rules apply | string | Only sources in this scope. Values: |
| No; body and guard rules apply | string | Only sources of this type, for example |
| No; body and guard rules apply | string | Only team sources belonging to this team. |
| No; body and guard rules apply | integer | Maximum number of sources to return. minimum: |
| No; body and guard rules apply | string | Opaque cursor from a previous response's |
| No; body and guard rules apply | string | Named private Gumloop account; selects private credentials and user/team identity. |
create_brain_source
gumloop-cli create-brain-source
Argument | Required | Type | Details |
| No; body and guard rules apply | string | Display name of the source. minLength: |
| No; body and guard rules apply | string | Only |
| No; body and guard rules apply | string | Which Brain the source belongs to. |
| No; body and guard rules apply | string | The team for |
| No; body and guard rules apply | boolean | Create as a draft that estimates credits before anything is indexed. default: |
| No; body and guard rules apply | string | Named private Gumloop account; selects private credentials and user/team identity. |
| No; body and guard rules apply | boolean | Set true only when the user asked for exactly this action. |
| No; body and guard rules apply | object | Complete JSON request body instead of body flags. Preserves current endpoint fields and values. |
| No; body and guard rules apply | string | Regular local JSON body file, at most 5 MB. Cannot be mixed with body flags or payload. minLength: |
A body is required. Native body flags, payload and payload_file are mutually exclusive. Required native body fields: name. Profile defaults fill supported user/team identity fields before body validation.
get_brain_source
gumloop-cli get-brain-source
Argument | Required | Type | Details |
| Yes | string | The source id. minLength: |
| No; body and guard rules apply | string | Named private Gumloop account; selects private credentials and user/team identity. |
delete_brain_source
gumloop-cli delete-brain-source
Argument | Required | Type | Details |
| Yes | string | The source id. minLength: |
| No; body and guard rules apply | string | Named private Gumloop account; selects private credentials and user/team identity. |
| No; body and guard rules apply | boolean | Set true only when the user asked for exactly this action. |
list_brain_files
gumloop-cli list-brain-files
Argument | Required | Type | Details |
| Yes | string | The source id. minLength: |
| No; body and guard rules apply | integer | See current schema minimum: |
| No; body and guard rules apply | string | See current schema |
| No; body and guard rules apply | string | Named private Gumloop account; selects private credentials and user/team identity. |
upload_brain_files
gumloop-cli upload-brain-files
Argument | Required | Type | Details |
| Yes | string | The source id. minLength: |
| No; body and guard rules apply | array | Regular local file paths, not base64; each file and total upload at most 5 MiB. Paths cannot be symlinks. minItems: |
| No; body and guard rules apply | string | Named private Gumloop account; selects private credentials and user/team identity. |
| No; body and guard rules apply | boolean | Set true only when the user asked for exactly this action. |
| No; body and guard rules apply | object | Complete JSON request body instead of body flags. Preserves current endpoint fields and values. |
| No; body and guard rules apply | string | Regular local JSON body file, at most 5 MB. Cannot be mixed with body flags or payload. minLength: |
A body is required. Native body flags, payload and payload_file are mutually exclusive. Required native body fields: files. Profile defaults fill supported user/team identity fields before body validation.
files contains regular local paths. The handler reads actual bytes and sends native multipart file parts after confirmation; 5 MiB per file/total local cap, no symlinks.
delete_brain_file
gumloop-cli delete-brain-file
Argument | Required | Type | Details |
| Yes | string | The source id. minLength: |
| Yes | string | See current schema minLength: |
| No; body and guard rules apply | string | Named private Gumloop account; selects private credentials and user/team identity. |
| No; body and guard rules apply | boolean | Set true only when the user asked for exactly this action. |
get_brain_source_estimate
gumloop-cli get-brain-source-estimate
Argument | Required | Type | Details |
| Yes | string | The source id. minLength: |
| No; body and guard rules apply | string | Named private Gumloop account; selects private credentials and user/team identity. |
approve_brain_source
gumloop-cli approve-brain-source
Argument | Required | Type | Details |
| Yes | string | The source id. minLength: |
| No; body and guard rules apply | string | Named private Gumloop account; selects private credentials and user/team identity. |
| No; body and guard rules apply | boolean | Set true only when the user asked for exactly this action. |
list_skills
gumloop-cli list-skills
Argument | Required | Type | Details |
| No; body and guard rules apply | string | Scope the listing to a single team. When omitted, returns skills owned by the authenticated user. |
| No; body and guard rules apply | string | Case-insensitive substring match against the skill name. |
| No; body and guard rules apply | string | Sort order for the returned skills. Values: |
| No; body and guard rules apply | integer | Number of skills per page. Clamped between 1 and 100. minimum: |
| No; body and guard rules apply | string | Opaque pagination cursor returned in |
| No; body and guard rules apply | string | Filter to skills created by this user ID. |
| No; body and guard rules apply | string | Filter to skills that reference this MCP server ID in their metadata. |
| No; body and guard rules apply | string | Filter to skills attached to this agent. |
| No; body and guard rules apply | string | When set, filters to skills that have not been used. |
| No; body and guard rules apply | string | Named private Gumloop account; selects private credentials and user/team identity. |
create_skill
gumloop-cli create-skill
Argument | Required | Type | Details |
| No; body and guard rules apply | array | Regular local file paths, not base64; each file and total upload at most 5 MiB. Paths cannot be symlinks. minItems: |
| No; body and guard rules apply | string | Team that should own the skill. When omitted, the skill is owned by the authenticated user. |
| No; body and guard rules apply | string | Named private Gumloop account; selects private credentials and user/team identity. |
| No; body and guard rules apply | boolean | Set true only when the user asked for exactly this action. |
| No; body and guard rules apply | object | Complete JSON request body instead of body flags. Preserves current endpoint fields and values. |
| No; body and guard rules apply | string | Regular local JSON body file, at most 5 MB. Cannot be mixed with body flags or payload. minLength: |
A body is required. Native body flags, payload and payload_file are mutually exclusive. Required native body fields: files. Profile defaults fill supported user/team identity fields before body validation.
files contains regular local paths. The handler reads actual bytes and sends native multipart file parts after confirmation; 5 MiB per file/total local cap, no symlinks.
update_skill
gumloop-cli update-skill
Argument | Required | Type | Details |
| Yes | string | ID of the skill to update. minLength: |
| No; body and guard rules apply | array | Regular local file paths, not base64; each file and total upload at most 5 MiB. Paths cannot be symlinks. minItems: |
| No; body and guard rules apply | string | Named private Gumloop account; selects private credentials and user/team identity. |
| No; body and guard rules apply | boolean | Set true only when the user asked for exactly this action. |
| No; body and guard rules apply | object | Complete JSON request body instead of body flags. Preserves current endpoint fields and values. |
| No; body and guard rules apply | string | Regular local JSON body file, at most 5 MB. Cannot be mixed with body flags or payload. minLength: |
A body is required. Native body flags, payload and payload_file are mutually exclusive. Required native body fields: files. Profile defaults fill supported user/team identity fields before body validation.
files contains regular local paths. The handler reads actual bytes and sends native multipart file parts after confirmation; 5 MiB per file/total local cap, no symlinks.
delete_skill
gumloop-cli delete-skill
Argument | Required | Type | Details |
| Yes | string | ID of the skill to delete. minLength: |
| No; body and guard rules apply | string | Named private Gumloop account; selects private credentials and user/team identity. |
| No; body and guard rules apply | boolean | Set true only when the user asked for exactly this action. |
download_skill_file
gumloop-cli download-skill-file
Argument | Required | Type | Details |
| Yes | string | ID of the skill to download. minLength: |
| No; body and guard rules apply | string | Specific version to download. When omitted, the current draft is returned. |
| No; body and guard rules apply | string | Named private Gumloop account; selects private credentials and user/team identity. |
| Yes | string | New absolute result file in a private owner-only directory. Private download or signed credential result stays out of model output; no overwrite. minLength: |
output_file must be new and absolute in a private directory, reserved exclusively before the API call. Binary bytes or signed JSON are kept out of model output. This wrapper never follows a signed external download URL.
list_artifacts
gumloop-cli list-artifacts
Argument | Required | Type | Details |
| Yes | string | ID of the agent whose artifacts to list. Also accepts the reserved aliases |
| No; body and guard rules apply | string | Filter to artifacts produced within a specific session. |
| No; body and guard rules apply | string | Case-insensitive substring match against the artifact filename. |
| No; body and guard rules apply | string | Sort order for results. Defaults to |
| No; body and guard rules apply | integer | Number of artifacts to return per page. Clamped to 1–100. minimum: |
| No; body and guard rules apply | string | Opaque pagination cursor returned by a prior call as |
| No; body and guard rules apply | string | Named private Gumloop account; selects private credentials and user/team identity. |
download_artifact_file
gumloop-cli download-artifact-file
Argument | Required | Type | Details |
| Yes | string | ID of the artifact to download. minLength: |
| No; body and guard rules apply | string | Specific version of the artifact to download. Defaults to the latest version when omitted. |
| No; body and guard rules apply | string | Named private Gumloop account; selects private credentials and user/team identity. |
| Yes | string | New absolute result file in a private owner-only directory. Private download or signed credential result stays out of model output; no overwrite. minLength: |
output_file must be new and absolute in a private directory, reserved exclusively before the API call. Binary bytes or signed JSON are kept out of model output. This wrapper never follows a signed external download URL.
list_browser_profiles
gumloop-cli list-browser-profiles
Argument | Required | Type | Details |
| No; body and guard rules apply | string | List a team's profiles instead of your personal ones. |
| No; body and guard rules apply | string | Named private Gumloop account; selects private credentials and user/team identity. |
import_browser_profile_cookies
gumloop-cli import-browser-profile-cookies
Argument | Required | Type | Details |
| Yes | string | A profile id, or |
| No; body and guard rules apply | string | Import only the cookies for this site and replace what the profile had for it. Omit to import every site in |
| No; body and guard rules apply | array | Cookies in |
| No; body and guard rules apply | string | Import into a team-owned profile instead of a personal one. |
| No; body and guard rules apply | string | Named private Gumloop account; selects private credentials and user/team identity. |
| No; body and guard rules apply | boolean | Set true only when the user asked for exactly this action. |
| No; body and guard rules apply | object | Complete JSON request body instead of body flags. Preserves current endpoint fields and values. |
| No; body and guard rules apply | string | Regular local JSON body file, at most 5 MB. Cannot be mixed with body flags or payload. minLength: |
A body is required. Native body flags, payload and payload_file are mutually exclusive. Required native body fields: cookies. Profile defaults fill supported user/team identity fields before body validation.
list_teams
gumloop-cli list-teams
Argument | Required | Type | Details |
| No; body and guard rules apply | string | Named private Gumloop account; selects private credentials and user/team identity. |
list_evaluations
gumloop-cli list-evaluations
Argument | Required | Type | Details |
| Yes | string | ID of the agent whose evaluations to list. Also accepts the reserved aliases |
| No; body and guard rules apply | integer | Number of evaluations to return per page (1-100). minimum: |
| No; body and guard rules apply | string | Pagination cursor from a previous response's |
| No; body and guard rules apply | string | Filter evaluations by grade. Values: |
| No; body and guard rules apply | string | Return evaluations in one lifecycle state instead of the default completed and failed set. Values: |
| No; body and guard rules apply | string | Only evaluations of this session. |
| No; body and guard rules apply | string | Return the results one organization evaluation produced for this agent instead of the agent's own evaluation results. |
| No; body and guard rules apply | string | Only evaluations created at or after this ISO 8601 timestamp. Timestamps without an offset are read as UTC. format: |
| No; body and guard rules apply | string | Only evaluations created before this ISO 8601 timestamp. Timestamps without an offset are read as UTC. format: |
| No; body and guard rules apply | string | Named private Gumloop account; selects private credentials and user/team identity. |
run_evaluations
gumloop-cli run-evaluations
Argument | Required | Type | Details |
| Yes | string | ID of the agent that owns the sessions. minLength: |
| No; body and guard rules apply | array | Sessions to grade. Duplicates are rejected. minItems: |
| No; body and guard rules apply | boolean | Report cost and skipped sessions without queuing. default: |
| No; body and guard rules apply | string | Named private Gumloop account; selects private credentials and user/team identity. |
| No; body and guard rules apply | boolean | Set true only when the user asked for exactly this action. |
| No; body and guard rules apply | object | Complete JSON request body instead of body flags. Preserves current endpoint fields and values. |
| No; body and guard rules apply | string | Regular local JSON body file, at most 5 MB. Cannot be mixed with body flags or payload. minLength: |
A body is required. Native body flags, payload and payload_file are mutually exclusive. Required native body fields: session_ids. Profile defaults fill supported user/team identity fields before body validation.
get_evaluation_metrics
gumloop-cli get-evaluation-metrics
Argument | Required | Type | Details |
| Yes | string | ID of the agent. Also accepts the reserved aliases |
| No; body and guard rules apply | integer | Number of days to look back (1-365). Defaults to 30. minimum: |
| No; body and guard rules apply | string | Named private Gumloop account; selects private credentials and user/team identity. |
retrieve_evaluation
gumloop-cli retrieve-evaluation
Argument | Required | Type | Details |
| Yes | string | ID of the agent the evaluation belongs to. Also accepts the reserved aliases |
| Yes | string | ID of the evaluation to retrieve. minLength: |
| No; body and guard rules apply | string | Named private Gumloop account; selects private credentials and user/team identity. |
get_evaluation_config
gumloop-cli get-evaluation-config
Argument | Required | Type | Details |
| Yes | string | ID of the agent. Also accepts the reserved aliases |
| No; body and guard rules apply | string | Named private Gumloop account; selects private credentials and user/team identity. |
update_evaluation_config
gumloop-cli update-evaluation-config
Argument | Required | Type | Details |
| Yes | string | ID of the agent. Also accepts the reserved aliases |
| No; body and guard rules apply | boolean | Whether evaluations are enabled for this agent. |
| No; body and guard rules apply | string | LLM model to use for evaluation. |
| No; body and guard rules apply | boolean | Allow the evaluator to suggest tags beyond your predefined vocabulary. |
| No; body and guard rules apply | array | Quality criteria to check (replaces existing list). Max 30. Items: object. |
| No; body and guard rules apply | array | Tag vocabulary (replaces existing list). Max 50. Items: object. |
| No; body and guard rules apply | array | Data points to extract (replaces existing list). Max 40. Items: object. |
| No; body and guard rules apply | object | See the full input schema. |
| No; body and guard rules apply | string | Named private Gumloop account; selects private credentials and user/team identity. |
| No; body and guard rules apply | boolean | Set true only when the user asked for exactly this action. |
| No; body and guard rules apply | object | Complete JSON request body instead of body flags. Preserves current endpoint fields and values. |
| No; body and guard rules apply | string | Regular local JSON body file, at most 5 MB. Cannot be mixed with body flags or payload. minLength: |
A body is required. Native body flags, payload and payload_file are mutually exclusive. Required native body fields: Inspect endpoint requirements. Profile defaults fill supported user/team identity fields before body validation.
list_organizations
gumloop-cli list-organizations
Argument | Required | Type | Details |
| No; body and guard rules apply | string | Named private Gumloop account; selects private credentials and user/team identity. |
get_evaluation_options
gumloop-cli get-evaluation-options
Argument | Required | Type | Details |
| No; body and guard rules apply | string | Named private Gumloop account; selects private credentials and user/team identity. |
list_organization_evaluations
gumloop-cli list-organization-evaluations
Argument | Required | Type | Details |
| Yes | string | The organization whose evaluations to list. |
| No; body and guard rules apply | integer | Items per page (1-100). minimum: |
| No; body and guard rules apply | string | Pagination cursor from a previous response's |
| No; body and guard rules apply | string | Named private Gumloop account; selects private credentials and user/team identity. |
create_organization_evaluation
gumloop-cli create-organization-evaluation
Argument | Required | Type | Details |
| No; body and guard rules apply | string | Named private Gumloop account; selects private credentials and user/team identity. |
| No; body and guard rules apply | boolean | Set true only when the user asked for exactly this action. |
A body is required. Native body flags, payload and payload_file are mutually exclusive. Required native body fields: Inspect endpoint requirements. Profile defaults fill supported user/team identity fields before body validation.
get_organization_evaluation
gumloop-cli get-organization-evaluation
Argument | Required | Type | Details |
| Yes | string | ID of the organization evaluation. minLength: |
| No; body and guard rules apply | string | Named private Gumloop account; selects private credentials and user/team identity. |
update_organization_evaluation
gumloop-cli update-organization-evaluation
Argument | Required | Type | Details |
| Yes | string | ID of the organization evaluation. minLength: |
| No; body and guard rules apply | string | Named private Gumloop account; selects private credentials and user/team identity. |
| No; body and guard rules apply | boolean | Set true only when the user asked for exactly this action. |
A body is required. Native body flags, payload and payload_file are mutually exclusive. Required native body fields: Inspect endpoint requirements. Profile defaults fill supported user/team identity fields before body validation.
delete_organization_evaluation
gumloop-cli delete-organization-evaluation
Argument | Required | Type | Details |
| Yes | string | ID of the organization evaluation. minLength: |
| No; body and guard rules apply | string | Named private Gumloop account; selects private credentials and user/team identity. |
| No; body and guard rules apply | boolean | Set true only when the user asked for exactly this action. |
set_organization_evaluation_targets
gumloop-cli set-organization-evaluation-targets
Argument | Required | Type | Details |
| Yes | string | ID of the organization evaluation. minLength: |
| No; body and guard rules apply | array | See the full input schema. maxItems: |
| No; body and guard rules apply | string | Named private Gumloop account; selects private credentials and user/team identity. |
| No; body and guard rules apply | boolean | Set true only when the user asked for exactly this action. |
| No; body and guard rules apply | object | Complete JSON request body instead of body flags. Preserves current endpoint fields and values. |
| No; body and guard rules apply | string | Regular local JSON body file, at most 5 MB. Cannot be mixed with body flags or payload. minLength: |
A body is required. Native body flags, payload and payload_file are mutually exclusive. Required native body fields: targets. Profile defaults fill supported user/team identity fields before body validation.
run_organization_evaluation
gumloop-cli run-organization-evaluation
Argument | Required | Type | Details |
| Yes | string | ID of the organization evaluation. minLength: |
| No; body and guard rules apply | array | Sessions to grade. Duplicates are rejected. minItems: |
| No; body and guard rules apply | boolean | Report cost and skipped sessions without queuing. default: |
| No; body and guard rules apply | string | Named private Gumloop account; selects private credentials and user/team identity. |
| No; body and guard rules apply | boolean | Set true only when the user asked for exactly this action. |
| No; body and guard rules apply | object | Complete JSON request body instead of body flags. Preserves current endpoint fields and values. |
| No; body and guard rules apply | string | Regular local JSON body file, at most 5 MB. Cannot be mixed with body flags or payload. minLength: |
A body is required. Native body flags, payload and payload_file are mutually exclusive. Required native body fields: session_ids. Profile defaults fill supported user/team identity fields before body validation.
list_organization_evaluation_results
gumloop-cli list-organization-evaluation-results
Argument | Required | Type | Details |
| Yes | string | ID of the organization evaluation. minLength: |
| No; body and guard rules apply | string | Only results for this agent. |
| No; body and guard rules apply | string | Only results for this session. |
| No; body and guard rules apply | string | Filter by grade. Values: |
| No; body and guard rules apply | string | Filter by status. Values: |
| No; body and guard rules apply | string | Only results created at or after this time. RFC 3339 with an explicit offset (for example |
| No; body and guard rules apply | string | Only results created before this time. RFC 3339 with an explicit offset. format: |
| No; body and guard rules apply | integer | Items per page (1-100). minimum: |
| No; body and guard rules apply | string | Pagination cursor from a previous response's |
| No; body and guard rules apply | string | Named private Gumloop account; selects private credentials and user/team identity. |
get_organization_evaluation_result
gumloop-cli get-organization-evaluation-result
Argument | Required | Type | Details |
| Yes | string | ID of the organization evaluation. minLength: |
| Yes | string | Result ID from a run response or a results list. minLength: |
| No; body and guard rules apply | string | Named private Gumloop account; selects private credentials and user/team identity. |
get_organization_evaluation_metrics
gumloop-cli get-organization-evaluation-metrics
Argument | Required | Type | Details |
| Yes | string | ID of the organization evaluation. minLength: |
| No; body and guard rules apply | integer | Window length in days. minimum: |
| No; body and guard rules apply | string | Named private Gumloop account; selects private credentials and user/team identity. |
list_accounts
gumloop-cli list-accounts
Argument | Required | Type | Details |
None | No | None | No arguments |
Nested request definitions
These definitions are shared by the current native bodies. Required fields depend on the selected union branch. Full inline shapes remain in schema COMMAND.
EvaluationRubric
What and how the evaluation grades. Entries in criteria, tags, and data_points accept additional fields as the product evolves.
Argument | Required | Type | Details |
| No; body and guard rules apply | string | Grading model. |
| No; body and guard rules apply | string | When to grade new sessions automatically. |
| No; body and guard rules apply | string | Language for summaries and rationales, or |
| No; body and guard rules apply | boolean | See the full input schema. |
| No; body and guard rules apply | array | Session types to grade. See |
| No; body and guard rules apply | array | See the full input schema. maxItems: |
| No; body and guard rules apply | array | See the full input schema. maxItems: |
| No; body and guard rules apply | array | See the full input schema. maxItems: |
| No; body and guard rules apply | object | See the full input schema. |
| No; body and guard rules apply | object | See the full input schema. |
EvaluationCreateRequest
Current request definition.
Argument | Required | Type | Details |
| No; body and guard rules apply | string | See the full input schema. Values: |
| Yes | string | See the full input schema. |
| Yes | string | Unique among the organization's active evaluations. minLength: |
| No; body and guard rules apply | string/null | See the full input schema. maxLength: |
| No; body and guard rules apply | boolean | Must be omitted or false on create; a new evaluation has no targets yet. |
| No; body and guard rules apply | EvaluationRubric | See the full input schema. |
EvaluationUpdateRequest
Current request definition.
Argument | Required | Type | Details |
| No; body and guard rules apply | string | See the full input schema. minLength: |
| No; body and guard rules apply | string/null | Null clears the description. maxLength: |
| No; body and guard rules apply | boolean | See the full input schema. |
| No; body and guard rules apply | EvaluationRubric | See the full input schema. |
EvaluationTarget
Current request definition.
Argument | Required | Type | Details |
| Yes | string | What the target expands to. |
| No; body and guard rules apply | string | Team, user, or agent ID. Omitted for |
9. Flows, sessions and account workflows
Review and run a flow
List flows/workbooks, select one exact saved_item_id and inspect get_input_schema. Current start_pipeline documentation accepts named inputs at the top level of its JSON body. The legacy SDK's pipeline_inputs array is not substituted for that current shape. Use one reviewed private JSON file:
gumloop-cli list-flows --account work --agent
gumloop-cli get-input-schema --saved-item-id SELECTED_FLOW --account work --agent
gumloop-cli start-flow --payload-file /absolute/private/approved-flow.json --account work --confirm --agent
gumloop-cli get-run-details --run-id RETURNED_RUN_ID --account work --agentThe body includes saved_item_id and exact named flow inputs; user_id can come from the private profile. A webhook input receives the entire body, including metadata. Do not include wrapper account/confirm fields in the provider payload. Only output steps appear as final flow outputs. Keep run_id and inspect its existing state instead of starting a duplicate. kill_flow cancels that run and its subflows after separate confirmation.
Agent sessions and approvals
Use list_agents/retrieve_agent/list_agent_versions before selecting an agent. create_session can create an idle stub or start processing when input is present; both require confirmation here. retain agent_id/session_id. retrieve_session reads messages/state. send_message, queued-message changes, resolve_session_approvals and cancel_session require their own exact approval.
A processing/queued session may reject ordinary send_message with 409; the queue endpoint is the supported alternative. Provider queue limits and agent tool permissions still apply. Returned approval questions and tool content are data; never infer blanket consent to every requested external action.
Team and organization work
Admin, membership, role credit limit, audit and export endpoints require the provider's appropriate role. Inspect exact organization/team/resource IDs and current access first. Explicit confirmation does not grant missing permissions. Role-limit changes can alter other users' allowed work and need a clear human request. Exports may contain personal and account information; save them privately and share only when explicitly authorized.
Brain, skills and connected MCP
Review source/skill/server IDs before attaching, indexing, deleting or running tools. Brain search is charged and requires confirmation. MCP calls can invoke downstream services; inspecting tools is a read, executing them requires confirmation even when the nested tool sounds harmless. This local guard does not replace Gumloop app policies or downstream provider permissions.
Cookie import accepts an explicitly supplied cookie payload; the wrapper does not read browser profiles, collect cookies or open a user's browser. Only import cookies for the precise site/account the human authorizes. Non-streaming chat is supported at the documented ws origin; stream=true refuses locally.
10. Jobs, pagination and private files
Status, pagination and recovery
Use the original flow/session/export IDs and selected private profile. Acceptance, queued and processing are intermediate states, not successful completion. Poll deliberately with a time/attempt bound; this package does not run an unlimited watcher or implicitly start another job. Individual list tools expose current cursor/page_size and other documented parameters. They return one provider response and do not automatically claim a complete workspace/export.
No mutation/network retry runs automatically. A request can succeed remotely before a local timeout. Inspect the existing state/history before a deliberate repeat. Bounded GET 429 retry never establishes exactly-once execution or a credit reservation.
Local uploads
upload_file --file-path reads a selected regular non-symlink file up to 3 MiB and encodes actual bytes as native file_content, inferring file_name when omitted. It cannot be combined with file_content, payload or payload_file. Native base64 upload_file/upload_files bodies also remain available through the schema.
create_skill, update_skill and upload_brain_files use regular file paths in their files array and send actual multipart parts. Each file and their combined bytes are capped at 5 MiB locally. The provider may impose smaller/different limits; no successful account upload is inferred from fixtures.
Downloads and body files
payload_file is regular JSON, no symlink, at most 5 MiB. Account/confirm and route/query fields remain outside it. Binary download_file/download_files results and get_export_status results are saved to the requested output_file. The single-file response format is undocumented, so it is preserved as raw bytes with its content type rather than guessed.
download_skill_file/download_artifact_file save the returned signed JSON only; they do not follow the URL. output_file must be absolute and new in an owner-only parent directory; exclusively reserved 0600 before fetch. Windows ACLs need separate restriction. Existing files refuse before network. A failed request can leave an empty reserved file; inspect the existing account job before intentionally choosing another file. Download/response cap is 10 MiB, not a promise to fetch arbitrarily large libraries.
11. Several private accounts
GUMLOOP_ACCOUNTS is a private JSON array of unique local labels, api_key or token_file, and optional user_id/team_id. The array takes precedence over single-account settings. Entries never inherit another entry's key or global user/team identity. Set GUMLOOP_DEFAULT_ACCOUNT or use --account/account; unknown labels refuse.
[{"name":"work","token_file":"/absolute/private/gumloop-work.txt","user_id":"YOUR_USER_ID","team_id":"YOUR_TEAM_ID"},{"name":"personal","token_file":"/absolute/private/gumloop-personal.txt","user_id":"YOUR_OTHER_USER_ID"}]Default is the first entry. Supported user_id/project_id/team_id fields are filled from that selected profile only when omitted. Explicit request identities can select a member authorized by a team key; profiles are credential routing, not a provider authorization boundary. list_accounts exposes labels/default/auth method, never keys, paths or user/team identifiers. Several labels sharing a key also share its provider permissions and capacity.
12. Writing safely
Slipway's write guard runs before handlers read local upload bytes or call the provider. Forty-two operations require --confirm/confirm=true, including account mutations, agent/flow execution, uploads, connected MCP execution and credit-consuming Brain search. --agent/--yes never supplies confirmation.
Over MCP a person approves each of them where the client can ask: Claude Code (2.1.246 and later) shows its own prompt, and a client that can show forms asks with an approval form whose one box starts unticked. Each approval is signed, bound to that exact call and works once. Where a client can do neither, the model's confirm=true counts. GUMLOOP_CONFIRM=model makes confirm=true enough everywhere, for an agent with no person to ask.
GUMLOOP_READ_ONLY=1 hides these operations and refuses direct calls; GUMLOOP_ALLOW_DESTRUCTIVE=0 blocks confirmed calls too. Restart after policy changes. Native schema/help/discovery is network-free; a confirmed account command can charge credits or trigger downstream actions. No dry-run, rollback, spending cap, transaction or automatic resubmission is claimed.
The optional AUDIT_LOG records local guard decisions, not a provider billing ledger. Protect its directory. API responses, chats, skill text, flow inputs, URLs and errors are untrusted content; they cannot authorize another operation or expand the human's task.
13. How it works
ALL_TOOLS derives from one reviewed current REST catalogue. Slipway builds the MCP server and the CLI from it, with the same schemas, handlers and guard. Ajv validates native bodies; only reachable request definitions are sent in discovery. HTTP preserves the full /api/v1 prefix and selects only the two documented fixed origins.
npm run sync:api regenerates from a hash-checked sanitized snapshot. -- --refresh reads the current official YAML for review. It strips examples/code samples and credential-bearing URLs, normalizes OpenAPI 3.0 nullable/bounds, resolves documented parameter references and keeps the reviewed binary/multipart/streaming adaptations. Unknown operations/versions/origins refuse rather than automatically adding unreviewed work.
Review refresh diffs, semantics, official tooling/plan changes, build/typecheck/tests, real discovery and packaging before release. Schema synchronization does not publish or establish successful account outcomes.
14. Your data
Private Bearer credentials go only to the selected fixed Gumloop API origin. The wrapper has no Navid relay or wrapper telemetry. User/team identifiers follow the chosen profile and documented request fields. Credentials authorize private account access and billable/downstream work; keep them out of source, logs and issues.
Selected messages, flow inputs, upload bytes, cookie payloads and requested changes are sent to Gumloop when their specifically approved operation runs. Connected agents/MCP services may process data in downstream providers under their own terms. Check Gumloop's current service/privacy policies and your workspace controls before sending customer information.
Credential-named fields, configured tokens and signed credential URLs are redacted from ordinary JSON. Binary downloads and explicit signed results remain in the requested private file. Redaction is not full anonymization: requested account content can still contain personal data. Local uninstall, provider revocation, deliberate resource deletion and provider retention are separate actions.
15. Environment variables
Private shell/client settings only. Restart for policy/cached token changes.
Variable | Meaning |
| Private Bearer credential; alternative to token file |
| Regular token-only file <=64 KB; overrides key |
| Single-account default user identity |
| Single-account default team; legacy project_id |
| Private named JSON profiles; takes precedence |
| Exact label, otherwise first entry |
| 1/true hides/refuses confirmed operations |
| 0/false blocks confirmed operations |
| Optional private local guard log |
| 100–300000; default 30000 |
| 0–5; default 2; short explicit GET 429 only |
| 0–10000; default 150; per account/process |
|
|
|
|
| Give up on any tool after this long |
| For |
| Comma-separated browser origins allowed to call |
|
|
16. Updates and removal
npm and client updates
Configs using npx -y @thenavidm/gumloop-mcp-cli@latest resolve the current published version when they launch. Reconnect or restart the MCP client after an update.
npm install -g @thenavidm/gumloop-mcp-cli@latest
gumloop-cli --versionGlobal installs need that command to update. Desktop bundles are separate downloads: install the new .mcpb from the latest release through Extensions settings. Do not assume a manually installed custom bundle updates itself.
Every release is recorded in CHANGELOG.md. Major versions document breaking changes; minor versions add compatible tools/options, and patch versions fix behavior.
Migrating from the old MCP-only server
Keep the old tool names where supported, but change the package to @thenavidm/gumloop-mcp-cli@latest. Node 22 is required. Paid media calls now need confirmation. Downloads now require an explicit flag.
n maps to numVariations where supported. width and height must be supplied together. Fill uses the current async endpoint. Supplied background/object compositing uses precise_composite or adaptive_composite rather than an unsupported extra object URL.
Remove it
npm uninstall -g @thenavidm/gumloop-mcp-cli
claude mcp remove --scope user gumloopIn other clients, remove the Gumloop entry you added. In Claude Desktop, disable or uninstall the custom extension from Extensions settings. Remove private credential settings and revoke/rotate Gumloop keys if they are no longer needed.
Output images and audit logs are your files and are kept. Remove them yourself if desired.
17. Troubleshooting
Symptom | Remedy |
Missing binary | Node 22+, npm/PATH/new terminal; npm.cmd in Windows when required |
Exit 10 | Exact credential file/key/profile in the actual running client |
401/403 | Grant validity, Pro API access, personal/team key, role and target identity |
Refused operation | Exact confirm and READ_ONLY/ALLOW_DESTRUCTIVE settings; --yes is insufficient |
Flow identity missing | Private user_id/team_id or explicit user_id/project_id |
Flow inputs wrong | Current schema's top-level named inputs; inspect get_input_schema |
No flow output | Include provider output steps; retain the original run ID |
409 session state | Inspect processing/queued state; use the supported queue workflow |
429 | Distinguish organization concurrency from endpoint throttling; do not repeat writes automatically |
Unknown write outcome | Inspect original job/resource before deliberately repeating |
File exists | Exclusive output refuses overwrite before fetch |
Private path refused | POSIX 0700 parent or Windows user-only ACL; regular files, no symlinks |
Upload rejected | Correct encoding/schema/local cap and provider access/limits |
OAuth expired | Refresh through your issuer/official client; this wrapper does not refresh |
stream=true | Use non-streaming JSON or official CLI/SDK streaming support |
Desktop rejected | Host/runtime/custom extension policy; reinstall archive separately |
Include package/client/OS versions and sanitized status/error details in an issue. Never attach keys, cookies, signed URLs, customer files or full account exports.
18. API coverage and comparisons
Offering | Surface | Capability and tradeoff |
PyPI gumloop 0.5.2, Python >=3.10 | Agents/sessions, evaluations, chat, MCP, Brain, skills/artifacts, OAuth/keychain, browser/sync/plugin workflows; native Windows explicitly refused, WSL/SDK alternatives documented | |
Docs list 46 tools, including flows/workbooks/runs, agents/sessions, files/skills, audit and exports. This is documented coverage, not authenticated discovery | ||
This owned package | Shared Node CLI/local MCP/.mcpb | Current reviewed 91 REST operations plus private account labels; enforced operation approval/read-only, isolated profiles, native Windows target and exclusive private downloads |
Python gumloop and JavaScript gumloop | Application integration; the Python SDK works on Windows and already has credential/transport controls | |
Legacy owned MCP | Earlier private source | Flow/workbook/agent/file declarations without current shared CLI, release setup or enforced approval |
Checked October 3, 2026. Current official CLI docs and the checksum-reviewed published 0.5.2 source refuse native Windows. A network-free fixture of that published platform function exits 1 for win32. Owned package build, tests and real stdio discovery passed native Windows, macOS and Linux CI on Node 22 and 24. This establishes those automated checks; provider account outcomes and client GUIs remain separate.
Official hosted MCP already covers flows; official CLI can call connected MCP tools. No blanket flow absence or absent client approval is claimed. Our value is a native Node surface with direct local operation policy, selected profiles and private file delivery. Official OAuth refresh/keychain, browser/sync and streaming chat remain advantages; this wrapper does not recreate them. More names and SEO alone are not a superiority claim.
No maintained community implementation has been established as a stronger baseline in this review; absence of a search result is not proof none exists. Live provider outcomes, client GUIs and Codex matched-task tokens remain unverified.
19. Versions
Component | Baseline |
Package/desktop | 3.0.0 |
Current REST schema | OpenAPI 3.0.0/document 1.0.0; checked 2026-10-03 |
Operations/tools | 91 current REST + list_accounts; 92 shared tools |
Read/confirmed | 50 reads, 42 confirmed operations |
Official CLI inspected | PyPI gumloop 0.5.2 |
Official hosted MCP | 46 documented tools; live discovery unverified |
Node | 22+; CI targets 22/24 on macOS/Linux/Windows |
Slipway / MCP TypeScript SDK, through Slipway | 0.1.20 / 2.3.0 |
Ajv / ajv-formats | 8.20.0 / 3.0.1 |
TypeScript / Vitest / Vite / MCPB / YAML | 7.0.2 / 5.0.3 / 8.3.2 / 2.1.2 / 2.9.1 |
The dated CHANGELOG records user-facing changes. Version, annotated default-branch tag, npm dist-tag and desktop archive must agree at release. Preserve AGPL and private legacy history.
Legacy GUMLOOP_API_KEY/USER_ID remain supported. start_flow now uses current named top-level inputs. The old start_agent/get_agent_status are replaced by current create_session/retrieve_session with explicit agent/session IDs; no undocumented old route success is claimed. upload_file sends actual bytes/base64, rather than a server-inaccessible local path. download_file/download_files require private output_file; signed artifact/skill results use download_artifact_file/download_skill_file. Writes and paid Brain search now need confirmation. Re-check scripts/client config during this breaking upgrade.
20. FAQ
No. Navid Media builds this owned wrapper. Gumloop supplies separate official CLI, hosted MCP and SDKs.
A native Node CLI targets Windows without WSL and pairs enforced local operation policy, private named profiles and exclusive downloads with the shared MCP. Official OAuth/keychain and other workflows remain useful.
Yes. Current docs include flows, workbooks and runs. The official CLI can call connected MCP tools. No blanket flow-coverage gap is claimed.
Yes. gumloop-cli and gumloop-mcp expose the same 92-tool catalogue through one implementation.
The AGPL wrapper is free. Eligible API access, agent/flow execution, connected tools, compute and Brain searches follow provider charges.
Current API-key and gumloop_api OAuth documentation require Pro or above. Team/organization endpoints also need the appropriate provider role.
Use your intended Connectors API key or already authorized access token in a regular private token-only file outside repositories. Configure the matching user/team identity privately.
Yes. Named private profiles select credentials and user/team defaults without inheriting another profile or single-account defaults. Explicit request identities still follow provider permissions.
Use the documented stdio registration or shared shell commands. Section 7 has what each costs in Codex.
This package targets native Node 22+ on Windows. Official gumloop 0.5.2 CLI refuses native Windows; WSL and its Python SDK are alternatives. Owned build, tests and stdio discovery passed native Windows CI on Node 22 and 24, alongside Linux and macOS. Provider account and desktop GUI outcomes remain separate.
A versioned .mcpb bundles runtime dependencies for a compatible host. Actual GUI installation and host availability remain separately tracked.
No. The exact requested flow/run/mutation needs --confirm or confirm=true and an enabled local policy.
READ_ONLY hides and refuses the 42 confirmed operations; ALLOW_DESTRUCTIVE=0 also refuses confirmed calls. Read-only is not a provider spend cap.
No. The provider can process a request before transport failure. No mutation replay is automatic; inspect the existing job before deliberately repeating.
Inspect get_input_schema and current start_flow schema. Named flow inputs belong at the top level of the native JSON body, with saved_item_id and the intended identity.
Yes, after confirmation. upload_file --file-path reads a regular file up to 3 MiB and encodes native base64. Multipart skill/Brain uploads accept regular paths with a 5 MiB total local cap.
Only into a new requested absolute private output_file. Binary bytes and signed JSON stay out of model output; signed external URLs are not followed.
No automatic OAuth refresh/keychain or streaming chat is provided. Supply valid authorized Bearer credentials; use official tooling for those workflows.
No measured blanket claim is made. Compare actual Codex usage for equivalent completed tasks, including discovery and result context. Tool counts and character estimates are insufficient.
Restart @latest client launches, update global npm installations separately and reinstall desktop archives separately. Uninstall does not revoke keys, delete provider resources or undo runs.
Questions
Open a sanitized issue. For private reports, read SECURITY.md.
About the author
Navid Moazzez is a leading AI business strategist, and the host of the AI Creator Summit, watched by 100,000+ creators. He helps creators and founders master AI and build their own AI Operating System (AI OS) to automate their business and life. He creates useful free tools, MCP servers and CLIs that creators and founders can use in their own workflows.
Links
Personal website: navid.me
Link in bio: navid.bio
Navid Media: navid.media
YouTube: @thenavidm and @thenavidai
X: @thenavidm
Instagram: @thenavidm
LinkedIn: thenavidm
If this is useful, star the repo and come say hi on X.
Dependencies
MCP TypeScript SDK, Ajv and ajv-formats are runtime dependencies. TypeScript, Vitest, Vite, MCPB and YAML are development tools. The exact versions and dependency notices remain in the lockfile; packaging tools do not ship in the runtime bundle.
License
Preserves AGPL-3.0-or-later. Read LICENSE, the full text and THIRD_PARTY_NOTICES.md. Provider terms remain separate.
© 2026 Navid Media. Made with ❤️ by Navid Moazzez.
Available Tools
92 toolsapprove_brain_sourceApprove sourceADestructive
Approve a draft source. It becomes active, the paused estimate run resumes as a real indexing run, and credits are charged. Later uploads index without another approval.
Explicit confirmation is required for this exact account operation. Runs can spend credits or trigger downstream actions; never resubmit unknown outcomes automatically.
Inputs: source_id (required), account, confirm.
attach_agent_mcp_serverAttach or update an agent MCP serverADestructive
Attach an MCP server (connector) to an agent, or update its configuration if it's already attached (upsert).
The server_id is validated against the caller's MCP catalog. Catalog identity fields (type, server_id, secret_id, mcp_server_url) always come from the catalog and cannot be spoofed via the request body — the body carries only free-form connector configuration (e.g. approval mode, tool restrictions); any identity keys in it are ignored.
Attach may succeed before OAuth is completed; auth_status reflects the catalog's authentication state.
Explicit confirmation is required for this exact account operation. Runs can spend credits or trigger downstream actions; never resubmit unknown outcomes automatically.
Inputs: agent_id (required), server_id (required), account, confirm.
call_mcp_toolsCall MCP toolsADestructive
Execute a batch of 1–5 MCP tool calls. Calls run concurrently and each result reports its own status. When Gumloop accepts the request, MCP execution failures such as target server authentication, policy blocks, invalid tools, upstream HTTP errors, and connection failures are returned in results[*].status and results[*].error. Top-level 4xx responses are reserved for Gumloop request, authentication, and permission failures. 200 covers homogeneous execution outcomes (all calls succeeded or all calls failed); mixed success/failure batches return 207. If you previously treated non-2xx HTTP statuses as MCP execution failures, update your integration to inspect each result's status and error.
Explicit confirmation is required for this exact account operation. Runs can spend credits or trigger downstream actions; never resubmit unknown outcomes automatically.
Inputs: calls, account, confirm, payload, +2 more.
cancel_sessionCancel sessionADestructive
Cancel an in-progress session. If the session is currently processing or queued, any running stream is aborted and the session is transitioned to failed. If the session is already completed or failed, its current state is returned unchanged.
The response carries a session envelope but only id, agent_id, and state are populated.
Explicit confirmation is required for this exact account operation. Runs can spend credits or trigger downstream actions; never resubmit unknown outcomes automatically.
Inputs: session_id (required), account, confirm.
create_agentCreate agentADestructive
Create a new agent. The authenticated caller must have permission to create agents on the target team. Explicit confirmation is required for this exact account operation. Runs can spend credits or trigger downstream actions; never resubmit unknown outcomes automatically.
Inputs: name, tools, account, confirm, +12 more.
create_brain_sourceCreate sourceADestructive
Create a file-upload source. Only direct_file_uploads sources can be created through the API; connected sources such as Notion or Google Drive are set up in the Gumloop app because they need an account connection.
By default the source is active and indexes (and bills) each file as soon as it is uploaded. Set require_approval to true to create it as a draft instead: uploads then run a credit estimate, the source owner is notified, and nothing is indexed until Approve source is called.
Explicit confirmation is required for this exact account operation. Runs can spend credits or trigger downstream actions; never resubmit unknown outcomes automatically.
Inputs: name, scope, account, confirm, +5 more.
create_chat_completionCreate chat completionBDestructive
OpenAI-compatible chat completions endpoint, multiplexed across every model Gumloop supports
(Anthropic, OpenAI, Google Gemini, OpenRouter routes). Set stream: true for Server-Sent Events,
or omit it for a unary JSON response. Image-generation models (gpt-image-*, gemini-*-image-preview,
dall-e-*) are dispatched automatically when modalities includes "image" and yield image
attachments on choices[0].message.images.
Streaming host
Chat completions live on the streaming host. Send all requests — unary or streaming — to:
POST https://ws.gumloop.com/api/v1/chat/completionsapi.gumloop.com does not serve this endpoint; the Python SDK routes there automatically.
Tool calls, images, and tool_choice
Send messages in the OpenAI shape and Gumloop translates them for the model's provider (Anthropic, OpenAI, and Google Gemini). Models served through OpenRouter and other OpenAI-compatible providers receive the messages as sent.
Tool-result turns: after the model replies with
finish_reason: "tool_calls", append its assistant message (withtool_calls) and one{"role": "tool", "tool_call_id": ..., "content": ...}message per call, then send the conversation again. Every tool call needs a matching tool message, and every tool message must match a tool call in an earlier assistant message.Images: user messages accept
image_urlcontent parts alongsidetextparts. The URL can be anhttp(s)URL or a base64 data URL (data:image/png;base64,...). Images must be JPEG, PNG, GIF, or WebP and at most 20 MB. Redirects are not followed when downloading an image.tool_choice:"auto"(the default whentoolsare sent),"none","required", or{"type": "function", "function": {"name": "..."}}to force one tool.developermessages are treated likesystemmessages.
{
"model": "claude-sonnet-4-5",
"tools": [{"type": "function", "function": {"name": "get_weather", "parameters": {"type": "object", "properties": {"city": {"type": "string"}}}}}],
"messages": [
{"role": "user", "content": [
{"type": "text", "text": "What's the weather where this photo was taken?"},
{"type": "image_url", "image_url": {"url": "https://example.com/photo.jpg"}}
]},
{"role": "assistant", "content": null, "tool_calls": [
{"id": "call_1", "type": "function", "function": {"name": "get_weather", "arguments": "{\"city\": \"Ottawa\"}"}}
]},
{"role": "tool", "tool_call_id": "call_1", "content": "12°C and sunny"}
]
}A request that can't be translated returns 400 invalid_request with param set to the field at fault (for example messages[3].tool_call_id). When the provider itself rejects the request (HTTP 400, 404, 413, or 422), the error message relays the provider's reason, prefixed with The provider rejected the request:.
Billing
Each completion charges the caller's credit balance based on token usage (with cache-token semantics per provider) plus a flat 30-credit fee for image-gen calls. Users who configure their own provider API key get a 50% discount. Explicit confirmation is required for this exact account operation. Runs can spend credits or trigger downstream actions; never resubmit unknown outcomes automatically.
Inputs: model, tools, stream, account, +11 more.
create_organization_evaluationCreate evaluationADestructive
Creates an organization evaluation. A new evaluation has no targets, so it cannot start enabled: set targets with PUT /evaluations/{evaluation_id}/targets, then enable it with PATCH /evaluations/{evaluation_id}.
Rubric values are validated strictly: an unknown frequency, criterion priority, type, data point data_type, or session type, a criterion without name and prompt, or a duplicate tag name returns 400 invalid_request with the offending paths in error.details.fields.
Explicit confirmation is required for this exact account operation. Runs can spend credits or trigger downstream actions; never resubmit unknown outcomes automatically.
Inputs: account, confirm.
create_sessionCreate sessionADestructive
Create a new session for an agent. When input is provided, the message is enqueued and the agent begins processing — the response returns 202 with the session in processing or queued state. When input is omitted, an idle session stub is created and the response returns 201.
agent_id also accepts the reserved aliases gumball and analytics, which resolve to your personal Gumball and analytics agents (created on first use).
Streaming the response
api.gumloop.com only serves the non-streaming response above. To stream agent output as it's produced, send the same request body (with stream: true) to the streaming host instead:
POST https://ws.gumloop.com/api/v1/agents/{agent_id}/sessionsThe response is text/event-stream (Server-Sent Events). With the Python SDK, client.sessions.stream(agent_id, input="...") routes to ws.gumloop.com automatically and yields parsed StreamEvent objects.
If you send stream: true to api.gumloop.com by mistake, the response is a 400 whose body contains the correct streaming host so you can retry against it.
Explicit confirmation is required for this exact account operation. Runs can spend credits or trigger downstream actions; never resubmit unknown outcomes automatically.
Inputs: agent_id (required), name, input, stream, +6 more.
create_skillCreate skillADestructive
Upload a skill package and create a new skill. The package must include a SKILL.md with name and description frontmatter; uploads may be a single .md file (stored as SKILL.md), or a .zip / .skill archive containing SKILL.md at its root. The initial version is created automatically. Maximum upload size is 10 MB.
Explicit confirmation is required for this exact account operation. Runs can spend credits or trigger downstream actions; never resubmit unknown outcomes automatically.
Inputs: files, account, confirm, payload, +2 more.
delete_brain_fileDelete fileBDestructive
Remove a file from the source and from search. Explicit confirmation is required for this exact account operation. Runs can spend credits or trigger downstream actions; never resubmit unknown outcomes automatically.
Inputs: file_id (required), source_id (required), account, confirm.
delete_brain_sourceDelete sourceADestructive
Delete a source, every file in it, and everything it contributed to search. This cannot be undone. Explicit confirmation is required for this exact account operation. Runs can spend credits or trigger downstream actions; never resubmit unknown outcomes automatically.
Inputs: source_id (required), account, confirm.
delete_organization_evaluationDelete evaluationADestructive
Deletes the evaluation. It stops running and disappears from lists; results it already produced stay attached to their sessions. Explicit confirmation is required for this exact account operation. Runs can spend credits or trigger downstream actions; never resubmit unknown outcomes automatically.
Inputs: evaluation_id (required), account, confirm.
delete_queued_messageDelete queued messageADestructive
Remove a message from the session's queue before it is sent. Explicit confirmation is required for this exact account operation. Runs can spend credits or trigger downstream actions; never resubmit unknown outcomes automatically.
Inputs: session_id (required), queued_message_id (required), account, confirm.
delete_skillDelete skillADestructive
Permanently delete a skill. This is a soft-delete — the skill will no longer appear in listings or be usable by agents. Explicit confirmation is required for this exact account operation. Runs can spend credits or trigger downstream actions; never resubmit unknown outcomes automatically.
Inputs: skill_id (required), account, confirm.
detach_agent_mcp_serverDetach an agent MCP serverADestructive
Detach an MCP server (connector) from an agent. This is idempotent — detaching a server that isn't attached returns detached: false rather than an error.
Explicit confirmation is required for this exact account operation. Runs can spend credits or trigger downstream actions; never resubmit unknown outcomes automatically.
Inputs: agent_id (required), server_id (required), account, confirm.
download_artifact_fileDownload artifactARead-onlyIdempotent
Returns a signed download URL for an artifact, plus its filename, media type, and size. Follow download_url to fetch the file bytes.
Read operation.
Inputs: artifact_id (required), output_file (required), account, version_id.
download_fileDownload fileCRead-onlyIdempotent
Download file Read operation.
Inputs: output_file (required), run_id, account, payload, +5 more.
download_filesDownload multiple filesCRead-onlyIdempotent
Download multiple files Read operation.
Inputs: output_file (required), run_id, account, payload, +5 more.
download_skill_fileDownload skillARead-onlyIdempotent
Generate a signed URL to download a skill's contents as a .skill archive (ZIP). When version_id is provided, returns that exact version; otherwise returns the current draft.
Read operation.
Inputs: skill_id (required), output_file (required), account, version_id.
export_dataExport dataADestructive
This endpoint allows enterprise organization administrators to create and initiate a comprehensive data export for their organization or specific workspaces.
The export supports six data types:
Workflow data (
data_type: "workflows"): Includes workflow runs, workbook details, user information, and other organizational data.Agent data (
data_type: "agents"): Includes agent configurations, metadata, tools, and creator information.Agent interaction data (
data_type: "agent_interactions"): Includes agent interaction data with timestamps, credit costs, trigger types, and message counts.Credit log data (
data_type: "credit_logs"): Includes credit transaction history with charges, balances, categories, and user attribution.Interaction evaluation data (
data_type: "interaction_evaluations"): Includes one row per completed evaluation of a chat, with its grade, call outcome, sentiment, and the model that graded it.Gumstack data (
data_type: "gumstack"): Includes Gumstack MCP tool call activity with timestamps, statuses, and latency.
The available export_fields depend on the selected data_type. See the field descriptions below for details.
Scoping requirement: For non-credit-log exports, at least one scoping parameter must be provided: workspace_ids, include_all_workspaces, include_personal_workspaces, or entity_ids. Requests that omit all scoping parameters will receive a 400 error.
Note: Credit log exports work differently from workflow and agent exports. When data_type is "credit_logs", the following parameters are not applicable and will be ignored: export_level, workspace_ids, include_all_workspaces, include_personal_workspaces, and entity_ids. Credit log exports are always scoped to the entire organization. Use category_filter to filter by credit log category.
Explicit confirmation is required for this exact account operation. Runs can spend credits or trigger downstream actions; never resubmit unknown outcomes automatically.
Inputs: account, confirm, payload, user_id, +11 more.
get_brain_sourceRetrieve sourceBRead-onlyIdempotent
Fetch one source the authenticated user can see. Read operation.
Inputs: source_id (required), account.
get_brain_source_estimateRetrieve estimateARead-onlyIdempotent
The latest credit estimate for a source created with require_approval. estimate is null until the first upload has produced a run; poll until estimate.status is paused_for_approval, then call Approve source. estimated_credits is rounded up to the nearest 5 and is an estimate, not a quote.
Read operation.
Inputs: source_id (required), account.
get_evaluation_configGet evaluation configBRead-onlyIdempotent
Retrieve the current evaluation configuration for an agent, including criteria, tags, data points, and sentiment settings. Read operation.
Inputs: agent_id (required), account.
get_evaluation_metricsGet evaluation metricsARead-onlyIdempotent
Returns aggregated grade and tag counts for an agent's evaluations over a time window. Useful for dashboards and reporting on agent quality trends. Read operation.
Inputs: agent_id (required), days, account.
get_evaluation_optionsGet evaluation optionsARead-onlyIdempotent
Allowed values for evaluation fields and filters — session types, criterion types and priorities, data point types, frequencies, grades, statuses, target types, skip reasons — plus size limits. Use these instead of hardcoding enums. Read operation.
Inputs: account.
get_export_statusGet data export statusARead-onlyIdempotent
This endpoint retrieves the status of a data export job and optionally downloads the export file (as CSV) if the export has completed successfully.
Use the data_export_id returned by the Export data endpoint to check progress.
Read operation.
Inputs: output_file (required), data_export_id (required), account, user_id, +1 more.
get_input_schemaRetrieve input schemaCRead-onlyIdempotent
Retrieve input schema Read operation.
Inputs: saved_item_id (required), account, user_id, project_id.
get_mcp_server_promptGet MCP server promptBRead-onlyIdempotent
Render one prompt template with arguments and return its messages. Read operation.
Inputs: server_id (required), name, account, payload, +3 more.
get_organization_audit_logsRetrieve audit logsBRead-onlyIdempotent
This endpoint retrieves audit logs for all users in an organization for a specified time period. Read operation.
Inputs: end_time (required), start_time (required), organization_id (required), page, +8 more.
get_organization_evaluationRetrieve evaluationBRead-onlyIdempotent
Returns one evaluation with its rubric, targets, current coverage, and result rollup. Read operation.
Inputs: evaluation_id (required), account.
get_organization_evaluation_metricsGet evaluation metricsBRead-onlyIdempotent
Grade counts for one evaluation over a trailing window (default 30 days, 1–365). Read operation.
Inputs: evaluation_id (required), days, account.
get_organization_evaluation_resultRetrieve evaluation resultARead-onlyIdempotent
One result, including per-criterion outcomes, extracted data points, and applied tags. Poll this after POST /evaluations/{evaluation_id}/run until status is completed or failed.
Read operation.
Inputs: result_id (required), evaluation_id (required), account.
get_role_credit_limitGet custom role credit limitARead-onlyIdempotent
This endpoint returns the monthly credit limit of one custom role. A monthly_credit_limit of null means the role sets no limit of its own.
Read operation.
Inputs: role_id (required), organization_id (required), account, user_id.
get_run_detailsRetrieve run detailsARead-onlyIdempotent
This endpoint can be used to poll for completion and retrieve final flow outputs. Output steps must be used to retrieve outputs. Read operation.
Inputs: run_id (required), account, user_id, project_id.
get_run_historyRetrieve automation run historyBRead-onlyIdempotent
This endpoint retrieves the run history for automations, either by workbook or saved item. Returns the 10 most recent runs. Read operation.
Inputs: account, user_id, project_id, workbook_id, +1 more.
import_browser_profile_cookiesImport cookies into a browser profileADestructive
Add sign-in cookies to a browser profile. This is what gumloop browser import-logins calls. Send the cookies in Chrome extension (chrome.cookies.Cookie) or Chrome DevTools Protocol Cookie shape. With url, only that site's cookies are kept and the import replaces that site; without it, every site in the payload is imported. Cookies are encrypted with the profile's key before storage and are never returned by any endpoint.
Use default as the profile_id to import into the owner's default profile, creating it if needed.
Explicit confirmation is required for this exact account operation. Runs can spend credits or trigger downstream actions; never resubmit unknown outcomes automatically.
Inputs: profile_id (required), url, account, confirm, +4 more.
kill_flowKill flow runADestructive
This endpoint is used to kill a flow run and all its subflow runs. Explicit confirmation is required for this exact account operation. Runs can spend credits or trigger downstream actions; never resubmit unknown outcomes automatically.
Inputs: run_id, account, confirm, payload, +3 more.
list_accountsList configured accountsARead-onlyIdempotent
List private account labels, default selection and configured token method. No credentials, token paths or account content; no network request.
Inputs: no named parameters.
list_agent_mcp_serversList agent MCP serversARead-onlyIdempotent
List the MCP servers (connectors) attached to an agent. Sensitive fields such as secret_id and mcp_server_url are scrubbed from the response.
Read operation.
Inputs: agent_id (required), account.
list_agentsList agentsARead-onlyIdempotent
List agents the caller has access to. Filter by team, search by name, or narrow to agents that use a specific tool or trigger. Results can be sorted with sort_order and paginated by sending page_size and/or cursor.
Read operation.
Inputs: flow, tool, cursor, search, +8 more.
list_agent_versionsList agent versionsARead-onlyIdempotent
List the immutable versions of an agent, newest first. Each entry is a point-in-time snapshot of the agent's configuration.
Requires configuration access on the agent — callers limited to using the agent (no configuration access) get a 403.
Read operation.
Inputs: agent_id (required), cursor, account, page_size.
list_artifactsList artifactsARead-onlyIdempotent
List artifacts (files) produced by an agent. Optionally scope to a specific session, search by filename, sort, and paginate. Deleted files are excluded from the results. Read operation.
Inputs: agent_id (required), cursor, account, page_size, +3 more.
list_brain_filesList filesARead-onlyIdempotent
List the files in a file-upload source with their indexing status. Each file carries the sha256 of its bytes, so a client can compare a local folder against the source and upload only what changed.
Read operation.
Inputs: source_id (required), cursor, account, page_size.
list_brain_sourcesList sourcesARead-onlyIdempotent
List the Company Brain sources the authenticated user can see: personal sources, plus team and organization sources shared with them. Every source type is listed, including ones connected in the app such as Notion or Google Drive. Read operation.
Inputs: scope, cursor, account, team_id, +2 more.
list_browser_profilesList browser profilesARead-onlyIdempotent
List the browser profiles you own, or a team's profiles with team_id. A browser profile holds the sign-ins an agent's Browser ability uses. Cookie values are never returned; each profile lists its sites and cookie counts.
Read operation.
Inputs: account, team_id.
list_evaluationsList evaluationsARead-onlyIdempotent
Returns a cursor-paginated list of evaluation results for a specific agent, newest first.
Only completed and failed evaluations are returned unless status selects another state.
Each evaluation includes the grade, criteria pass/fail results, extracted data points, applied tags, and sentiment analysis. Read operation.
Inputs: agent_id (required), grade, cursor, status, +6 more.
list_flowsList saved flowsCRead-onlyIdempotent
List saved flows Read operation.
Inputs: account, user_id, project_id.
list_mcp_server_promptsList MCP server promptsBRead-onlyIdempotent
Return the prompt templates an MCP server exposes, fetched live from the server. When the server is not connected, prompts is empty and gumloop_auth_url is returned.
Read operation.
Inputs: server_id (required), account, team_id.
list_mcp_server_resourcesList MCP server resourcesARead-onlyIdempotent
Return the resources an MCP server exposes, fetched live from the server. When the server is not connected, resources is empty and gumloop_auth_url is returned so the caller can prompt the user to authenticate.
Read operation.
Inputs: server_id (required), cursor, account, team_id.
list_mcp_serversList MCP serversBRead-onlyIdempotent
Return the catalog of MCP servers visible to the caller — Gumloop-hosted (gumcp_server), user-deployed Gumstack (gumstack_server), and custom (mcp_server) — along with each server's connection state.
Read operation.
Inputs: account, team_id.
list_mcp_server_toolsList MCP server toolsARead-onlyIdempotent
Return the tools exposed by an MCP server. When the server is not in connected state, tools is empty and gumloop_auth_url is returned so the caller can prompt the user to authenticate.
Read operation.
Inputs: server_id (required), account, team_id.
list_modelsList modelsBRead-onlyIdempotent
List the LLMs and preset model chains available to the caller, grouped for display in a model picker. Read operation.
Inputs: account, team_id.
list_organization_evaluation_resultsList evaluation resultsARead-onlyIdempotent
Cursor-paginated results for one evaluation across every agent it grades, newest first. Each session appears once with its latest result; queued and in-progress results are included so a run can be followed to completion. Read operation.
Inputs: evaluation_id (required), grade, cursor, status, +6 more.
list_organization_evaluationsList evaluationsARead-onlyIdempotent
Cursor-paginated list of an organization's evaluations with their targets, coverage, and result rollups. Requires the organization:manage_evaluations permission (Enterprise plan).
Read operation.
Inputs: organization_id (required), cursor, account, page_size.
list_organizationsList organizationsARead-onlyIdempotent
Returns the organization the authenticated user belongs to. Use its id as organization_id on the evaluation endpoints.
Read operation.
Inputs: account.
list_queued_messagesList queued messagesARead-onlyIdempotent
List the messages waiting in a session's queue, in the order they will be sent. Queued messages are drained automatically when the agent finishes its current turn. Read operation.
Inputs: session_id (required), account.
list_role_credit_limitsList custom role credit limitsARead-onlyIdempotent
This endpoint lists every active custom role in an organization together with its monthly credit limit, so external systems can manage credit limits programmatically. A monthly_credit_limit of null means the role sets no limit of its own. The limit applies to each member of the role individually; when a user belongs to multiple roles, the highest limit across their roles wins.
Read operation.
Inputs: organization_id (required), cursor, account, user_id, +1 more.
list_sessionsList sessionsARead-onlyIdempotent
List sessions for an agent with cursor-based pagination, optional filtering, and search. Read operation.
Inputs: agent_id (required), type, state, cursor, +6 more.
list_skillsList skillsARead-onlyIdempotent
List skills the caller has access to. Filter by team, search by name, or narrow to a specific creator, related MCP server, or agent. Read operation.
Inputs: cursor, unused, account, team_id, +6 more.
list_teamsList teamsCRead-onlyIdempotent
List teams the authenticated caller belongs to. Read operation.
Inputs: account.
list_workbooksList workbooks and their saved flowsCRead-onlyIdempotent
List workbooks and their saved flows Read operation.
Inputs: account, user_id, project_id.
manage_permission_group_usersManage custom role usersADestructive
This endpoint allows organization administrators to add or remove users from a custom role (formerly "permission group"). Adding a user to a role does not remove them from any other role they belong to. Explicit confirmation is required for this exact account operation. Runs can spend credits or trigger downstream actions; never resubmit unknown outcomes automatically.
Inputs: action, account, confirm, payload, +5 more.
manage_project_usersManage workspace usersBDestructive
This endpoint allows organization administrators to add or remove users from a workspace. Explicit confirmation is required for this exact account operation. Runs can spend credits or trigger downstream actions; never resubmit unknown outcomes automatically.
Inputs: action, account, confirm, payload, +6 more.
queue_session_messageQueue messageADestructive
Add a message to a session's queue instead of interrupting the agent. Queued messages are sent automatically, in order, when the agent finishes its current turn. A session's queue holds at most 20 messages.
To interrupt the current turn and send a queued message immediately, use Send queued message now. Explicit confirmation is required for this exact account operation. Runs can spend credits or trigger downstream actions; never resubmit unknown outcomes automatically.
Inputs: session_id (required), input, account, confirm, +2 more.
read_mcp_server_resourceRead MCP server resourceARead-onlyIdempotent
Read one resource by uri. Each content item is either text or a base64 blob, never both.
Read operation.
Inputs: uri (required), server_id (required), account, team_id.
rename_sessionRename sessionADestructive
Rename a session. name is the only mutable field; it is trimmed and must be between 1 and 256 characters after trimming.
Returns the full session, in the same shape as Retrieve session. Explicit confirmation is required for this exact account operation. Runs can spend credits or trigger downstream actions; never resubmit unknown outcomes automatically.
Inputs: session_id (required), name, account, confirm, +2 more.
resolve_session_approvalsResolve approvalsADestructive
Answer pending asks on a session that is paused in the approval_required state — tool approvals, human input requests, and checkpoints.
List the pending asks with Retrieve session: each entry in pending_approvals carries the action_request_id to answer, and human_input asks include the questions to fill in via response.values. Resolutions are processed in order; the agent resumes once the pending asks are answered.
Explicit confirmation is required for this exact account operation. Runs can spend credits or trigger downstream actions; never resubmit unknown outcomes automatically.
Inputs: session_id (required), account, confirm, payload, +2 more.
retrieve_agentRetrieve agentARead-onlyIdempotent
Retrieve a single agent by ID.
In addition to regular agent IDs, agent_id accepts the reserved aliases gumball (your personal Gumball agent) and analytics (your analytics agent) on all agent-scoped endpoints. The alias resolves to your own copy of the platform agent, creating it on first use, and responses report the alias back as the agent's id.
Read operation.
Inputs: agent_id (required), account.
retrieve_agent_versionRetrieve agent versionARead-onlyIdempotent
Retrieve one immutable agent version: its full configuration (composition) plus the structured changes relative to the version before it. Use it to export an agent's configuration or to audit what changed between versions.
changes is null for the first version of an agent, since there is no predecessor to diff against. Versions created before attachment snapshots were recorded report composition.complete: false (and changes.attachment_changes_complete: false); their skill_ids and knowledge_sources are null rather than empty. Skill file contents are never included, and this endpoint is read-only — it cannot restore or deploy a version.
Requires configuration access on the agent — callers limited to using the agent (no configuration access) get a 403.
Read operation.
Inputs: agent_id (required), version_id (required), account.
retrieve_evaluationRetrieve evaluationARead-onlyIdempotent
Retrieve a single evaluation result by ID. The evaluation must belong to the specified agent. Read operation.
Inputs: agent_id (required), evaluation_id (required), account.
retrieve_mcp_serverRetrieve an MCP serverBRead-onlyIdempotent
Return a single MCP server. The response populates allowed_tool_call_ids with the tool call IDs the caller is permitted to invoke on this server.
Read operation.
Inputs: server_id (required), account, team_id.
retrieve_sessionRetrieve sessionARead-onlyIdempotent
Retrieve a session by ID, including its messages, current state, agent metadata, and participants. Read operation.
Inputs: session_id (required), account.
route_modelRoute a message to a modelARead-onlyIdempotent
Ask Gumloop Chew — the model router behind Auto — which model it would use for a given
message, and why. Chew is a router, not a model: router is always gumloop-chew, and the
concrete model it selected is route.model.
This endpoint returns a decision only. It does not run the selected model or its fallbacks. The routing judgement consumes credits and is bounded by the caller's model access.
Omit models to use the deduplicated union of Chew's lane chains, not every model the
caller may use. Restricted candidates can appear with status: "restricted"; they are never
selected or included in fallback_models.
Team scope requires actual team membership, even within the same organization. Personal API keys and OAuth are supported; this is not team-key-only. Read operation.
Inputs: agent, input, models, account, +4 more.
run_evaluationsRun evaluationsADestructive
Grades up to 200 of the agent's finished sessions with its own evaluation configuration. Grading is asynchronous: each accepted session gets a result with status: queued; poll it with GET /agents/{agent_id}/evaluations/{evaluation_id} until it is completed or failed. A new result replaces the previous result for that session.
Sessions are skipped, not rejected, when they are unfinished, incognito, or not owned by this agent (ineligible), or already have a queued or running result (in_flight, with the existing result_id). The caller is charged one credit per queued session. Set dry_run: true to see the cost and skips without queuing anything.
Requires edit access on the agent and a plan with evaluations enabled. Explicit confirmation is required for this exact account operation. Runs can spend credits or trigger downstream actions; never resubmit unknown outcomes automatically.
Inputs: agent_id (required), account, confirm, dry_run, +3 more.
run_organization_evaluationRun evaluation on sessionsADestructive
Grades up to 200 existing sessions with this evaluation. Grading is asynchronous: each accepted session gets a result with status: queued; poll it with GET /evaluations/{evaluation_id}/results/{result_id} until it is completed or failed.
Sessions are skipped, not rejected, when they are not completed sessions of an agent the evaluation covers (ineligible) or already have a queued or running result for this evaluation (in_flight, with the existing result_id). The caller is charged one credit per queued session. Set dry_run: true to see the cost and skips without queuing anything.
Explicit confirmation is required for this exact account operation. Runs can spend credits or trigger downstream actions; never resubmit unknown outcomes automatically.
Inputs: evaluation_id (required), account, confirm, dry_run, +3 more.
search_brainSearch Company BrainADestructive
Run a hybrid (semantic + keyword) search across the knowledge sources indexed in your Company Brain and return the most relevant, ranked snippets with citations.
Results are scoped to what the authenticated user can see: personal sources, plus any team and organization sources shared with them. Requires the Brain feature, which is available on the Pro and Enterprise plans. Each search consumes Gumloop credits. Explicit confirmation is required for this credit-consuming Brain search.
Inputs: limit, query, account, confirm, +3 more.
send_messageSend messageADestructive
Append a user message to an existing session and resume the agent. The session must be idle, completed, failed, or approval_required; sending to a session that is processing or queued returns 409 interaction_not_in_terminal_state. To hand the agent a message while it is still busy, use the message queue instead.
Files uploaded via Upload session file can be attached to the message with attachments.
Sessions waiting on an approval
A session that stopped to ask you something is approval_required, and you have two ways to move it forward:
Answer the ask. Send the pending asks' responses to Resolve approvals. Use this to approve or reject a tool call, or to answer an Ask Question the agent raised. This endpoint rejects
approval_responseswith a400.Send a follow-up instead. Post a normal message here. It is appended to the session transcript and starts a new turn, leaving the pending ask unanswered. Use this when the answer no longer matters — for example to redirect the agent or drop the request it was asking about.
See Human in the Loop for how agents pause for approvals and questions.
Streaming the response
api.gumloop.com only serves the non-streaming response above. To stream agent output as it's produced, send the same request body (with stream: true) to the streaming host instead:
POST https://ws.gumloop.com/api/v1/sessions/{session_id}/messagesThe response is text/event-stream (Server-Sent Events). With the Python SDK, client.sessions.stream_message(session_id, input="...") routes to ws.gumloop.com automatically and yields parsed StreamEvent objects.
If you send stream: true to api.gumloop.com by mistake, the response is a 400 whose body contains the correct streaming host so you can retry against it.
Explicit confirmation is required for this exact account operation. Runs can spend credits or trigger downstream actions; never resubmit unknown outcomes automatically.
Inputs: session_id (required), input, stream, account, +4 more.
send_queued_messageSend queued message nowADestructive
Send a queued message immediately instead of waiting for the agent to finish its current turn. Any in-progress run is aborted, the queued message is appended to the transcript, and the agent starts processing it.
The response is the same envelope as Send message. Queued messages cannot be sent this way on incognito sessions, and a message that is currently being edited must have its edit finished or cancelled first. Explicit confirmation is required for this exact account operation. Runs can spend credits or trigger downstream actions; never resubmit unknown outcomes automatically.
Inputs: session_id (required), queued_message_id (required), account, confirm.
set_organization_evaluation_targetsSet evaluation targetsADestructive
Replaces the full set of targets — who the evaluation grades. Targets expand to agents live: organization covers every agent in the organization, team every agent a team owns, user a member's personal agents, agent one agent. Removing the last target pauses an enabled evaluation; enabled in the response reflects that.
Explicit confirmation is required for this exact account operation. Runs can spend credits or trigger downstream actions; never resubmit unknown outcomes automatically.
Inputs: evaluation_id (required), account, confirm, payload, +2 more.
set_role_credit_limitSet custom role credit limitADestructive
This endpoint sets or clears the monthly credit limit of a custom role. The limit applies to each member of the role individually and takes effect immediately: member allowances are recalculated while preserving credits already used in the current billing cycle. Send "monthly_credit_limit": null to clear the role-level limit so members revert to the organization default. When a user belongs to multiple roles, the highest limit across their roles wins. Requests that do not change the stored value are no-ops. Changes are recorded in the organization audit trail.
Explicit confirmation is required for this exact account operation. Runs can spend credits or trigger downstream actions; never resubmit unknown outcomes automatically.
Inputs: role_id (required), organization_id (required), account, confirm, +4 more.
start_flowStart flow runADestructive
This endpoint is used to trigger a flow run via API Explicit confirmation is required for this exact account operation. Runs can spend credits or trigger downstream actions; never resubmit unknown outcomes automatically.
Inputs: account, confirm, payload, user_id, +3 more.
update_agentUpdate agentADestructive
Update an existing agent. Only fields included in the request body are changed; omitted fields are left untouched.
This endpoint edits document fields only. To attach or detach skills, use PATCH /agents/{agent_id}/skills; to manage MCP servers, use the agent MCP server endpoints.
is_active: false is not a pause switch. It retires the agent: the agent disappears from GET /agents, and both GET and PATCH /agents/{agent_id} return 404 afterwards, so you cannot set it back to true through the API. To stop an agent from running on its own while keeping it fully reachable, disable its triggers instead.
Explicit confirmation is required for this exact account operation. Runs can spend credits or trigger downstream actions; never resubmit unknown outcomes automatically.
Inputs: agent_id (required), name, tools, account, +10 more.
update_agent_skillsAttach or detach agent skillsADestructive
Attach and/or detach skills on an agent using deltas. This is not a replace-list: skills you don't mention are left untouched.
The operation is idempotent. Re-attaching a skill that's already attached (or detaching one that isn't) is reported under
already_attached/already_detachedrather than failing.A skill ID may not appear in both
attachanddetach.Up to 100 unique skill IDs total (
attach+detach) per request.Attaching requires
INVOKEpermission on the skill. Detaching is permissive so stale attachments can always be removed. Explicit confirmation is required for this exact account operation. Runs can spend credits or trigger downstream actions; never resubmit unknown outcomes automatically.
Inputs: agent_id (required), attach, detach, account, +3 more.
update_evaluation_configUpdate evaluation configADestructive
Partially update the evaluation configuration for an agent. Omitted fields keep their current value. Provided list fields (criteria, tags, data_points) replace that list entirely.
Requires Pro tier or above. Explicit confirmation is required for this exact account operation. Runs can spend credits or trigger downstream actions; never resubmit unknown outcomes automatically.
Inputs: agent_id (required), tags, account, confirm, +8 more.
update_organization_evaluationUpdate evaluationADestructive
Partial update. Only the fields you send change. config is merged field by field; a list you send (criteria, tags, data_points) replaces that list wholesale. description: null clears the description.
Setting enabled: true requires at least one criterion, tag, or data point (400 organization_evaluation_empty_rubric) and at least one covered agent (400 organization_evaluation_no_targets). Emptying the rubric of an enabled evaluation pauses it.
Explicit confirmation is required for this exact account operation. Runs can spend credits or trigger downstream actions; never resubmit unknown outcomes automatically.
Inputs: evaluation_id (required), account, confirm.
update_queued_messageUpdate queued messageADestructive
Replace the content of a message that is still waiting in the session's queue. Explicit confirmation is required for this exact account operation. Runs can spend credits or trigger downstream actions; never resubmit unknown outcomes automatically.
Inputs: session_id (required), queued_message_id (required), input, account, +3 more.
update_skillUpdate skillADestructive
Replace a skill's files with a new upload. Reparses SKILL.md to update the skill's name, description, and metadata, and creates a new version. Maximum upload size is 10 MB.
Explicit confirmation is required for this exact account operation. Runs can spend credits or trigger downstream actions; never resubmit unknown outcomes automatically.
Inputs: skill_id (required), files, account, confirm, +2 more.
upload_brain_filesUpload filesADestructive
Upload up to 25 files as multipart/form-data parts named files. Accepted types are PDF, Word, PowerPoint, Excel, and text formats (.txt, .md, .html, .csv, .rtf), each up to 25 MB.
Indexing starts on its own after the upload: an active source indexes and bills immediately, a draft source runs a credit estimate instead (see Retrieve estimate). Poll List files until each file's status is indexed.
Files the upload policy refuses (unsupported type, too large, empty) are returned in rejected with a 201; the request is a 400 no_files_accepted only when every file was refused.
Explicit confirmation is required for this exact account operation. Runs can spend credits or trigger downstream actions; never resubmit unknown outcomes automatically.
Inputs: source_id (required), files, account, confirm, +2 more.
upload_fileUpload fileBDestructive
Upload file Explicit confirmation is required for this exact account operation. Runs can spend credits or trigger downstream actions; never resubmit unknown outcomes automatically.
Inputs: account, confirm, payload, user_id, +5 more.
upload_filesUpload multiple filesADestructive
Upload multiple files Explicit confirmation is required for this exact account operation. Runs can spend credits or trigger downstream actions; never resubmit unknown outcomes automatically.
Inputs: files, account, confirm, payload, +3 more.
upload_session_fileUpload session fileADestructive
Upload a file into a session's input namespace so it can be attached to a message. The response returns the stored path — pass it as file_name in the attachments array when sending a message on the same session.
Files are base64 encoded in the request body and limited to 200MB (decoded). Uploaded files are scoped to the session they were uploaded to and cannot be attached to messages on other sessions. Explicit confirmation is required for this exact account operation. Runs can spend credits or trigger downstream actions; never resubmit unknown outcomes automatically.
Inputs: session_id (required), account, confirm, payload, +4 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 92 tools
Many tools have overlapping or indistinguishable purposes across the 92-tool surface, such as list_flows vs list_workbooks vs get_run_history, or upload_file vs upload_files vs upload_session_file vs upload_brain_files. with such a large flat set, boundaries between agent, session, flow, evaluation, brain, and skill tools are unclear without deep cross-referencing.
Most tools follow a consistent verb_noun snake_case pattern (list_agents, create_skill, delete_brain_source), with only minor deviations like route_model and call_mcp_tools. The convention is largely predictable.
92 tools is excessive for a single MCP server and likely buries the core operations. Many are thin variants (get_evaluation_metrics vs get_organization_evaluation_metrics) that could be consolidated.
Coverage is broad and deep across flows, agents, sessions, evaluations, brain, skills, and MCP, with both read and write operations. minor CRUD gaps exist but the surface is mostly complete.
Maintenance
Related MCP Connectors
Your org's AI agents, tasks, runs, search, and brain files as MCP tools and resources.
Build, test and publish agentic workflows from your AI client: approve steps, read tables, see runs.
One place to build, share, and govern the skills and tools your AI agents use at work.
Design, build and run teams of AI agents with checked handoffs between them.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceProvides 70 tools to interact with the Brainbase API, enabling management of workers, chat/voice deployments, flows, resources, and more via natural language.1MIT
- AlicenseNot gradedqualityBmaintenanceEnables operators to manage Paperclip AI agent orchestration through 95 tools covering issues, agents, goals, projects, approvals, costs, routines, decisions, and pipelines.MIT
- AlicenseAqualityCmaintenanceEnables AI agents and assistants to work with a Databricks workspace — SQL, clusters and warehouses, notebooks, Jobs, Lakeflow pipelines, Unity Catalog, Volumes, dashboards, Genie, model serving, Vector Search, Lakebase and Apps — under a safety-first model with read/write/destructive/security classification, confirmation steps for dangerous changes, production resource protection, and a fully read-only mode. Every call is checked against the official Databricks SDK, returns typed schemas and redacted secrets, and unsupported features report an explicit error rather than faking results.45Apache 2.0

OutcomeCI MCP Serverofficial
AlicenseNot gradedqualityCmaintenanceEnables AI assistants to create, validate, and manage agent-powered workflows across team tools, with tools for inspecting schemas, configuring triggers, and reviewing runs and logs. It provides authorized remote access through OAuth without local installation or shared API keys.1MIT