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.

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_pipeline?user_id=xxxxxxxxxxxxxx&saved_item_id=xxxxxxxxxxxxxx&api_key=xxxxxxxxxxxx \
  -H "Content-Type: application/json" \
  -d '{}'

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_pipeline?user_id=xxxxxxxxxxxxxx&saved_item_id=xxxxxxxxxxxxxx \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer xxxxxxxxxxxx" \
  -d '{}'

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

Triggering Saved Workflows

Workflow webhooks are the pre-agent way to trigger Gumloop from your own app, and they still work exactly as before. For new integrations, use an agent webhook instead.

Getting a workflow's webhook snippet

All Gumloop workflows can be triggered from an external app using webhooks. Open your workflow and click the Webhooks button on the top left of the pipeline builder to see the code you need.

You can switch between the API-key-in-URL and Authorization header methods in the webhook modal by checking or unchecking the “Use Authorization Header” option.

Sending inputs

Most useful workflows require some input from the user. There are two main approaches to handle inputs in your Gumloop workflows:

Webhook Input Node (Recommended)
Named Input Nodes

Webhook Input Node with JSON Parsing

This is the recommended approach for handling inputs. Use a Webhook Input node to capture the entire request body as a string, then parse it using a JSON Reader node. This method provides maximum flexibility and makes it easy to handle complex, nested data structures.

With this approach, you can send any JSON structure directly in your request body:

curl -X POST \
  https://api.gumloop.com/api/v1/start_pipeline?user_id=xxxxxxxxxxxxxx&saved_item_id=xxxxxxxxxxxxxx \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer xxxxxxxxxxxx" \
  -d '{
    "recipient": "recipient@gmail.com",
    "subject": "Example of an Email Subject Line",
    "body": "Example of the Text of an Email Body",
  }'

The Webhook Inputs node will capture this entire JSON payload as a string, which you can then parse using a JSON Reader node to extract individual fields or work with the entire data structure.

Alternative Method: Named Input Nodes

While the webhook inputs node with JSON parsing is recommended, there is an alternative method for receiving data that uses named Input nodes. All the following options require you to set up Input nodes in your workflow where the ‘Input name’ values represent the name of that input field. These input names are used to map the information you send via the webhook to the appropriate nodes.

Once you have set up your named Input nodes, you can choose from any of the following options to send data to your workflow:

Option 1: Direct Field Mapping

Just like with the Webhook Input node, you can pass inputs by name directly in the body of the request. This approach is concise and straightforward:

curl -X POST \
  https://api.gumloop.com/api/v1/start_pipeline?user_id=xxxxxxxxxxxxxx&saved_item_id=xxxxxxxxxxxxxx \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer xxxxxxxxxxxx" \
  -d '{
    "recipient": "recipient@gmail.com",
    "subject": "Example of an Email Subject Line",
    "body": "Example of the Text of an Email Body"
  }'

Option 2: Header-Based Inputs (Not Recommended)

When using any of the above methods to trigger a workflow, any provided headers will also be passed along as inputs to the workflow. If you have an Input node with the same name as a header, it will be provided the header value as input.This method is not recommended for regular use, but can be useful in specific integration scenarios:

curl -X POST \
  https://api.gumloop.com/api/v1/start_pipeline?user_id=xxxxxxxxxxxxxx&saved_item_id=xxxxxxxxxxxxxx \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer xxxxxxxxxxxx" \
  -H "recipient: recipient@gmail.com" \
  -H "subject: Example of an Email Subject Line" \
  -H "body: Example of the Text of an Email Body" \
  -d '{}'

Reading outputs and polling for run status

When you run a Gumloop pipeline remotely, the POST request to https://api.gumloop.com/api/v1/start_pipeline will return a run_id and a URL that links to the workflow run.Here is an example of the response:

{
  "run_id": B7uiXDngvzFvUWxHRKQFAD,
  "saved_item_id": q3dasHQBidkNeXvAZo6Dby,
  "url": https://www.gumloop.com/pipeline?run_id=B7uiXDngvzFvUWxHRKQFAD&flow_id=q3dasHQBidkNeXvAZo6Dby
}

You can use run_id to poll a separate endpoint to get information about the ongoing run like the status, logs, and outputs when it is completed.Polling for run statusIn order to poll, make a GET request to https://api.gumloop.com/api/v1/get_pl_run with run_id as a query parameter.Here is an example of a GET request with cURL, Python, and JavaScript and their outputs:

curl 'https://api.gumloop.com/api/v1/get_pl_run?run_id=B7uiXDngvzFvUWxHRKQFAD&user_id=your_user_id' \
  -H 'Authorization: Bearer xxxxxxxxxxxxx'

import requests

url = "https://api.gumloop.com/api/v1/get_pl_run?run_id=B7uiXDngvzFvUWxHRKQFAD&user_id=your_user_id"
headers = {
    "Authorization": "Bearer xxxxxxxxxxxx"
}

response = requests.get(url, headers=headers)
print(response.json())

const url = 'https://api.gumloop.com/api/v1/get_pl_run?run_id=B7uiXDngvzFvUWxHRKQFAD&user_id=your_user_id';
const headers = {
  Authorization: 'Bearer xxxxxxxxxxxxxx',
};

fetch(url, {
  method: 'GET',
  headers: headers,
})
  .then((response) => response.json())
  .then((data) => console.log(data));

Response structure

{
    "created_ts": "2023-11-19T18:06:31.102786+00:00",
    "finished_ts": null,
    "log": [
        "\u001b[34m__system__: __STARTING__:Read files from GitHub\u001b[0m"
    ],
    "outputs": {},
    "run_id": "B7uiXDngvzFvUWxHRKQFAD",
    "state": "RUNNING",
    "user_id": "your_user_id"
}

The key attributes here are:

Attribute	Description
`log`	A running log of each node and the activities within it
`state`	One of “STARTED”, “RUNNING”, “TERMINATED”, “FAILED” or “DONE”
`outputs`	Key-value pairs of `output name` to `output value`. Only populated once the pipeline reaches “DONE” and the pipeline has named output nodes.

Core Concepts

SDKs

Agents

Sessions

Skills

Artifacts

MCP

Evaluations

Brain

Teams

Chat completions

Models

Retrieving Automations

File Operations

Enterprise Organization

Running Flows

Getting Started

Agent Webhooks

Request & Response

Finding Your User ID

Authorization

Triggering Saved Workflows

Webhook Input Node with JSON Parsing

Alternative Method: Named Input Nodes

​Agent Webhooks

​Request & Response

​Finding Your User ID

​Authorization

​Triggering Saved Workflows

​Webhook Input Node with JSON Parsing

​Alternative Method: Named Input Nodes

Agent Webhooks

Request & Response

Finding Your User ID

Authorization

Triggering Saved Workflows

Webhook Input Node with JSON Parsing

Alternative Method: Named Input Nodes