Skip to main content
Glama

Gumloop MCP Server & CLI

npm CI License YouTube X LinkedIn

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 --agent

MCP server, for your AI app

codex mcp add gumloop -- npx -y @thenavidm/gumloop-mcp-cli@latest

Configure 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

What you can ask it

2

Quick install

Quick install

3

Set up Gumloop access

Set up Gumloop access

4

Connect your client

Connect your client

5

Check it works

Check it works

6

Output, flags and exit codes

Output, flags and exit codes

7

MCP or CLI and token cost

MCP or CLI and token cost

8

Every tool and argument

Every tool and argument

9

Flows, sessions and account workflows

Flows, sessions and account workflows

10

Jobs, pagination and private files

Jobs, pagination and private files

11

Several private accounts

Several private accounts

12

Writing safely

Writing safely

13

How it works

How it works

14

Your data

Your data

15

Environment variables

Environment variables

16

Updates and removal

Updates and removal

17

Troubleshooting

Troubleshooting

18

API coverage and comparisons

API coverage and comparisons

19

Versions

Versions

20

FAQ

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 tools

Node 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 list

3. Set up Gumloop access

Private credentials and permissions

  1. Open the intended account's Connectors settings. Select Gumloop API Key and create the personal or team key needed for your task.

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

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

  4. Run gumloop-cli doctor, then doctor --network. The network check reads accessible agent metadata without printing account content.

  5. 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 --agent

Discovery, 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 agents

Flag

What it does

--json

JSON output

--compact

Single-line JSON

--agent

Compact JSON and no prompts; never confirms a write

--select a,b.c

Keep selected fields; dotted paths descend and arrays are traversed

--confirm

Confirm the requested flow, session, paid search or account operation

--no-input, --no-color, --yes

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

SKILL.md, read once

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

start_flow

POST /api/v1/start_pipeline

Confirm exact operation

kill_flow

POST /api/v1/kill_pipeline

Confirm exact operation

get_run_details

GET /api/v1/get_pl_run

Read

list_workbooks

GET /api/v1/list_workbooks

Read

list_flows

GET /api/v1/list_saved_items

Read

get_input_schema

GET /api/v1/get_inputs

Read

get_run_history

GET /api/v1/get_plrun_saved_item_map

Read

download_file

POST /api/v1/download_file

Read

download_files

POST /api/v1/download_files

Read

upload_file

POST /api/v1/upload_file

Confirm exact operation

upload_files

POST /api/v1/upload_files

Confirm exact operation

get_organization_audit_logs

GET /api/v1/get_audit_logs

Read

manage_project_users

POST /api/v1/manage_workspace_users

Confirm exact operation

manage_permission_group_users

POST /api/v1/manage_permission_group_users

Confirm exact operation

list_role_credit_limits

GET /api/v1/organizations/{organization_id}/roles/credit-limits

Read

get_role_credit_limit

GET /api/v1/organizations/{organization_id}/roles/{role_id}/credit-limit

Read

set_role_credit_limit

PUT /api/v1/organizations/{organization_id}/roles/{role_id}/credit-limit

Confirm exact operation

export_data

POST /api/v1/export_data

Confirm exact operation

get_export_status

GET /api/v1/export_status

Read

list_agents

GET /api/v1/agents

Read

create_agent

POST /api/v1/agents

Confirm exact operation

retrieve_agent

GET /api/v1/agents/{agent_id}

Read

update_agent

PATCH /api/v1/agents/{agent_id}

Confirm exact operation

create_chat_completion

POST /api/v1/chat/completions

Confirm exact operation

list_models

GET /api/v1/models

Read

route_model

POST /api/v1/models/route

Read

list_agent_versions

GET /api/v1/agents/{agent_id}/versions

Read

retrieve_agent_version

GET /api/v1/agents/{agent_id}/versions/{version_id}

Read

update_agent_skills

PATCH /api/v1/agents/{agent_id}/skills

Confirm exact operation

list_agent_mcp_servers

GET /api/v1/agents/{agent_id}/mcp-servers

Read

attach_agent_mcp_server

PUT /api/v1/agents/{agent_id}/mcp-servers/{server_id}

Confirm exact operation

detach_agent_mcp_server

DELETE /api/v1/agents/{agent_id}/mcp-servers/{server_id}

Confirm exact operation

list_sessions

GET /api/v1/agents/{agent_id}/sessions

Read

create_session

POST /api/v1/agents/{agent_id}/sessions

Confirm exact operation

retrieve_session

GET /api/v1/sessions/{session_id}

Read

rename_session

PATCH /api/v1/sessions/{session_id}

Confirm exact operation

send_message

POST /api/v1/sessions/{session_id}/messages

Confirm exact operation

cancel_session

POST /api/v1/sessions/{session_id}/cancel

Confirm exact operation

upload_session_file

POST /api/v1/sessions/{session_id}/files

Confirm exact operation

resolve_session_approvals

POST /api/v1/sessions/{session_id}/approvals

Confirm exact operation

list_queued_messages

GET /api/v1/sessions/{session_id}/queue

Read

queue_session_message

POST /api/v1/sessions/{session_id}/queue

Confirm exact operation

update_queued_message

PATCH /api/v1/sessions/{session_id}/queue/{queued_message_id}

Confirm exact operation

delete_queued_message

DELETE /api/v1/sessions/{session_id}/queue/{queued_message_id}

Confirm exact operation

send_queued_message

POST /api/v1/sessions/{session_id}/queue/{queued_message_id}/send

Confirm exact operation

list_mcp_servers

GET /api/v1/mcp/servers

Read

retrieve_mcp_server

GET /api/v1/mcp/servers/{server_id}

Read

list_mcp_server_tools

GET /api/v1/mcp/servers/{server_id}/tools

Read

list_mcp_server_resources

GET /api/v1/mcp/servers/{server_id}/resources

Read

read_mcp_server_resource

GET /api/v1/mcp/servers/{server_id}/resources/read

Read

list_mcp_server_prompts

GET /api/v1/mcp/servers/{server_id}/prompts

Read

get_mcp_server_prompt

POST /api/v1/mcp/servers/{server_id}/prompts/get

Read

call_mcp_tools

POST /api/v1/mcp/tools/call

Confirm exact operation

search_brain

POST /api/v1/brain/search

Confirm exact operation

list_brain_sources

GET /api/v1/brain/sources

Read

create_brain_source

POST /api/v1/brain/sources

Confirm exact operation

get_brain_source

GET /api/v1/brain/sources/{source_id}

Read

delete_brain_source

DELETE /api/v1/brain/sources/{source_id}

Confirm exact operation

list_brain_files

GET /api/v1/brain/sources/{source_id}/files

Read

upload_brain_files

POST /api/v1/brain/sources/{source_id}/files

Confirm exact operation

delete_brain_file

DELETE /api/v1/brain/sources/{source_id}/files/{file_id}

Confirm exact operation

get_brain_source_estimate

GET /api/v1/brain/sources/{source_id}/estimate

Read

approve_brain_source

POST /api/v1/brain/sources/{source_id}/approve

Confirm exact operation

list_skills

GET /api/v1/skills

Read

create_skill

POST /api/v1/skills

Confirm exact operation

update_skill

PATCH /api/v1/skills/{skill_id}

Confirm exact operation

delete_skill

DELETE /api/v1/skills/{skill_id}

Confirm exact operation

download_skill_file

GET /api/v1/skills/{skill_id}/download

Read

list_artifacts

GET /api/v1/agents/{agent_id}/artifacts

Read

download_artifact_file

GET /api/v1/artifacts/{artifact_id}/download

Read

list_browser_profiles

GET /api/v1/browser-profiles

Read

import_browser_profile_cookies

POST /api/v1/browser-profiles/{profile_id}/cookies

Confirm exact operation

list_teams

GET /api/v1/teams

Read

list_evaluations

GET /api/v1/agents/{agent_id}/evaluations

Read

run_evaluations

POST /api/v1/agents/{agent_id}/evaluations/run

Confirm exact operation

get_evaluation_metrics

GET /api/v1/agents/{agent_id}/evaluations/metrics

Read

retrieve_evaluation

GET /api/v1/agents/{agent_id}/evaluations/{evaluation_id}

Read

get_evaluation_config

GET /api/v1/agents/{agent_id}/evaluation-config

Read

update_evaluation_config

