Gumloop API Guide: Keys, Webhooks, Python SDK and the CLI

Yes, Gumloop has a public REST API, and it is built around agents. You call the base URL api.gumloop.com/api/v1 with a personal API key from your Profile settings, sent as a bearer token, and you can create agents, start sessions with them and stream their replies ^[1]. Three choices shape everything else. A team key only reads. OAuth needs the Pro plan or above, while API keys carry no plan check. Webhook triggers need no key at all, because the URL itself is the secret. API runs spend the same credits as chat: Gumloop Pro is $37 a month for the whole organization's shared pool of 20,000 credits.

Pick the credential before you write any code

Gumloop's docs list three credential types, and the wrong one fails in a confusing way. A personal API key acts as you: it lives in the Gumloop API key row of your Profile settings, and the SDK pairs it with your user ID. A team API key acts as the team itself, never as a member. Only team admins can generate, regenerate or revoke it, though every team member can view and copy it. It suits read-only scripts that list teams, models, agents or skills.

Anything that does real work is refused for a team key. Creating agents, starting sessions, sending messages, uploads, approvals, browser operations and connector calls all return 403 personal_credential_required. OAuth is the third route, for apps that act on behalf of other people: the authorization code grant with PKCE (S256), one-hour access tokens and refresh tokens. Client registration is invite-only, so you email support@gumloop.com with your app name, use case, redirect URIs and logo. OAuth requires Pro or above for the authorizing user; otherwise the token exchange fails with tier_required_pro.

Two housekeeping details save an afternoon. Regenerating a key kills the old one immediately, so every CLI install, GitHub Actions job and SDK client has to be updated in the same sitting. The API parameter project_id survives for backwards compatibility, and it means the team ID shown in the interface. The Gumloop key is not a model provider key; it authenticates only the API, CLI and SDKs.

What the REST API and the SDKs cover

The API is agent-first. Through client.agents you can create an agent and set everything the agent panel sets: model, prompt, skills, knowledge sources, MCP servers, web search, subagents, and schedule or webhook triggers. A session is one conversation with one agent. You create it, then either poll until its state is completed or failed, or stream newline-delimited events with resume cursors. Resume is not guaranteed. A stream that cannot continue returns finish_reason not_resumable, and Gumloop advises reading the session state instead of resubmitting the message.

Sessions accept up to ten file attachments per message. A message to a busy session can be queued with delivery set to queued and an Idempotency-Key for safe retries, and pending approvals or requests for human input can be accepted or rejected from code, with an optional reason. Every session returns usage with credit_cost, input_tokens and output_tokens, so you can meter API runs in credits ^[2]. Beyond agents, the API offers OpenAI-compatible chat completions across Anthropic, OpenAI, Google Gemini and OpenRouter routes, with streaming, JSON schema output, tool calling and images.

The Python SDK first, JavaScript second

The Python package is called gumloop and installs with pip or uv. It needs Python 3.10 or later and works on Windows, macOS and Linux. It ships a sync client, Gumloop, and an async one, AsyncGumloop, with a 90-second request timeout and 3,600 seconds for streams and chat completions. Errors subclass GumloopError and carry codes such as tier_required_pro. The old GumloopClient only starts saved Legacy workflows and emits a deprecation warning. For JavaScript the install is npm install gumloop; Gumloop says both SDKs wrap the whole API, but its JavaScript SDK page documents only running saved flows by ID, so agent and session work is documented in Python.

Chat completions hide one trap. They need a concrete model, and the Auto router, gumloop-chew, is not accepted there. If you want Gumloop's pick without running anything, models.route returns the model it would choose. The decisions API, which answers named questions about a state you send, needs OAuth or a personal key and can consume credits. Agents get their full configuration over the API, but the built-in Gumball and analytics agents can only be read and chatted with, never configured.

Webhook triggers: the URL is the password

The quickest way to start an agent from another system needs no SDK. Since August 2026 an agent can carry a webhook trigger with its own URL, and anything that can send an HTTP POST can run it ^[3]. There is no API key or header, because the secret sits inside the URL. Store it like a password. The SDK returns that URL with its secret only once (from create_trigger or get_trigger_webhook_url), so save it when you get it. To retire it, delete the trigger; a new trigger gets a fresh URL.

