Getting Started

The Gumloop API is agent-first: you can create and update agents, start sessions to chat with them, and use chat completions from any OpenAI-compatible client. The Python and JavaScript SDKs wrap all of it. Webhooks, covered next, let an outside service run an agent by calling a URL — no API key, SDK, or polling loop needed.

Agent Webhooks

A webhook trigger gives an agent its own URL. Anything that can send an HTTP POST — Stripe, GitHub, a cron job, an internal script — runs the agent by calling it.

Create the trigger

On the agent’s configuration page, open the Triggers section, click + Add, and choose Webhook. Give it a name and either a prompt (drop the Raw JSON badge where the payload should land) or turn on Send raw JSON instead of a prompt.

Copy the URL

Gumloop shows the URL as soon as the trigger is created, along with a curl example. You can copy it again any time from the trigger’s detail panel.

Trigger created screen showing the webhook URL and a Try it yourself curl example

POST to it

curl -X POST \
  'https://api.gumloop.com/trigger_incoming_webhook/<trigger_id>/<secret>' \
  -H 'Content-Type: application/json' \
  -d '{"customer": {"email": "ada@example.com"}}'

Request & Response

	Behavior
Method	`POST` only
Auth	None — the secret is part of the URL, so no API key or header is required
Body	JSON (parsed even without a `Content-Type: application/json` header), form-encoded data, or raw text
Success	`200` with `{"success": true}`, returned as soon as the request is accepted
Rejected	`404` with `{"error": "not_found"}` for an unknown trigger, a deactivated trigger, or a wrong secret — deliberately identical, so a bad URL reveals nothing

The agent runs in the background, so the response never carries its output. Have the agent report results through a tool (Slack, email, a database write) or check the run in the agent’s history.

The webhook URL is the credential: anyone holding it can run your agent. Store it like a password, and delete the trigger to retire a URL — a new trigger always gets a fresh one.

Finding Your User ID

Many API endpoints require a user_id parameter. You can find your User ID on the Profile Settings page, under your email address.

Click the copy icon next to your User ID to copy it to your clipboard.

Authorization

Agent webhooks need no credentials, but the rest of the API does. You can authenticate using one of two methods:

API Key in URL
Authorization Header

The default method is to include your API key as a query parameter in the URL. This method is simpler and works well for most integrations:

curl -X POST \
  https://api.gumloop.com/api/v1/start_agent?api_key=xxxxxxxxxxxx \
  -H "Content-Type: application/json" \
  -d '{"user_id": "xxxxxxxxxxxxxx", "agent_id": "xxxxxxxxxxxxxx", "message": "Hello"}'

Alternatively, you can use the Authorization header with a Bearer token. This method is preferred when you want to keep credentials out of URLs:

curl -X POST \
  https://api.gumloop.com/api/v1/start_agent \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer xxxxxxxxxxxx" \
  -d '{"user_id": "xxxxxxxxxxxxxx", "agent_id": "xxxxxxxxxxxxxx", "message": "Hello"}'

All examples in the API reference use the Authorization header method, but you can substitute the API key method in any of them.

Core Concepts

SDKs

Agents

Sessions

Skills

Artifacts

MCP

Evaluations

Organization Evaluations

Brain

Teams

Chat completions

Models

File Operations

Enterprise Organization

Getting Started

Agent Webhooks

Request & Response

Finding Your User ID

Authorization

​Agent Webhooks

​Request & Response

​Finding Your User ID

​Authorization

Agent Webhooks

Request & Response

Finding Your User ID

Authorization