PATCH /api/v1/agents/{agent_id}/evaluation-config

Confirm exact operation

list_organizations

GET /api/v1/organizations

Read

get_evaluation_options

GET /api/v1/evaluation-options

Read

list_organization_evaluations

GET /api/v1/evaluations

Read

create_organization_evaluation

POST /api/v1/evaluations

Confirm exact operation

get_organization_evaluation

GET /api/v1/evaluations/{evaluation_id}

Read

update_organization_evaluation

PATCH /api/v1/evaluations/{evaluation_id}

Confirm exact operation

delete_organization_evaluation

DELETE /api/v1/evaluations/{evaluation_id}

Confirm exact operation

set_organization_evaluation_targets

PUT /api/v1/evaluations/{evaluation_id}/targets

Confirm exact operation

run_organization_evaluation

POST /api/v1/evaluations/{evaluation_id}/run

Confirm exact operation

list_organization_evaluation_results

GET /api/v1/evaluations/{evaluation_id}/results

Read

get_organization_evaluation_result

GET /api/v1/evaluations/{evaluation_id}/results/{result_id}

Read

get_organization_evaluation_metrics

GET /api/v1/evaluations/{evaluation_id}/metrics

Read

list_accounts

Local, no network

Read

start_flow

gumloop-cli start-flow

Argument

Required

Type

Details

user_id

No; body and guard rules apply

string

The id for the user initiating the flow.

project_id

No; body and guard rules apply

string

(Optional) The id of the project within which the flow is executed.

saved_item_id

No; body and guard rules apply

string

The id for the saved flow.

account

No; body and guard rules apply

string

Named private Gumloop account; selects private credentials and user/team identity.

confirm

No; body and guard rules apply

boolean

Set true only when the user asked for exactly this action.

payload

No; body and guard rules apply

object

Complete JSON request body instead of body flags. Preserves current endpoint fields and values.

payload_file

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: 1.

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

run_id

No; body and guard rules apply

string

The ID of the pipeline run to kill.

user_id

No; body and guard rules apply

string

The user ID. Required if project_id is not provided.

project_id

No; body and guard rules apply

string

The project ID. Required if user_id is not provided.

account

No; body and guard rules apply

string

Named private Gumloop account; selects private credentials and user/team identity.

confirm

No; body and guard rules apply

boolean

Set true only when the user asked for exactly this action.

payload

No; body and guard rules apply

object

Complete JSON request body instead of body flags. Preserves current endpoint fields and values.

payload_file

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: 1.

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

run_id

Yes

string

ID of the flow run to retrieve

user_id

No; body and guard rules apply

string

The id for the user initiating the flow. Required if project_id is not provided.

project_id

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.

account

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

user_id

No; body and guard rules apply

string

The user ID for which to list workbooks. Required if project_id is not provided.

project_id

No; body and guard rules apply

string

The project ID for which to list workbooks. Required if user_id is not provided.

account

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

user_id

No; body and guard rules apply

string

The user ID to for which to list items. Required if project_id is not provided.

project_id

No; body and guard rules apply

string

The project ID for which to list items. Required if user_id is not provided.

account

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

saved_item_id

Yes

string

The ID of the saved item for which to retrieve input schemas.

user_id

No; body and guard rules apply

string

User ID that created the flow. Required if project_id is not provided.

project_id

No; body and guard rules apply

string

Project ID that the flow is under. Required if user_id is not provided.

account

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

workbook_id

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.

saved_item_id

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.

user_id

No; body and guard rules apply

string

The user ID. Required if project_id is not provided.

project_id

No; body and guard rules apply

string

The project ID. Required if user_id is not provided.

account

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

file_name

No; body and guard rules apply

string

The name of the file to download.

run_id

No; body and guard rules apply

string

The ID of the flow run associated with the file.

saved_item_id

No; body and guard rules apply

string

The saved item ID associated with the file.

user_id

No; body and guard rules apply

string

Optional. The user ID associated with the flow run.

project_id

No; body and guard rules apply

string

Optional. The project ID associated with the flow run.

account

No; body and guard rules apply

string

Named private Gumloop account; selects private credentials and user/team identity.

payload

No; body and guard rules apply

object

Complete JSON request body instead of body flags. Preserves current endpoint fields and values.

payload_file

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: 1.

output_file

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: 1.

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

file_names

No; body and guard rules apply

array

An array of file names to download. Items: string.

run_id

No; body and guard rules apply

string

The ID of the flow run associated with the files.

user_id

No; body and guard rules apply

string

The user ID associated with the files. Required if project_id is not provided.

project_id

No; body and guard rules apply

string

The project ID associated with the files. Required if user_id is not provided.

saved_item_id

No; body and guard rules apply

string

Optional. The saved item ID associated with the files.

account

No; body and guard rules apply

string

Named private Gumloop account; selects private credentials and user/team identity.

payload

No; body and guard rules apply

object

Complete JSON request body instead of body flags. Preserves current endpoint fields and values.

payload_file

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: 1.

output_file

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: 1.

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

file_name

No; body and guard rules apply

string

The name of the file to be uploaded.

file_content

No; body and guard rules apply

string

Base64 encoded content of the file. format: byte.

user_id

No; body and guard rules apply

string

The user ID associated with the file. Required if project_id is not provided.

project_id

No; body and guard rules apply

string

The project ID associated with the file. Required if user_id is not provided.

account

No; body and guard rules apply

string

Named private Gumloop account; selects private credentials and user/team identity.

confirm

No; body and guard rules apply

boolean

Set true only when the user asked for exactly this action.

payload

No; body and guard rules apply

object

Complete JSON request body instead of body flags. Preserves current endpoint fields and values.

payload_file

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: 1.

file_path

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: 1.

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

files

No; body and guard rules apply

array

See the full input schema. Items: object.

user_id

No; body and guard rules apply

string

The user ID associated with the files. Required if project_id is not provided.

project_id

No; body and guard rules apply

string

The project ID associated with the files. Required if user_id is not provided.

account

No; body and guard rules apply

string

Named private Gumloop account; selects private credentials and user/team identity.

confirm

No; body and guard rules apply

boolean

Set true only when the user asked for exactly this action.

payload

No; body and guard rules apply

object

Complete JSON request body instead of body flags. Preserves current endpoint fields and values.

payload_file

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: 1.

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

organization_id

Yes

string

The ID of the organization to retrieve audit logs for.

user_id

No; body and guard rules apply

string

Your user id -- you must be an organization admin to retrieve organization logs.

start_time

Yes

string

Start timestamp for log filtering (ISO format). format: date-time.

end_time

Yes

string

End timestamp for log filtering (ISO format). format: date-time.

event_types

No; body and guard rules apply

string

Comma-separated list of event types to filter by (e.g. user_sign_in,credential_retrieval). The singular event_type param accepts a single value.

user_ids

No; body and guard rules apply

string

Comma-separated list of user IDs whose events should be returned.

ip_addresses

No; body and guard rules apply

string

Comma-separated list of source IP addresses to filter by. The singular ip_address param accepts a single value.

workspace_ids

No; body and guard rules apply

string

Comma-separated list of workspace (team) IDs to filter by. The singular workspace_id param accepts a single value.

entity_ids

No; body and guard rules apply

string

Comma-separated list of entity IDs (agents, workbooks, files) to filter by. The singular entity_id param accepts a single value.

page

No; body and guard rules apply

integer

Page number for pagination. default: 1.

page_size

No; body and guard rules apply

integer

Number of records per page. default: 50.

account

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

organization_id

No; body and guard rules apply

string

The ID of the organization that the workspace belongs to.

user_id

No; body and guard rules apply

string

Your user id -- you must be an organization admin to manage workspace users.

workspace_id

No; body and guard rules apply

string

The ID of the workspace to manage users for.

action

No; body and guard rules apply

string

The action to perform - either 'add' or 'remove' a user. Values: add, remove.

user_email

No; body and guard rules apply

string

The email address of the target user to add or remove.

is_admin

No; body and guard rules apply

boolean

When adding a user, specify whether they should have admin privileges (default is false).

account

No; body and guard rules apply

string

Named private Gumloop account; selects private credentials and user/team identity.

confirm

No; body and guard rules apply

boolean

Set true only when the user asked for exactly this action.

payload

No; body and guard rules apply

object

Complete JSON request body instead of body flags. Preserves current endpoint fields and values.