The call is fire-and-forget. Gumloop answers 200 with success true the moment it accepts the request and runs the agent in the background, so the response never holds the agent's answer. Results have to leave through a tool, such as a Slack post or a sheet row, or be read later from run history. JSON is parsed even without a Content-Type header, form-encoded bodies become key/value pairs, and anything else passes through as raw text.

Debugging needs two more facts. Every rejection, whether the trigger is missing, deactivated or the secret is wrong, returns the same 404 not_found, so a 404 never tells you which. Each trigger also accepts 100 requests a minute, counted per trigger and including rejected calls; past that you get 429 rate_limited with a Retry-After header and the agent does not run. Integration triggers created through the public API start disabled until you pass enabled as true. Triggers run with the creator's connected accounts, though team agents can use the team's shared credentials.

The CLI, and why Windows users need WSL

The gumloop CLI installs with a curl script into ~/.gumloop, brings its own Python and needs no sudo. It runs on macOS and Linux only. On Windows, Gumloop points you to WSL or the Python SDK; the CLI even ships inside the Python package, but it will not run natively there . Login uses OAuth through a one-shot local server on port 8765, or a personal key, and credentials go to the OS keychain rather than a plaintext file.

Commands cover agents, sessions, evaluations, chat, decisions, MCP, Brain, skills and artifacts, with a --json mode on most of them for scripts and cron jobs. For headless machines and CI, set GUMLOOP_ACCESS_TOKEN, or GUMLOOP_API_KEY with GUMLOOP_USER_ID. Mind the asymmetry. GUMLOOP_API_KEY is read only by the CLI, while the Python SDK reads GUMLOOP_ACCESS_TOKEN, GUMLOOP_USER_ID, GUMLOOP_TEAM_ID and GUMLOOP_BASE_URL. If you write code with an AI assistant, gumloop plugin install adds a gumloop-cli skill to Claude Code, Cursor or Codex.

What API traffic costs, and where it gets refused

API runs are not a separate product with separate billing. Web chat, Slack and API usage all draw from the organization's one credit pool, and each run costs what the agent actually does: model tokens at list price, at least 1 credit per successful connector call, 5 credits per session-minute of active compute and an 8% orchestration fee. The docs' own examples put a quick question at 2 credits and a deep research task at 200, and neither figure is a floor or a ceiling. By our arithmetic, the docs' sample run of 459 credits comes to about $2.30 at list price.

Credits reset monthly, and when the pool runs dry, agents stop and trigger runs fail until you top up or raise the cap. Concurrency is the other ceiling. Pro allows 25 simultaneous agent interactions across the whole organization, and web, Slack, Teams, API and trigger runs all count. At the limit, Pro rejects the request, which over the API arrives as HTTP 429, and scheduled or event triggers are skipped. Enterprise defaults to 100, customizable, and queues instead: the API returns a queued state with a queue_position. Design retries for Pro. A job that fires more than 25 sessions at once will see some bounce.

What stays in the app, and when MCP fits better

Some jobs have no endpoint. Organization and team administration and custom roles stay in the main platform, as do deploying or restoring an agent version (the API can list and diff the immutable history), hosting artifacts, browser control and handoffs, and the aggregated Organization Insights charts. Connected Brain sources are set up in the app; the SDK can create only file-upload sources. Be careful with is_active. Setting it to false through the API or CLI retires the agent, it vanishes from lists and only support can restore it. To pause an agent, deactivate its triggers.

The Gumloop MCP server overlaps with the API, but neither is a superset. Only REST gives you queued messages, session file uploads, browser profiles and cookie import, and chat completions; only MCP gives you documentation search. If the goal is letting Claude, Cursor or ChatGPT drive your agents, read our Gumloop MCP guide. If the agent editor itself is still new, start with how to use Gumloop. Teams weighing developer surfaces should know that n8n lists API and CLI control and webhook triggers on all its plans, though its public API is not available during the Cloud free trial; our Gumloop vs n8n comparison covers the rest.

When the API is the right door into Gumloop

Build on the API when Gumloop agents already do useful work and you need to start them from your own product, a CI pipeline or an internal tool. It is also the supported way to put an agent inside your own site, since hosted agent pages require a Gumloop sign-in and iframe embedding is not officially supported. Start with a personal key and the Python SDK. Use webhooks for one-way events from forms and alerts, and reach for OAuth only when other people authorize your app, which means Pro. Windows shops script with the SDK, not the CLI.