payload_file

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: 1.

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

organization_id

No; body and guard rules apply

string

The ID of the organization that the custom role belongs to.

user_id

No; body and guard rules apply

string

Your user id -- you must be an organization admin to manage custom role users.

group_id

No; body and guard rules apply

string

The ID of the custom role to manage users for.

action

No; body and guard rules apply

string

The action to perform - either 'add' or 'remove' a user. Values: add, remove.

user_email

No; body and guard rules apply

string

The email address of the target user to add or remove.

account

No; body and guard rules apply

string

Named private Gumloop account; selects private credentials and user/team identity.

confirm

No; body and guard rules apply

boolean

Set true only when the user asked for exactly this action.

payload

No; body and guard rules apply

object

Complete JSON request body instead of body flags. Preserves current endpoint fields and values.

payload_file

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: 1.

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

organization_id

Yes

string

The ID of the organization. minLength: 1.

user_id

No; body and guard rules apply

string

Your user id -- you must be an organization admin to manage custom role credit limits.

page_size

No; body and guard rules apply

integer

Number of roles per page. maximum: 100. default: 20.

cursor

No; body and guard rules apply

string

Opaque cursor from a previous response's next_cursor; omit for the first page.

account

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

organization_id

Yes

string

The ID of the organization the custom role belongs to. minLength: 1.

role_id

Yes

string

The ID of the custom role (the same ID used as group_id by the Manage custom role users endpoint). minLength: 1.

user_id

No; body and guard rules apply

string

Your user id -- you must be an organization admin to manage custom role credit limits.

account

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

organization_id

Yes

string

The ID of the organization the custom role belongs to. minLength: 1.

role_id

Yes

string

The ID of the custom role (the same ID used as group_id by the Manage custom role users endpoint). minLength: 1.

monthly_credit_limit

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: 0. maximum: 1000000000.

user_id

No; body and guard rules apply

string

Your user id -- you must be an organization admin to manage custom role credit limits.

account

No; body and guard rules apply

string

Named private Gumloop account; selects private credentials and user/team identity.

confirm

No; body and guard rules apply

boolean

Set true only when the user asked for exactly this action.

payload

No; body and guard rules apply

object

Complete JSON request body instead of body flags. Preserves current endpoint fields and values.

payload_file

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: 1.

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

user_id

No; body and guard rules apply

string

The ID of the user requesting the export.

data_type

No; body and guard rules apply

string

The type of data to export. Use "workflows" to export workflow run data, "agents" to export agent configuration data, "agent_interactions" to export agent interaction data, "credit_logs" to export credit transaction history, "interaction_evaluations" to export completed chat evaluations, or "gumstack" to export Gumstack tool call activity. Defaults to "workflows". Audit-log exports are available in the Gumloop app only, not through this endpoint. Values: workflows, agents, agent_interactions, credit_logs, interaction_evaluations, gumstack. default: workflows.

category_filter

No; body and guard rules apply

string

Only applicable when data_type is "credit_logs". Optional filter to export only credit logs matching a specific category (e.g., "PIPELINE_RUN", "AGENT_RUN", "CUSTOM_NODE_RD", "EXTERNAL_GUMCP_CALL"). When omitted, all categories are included.

export_level

No; body and guard rules apply

string

The scope of the export. Use "organization" to export across the entire organization, or "workspace" to export from a single workspace (requires exactly one ID in workspace_ids). Defaults to "organization". Not applicable when data_type is "credit_logs". Values: workspace, organization. default: organization.

export_fields

No; body and guard rules apply

array

Array of fields to include in the export. The available fields depend on the data_type. Workflow fields (when data_type is "workflows"): - workbook_id - The workbook identifier - workbook_name - The workbook name - workbook_created_ts - Workbook creation timestamp - user_id - The user identifier - user_email - The user's email address - workspace_id - The workspace identifier - workspace_name - The workspace name - run_id - The flow run identifier - credit_cost - Credits consumed by the run - pl_run_created_ts - Flow run creation timestamp - pl_run_finished_ts - Flow run completion timestamp - pipeline - The full pipeline configuration (JSON) Agent fields (when data_type is "agents"): - agent_id - The agent identifier - agent_name - The agent name - agent_description - The agent description - agent_model - The model used by the agent - agent_system_prompt - The agent's system prompt - agent_created_ts - Agent creation timestamp - agent_tools - Tools configured for the agent (JSON) - agent_metadata - Additional agent metadata (JSON) - agent_evaluations_enabled - Whether the agent's own Evaluations are turned on (true/false) - creator_email - Email of the user who created the agent - workspace_id - The workspace identifier - workspace_name - The workspace name - folder_id - The identifier of the folder containing the agent (empty when the agent is not in a folder) - folder_name - The name of the folder containing the agent (empty when the agent is not in a folder) Agent interaction fields (when data_type is "agent_interactions"): - interaction_id - Unique identifier for the chat session - agent_id - The agent identifier - agent_name - The agent name - interaction_type - Type of interaction (e.g., chat, slack, api, triggered) - interaction_name - Display name of the chat session - trigger_type - For triggered interactions, the specific trigger type (e.g., time_based, polling_new_record_salesforce). Null for non-triggered interactions. - interaction_created_ts - Chat session creation timestamp - user_email - Email of the user who initiated the chat - credit_cost - Total credits consumed (LLM + tool + flow) - llm_credit_cost - Credits consumed by LLM calls only - tool_credit_cost - Credits consumed by tool calls - flow_credit_cost - Credits consumed by pipeline runs - message_count - Number of messages in the conversation - workspace_id - The workspace identifier - workspace_name - The workspace name Interaction evaluation fields (when data_type is "interaction_evaluations"): - evaluation_id - Unique identifier for the evaluation row - interaction_id - The chat session that was evaluated (one chat can have several evaluation rows) - agent_id - The identifier of the agent that was evaluated - organization_evaluation_id - The organization-level evaluation this row belongs to (empty for agent-level rubrics) - evaluation_created_ts - When the evaluation reached its final state - status - The evaluation's state - grade - The grade the evaluation produced - call_outcome - The outcome the evaluation recorded for the conversation - sentiment - The sentiment the evaluation recorded - error_code - Error code when the evaluation could not complete - summary - The evaluation's written summary - evaluation_model - The model that ran the evaluation - credit_cost - Credits consumed by the evaluation - user_email - Email of the user whose chat was evaluated Credit log fields (when data_type is "credit_logs"): - user_email - Email of the user associated with the credit log entry - permission_group_id - Custom role ID(s) the user belongs to (semicolon-separated if multiple) (disabled by default) - permission_group_name - Custom role name(s) the user belongs to (semicolon-separated if multiple) (disabled by default) - timestamp - When the credit transaction occurred - category - The category of the credit log (e.g., PIPELINE_RUN, AGENT_RUN) - type - The specific type of credit charge - name - Display name of the credit log entry - amount - Number of credits charged or adjusted - balance - Credit balance after the transaction - log_id - Unique identifier for the credit log entry - correlation_id - Join key to the related run or interaction (disabled by default) - balance_scope - Whether the balance is organization- or user-scoped (disabled by default) - project_id - The project identifier (disabled by default) Not all combinations of selected fields are guaranteed to produce data for every row. Items: string.

start_date

No; body and guard rules apply

string

Start date for the export in ISO 8601 format (e.g., 2025-01-01T00:00:00Z). format: date-time.

end_date

No; body and guard rules apply

string

End date for the export in ISO 8601 format (e.g., 2025-12-31T23:59:59Z). format: date-time.

include_all_workspaces

No; body and guard rules apply

boolean

Whether to include all workspaces in the organization. When true, also sets include_personal_workspaces to true. Not applicable when data_type is "credit_logs". default: False.

include_personal_workspaces

No; body and guard rules apply

boolean

Whether to include personal workspaces in the export. Ignored if include_all_workspaces is true. Not applicable when data_type is "credit_logs". default: False.

workspace_ids

No; body and guard rules apply

array

An optional array of workspace IDs to include in the export. When export_level is "workspace", exactly one workspace ID is required. Ignored if include_all_workspaces is true. Not applicable when data_type is "credit_logs". Items: string.

entity_ids

No; body and guard rules apply

array

An optional array of specific entity IDs to filter the export. For workflow exports (data_type: "workflows"), these are workbook IDs. For agent exports (data_type: "agents") and agent interaction exports (data_type: "agent_interactions"), these are agent IDs. When provided, only data for the specified entities will be included. Not applicable when data_type is "credit_logs". Items: string.

account

No; body and guard rules apply

string

Named private Gumloop account; selects private credentials and user/team identity.

confirm

No; body and guard rules apply

boolean

Set true only when the user asked for exactly this action.

payload

No; body and guard rules apply

object

Complete JSON request body instead of body flags. Preserves current endpoint fields and values.

payload_file

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: 1.

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

user_id

No; body and guard rules apply

string

The ID of the user requesting the export status.

data_export_id

Yes

string

The unique identifier of the data export job to check (returned by the Export data endpoint).

download

No; body and guard rules apply

boolean

Set to true to download the export file directly when the export is completed. When true and the export state is COMPLETED, the response will be a CSV file download instead of JSON. default: False.

account

No; body and guard rules apply

string

Named private Gumloop account; selects private credentials and user/team identity.

output_file

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: 1.

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

team_id

No; body and guard rules apply

string

Scope the listing to a single team. When omitted, returns agents owned by the authenticated user.

search

No; body and guard rules apply

string

Case-insensitive substring match against the agent name.

creator

No; body and guard rules apply

string

Filter to agents created by this user ID.

has_triggers

No; body and guard rules apply

boolean

When true, only returns agents that have at least one active trigger configured.

tool

No; body and guard rules apply

string

Filter to agents that use the specified MCP server as a tool.

flow

No; body and guard rules apply

string

Filter to agents that use the specified saved flow as a tool.

sort_order

No; body and guard rules apply

string

Sort order for the listing. Defaults to newest first. Values: newest, oldest, name_asc, name_desc. default: newest.

include_last_used

No; body and guard rules apply

boolean

When true, populates last_used_at on each agent with the timestamp of its most recent session.

include_last_updated

No; body and guard rules apply

boolean

When true, populates last_updated_at on each agent with the timestamp of its most recent configuration change.

page_size

No; body and guard rules apply

integer

Number of agents per page. Sending page_size or cursor opts into cursor pagination; requests that send neither return the full list. minimum: 1. maximum: 100. default: 20.

cursor

No; body and guard rules apply

string

Opaque cursor from a previous response's next_cursor. Pass it to fetch the next page.

account

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

name

No; body and guard rules apply

string

Display name for the agent.

model_name

No; body and guard rules apply

string

ID of the LLM the agent runs on. Use GET /models to discover valid values.

description

No; body and guard rules apply

string/null

See the full input schema.

system_prompt

No; body and guard rules apply

string/null

See the full input schema.

tools

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: []. Items: object.

resources

No; body and guard rules apply

array

Resources attached to the agent. default: []. Items: object.

skill_ids

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 INVOKE on each skill. After creation, manage skills with PATCH /agents/{agent_id}/skills. Items: string.

metadata

No; body and guard rules apply

object/null

Arbitrary key/value metadata stored on the agent.

folder_id

No; body and guard rules apply

string/null

ID of the folder to place the agent in.

is_active

No; body and guard rules apply

boolean

Whether the agent is active. Defaults to true. Setting this to false retires the agent: it disappears from GET /agents, and GET/PATCH /agents/{agent_id} return 404, so it cannot be reactivated through the API. This is not a pause switch — to stop an agent from running while keeping it reachable, disable its triggers instead. default: True.

agent_id

No; body and guard rules apply

string/null

Optional caller-supplied agent ID. When omitted, the server generates one.

team_id

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.

account

No; body and guard rules apply

string

Named private Gumloop account; selects private credentials and user/team identity.

confirm

No; body and guard rules apply

boolean

Set true only when the user asked for exactly this action.

payload

No; body and guard rules apply

object

Complete JSON request body instead of body flags. Preserves current endpoint fields and values.

payload_file

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: 1.

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

agent_id

Yes

string

ID of the agent to retrieve. Also accepts the reserved aliases gumball and analytics. minLength: 1.

account

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

agent_id

Yes

string

ID of the agent to update. Also accepts the reserved aliases gumball and analytics. minLength: 1.

name

No; body and guard rules apply

string/null

See the full input schema.

model_name

No; body and guard rules apply

string/null

ID of the LLM the agent runs on. Use GET /models to discover valid values.

description

No; body and guard rules apply

string/null

See the full input schema.

system_prompt

No; body and guard rules apply

string/null

See the full input schema.

tools

No; body and guard rules apply

array/null

When provided, replaces the agent's tool list. Items: object.

resources

No; body and guard rules apply

array/null

When provided, replaces the agent's resource list. Items: object.

metadata

No; body and guard rules apply

object/null

See the full input schema.

is_active

No; body and guard rules apply

boolean/null

Setting this to false retires the agent: it disappears from GET /agents, and GET/PATCH /agents/{agent_id} return 404, so it cannot be reactivated through the API. This is not a pause switch — to stop an agent from running while keeping it reachable, disable its triggers instead.

team_id

No; body and guard rules apply

string/null

When provided, transfers ownership of the agent to this team.

account

No; body and guard rules apply

string

Named private Gumloop account; selects private credentials and user/team identity.

confirm

No; body and guard rules apply

boolean

Set true only when the user asked for exactly this action.

payload

No; body and guard rules apply

object

Complete JSON request body instead of body flags. Preserves current endpoint fields and values.

payload_file

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: 1.

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

model

No; body and guard rules apply

string

Model slug. Use the id from GET /models or one of Gumloop's preset routes.

messages

No; body and guard rules apply

array

Conversation history. Roles system, developer, user, assistant, and tool. User messages accept multipart content with text and image_url parts. Assistant messages can carry tool_calls; answer each one with a tool message whose tool_call_id matches the call's id. Items: object.

stream

No; body and guard rules apply

boolean

Only non-streaming JSON is supported. Streaming requests are refused before fetch.

temperature

No; body and guard rules apply

number

Sampling temperature.

max_completion_tokens

No; body and guard rules apply

integer

Cap on completion tokens. Replaces the deprecated max_tokens field.

modalities

No; body and guard rules apply

array

Output modalities. Include "image" to route to an image-generation model. Items: string.

image_config

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 modalities: ["image"] or image_config (or both); chat models ignore this field.

response_format

No; body and guard rules apply

object

Constrain the response. {type: "json_object"} returns a JSON object; {type: "json_schema", json_schema: {name, strict, schema}} returns JSON matching the supplied schema.

tools

No; body and guard rules apply

array

OpenAI-shape tool definitions ({type: "function", function: {name, description, parameters}}). Pass tool_choice to constrain selection.

tool_choice

No; body and guard rules apply

Union

"auto" lets the model choose and is the default when tools are sent. "none" disables tool calls, "required" forces a tool call, and {"type": "function", "function": {"name": "..."}} forces a specific tool.

provider

No; body and guard rules apply

object

OpenRouter provider routing config. Caller fields like sort and order are honored; ZDR/data_collection policy is server-enforced.

account

No; body and guard rules apply

string

Named private Gumloop account; selects private credentials and user/team identity.

confirm

No; body and guard rules apply

boolean

Set true only when the user asked for exactly this action.

payload

No; body and guard rules apply

object

Complete JSON request body instead of body flags. Preserves current endpoint fields and values.

payload_file

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: 1.

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

team_id

No; body and guard rules apply

string

Scope model availability to a specific team. When omitted, uses the authenticated user's default organization.

account

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

input

No; body and guard rules apply

Union

The message to route. message is accepted as an alias. A string or an array of {type: text, text: ...} parts.

models

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: 1. maxItems: 50. Items: string.

history

No; body and guard rules apply

array

Prior turns, oldest first, for context. maxItems: 20. Items: object.

agent

No; body and guard rules apply

object

Optional context about the agent the message is for. Sharper context produces a sharper route.

team_id

No; body and guard rules apply

string

Scope model availability and credit attribution to a team the caller belongs to.

account

No; body and guard rules apply

string

Named private Gumloop account; selects private credentials and user/team identity.

payload

No; body and guard rules apply

object

Complete JSON request body instead of body flags. Preserves current endpoint fields and values.

payload_file

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: 1.

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

agent_id

Yes

string

ID of the agent whose versions to list. Also accepts the reserved aliases gumball and analytics. minLength: 1.

page_size

No; body and guard rules apply

integer

Number of versions to return per page. Clamped to 1–100. minimum: 1. maximum: 100. default: 20.

cursor

No; body and guard rules apply

string

Opaque pagination cursor returned by a prior call as next_cursor.

account

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

agent_id

Yes

string

ID of the agent the version belongs to. Also accepts the reserved aliases gumball and analytics. minLength: 1.

version_id

Yes

string

ID of the version to retrieve, from GET /agents/{agent_id}/versions. minLength: 1.

account

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

agent_id

Yes

string

ID of the agent whose skills to update. Also accepts the reserved aliases gumball and analytics. minLength: 1.

attach

No; body and guard rules apply

array

Skill IDs to attach. Ignored if already attached. default: []. Items: string.

detach

No; body and guard rules apply

array

Skill IDs to detach. Ignored if not attached. default: []. Items: string.

account

No; body and guard rules apply

string

Named private Gumloop account; selects private credentials and user/team identity.

confirm

No; body and guard rules apply

boolean

Set true only when the user asked for exactly this action.

payload

No; body and guard rules apply

object

Complete JSON request body instead of body flags. Preserves current endpoint fields and values.

payload_file

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: 1.

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

agent_id

Yes

string

ID of the agent. Also accepts the reserved aliases gumball and analytics. minLength: 1.

account

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

agent_id

Yes

string

ID of the agent. Also accepts the reserved aliases gumball and analytics. minLength: 1.

server_id

Yes

string

ID of the MCP server from the caller's catalog. minLength: 1.

account

No; body and guard rules apply

string

Named private Gumloop account; selects private credentials and user/team identity.

confirm

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

agent_id

Yes

string

ID of the agent. Also accepts the reserved aliases gumball and analytics. minLength: 1.

server_id

Yes

string

ID of the MCP server to detach. minLength: 1.

account

No; body and guard rules apply

string

Named private Gumloop account; selects private credentials and user/team identity.

confirm

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

agent_id

Yes

string

ID of the agent whose sessions to list. Also accepts the reserved aliases gumball and analytics. minLength: 1.

page_size

No; body and guard rules apply

integer

Number of sessions to return per page. Defaults to 20, maximum 100. minimum: 1. maximum: 100. default: 20.

cursor

No; body and guard rules apply

string

Cursor for the next page of results. Use the next_cursor value from a previous response.

search

No; body and guard rules apply

string

Free-text search query to filter sessions by name or content. Also accepted as search_query.

sort_order

No; body and guard rules apply

string

Sort order for the results (e.g. newest or oldest).

type

No; body and guard rules apply

string

Filter sessions by type (e.g. api, web, slack).

state

No; body and guard rules apply

string

Filter sessions by state. Values: processing, completed, failed, queued, idle.

creator_user_id

No; body and guard rules apply

string

Filter sessions by the user who created them.

trigger_id

No; body and guard rules apply

string

Filter sessions by the trigger that initiated them.

account

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

agent_id

Yes

string

ID of the agent to start a session on. Also accepts the reserved aliases gumball and analytics. minLength: 1.

input

No; body and guard rules apply

string

The first user message for the session. Also accepted as message for backwards compatibility. When omitted, an idle session is created with no messages.

session_id

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 409 session_already_exists.

name

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 PATCH /sessions/{session_id}. maxLength: 256.

metadata

No; body and guard rules apply

object

Arbitrary key/value metadata attached to the session. Stored under metadata.client.

stream

No; body and guard rules apply

boolean

Must be false (or omitted) when calling api.gumloop.com. Set to true only when calling ws.gumloop.com (see the streaming section above). default: False.

account

No; body and guard rules apply

string

Named private Gumloop account; selects private credentials and user/team identity.

confirm

No; body and guard rules apply

boolean

Set true only when the user asked for exactly this action.

payload

No; body and guard rules apply

object

Complete JSON request body instead of body flags. Preserves current endpoint fields and values.

payload_file

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: 1.

retrieve_session

gumloop-cli retrieve-session

Argument

Required

Type

Details

session_id

Yes

string

ID of the session to retrieve. minLength: 1.

account

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

session_id

Yes

string

ID of the session to rename. minLength: 1.

name

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: 1. maxLength: 256.

account

No; body and guard rules apply

string

Named private Gumloop account; selects private credentials and user/team identity.

confirm

No; body and guard rules apply

boolean

Set true only when the user asked for exactly this action.

payload

No; body and guard rules apply

object

Complete JSON request body instead of body flags. Preserves current endpoint fields and values.

payload_file

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: 1.

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

session_id

Yes

string

ID of the session to continue. minLength: 1.

input

No; body and guard rules apply

string

The next user message. Required. Also accepted as message for backwards compatibility.

stream

No; body and guard rules apply

boolean

Must be false (or omitted) when calling api.gumloop.com. Set to true only when calling ws.gumloop.com (see the streaming section above). default: False.

attachments

No; body and guard rules apply

array

Files to attach to the message. Each file_name must be a stored path returned by Upload session file for this session. maxItems: 10. Items: object.

account

No; body and guard rules apply

string

Named private Gumloop account; selects private credentials and user/team identity.

confirm

No; body and guard rules apply

boolean

Set true only when the user asked for exactly this action.

payload

No; body and guard rules apply

object

Complete JSON request body instead of body flags. Preserves current endpoint fields and values.

payload_file

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: 1.

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

session_id

Yes

string

ID of the session to cancel. minLength: 1.

account

No; body and guard rules apply

string

Named private Gumloop account; selects private credentials and user/team identity.

confirm

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

session_id

Yes

string

ID of the session to upload the file to. minLength: 1.

file_name

No; body and guard rules apply

string

Name of the file. Directory components are stripped; the base name is sanitized before storage.

file_content

No; body and guard rules apply

string

Base64-encoded file contents. Maximum decoded size is 200MB. format: byte.

media_type

No; body and guard rules apply

string

MIME type of the file. Echoed back in the response.

account

No; body and guard rules apply

string

Named private Gumloop account; selects private credentials and user/team identity.

confirm

No; body and guard rules apply

boolean

Set true only when the user asked for exactly this action.

payload

No; body and guard rules apply

object

Complete JSON request body instead of body flags. Preserves current endpoint fields and values.

payload_file

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: 1.

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

session_id

Yes

string

ID of the session with pending approvals. minLength: 1.

approval_responses

No; body and guard rules apply

array

Answers to pending asks. Each action_request_id may appear at most once. minItems: 1. maxItems: 20. Items: object.

account

No; body and guard rules apply

string

Named private Gumloop account; selects private credentials and user/team identity.

confirm

No; body and guard rules apply

boolean

Set true only when the user asked for exactly this action.

payload

No; body and guard rules apply

object

Complete JSON request body instead of body flags. Preserves current endpoint fields and values.

payload_file

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: 1.

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

session_id

Yes

string

ID of the session whose queue to list. minLength: 1.

account

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

session_id

Yes

string

ID of the session to queue the message on. minLength: 1.

input

No; body and guard rules apply

string

The message to queue. Cannot be empty. Also accepted as message for backwards compatibility.

account

No; body and guard rules apply

string

Named private Gumloop account; selects private credentials and user/team identity.

confirm

No; body and guard rules apply

boolean

Set true only when the user asked for exactly this action.

payload

No; body and guard rules apply

object

Complete JSON request body instead of body flags. Preserves current endpoint fields and values.

payload_file

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: 1.

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

session_id

Yes

string

ID of the session the queued message belongs to. minLength: 1.

queued_message_id

Yes

string

ID of the queued message to update. minLength: 1.

input

No; body and guard rules apply

string

The new message content. Cannot be empty. Also accepted as message for backwards compatibility.

account

No; body and guard rules apply

string

Named private Gumloop account; selects private credentials and user/team identity.

confirm

No; body and guard rules apply

boolean

Set true only when the user asked for exactly this action.

payload

No; body and guard rules apply

object

Complete JSON request body instead of body flags. Preserves current endpoint fields and values.

payload_file

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: 1.

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

session_id

Yes

string

ID of the session the queued message belongs to. minLength: 1.

queued_message_id

Yes

string

ID of the queued message to delete. minLength: 1.

account

No; body and guard rules apply

string

Named private Gumloop account; selects private credentials and user/team identity.

confirm

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

session_id

Yes

string

ID of the session the queued message belongs to. minLength: 1.

queued_message_id

Yes

string

ID of the queued message to send. minLength: 1.

account

No; body and guard rules apply

string

Named private Gumloop account; selects private credentials and user/team identity.

confirm

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

team_id

No; body and guard rules apply

string

Scope the catalog to a single team. When omitted, returns servers visible to the authenticated user.

account

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

server_id

Yes

string

Identifier of the MCP server to retrieve. minLength: 1.

team_id

No; body and guard rules apply

string

Scope the lookup to a single team.

account

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

server_id

Yes

string

Identifier of the MCP server. minLength: 1.

team_id

No; body and guard rules apply

string

Scope the lookup to a single team.

account

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

server_id

Yes

string

Identifier of the MCP server. minLength: 1.

team_id

No; body and guard rules apply

string

Scope the lookup to a single team.

cursor

No; body and guard rules apply

string

Opaque cursor from a previous response's next_cursor.

account

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

server_id

Yes

string

See current schema minLength: 1.

uri

Yes

string

The resource uri from List MCP server resources.

team_id

No; body and guard rules apply

string

See current schema

account

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

server_id

Yes

string

See current schema minLength: 1.

team_id

No; body and guard rules apply

string

See current schema

account

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

server_id

Yes

string

See current schema minLength: 1.

name

No; body and guard rules apply

string

Prompt name from List MCP server prompts.

arguments

No; body and guard rules apply

object

Argument values for the template.

team_id

No; body and guard rules apply

string

Scope the lookup to a single team.

account

No; body and guard rules apply

string

Named private Gumloop account; selects private credentials and user/team identity.

payload

No; body and guard rules apply

object

Complete JSON request body instead of body flags. Preserves current endpoint fields and values.

payload_file

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: 1.

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

calls

No; body and guard rules apply

array

Tool calls to execute. Dispatched concurrently; the batch is capped at 5. minItems: 1. maxItems: 5. Items: object.

team_id

No; body and guard rules apply

string/null

Team the calls are scoped to.

account

No; body and guard rules apply

string

Named private Gumloop account; selects private credentials and user/team identity.

confirm

No; body and guard rules apply

boolean

Set true only when the user asked for exactly this action.

payload

No; body and guard rules apply

object

Complete JSON request body instead of body flags. Preserves current endpoint fields and values.

payload_file

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: 1.

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

query

No; body and guard rules apply

string

The natural-language search query.

limit

No; body and guard rules apply

integer

Maximum number of results to return. minimum: 1. maximum: 50. default: 8.

source_type

No; body and guard rules apply

array/null

Restrict results to specific source types. Omit to search every source you can access. Valid values: notion, google_drive, slack, github, confluence, direct_file_uploads, gumloop_artifacts. minItems: 1. Items: string.

account

No; body and guard rules apply

string

Named private Gumloop account; selects private credentials and user/team identity.

confirm

No; body and guard rules apply

boolean

Set true only when the user asked for exactly this action.

payload

No; body and guard rules apply

object

Complete JSON request body instead of body flags. Preserves current endpoint fields and values.

payload_file

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: 1.

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

scope

No; body and guard rules apply

string

Only sources in this scope. Values: personal, team, organization.

source_type

No; body and guard rules apply

string

Only sources of this type, for example direct_file_uploads or notion.

team_id

No; body and guard rules apply

string

Only team sources belonging to this team.

page_size

No; body and guard rules apply

integer

Maximum number of sources to return. minimum: 1. maximum: 100. default: 20.

cursor

No; body and guard rules apply

string

Opaque cursor from a previous response's next_cursor.

account

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

name

No; body and guard rules apply

string

Display name of the source. minLength: 1. maxLength: 200.

source_type

No; body and guard rules apply

string

Only direct_file_uploads is accepted. default: direct_file_uploads.

scope

No; body and guard rules apply

string

Which Brain the source belongs to. team requires team_id. Values: personal, team, organization. default: personal.

team_id

No; body and guard rules apply

string

The team for scope: team. Not accepted with other scopes.

require_approval

No; body and guard rules apply

boolean

Create as a draft that estimates credits before anything is indexed. default: False.

account

No; body and guard rules apply

string

Named private Gumloop account; selects private credentials and user/team identity.

confirm

No; body and guard rules apply

boolean

Set true only when the user asked for exactly this action.

payload

No; body and guard rules apply

object

Complete JSON request body instead of body flags. Preserves current endpoint fields and values.

payload_file

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: 1.

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

source_id

Yes

string

The source id. minLength: 1.

account

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

source_id

Yes

string

The source id. minLength: 1.

account

No; body and guard rules apply

string

Named private Gumloop account; selects private credentials and user/team identity.

confirm

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

source_id

Yes

string

The source id. minLength: 1.

page_size

No; body and guard rules apply

integer

See current schema minimum: 1. maximum: 100. default: 20.

cursor

No; body and guard rules apply

string

See current schema

account

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

source_id

Yes

string

The source id. minLength: 1.

files

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: 1. maxItems: 25. Items: string.

account

No; body and guard rules apply

string

Named private Gumloop account; selects private credentials and user/team identity.

confirm

No; body and guard rules apply

boolean

Set true only when the user asked for exactly this action.

payload

No; body and guard rules apply

object

Complete JSON request body instead of body flags. Preserves current endpoint fields and values.

payload_file

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: 1.

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

source_id

Yes

string

The source id. minLength: 1.

file_id

Yes

string

See current schema minLength: 1.

account

No; body and guard rules apply

string

Named private Gumloop account; selects private credentials and user/team identity.

confirm

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

source_id

Yes

string

The source id. minLength: 1.

account

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

source_id

Yes

string

The source id. minLength: 1.

account

No; body and guard rules apply

string

Named private Gumloop account; selects private credentials and user/team identity.

confirm

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

team_id

No; body and guard rules apply

string

Scope the listing to a single team. When omitted, returns skills owned by the authenticated user.

search_query

No; body and guard rules apply

string

Case-insensitive substring match against the skill name.

sort_order

No; body and guard rules apply

string

Sort order for the returned skills. Values: newest, popular, most_used. default: newest.

page_size

No; body and guard rules apply

integer

Number of skills per page. Clamped between 1 and 100. minimum: 1. maximum: 100. default: 20.

cursor

No; body and guard rules apply

string

Opaque pagination cursor returned in next_cursor from a prior page.

creator_user_id

No; body and guard rules apply

string

Filter to skills created by this user ID.

related_server_id

No; body and guard rules apply

string

Filter to skills that reference this MCP server ID in their metadata.

agent_id

No; body and guard rules apply

string

Filter to skills attached to this agent.

unused

No; body and guard rules apply

string

When set, filters to skills that have not been used.

account

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

files

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: 1. maxItems: 25. Items: string.

team_id

No; body and guard rules apply

string

Team that should own the skill. When omitted, the skill is owned by the authenticated user.

account

No; body and guard rules apply

string

Named private Gumloop account; selects private credentials and user/team identity.

confirm

No; body and guard rules apply

boolean

Set true only when the user asked for exactly this action.

payload

No; body and guard rules apply

object

Complete JSON request body instead of body flags. Preserves current endpoint fields and values.

payload_file

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: 1.

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

skill_id

Yes

string

ID of the skill to update. minLength: 1.

files

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: 1. maxItems: 25. Items: string.

account

No; body and guard rules apply

string

Named private Gumloop account; selects private credentials and user/team identity.

confirm

No; body and guard rules apply

boolean

Set true only when the user asked for exactly this action.

payload

No; body and guard rules apply

object

Complete JSON request body instead of body flags. Preserves current endpoint fields and values.

payload_file

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: 1.

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

skill_id

Yes

string

ID of the skill to delete. minLength: 1.

account

No; body and guard rules apply

string

Named private Gumloop account; selects private credentials and user/team identity.

confirm

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

skill_id

Yes

string

ID of the skill to download. minLength: 1.

version_id

No; body and guard rules apply

string

Specific version to download. When omitted, the current draft is returned.

account

No; body and guard rules apply

string

Named private Gumloop account; selects private credentials and user/team identity.

output_file

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: 1.

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

agent_id

Yes

string

ID of the agent whose artifacts to list. Also accepts the reserved aliases gumball and analytics. minLength: 1.

session_id

No; body and guard rules apply

string

Filter to artifacts produced within a specific session.

search_query

No; body and guard rules apply

string

Case-insensitive substring match against the artifact filename.

sort_order

No; body and guard rules apply

string

Sort order for results. Defaults to newest. default: newest.

page_size

No; body and guard rules apply

integer

Number of artifacts to return per page. Clamped to 1–100. minimum: 1. maximum: 100. default: 20.

cursor

No; body and guard rules apply

string

Opaque pagination cursor returned by a prior call as next_cursor.

account

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

artifact_id

Yes

string

ID of the artifact to download. minLength: 1.

version_id

No; body and guard rules apply

string

Specific version of the artifact to download. Defaults to the latest version when omitted.

account

No; body and guard rules apply

string

Named private Gumloop account; selects private credentials and user/team identity.

output_file

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: 1.

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

team_id

No; body and guard rules apply

string

List a team's profiles instead of your personal ones.

account

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

profile_id

Yes

string

A profile id, or default. minLength: 1.

url

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 cookies. maxLength: 2048.

cookies

No; body and guard rules apply

array

Cookies in chrome.cookies.Cookie or CDP Cookie shape. minItems: 1. Items: object.

team_id

No; body and guard rules apply

string

Import into a team-owned profile instead of a personal one.

account

No; body and guard rules apply

string

Named private Gumloop account; selects private credentials and user/team identity.

confirm

No; body and guard rules apply

boolean

Set true only when the user asked for exactly this action.

payload

No; body and guard rules apply

object

Complete JSON request body instead of body flags. Preserves current endpoint fields and values.

payload_file

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: 1.

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

account

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

agent_id

Yes

string

ID of the agent whose evaluations to list. Also accepts the reserved aliases gumball and analytics. minLength: 1.

page_size

No; body and guard rules apply

integer

Number of evaluations to return per page (1-100). minimum: 1. maximum: 100. default: 20.

cursor

No; body and guard rules apply

string

Pagination cursor from a previous response's next_cursor field.

grade

No; body and guard rules apply

string

Filter evaluations by grade. Values: pass, needs_review, needs_attention.

status

No; body and guard rules apply

string

Return evaluations in one lifecycle state instead of the default completed and failed set. Values: queued, in_progress, completed, failed.

session_id

No; body and guard rules apply

string

Only evaluations of this session.

organization_evaluation_id

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.

created_after

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: date-time.

created_before

No; body and guard rules apply

string

Only evaluations created before this ISO 8601 timestamp. Timestamps without an offset are read as UTC. format: date-time.

account

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

agent_id

Yes

string

ID of the agent that owns the sessions. minLength: 1.

session_ids

No; body and guard rules apply

array

Sessions to grade. Duplicates are rejected. minItems: 1. maxItems: 200. Items: string.

dry_run

No; body and guard rules apply

boolean

Report cost and skipped sessions without queuing. default: False.

account

No; body and guard rules apply

string

Named private Gumloop account; selects private credentials and user/team identity.

confirm

No; body and guard rules apply

boolean

Set true only when the user asked for exactly this action.

payload

No; body and guard rules apply

object

Complete JSON request body instead of body flags. Preserves current endpoint fields and values.

payload_file

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: 1.

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

agent_id

Yes

string

ID of the agent. Also accepts the reserved aliases gumball and analytics. minLength: 1.

days

No; body and guard rules apply

integer

Number of days to look back (1-365). Defaults to 30. minimum: 1. maximum: 365. default: 30.

account

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

agent_id

Yes

string

ID of the agent the evaluation belongs to. Also accepts the reserved aliases gumball and analytics. minLength: 1.

evaluation_id

Yes

string

ID of the evaluation to retrieve. minLength: 1.

account

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

agent_id

Yes

string

ID of the agent. Also accepts the reserved aliases gumball and analytics. minLength: 1.

account

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

agent_id

Yes

string

ID of the agent. Also accepts the reserved aliases gumball and analytics. minLength: 1.

enabled

No; body and guard rules apply

boolean

Whether evaluations are enabled for this agent.

model_name

No; body and guard rules apply

string

LLM model to use for evaluation.

include_auto_tags

No; body and guard rules apply

boolean

Allow the evaluator to suggest tags beyond your predefined vocabulary.

criteria

No; body and guard rules apply

array

Quality criteria to check (replaces existing list). Max 30. Items: object.

tags

No; body and guard rules apply

array

Tag vocabulary (replaces existing list). Max 50. Items: object.

data_points

No; body and guard rules apply

array

Data points to extract (replaces existing list). Max 40. Items: object.

sentiment

No; body and guard rules apply

object

See the full input schema.

account

No; body and guard rules apply

string

Named private Gumloop account; selects private credentials and user/team identity.

confirm

No; body and guard rules apply

boolean

Set true only when the user asked for exactly this action.

payload

No; body and guard rules apply

object

Complete JSON request body instead of body flags. Preserves current endpoint fields and values.

payload_file

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: 1.

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

account

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

account

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

organization_id

Yes

string

The organization whose evaluations to list.

page_size

No; body and guard rules apply

integer

Items per page (1-100). minimum: 1. maximum: 100. default: 20.

cursor

No; body and guard rules apply

string

Pagination cursor from a previous response's next_cursor.

account

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

account

No; body and guard rules apply

string

Named private Gumloop account; selects private credentials and user/team identity.

confirm

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

evaluation_id

Yes

string

ID of the organization evaluation. minLength: 1.

account

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

evaluation_id

Yes

string

ID of the organization evaluation. minLength: 1.

account

No; body and guard rules apply

string

Named private Gumloop account; selects private credentials and user/team identity.

confirm

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

evaluation_id

Yes

string

ID of the organization evaluation. minLength: 1.

account

No; body and guard rules apply

string

Named private Gumloop account; selects private credentials and user/team identity.

confirm

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

evaluation_id

Yes

string

ID of the organization evaluation. minLength: 1.

targets

No; body and guard rules apply

array

See the full input schema. maxItems: 1000. Items: EvaluationTarget.

account

No; body and guard rules apply

string

Named private Gumloop account; selects private credentials and user/team identity.

confirm

No; body and guard rules apply

boolean

Set true only when the user asked for exactly this action.

payload

No; body and guard rules apply

object

Complete JSON request body instead of body flags. Preserves current endpoint fields and values.

payload_file

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: 1.

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

evaluation_id

Yes

string

ID of the organization evaluation. minLength: 1.

session_ids

No; body and guard rules apply

array

Sessions to grade. Duplicates are rejected. minItems: 1. maxItems: 200. Items: string.

dry_run

No; body and guard rules apply

boolean

Report cost and skipped sessions without queuing. default: False.

account

No; body and guard rules apply

string

Named private Gumloop account; selects private credentials and user/team identity.

confirm

No; body and guard rules apply

boolean

Set true only when the user asked for exactly this action.

payload

No; body and guard rules apply

object

Complete JSON request body instead of body flags. Preserves current endpoint fields and values.

payload_file

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: 1.

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

evaluation_id

Yes

string

ID of the organization evaluation. minLength: 1.

agent_id

No; body and guard rules apply

string

Only results for this agent.

session_id

No; body and guard rules apply

string

Only results for this session.

grade

No; body and guard rules apply

string

Filter by grade. Values: pass, needs_review, needs_attention.

status

No; body and guard rules apply

string

Filter by status. Values: queued, in_progress, completed, failed.

created_after

No; body and guard rules apply

string

Only results created at or after this time. RFC 3339 with an explicit offset (for example 2026-09-01T00:00:00Z). format: date-time.

created_before

No; body and guard rules apply

string

Only results created before this time. RFC 3339 with an explicit offset. format: date-time.

page_size

No; body and guard rules apply

integer

Items per page (1-100). minimum: 1. maximum: 100. default: 20.

cursor

No; body and guard rules apply

string

Pagination cursor from a previous response's next_cursor.

account

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

evaluation_id

Yes

string

ID of the organization evaluation. minLength: 1.

result_id

Yes

string

Result ID from a run response or a results list. minLength: 1.

account

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

evaluation_id

Yes

string

ID of the organization evaluation. minLength: 1.

days

No; body and guard rules apply

integer

Window length in days. minimum: 1. maximum: 365. default: 30.

account

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

model_name

No; body and guard rules apply

string

Grading model. auto picks the recommended model.

frequency

No; body and guard rules apply

string

When to grade new sessions automatically. manual only grades via POST /evaluations/{evaluation_id}/run. Values: debounced, per_turn, manual.

language

No; body and guard rules apply

string

Language for summaries and rationales, or auto.

include_auto_tags

No; body and guard rules apply

boolean

See the full input schema.

session_types

No; body and guard rules apply

array

Session types to grade. See session_types in GET /evaluation-options. Items: string.

criteria

No; body and guard rules apply

array

See the full input schema. maxItems: 30. Items: object.

tags

No; body and guard rules apply

array

See the full input schema. maxItems: 50. Items: object.

data_points

No; body and guard rules apply

array

See the full input schema. maxItems: 40. Items: object.

sentiment

No; body and guard rules apply

object

See the full input schema.

notifications

No; body and guard rules apply

object

See the full input schema.

EvaluationCreateRequest

Current request definition.

Argument

Required

Type

Details

scope

No; body and guard rules apply

string

See the full input schema. Values: organization. default: organization.

organization_id

Yes

string

See the full input schema.

name

Yes

string

Unique among the organization's active evaluations. minLength: 1. maxLength: 256.

description

No; body and guard rules apply

string/null

See the full input schema. maxLength: 4000.

enabled

No; body and guard rules apply

boolean

Must be omitted or false on create; a new evaluation has no targets yet.

config

No; body and guard rules apply

EvaluationRubric

See the full input schema.

EvaluationUpdateRequest

Current request definition.

Argument

Required

Type

Details

name

No; body and guard rules apply

string

See the full input schema. minLength: 1. maxLength: 256.

description

No; body and guard rules apply

string/null

Null clears the description. maxLength: 4000.

enabled

No; body and guard rules apply

boolean

See the full input schema.

config

No; body and guard rules apply

EvaluationRubric

See the full input schema.

EvaluationTarget

Current request definition.

Argument

Required

Type

Details

type

Yes

string

What the target expands to. user covers a member's personal agents. Values: organization, team, user, agent.

id

No; body and guard rules apply

string

Team, user, or agent ID. Omitted for organization; responses return the organization ID.

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 --agent

The 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

GUMLOOP_API_KEY

Private Bearer credential; alternative to token file

GUMLOOP_TOKEN_FILE

Regular token-only file <=64 KB; overrides key

GUMLOOP_USER_ID

Single-account default user identity

GUMLOOP_TEAM_ID

Single-account default team; legacy project_id

GUMLOOP_ACCOUNTS

Private named JSON profiles; takes precedence

GUMLOOP_DEFAULT_ACCOUNT

Exact label, otherwise first entry

GUMLOOP_READ_ONLY

1/true hides/refuses confirmed operations

GUMLOOP_ALLOW_DESTRUCTIVE

0/false blocks confirmed operations

GUMLOOP_AUDIT_LOG

Optional private local guard log

GUMLOOP_REQUEST_TIMEOUT_MS

100–300000; default 30000

GUMLOOP_MAX_RETRIES

0–5; default 2; short explicit GET 429 only

GUMLOOP_MIN_REQUEST_INTERVAL_MS

0–10000; default 150; per account/process

GUMLOOP_CONFIRM

human by default; model lets confirm:true alone approve over MCP, for an agent with no person to ask

GUMLOOP_SURFACE

full by default; search lists three tools that find, describe and run the rest

GUMLOOP_TOOL_TIMEOUT_MS

Give up on any tool after this long

GUMLOOP_HTTP_PORT, GUMLOOP_HTTP_HOST, GUMLOOP_HTTP_TOKEN

For --http: port 8787 and host 127.0.0.1 by default; any other host needs the bearer token

GUMLOOP_HTTP_ALLOWED_ORIGINS

Comma-separated browser origins allowed to call --http; a page from any other site is refused

GUMLOOP_DEBUG

1 prints debug lines on stderr

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 --version

Global 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 gumloop

In 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

Official CLI

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

Official hosted MCP

https://mcp.gumloop.com/gumloop/mcp

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

Official SDKs

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

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 tools
approve_brain_sourceApprove sourceA
Destructive

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 serverA
Destructive

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 toolsA
Destructive

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 sessionA
Destructive

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 agentA
Destructive

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 sourceA
Destructive

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 completionB
Destructive

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/completions

api.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 (with tool_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_url content parts alongside text parts. The URL can be an http(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 when tools are sent), "none", "required", or {"type": "function", "function": {"name": "..."}} to force one tool.

  • developer messages are treated like system messages.

{
  "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 evaluationA
Destructive

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 sessionA
Destructive

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}/sessions

The 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 skillA
Destructive

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 fileB
Destructive

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 sourceA
Destructive

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 evaluationA
Destructive

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 messageA
Destructive

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 skillA
Destructive

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 serverA
Destructive

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 artifactA
Read-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 fileC
Read-onlyIdempotent

Download file Read operation.

Inputs: output_file (required), run_id, account, payload, +5 more.

download_filesDownload multiple filesC
Read-onlyIdempotent

Download multiple files Read operation.

Inputs: output_file (required), run_id, account, payload, +5 more.

download_skill_fileDownload skillA
Read-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 dataA
Destructive

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 sourceB
Read-onlyIdempotent

Fetch one source the authenticated user can see. Read operation.

Inputs: source_id (required), account.

get_brain_source_estimateRetrieve estimateA
Read-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 configB
Read-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 metricsA
Read-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 optionsA
Read-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 statusA
Read-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 schemaC
Read-onlyIdempotent

Retrieve input schema Read operation.

Inputs: saved_item_id (required), account, user_id, project_id.

get_mcp_server_promptGet MCP server promptB
Read-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 logsB
Read-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 evaluationB
Read-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 metricsB
Read-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 resultA
Read-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 limitA
Read-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 detailsA
Read-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 historyB
Read-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 profileA
Destructive

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 runA
Destructive

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 accountsA
Read-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 serversA
Read-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 agentsA
Read-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 versionsA
Read-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 artifactsA
Read-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 filesA
Read-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 sourcesA
Read-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 profilesA
Read-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 evaluationsA
Read-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 flowsC
Read-onlyIdempotent

List saved flows Read operation.

Inputs: account, user_id, project_id.

list_mcp_server_promptsList MCP server promptsB
Read-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 resourcesA
Read-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 serversB
Read-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 toolsA
Read-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 modelsB
Read-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 resultsA
Read-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 evaluationsA
Read-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 organizationsA
Read-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 messagesA
Read-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 limitsA
Read-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 sessionsA
Read-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 skillsA
Read-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 teamsC
Read-onlyIdempotent

List teams the authenticated caller belongs to. Read operation.

Inputs: account.

list_workbooksList workbooks and their saved flowsC
Read-onlyIdempotent

List workbooks and their saved flows Read operation.

Inputs: account, user_id, project_id.

manage_permission_group_usersManage custom role usersA
Destructive

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 usersB
Destructive

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 messageA
Destructive

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 resourceA
Read-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 sessionA
Destructive

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 approvalsA
Destructive

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 agentA
Read-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 versionA
Read-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 evaluationA
Read-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 serverB
Read-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 sessionA
Read-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 modelA
Read-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 evaluationsA
Destructive

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 sessionsA
Destructive

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 BrainA
Destructive

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 messageA
Destructive

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_responses with a 400.

  • 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}/messages

The 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 nowA
Destructive

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 targetsA
Destructive

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 limitA
Destructive

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 runA
Destructive

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 agentA
Destructive

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 skillsA
Destructive

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_detached rather than failing.

  • A skill ID may not appear in both attach and detach.

  • Up to 100 unique skill IDs total (attach + detach) per request.

  • Attaching requires INVOKE permission 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 configA
Destructive

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 evaluationA
Destructive

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 messageA
Destructive

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 skillA
Destructive

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 filesA
Destructive

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 fileB
Destructive

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 filesA
Destructive

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 fileA
Destructive

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

    B3.1/5.0

    Scored across 92 tools

    Disambiguation2/5

    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.

    Naming Consistency4/5

    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.

    Tool Count2/5

    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.

    Completeness4/5

    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

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables operators to manage Paperclip AI agent orchestration through 95 tools covering issues, agents, goals, projects, approvals, costs, routines, decisions, and pipelines.
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      Enables 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.
      45
      Apache 2.0
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables 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.
      1
      MIT